XRX Toolkit

XRX (XForms-REST-XQuery) is an web application architecture where XForms is used to provide the user interface (fulfilling much of the role of Javascript and Javascript libraries), XQuery provides the server-side processing (fulfilling the usual role of PHP), and REST requests to a server (typically an XML database) glue the XForms to the data on the server (roughly equivalent to AJAX calls).

In the XRX architecture, data is stored as XML both on the client and server. While some data format shifting is needed, far less is required than when shifting between Javascript's native structures and XML.

The Open Siddur XRX toolkit is a set of categorized XQuery function modules for server-side generation of XForms and data processing. In order to develop with it:
 * familiarize yourself with the basics of XQuery and XForms.
 * For XForms basics, the online tutorial at W3Schools provides a good introduction; Micah Dubinko's XForms Essentials is also a good resource. The XForms wikibook provides an introduction and a number of examples.
 * install a mirror of the database on your local machine.

=A First app=

Applications are stored inside the database in their own collection in /db/code/apps/. This application, for example, may be stored as helloworld.xql in the database collection /db/code/apps/helloworld.

To get the application into the database, start up the database and place the application in your working copy in code/apps/helloworld (note: all working copy paths are relative to the tag you're using, eg: trunk, branches/efraim). Run: make db-svnsync which will sync the database to the contents of your working copy.

The conventional "Hello World" application:

The application above will simply display "Hello, world!" using the Open Siddur applications' header and footer. It will run when you point your browser to http://localhost:8080/code/apps/helloworld/helloworld.xql while the database is running.

=Modules and apps=

The XRX toolkit is separated into modules and apps. XQuery Modules (.xqm extension) provide function libraries that can be used by applications to do work. These functions both operate on data and provide standard interfaces and UI controls. Each module is uniquely identified by a URI namespace (such "http://jewishliturgy.org/modules/site"). When loading a module (with import module namespace ...), both the namespace and the location of the module (at "...") must be referenced. When you call functions in the module, the function names are prefixed by the module's namespace prefix (as in site:form).

Apps group together function modules and user-executable interfaces that operate on related data. For example, the "contributors" app operates on the contributor list, and the "bibliography" app operates on bibliographic records.

Example: Adding a login control
The login control is provided by a module in the user management application (/code/apps/user).

In XForms, structured data is declared in "instances" in the data model, and user interface code references those instances. The content of the instances is submitted to the server through HTTP, and the server places the result in another instance. In the Open Siddur XRX toolkit, modules provide *-instance and *-ui functions that place the instances and user interfaces of the common controls in the appropriate places.***

Modifying our "Hello world" application, we get:

App structure
Apps have a general directory structure template: controller.xql app-info.xml search/ search.xql views/ view-item.xql list-items.xql edit/ edit-item.xql edit.xql new-instance.xml delete.xql save.xql update.xql modules/ controls.xqm common.xqm scripts/ *.xsl2 styles/ *.css

Form validation errors
To do server-side validation of the data in a control, add a call to the following XQuery function in the instance

and add a call to the following function as a child of the control:

If you give controls:validator-instance a $event-target parameter, you may also catch the events:
 * validator-ok
 * validator-warn
 * validator-error
 * xforms-submit-error

The $validator-url parameter points to an XQuery that will run whenever the control data needs to be validated. The data will be sent as XML via POST. An optional lang= query parameter may be sent, indicating the preferred language for error messages.

The XQuery validator must return one of:
 * A single  element, indicating that the input data is valid
 * A single text element, indicating that the input data is valid, but there may be a problem with it. The optional type is a computer-parsable code indicating the warning type.
 * A single text element, indicating that the input data is invalid. The type is a computer-parsable code.