File talk:OpenOfficeXMLExampleForm.odt

[[Image:|thumb|Figure 7: Instance data "tree" showing attributes and elements]][[Image:|thumb|Figure 8: XML data showing attributes and elements]]Using XForms and the OpenDocument format in OpenOffice.org and StarOffice By Valden Longhurst

Keywords: XForms, OpenDocument, OpenOffice.org, StarOffice, OASIS Open Office format, Instances, Submissions, Bindings, Form Controls, Models, Required, Relevant, Read-only, Constraint, Calculation, Data-type.

Abstract

This paper addresses the use of the W3C XForms standard in the OpenOffice.org office suite.

OpenOffice.org is a cousin to the StarOffice suite. They are both very versatile and standards compliant office suites. StarOffice was originally developed by StarDivision and acquired by Sun Microsystems in August 1999 who released the source code as open source calling it OpenOffice.org. After this source code was released, it gathered a large developer base. As of November 2008, OpenOffice.org supports over 45 languages and installs on a number of different computer operating systems.

The ISO/IEC standard OpenDocument format (ODF) is a generic file format for electronic office documents (such as spreadsheets, charts, presentations, word processing, and form documents). While the specifications were originally developed by Sun, the standard was embraced by the Open Office XML technical committee of the Organization for the Advancement of Structured Information Standards (OASIS) consortium and is now considered the base on which the XML format is structured.

The eXtensible Markup Language (XML) is a general-purpose specification for creating customized markup languages. It is extensible because it allows the user to define custom mark-up elements. XML's purpose is to aid information systems in sharing structured data as well as separate the data from the presentation of that data.

One component of XML in OpenOffice.org version 2.0 and beyond is the use of XForms. XForms with complex data can be processed locally while providing instant feedback to the user without sending or receiving data across a network connection. XForms may be saved to disk, submitted to the Internet, or even a file server. Selections made in XForms and saved to disk can latter be reopened with the user's selections still intact.

Another component of XML in OpenOffice.org version 2.0 is XML Path Language (XPath). XPath is a language for selecting elements from an XML document. In addition, XPath may be used to compute values (strings, numbers, or boolean values) from the content of an XML document.

Step-by-step instructions with explanations will be given on how one might set up a practical and useful XForm using XPath in the OpenOffice.org suite. Before showing how OpenOffice.org allows a user to graphically create XForms, a very quick and basic explanation of XML and XForms will be given to help the user with the fundamental concepts of what is happening under the graphical interface. If you are familiar with these concepts, then please feel free to skip them and go directly to the [#8.XForms and XPath in OpenOffice.org|outline XForms and XPath in OpenOffice.org] section.

Revision History

1. Original VersionValden Longhurst2009-02-13

Table of Contents

Abstract1

Revision History2

Credits4

Conventions/definitions used4

Why XForms4

What is XML5

The XForms Model7

The XPath Language9

XPath/XForms/XML/ODF => Huh?11

XForms and XPath in OpenOffice.org12

Objective12

XForms in OpenOffice.org12

Instance Data at Work16

Form Controls at Work20

Adding a text box20

Adding an option button21

Adding a date field22

Adding a time field23

Adding a formatted field23

Adding a combo box23

Adding checkboxes23

Adding a list box23

Adding a numeric field23

Bindings at Work24

Adding conditions27

Adding a required condition28

Adding a relevant condition28

Adding a constraint condition29

Adding a read-only condition30

Adding a calculation condition30

Submissions at Work31

Adding a web server submission32

Adding a local submission32

Conclusion33

Example XForm34

Endnotes37= Credits = There have been three key sources I have used for my education on how to use XForms in OpenOffice.org.

Lars Oppermann's paper titled “Using XForms in Office Applications” provides an excellent background understanding for this whole group of interrelated concepts. His paper helped solidify my novice understanding.

J. David Eisenberg's paper “XForms and OpenDocument in OpenOffice.org” gives clear instructions on using OpenOffice.org as the graphical front end design tool for XForm construction and was an impetus for this paper.

Finally, it would not have been possible to really glue together these almost ethereal concepts into a well-rounded idea of what is really possible without the huge amount of work by the World Wide Web Consortium. By making public their various standards, I was able to implement their world-wide work using one of my favorite office suites.

I must also include credit to Sun Microsystems for releasing the code of OpenOffice.org as open source. This has enabled me to really dig into finding out what is happening “under the hood” as well as offering sundry solutions for many client computers.

Notwithstanding all this, the OpenOffice.org Internet forums as a whole have also been very valuable in showing different ways to accomplish sundry tasks. Thanks to so many.

Conventions/definitions used

Throughout this paper you will come across a few words that have a unique context and syntax.

• When I speak of you, it represents the designer of the XForm. When I speak of the user, it represents the person who will latter use the XForm you designed.
• Occasionally, I have used the XML “<!--” and “-->” comment notation when I wanted to make a general comment and which is not to be literally typed into the XForm.
• I have used bold font when representing XPath expressions to help distinguish them from the surrounding text.
• I have also used the pipe (|) symbol to represent individual steps you should take when navigating OpenOffice.org's menu system.

Why XForms

Why would you consider taking your time to read about XForms and why would you want to invest any effort to learn this new technology?

There are a lot of reasons, some of which might apply to you and your situation. Then again, some reasons may not apply to you and you are better served elsewhere. However, XForms is not only very quickly being adopted in many, many disparate areas but also the supporters have increased their footprint over these last few years.

What’s more, as a W3C standard, you can deploy XForms with no royalty costs, you can implement XForms on a wide variety of platforms, and you can't be held hostage to any company’s whim. One key reason using this defined standard is important is because XForms separates the user interface and presentation from the data model and logic. Let's quickly look at some specifics.

XForms is not just for the Web and not just for HTML. It's certainly not just for classic desktop browsers like Firefox and Microsoft® Internet Explorer. XForms is designed to work well in many other environments: mobile phone browsers, audio browsers, and things that aren't browsers at all such as OpenOffice.org.

Let's say an office manager enters requisitions for office supplies into OpenOffice.org. OpenOffice.org can then search for the best prices for each item at OfficeMax, Staples, Office Depot, and Laser Monks before ordering. The office manager fills out a local form in OpenOffice.org which then submits this information to the store with the best price. For this scenario to work, the forms have to be accessible to other environments—not to only one proprietary software stack held by one company that can only run in one environment.

It's not surprising that the office manager might make mistakes in filling out this form. All too often, she has been asked to type her email address twice—just to be sure she didn't make a typo. Sound familiar? XForms can easily minimize these kind of mistakes using constraints.

Some constraints can be checked as the office manager types. If a particular input field is declared as a text field, then the OpenOffice.org might ignore any digit keys she presses. Furthermore, OpenOffice.org may also check the constraints before submitting her replies and alert her if it finds a violation.

There may be other reasons XForms would make sense for use in your environment. These will be discussed throughout this paper. Hopefully, those already provided will help you see the value of XForms.

What is XML

The eXtensible Markup Language (XML) is a specification for storing information of many types. XML also is a specification for describing the structure of this information. As information various so widely between different companies, clients, customers, end users, and books old and new, getting one specification to outline how information is stored and described is a big specification. Well . . . maybe not too big if you understand XML is simply a set of rules for defining custom-built methods for describing and storing your information in a way that can be easily extended.

XML is a generic framework for storing any amount of text or any data whose structure can be visually represented as a “tree.” The only indispensable syntactical requirement is that the document has exactly one root element (also known as the document node). Text must be enclosed between a root start-element and a corresponding end-element.

In the following XML example you see the root start-element <book> and the corresponding end-element </book>. Between these elements is the text.

<book>
    This is a book . . .
</book>

The root element can be preceded by an optional XML declaration element stating what XML version is in use (normally 1.0).

<?xml version="1.0" encoding="UTF-8" ?>
<book>
    This is a book . . .
</book>

In any meaningful application, additional markup is used to structure the contents of the XML document. The text enclosed by the root elements may contain an arbitrary number of XML elements. The basic syntax for one element is:

<element_name attribute_name="attribute_value">
    Element Content
</element_name>

Here,”Element Content” is some text which may again contain XML elements. You can see a generic XML document contains a tree-based data structure. Here is another example of a structured XML document:

<recipe name="bread" prep_time="5 mins" cook_time="3 hours">
    <title>
        Basic bread
    </title>
    <ingredient amount="8" unit="dL">
        Flour
    </ingredient>
    <ingredient amount="10" unit="grams">
        Yeast
    </ingredient>
    <ingredient amount="4" unit="dL" state="warm">
        Water
    </ingredient>
    <ingredient amount="1" unit="teaspoon">
        Salt
    </ingredient>
    <instructions>
        <step>
            Mix all ingredients together.
        </step>
        <step time="5" unit="minute">
            Knead thoroughly.
        </step>
        <step>
            Cover with a cloth.
        </step>
        <step>
            Knead again.
        </step>
        <step>
            Place in a bread baking tin.
        </step>
        <step>
            Cover with a cloth.
        </step>
        <step>
            Bake in the oven at 180 for 30 minutes.
        </step>
    </instructions>
</recipe>

An empty-element may contain attributes

<info author="John Smith" genre="science-fiction" date="2009-Jan-01" />

Element names are case-sensitive. For example, the following is a well-formed matching pair

<Step> . . . </Step> 

whereas these are not pairs

<Step> . . . </step> 
<STEP> . . . </step> 

XML is a language for storing and describing information. As was seen above with a bread recipe, XML can easily be extended and adapted to all kinds and types of information. You can use XML to design your own customized markup languages and then store your information. Because XML is text-based, easily parseable, free, and non-proprietary it can be used to share data between disparate systems and organizations.

So, XML allows one to easily describe and store information. What good is XML if its information is never presented in a meaningful way to anyone? This is the purpose of XForms.

The XForms Model

XForms (eXtensible markup language Forms) is a format and specification for presenting XML data using user interfaces. XForms was designed to be the next generation of HTML/XHTML forms, but is generic enough that it can also be used in a standalone manner to describe a user interface's presentation of that data.

XForms provides a clear separation of the data being collected from the controls (such as a list box menu) which are collecting the data. Not only does this separation provide greater transparency within the system as a whole, but it also enables XForms to be independent from the actual application (such as OpenOffice.org) presenting the data. This means one can read the data that was submitted using the OpenOffice.org application using a different application altogether.

Associating the XML data to individual form controls is done using XForms. For example, if you were creating a form that had a list box menu of different temperatures for baking break, then XForms would control which temperatures would be displayed as choices to your user. XForms would also be responsible for placing the user's choice into the XML data file. At times it is useful, even necessary at times, to set restrictions and conditions upon what the user sees and chooses. XForms is also responsible for these restrictions and conditions.

The XForms data structure to describe these responsibilities can be graphically depicted as shown in [#Frame1|frame Figure 1].

[[Image:|thumb|<center>Figure 1: The responsibilities between the Model, View, and Controller.]]</center>

Here are the three components of this data structure.

Controller

The controller manages the processed data in order to properly enforce restrictions and conditions to and from the Model. Restrictions and conditions might include various properties such as hiding text for sensitive data, ensuring data is read-only, allowing data to have single or multiple selections, and so forth. A logical example of a Controller is a password box showing stars instead of the actual password as the call out shows in [#Frame1|frame Figure 1].

View

Views are XForms controls for screen objects and can be placed directly in the form. The Model and View are bound together using reference or binding statements. These binding statements ensure Views are correctly updated when data in the Model changes. An example of a View screen object is shown as a call out in [#Frame1|frame Figure 1].

Model

XForms stores the model as XML data in an XML data file. It receives data manipulation information, transmission information, and association information from the Views and Controller. Please do not get this uppercase Model of the data structure confused with the lowercase model of the XForm. Unfortunately, the same word was chosen for two similar concepts. An example of a Model as XML data is shown as a call out in [#Frame1|frame Figure 1].

This 3-tier data structure eliminates almost entirely the need for any external scripting facilities because a vast number of relations between model and controller can be defined by View bindings.

So, XForms allows one to present and set restrictions and conditions upon XML data. It would sure be nice if you could point to and manipulate specific data under certain circumstances. This is the purpose of XPath.

The XPath Language

XPath (eXtensible Path language) makes it possible to refer to individual elements of an XML document. Up to this point I have been a little vague in defining “elements.” An element refers to a section of the XML tree framework. In the recipe example given above, one of the elements would be “instructions.” Another element would be “step.” Interestingly, in this example, “step” is a sub-element of “instructions.” In other words, “step” is a child element of the parent element “instructions.”

The “step” element can also have related attributes specific to that “step” such as the amount time to knead the dough. Then again, the “ingredient” element can also have a related attribute specific to that “ingredient” such as one teaspoon.

The XPath data structure to describe these elements and attributes can be graphically depicted as shown in [#Frame2|frame Figure 2]. Notice that each element is connected in some manner to the next element.

[[Image:|thumb|<center>Figure 2: XML Blocks of data]]</center>

Or, if it helps to visualize the framework of a tree, “step” is a leaf element of the branch “instructions” element of the “recipe” root element. Notice also that an attribute of a leaf could be “green,” or “brown,” or “dried.”

[[Image:|thumb|<center>Figure 3: Tree with its elements]]</center>

• What is an element of trunk? One is branches.
• What is an element of branches? One is leaves.
• What is an attribute of leaves? One might be green.
• What is an element of roots? One might be radicle.

Showing some actual XML at this time will assist in identifying how [#Frame2|frame Figure 2] and [#Frame3|frame Figure 3] fit into the XPath language.

<recipe name="bread" prep_time="5 mins" cook_time="3 hours">
    <title>
        Basic bread
    </title>
    <ingredient amount="1" unit="teaspoon">
        Salt
    </ingredient>
    <instructions>
        <step time="5" unit="minute">
            Knead thoroughly.
        </step>
    </instructions>
</recipe>

• What is an element of step? It is “Knead thoroughly.”
• What are attributes of step? There happen to be two, namely time and unit.
• What is an element of ingredient? It is “Salt.”
• What are attributes of ingredient? Again, there happen to be two, namely “amount” and “unit.”
• What are attributes of recipe? They are “name,” “prep_time,” and “cook_time” and, yet, these attributes have values.

Finally, in XPath we use the forward slash (/) character to designate each element of the tree. We use the at symbol (@) to designate each attribute. We can also use both of them together. We can also now ask questions relating to the XML of this example.

• How would you refer to the “instructions” element? You would call it by its location, namely /recipe/instructions
• How would you refer to the “ingredient” element? It would be /recipe/ingredient
• How would you refer to the entire recipe will all its sub-elements? It would be /recipe
• How would you refer to the “amount” attribute? It would be /recipe/ingredient/@amount

XPath expressions can refer to all or part of the text, data and values in XML elements, attributes, processing instructions, comments, and so forth. They can also access the names of elements and attributes.

XPath/XForms/XML/ODF => Huh?

In an effort to provide a good base to build upon, I began talking a lot about XPath, XForms, and XML. What is this new acronym O.D.F. and how does it fit into all this fine detail? Well, the OpenDocument Format (ODF) is the default file format for OpenOffice.org and is able to store XML, XForms, XPath, and more information in one self-contained file. In fact, the ODF format is XML data. If you were to look at the raw OpenOffice.org document you would see XML data. If you were to look at an OpenOffice.org XForms document you would see XPath data.

ODF does not use the entire feature set of XPath, XForms, and XML as these are large standards still being refined; however, there is enough support in ODF for OpenOffice.org to produce effective XForms.

XForms and XPath in OpenOffice.org

Objective

Let's take a step-by-step approach in designing an XForm document using the graphical user interface of OpenOffice.org. This will include most all the form controls offered in OpenOffice.org version 3.0 as well as all the XForm conditions offered in OpenOffice.org version 3.0. A final copy of our work will be available in the [#10.Example XForm|outline Example XForm] section of this paper.

Let's begin by saying you are tasked with building a form for the fictitious Professional Parties, Inc. It needs to include basic customer information, party information, possible guest information, and possible decorations and food selections. The customer should be able to fill in their information and either save it to their local computer with all information intact in one file or stream their information through the Internet to Professional Parties' Internet server. Oh, and also the customer needs to have some idea of what it will cost them as they fill out this form.

XForms in OpenOffice.org

Using the graphical user interface of OpenOffice.org you create a new XML forms document as shown in [#Frame4|frame Figure 4].

[[Image:|thumb|<center>Figure 4: OpenOffice.org's Menu For XML Forms]]</center>

When you create an XML Form document (XForms), you'll see the eight parts of the XForms model on the screen as shown in [#Frame5|frame Figure 5].

[[Image:|thumb|<center>Figure 5: OpenOffice.org GUI for XForms]]</center>

Reading from left to right they are

1. Form controls: The form controls allow the user to graphically manipulate data residing in the XForm (or more properly called instance data).
2. Instance data tab: The tab that shows the model's instance data.
3. Instance data: The graphical representation of the XML that will hold the data entered into the form controls.
4. Submission data tab: The tab that shows the model's method of transmitting the instance data.
5. Model select button: The button that allows you to select different models in the XForm.
6. Bindings data tab: The tab that shows the links between the Form Controls and the Instance Data.
7. Model edit/add/remove button: The button that allows you to manipulate more than one model in the XForm.
8. Instance edit/add button: The button that allows you to manipulate more than one instance in the XForm.

To visualize the correlation of these parts, please refer to [#Frame6|frame Figure 6]. An XForm may contain (but not require) these various parts to provide the user with a rich, interactive experience. Please do not confuse the lower case model(s) of XForms mentioned here with the uppercase Model of the data structure mentioned in [#5.The XForms Model|outline The XForms Model].

[[Image:|thumb|<center>Figure 6: XForm Graphical Representation]]</center>

I must acknowledge there are some areas where I believe OpenOffice.org could make it easier for you to develop XForm forms. One of these areas would be to allow the user to first graphically create a form and from that form simply drag controls into the Instance (circle ^#3 in [#Frame5|frame Figure 5]) window. As it stands now with OpenOffice.org version 3.0, it is easier to first layout the Instance data followed by the form controls. It is easier to take the database designer's approach by first taking the majority of your time to plan and lay out what you want to accomplish followed by actually building the user interface to comply with that plan and layout. We will first lay out the structured content and then lay the presentation on top of that.

Let's first begin by thinking about our various types of data (such as plain text, checkboxes, option buttons, list box menus, and so forth.) you would like to collect from the users of the XForms. You might also want to know what kind of conditions (such as required data, data which value is relevant to other data, read-only data, data constrained by other data, calculations based upon other data, and so forth.) you might want to place on the user. You would also think about how you are going to present this data (such as form hints, different fonts, various emphasis, location on the page, and so forth.) to the user. Maybe for the casual form it would not be cost productive to spend time thinking upon these detail; however, if you intend on using this form for the foreseeable future and provide feedback to the user, then you would come out ahead if you would take the time up front to think about these details.

Let's break the layout of our XForm into seven major sections: Basics, Party Information, Guest Information, Decorations, Food Information, Notes or Commentary, and Payment. Each section will have fields where the user can provide information. Here are a few examples of how you might organize our party form to help the user. It provides you with an idea of some details discussed above.

Form Section	User Description	Data Type	Defined Conditions	Data Presentation	Notes
Basics	Name	Any keyboard character (text box)	Required	At the top. Red, white, and blue fonts.	Provide a helpful note that these are required fields.
. . .
Party Information	Party Type	Only one selection out of our current two possibilities (option button)	Required	Near the top.
Party Information	Date	Only a date (date field)	Required	Near the top.
Party Information	Time of Day	Only time in a format everyone can understand. (time field)	Required	Near the top.	A list box selection would be nice.
Party Information	Duration	Any keyboard character (formatted field)	Required	Near the top.	Specifying using the word “hours” and also in tenths would be specific enough.
…
Guest Information	Accommodations	(Combo Box)			Allow the user some predefined selections yet allow them to type in their own as well.
. . .
Decorations	Specifically list all our current options.	Boolean Yes or No (checkbox)			Different decorations have different dollar values associated with them.
. . .
Food Information	Type of Food	Predefined text (list box)	Other boxes in this section are dependent upon this box.	Grey out other boxes in this section if Type of Food equals “None.”	All other boxes in this section are filled out only if Type of Food equals “None.”
. . .
Payment	Down Payment	Dollar amount (numeric field)	Must be greater or equal to zero.	At the bottom.
. . .

OK, now that you have all this information you are armed and dangerous. You have a good plan and know where you are going. Now you need to work on getting there.

Instance Data at Work

Ensure the form design toolbar is enabled (View > Toolbars > Form Design) and that its XML data navigator button is toggled on.

Let's begin to put these ideas together and build our XML instance data using the graphical user interface shown as circles ^#2 and ^#3 in [#Frame5|frame Figure 5]. This instance data relates to the Model in [#Frame1|frame Figure 1]. The instance data screen shown in [#Frame5|frame Figure 5] is a graphical representation of the actual XML data.

Open an OpenOffice.org XML document as shown in [#Frame4|frame Figure 4] by selecting File > New > XML Form Document. You should see the graphical interface you will use to build the XForm discussed in [#Frame6|frame Figure 6] . Notice that “Model 1” has its own Instance 1, Submissions, and Bindings tabs.

Remember, XML data allows for defining custom-built methods for describing and storing your information in a way that can be easily extended. You are free to rename models, instances, submissions, and bindings to whatever names you want.

Let's change the name of our first model from “Model 1” to “SetupForm.”

• Click the “Models” button
• Select “Rename”

When you change the instance name you will see something similar to [#Frame7|frame Figure 9]. I will call this the root element.

[[Image:|thumb|<center>Figure 9: Edit Instance dialog box]]</center>

By using the icons in the instance data area as shown in [#Frame12|frame Figure 7] create the instance data “tree.” Latter when you save or stream this instance data you will be saving or streaming an XML file as shown in [#Frame8|frame Figure 8]. When you add an element, it will be added as a child of the highlighted element. When you add an attribute, it will show with a preceding “@” sign. You do not need to type the “@” yourself. An example of an element having attributes is the decorations element of [#Frame8|frame Figure 7] and [#Frame12|frame Figure 8]. Let's walk through adding the elements and attributes discussed in the table above. Understand that at this point you are only setting up the XML “place holders” to hold the actual data to be typed in latter using form controls.

Lets begin populating the SetupForm root element with sub-elements and attributes that correspond with the table above.

Let's first add a sub-element to the root SetupForm element.

• Highlight SetupForm and left click the “add element” ([[Image:]]) icon where the Element Name = Basics

Now add a child element to the Basics element just created.

• Highlight Basics and left click the “add element” icon where Element Name = Name

Its default value you don't care about now as you are only setting up “place holders.” Referring back to the first row of our table above, you can see that this element is the person's name under the Basics section.

OK, you have now specified a root element called “SetupForm” with one child element called “Basics” and one sub-element called “Name.” You have just completed setting up two elements. You may want to now add the sub-elements Address, City, Phone, State, and Zip in like manner.

Now populate the root element “SetupForm” with another element that corresponds to the table above. Let's take the next example in the table which is Party Type under the Party Information section.

First add the “PartyInformation” sub-element to the root SetupForm element.

• Highlight SetupForm and left click the “add element” icon where the Element Name = PartyInformation

Now add a child element to the PartyInformation element just created.

• Highlight PartyInformation and left click the “add element” icon where Element Name = PartyType

OK, You have now specified another sub-element which hold the data you will latter give it. You may want to now add additional sub-elements such as Site, Date, TimeOfDay, Duration, and Occasion.

As you do this for each element you will create place holders for all your data you will be collecting latter.

But what about attributes? Let's take a closer look at an element that has attributes. The decorations section contains elements that have attributes. These attributes are for specific decorations such as what price will be charged, whether or not the user selected this decoration, and what unique id this decoration might have.

Once you create the Decoration sub-elements (such as Balloons, Favors, Streamers, Signs, Candles) as described above, you would add individual attributes to them.

• Highlight Balloons and left click the “add attribute” ([[Image:]]) icon where the attribute Name = price
• Highlight Balloons and left click the “add attribute” icon where the attribute Name = selected
• Highlight Balloons and left click the “add attribute” icon where the attribute Name = id

Continue to create elements and attributes ad infinitum (oops, did I say that?) until you have place holders for all your data you are going to collect. Once you have place holders, you are ready to create the form controls that supply the user an entry point for each of the place holders.

It should be noted that once you have created your instance data in OpenOffice.org you may then drag from the instance data window and drop into your XForm document. This currently works for simple forms where your fields are mostly text fields. However, for more complex forms, use form controls as described below.

Form Controls at Work

Ensure the form controls toolbar is enabled (View > Toolbars > Form Control) and that its form design mode is toggled on.

Different form controls have different capabilities. Generally speaking, these capabilities are specific to the application you are using (such as OpenOffice.org). These form controls relate to the View in [#Frame1|frame Figure 1]. Furthermore, these specific form control capabilities in this section are not specific to XForms but to OpenOffice.org's ODT file capabilities.

Another item to be aware of is how OpenOffice.org allows the use of different form control anchorings. Each anchoring also has different capabilities. You will want to anchor form controls according to your personal preference.

One last item to remember. Each form control has its own label field which you may or may not want to use. I will not be using them in this paper. Our “labels” will be part of the XForm document proper and not part of the XForm form control.

Start to build the form controls by first typing the word “Name” in the XForm document proper. Next you will create a text box that is associated with “Name.”

[[Image:|thumb|Figure 10: Form Control toolbar (textbox highlighted)]]Adding a text box

Within the form controls toolbar

• Left click on the text box icon (see [#Frame9|frame Figure 10]).
• [[Image:|thumb|Figure 11: Text box properties dialog—General tab]]Go to the XForm and click and drag the text box to the dimensions you choose.

Once the text box is in the XForm, you can adjust its different capabilities. To anchor this text box as a character, you would

• Right-click the text box
• Select anchor
• Select “as character”

Let's adjust some of the properties specific to text boxes.

• Double left click the text box

This brings up a window similar to [#Frame10|frame Figure 11].

The General tab shows the general properties for a text box. Notice you can change the tab order (what order this text box will receive focus when tabbing between different form fields), font (size, color, effects, and so forth.), text alignment, text type (single line, multi-line with formatting, and so forth.), and provide help text (mouse hovering shows specific text).

This can provide helpful feedback information to the user. For our Name box you might want to have the help text read “First name and last name please.”

Continue to type text in the XForm and add associated text boxes to your document as needed.

At one point you will come across the need for the user to choose either one option or another option but not both.

Adding an option button

In our XForm and according to the table above, the PartyType would need to have at least two possible choices.

Option buttons allow the user to select one option out of a set of possibilities. Within the form controls toolbar

• Left click on the option button icon
• Go to the XForm and click and drag the option button to the dimensions you choose

[[Image:|thumb|Figure 12: Option box properties dialog--General tab]]Once the option button is in the XForm, you can adjust its different capabilities. Let's adjust some of the properties specific to option buttons.

• Double left click the option button

Notice something similar to [#Frame11|frame Figure 12] comes up.

The Style, Alignment, and Default status are probably of most interest for our type of XForm. It is possible to have one option selected by default if that is what you choose.

• Go ahead and insert another option button as you want at least two options for PartyType.

[[Image:|thumb|Figure 13: Date field box properties dialog—General tab]]Bindings (discussed latter) limit when only one option out of the various option buttons can be chose at any given time. In order to “connect” a group of option buttons so only one can be chosen at a time, you will set all of them to have the same binding expression.

Adding a date field

Date fields allow the user to easily enter a date in a standard format. Within the form controls toolbar

• Left click on the date field icon

• Go to the XForm and click and drag the date field button to the dimensions you choose

If the strict format is Yes, then the user is required to use only the date format specified below. The date format can be set as shown is [#Frame14|frame Figure 13].

The spin button option allows the user to cycle through the date one at a time and the list box option allows the user to view a calendar from which to choose the date.

Adding a time field

Time fields allow the user to easily enter a time in a standard format. Within the form controls toolbar

• Left click on the time field icon

• Go to the XForm and click and drag the time field button to the dimensions you choose

It has similar options to the date field but related to time.

Adding a formatted field

Formatted fields allow the user to enter text in a certain predefined format. Within the form controls toolbar

• Left click on the formatted field icon

There is a wide range of options on how text can be represented using various format codes. One quick example is the format code #.0" hours". This will allow the user to type any number, then one decimal place, then one more number. If the user were to simply type “13.52” into this formatted field, then OpenOffice.org would translate that into “13.5 hours” More information about format codes is available in the OpenOffice.org help pages.

Adding a combo box

Combo boxes allow the user to either select an entry from a populated list or manually type in another option of their choosing. In our example XForm and according to the table above, the Accommodations would need a combo box.

Adding checkboxes

checkboxes allow the user to easily check off what they want from a provided list. In the checkbox properties dialog, you can specify the values for what “on” and “off” mean. Typically, these values are “1” or “Y” for “on” and “0” or “N” for “off.” The Decorations section of our example XForm provides an example of when you might use checkboxes.

Adding a list box

List boxes allow the user to select only one or multiple items from a predefined list of entries. The listed entries can come from either the form control or the XForms model. In keeping with our XForms purpose, you will latter create these entries using another XForms model within the same XForm.

Adding a numeric field

Numeric fields allow the user to type numbers and for them to be formatted in an aesthetic way. Our example XForm shows a numeric field being used to capture the user's down payment entry.

Continue to create form controls until you have entry points for all your data you will collect.

Once you have entry points and place holders, you are ready to create the link between the two. In our next section your previous work begins to pay dividends and you begin to see the value of XForms.

Bindings at Work

After setting up the preliminary form controls and instance data you are now ready to bind together the various form controls and the corresponding instance data. In other words, the binding is the critical link between the XForm's form data and the XForm's XML data. Bindings relate both to the Model and to the Controller in [#Frame1|frame Figure 1].

• Left click the Bindings tab (circle ^#6 in [#Frame5|frame Figure 5]) in the XML data navigator.

Let's first add a binding to the Name sub-element of the Basic sub-element. We shall use XPath notation and write it as Basics/Name.

• Left click the “add binding” ([[Image:]]) icon where the binding Name = Basics_Name and binding expression = Basics/Name

Remember that you are free to name models, instances, submissions, and bindings to whatever names you want; however, the binding expression is not arbitrary but is a valid XPath expression.

Now add the data link between the form control (text box in this case) and the instance data via the binding just created.

• Double left click the Name text box in the XForm
• Left clicking the Data tab

[[Image:|thumb|Figure 14: Text box properties dialog—Data tab]]This brings up a windows similar to [#Frame13|frame Figure 14].

You can see a variety of options available to us. Not all of them we are concerned with at this time. You may want more than one enabled, but that will depend upon your conditions in your table.

The Events tab is for even more functionality such as handling specific events (when mouse enters the text box, when a key is pressed in the text box, when text is modified in the text box, and so forth.) through macro programming. I will not go into this topic in this paper.

• Click the XML data model list box and select SetupForm
• Click the Binding list box and select Basics_Name

Referring back to the first row of our table above, you can see that your decision was to require the user to populate this entry. You need to specify that it is required.

• Type the valid XPath function “true()” into the Required field if it is not already there

OK, you have specified that the binding belongs to the SetupForm model which will store the Name data in this model. You have specified in XML a binding called “Basics_Name.” You have specified that the Name element is required to be filled in when a user completes the form. You have also specified in our XForm to what element our Name form control is bound. [#Frame15|frame Figure 15] shows our completed binding.

[[Image:|thumb|Figure 15: Dialog box—Our binding control]]You have just completed you first binding. You may want to now add other bindings in like manner.

Now, there is one last item to cover in bindings. You want to be able to use the XForms model to produce its own list box entries. You will do this by creating a new XForms model. The entries will come from elements that have attributes in this new model.

Our Type of Food in our table would be a good example to work with.

First add the new model

• Click the models button (circle ^#7 in [#Frame5|frame Figure 5]. and select “Add”

Name the model something that makes sense

• Model Name = TypeOfFood

Create instance data that has various elements by the same name.

• Highlight “instanceData”
• Click on the Edit element icon ([[Image:]]) and rename it to something that makes sense, say TypeOfFoodList
• Highlight TypeOfFoodList and click the add element icon
• Add sub-elements that each have the same name, say “Food”
• [[Image:|thumb|Figure 16: Dialog box--A new model for a list box]]Add unique attributes, say “type,” to each of the elements

You may want to refer to [#Frame25|frame Figure 16].

Values for the @type attributes might be Breakfast, Lunch, Dinner, and so forth. These attributes will be what populate the list box entires.

OK, you have now created two models within our XForm. You can now return to the XForm to complete our list box.

• Double left click the list box

This brings up a window similar to [#Frame16|frame Figure 17].

• [[Image:|thumb|Figure 17: List box properties dialog box—data tab]]Change the list entry source to point to the correct model with the elements and attributes

• List entry source = <!-- What you see is the full path to the attributes -->

Notice the XML data model is set to SetupForm. You want to use this model if you want the selected value to be saved as part of the SetupForm instance data. The Binding expression should also indicate you want the selected value to be saved as part of the SetupForm instance data.

• XML data model = SetupForm
• Binding expression = FoodInformation/TypeOfFood

Continue to create as many models as you need inside your XForm for your various list boxes. Again, the listed entries can come from either the form control or the XForms model. I have shown how to use the XForms model to create list box entries.

Let's turn our attention to the power of conditions in our XForms.

Adding conditions

Setting conditions allow instant feedback in a variety of ways to the user. Some might be to inform them whether they are filling out the form as they should, to perform calculations for them, to automatically skip content-sensitive or irrelevant fields, and so forth. Some conditions might be a combination of these. In essence, the conditions create value for the user as they are guided in completing your form as well as for you when you get the data your thought you were requesting.

You can create these conditions without having to learn another programming language (such as Java, JavaScript, Perl, Ruby, and so forth.) but by using the simpler and more natural XPath language. In fact, if you have read [#6.The XPath Language|outline The XPath Language] section then you already know how to use XPath.

The conditions found in XForms that allow instant feedback to the user are as follows:

• Required: A form may require certain values and this requirement may be dependent upon other values in the form. The user is informed if the required condition is not met.
• Relevant: Many forms have data entry sections who's value depend upon other values or sections. The user is alerted through section visibility, focus, and navigation order if one section is relevant to another section.
• Read-only: A form may have values that should not be directly modifiable by the user but may be modifiable due to the conditions of other modifiable sections.
• Constraint: Many forms have data entry sections who's value should be constrained to only a certain range, type, or value. The user is alerted to which sections have unfulfilled constraints and told what constraint was imposed.
• Calculation: A form may have sections who's value is computed from other values the user may or may not have provided.
• Data type: The user can be told what data type (number, letter, date, time, and so forth.) is expected.

Conditions are not limited to the control which they are bound to. They can include XPath references to all parts of the data instance. A calculation may sum the values from individual elements or attributes. A constraint may be dependent on any number of elements or attributes.

The XForms library includes the entire XPath 1.0 core function library. This includes operations on elements, attributes, strings, numbers, and booleans as well as other extension functions specifically designed for forms.

[[Image:|thumb|Figure 18: Required condition dialog box]]Let's consider some specific examples for each condition. You should reference our above table again to determine which conditions need to be applied.

Adding a required condition

The Name under the Basics section has a required condition. You would first select the correct model and binding for this.

• Select SetupForm model using the model select button (circle ^#5 in [#Frame5|frame Figure 5])
• Left click the Bindings tab (circle ^#6 in [#Frame5|frame Figure 5])
• Select the correct binding by left clicking the Basics/Name binding
• Left click the Edit Binding icon

You have now selected the correct model and binding for the Name. Now specify the required condition for this binding.

• Toggle “on” the Required checkbox under the settings section

You are finished specifying that the Name is required when the user fills out this form. Please see [#Frame17|frame Figure 18] for an example of how this might look.

If you want, you could look at the XPath condition to see it uses the simple true() function to designate this entry is truly required.

Adding a relevant condition

[[Image:|thumb|Figure 19: Relevant condition dialog box]]Let's now consider making all the entries in the Food Information section relevant to what the user chooses for TypeOfFood under that same section.

Specifically, if the user selects “None” for the TypeOfFood, then all entries in this “Food Information” section are irrelevant and the user should be able to simply skip the rest of this section when filling out the XForm.

Let's say you want to add a relevant condition to Served under the “Food Information” section.

• Select the binding associated with Served
• Left click the Edit Binding icon
• Toggle on the Relevant checkbox under the settings section

This should bring up a window similar to [#Frame18|frame Figure 19]. You now want to specify how Served is relevant.

• [[Image:|thumb|Figure 20: Relevant condition in an XPath expression]]Click the Relevant Condition button

This should bring up a window similar to [#Frame19|frame Figure 20]. Here you see an XPath expression along with the current result of that expression (which happens to be false).

In English, this XPath expression says that if the TypeOfFood element of the FoodInformation element of the SetupForm element is not equal to the word “None,” then this entry is irrelevant. OpenOffice.org will just skip it when the user fills out the form.

You will notice that Served is not only relevant to what value TypeOfFood has but also that Served is required. However, if TypeOfFood is set to “None,” then both conditions work together and Served is no longer required.

Adding a constraint condition

Let's now consider the constraint condition. One practical expectation would be for the user to not provide a down payment with a negative value. Let's constrain this down payment to be greater or equal to zero.

Just like the other constraints, you then want to select the binding associated with the Down Payment (also called installment payment in our example XForm).

• [[Image:|thumb|Figure 21: Constraint condition in an XPath expression]]Select the binding associated with the InstallmentPayment
• Left click the Edit Binding icon
• Toggle on the Constraint checkbox
• Click the Constraint condition button

This should bring up a window similar to [#Frame20|frame Figure 21]. Here you see an XPath expression along with the current result of that expression (which happens to be true).

In English, this XPath expression says that if the Installment element of the Payment element of the SetupForm element is greater or equal to zero, then this entry is valid. Because this entry is valid, the user will not be alerted in any way that there is a conditional problem.

Adding a read-only condition

Setting up the read-only condition is done in the same way as was the required condition. However, in OpenOffice.org version 3.0, it appears to also need the help of <!-- tongueincheek --> the read-only form control <!-- /tongueincheek -->.

[[Image:|thumb|Figure 22: Calculation condition using simple operands in an XPath expression]]An example of a read-only condition in our XForm would be our Payment/BaseFee condition.

Adding a calculation condition

Just like all other conditions, the calculation condition uses XPath expressions. You are free to use operations as well as XPath functions. I will show examples of both.

[[Image:|thumb|Figure 23: Calculation condition using a function in an XPath expression]][#Frame21|frame Figure 22] shows operations being used with XPath expressions. Notice that the XPath expression is simple and natural . . . like how you would write a simple math expression.

Notice also that the result for the expression is provided for you. At this moment, the value happens to be “67.”

By saying simple in the above sentence, don't let that fool you into thinking XPath can't express more complex calculations. Our second example using [#Frame22|frame Figure 23] shows the count() function being used with XPath expressions.

Here you are counting ALL the Decorations elements who's selected attributes are set to the “true” value. You are counting how many decorations were selected.

In XPath, square brackets are called predicates and can compare values, test for existence, do math, and more.

Bindings provide the link between form controls and the corresponding instance data. By using conditions in our bindings, our design work begins to pay dividends. Our XForms become practical with rich user experiences.

I have talked about creating place holders for data, creating controls for data entry, and binding of data with possible conditions. However, what good is all this if you can not submit the gathered data using various methods.

Submissions at Work

After gathering data from the user, you want to be able to submit it using various methods. You might choose to submit all data to a file on the local disk, to the Internet, or to a file server. You might also feel a need to submit only part of the data to these locations. The submission process relates to the Controller in [#Frame1|frame Figure 1].

[[Image:|thumb|Figure 24: Add submission dialog box]]First, some basic information about submissions.

• Click the the submissions tab (circle ^#4 in [#Frame5|frame Figure 5])
• Left click the Add Submission icon

This should bring up a window similar to [#Frame23|frame Figure 24]. Let me explain.

The Name box

This can be any name you choose.

The Action box

This is any valid URI as defined by the W3C technical architecture group. Unfortunately, OpenOffice.org version 3.0 does not seem to work with the mailto: URI.

The Method list box

This provides the user with choices on different methods for saving the instance data.

The Binding expression box

The XPath expression that selects the elements to include in the submission. In our example if you wanted to include just the Basics section data, the expression would be /SetupForm/Basics.

The Binding box

This allows the user to select an existing binding to which this submission it to be assigned.

The Replace list box

This selects the action to be taken after the submission has been executed. If the action box was set to submit to a server, then the server's reply could either replace the whole document that is including the submitted form or it could replace all or part of the data instance that is associated with the form—allowing for the representation of the result withing the current form. Again, here we see practical XForms uses which provide rich user experiences.

Let's add two submissions to the form. One will stream the complete instance data to a web server and the other will save a portion of the instance data to a local disk for either archiving or possible further processing.

Adding a web server submission

• Open a submission dialog box as indicated above
• Set the Name = SubmitData
• Set the Action = http://www.example.org/cgi-bin/process.pl
• Set the Method = Post as most servers will want to receive using this method.
• Set Binding expression = / so all elements (from the root element on down) are submitted. You could also leave this blank which would default to /.
• Set Binding = <!-- NULL --> as it doesn't matter with this example.
• Replace = None as you don't want to replace any XForm data in our document after the server's reply.

You have configured a submission that will stream data the user provided in the XForm out into the Internet to the server http://www.example.com. It is up the the server at http://www.example.com to process the data and provide any response it may want to.

Adding a local submission

• Open a submission dialog box as indicated above
• Set the Name = SaveData
• Set the Action = file:///tmp/PartyFormXMLData.xml
• Set the Method = Put as you are saving to a local hard drive.
• Set Binding expression = /SetupForm/Basics so only some elements (from the /SetupForm/Basics element on down) are submitted.
• Set Binding = <!-- NULL --> as it doesn't matter with this example.
• Replace = None as you don't want to replace any XForm data in our document.

[[Image:|thumb|Figure 25: Button properties dialog box]]You have configured a submission that will save a portion of the data which a user provided in the XForm to the local disk.

Adding a button in the XForm to work with submissions is accomplished as described in the [#8.4.Form Controls at Work|outline Form Controls at Work] section.

• Left click on the push button icon
• Go to the XForm and click and drag the push button to the dimensions you choose.
• Double left click the push button
• Left click the General tab

There are various options available but only two related to the submission.

• Action = Submit Form
• Submission = SaveData

You now have a button in the XForm that is associated with this submission. An example of what it might look like is shown in [#Frame24|frame Figure 25].

After you have created and finalized your form, make sure you disable edit mode and turn off the XML data navigator as discussed in the [#8.3.Instance Data at Work|outline Instance Data at Work] section.

Conclusion

Congratulations! You made it through thus far . . . if you are not one of those readers that cheats and skips to the end chapter. :-)

Hopefully these instructions and explanations have been helpful in showing you how to use OpenOffice.org to create XForms using the extensibility of XML. You saw how forms with both simple and complex data can be locally processed using XPath to provide instance feedback to the user without sending or receiving data across a network connection. These forms may be saved to disk, submitted to the Internet, or even a file server. These forms can latter be reopened with the previously selected data still intact.

Example XForm

File:Redrulr5.gifBasics

Name Phone

Address

City State Zip

Party Information

Occasion

Party Type Date

Site Time of Day

Duration

Guest Information

Number of Guests Type of Guest

Time of Arrival Accommodations

Listed accommodations are only suggestions.

Please feel free to type in your own.

Decorations

File:Redrulr5.gifFood Information

Type of Food Provided by

Served Restrictions

Paid for by

Notes or Commentary

File:Redrulr5.gifPayment Installment Payment:

Party Decorations (selected):

Base Party Fee:

Remaining Balance:

Order Number:

Special Notes: == Alphabetical Index ==

Action box31

attributes9

Binding box32

Binding expression26

Binding expression box31

Bindings24

Bindings data tab13

Calculation27

calculation condition30

case-sensitive7

checkboxes23

child element9

combo box23

conditions27

Constraint27

constraint condition29

Controller8

Data tab24

Data type27

date field22

element6, 9

Events tab24

Form controls13

Form Controls20

formatted field23

functions27

General tab21

Instance button13

Instance data13

Instance Data16

Instance data tab13

J. David Eisenberg4

Lars Oppermann4

list box23

local submission32

Method list box31

Model9

Model button13

Model select button13

Name box31

numeric field23

ODF11

option button21

parent element9

predicates31

Read-only27

read-only condition30

Relevant27

relevant condition28

Replace list box32

Required27

required condition28

square brackets31

Submission data tab13

Submissions31

sum27

Sun Microsystems4

text box20

time field23

true()25, 28

View9

web server submission32

World Wide Web Consortium4

XForms7

XML5

XPath9

@11

/11

<!4

|4= Endnotes =

---