Getting Started with Qookery

This guide will help you create your first Qookery project. It is assumed that you are familiar with the basics of Qooxdoo and that you have downloaded and installed the Desktop component of the framework.

Setup a new application

We will create a new Qooxdoo application with the skeleton application creation tool create-application.py found in <qooxdoo-sdk>/tool/bin

> cd <qooxdoo-sdk>/tool/bin
> ./create-application.py --name tutorial
> cd tutorial

In the build file config.json, uncomment the “jobs/libraries” key and replace the example contrib line

"manifest": "contrib://SkeletonApplication/trunk/Manifest.json"

with this one

"manifest": "https://github.com/ergobyte/qookery/releases/download/0.1/qookery.json"

Build your application for the first time

> ./generate.py source-hybrid

You will need a minimal web server to load file resources via XHR, which is needed by Qookery. Python provides an module for that, called SimpleHTTPServer. Open a new terminal window, run below commands and leave the Python server running

> cd <qooxdoo-sdk>
> python -m SimpleHTTPServer

To check that everything works, open your web browser and visit

http://localhost:8000/tool/bin/tutorial/source/index.html

Create your first form

Create a folder named forms in the resource directory of your project

> mkdir -p source/resource/tutorial/forms

Inside it, create a file named application.xml with the following contents

<?xml version="1.0" encoding="utf-8"?>
<form xmlns="http://www.qookery.org/ns/Form">
	<button label="First Button" icon="tutorial/test.png">
		<script event="execute">
			alert("Hello, World!");
		</script>
	</button>
</form>

Edit source/class/tutorial/Application.js and replace the skeleton code that creates a button (everything after "Below is your actual application code...") with below lines

qookery.contexts.Qookery.loadResource("tutorial/forms/application.xml", this, function(xmlSource) {
	var xmlDocument = qx.xml.Document.fromString(xmlSource);
	var parser = qookery.Qookery.createFormParser();
	try {
		var formComponent = parser.parseXmlDocument(xmlDocument);
		this.getRoot().add(formComponent.getMainWidget(), { left: 100, top: 50 });
	}
	catch(e) {
		this.error("Error parsing application root form", e);
	}
	finally {
		parser.dispose();
	}
});

Generate and run your application again; if all goes well, you will get the exact same UI as before, but with Qookery.

Open a second form in a window

Inside source/resource/tutorial/forms, create a file named window.xml with the following contents

<?xml version="1.0" encoding="utf-8"?>
<form xmlns="http://www.qookery.org/ns/Form" column-count="2">
	<image source="tutorial/test.png" align-y="middle" />
	<label rich="true" wrap="true" label="Discover Qookery and experiment with its features" />
</form>

Now create a second button that opens a window in application.xml by adding below code under the first <button> element

<button label="Second Button" icon="tutorial/test.png">
	<script event="execute">
		qookery.contexts.Qookery.openWindow("tutorial/forms/window.xml");
	</script>
</button>

Build and run again the application – you will be able to open your first window.

At this point you can quickly experiment with Qookery by editing window.xml, hiting save in your favorite text editor/IDE and pressing the Second Button again. Since XML forms are parsed and evaluated at runtime, there is no need to regenerate the application or refresh the browser window.

Next steps

Hopefully this short introduction whetted your appetite for more. Until documentation is improved, here are some tips as to how to proceed from here:

- Experiment with the Qookery Playground to get to grips with the XML language
- Much needed assistance is provided by the XSD files of the project when authoring forms. An XSD enabled XML editor is able to both autocomplete suggestions and mark errors with descriptive messages. In order to get the XSD files, you will have to download the Qookery source code. At the root of the directory structure resides an OASIS xml-catalog.xml which may be used to quickly instruct your IDE with the location of the XSD files.
- Try to integrate XML forms into an existing project by replacing UI elements incrementally: first work on non-crucial parts, such as an about window, and then proceed to more critical parts
- When at loss, consult the source code and/or ask the developers for help and hints