ost developers have heard of XForms as an XML-based forms language meant to replace traditional HTML Forms. This is essentially correct; XForms was created as the next generation version of HTML forms—but the design goals are such that they can be implemented as forms in environments other than the web browser. One such environment is your typical office application. XForms is implemented as one possible method of doing forms-based applications in OpenOffice or Sun’s StarOffice.

The XForm discussed in this article has been tested on both a Microsoft Windows XP installation, and a Xandros Linux installation. Note that the file URI for output submission was adapted for each operating system’s specific file paths.

Choosing an XML Format
You need an XML format for the form. The example discussed here uses a Danish governmental format that represents the data for a single postal address (only the address, not such extraneous information as the identity of whoever resides there) with additional constructs specific to Denmark. This format makes a decent example because it is simple enough to be comprehensible, yet real-world enough to be potentially useful.

The XKOM (for XML Kommittee) AddressPostal format defines a single complex element named AddressPostal that holds a sequence of 11 simple elements, only some of which are required. An instance document has up to four possible namespaces. Here’s an example used throughout this article that contains three of those namespaces and the five required elements:

               Nærum Hovedgade            10            2850            Nærum   

Creating XForms in OpenOffice
The XForms in OpenOffice implementation focuses on simple forms that end users can design themselves. This article provides a limited example of how an end user could use OpenOffice’s design mode to build a form, including discussions of the XForms syntax, and common problems that users may encounter.

Figure 1. Creating a New XForms Document: The figure shows the menu command sequence for creating a new XML Form (XForms) document in OpenOffice Writer.

The first step is to create an XForms document. To do that, open a new instance of OpenOffice Writer and choose the menu path File ? New ? Xml Form Document (press Alt-f ? n ? x). You’ll see something similar to Figure 1.

Your newly-created XForm is a normal OpenOffice document, but accompanied by a set of form controls floating on the screen, probably in the upper left corner, as shown in Figure 2, and an open panel on the right side of the screen as shown in Figure 3.

Figure 2. OpenOffice Form Controls: After creating or opening an XML Forms document, you’ll see a Controls panel containing controls you can place on the form.

Figure 3. The XForms Model Panel: The Model panel shows your instance data.

If you don’t see the form control shown in Figure 2, you can enable it by following the menu path View ? Toolbars ? Form Controls.

When you initially create the XForm, the document will be in design mode; you can toggle design mode off and on by clicking the icon at the top right-hand corner of the form controls panel shown in Figure 2.

At this point you have an XForm with XML data inside of it. The document element of this XForms instance is the default instanceData element you can see in Figure 3.

Figure 4. Adding an Element: You add elements to your form’s instance data through the Add Element dialog.

Right click on instanceData in the Model panel, and choose add element. Doing so pops up a form resembling Figure 4.

Add the element AddressPostal. Notice that there’s no namespace associated with the element. That’s a problem, because you can easily create a malformed instance by using a name with a namespace prefix that has no corresponding namespace association. For example, if you entered xkom:AddressPostal in the name field, the dialog will not prompt you in any way to define the namespace to which the xkom prefix is bound.

The XForms Model panel (see Figure 3) has three tabs, named “Instance 1,” “Submissions,” and “Bindings.” Each tab has a number of icons beneath it, the middle one of which is an edit icon. In the “Instance 1” tab you can edit a selected element by choosing the middle “Edit Element” icon. Rather confusingly, to add namespaces to your instance you don’t choose the Edit Element icon in the first tab; instead, you add namespaces by editing a binding expression from either the Submissions or Bindings tab.

To do this, choose the “Bindings” tab, then the middle edit bindings icon, then the “Edit Binding Expression” button on the form that pops up. That pops up another form, where you choose “Edit Namespaces.” Finally, that form provides a list view where you can add namespaces and associate them with a prefix.

Figure 5 shows the forms that appear when you want to edit namespaces.

Figure 5. Adding Namespaces: You add namespaces to your instance via a roundabout sequence of steps to arrive at the “Namespaces for Forms” dialog.

As you can see, the UI has an inconvenient and counter-intuitive method for adding namespaces. For the example in this article, you won’t need to add namespaces or use that portion of the UI, but at least you now know how to get to the feature.

Adding Controls
Next, you’ll add a submission button to the form. Choose the Button control from the form controls panel, move to the designer, and draw a rectangle for the button, sizing it as you prefer. By default, the button will “snap” to the upper left corner of the document. If you don’t like the button placement, you can right click on it, choose Position and Size from the context menu, and change the anchor from “As Character” to one of the other available values.

Figure 6. Edit Submissions Form: On this form, enter an action, select a method, and give the submission a name.

The various ‘Position and Size” stylings are outside the purview of this article, but the “As Character” setting makes the form control part of the normal document flow; if you don’t really have other content in the document anchoring the form as character sets the field to be displayed at the document’s outer left margin.

Click the Submissions tab of the XForms Model panel on the right. The first icon in the panel is “Add Submission;” select that icon. The “Edit Submission” form that pops up looks like Figure 6.

Add a name of your choice, set the file action to be file:/// and enter a location where you want the file output to be saved in the file system. For example, in Windows you might choose file:///c:/xforms/Example2.xml. Next, set the method to be Put, and select “Document” for the Replace field so the submission will overwrite any existing document.

Now you have a place to submit a file and a button—you just need to bind the two. Right click on the button and select “Control” from the context menu.

Figure 7. Text Box Properties: These settings bind the XPath expression /instanceData/AddressPortal to the form model.

Add a text box so users can edit the element. Choose the text box icon from the forms control, and then click on the page and resize the control as desired.

Right-click on your text box and choose “Control.” Edit the properties so they match in the contents of Figure 7.

The Binding expression field is an XPath expression. When using XPath in XForms it is by default rooted on the document element of the to-be-generated output instance, which in this case is the default instanceData element used by OpenOffice. Therefore, the Binding expression field value in Figure 7 actually means the XPath selected will be /instanceData/AddressPortal. This convention is a bit of syntactical sugar, the benefit of which I’ve never understood.

If everything works so far, you should be able to turn off Design Mode, write Hello World in the text field and push your submit button. Assuming the folder exists that your file path references, you should see a new file appear containing the following XML:

                  Hello World        

While the preceding file format does not yet match the final target XML, it does provide an example of how editing the XForm can create an XML document.

XForms Syntax in OpenOffice
As you may have noticed from the UI, XForms in OpenOffice are analogous to the common MVC architecture: the Model is the XForm Model, the View is the rendered form fields, and the control is OpenOffice Forms. Note that the OpenOffice Forms Namespace abstractly describes a form and its properties—the actual forms input portion of the XForms specification is not implemented. This varies from the XHTML model of XForms, because there’s no clear analog to the Controller in that model.

You can look at the code that comprises the example form you designed earlier by extracting the document named Content.xml from your OpenOffice document using an unzip tool.

The document you’ll see is ordered into several sections: a styling section holding all document styles, the XForm section which contains our data, any XML Schemas, and submission information, a Form Controls section which holds the bindings between the actual Form fields and the XML, and the section holding the drawn controls themselves.

The following examples show the relevant XForm and bindings.

XForms Code for the Example Form
OpenOffice saved the data in the XForm as external XML when you saved the document. The form elements will use Binding 1 to track what form will be output where. The example shown below contains a Windows-specific file URI for the submission action; a corresponding Linux installation used file:///home/user/xforms/example3.xml.

                        Hello World                                       

Table 1 shows the XForms submission options:

The example in this article uses the File URI Scheme to define paths simply to avoid having to configure an HTTP server to receive XML for a tutorial. However, in my experience, the File URI scheme is inadequate for production work with OpenOffice, because it requires absolute paths and does not have graceful error handling when files are locked for editing.

A form element that uses the XForm binding shown earlier would look like Listing 1. The important parts of Listing 1 are the form:id attribute on the form:text element, which is the identifier that the text fields use to figure out the type of form input they hold, and the xforms:bind attribute, which declares that this form element binds to an XML element in the XForms instance using the xforms:bind element that has an id of StreetName.

Finally, the code draws the input field, using presentational markup that defines the display of the form field. Actual form elements are represented using the “draw” namespace.

The control is bound to the form input via the id reference used in the draw:control attribute. OpenOffice draws controls with absolute placement via the x, y coordinates—you cannot rely on OpenOffice to place a field automatically in document flow; the explicit coordinates are required.

Figure 8. Understanding Connections: The graph shows the relationships between controls, form items, and the XForms model.

You can understand the relationships between the various form elements most easily by moving from the rendered elements back to their connections via the Form Controls to the XForms element (see Figure 8).

Moving from left to right in Figure 8, the drawn control is bound to the abstract control in the form via the draw:control attribute. For example, the first control has a draw:control attribute value of control1. Note that control1 is the form:id of the button on the form.

Using the relationship information, you can now make an OpenOffice XForm without designing it as an end user. Instead, you can just write the markup directly.