Orbeon Forms is an open source solution to build and deploy web forms. For more information, please visit the Orbeon home page at http://www.orbeon.com/.

To go through this tutorial, you don't need much: any reasonably modern computer on which you can install Java 1.5 or 1.6 should do (Java 1.4.2 may work for you but 1.5 or 1.6 is strongly recommended). You should be comfortable with installing new software on your computer, including uncompressing zip or gzip archives. You will also have to edit XML files. If you are familiar with HTML, this should not be a problem.

You also need a reasonably recent web browser. We recommend one of the following browsers:

• Mozilla Firefox 1.5 or 2 or greater.

• Safari 2 or greater.

• Opera 9 or greater.

• Internet Explorer 6 or 7 or greater.

You will not have to:

• Write any Java code or any scripting language code.

• Use a compiler or other complicated build tool.

• Install browser plugins or any other client-side software, besides your regular web browser!

Orbeon Forms follows a few principles:

• More standards. You use standards whenever possible. For example, Orbeon Forms applications are created using XForms and XHTML, which are W3C standards.

• Less scripting. You write most applications without writing Java, JavaScript, or other scripting code. (But you can if you really want.)

• Instant gratification. You get instant gratification by making changes to your application and just reloading your page in your web browser. (You don't need to "compile" or "build".)

Java provides the cross-platform environment in which Orbeon Forms runs.

If you don't have Java installed yet, download it from the Sun web site at http://java.sun.com/javase/downloads/index.jsp. Sun provides Windows, Linux and Solaris versions. If you use a Mac with Mac OS X, you probably have Java already installed on your machine, but if not visit http://www.apple.com/macosx/features/java/. Then follow the instructions to install Java.

Tomcat is the container application into which Orbeon Forms deploys. Follow these steps to download and install Tomcat if you don't have it installed yet:

1. Download Tomcat 5.5 from the Apache web site at http://tomcat.apache.org/download-55.cgi.

2. Install Tomcat as per the instructions. If you downloaded the installer version (Windows only), run the installer. If you downloaded a compressed archive, uncompress it to the location of your choice. We call the install location TOMCAT_HOME (on windows, this could be c:/Program Files/Apache/Tomcat, on a Unix system, /home/jdoe/tomcat, etc.).

3. Check that your Tomcat installation is working correctly:

   • Run the Tomcat startup script under TOMCAT_HOME/bin (startup.sh or startup.bat depending on your platform), or start Tomcat with the control application (Windows only).

   • Open a web browser and access the following URL:

     http://localhost:8080/

     You should see the Tomcat welcome page.

     

Follow these steps to download and install Orbeon Forms:

1. Download Orbeon Forms 3.5 or later from http://www.orbeon.com/forms/download.

2. Uncompress the archive into a directory of your choice. We call that directory ORBEON_FORMS_HOME.

3. Under ORBEON_FORMS_HOME, you find a file called ops.war. This is the file to deploy into Tomcat. To do so, just copy it under TOMCAT_HOME/webapps (alternatively, if you know what you are doing, you can uncompress it at a location of your choice and configure a context in TOMCAT_HOME/conf/server.xml). The webapps directory is already present after you have installed Tomcat.

Make sure you restart Tomcat (run the shutdown script under TOMCAT_HOME/bin, and then the startup script again). Then open up with a web browser the following URL:

You should see the Orbeon Forms welcome page:

You can now navigate the list of sample applications listed on the left side. You can see the source code of each application directly in your web browser by selecting the "View Source Code" tab at the top of the page to open up the Orbeon Forms Source Viewer:

The Hello application is about the simplest Orbeon Forms application you can think of. It asks for your name and displays it back. You run the Hello application by selecting the link "XForms Hello" in the list of applications. Here are direct links for running XForms Hello on your local Orbeon Forms install or online on the Orbeon web site.

Simply enter your first name in the input field, for example "Joe". You should promptly see a message underneath saying "Hello, Joe!".

You can directly view the source code from your web browser by selecting the "View Source Code" tab. There you see:

• view.xhtml: this is the XHTML and XForms code for the Hello application.

• page-flow.xml: this is the page flow for the Hello application. The main task of a page flow is mapping external URLs (as typed in a web browser) to Orbeon Forms pages.

You are now ready to look at the source code of the Hello application. This will give you an idea of what an Orbeon Forms application looks like. First, select view.xhtml to make the source code for that file appear on the right:

The first thing you notice is that this looks very much like HTML (notice the <html> tag). But in fact, this is XHTML, the XML-compatible version of HTML. There are only a few differences that matter between HTML and XHTML, in particular you must close all your tags and use quotes around attributes. Also, you must place your tags in a namespace, which is why the <html> tag features the xmlns="http://www.w3.org/1999/xhtml" namespace declaration.

Another difference with plain HTML is that there are tags that start with the string xforms:. Those are defined by the XForms specification from W3C. They are at the heart of Orbeon Forms and enable all the cool forms features that you see in Orbeon Forms demos. (In order to use XForms tags that start with xforms:, you must add another namespace declaration on the <html> tag: xmlns:xforms="http://www.w3.org/2002/xforms".)

Using XForms in Orbeon Forms means that you don't have to use HTML forms at all. The benefit is that XForms is much more powerful than HTML forms, as you will see in this tutorial.

You notice a tag called <xforms:model>. Because XForms follows a Model-View-Controller (MVC) approach, most XForms pages contain one or more models that usually encapsulate other XForms markup. You place these models under the XHTML <head> tag.

Note that from now on, we prefer the term element to the term tag. An element is an XML term that includes the start tag and end tag, and can have content such as other elements and text.

With XForms, you store the data captured by controls such as input fields, combo boxes, etc. as text contained within XML elements or attributes. Consider the following XML document containing a single element called first-name.

The first-name element is empty. Contrast with:

The element now contains the string "Joe". Notice how in view.xhtml the XML document is encapsulated within an <xforms:instance> element:

Also notice the special xmlns="" namespace attribute on <first-name>: this is necessary because the root element of the XHTML document defines a default namespace with xmlns="http://www.w3.org/1999/xhtml". Because we want to make it clear that the element <first-name> is not an XHTML element, but an element in no namespace, we add xmlns="" to that element. If your instance document must be in no particular namespace, you are always safe to add xmlns="" on the root element of that instance.

This element defines an XForms instance, which is just XForms' way of calling an XML document used to store data.

Now consider the remaining XForms elements in the source file: <xforms:input> and <xforms:output>. These two elements are not located under the XHTML <head>, but under <body>. They are part of the view of your page, in other words these elements directly help define visible controls on the page. Consider <xforms:input>:

You guessed that this element allows the user to input information. <xforms:input> is usually displayed to the user as an input field. The ref attribute is the magic that connects the input field to the XForms instance. It contains an XPath expression, which in this case just looks like a file path. In this case, /first-name points to the element called first-name, which happens to be the only element we have in the XForms instance. Using the ref attribute this way is called a binding and means two things:

• When the user enters text in the input field, the text is saved into the element called first-name.

• It also goes the other way: if somehow the text content of first-name in the XForms instance changes, this is automatically reflected in the input field.

Now consider <xforms:output>. As you guess from the name of the element, this simply displays a value on screen. If you have tried running the Hello application, you have probably guessed the logic that is being implemented: if the first name entered by the user is not a blank string, then we display the "Hello" message followed by the first name and then an exclamation mark. Otherwise if the first name consists only of spaces, we just display a blank string. The idea is to avoid displaying things like "Hello !" without an actual first name.

With many client-side libraries, you express this type of logic with JavaScript. With XForms, you use XPath instead. This means that you need to learn at least a few bits of the XPath syntax. While XPath may be different from what you already know (it is based on expressions and definitely targeted at XML), it is in fact a smaller language than JavaScript.

So how do you hook-up the logic within <xforms:output>? Here, instead of a ref attribute, we use a value attribute. Like ref, value takes an XPath expression, but it doesn't actually create a binding to instance data: it just returns a string. The XPath is as follows:

A few things to point out:

• The main expression has the form if () then ... else .... (This is actually an XPath 2.0 expression, which supports the if construct.)

• The normalize-space() function removes all leading and trailing space (and simplifies internal spaces as well). This is a little trick to not only test whether the first name is empty, but also to test whether it is an all-blank string.

• Contrary to JavaScript, the equality test is expressed with a single = instead of ==.

• The concat function concatenates all its parameters into a resulting string. It is like the JavaScript + operator on strings.

• Note the use of the single quote ' around strings. This is needed because the XPath expression is put within double quotes " in the value attribute.

If you look at your browser's URL bar when showing the example, you notice that it looks like this:

• The first part of the URL, http://localhost:8080/, is self-explanatory: it depends on what host and port your server is running.

• The next part, ops, depends on what context you install Orbeon Forms into. By default, because the WAR file is called ops.war, the context is ops. (You could as well configure your container to use a different context, or an empty (default) context.)

• The last part, /xforms-hello/, automatically matches the name of the directory you store your application into (more on this later when you look at the source code). This causes the application's page flow (page-flow.xml) to run.

So now look at page-flow.xml for the Hello application. It is very simple:

The important line in this page flow is this one:

It tells Orbeon Forms that any path (notice the wildcard *) sent by the web browser to this application causes the page view stored in view.xhtml to be processed. You can check this by entering the following path in your browser:

The exact same result shows! Of course, page flows make the most sense when you have more than one page in your application, which translates into more than one <page> element.

Under TOMCAT_HOME/webapps/ops, you find a WEB-INF directory. That directory, in turn, contains a resources directory. We refer to that resources directory as RESOURCES below.

The RESOURCES directory is very important: this is where your application lives. This directory is called "resources" because it contains all the files (or resources) such as XHTML documents, XML schemas, images, CSS, etc. needed by your Orbeon Forms application.

Under RESOURCES, you see the following files and directories:

• apps directory: contains one sub-directory for each application currently running in Orbeon Forms. By default, it contains a series of sample applications - the ones that you see on the left side of your screen when you start Orbeon Forms. Notice a directory called xforms-hello: this is the directory that contains the Hello application.

• config directory: contains several configuration files that you can modify if needed. For now, you don't need to worry about this directory.

• page-flow.xml file: the top-level page flow file. You should not worry about this file just yet. Just know that by default, it is in charge of deciding which application to run depending on the application name in the URL that you enter in your web browser.

• apps-list.xml file: contains the list of sample applications to display on the left side of the screen. This is not needed by your own application.

You find the application under RESOURCES/apps/xforms-hello. That directory contains the two files that you have seen earlier through the Source Code Viewer in your web browser. Again, the name xforms-hello is important and matches the xforms-hello part of the URL in your web browser: http://localhost:8080/ops/xforms-hello/.

Now, modify view.xhtml:

• Open view.xhtml in a text editor.

• Modify the string "Please enter your first name:" with "Your name here:".

• Save view.xhtml.

• Go back to the Hello application in your web browser and reload the page. You should see the new text appear:

  

• Repeat the experience but add some XForms. For example, add a second <xforms:input> right after the first one:

  <xforms:input ref="/first-name" incremental="true"/><xforms:input ref="/first-name" incremental="true"/>

  Reload the page, and notice, as you type in an input field, how the other one updates as you type. This happens because the two fields are bound to the same instance data. The incremental="true" attribute allows the changes to occur as you type, instead of occurring when you focus in and out of fields:

  

You notice that you get instant gratification with Orbeon forms: just change files on disk, reload your page, and your changes are taken into account with no compilation or other complex deployment.

In this section, you will create a more complete XForms application: the Bookcast application. The Bookcast application allows you to keep track of information about books you have read. For each book, you enter information such as title, author, language, and your own comments. The information is persisted so you can access it again. Then you can do cool things with the available data such create an Atom feed of your entries.

You can run the final application on your local Orbeon Forms install or online on the Orbeon web site.

But first things first. Start by making a first functional page:

• The first thing to do is to create a new directory for your application. Orbeon Forms already come with the complete xforms-bookcast application, so instead let's decide on another name, for example my-bookcast. Create a directory with that name as RESOURCES/apps/my-bookcast. For convenience, we refer to that new directory as the BOOKCAST directory below.

• Create a page-flow.xml file under BOOKCAST:

  <config xmlns="http://www.orbeon.com/oxf/controller"><page path-info="/my-bookcast/" view="view.xhtml"/><epilogue url="oxf:/config/epilogue.xpl"/></config>

  This page flow is automatically called for any path that starts with /ops/my-bookcast/. Here, it matches on the exact path /ops/my-bookcast/ and calls up the page view called view.xhtml.

• Create a skeleton for your view.xhtml under BOOKCAST:

  <html xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://www.w3.org/1999/xhtml" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:xxforms="http://orbeon.org/oxf/xml/xforms"><head><title>XForms Bookcast</title></head><body><p>Hello!</p></body></html>

  This is a very basic XHTML document. It features a title in the <head> and a "Hello!" message in the <body>/. It also declares a bunch of XML namespaces that you need later in the document.

Now go to:

You should something like this:

An XForms document that wants to do something really useful needs at least one model containing one instance. But first it is wise to decide how you would like to represent the information captured by your form. This is an example that shows a possible representation of the data of the Bookcast application (notes are borrowed from Wikipedia and are under the GNU Free Documentation License):

As you can see, the idea is to store the information about all the books in a single XML document. So under a top-level <books> element, we put as many <book> children elements as needed. You will see later how it is possible with XForms to add and remove children elements. For now, your initial instance declaration is empty and contains a single book, and you place it as usual within an <xforms:model> element:

Notice the id attribute which allows other XForms constructs to refer to that particular instance.

Now do the following:

• Insert the model and instance under the <head> element.

• Reload the page.

You should still see a blank page, because so far you haven't added any visual elements!

Now it's time to add some visual controls to your page. Start with the following under the <body> element:

Reload the page. You should seem something like this:

After having looked at the Hello example, this should be clear, with a little novelty: <xforms:group>: this element allows grouping XForms controls together. The ref="book" element changes the current evaluation context for the nested controls, which means that they can use simpler XPath expressions: ref="title" instead of ref="book/title" and ref="author" instead of ref="book/author" (groups have other uses but you don't need to learn that now).

Another thing: all XForms controls require a nested <xforms:label> element, as an effort to help accessibility. In some cases, you won't want an actual label to display next to the control: to achieve this, you can either hide the label with CSS, or use an empty label element (<xforms:label/>).

Now say you want to make the title and author required data. You control this with the <xforms:bind> element in the XForms model. Add the following under <xforms:model> after your instance:

Notice how, as you enter text in the title or author field, the field's background changes color to indicate that the field must be filled out.

The above requires some explanations:

• The <xforms:bind> element is used to assign so-called Model Item Properties (or MIPs) to XForms instance nodes (typically XML elements or attributes). Such properties include whether a field is required, read-only, or visible; whether the field has to satisfy a certain constraint or be of a particular type; and whether the field is a calculated value.

• Here we use the required attribute, which determines whether a field is, well, required, that is, whether it has to be filled out by the user.

• Much like <xforms:group> in the controls, <xforms:bind> elements can be nested.

• <xforms:bind> doesn't use a ref attribute to point to instance nodes, but a nodeset attribute, which allows pointing at more than one node using a single XPath expression.

• The outer <xforms:bind> element points to the <book> element under the top-level <books> element of your instance. This happens because the evaluation context for a top-level XPath expression in an <xforms:bind> element is the root element of the first XForms instance. You could be more explicit, for example with:

  <xforms:bind nodeset="/books/book">...</xforms:bind>

  Or with:

  <xforms:bind nodeset="instance('books-instance')/book">...</xforms:bind>

  The latter makes it clear, with the XForms instance() function, that you are addressing the books-instance instance and not another instance, so you will probably tend to prefer that notation.

• The inner <xforms:bind> elements apply the required MIP to the <title> and <author> elements. The required attribute must contain an XPath expression, which is why it contains true() (the way to express a Boolean "true" value in XPath) and not simply true. Using XPath expressions allows you to make MIPs dynamically change, so that, for example, a form field can be required or not depending on other form fields.

• Note that MIPs are assigned to XML nodes, not directly to controls. But they affect the controls that are bound to those nodes. This is part of XForms's MVC philosophy.

XForms is of course not limited to simple input controls. Add the following after the second <xforms:input> control:

Reload the page. You should see the following:

You have just added a single selection control with <xforms:select1>. The name means that the user can "select one" item among several items. (XForms tends to call controls using more abstract terms, rather than giving them names such as "combo box" or "menu".) The single selection control usually appears like a drop-down menu or combo box with most XForms implementations (but you can change it's appearance as shown later).

Nested within the control, you find several <xforms:item> elements. Each one creates an item in the drop-down menu. An item has to sides: the <xforms:label> element specifies the label that is presented to the user, and the <xforms:value> element specifies the value that is stored into the XForms instance when the user selects that particular item.

Now XForms encourages you to store data in the model. For a selection control, this means storing the list of labels and values in an XForms instance instead of statically listing the items under the <xforms:select1> element. So let's do this! Create a new instance in the model:

Then modify the <xforms:select1> element as follows:

Notice the new <xforms:itemset> element in addition to the <xforms:item> previously used. That element specifies an item set, which allows you to point to the list of <language> nodes in the languages-instance instance, and for each of those to tell the control where to find the label and the value.

You often don't have to use an item set, but using them gives you the flexibility of reusing existing sets of data, dynamically changing the list of items, easing localization, etc.

Now add yet another control, a text area:

The <xforms:textarea> element acts very much like the HTML textarea element. It makes sense to use it to allow entering more than one line of text.

Here there is a little trick: you use the appearance attribute to tell Orbeon Forms to use a particular appearance for the text area control. Instead of the standard text area, appearance="xxforms:autosize" allows the text area to grow vertically as the user enters more text. (This is an appearance which is specific to Orbeon Forms, and you can tell that because of the xxforms: prefix in the appearance value.)

Note that the application captures the same data without the appearance attribute, it's just that the control appears slightly differently and the user experience is changed.

To create the ratings input, add this new instance:

And then add another <xforms:select1> control:

Here again, you store the list of items as a separate instance, but we keep the "empty" item as an <xforms:item>. There is something new: the use of the full appearance, which displays the selection control as a list of radio buttons. This is a standard XForms appearance value, which is likely to be supported by all XForms implementations. (You can tell that it is standard because there is no colon : in the appearance value.)

The only missing control now is the input field bound to the <link> element. Add this, and you should have something like this in your controls:

And this is how the result should look like:

By now you probably get the gist of it!

The Bookcast application now allows you to capture some data. But it is not a very useful application yet, because it doesn't do anything with it! So let's see how you can add a "Save" button that, once pressed, well, saves the data in your form.

Many applications use relational databases as a persistence layer. But because Orbeon Forms and XForms use XML as their native data format, it is very appropriate to use a database that understands XML instead. Orbeon Forms comes with the open source eXist database that does just that.

So how do you save data from XForms to a database? An important feature of XForms is the XForms submission. A submission allows you to read and write XML documents using HTTP and other protocols. Because the eXist database has a REST API (in other words an HTTP-friendly interface), XForms can directly talk to eXist to read and write XML documents and perform all the common CRUD (Create, Retrieve, Update and Delete) operations.

So look at how you create a submission that saves the books-instance instance into eXist:

Let's look at the details:

• The <xforms:submission> element declares a submission.

• As usual, the id attribute allows referring to the submission from other XForms constructs.

• The ref attribute specifies what piece of XML must be handled by the submission. It points to an instance node with an XPath expression. Here, we point to the whole books-instance instance by using the instance() function.

• The action attribute specifies to what URL the submission takes place. Here, you use an absolute path:

  /exist/rest/db/orbeon/my-bookcast/books.xml

  This path is equivalent to using the absolute URL:

  http://localhost:8080/ops/exist/rest/db/orbeon/my-bookcast/books.xml

  (Because it is inconvenient for you to always write absolute URLs when you want to address an URL handle by Orbeon Forms, Orbeon Forms automatically resolves absolute paths against the base http://localhost:8080/ops/.)

  The paths starts with /exist/rest/, which maps to the built-in eXist database. The rest of the path (/db/orbeon/my-bookcast/books.xml) specifies the collection and document to access. Here, we decide to save the data to a document called books within a collection called /db/orbeon/my-bookcast/.

• The method attribute specifies what HTTP method to use. Here, you use the value put, which translates into using the HTTP PUT method. (You may not be very familiar with the PUT method (HTML forms, for example, always use GET and POST), but PUT is getting used more and more with REST interfaces. In just a few words, PUT allows you to store a resource to a particular location on an HTTP server.)

• Finally, the replace attribute specifies what to do with the response sent by the server (here the server is the eXist database). Specifying a value of none tells the XForms engine to discard the content of the response from the database.

This is great, but specifying a submission does not do anything until you send (execute) that submission. A simple way to do this is to use the submit control:

This control has a submission attribute which specifies what submission to send. The control typically looks like a push button, into which the specified label appears. Pressing it automatically sends the submission specified.

So go ahead and:

• Add the submit control just before the <xforms:group> element.

• Add the submission to the model.

• Reload the page.

• Enter a book title and an author, then press the "Save" button. Your form data has been silently saved to the database. It was that easy!

• To check that the data is actually in the database, open up a new browser tab or window, and enter the following URL:

  http://localhost:8080/ops/exist/rest/db/orbeon/my-bookcast/books.xml

  This is the exact same URL to which your submission has done an HTTP PUT. By entering it in your browser, you tell it to do an HTTP GET instead, and the eXist database simply sends the XML document to your browser. You should see this:

  

Try changing the book author and pressing "Save" again. Then in your other browser tab or window, reload the eXist URL, and notice that the data has actually changed in the database.

Do you see how persistence is easily implemented with Orbeon Forms? No need for object-relational mapping or for manually marshalling data to and from a database: just send and retrieve XML documents representing your form data!

You can now save your data to the database, and read it back using your web browser. The missing part of course consists in allowing the application to automatically load up the data when the page is first displayed.

You guessed it, one way of doing this is to use a submission:

There are a few differences with save-submission:

• The id attribute is different: list-submission. (All the id attributes in a given XForms document must be different.)

• The serialize="false" attribute specifies that you don't want to send XML data with this submission.

• The get method specifies that you want to do an HTTP GET, like when you pointed your web browser at the URL to read the document from eXist.

• The replace="instance" attribute specifies that the result of the submission has to be stored into an instance. The instance="books-instance" attribute specifies the identifier of the instance into which the result must be stored.

Like with save-submission, the submission needs to be sent to achieve something. You do this by adding the following event handler to the model:

This tells the XForms engine to execute an action called <xforms:send> when the XForms engine is ready. This action takes an attribute called submission, which specifies which submission to send, here list-submission.

Note the special attribute called ev:event: this attributes marks the <xforms:send> element as an event handler, that is an action that must respond to an event dispatched by the XForms engine. In this case, the name of the event is xforms-ready, which is a standard XForms event with the meaning that well, the XForms engine is ready.

After adding the event handler, reload the page, and notice how the page now loads and immediately shows the data that you saved into the database.

The following is an overview of what has just happened:

• You request the page of the Bookcast application with your browser.

• Orbeon Forms receives the request, looks up the page flow file, and finds out that view.xhtml must be served.

• view.xhtml goes through the XForms engine, which does a few bits of magic: it goes through an initialization phase, where it creates the objects you have defined such as as model, instance, and controls.

• Once this is done, the XForms engine sends the xforms-ready event to the model.

• Because you have defined an event handler for xforms-ready, that handler is called. This caused the <xforms:send> action to be run and, therefore, the list-submission submission to be sent.

• The submission performs an HTTP GET to the URL you have specified. The connection reaches the built-in eXist database, which returns the document called books.xml. The content of that document reaches back the XForms engine, which stores it into the books-instance instance.

• The XForms engine updates the XForms controls bound to the instance with the values now contained in the instance. For example, the "title" and "author" input fields are now updated with the values that came from the database.

• The XForms engine sends an HTML page to your web browser. You see the page with all the correct data as saved earlier into the database.

Actions and events are very important in XForms: they are the glue that allows you to react to different "things" that happen in an XForms page, whether controlled by the XForms engine or directly by the user. This is very similar to using JavaScript in a regular HTML page. In XForms, they allow you to react to the user pressing a button, entering data, etc. XForms comes with a number of standard events and configurable action that you can combine in many ways, so that in most cases you don't need to use something like JavaScript.

(You may wonder what would happen the first time the list-submission is called if no books.xml document is available in the database. The answer is that the database would return an error, and the submission would throw an event called xforms-submit-error. But because you don't have an event handler for this event, nothing happens: the initial content of the books-submission instance is not changed and so you see an empty form.)

Now let's see how we can enter information about more than a single book!

XForms comes with a really handy construct called <xforms:repeat>. This allows you to repeat sections of user interface controls, based on instance data. To see how this works, first replace the group you have defined:

with, instead, this:

Reload the page, and notice that, well, nothing changes so far!

This tells the XForms engine that the content of the <xforms:repeat> element must be repeated as many times as <book> elements are found in the instance. If you have a single <book> element, then the controls are not repeated (which is equivalent to having <xforms:group>); if you have two <book> elements, they are repeated two times, etc.

The trick now is to manage to add a new <book> element to the books-instance instance. First, create a template for the new <book> element to insert by declaring a new instance:

Then you want to copy that template to the right place in books-instance when the user presses a button. You do this with a new control called <xforms:trigger> and a new action called <xforms:insert>. Add the following to your controls:

Let's explain what the above does:

• The <xforms:trigger> element declares a button (remember, XForms likes more abstract names, but this control could have as well been called <xforms:button>). Like all XForms controls, <xforms:trigger> takes a label, which is here displayed within the button.

• Once the user presses it, the button sends an event called DOMActivate. Don't be scared by this funny name, you will use it all the time. It just means that the user has activated the button, which in most cases means that the user pressed (clicked) on it.

• <xforms:insert> is declared as an event handler with the ev:event="DOMActivate" attribute, so this action runs when the user presses the button.

• Here we have decided that we want to insert a new book always in first position in the page. The trick is to configure the insert action with the appropriate attributes.

  With the configuration provided, the action inserts (<xforms:insert>) the contents of the book-template instance (origin="instance('book-template')") before (position="before") the first (at="1") element called <book> (nodeset="book") under the books-instance instance's root element (context="instance('books-instance')").

  This may sound a little confusing at first, but that's because <xforms:insert> is in fact very powerful and you can combine its attributes in many different ways.

Make the changes above, press on the "Add One" button, and you see a new row of controls created.

Again the XForms engine does its magic and takes care of updating the web page automatically. You also notice that the web page does not reload as it updates. This is because Orbeon Forms uses Ajax technology to perform updates to the page. With Ajax, client-side JavaScript code silently talks to the Orbeon Forms server, which then communicates to the client-side code the updates to perform to the page. These update are directly done to the HTML Document Object Model (DOM) without reload.

If you can add books, you probably also want to be able to remove them. This can be done with the <xforms:delete> action. It doesn't seem to make much sense to always remove the first book, but rather, you probably want to delete a specific book. This can be done in several ways, but what about adding a delete button next to each series of repeated controls:

This works in a way very similar to the "Add One" button:

• The <xforms:trigger> element declares a button, but here with a different label ("Remove"). Once the user presses it, the button sends a DOMActivate.

• <xforms:delete> is declared as an event handler with the ev:event="DOMActivate" attribute.

• The difference is in the configuration of <xforms:delete>.

  Here you don't use the position and origin attributes. What you are telling the action here is to delete (<xforms:delete>) the element called <book> (nodeset="book") under the books-instance instance's root element (context="instance('books-instance')") which is at the current index position of the book-repeat repetition (at="index('book-repeat')").

  To understand the index() function, you should know that each repetition in XForms has an associated current index, which tells you which current iteration of a repetition is currently active. The current index changes as you navigate through controls. If you type in the title input field of the first book, the index is 1; if you type in the author input field of the third book, the index is 3; and so on. The index changes also if you click buttons. Usually, the current index is also visually highlighted.

  So here, when you click on the "Remove" button of, say, the second book, the index for the books-repeat repetition changes to 2, and therefore index('books-repeat') also returns 2. This way, you can tell <xforms:delete> to remove the second <book> element.

Now add the new trigger within <xforms:repeat> and reload the page. Try adding books, then removing them by pressing the "Remove" button.

For fun, let's also add a new button to cancel your unsaved edits and reload the original data from the database. It's as easy as this:

When you press the "Revert" button, the list-submission submission is called, which causes the latest saved books.xml document to be reloaded. The XForms engine makes sure that all the controls on the page, including repeats, automatically update to reflect the changes to the books-instance instance.

You are probably not very happy with the look of your application. But let's see how you can improve this with CSS.

First, start with a nicer "action bar" at the top of the page:

You notice that:

• The triggers are also improved with the minimal appearance, which renders the trigger as a hyperlink instead of a button.

• You put an HTML image (<img>) element within the trigger's label. Yes, this is allowed and allows you to make a clickable icon!

Then encapsulate the main XForms controls within a table:

You notice a few more things:

• <xforms:repeat> is put around an XHTML <tr> element, which means that the repetition repeats table rows.

• You add class names on the table and on a table cell, in order to facilitate CSS styling.

Finally, add a books-label class to the controls related to book data, for example:

Now remember that Orbeon Forms does not send the XForms code directly to the web browser, but instead it transforms it into HTML. You realize that this is done because Orbeon Forms cannot assume that your web browser to support XForms at all. Consider the following examples:

And so on for each XForms construct. You notice that Orbeon Forms produces HTML code, including HTML form elements. Ideally, you wouldn't have to know this, and often you don't, but when it comes to styling with CSS having an idea of what the resulting HTML looks like will help you a lot.

So now look at the following CSS declaration for the Bookcast application:

Now just add all the CSS declaration under the page's <head> element, encapsulated within an HTML <style> element:

Reload the page, and you should see something like this:

A little bit of CSS does make things look a little better, doesn't it?

You already made the title and author mandatory fields, but you may want to validate the data more thoroughly. With XForms, validation has two sides:

• A user-facing side, which tells the user which form fields are invalid. With Orbeon Forms, invalid fields are marked by default with an exclamation point icon. In the Bookcast application, you may want to make sure that the link field contains an HTTP URI with a correct syntax.

• A hidden side, which prevents submission from happening if the data to submit is invalid. With the Bookcast application, for example, it is important to make sure that the data you store into the database follows a certain set of rules. This protects you against invalid data entered by the user, or against programming mistakes.

XForms supports two ways of performing validation:

• With Model Item Properties (MIPs) in the model, called constraint and type.

• With an XML Schema. XML Schema is a W3C standard to specify constraints on XML documents, including constraints on the structure of the document or on the data types contained.

Look at the following XML Schema for the Bookcast application:

XML Schema requires some learning, but for now just consider the following:

• This schema constrains the structure of the books-instance document, i.e. it makes sure that the correct elements are encapsulated. If by mistake you create a <bRook> element under <books>, this error will be caught.

• This schema also checks the data types for the rating, language and link. If by mistake you allow a rating with value 6, the schema will catch this.

• A schema is rarely perfect! You can often work more on it and constrain your data in a better way.

Now create the schema as schema.xsd in the same directory as view.xhtml and page-flow.xml. Then link it to the XForms page as follows:

Reload the page, and try to enter an invalid link, for example "ftp://ftp.example.com/". An alert icon will show up as you leave the link field with your cursor.

Still with an invalid link, press the "Save" link and check the data in the database. Notice that the invalid data didn't save! This happens because the XForms engine automatically ensures that the data sent by a submission is valid before going on with the actual submission.

It would be nice to tell the user that saving didn't work. You can do this very easily: if a submission error occurs, the <xforms:submission> element dispaches the xforms-submit-error event. So let's see how you catch that event and display a message to the user:

The <xforms:submission> element hasn't changed, except we added a nested <xforms:message> element. Besides the ev:event attribute, which you start to be familiar with, this element takes a level attribute (use "modal" in general for alerts) and message for the user.

Try now making this change, enter an invalid link, and press the "Save" link: an alert message should show up!

Remember, the name of this application is Bookcast, which lets suggest that we can expose the list of books as a feed of some sort. Here, you will use the Atom Syndication Format (or Atom in short). Atom is a format very much like RSS but it has been standardized by IETF and is much cleaner than RSS (note that there are at least 6 different versions of RSS). Atom is now supported by most feed readers.

An atom feed looks like this (example from the Atom specification):

It would be nice if you could use XForms to produce such a format, and in fact in theory this is possible, but Orbeon Forms currently only supports XForms embedded within XHTML. So here you will use XSLT instead. XSLT is an XML transformation language, which can also be used as an XML template language.

But first, it's time to introduce the Model-View-Controller (MVC) support in the page flow. Consider the following page flow declaration:

Notice how, instead of an XHTML page view (view.xhtml), you now use:

• A page model, called atom.xpl. This page model has an *.xpl extension, which tells you that it contains an XML pipeline.

• A page view, called view.xsl. This page view has an *.xsl extension, which tells you that it contains an XSLT stylesheet.