Getting started with betterFORM limeGreen
This post guides you through the first steps of installing, running and using betterFORM limeGreen. Though betterFORM can be run in a variety of deployments and configurations this document focusses on betterFORM XRX. This is a bundling of the eXistDB XML database with betterFORM in a ready-to-run configuration along with a dashboard to help you manage your applications.
- Java 1.5 installed on your system
Before you start you need an installation of betterFORM XRX.
- Goto the sourceforge download page and get the latest version. This will download the betterFORM installer.
- After the download is finished double-click the betterform-install.jar to open it. Please note that Java must be installed on your system and jar files must be configured as executable (which is the case by default).
- After you have accepted the license terms and specified the installation directory you will presented with some readme information. Skip that screen to get into the package selection.
The installer will offer several different options for betterFORM:
- installation of a WAR for direct deployment into your webcontainer
- betterFORM standalone bundles the Jetty webcontainer and comes with a graphical application starter
- betterFORM XRX which integrates betterFORM with eXistDB as a standalone application platform
For the scope of this article we deal with betterFORM XRX which is already selected by default in the installer. Just hit the ‘Next’ button to go to installation screen.
During this step the betterFORM will be installed on your disk.
The following screen lets you choose a password for the ‘admin’ user. Please memorize this password as otherwise you’ll be locked out of the database. If you are just test-driving you may leave the password empty.
After this is done hit ‘Next’ a last time to finish the installer.
In standalone (Jetty) and XRX mode betterFORM can be run via a Java executable jar. To run it double-click it in your favorite file browser or execute the following command line:
>java -jar betterform.jar
A small application with betterFORM logo will appear.
Clicking on the icon will run your default web browser with the entry page.
The ‘Dashboard’ will be the default entry page when you browse a new betterFORM installation. Besides browsing and running the XForms, you can add files and collections to your application and view the source.
One of the items found on the Dashboard root level is the Feature Explorer. It is the central location for running the reference forms of betterFORM. They serve as a live documentation of XForms and betterFORM features and show you working markup examples and the rendered output.
Some of the pages will have links to the respective sections in the XForms 1.1 Recommendation and the XForms 1.1 Quick Reference documents for quick lookup of syntax details.
On the right hand there is a CSS reference that highlights the matched elements when hovered.
The Feature Explorer will be extended with further examples as new features become available.
Under the hood Feature Explorer makes heavy use of form embedding. All embedded forms can also be run standalone by browsing the ‘reference’ collection with the Dashboard and clicking on the respective link.
Running the XRX demo application
Start your browser and goto:http://localhost:8080/betterform/rest/db/betterform/apps/timetracker/index.xql or execute index.xql from Dashboard. This should show you a screen like this:
Please note that this is only the first version (0.1) of the application and we plan to continuously extend it to show more features and solution patterns. Therefore not all menu buttons are already working.
Please use the ‘filter’ to select a start date before 01. June 2010 to see all the sample data.
What Timetracker does
TimeTracker is a simple application to track the time spend on a project and we use it internally log our working hours. As such TimeTracker gathers small XML files in a database collection and allows to create, edit, delete and filter those entries. The whole application consists of a bunch of files organized in a collection hierarchy stored in the database.
TimeTracker uses XForms, REST and XQuery to model a complete application. The XForms are generated by XQuery code and XForms embedding is used to assemble the different documents into one single-page application. The data can be filtered by several criteria and are returned as a plain HTML table. The table is then embedded into the main page of the application (index.xql).
A single entry in our time tracking is represented by a ‘task’. Tasks are always shown for the selected date range which is displayed in the upper right. By choosing the ‘Filter’ button from the toolbar you can change the displayed date range. Please play with the filter fields to see more or less entries. The form selects a default date range that starts 30 days before today.
A first glimpse behind the scenes
To see the gears TimeTracker was made of it’s best to use the eXistDB Java admin client and take a look into the XQueries and XForms that make up the application. To access the admin client please first goto http://localhost:8080/betterform. In the right upper corner of the Dashboard you find a blue button with an eXist icon. Hit that button and the admin client will download and start automatically.
After you have confirmed the execution of the admin client the following screen will be presented:
Please use the password you have choosen during install to login and close the dialog. Otherwise the application will not show up.
Go to collection ‘betterform/apps/timetracker’. This is the root collection of the application. You can directly access any file or collection by double-clicking on it. You should start your investigation with ‘index.xql’ with is the main page of the application. All other documents or generated contents will be embedded dynamically into this page. index.xql is simply an XForms document wrapped as an XQuery. XQuery does not do anything here. It’s just to see it’s possible ;) Instead we could have just stored a XHTML document here.
Further files of interest are ‘edit/edit-item.xql‘ which is the creation and editing form for the application and ‘list-items.xql’ which is responsible for generating the results table. You will find some more files in the database and not all of them are already active.
This is only a first glimpse on the application and betterFORM XRX. A follow-up post will go more into the technical details of how the pieces fit together and show how easy and powerful the combination of XForms REST and XQuery is.