Database-backed Application

Summary

In part 1 we built and configured a module to connect to a database and setup the database and JDBC connection. The application framework is complete we now need to write the application code which is now pretty straightforward.

Specification part2

We will create two pages for the application. A master page will provide an alphabetically browsable view of the address book. The master page will also provide an embedded search form. The search results will be rendered back into the master page. It will also have a link to a new entry form - this will be a new page containing an XForm.

Using the mapper and xrl accessor we will modularize the design into components and use a template document in which the page components are combined.

Building the App

Master Template

The master template will be an XHTML document containing some static content common to all pages. It includes an <xrl:include/> element which is an xrl statement to include any dynamic content supplied from the mapper. Here it is

Copy this into a file called mastertemplate.xml in the resources/ directory. Add the following link to the links.xml document.

The link maps a request for the external root path to an internal execution of the xrl accessor with the mastertemplate.xml as template - since this is just testing we are not providing a content argument, also we are using the xrl-html varient of the xrl accessor, this simply tells xrl to return the XML with a mimetype of text/html. We've also specified <args>param,session</args> this tells the mapper to pass through the param and session arguments to any included content (more on this later).

We can now test the contentless template http://localhost:8080/addressbook/.

Adding the alphabet browser bar

We require an alphabetized browser bar with each letter a link to a page which renders all entries beginning with that letter. We have said that the main page will provide the browser view. So it's REST interface will look like /addressbook/?letter=a.

Here is an idoc which uses an XQuery to generate the browser bar - save it in the resources/ directory as alphabetmenu.idoc.

We want to include the browser bar in the mastertemplate. First we add a new named link to the links.xml file.

This link has no external part since it is purely an internal component. It's internal URI is an active:dpml which executes the alphabetmenu.idoc in the DPML runtime. Therefore any XRL Include of this link will execute the the DPML process to generate the browser bar.

Edit the mastertemplate to xrl:include the alphamenu link like this...

Try the master template again http://localhost:8080/addressbook/.

Entering data with an XForm

So far our application is static - we can't add any data and all we're doing is looking at the dynamically generated template but with no content.

Add the following two links to the links.xml document.

The first link maps the external path /newentry to an execution of the XRL runtime. As for the "main" root link it uses our mastertemplate.xml but it also declares a content resource xrl:xform. This is a reference to the second link, an internal link, which executes an idoc xform_execute.idoc. The result is that a request for /newentry will start a cascade of XRL includes, first for the mastertemplate which will then include the content of the execution of the xform idoc.

XRL is a pull runtime it recusively pulls URI referenced resources defined by xrl:include declarations - it uses the the named links as the primary resource identifier, the resources can be static or as in the case above dynamically generated (here by DPML).

Below is the xform_execute.idoc and below that is xform.xml, the XForm it will process. Add these files to the resources/ directory.

This is the XForm for a new entry - although it has many fields it is not very complicated! It contains a single constraint - the Form is not valid unless a lastname is given.

XForms

XForms are the W3C's next generation web form - since browsers do not yet support client-side XForms we are using a server-side XForm module based on the Chiba XForm engine. You can read in detail about using XForms on NetKernel here.

In brief the xform_exec.idoc is both the source of the form and the target of submission of the form. It renders the form using an XSLT stylesheet (see below, make sure you copy this to a file called xform_style.xsl in the resources/ directory). The form's state is held in the session (hence the reason we used the sessionmapper and pass the session through in the mapper arguments). The xform will not complete until all its constraints have been met. In this case a lastname must be provided. Once valid the xform's instance data is submitted to the target process defined in the submission definition - in this case the idoc xform_process.idoc, which receives the instance data as it's parameter.

You should have put these three files (named as described above) in your resources/ directory. In the mastertemplate.xml add an href link <a href="newentry">Add new entry</a> - this links to the XForm page we've just created. Give it a try directly...http://localhost:8080/addressbook/newentry.

The XForm executes but we've not created the xform_process.idoc yet so it will break if you submit any data. In the final part we will show how the xform_process.idoc creates a new RDBMS entry from the form data and finish the browser.