Getting started with betterFORM XRX (lightSteelBlue)
This post relates to betterFORM lightSteelBlue XRX edition and gives a short introduction about how to start developing XRX applications with it.
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. The installer is a small wizards that lets you choose the modules you want before actually downloading them. This saves you bandwidth and time during install.
- 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 packs download screen. The download will take a while as this pack is about 65Mb.
During this step the download and installation on your machine happens. After this is done hit ‘Next’ a last time to finish the installer.
Running betterFORM XRX
To run betterFORM XRX open a shell and goto INSTALLATION_DIR/bin (where INSTALLATION_DIR is of course the location on your disk you choose during installation).
Execute ./startup.sh or startup.bat depending on your operating system.
Now the system should be up and running and http://localhost:8080/exist should show you the standard eXistDB homepage.
Running the XRX demo application
Start your browser and goto: http://localhost:8080/exist/rest/db/betterform/apps/timetracker/index.xql 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.
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 try to change to a starting date some weeks before today to see more 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/exist. In the left sidebar you find an orange button labelled ‘Launch’. 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 ‘betterform‘ to login and close the dialog. Otherwise the application will not show up. Also note that this password cannot yet be changed for TimeTracker as it is hardcoded in the forms. Next version will add auth to TimeTracker.
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.
Entry filed under: betterFORM XRX.