Itâs easy to dismiss any forms technology as simply moving paper forms to a computer screen. However, the truth is that IBM Workplace Forms provides far more value to the enterprise. Yes, the paper form is translated into an online equivalent, but thatâs only the beginning.
Workplace Forms features internal logic and internal data models. Business rules are encapsulated within the logic, preventing users from inputting incorrect information and even guiding the user through the form-filling process by turning portions of the form on and off as required. At the same time, the internal data model eases integration. The data model is a singly rooted XML fragment that can follow any schema or standard as long as itâs well-formed XML. This means that data can be moved directly from an XML database, or other XML system, into a Workplace Forms form and back again.
This article assumes no previous knowledge of Workplace Forms. If, however, you want to follow along as we build a sample form, install IBM Workplace Forms Designer V2.6.1 and IBM Workplace Forms Viewer V2.6.1. Trial versions of Workplace Forms Designer and Viewer are available from developerWorks.
When creating a new form, you must first decide whether to follow a form-centric or data-centric design method. For instance, if you convert paper forms, you want to use a form-centric method by which you first reproduce the look of the form, and then design a data model to match. On the other hand, if youâre starting with a data set, such as fields that must be completed in a database, start by designing the data model first, and then create the form layout. Workplace Forms Designer includes features that can help with either approach.
In this article, we use a data-centric approach. We start with a schema that defines the required data set, create a data model to reflect that schema, and then design a form that consumes that data model. To do this, we follow these steps:
- Create a new XForms form.
- Create an XForms data instance.
- Create labels.
- Create input controls.
- Align items.
- Create an XForms table.
- Set up calculations for the table.
- Add an image to a button.
- Create an XForms submission.
- Set up data constraints.
- Create localized forms.
To create a new Workplace Forms form, follow these steps:
- In Workplace Forms Designer, click the Workbench icon to open the Designer perspective.
- Right-click a project in the Navigator view (create a new one if there is no existing project), and then choose New - New Workplace Form. The New Workplace Form dialog box opens (see figure 1). Notice that the FormsProject folder is selected by default.
- In the File name field, type PurchaseOrder, and then click Next.
Figure 1. New Workplace Form dialog box
- The Choose Template dialog box opens (see figure 2), in which you can choose a template for the form. Templates provide a starting point for the form. There are a variety of templates available, and after you select a template to start with, you can make any changes you like, including changing the appearance of the template itself.
- For this article, we start with a completely blank form and create the entire design ourselves. Select the Default Empty Form â XForms template, and then click Finish.
Figure 2. Choose Template dialog box
You now have a blank canvas on which to create your form. In the XForms view, there is a model (see figure 3) that stores all the data in the form (like a mini-database). The model is automatically created when you select the XForms template.
Figure 3. XForms model

TIP: You can convert a standard XFDL form without XForms to a form with XForms support by adding a model in the XForms view. To add the XForms model to an XFDL form, go to the XForms view, right-click No Model Exists, and choose Add XForms Support.
Creating an XForms data instance
The XForms model arranges data into data instances, which are logical groupings of data within the form. For example, if the form is to integrate with two backend systems, you may create two instances, each one specific to a particular system.
Each data model must contain one or more data instances. The Instance view has four button commands that you can use to create an instance as shown in table 1.
Table 1. Instance icons
![]() | Create an instance from the current document. Generates an instance based on the items already added to the form. |
![]() | Create an empty instance. Creates an empty data instance. |
![]() | Create an instance from a schema. Creates a data instance from an enclosed schema. The data instance is based on the schema and conforms to the layout dictated by the schema. |
![]() | Create an instance from a WSDL message. Creates a data instance from a Web Services Description Language (WSDL) message. |
In this case, we show you how to create a data instance from a schema. This not only creates a data instance that matches the schema, but also creates an instance that validates user input against the schema as the user completes the form. To do this, follow these steps:
- In the Enclosures view, expand the Schema option.
- Right-click Model:Default, and then choose Enclose Schema File.
- Browse to the directory containing the schema file (a sample schema called purchaseOrder.xsd is provided in the Download section of this article), and then click Open. In the Enclosures view, you can see that a schema has been enclosed (see figure 4).
Figure 4. Schema file in the model
- In the Instance view, click the XSD icon to generate an instance from the schema (see table 1 for icon).
- Select the root <instance> node in the Instance view (see figure 5). Notice that its properties are displayed in the Properties view. In this view, change the ID to poInstance.
TIP: After you generate the data instance from the schema, you cannot use the Instance view to modify that instance. This is intentional so that you do not accidentally change the instance in a way that contradicts the schema. However, if you need to make a change, you can do so in the Source view. This is useful if you want to add sample data to the instance, for example.
Figure 5. New instance created from schema
Labels are used to display titles and instructions on the form. They never take input and never receive the focus when the user is filling out the form. There are two styles of labels in Workplace Forms:
- Label item. This is a separate widget on the form similar to a field or to a pop-up list.
- Label property. You can think of these as built-in labels that you can add to the top-left portion of any widget, such as a field or check box.
In general, the separate label items are used more often because they can appear anywhere in relation to other items on the form; they are not limited to the top-left portion of the item.
There are two kinds of label items: XFDL labels and XForms labels. The only difference between them is that XForms labels are linked to the data model and get their content from a node in data instance.
In our form, we begin by using XFDL label items as follows:
- In the Standard Library palette, click the drop-down button beside Label (Output) and select Label (Non-XForms).
- Click the canvas to add a label.
- Double-click the label on the canvas and change its value to Make Purchase Order.
- In the Properties view, expand the Appearance section (see figure 6) and change the following settings:
- Set fontinfo to 12 pt Arial (bold) by clicking the ". . ." button and by completing the dialog box that opens.
- Set fontcolor to the hex value #006699 by typing that value into the field.
TIP: In the Properties view, properties that have been modified are indicated by a blue circle (see figure 6). You can click the blue circle to reset a property to its default value, which is indicated by a white circle.
Figure 6. Change appearance of the label
NOTE: You can specify a color using the colorâs name, its RGB triplet, or the hex value for the color. The transparent color means that no color is specified and that it is the same as the pageâs background color.
- Add the Store Information, Supplier Information, and Items for Purchase labels on the canvas as shown in figure 7. Select each label on the canvas, drag the edges to resize the item, and change their appearance settings in the Properties view as follows:
- Set justify to center.
- Set fontinfo to 10 pt Arial (bold).
- Set fontcolor to white.
- Set bgcolor to the hex value #8080FF.
Figure 7. Labels in the form
TIP: You can use the copy and paste features to create labels in the same style (font color, background color, and font size). For example, you may set up the Store Information label and copy it to make Supplier Information and Items for Purchase labels. After that, you need only change their value and size.
Fields are one of the items that are used to collect input from the user. They receive focus when the user fills out the form, and the user typically enters data into them.
There are several types of fields available in Workplace Forms Designer. The first three are linked to the data model and appear only in XForms forms, while the last can appear in both XForms forms and XFDL forms:
- Input. Takes a single line of input.
- TextArea. Takes two or more lines of input. This is used only with XForms.
- Secret. Works like a password field. All characters typed into the field are masked with a single character, such as an asterisk (*). This is used only with XForms.
- Non-XForms. This is a standard XFDL field. It can act like any of the previous field types, but cannot be linked to the XForms data model.
There are also two ways to create fields. If you create a form-centric design, you can add fields to the form by clicking the Field button on the palette. However, if you create a data-centric design, you can drag a data element from the Instance view onto the palette. Workplace Forms Designer automatically creates an Input field to represent that data element.
Because you are creating a data-centric design, drag from the data model as follows:
- From the Instance view, open the <store> node and drag the <id> node onto the canvas. This creates a field with a matching label on the design canvas and automatically binds the field to the <id> node in the instance.
- Click the Date field on the canvas and examine the Properties view. When you expand the XForms (input) section, you see that the ref uses an XPath expression to point to the id element in the data instance (see figure 8).
Figure 8. Use XPath expression to bind input field with data instance
- Click the Date field on the canvas and examine the Instance view. If you click the "Show bound instance elements" button in the toolbar, the number one appears in parentheses beside the <id> node, meaning that this node is bound to one item on the canvas.
TIP: You may also use the menu command View - Highlight Items with XForms Binds or the "Highlight Items with XForms Binds" button in the main toolbar of Workplace Forms Designer to highlight XForms items that are associated with data instance elements. This button is a three-way switch; it highlights items that are bound to the data model, items that are not bound to the data model, or no items.
- Repeat the previous steps for the following data elements:
- The other elements under <store>
- All elements under <supplier>
- The <totalPrice> element
- Press the Ctrl key and select the labels before the Input fields on the canvas. In the Properties view, change the fontinfo property to 8 pt Arial (bold).
- Resize the fields to proper size. After you are done, your form should look similar to figure 9.
Figure 9. Input fields in the form
You can drag and drop any of the items already placed on the form to move them around. However, it can still be difficult to line things up correctly if you eyeball them. Workplace Forms Designer includes a group of alignment tools to help you line up items on the form.
There are two types of alignment:
- Absolute alignment. Places items in set locations on the page. This type of positioning uses an x,y coordinate system to specify where the item should be placed. Use absolute positioning if your form layout will not change based on user input.
- Relative alignment. Places items on the form relative to another anchor item rather than at absolute positions. When you move the anchor item, all the items that are positioned relative to it also move. Use relative positioning if your form is going to be quite dynamic. For instance, items placed after tables often require relative positioning because the user can often add rows to the table and make it longer.
Absolute alignment is easier to work with and should be your default choice. Relative alignment is more difficult to work with because it depends upon the build order of the form. The build order is the order in which items appear in the Outline view of the form (which reflects the order of the items in the XFDL source code of the form). Items can only be relatively aligned to anchor items that appear before them in the build order.
Because absolute alignment is fairly straightforward, we use relative alignment here so that you can get a better feel for it:
- Click the Store Information label on the canvas, press the Ctrl key, and then click the Make Purchase Order label.
Both items are now highlighted, but one is surrounded by black squares, while the other is surrounded by hollow squares. The item with black squares is always the last one you click and is treated as the anchor item.
- Right-click either item, and then choose Relative Align - Relatively Align Below.
Notice that the Store Information label is placed below the Make Purchase Order label. By default, this type of alignment puts three pixels of space between the items. Also, notice that the left edge of the Store Information label is lined up with the left edge of the anchor item.
- Click the Supplier Information label on the canvas, press the Ctrl key, and click the Store Information label.
- Right-click either item, and then choose Relative Align - Relatively Align After.
The Supplier Information label is placed after the Store Information label with three pixels between them, and the top edge of the Supplier Information label is lined up with the top edge of the anchor item.
- Click the ID field for the store, press the Ctrl key, and click the Store Information label.
- Right-click either item, and then choose Relative Align - Relatively Align Below.
- Right-click either item again, and choose Relative Align - Relatively Align Right to Right to line up the two items.
TIP: You can apply any number of relative positioning instructions to an item. These instructions are always processed in the order in which you apply them. You can inspect this order in the itemlocation setting in the Properties view.
- Align the other fields on the canvas as shown figure 10, using relative positioning. Use below for the vertical arrows and after for the horizontal arrows.
Figure 10. Relatively align items in the form
- Click the Items for Purchase label on the canvas, press the Ctrl key, and click the Store Information label.
- Right-click either item, and then choose Relative Align - Relatively Align Below.
As expected, this puts three pixels of space between the items. To widen that interval, select the Items for Purchase label and press the down-arrow key on your keyboard to move the item to its proper location.
TIP: To move an item one pixel at a time, select the item and press an arrow key on your keyboard. This is called nudging.
- Move the Make Purchase Order label to another position on the canvas. You can see that all the other items (except the Total Price label and field) also change their position accordingly.
- Choose View - Show Grid. This displays a grid that helps you line up items on the form and ensure uniform spacing.
- Choose View - Show Rulers to enable rulers and guides. These help you to measure form items on the screen.
Let's now create an XForms table to provide an interface for the user to input multiple items. Follow these steps:
- In the Standard Library palette, click the drop-down button beside Table (Repeat) and select Table (Repeat) By Wizard.
- Click the canvas where you want to add the table; the Table Wizard dialog box opens.
- Select the Advanced Setup (using existing data) option, and then click Next.
- In the Instance column, select poInstance; in the Instance Data column, select the item node (see figure 11), and then click Next.
Figure 11. Select Instance Data for the table
- To configure the columns, click each item in the Display Columns column (see figure 12), and make the following changes:
- Display As: Select Text (read/write) for all elements except the Subtotal. Set the subtotal to Text (read). This creates an input field for each read/write element and a label for the subtotal.
- Include Header: Ensure this option is selected; it adds a header to each column of the table.
- Header: Enter the column header name. In this case, set header to ID for id element. Capitalize the first letter of other elements' name to be the header name.
- Width (Pixels): Leave the width as 100 pixels for each column except the ID column. Set the width to 50 (pixels) for the ID column.
- Show Border: Turn the border on for all the columns except the Subtotal. We recommend you turn the border off for Text (read) elements.
Figure 12. Configure columns for the table
- Click Next.
- Select Insert New Row Button and Remove Button on Each Row, clear all other options, and then click Finish.
- Select the pane that encloses the table, press the Ctrl key, and click the Items for Purchase label.
- Right-click either item, and then choose Relative Align - Relatively Align Below. It should look like figure 13.
Figure 13. Align table created by the wizard with the label
Setting up calculations for the table
You can add calculations to the table, multiplying Quantity by Price to get the Subtotal, and then adding all the subtotals to get the total price. There are two table wizards available to help with this (one for row operations and one for column operations).
Letâs start with the row:
- In the Outline view, select TABLE1_TABLE, right-click the element, and choose Wizards - Table Row Operation Wizard.
- Choose the target (ITEM5) for the calculation, and then click Next (see figure 14).
Figure 14. Select target item in row operation wizard
- Set the formula to the product (*) of ITEM3 and ITEM4, then click Finish.
- In the Outline view, right-click TABLE1_TABLE again, and then choose Wizards - Table Column Summation Wizard.
- In Step 1 of the wizard, select the TOTALPRICE1 field, and click Next.
- In Step 2, select ITEM5 as the column to be totaled, and click Finish.
- In the XForms view, notice that two XForms binds have been added to the form by the table wizards. These binds perform the calculations for the Subtotal and Totalprice fields (see figure 15).
Figure 15. XForms binding created by the table calculation wizards
- To align items in the table, select the plus (+) button on the canvas, press the Ctrl key, and click the table.
- Right-click either item and choose Relative Align - Relatively Align Below. The Insert Row button is moved under the table.
- In the Outline view, press the Ctrl key and select both the TOTALPRICE1 and TOTALPRICE_LABEL1 elements.
- Drag and drop them under the ADD element inside the TABLE1_PANE element.
- Because the table expands when the user adds rows, you should position the Total Price label and field relative to the table so that they move as the table grows. Select the Total Price input field on the canvas, press the Ctrl key, and click the table.
- Right-click either item, and then choose Relative Align - Relatively Align Below.
- Select the Total Price input field, press the Ctrl key, and click the Subtotal column header label.
- Right-click either item, and then choose Relative Align - Relatively Align Right to Right.
When you preview the form to check the calculations, you see that the input fields for Subtotal and Total Price contain the letters NaN, which stand for Not a Number. This occurs because the fields are empty, so we are actually multiplying nothing by nothing (or empty set by empty set). If you fill in all the Quantity and Price fields, you see that the subtotals and the total price are calculated correctly (see figure 16).
Figure 16. Preview the form to verify the calculation

Now you can add images to the Delete Row and Insert Row buttons to make them look more attractive. When adding images to a form, you must first enclose the image file in the form. After the image is added to the form, you can link any button or label items to that image to display the image.
- In the Enclosures view, expand Data, right-click PAGE1, and then choose Enclose File.
- Browse to the Add button image provided in the Download section. Select the file and click Open.
- Repeat the previous steps to enclose the Delete button image (also in the Download section). Notice that the Enclosures view now includes the image files you have added.
- In the Enclosures view, drag the add1 image and drop it on the Add button on the canvas. Enlarge the size of the button to see that the button now displays the image.
- Repeat the prevous step for the delete1 image and the delete button.
- By default, if the image is smaller than the button, the image is re-sized to fit within and to fill the button. We must now center the image on the button. To do this, select the Add button on the canvas. In the Properties view, click the Menu button, and then select Show Advanced Properties (see figure 17).
Figure 17. Show Advanced Properties in Properties view
- In the Properties view, expand Appearance. Set imagemode to clip, which centers the image on the button. Also, set border to off and bgcolor to transparent.
- Repeat the previous step for the Delete button and preview the form to see the new images (see figure 18).
Figure 18. Preview the form to see image buttons
A submission is a set of rules that defines which form data is submitted, how the data is submitted, and where the data goes. Workplace Forms supports two types of submissions:
- XFDL submissions. These typically submit the complete form to a processing application. These submissions can filter out various parts of the form, if desired, or submit the form as HTML data instead of XFDL data. However, theyâre most commonly used to submit the entire XFDL form.
- XForms submissions. These do not submit the XFDL elements of the form. They submit only the data model or a portion thereof. This is useful if you want to submit data directly to processing applications or if you want to make mid-population calls that return data to the form while the user is working with it (much like a Web service call).
Let's now add an XForms submission to your form. To do this, you define a set of submission rules, and then create a button that triggers the submission:
- In the XForms view, right-click Model: Default, and then choose Create Submission.
Note that XForms submissions apply only to one data model in the form, though itâs unusual to have more than one model.
- In the XForms view, select the submission. The Properties view now shows the properties for this submission.
- Set up a submission that writes the XForms data model to a file on disk. Normally, we set up a submission to go to a URL that processes the form, but writing it to disk instead gives us a chance to see the data thatâs normally submitted. In the Properties view (see figure 19), expand the XForms section and make the following changes:
- Method: Select put. This saves the data to the local file system.
- Replace: Sets the part of the data model that is replaced by the response data. Because you do not expect any response, select none.
- Action: Enter the full path to the target file using the format: file:\\<folder>\<file name>
Figure 19. Set properties for the XForms submission
TIP: Workplace Forms Viewer limits where you can write data on the local file system. This is a security measure similar to the Java sandbox that prevents forms from overwriting important files. Forms can write only to the folder that contains them or to one of its subfolders. For example, if the XFDL form is in the C:\Workplace Forms\FormsProject\ directory, you can write data to file:\\C:\Workplace Forms\FormsProject\temp.xml. If the form is opened from a Web site instead of the local file system, you cannot write to file at all because the form does not have a parent folder on the local file system.
- In the XForms view, drag and drop the submission node onto the canvas to create a new button that is bound to submission. Clicking this button triggers the submission you just defined.
- Change the appearance of the button in the Properties view as follows:
- Justify: center
- Fontinfo: 9 pt Arial (bold)
- Fontcolor: white
- Bgcolor: #8080FF
- Select the button, press the Ctrl key, and select the Make Purchase Order label.
- Right-click either item, and then choose Relative Align - Relatively Align Bottom to Bottom. The button moves so that its bottom edge is lined up with the label.
- Select the button, press the Ctrl key, and select the Supplier Information label.
- Right-click either item, and then choose Relative Align - Relatively Align Right to Right. The button has moved so that its right edge is lined up with the label (see figure 20).
Figure 20. Change position of the XForms submission button
- When you preview the form, enter values for mandatory fields, and then click the Submit button. Open the file that was written to disk and examine the data it contains (see figure 21). Notice how it matches the data model in your form.
Figure 21. Data saved by put submission
When the user opens a form, all mandatory input items appear with a different background color. You can set this color as you like, but the default is yellow. This color indicates that the field is required. If the user attempts to tab past a mandatory input item, an error message appears. The default error message warns the user, "This entry is invalid. Please try again."
If you preview the form you have designed, you can see that the Quantity and Price input fields have a yellow background. All elements generated from the schema are mandatory by default. However, elements of type string do not appear as mandatory in the form because the schema accepts an empty value as valid input for a string.
TIP: You can make a string field mandatory by either enabling the mandatory option in the XFDL format option or setting required to true() in an XForms bind. You can set the other data types to be non-mandatory by adding the nillable="true" attribute to that element in the schema.
Now you set the store ID and supplier ID fields so that they do not accept an empty value. Of course, you can add a schema constraint into the XForms model to achieve this. Instead, however, we want to show how to use a constraint setting to set data constraints for the fields and how to change the default error message when the input is invalid:
- Select the ID field for the store.
- In the Properties view, expand Format, format, constraints, and set mandatory to on.
- Expand patterns and click <empty> value. Notice that a drop-down list and an Add button appear.
- Click the Add button to add a new pattern under the Pattern node. Set the new pattern nodeâs value to ID([0-9]{6}). This pattern is a regular expression that means the acceptable value of store ID should begin with ID followed by six digits.
TIP: All constraints and display patterns are set by regular expressions. If youâre using particular constraints repeatedly (for instance, for a phone number field), itâs a good idea to save your item as a custom object so that you can re-create it easily. This saves you the trouble of having to re-type the regular expression every time.
- Finally, set the error message that is displayed when the input in invalid: Beside the message property, enter the message: "The acceptable value should begin with 'ID' followed by six digits."
- Repeat the previous steps to set constraints for the Supplier ID input field.
Preview the form to see the effect; it should look like figure 22.
Figure 22. Preview the form to verify the data constraint

Every locale uses different symbols to express common concepts, such as currencies, decimal and grouping separators, and mathematical symbols. Furthermore, most locales express dates and times in different ways as well. To ensure that your form displays this information correctly, you should localize your forms to suit the locale (country and language) in which they will be used. IBM Workplace Forms is designed to be locale- and language-aware, meaning that each form is designed for a specific language and locale.
Follow these steps to localize the form to different locales:
- Select the Quantity input field inside the table on the canvas.
- In the Properties view, expand Format, format, datatype and change its value to integer.
- Select the Price input field inside the table.
- In the Properties view, expand Format, format, datatype and change its value to currency. Change the datatype of the Subtotal and Total Price fields to currency, using the same method.
- Create a Non-XForms label on the canvas and align it relatively after the Make Purchase Order label.
- Next, click the label you just created and change its value, datatype, and presentation pattern in the Properties view as follows:
- Value: 20061001
- Datatype: date
- Pattern: EEEE, MMMM d, yyyy
When you preview the form, it defaults to the en-US locale because there is no locale setting for the form. The date label should be formatted like so: Sunday, October 1, 2006.
- Enter numeric values into the Quantity and Price input fields. You see that a dollar symbol is now added to the price, subtotal, and total.
- Locale support is identified through the xml:lang attribute. This attribute is added to the XFDL tag in the form and identifies which locale the form was designed for. Open the Source panel of the form editor and add an xml:lang attribute with a value of fr-FR value to the XFDL tag (see figure 23). This sets the form to use the French France locale.
Figure 23. Set locale for the form
When you preview the form, notice that the date is now in French, and the monetary values are now expressed as euros with different delimiters for the thousand and decimal places as shown in figure 24.
Figure 24. Numbers and currencies in French locale

IBM Workplace Forms Designer is a drag-and-drop design program that lets form designers create highly detailed, powerful XFDL forms. Workplace Forms Designer V2.6.1 is based on open source Eclipse Workbench technologies and works in tandem with IBM Workplace Forms Viewer V2.6.1. Developers use Workplace Forms Designer to build forms and use Workplace Forms Viewer to check form appearance, layout, and logic.
This article provided you with some basic knowledge of Workplace Forms Designer and stepped you through the process of designing a form that leverages the XForms open standard.
| Description | Name | Size | Download method |
|---|---|---|---|
| Sample Forms for this article | forms-creation.ZIP | 6 KB | HTTP |
Information about download methods
Learn
- IBM Workplace Forms V2.6.1 Information Roadmap
- Workplace Forms product documentation page
- developerWorks Workplace white paper, "Overview of IBM Workplace Forms"
Get products and technologies
- Download a trial version of Workplace Forms Designer and Workplace Forms Viewer from developerWorks.
Discuss
- Participate in the discussion forum.
- Read John Boyer's blog: Workplace Forms and Next Generation Web Applications.
Check out developerWorks
Comments (Undergoing maintenance)









