
IBM Forms Viewer 4


Second Edition
Published May 2011

© Copyright IBM Corporation 2000, 2011
You can save a local copy of this document from your browser. Each browser has different menus and menu options. Consult the browser help if you need assistance saving the document locally.
If you would like to provide feedback about this document, see the IBM Documentation Feedback Web site.
The IBM® Forms Viewer provides a single interface for users to open, fill out, and save forms.
The Viewer can display forms within its own window (standalone) or within your Web browser. In either case, all Viewer functionality is available.
The new features for the Viewer 4.0 are listed below.
This section describes the available accessibility features for the IBM Forms Viewer.
The Viewer supports screen readers through the MSAA (Microsoft® Active Accessibility) standard. Through this standard, the Viewer works with the JAWS screen reader from Freedom Scientific, as well as other MSAA-compliant readers, such as Window-Eyes from GW Micro and Microsoft Narrator.
Each item in a form can have an accessibility-specific message associated with it. When a screen reader is active, the Viewer checks items for these messages as each item receives the focus. The Viewer then passes the message to the screen reader, which reads the message aloud for the user, along with some general information about the item.
If a form does not have any accessibility-specific messages, the screen reader still reads general information about each item, but this information may not be clear to the user.
The Viewer automatically activates screen reader support when an MSAA-compliant screen reader is running.
The enhanced focus indicator makes it easier to see which item has the focus by drawing a small, black square near the top-left corner of the item. This enhancement appears in addition to the regular focus indicator, which normally outlines an item or places the cursor inside an item.
The release notes provide a summary of new features and improvements, and descriptions of known limitations, problems, and workarounds.
| About this release | New features and improvements | What's new in the IBM Forms Viewer |
| Migration, upgrade, and configuration information | System requirements, backward compatibility information | Viewer system requirements |
| Known limitations, problems, and workaround | Troubleshooting | Troubleshooting and support |
| Limitations, problems, and workarounds | Viewer technotes and flashes | |
| Contacting customer support | Customer support | IBM Forms Support web page |
This section contains two reference cards which provide information on keyboard shortcuts and accessibility options.
This reference card provides a list of Viewer keyboard commands used to navigate a form without the use of a mouse.
| Tab | Moves focus forward from item to item in the form. |
| Shift + Tab | Moves focus backward from item to item in the form. |
| Enter | Activates a button or field in the form. |
| Space | Selects a check box or radio button, or displays the contents of a dropdown list. In an open dropdown list, pressing SPACE selects the highlighted choice and closes the list. |
| Arrow keys | Pressing the LEFT or RIGHT arrow keys moves the cursor between letters in a field. In a dropdown list, pressing the DOWN arrow key displays the contents of the list. Use the DOWN and UP arrows to move through the list of choices. |
| Alt + F1 | Opens Viewer Help. |
| Alt + F7 | Spell checks the selected item. |
| Alt + F12 | Opens the Preferences window. |
| Alt + Space | Opens the context menu, which allows resizing or closing of the Viewer's window. |
| Ctrl +A | Selects all from a text field. |
| Ctrl + B | Turns bold typeface in a rich text field on or off. |
| Ctrl + C | Copies from a text field. |
| Ctrl + F | Opens the font dialog in a rich text field. |
| Ctrl + G | Opens the paragraph dialog in a rich text field. |
| Ctrl + H | Toggles the Viewer 's help mode which displays any context-sensitive help messages in the form. |
| Ctrl + I | Turns italic typeface in a rich text field on or off. |
| Ctrl + M | E-mails the form. |
| Ctrl + O | Opens a form. |
| Ctrl + P | Prints the form. |
| Ctrl + S | Saves the form. |
| Ctrl + U | Turns underline typeface in a rich text field on or off. |
| Ctrl + V | Pastes into a text field. |
| Ctrl + Shift + S | Save as. |
| Ctrl + Shift + Plus (+) | Increases zoom. |
| Ctrl + Shift + Minus (-) | Decreases zoom. |
This reference card provides descriptions of the Viewer preferences available for modification.
| WWW Browser Configuration | |
| Online | The computer is connected to a network and will submit forms when "Submit" is clicked. |
| Online with Backup | The computer is connected to a network and will save a backup copy of the last form submitted. |
| Offline | The computer is not connected to a network. A save prompt appears when the "Submit" is clicked. |
| Accessibility Configuration | |
| Use Enhanced Focus Indicator | A small, black square is drawn near the top-left corner of the item that currently has focus. This square appears in addition to the normal focus indicators, making it easier to see which item has focus. |
| Use Operating System Colors | The Viewer uses the operating system colors, such as high contrast, when drawing a form rather than the colors specified in the form itself. |
| Type Checking Options | |
| Do Predictive Input Checking | The Viewer checks for errors, and underlines them as words are typed. |
| Date Format | This setting determines how the Viewer interprets numeric dates. For example, 02/03/2009 may be interpreted as either February 3, 2009 or March 2, 2009. Setting the Date Format ensures the Viewer correctly identifies potentially confusing dates. |
| Tabbing Options – Pressing the Tab key twice moves the focus from an item with invalid information, or missing mandatory information. Regardless of selected Tab options, focus can be moved by using the mouse. | |
| Stop Tab from Invalid Input Items | When enabled, the Tab key does not move focus away from invalid input items. |
| Stop Tab from Empty Mandatory Items | When enabled, the Tab key does not move focus away from empty mandatory items. |
| Smartfill – Smartfill records frequently used information, then automatically inserts the information in Smartfill-enabled forms. | |
| Enable Smartfill | When enabled, Smartfill prompts users to save applicable data. In a Smartfill-enabled form, the user is asked whether or not the saved data should be used to fill in the form. |
| Conversion Options | |
| Print Radio Buttons as Check Boxes | Prints radio buttons as check boxes. This creates visual consistency in the printed form, with all choices appearing uniformly as check boxes. |
| Print Radio Buttons without Values | Prints all radio buttons in a group as blank choices. |
| Print Scroll Bars on Fields | Prints the scroll bars as they appear beside text fields. |
| Print Single Line Fields as Lines | Prints a blank line instead of printing a single line field as an empty rectangle. |
| Print Border Around Form Page | Visually frames the form by printing a border around the form. |
| Page Layout Defaults | |
| Fit to One Page (expand or shrink) | Prints the form page on a single piece of paper. This option scales the form up or down so it fits on a single page, covering as much of the page as possible. |
| Shrink to One Page | Prints the form page on a single piece of paper. This option scales the form down so that it will fit on a single page. If the form already fits on a single page, it is not scaled. |
| Tile in One Direction | Prints the form on multiple pages in the longer dimension (either horizontal or vertical). This option scales the form so that the smaller dimension fits on a single page if necessary. |
| Tile in Two Directions | Prints the form on multiple pages in both dimensions. This option prints the form in its true size. |
| Miscellaneous Options | |
| Print each page as separate print job | Prints each form page as a separate print job rather than grouping all the pages of a form into a single print job. Only select this option if the printer does not have enough memory to print a large form. |
| Print black and white (excluding images) | Prints the form in black and white only. Select this option if the printer has difficulty representing the form's colors in color. Typical symptoms include: getting black boxes where the text should be; text not showing up; or whiteness appearing around the text of transparent labels. |
| Form Appearance Options | |
| Show Boundary on All Form Items | Draws a boundary line around the edges of all visible form items. This option should be turned off except when designing the layout of a form. |
| Use "X" Style Check Boxes | By default, check boxes are drawn as a three-dimensional box with a red check mark when selected. Using "X" style check boxes draws a two-dimensional box with a black "X" when selected. |
| Scroll Fields on Zoom | Provides access to complete text by adding scroll bars to zoomed fields. This does not change the amount of text that can be entered into the field. Note that this setting may be overridden by individual forms. |
| Viewer Language | |
| Locale | Determines what language used by the Viewer. This feature does not translate forms, but ensures that all elements of the Viewer are displayed in the chosen language. |
| Security Options | |
| Digital Certificate Identity Filter | Filters the list of available digital certificates. The value can be any part of a valid signing identity, such as an email address or first name. All certificates that match the entered value will be available. For example, if you entered, "Bob", all certificates with the name Bob in the signing identity are made available. Select this option only if there are digital certificates installed on the computer that should remain inaccessible. |
| Check CRL Distribution Points | Certificate Revocation Lists (CRLs) contain the names of digital certificates that are no longer valid. When a form is signed, the Viewer checks its locally stored CRLs to verify the certificate is valid. Select this check box to have the Viewer verify online CRLs. Only check this box if the Viewer can connect to the required URLs. If this check box is selected and the computer is unable to connect to the required URL, there may be a delay of up to three minutes during which the Viewer will not respond to any requests. |
When you embed an XFDL form in an HTML page, you are essentially declaring that a portion of the web page is controlled by a program other than the browser, such as the Viewer. As a result, this portion of the page operates differently than the HTML page in which it resides.
For example, if a user is filling out a form on a Web page but needs more information to complete it, he or she might click a link on the HTML page and go to a new page. Normally when users perform this action, any data that they have entered into the form is lost. However, with an XFDL form, the form can be detached from the first Web page and provided for viewing in a second Web page.
When a form is detached from one Web page and reattached to another, it maintains all of the user's data. Unlike the first Web page, any successive Web pages that need to display the same form do not need to explicitly embed the form. If you want them to display the same form and retain user data, they must contain objects that share the same detach_id.
Successive pages do not have to display the same form. A second Web page can display a different form if it contains a different object. You can even redirect users to a different Web page if they are taking too long to complete a form and the detached form has timed out. Objects that contain a refresh_URL ensure that users can be directed to another Web page if they need help or to a new form if they abandon completion of the old one.
Once the Viewer is embedded in an HTML Web page, you can treat it like any other HTML object. For example, you can use JavaScript™, other portlets, or servlets to generate dynamic content within the object or form. You can also generate new XML instances for your form.
Embedding the Viewer in an HTML page allows you to display forms in a portal environment or as part of a series of web pages. This permits forms to be updated dynamically in response to user selections on the HTML page.
To embed the Viewer, you must use two HTML elements:
The HTML object is a placeholder. In your HTML file, it specifies the location where the object will be displayed in relation to the other elements on the web page. For example, you could place an object inside an HTML table cell:
<tr>
<td>
<object>...</object>
</td>
</tr>
The script element is not displayed as part of the Web page, so it can be placed anywhere in your HTML code. You may prefer to place scripts directly after the object that they are associated with, or at the beginning or end of the page. In the following example, the script that contains the form is placed immediately after the table with the form's object:
</table>
<script>
... XFDL form ...
</script>
You can embed a form into any HTML page. However, every browser interprets HTML code differently. If you know that all your users are only using one type of browser, you can focus your HTML code to support it specifically. On the other hand, if your users are using multiple browser types, you will need to create additional code to ensure that all of the browsers recognize and display the embedded form.
If you are only supporting one kind of browser, you can create a single object. If you are supporting multiple browsers, you need to dynamically create the object with JavaScript, as shown in Supporting multiple browsers.
The object element in HTML allows Web page designers to specify data to be rendered by a browser plugin. IBM has taken advantage of this element to allow XFDL forms to be embedded in a web page. Using the object element allows you to specify how the object is implemented and the location of the object's data. This is done using the following attributes:
You can also modify the display area of the form with the following optional attributes:
| Attribute | Browser Support | Description |
|---|---|---|
| align | All | Sets the position of the object within
its allowed display area. The valid settings are: left, right,
and center. For example: <OBJECT align="center"> |
| border | All | Sets the width of the object's border
in pixels. This value must always be an integer. For example: <OBJECT border="2"> |
| hspace | All | Sets the amount of white space (in pixels)
to be inserted to the left and right of an object. If the object has
a border, this additional white space is outside of the border. This
number is always an integer. For example: <OBJECT hspace="2"> |
| vspace | All | Sets the amount of white space (in pixels)
to be inserted above and below an object. If the object has a border,
this additional white space is outside of the border. This number
is always an integer. For example: <OBJECT hspace="2"> |
In the following example, the object is assigned a unique name, pointed at the Viewer Active X control, and given a size.
<OBJECT id="unique_name" height="400" width="800"
classid="CLSID:354913B2-7190-49C0-944B-1507C9125367">
... object parameters...
</OBJECT>
Object attributes identify and set the size of the object, but to specify run-time values you must use the param element. The param element consists of name and value pairs. For example:
<PARAM NAME="XFDLID" VALUE="XFDLData">
The param elements determine the behavior of the Viewer and how it handles the embedded form. There are six param elements:
<PARAM NAME="XFDLID" VALUE="XFDLData">
<PARAM NAME="detach_id" VALUE="1234567890ABCD">
Successive objects containing the same form must all have the same detach_id if you want to maintain user data between web pages. For example, if form A appears in HTML pages 1- 4, and the form object in page 1 has a detach_id of 10236B, then the form objects in pages 2 - 4 must also have a detach_id of 10236B.
If you specify a detach_id, you must also give the object a TTL (Time To Live).
<PARAM NAME="refresh_URL"
VALUE="http://www.serv1/IRS/Sched22.htm">
<PARAM NAME="TTL" VALUE="15">
If you are using data instances, several additional values may be included:
The following code sample shows how to define the object parameters if you want to add new XML data to the end of an existing XML data model instance:
<PARAM NAME="instance_1"
VALUE="new_Inst old_Inst append '[custom:rec][custom:name]'">
The following code sample shows how to define the object parameters if you want to replace the existing XForms data instance with a new one:
<PARAM NAME="instance_1"
VALUE="new_Inst old_Inst xforms; replace="."">
The following example displays an object with a complete set of param attributes for replacing an XML data model instance:
<OBJECT...object attributes...>
<PARAM NAME="XFDLID" VALUE="theForm">
<PARAM NAME="TTL" VALUE="15">
<PARAM NAME="detach_id" VALUE="12354678901234567890">
<PARAM NAME="refresh_URL" VALUE="http://www.serv1/IRS/Sched22.htm">
<PARAM NAME="retain_Viewer" VALUE="on">
<PARAM NAME="instance_1" VALUE="newIns oldIns replace [0][0]">
</OBJECT>
The following example displays an object with a complete set of param attributes for replacing an XForms instance:
<OBJECT...object attributes...>
<PARAM NAME="XFDLID" VALUE="theForm">
<PARAM NAME="TTL" VALUE="15">
<PARAM NAME="detach_id" VALUE="12354678901234567890">
<PARAM NAME="refresh_URL" VALUE="http://www.serv1/IRS/Sched22.htm">
<PARAM NAME="retain_Viewer" VALUE="on">
<PARAM NAME="instance_1"
VALUE="new_Inst old_Inst xforms; replace="."">
</OBJECT>
Objects frequently include multiple parameters. As a result, the Viewer must follow an order of precedence so that the object parameters are always processed in a consistent manner. When a new Web page containing a form object is opened, the following precedence is used to determine what is displayed:
Internet Explorer and Mozilla Firefox have different and incompatible ways of embedding objects. The best way to support both browsers is to use JavaScript to dynamically create the object specific to the browser which is being used.
The JavaScript technique is shown in the example below. The code is in two parts. The first part is a function declaration that you place in the HTML head section of your Web page. In the example, the function is named addViewer, but you can give it any name you want. You can copy this part of the code without any changes.
When modifying the parameters, make sure that you have a comma after each one. You do not need a comma after the last parameter.
<html>
<head>
<title>Embedded Form</title>
<script type="text/javascript">
function addViewer(containerDiv, tagID, _width, _height)
{
var parentDiv = document.getElementById(containerDiv);
var element = document.createElement('object');
for (var i = 4; i < arguments.length; i+=2)
{
var param = document.createElement('param');
param.setAttribute('name', arguments[i]);
param.setAttribute('value',arguments[i+1]);
element.appendChild(param);
}
element.setAttribute('id',tagID);
element.setAttribute('height',_height);
element.setAttribute('width',_width);
if (navigator.appName == 'Microsoft Internet Explorer')
{
parentDiv.appendChild(element);
element.setAttribute('classid', 'clsid:354913B2-7190-49C0-944B-1507C9125367');
}
else
{
element.setAttribute('type', 'application/vnd.xfdl');
parentDiv.appendChild(element);
}
} </script>
<script language="XFDL" id="XFDLData" type="application/vnd.xfdl;
wrapped=comment;">
<!--
form data goes here
-->
</script>
</head>
<body>
<div id="viewer">
<script type="text/javascript">
addViewer (
"viewer", // id of the HTML div element
"CPClient", // id to assign to the object element
800, 400, // width and height of the Viewer
"XFDLID", "XFDLData", // name/value pair for XFDL param
"detach_id", value="2507088000" // name/value pair for detach_id param
/* other params as required. */
);
</script>
</div>
web page content goes here
</body>
</html>
In HTML, the script element places a script inside the HTML page. In the case of XFDL forms, the script includes the form itself. There are a number of attributes that modify the script element. These attributes help the Viewer to recognize the embedded form as valid XFDL. They include:
<SCRIPT language="XFDL">
<PARAM NAME="XFDLID" VALUE="XFDLData">
<SCRIPT id="XFDLData">
<SCRIPT type="application/vnd.xfdl; wrapped=comment;
encoding=base64; next-chunk=Part2; content-encoding=utf-16">
These parameters must be separated with a semi-colon followed by a space.
The following example displays a script starting tag, complete with all of the required attributes:
<SCRIPT language="XFDL" id="XFDLData"
type="application/vnd.xfdl; wrapped=comment;">
...enclosed form...
</SCRIPT>
The following example shows a small XFDL form enclosed in a comment wrapper:
<SCRIPT ...script attributes...>
<!--
<?xml version="1.0"?>
<XFDL xmlns="http://www.ibm.com/xmlns/prod/XFDL/7.0"
xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom">
<globalpage sid="global">
<global sid="global">
<vfd_date>9/7/2004</vfd_date>
</global>
</globalpage>
<page sid="PAGE1">
<global sid="global">
<label>PAGE1</label>
</global>
<label sid="LABEL1">
<value>This is a short sample form.</value>
</label>
</page>
</XFDL>
-->
</SCRIPT>
You can include XML instances (XForms or XML Data Model) in your Web page that contain XML data that you can move into your form. This XML data can replace or add to existing XML data inside your form – particularly useful for dynamically populating forms with information selected by the user from an HTML page.
For example, consider a purchase order form embedded in an HTML page. The XFDL form is a generic purchase order form, possibly personalized with user information via a data fragment. This form is displayed in an HTML page (or a series of HTML pages) that allow users to select the products they want to purchase. When users select the desired product, they trigger the application server to create a custom XML instance to replace the generic XML instance currently in the XFDL form. To the eyes of the users, the form appears to automatically populate with the correct purchase information, including order number, product type, and pricing.
Regardless of whether the XML instance is hardcoded into the HTML page or generated by an application server, it must be wrapped in a script container. Like a script element containing an XFDL form, you must define the following attributes:
<SCRIPT language="XFDL">
<OBJECT ... object attributes ...>
<PARAM NAME="instance_1"
VALUE="new_Instance old_Instance
append[custom:record][custom:name]">
... other params ...
</OBJECT>
<SCRIPT id="new_Instance">
<SCRIPT type="application/vnd.xfdl; wrapped=comment">
The type and wrapped parameters must be separated with a semi-colon.
Forms often include multiple XML instances. They may even refer to data fragments, frequently used scraps of XML data that are stored on users’ computers. If your HTML contains replacement instances, or if replacement instances are generated by an application server, the Viewer must follow an order of precedence to ensure the instances are always loaded in a consistent manner.
When a new Web page containing XML instances is opened, the following precedence is used to determine what is displayed:
The following example shows all the code required to fully embed a form in Internet Explorer or Firefox.
This includes an object element, the object parameters, the script element, and a sample XFDL form wrapped in a comment structure.
<OBJECT id="Object1" height="200" width="200" border="5"
classid="CLSID:354913B2-7190-49C0-944B-1507C9125367">
<PARAM NAME="XFDLID" VALUE="XFDLData">
<PARAM NAME="detach_id" VALUE="2507088000">
<PARAM NAME="refresh_url" VALUE="envAware.html">
<PARAM NAME="TTL" VALUE="17">
<PARAM NAME="retain_Viewer" VALUE="on">
</OBJECT>
<!--[if !IE]>
Mozilla 1.x, Firefox 1.x, Netscape 7+ and others will use the inner object, the nested object
-->
<OBJECT ID="forMozillabrowser" height="300" width="800" border="5"
type="application/vnd.xfdl">
<PARAM NAME="XFDLID" VALUE="theForm2">
<PARAM NAME="detach_id" VALUE="2507088000">
<PARAM NAME="refresh_url" VALUE="envAware.html">
<PARAM NAME="TTL" VALUE="17">
<PARAM NAME="retain_Viewer" VALUE="on">
<PARAM NAME="instance_1" VALUE="newInst xforms; replace="."">
</OBJECT>
<!--<![endif]-->
</OBJECT>
<SCRIPT language="XFDL" id="XFDLData"
type="application/vnd.xfdl; wrapped=comment">
<!--
<?xml version="1.0"?>
<XFDL xmlns="http://www.ibm.com/xmlns/prod/XFDL/7.0"
xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom">
<globalpage sid="global">
<global sid="global">
<vfd_date>9/7/2004</vfd_date>
</global>
</globalpage>
<page sid="PAGE1">
<global sid="global">
<label>PAGE1</label>
</global>
<label sid="LABEL1">
<value>This is a short sample form.</value>
</label>
</page>
</XFDL>
-->
</SCRIPT>
The following example shows all the code required to fully embed an XForms form and support both Internet Explorer and Firefox browsers. It also demonstrates how to use chunking.
<html>
<head>
<title>Embed Form</title>
<script type="text/javascript">
function addViewer(containerDiv, tagID, _width, _height)
{
var parentDiv = document.getElementById(containerDiv);
var element = document.createElement('object');
for (var i = 4; i < arguments.length; i+=2)
{
var param = document.createElement('param');
param.setAttribute('name', arguments[i]);
param.setAttribute('value',arguments[i+1]);
element.appendChild(param);
}
element.setAttribute('id',tagID);
element.setAttribute('height',_height);
element.setAttribute('width',_width);
if (navigator.appName == 'Microsoft Internet Explorer')
{
parentDiv.appendChild(element);
element.setAttribute('classid', 'clsid:354913B2-7190-49C0-944B-1507C9125367');
}
else
{
element.setAttribute('type', 'application/vnd.xfdl');
parentDiv.appendChild(element);
}
}
</script>
<script language="XFDL" id="XFDLData" type="application/vnd.xfdl;
wrapped=comment; next-chunk=chunk2">
<!--
<?xml version="1.0" encoding="UTF-8"?>
<XFDL xmlns="http://www.ibm.com/xmlns/prod/XFDL/7.1"
xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"
xmlns:ev="http://www.w3.org/2001/xml-events"
xmlns:xforms="http://www.w3.org/2002/xforms">
<globalpage sid="global">
<global sid="global">
<xformsmodels>
<xforms:model>
<xforms:instance id="instance1" xmlns="">
<root>
<field_1></field_1>
<field_2></field_2>
<field_3></field_3>
</root>
</xforms:instance>
</xforms:model>
</xformsmodels>
</global>
</globalpage>
-->
</script>
<script language="XFDL" id="chunk2" type="application/vnd.xfdl;
wrapped=comment; next-chunk=chunk3">
<!--
<page sid="PAGE1">
<global sid="global">
<label>PAGE1</label>
</global>
<field sid="field1">
<xforms:input ref="field_1">
<xforms:label>Field with xforms:input</xforms:label>
</xforms:input>
</field>
<field sid="field2">
<xforms:textarea ref="field_2">
<xforms:label>Field with xforms:textarea</xforms:label>
</xforms:textarea>
<size>
<width>30</width>
<height>2</height>
</size>
</field>
-->
</script>
<script language="XFDL" id="chunk3" type="application/vnd.xfdl;
wrapped=comment">
<!--
<field sid="field3">
<xforms:secret ref="field_3">
<xforms:label>Field with xforms:secret</xforms:label>
</xforms:secret>
</field>
<spacer sid="vfd_spacer">
<itemlocation>
<x>250</x>
<y>250</y>
<width>1</width>
<height>1</height>
</itemlocation>
</spacer>
</page>
</XFDL>
-->
</script>
</head>
<body>
<div id="viewer">
<script type="text/javascript">
addViewer (
"viewer", // id of the HTML div element
"CPClient", // id to assign to the object element
800, 400, // width and height of the Viewer
"XFDLID", "XFDLData", // name/value pair for XFDL param
"detach_id", value="2507088000" // name/value pair for detach_id param
/* other params as required. */
);
</script>
</div>
</body>
</html>
The Viewer functions enable you to trigger actions in the Viewer. The param Viewer function allows you to call specific object parameters in computes that return the parameter's value. For example, if the param function called the object's XFDLID parameter, then it would return the object’s XFDL ID. For more information, see the XFDL Specification
If you want to embed a signed form into a Web page, the form must be base64-gzip encoded. When Internet Explorer parses a signed embedded form, it may add extra carriage returns to the form. This prevents the form from matching the signature hash value, which causes the Viewer to declare that the form’s signature is invalid. Encoding signed forms in base64-gzip ensures that this does not occur.
The easiest way to encode an XFDL form is to open it and encode it in the Designer.
If your form contains characters outside of the ASCII (0-7F) range, the character encoding in your XFDL form must match the BSTR encoding passed by the browser to the object containing the Viewer. The easiest way to ensure that they match is to specify character encoding only in the HTML form. You can place it in a meta tag inside the HTML head tag. For example:
<META http-equiv="Content-Type" content="text/html;
charset=utf-8">
Furthermore, you must also remove the character encoding already in your form. As the Designer automatically adds character encoding, you must open the form in another text editor, such as UltraEdit, Notepad, or TextPad, and delete the encoding.
However, under some circumstances you may find that you must include character encoding in your XFDL form. If so, you must still ensure that the form encoding matches the BSTR encoding. Therefore, if you include character encoding in your form, it must always be:
You cannot change the character encoding of the form in the Designer. You must edit it in another text editor, such as UltraEdit or Notepad.
To change your form's character encoding:
You can use IBM Forms JavaScript API to communicate between a form and a web page. The web page can be in an XFDL pane item, or it can be inside a modal dialog box.
The tutorials describe how to use Dojo widgets inside a web page on an XFDL form, and how to use the JavaScript API to transfer data between the form and the web page. Although the use of Dojo Toolkit is described, you can modify the technique to use other toolkits.
Except for minor differences in file paths, the forms and web pages in the Webform Server and Viewer versions of the tutorials are identical. The differences in the file paths are due to the way that the sample servlet that comes with Webform Server handles relative URLs. It is possible to design a servlet so that the file paths can be identical. However, because the tutorial relies on the sample servlet, some adjustments to the file paths are required.
If your forms are served by Webform Server but viewed inside Viewer embedded in an HTML page, follow the tutorial for Webform Server.
In this tutorial, you will learn how to embed a web page in a form. The web page contains a Dojo slider widget. When the value of the slider widget changes, the new value is inserted into a label on the form.
The project that you build in this tutorial consists of two files. One file is a simple XFDL form that contains data, a pane, and a label. The other file is a web page that implements a Dojo slider control and is displayed inside the pane. The web page uses the IBM Forms JavaScript API to transfer data between the slider control and the form.
The web page is loaded when you open the form. A script on the web page copies the slider value from the XForms model into the slider control. When you change the value of the slider, the script copies the new value into the XForms model, which updates the label.
The first task is to verify that you have the appropriate files installed on your computer. Next, you create the XFDL form that contains the web page. After you create the form, you create the web page that is displayed in the form. Finally, you deploy and use the form.
To avoid problems during the tutorial, make sure that you have Dojo Toolkit in the correct location and that you have the appropriate supporting files in place.
The folder structure that you create in this tutorial is only one of several valid structures. You can use a different structure if you want, but you must adjust filepaths in your XFDL form and HTML pages to suit the structure.
You can download Dojo Toolkit from the Dojo website, or use the version that is included with Webform Server. If you have Webform Server, look for dojo.ibm.standard-1.4.3-20100331.zip in C:\Program Files\IBM\Forms Server\4.0\WebformServer\redist.
HTMLPane\dojo\dijit HTMLPane\dojo\dojo HTMLPane\dojo\dojox HTMLPane\JavaScript
The form contains a label and a pane. The form also contains an XForms model that supplies the value for the label and for the slider control.
In this stage of the tutorial, you create the XFDL form that contains a pane. The pane will display the web page that you create in a later stage.
Here is the complete file:
<?xml version="1.0" encoding="UTF-8"?>
<XFDL xmlns="http://www.ibm.com/xmlns/prod/XFDL/8.0"
xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/8.0"
xmlns:xforms="http://www.w3.org/2002/xforms">
<globalpage sid="global">
<global sid="global">
<xformsmodels>
<xforms:model>
<xforms:instance xmlns="" id="slider-value">
<data>
<slider>4</slider>
</data>
</xforms:instance>
</xforms:model>
</xformsmodels>
</global>
</globalpage>
<page sid="PAGE1">
<global sid="global">
<label>HTML in pane</label>
</global>
<label sid="LABEL1">
<value>Viewer HTML in pane Tutorial</value>
</label>
<label sid="LABEL2">
<xforms:output ref="instance('slider-value')/slider">
<xforms:label>Value of slider: </xforms:label>
</xforms:output>
<itemlocation>
<below>LABEL1</below>
</itemlocation>
</label>
<pane sid="PANE1">
<xforms:group ref="instance('slider-value')/slider">
<label sid="PANE1_LABEL1">
<value>This is printed.</value>
</label>
<spacer sid="vfd_spacer">
<itemlocation>
<x>300</x>
<y>40</y>
</itemlocation>
</spacer>
</xforms:group>
<!-- The file must be in the same folder as the XFDL form -->
<url>TutorialHTMLPane.html</url>
</pane>
</page>
</XFDL>
In this stage of the tutorial, you create the web page for the form.
The web page contains a short piece of JavaScript that uses the IBM Forms JavaScript API to obtain the value of the <slider> element from the XForms model. The value becomes the initial value for the slider control. When you change the slider, the script updates the <slider> element in the XForms model.
Here is the complete file:
<html>
<head>
<link href="dojo/dijit/themes/nihilo/nihilo.css" rel="stylesheet" type="text/css">
<link href="dojo/dojo/resources/dojo.css" rel="stylesheet" type="text/css">
<script type="text/javascript" src="dojo/dojo/dojo.js" djConfig="parseOnLoad: true"></script>
<script type="text/javascript" src="JavaScript/LF_FormNodeP.js"></script>
<script type="text/javascript" src="JavaScript/LF_XFDL.js"></script>
<script type="text/javascript">
dojo.require("dijit.form.Slider");
dojo.addOnLoad(function() {
/* get the value of the field in the form and assign it to the variable
initvalue. The extractXFormsInstance method from the IBM Forms
JavaScript API returns a string in this format: "<slider>n</slider>"
where n is a number */
var initvalue = XFDL.getCurrentForm().extractXFormsInstance(null,
"instance('slider-value')/slider", true, true, null);
// use a regular expression to extract the number from initvalue
initvalue = initvalue.match(/\d+/);
// set up the Dojo slider
var sliderRules = new dijit.form.HorizontalRule({
count: 10,
style: "height:5px;"
},
"sliderrules");
var slider = new dijit.form.HorizontalSlider({
name: "slider",
value: initvalue,
minimum: 1,
maximum: 10,
discreteValues: 10,
style: "width:300px;",
onChange: function(value) {
// update the XForms model when the slider value changes
XFDL.getCurrentForm().updateXFormsInstance(null,
"instance('slider-value')/slider",
null, value.toString(),
XFDL.UFL_XFORMS_UPDATE_REPLACE_TEXT);
}
},
"slider");
});
</script>
</head>
<body class="nihilo">
<div id="slider">
<div id="sliderrules"></div>
<ol dojoType="dijit.form.HorizontalRuleLabels" container="bottomDecoration"
style="height:1.5em;font-size:75%;color:gray;">
<li>1</li>
<li>2</li>
<li>3</li>
<li>4</li>
<li>5</li>
<li>6</li>
<li>7</li>
<li>8</li>
<li>9</li>
<li>10</li>
</ol>
</div>
</body>
</html>
After creating the form and the web page, open the form in Viewer.
To use the HTML in pane project:
In this tutorial, you will learn how to implement two-way communication between an HTML web page inside the Modal Dialog and an XFDL form.
The project that you build in this tutorial consists of two files. One file is a simple XFDL form that contains data, a label, a field, and a button. The other file is a web page that implements a Dojo slider control and is displayed inside the Modal Dialog. The web page uses the IBM Forms JavaScript API to transfer data between the slider control and the form.
When you click the button on the form, the Modal Dialog opens and loads the web page. A script on the web page copies the value from the XForms model into the slider control. When you click Update Form in the Modal Dialog, the script copies the value of the slider control into the XForms model, which updates the value that is displayed in the field.
The first task is to verify that you have the appropriate files installed on your computer. Next, you create the XFDL form that opens the Modal Dialog. After you create the form, you create the web page that is displayed inside the Modal Dialog. Finally, you deploy and use the Modal Dialog project.
To avoid problems during the tutorial, make sure that you have Dojo Toolkit in the correct location and that you have the appropriate supporting files in place.
The folder structure that you create in this tutorial is only one of several valid structures. You can use a different structure if you want, but you must adjust filepaths in your XFDL form and HTML to suit the structure.
You can download Dojo Toolkit from the Dojo website, or use the version that is included with Webform Server. If you have Webform Server, look for dojo.ibm.standard-1.4.3-20100331.zip in C:\Program Files\IBM\Forms Server\4.0\WebformServer\redist.
ModalDialog\dojo\dijit ModalDialog\dojo\dojo ModalDialog\dojo\dojox ModalDialog\JavaScript
The form contains a label, a button, and a field. The form also contains an XForms model that supplies the value for the field.
Before you begin, make sure that you have set up your environment by creating the folder structure and copying the Dojo files and the JavaScript API files.
The button opens the Modal Dialog using the XFDL viewer.launchModalDialog function.
In a later stage of the tutorial, you will create the web page for the Modal Dialog. The web page will contain a short piece of JavaScript that uses the IBM Forms JavaScript API to obtain the value of the <slider> element from the XForms instance. The value becomes the initial value for the slider control. When the Update Form button on the web page is clicked, the script updates the <slider> element in the form before closing the Modal Dialog.
Here is the complete file:
<?xml version="1.0" encoding="UTF-8"?>
<XFDL xmlns="http://www.ibm.com/xmlns/prod/XFDL/8.0"
xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"
xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/8.0"
xmlns:xforms="http://www.w3.org/2002/xforms">
<globalpage sid="global">
<global sid="global">
<xformsmodels>
<xforms:model>
<xforms:instance id="slider-value" xmlns="">
<data>
<slider>9</slider>
</data>
</xforms:instance>
</xforms:model>
</xformsmodels>
</global>
</globalpage>
<page sid="PAGE1">
<global sid="global">
<label>Modal Dialog</label>
</global>
<label sid="LABEL1">
<value>Modal Dialog Tutorial</value>
</label>
<button sid="BUTTON1">
<value>Open Modal Dialog</value>
<layoutflow>block</layoutflow>
<custom:option xfdl:compute="toggle(activated, 'off', 'on') == '1' ?
viewer.launchModalDialog('TutorialModalDialog.html', '',
'380', '200', 'false', 'false') : ''"></custom:option>
</button>
<field sid="FIELD1">
<xforms:input ref="instance('slider-value')/slider">
<xforms:label></xforms:label>
</xforms:input>
<size>
<width>2</width>
</size>
<justify>right</justify>
<value></value>
</field>
</page>
</XFDL>
In this stage of the tutorial, you create the web page for the Modal Dialog.
The web page contains a short piece of JavaScript that uses the IBM Forms JavaScript API to obtain the initial value of the slider control. When the Update Form button on the web page is clicked, the script updates the slider element in the form before closing the Modal Dialog.
Here is the complete file:
<html>
<head>
<link href="dojo/dijit/themes/nihilo/nihilo.css" rel="stylesheet" type="text/css">
<link href="dojo/dojo/resources/dojo.css" rel="stylesheet" type="text/css">
<script type="text/javascript" src="dojo/dojo/dojo.js" djConfig="parseOnLoad: true"></script>
<script type="text/javascript" src="JavaScript/LF_FormNodeP.js"></script>
<script type="text/javascript" src="JavaScript/LF_XFDL.js"></script>
<script type="text/javascript">
dojo.require("dijit.form.Slider");
dojo.require("dijit.form.TextBox");
dojo.addOnLoad(function() {
// get the value of the field in the form, and assign it to the variable
// initvalue. The extractXFormsInstance method from the IBM Forms
// JavaScript API returns a string in this format:
// "<slider>n</slider>" where n is a number
var initvalue = XFDL.getCurrentForm().extractXFormsInstance(null,
"instance('slider-value')/slider", true, true, null);
// use a regular expression to extract the number from initvalue
initvalue = initvalue.match(/\d+/);
// set up the Dojo slider
var sliderRules = new dijit.form.HorizontalRule({
count: 10,
style: "height:5px;"
},
"sliderrules");
var slider = new dijit.form.HorizontalSlider({
name: "slider",
value: initvalue,
minimum: 1,
maximum: 10,
discreteValues: 10,
style: "width:300px;",
onChange: function(value) {
dojo.byId("sliderValue").value = value;
}
},
"slider");
dojo.byId("sliderValue").value = slider.value;
});
function update()
{
// Use the updateXFormsInstance method from the IBM Forms
// JavaScript API to update the form
XFDL.getCurrentForm().updateXFormsInstance(null,
"instance('slider-value')/slider",
null, dojo.byId("sliderValue").value,
XFDL.UFL_XFORMS_UPDATE_REPLACE_TEXT);
}
function cancel()
{
XFDL.getCurrentForm().getDialog().close();
}
</script>
</head>
<body class="nihilo">
<div style="position:absolute;left:34px;top:30px;width:302px;height:150px">
<div id="slider">
<div id="sliderrules"></div>
<ol dojoType="dijit.form.HorizontalRuleLabels" container="bottomDecoration"
style="height:1.5em;font-size:75%;color:gray;">
<li>1</li>
<li>2</li>
<li>3</li>
<li>4</li>
<li>5</li>
<li>6</li>
<li>7</li>
<li>8</li>
<li>9</li>
<li>10</li>
</ol>
</div>
<table>
<tr>
<td style="text-align:center;width:318px;height:38px;">Selected Value:
<label style="width:30px" id="sliderValue" dojoType="dijit.form.TextBox"></label>
</td>
</tr>
<tr>
<td style="text-align:center;width:318px;height:38px;">
<button onclick="javascript:update();">Update Form</button>
<button onclick="javascript:cancel();">Close</button>
</td>
</tr>
</table>
</div>
</body>
</html>
After creating the form and the web page, open the form in Viewer.
To use the Modal Dialog project:
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
IBM Corporation
5 Technology Park Drive
Westford Technology Park
Westford, MA 01886
U.S.A.
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
IBM, the IBM logo, ibm.com, Lotus, and Notes are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (® or ™), indicating US registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product, or service names may be trademarks or service marks of others.