Below are some quick steps for getting a new application started with Pentaho Xul. In this example Swing is used as the runtime toolkit. The same steps apply for creating a project with XUL-SWT.
Step 1: Get the libraries
You can build XUL yourself or download pre-compiled binaries from the Pentaho Build machine
If you're building yourself, for each of the Pentaho XUL projects you need to do the following:
- Run the "Resolve" task from the included build.xml file. This will bring down the supporting jars required for compilation.
- Run the "Dist" task to create a jar.
- Copy the resulting jar from the "dist" directory to the lib directory of your project.
- Also copy all jars from the "lib" directory into the "lib" directory of the same project. This will ensure that you have all the required dependencies.
Step 2: Create your project
Create a new project in your IDE of choice. Add the XUL-Core jar and Swing, SWT or GWT jar depending on the final client UIs you want it to run in.
Step 3: Loading your Xul Document
Loading of Xul documents is done with via a XulLoader. For each of the UI toolkits there's a corresponding XulLoader implementation to use. The loader parses the XML document and creates the real UI elements in the background. The resulting XulDomContainer contains a DOM with all the Xul tags parsed for the targeted UI technology.
Step 4: Adding Event Handlers
Interaction between the UI and your code is managed though event handlers (often called "controllers"). You can add these directly in the Xul document with the <script> tag:
However, most of the time you'll want to control the creation of your event handlers (dependancy injection for instance). Now is the time to create them and add them to the XulDomContainer.
Event handlers added to the container are given a reference to the XulDomContainer. This allows them to access the XUL DOM as needed. If your handler extends "AbstractXulEventHandler" you interact with the XulDomContainer via the "document" member variable.
Step 4: Starting it all up
The next step is to create a XulRunner and pass it your XulDomContainer instance. XulRunners handle "onload" events for your document and if you application is a <window> or <dialog>, can display display the UI if started.
You may not want to start the runner. For instance, if you wanted to pull out a particular dialog or panel for use in your Swing application, you could do that here. If there were a <vbox> with an id of "sidePanel" in your document, you can pull it out of the document and use it as a JPanel in your Swing app by doing the following:
Here's the steps above all in one block. Change the Swing to SWT and you have your application running in a completely different UI toolkit.
What's different in GWT?
Starting up a GWT Xul app is a little different due to the asynchronous nature of the technology.