This tutorial is a step-by-step instruction on how to get started with qooxdoo and how to build a first application.

If you expect to see how to write a typical “Hello World” application with only a single line of code you will be disappointed. This tutorial tries to show you in detail how to set up a new qooxdoo project using best practices, which can easily become the basis for more complex applications.

The tutorial takes the following three steps:

1. Preparations
2. Build a skeleton
3. Write the application code

Of course, the steps cannot cover all details, so links to the corresponding articles in the wiki-based homepage are provided.

Check the Requirements. You will need “Cygwin” on Windows and the “XCode developer tools” or “fink” on OS X. Typical Linux distributions should already have everything properly installed by default.

You can put the qooxdoo SDK (to be downloaded) and also your “Hello World” application (to be created) into any two (independent) places in your file system. For simplicity, we assume in this tutorial that you unpack the SDK and the skeleton for the “Hello World” application into a base directory “QOOXDOO”. If it does not yet exist, please create a new folder:

mkdir QOOXDOO

Download the SDK from http://qooxdoo.org/download. Use the “.zip” archive for Windows and the “.gz” archive for Linux or OS X. For example, the current release 0.7 for OS X would be “qooxdoo-0.7-sdk.tar.gz”.

If you downloaded the archive into directory “QOOXDOO”, you may want to use one of the following commands.

Under Windows:

cd QOOXDOO
unzip qooxdoo-0.7-sdk.zip

Under Linux or OS X:

cd QOOXDOO
tar xzf qooxdoo-0.7-sdk.tar.gz

In both cases, a directory “QOOXDOO/qooxdoo-0.7-sdk” will have been created.

cd qooxdoo-0.7-sdk/frontend
make

make (or the equivalent make source) generates the “source” version of qooxdoo. This is what we need during development. No JavaScript optimizations take place and both the qooxdoo and application class files are included as distinct, unmodified JavaScript files. This is essential for debugging, since the browser is still able to associate errors with the corresponding JavaScript files and line numbers.

In contrast, make build would have generated the “build” version of qooxdoo. By default it combines, compresses and optimizes all class files into a single JavaScript file and transfers all other resources the application needs into the “build” directory. This build directory is self-contained and ready for deployment, e.g. onto a remote web server by (S)FTP. (Generating from source)

Please try the sample applications and the API viewer by opening the following file in your browser:

• QOOXDOO/qooxdoo-0.7-sdk/frontend/application/index.html

Especially the API viewer is a valuable source of information for qooxdoo application developers.

You have successfully installed qooxdoo and are now ready to write the first application.

We base our “Hello World” application on the so-called qooxdoo application “skeleton”. The skeleton contains a pre-configured build system and is the best way to take full advantage of qooxdoo.

Unpack “skeleton.tar.gz” (”skeleton.zip” on Windows) from “QOOXDOO/qooxdoo-0.7-sdk/frontend/application/” into the QOOXDOO base directory.

Since we want to create a “Hello World” application rename the folder “skeleton” to the more meaningful “helloworld”.

Tell the Makefile where to find the qooxdoo SDK. This is the only thing we have to configure to start using the skeleton. Open “QOOXDOO/helloworld/Makefile” in a text editor and replace the line:

#
# Location of your qooxdoo distribution
# Could be relative from this location or absolute
# 
QOOXDOO_PATH = PLEASE_DEFINE_QOOXDOO_PATH

#
# The same as above, but from the webserver point of view
# Starting point is the application HTML file of the source folder.
# In most cases just add a "/.." compared to above
#
QOOXDOO_URI = PLEASE_DEFINE_QOOXDOO_URI

with

#
# Location of your qooxdoo distribution
# Could be relative from this location or absolute
# 
QOOXDOO_PATH = ../qooxdoo-0.7-sdk

#
# The same as above, but from the webserver point of view
# Starting point is the application HTML file of the source folder.
# In most cases just add a "/.." compared to above
#
QOOXDOO_URI = ../../qooxdoo-0.7-sdk 

cd helloworld
make

This builds the skeleton just like we have built qooxdoo before. If everything went fine, you can now open “QOOXDOO/helloworld/source/index.html” in your browser. Make sure you have disabled the popup blocker for this page because all debugging messages will be displayed in a logging console inside a popup window. (Using the Skeletons)

The most interesting files are the JavaScript class files of the application under the “source/class” directory. This is where all of the actual coding in JavaScript takes place. For a typical qooxdoo application you will not have to create or modify CSS files and you only may need to tweak the initial HTML file. (The directory structure)

qooxdoo organizes all JavaScript classes in namespaces just like Java does. A fully-qualified class name consists of a namespace, which corresponds to its path name relative to the “source/class” directory, and the actual class name, which corresponds to its file name. In the qooxdoo SDK, for example, the button class is “qx.ui.form.Button” which means that it is in the directory “qx/ui/form” and has the filename “Button.js”. This is how the files are organized in the skeleton as well. In our example the application class is called “custom.Application”, so the corresponding path for the file is “source/class/custom/Application.js”. (Understanding namespaces)

cd source/class/custom

The button of the unmodified skeleton application reads something like “First Button”. We want to create a “Hello World” application, so we now will modify the top application class “Application.js” a little bit.

The main() method of the application class constructs all widgets that should be displayed at application start-up. In the original skeleton this is only a single button. We keep this button, but change the first argument of its constructor to “Hello World!” in file “Application.js”:

// Create button
var button1 = new qx.ui.form.Button("Hello World!", "custom/image/test.png");

Now save the file and hit “reload” in the browser. Since we are using the “source” version of this qooxdoo application the changes are visible in the browser immediately.

(Don’t worry too much about the second argument to the “Button()” constructor; it specifies an image resource to be displayed within the button. As for the image resources used in the example code, they follow similar path patterns as the Javascript code files, but there is also some name aliasing involved, through both application-defined as well as qooxdoo built-in aliases).

To bring a bit of life to the application you can add an action to a button. A user can then “execute” the button either by clicking it with the mouse or by using the keyboard (pressing Tab untill it is focused, then hitting Return). In such a case an action event “execute” is fired by qooxdoo. It is possible to attach event listener functions to qooxdoo events, which are called when an corresponding event is fired.

Modify the corresponding section in the main() method so that it looks like this:

// Add an event listener
button1.addEventListener(
  "execute", 
  function(e) {
    this.debug("Hello World button clicked!");	
    },
  this);

The modified statement says: When the “execute” event of the button is triggered (first argument), call the anonymous function as event handler (second argument) and bind “this” inside the event handler to the instance of the application class (third argument). (Using Events)

If you reload the page again and click on the button, you should see the text “Hello World button clicked!” in the logging console.

Note: At least with Firefox 2.0 with installed Addon Firebug 1 no logging console will appear at all. Instead the log message will be written to the Console provided by Firebug.

To generate the API documentation for your project, just go to the project directory “QOOXDOO/helloworld” and type:

make api

This command will generate an API viewer for both the qooxdoo framework classes and your very own application classes:

Please open “QOOXDOO/helloworld/api/index.html” in your browser.

OK, for such a simple “Hello World” example this might look like overkill. But keep in mind how fast the automatic API reference may become indispensable during development of larger applications. (How to write API documentation)

Congratulations! If you have successfully followed the instructions up to this point you have created a full-featured qooxdoo “Hello World” application. Take this application as your starting point for some great qooxdoo application