QxTransformer takes up the syntax of the QxBuilder class that was present in the qooxdoo 0.1 - 0.5 releases, but extends it significantly. Currently, It uses two namespaces, “qx” for “real” qooxdoo widgets and “qxt” for “virtual” widgets constructed by templates. We call the resulting XML code "QXML" (for qooxdoo XML).

To avoid lengthy namespaces (and typos), xml tag names do not use the full namespace of the classes, but use an abbreviated name similar to the class names in qooxdoo 0.1.

A list of <qx:...> tags can be found here, a list of <qxt:...> tags will be forthcoming, we will cover the most important ones in this tutorial. We will also provide an XSD schema file in one of the next releases, which will be very useful when writing QXML documents. At the moment, only the namespaces "qx" and "qxt" are supported. In a coming release, we will support custom namespaces, so that you can call your custom widgets using your application namespace.

Each node corresponds to an anonymous variable name created by the XSLT engine. For example, <qx:atom/> is translated into “var qx_1337463242 = new qx.ui.basic.Atom()”. If you want to have a named variable reference to your newly created object, you need to specify an id, such as <qx:atom id=”foo”/>. If this reference should be a global variable, you can provide the “scope” attribute and set it to “global”.

<qx:atom 
    id="myFirstAtom" scope="global"
    label="Hello Word" icon="icons/16/smiley.png"
    left="10" top="10"/>

As you can see, all properties that you want set on this widget are specified as XML attributes. For example,

myFirstAtom = new qx.ui.basic.Atom("Hello World","icons/16/smiley.png");
myFirstAtom.setLeft(10);
myFirstAtom.setTop(10);

As can be expected, the widget object hierarchy is modeled as parent-child node relations. For example, a list contained in a horizontal box layout is constructed like this:

<qx:horizontalBoxLayout
    padding="10" 
    spacing="10"
    width="auto"
    height="100%">
 
    <qx:list id="list"
        height="100%"
        width="150"
        overflow="scrollY">
 
        <qx:listItem icon="icon/16/places/folder.png"
                 text="Item No 1."/>
        <qx:listItem icon="icon/16/devices/drive-harddisk.png"
                 text="Item No 2."/>
        <qx:listItem icon="icon/16/apps/accessories-tip.png"
                 text="Item No 3."/>
        <qx:listItem icon="icon/16/devices/scanner.png"
                 text="Item No 4." enabled="false"/>
                 
    </qx:list>
    
<qx:horizontalBoxLayout>

This main pattern applies to all qooxdoo classes that support adding its children through the “.add()” mechanism. For more complex widgets, such as the ListView, Menu, SplitPane etc, QxTransformer models the parent-child relationships even when the qooxdoo API works differently. The QxTransformer showcase (to be released) contains individual pages that show the xml syntax of these widgets.

For example, the qooxdoo implementation of a grid layout requires code that quickly gets confusing and is hard to maintain. QxTransformer provides you with a syntax which frees you from having to keep track of which cell you are currently adding content to. You can code a grid similar to the way you are used to with HTML tables:

<qx:gridLayout 
    width="100%" 
    height="100%"
    verticalSpacing="2" 
    horizontalSpacing="5">
    
    <qx:gridLayoutColumn 
        width="20%" 
        horizontalAlignment="right"
        verticalAlignment="top" >
 
    <qx:gridLayoutColumn 
        width="80%" 
        horizontalAlignment="left"
        verticalAlignment="top" >
    
    <qx:gridLayoutRow height="20">
        <qx:gridLayoutCell>
            <qx:atom label="foo"/>
        </qx:gridLayoutCell>
        <qx:gridLayoutCell>
            <qx:atom label="bar"/>
        </qx:gridLayoutCell>        
    <qx:gridLayoutRow>
    
    <qx:gridLayoutRow height="20">
        <qx:gridLayoutCell>
            <qx:atom label="foo2"/>
        </qx:gridLayoutCell>
        <qx:gridLayoutCell>
            <qx:atom label="bar2"/>
        </qx:gridLayoutCell>        
    <qx:gridLayoutRow>
    
</qx:gridLayout>

Note that, for convenience, we use “qx:..” instead of “qxt:..” for rows, columns or cells even though they are pure constructs and do not correspond to “real” qooxdoo widgets.

You can attach event listeners to each widget that is a subclass of qx.core.Target. The easiest way to do this with QxTransformer is to add an “onFoo” attribute. For example,

<qx:atom
  label="Hello" 
  onAppear="this.info('I appeared')" 
  onClick="alert('I was clicked!')"/>

will log an info message once the “appear” event has been fired on the Atom and will alert when the atom has been clicked on.

More sophicated event handlers are attached like so:

<qx:window
    id="myWindow"
    width="300" height="100"
    onAppear="this.centerToBrowser()">
    <qx:eventListener type="close" dispatchMessage="myapplication.window.closed" />
    <qx:horizontalBoxLayout width="100%" height="100%">
        <qx:button
            label="New" icon="icons/16/file-new.png">
            <qx:eventListener type="execute" delegate="create_new"/>
        </qx:button> 
        <qx:button
            label="Close" icon="icons/16/stop.png">
            <qx:eventListener type="execute">
                myWindow.close();
            </qx:eventListener>
        </qx:button>
    </qx:horizontalBoxLayout>
</qx:window>
<qxt:eventHandler name="create_new">
    <![CDATA[  
    // do stuff 
    ]]>
<qxt:eventHandler>

The “delegate” attribute delegates, as its name suggests, the event handling to an external event handler defined by <qxt:eventHandler>. This allows you to put longer pieces of code out of the GUI description. Internally, such event Handlers are implemented as methods to the main application object, so make sure you do not use names that conflict with methods of qx.application.Gui. Instead of executing event handler, you can also delegate the event (and event data) to a message subscriber by dispatching a message with the "dispatchMessage" attribute (see below).

It is good practice to enclose event handling code (and all other javascript code in an qxml document) in <![CDATA[ ... ]]>, and it is required if you use characters that have a special meaning in XML such as “<” and “&”.

Inside the event handler code, the event itself is available as the local variable “event”. You can also use a different variable name by setting the “args” attribute. The object itself is available as “this”:

<qx:textField onChangeValue=" alert('User wrote:' + event.getData())" />
<qx:textField>
    <qx:eventListener type="changeValue" args="e">
        var vUserInput = e.getData();
        alert('User wrote: ' + vUserInput );
        this.setValue('');
    </qx:eventListener>
</qx:textField>

One philosophy behind QxTransformer is to minimize the use of named objects and global variables as much as possible. Widget objects should work as self-contained units which do not need to know about the name of other objects - in fact, they should not even need to know about each others’ existence.

Instead of calling each others’ methods, objects should issue messages in which they state what action should be performed by others and react to messages issued by other objects. This does not only prevent situations in which the non-initialization of one object breaks the application (because the named object then doesn’t exist and the method call results in a javascript error). It also allows the routing of messages beyond the scope of the client environment, for example, to the server.

A simple example: An atom listens for value change in a text field:

<qx:atom label="Display change-label message value">
    <qx:messageSubscriber filter="change-label">
        this.setLabel(message.getData());
    </qx:messageSubscriber>
</qx:atom>
<qx:textField liveUpdate="true">
    <qx:eventListener type="changeValue" dispatchMessage="change-label"/>
</qx:textField>

What this code does is to create an event listener at the text field which redirects the event data into a “change-label” message. The atom listens for the message and changes its label with the value of the user input. Neither object needs to know that the other one exists.

On the other hand, there can be multiple senders and multiple subscribers. For example, in a different part of the application, the “change-label” message could be issued manually:

qx.event.message.Bus.dispatch("change-label","Hello World!");

You don’t need to know about the specific atom or remember its global variable name, and there can be any number of other widgets which listen for the message as well.

Additionally, message subscribers can listen for multiple messages at once by using truncation:

<qx:atom label="Display non-object 'change-*' messages">
    <qx:messageSubscriber filter="change-*">
        <![CDATA[
        var data = message.getData();
        if ( typeof data != "object" )
        {
            this.setLabel ( data );
        }
        ]]>
    </qx:messageSubscriber>
</qx:atom>

Not everything can be done with the QXML, many things, in particular the main business logic of your application, has to be coded in javascript. You can put a big part of the code into event listeners and event handlers. Additionally, plain text javascript can be inserted into the page between <qxt:script> and </qxt:script> tags. It will be executed at its position in the document. As mentioned above, it is advised to enclose the code in <![CDATA[ ... ]]>. 

It is also possible to include external scripts this way:

<qxt:script src="js/myExternalFile.js" />

Creating the main application

<?xml version="1.0" encoding="utf-8"?>
<qx:root 
    xmlns:qx="http://www.qxtransformer.org/qooxdoo"
    xmlns:qxt="http://www.qxtransformer.org/extension"
    qooxdooVersion="0.7">
	
	<!-- application -->
	
	<qx:application 
        title="Hello world application"
        namespace="custom"
        authors="John Doe">
        
        <qx:button label="Click me!" onClick="alert('Hello World!');" />
        
    </qxt:application>
 
</qx:root>

    xmlns:qx="http://www.qxtransformer.org/qooxdoo"
    xmlns:qxt="http://www.qxtransformer.org/extension"

<?xml version="1.0" encoding="utf-8"?>
<qooxdoo 
    xmlns:qx="http://www.qxtransformer.org/qooxdoo"
    xmlns:qxt="http://www.qxtransformer.org/extension"

    qooxdooVersion="0.7">

 
	<qx:widget 
		namespace="custom" 
		className="LoginWindow"
		title="Login Widget" 
		authors="John Doe">
 
		<qx:window 
			id="loginWindow" 
			width="400" 
			caption="Login" 
			modal="false" 
			showMinimize="false"
			showMaximize="false" 
			showClose="false" display="true"
			onAppear="this.centerToBrowser()">
[...]

var w = new custom.LoginWindow;