The basic app
Getting started
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-bookcastapplication, so instead let's decide on another name, for examplemy-bookcast. Create a directory with that name asRESOURCES/apps/my-bookcast. For convenience, we refer to that new directory as theBOOKCASTdirectory below.Create a
page-flow.xmlfile underBOOKCAST:
This page flow is automatically called for any path that starts with /orbeon/my-bookcast/. Here, it matches on the exact path /orbeon/my-bookcast/ and calls up the page view called view.xhtml.
Create a skeleton for your
view.xhtmlunderBOOKCAST: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 see something like this:
NOTE:
If you get lost at some point in this tutorial, feel free to look at the reference source files for the Bookcast application:
XForms model and instance
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 <xf: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!
First controls
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 see something like this:
Another thing: all XForms controls require a nested <xf: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 (<xf:label/>).
Adding constraints
Now say you want to make the title and author required data. You control this with the <xf:bind> element in the XForms model. Add the following under <xf: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:
Here we use the
requiredattribute, which determines whether a field is, well, required, that is, whether it has to be filled out by the user.Much like
<xf:group>in the controls,<xf:bind>elements can be nested.<xf:bind>uses arefattribute, which allows pointing at more than one node using a single XPath expression.The outer
<xf: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<xf:bind>element is the root element of the first XForms instance. You could be more explicit, for example with:Or with:
The latter makes it clear, with the XForms
instance()function, that you are addressing thebooks-instanceinstance and not another instance, so you will probably tend to prefer that notation.The inner
<xf:bind>elements apply the required MIP to the<title>and<author>elements. Therequiredattribute must contain an XPath expression, which is why it containstrue()(the way to express a Boolean "true" value in XPath) and not simplytrue. 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.
Single selection controls
XForms is of course not limited to simple input controls. Add the following after the second <xf:input> control:
Reload the page. You should see the following:
You have just added a single selection control with <xf: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 <xf:item> elements. Each one creates an item in the drop-down menu. An item has two sides: the <xf:label> element specifies the label that is presented to the user, and the <xf: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 <xf:select1> element. So let's do this! Create a new instance in the model:
Then modify the <xf:select1> element as follows:
Notice the new <xf:itemset> element in addition to the <xf: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.
Adding a text area
Now add yet another control, a text area:
The <xf: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="xxf: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 xxf: 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.
Finishing-up the controls
To create the ratings input, add this new instance:
And then add another <xf:select1> control:
Here again, you store the list of items as a separate instance, but we keep the "empty" item as an <xf: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 (you will see how to add the Save button you see on this screenshot in the next section):
By now you probably get the gist of it!
