 | Level: Intermediate Gu Yi (guyi@cn.ibm.com), Lead Software Engineer, IBM
Yi Ting Shan (shanyit@cn.ibm.com), Software Engineer, IBM
08 Jan 2008 In IBM Lotus Forms V3.0, a new JavaScript API lets you can manipulate and control the behavior of embedded Lotus Forms with simple HTML and JavaScript in a browser. A new event listener mechanism lets you write custom features to handle the forms and allows easier integration with other systems.
This article introduces the JavaScript API in IBM Lotus Forms, describes the mechanism of the API, and provides examples of how to use the API. You should be familiar with IBM Lotus Forms.
What is the JavaScript API?
To support outside access to IBM Lotus Forms in HTML forms or other forms, a new JavaScript API has been added to the Lotus Forms family. This JavaScript API lets you manipulate a form displayed within an HTML file. You can render the form with the IBM Lotus Forms Viewer or the IBM Lotus Forms Webform Server. With the JavaScript API, you can integrate Lotus Forms with other applications more easily.
Compared with the core Java and C APIs, the JavaScript API has a similar FormNodeP and XFDL library that provides a standard load and set/get type access to the form. The interface names of these libraries are the same as the name for the core API. Besides the FormNodeP library, a new event library is added to the JavaScript API. This event library allows JavaScript to be notified when certain events occur on the form. This listener mechanism enables the HTML pages to interact with the embedded Lotus Forms closely. Currently, the API supports four events: onBlur, onChange, onClick, and onFocus.
The JavaScript API working mechanism
To make JavaScript event listeners work, an ActiveX control is used as an interface to pass the information between the JavaScript code and the embedded Lotus Forms Viewer as shown in figure 1.
Figure 1. Event handling mechanism
Figure 1 describes the event handling procedure using the JavaScript API and Lotus Forms Viewer. When an event adding method is called, the JavaScript API registers the event to the Lotus Forms Viewer event watch list through the ActiveX control. When receiving a windows event for an item, Lotus Forms Viewer checks to see if it's an event to watch. If it is, it is put into the event queue, and the ActiveX control is notified that something is in the queue. The ActiveX control gets the event and builds a single browser event to fire to the internal event handler of the JavaScript API. Then the internal event handler calls the registered event listener method for further processing.
Installation of the JavaScript API
There is no separate package for installing the JavaScript API. After you have installed Lotus Forms Viewer V3.0 and Lotus Forms Webform Server V3.0, you can find the JavaScript API library in the following locations:
<<Viewer Installation Folder>>\JavaScript
The Viewer Installation Folder is the installation folder of Lotus Forms Viewer such as C:\Program Files\IBM\Lotus Forms\Viewer\3.0.
<<Webform Server Installation Folder>>\redist
The Webform Server Installation Folder is the installation folder of Lotus Forms Webform Server such as C:\Program Files\IBM\Lotus Forms\Server\3.0\Webform Server\redist.
Table 1 lists the three files that can be found in these directories.
Table 1. Library files
| File name | Description |
|---|
| LF_FormNodeP.js | Interface for all the normal FormNodeP and new event-based functions |
|---|
| LF_ViewerScript.js | Interface for registering / deregistering forms |
|---|
| LF_XFDL.js |
Provides addViewer() function for creating HTML object tags
No longer needs to have nested object tags that work for both Microsoft Internet Explorer and Mozilla Firefox
Removes the “Click to activate this ActiveX control” warning from Microsoft Internet Explorer
|
|---|
Interface of the JavaScript API
The three library files define the interface for handling embedded forms. The following is a brief introduction to the interface.
ibmforms array
The ibmforms array is a global associate array defined in the file LF_XFDL.js. Using XFDL.registerForm(), you can register the form to the global variable to access all the registered forms by referencing the ibmforms array.
The XFDL class
The XFDL class defines a set of constants and functions that are used to handle the form itself. The functions registerForm() and deregisterForm() are defined in the XFDL class. You can find the whole class in the file LF_XFDL.js.
The FormNodeP class
The class FormNodeP defines the methods that you can use to manipulate a form node. This class is similar to the methods defined in core Java and C APIs. Each item and option on the form is a FormNodeP node. The interface of FormNodeP is defined in the file LF_FormNodeP.js. Most of the traditional FormNode handling methods can be found there as shown in table 2.
Table 2. Form node methods
| Method | Description |
|---|
| dereferenceEx() | Locates a particular FormNodeP |
|---|
| setLiteralByRefEx() | Finds a particular FormNodeP as specified by a reference string, and sets the literal if the FormNodeP is found |
|---|
| getLiteralByRefEx() | Finds a particular FormNodeP as specified by a reference string, and returns the literal of the FormNodeP if the FormNodeP can be found |
|---|
The JavaScript API serves as a bridge between the HTML files and the embedded Lotus Forms. A full set of events is defined to notify the HTML context when the states of the embedded form change. To support the event system, a new collection of event registering methods is added to the class FormNodeP.
Table 3 lists some useful event registering and deregistering methods.
Table 3. Event registering and deregistering methods
| Method | Description |
|---|
addOnBlur () /
removeOnBlur () | Registers/deregisters an event handler for the onBlur event. The onBlur event occurs when an item loses focus. |
|---|
addOnChange () /
removeOnChange () | Registers/deregisters an event handler for the onChange event. The onChange event occurs when the value of an item changes. |
|---|
addOnClick () /
removeOnClick () | Registers/deregisters an event handler for the onClick event. The onClick event occurs when an item is clicked with the mouse. |
|---|
addOnFocus () /
removeOnFocus () | Registers/deregisters an event handler for the onFocus event. The onFocus event occurs when an item gets focus. |
|---|
JavaScript API usage samples
In this section, some samples show how to use the JavaScript API with Lotus Forms Viewer and Lotus Forms Webform Server.
Using the JavaScript API with Lotus Forms Viewer
To use the JavaScript API with Lotus Forms Viewer, you need to create an HTML file with an embedded form. The following detailed steps show how to create a sample HTML file to convert currency value based on the exchange rate set in the HTML file.
- Create the HTML file.
First, create the HTML file with an input field and a <div> section. The <div> section is reserved to embed the sample form later. Place an <input> textbox where users can enter their ratio and an <input> button to set the ratio to the embedded form.
Listing 1. Creating the HTML file
<P>
Ratio Today = <INPUT id='field_ratio' style='width:160;height:25'
type='textbox' value="2.0230"></INPUT>
<INPUT id="button_ratio" style='width:100;height:25' value='Set The Ratio'
type='button' onClick='setRatio();'></INPUT>
</P>
<div id="divID">
</div>
<P id="result"></P>
|
- Embed the form into the HTML files.
Place the XFDL form on the HTML file surrounded by a pair of <script> tags. Notice that the content of the form should be encapsulated in an HTML comment.
Listing 2. Embedding the form in the HTML file
<SCRIPT language="XFDL" id="XFDLData" type="application/vnd.xfdl; wrapped=comment">
<!--
<?xml version="1.0" encoding="UTF-8"?>
//Here is the XFDL form content
-->
</SCRIPT>
|
- Include the library files.
The library files provide the basic functions that users can employ to manipulate the embedded form. They are needed to import in the HTML files to run the application.
<SCRIPT TYPE="text/javascript" SRC="LF_XFDL.js"></SCRIPT>
<SCRIPT TYPE="text/javascript" SRC="LF_FormNodeP.js"></SCRIPT>
<SCRIPT TYPE="text/javascript" SRC="LF_ViewerScript.js"></SCRIPT>
|
- Add the form into the <div> section.
To make the form visible, you must create HTML object tags for the embedded form. In older versions of Lotus Forms, you must add these tags manually and create different sets of tags for Microsoft Internet Explorer and Mozilla Firefox browsers. With the JavaScript API, a utility function called addViewer() eases the work.
Listing 3. Adding the form into the <div> section
<P>
Ratio Today = <INPUT id='field_ratio' style='width:160;height:25'
type='textbox' value="2.0230"></INPUT>
<INPUT id="button_ratio" style='width:100;height:25'
value='Set The Ratio' type='button' onClick='setRatio();'></INPUT>
</P>
<div id="divID">
<script language="Javascript">
addViewer("divID","sample_form",450,400,"XFDLID","XFDLData",
"detach_id", "12354678901234567890");
</script>
</div>
<P id="result"></P>
|
- Initialize the form, and register the event handler when the HTML file is loaded.
The onLoadForm() function is called whenever the HTML file is loaded to the browser. The onLoadForm() function calls addEvent() to register the fieldOnChange() callback function to the XFDL field in the embedded form, and the function setRatio() is invoked when the user clicks the Set the Ratio button.
Listing 4. Initializing the form
var formName = "sample_form";
function onLoadForm()
{
var aForm = new FormNodeP(formName);
//register the formName
XFDL.registerForm(aForm,formName);
addEvent();
}
//set the onload event
if(window.addEventListener)
window.addEventListener('load', onLoadForm, false);
else
window.attachEvent('onload', onLoadForm);
function addEvent()
{
var fieldNode;
var s;
var theForm = ibmForms[formName];
fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD_USD", 0,
FormNodeP.UFL_ITEM_REFERENCE, null);
//add the OnChange event listener
fieldNode.addOnChange(fieldOnChange);
}
function fieldOnChange(xfdlEvent)
{
var theForm = ibmForms[formName];
//get the field value on the XFDL
var gbpValue = theForm.getLiteralByRefEx(null, "PAGE1.FIELD_GBP.value", 0, null);
var usdValue = theForm.getLiteralByRefEx(null, "PAGE1.FIELD_USD.value", 0, null);
var ratioValue = theForm.getLiteralByRefEx(null, "global.global.custom:ratio", 0, null);
document.getElementById("result").innerHTML = gbpValue +
" equals to " + usdValue + " at the ratio " + ratioValue + "." ;
}
function setRatio() {
var theForm = ibmForms[formName];
var ratio = parseFloat(document.getElementById("field_ratio").value);
if (isNaN(ratio) || ratio < 0) {
alert("Please enter a positive number as the ratio.");
}else {
//set the value on the form
theForm.setLiteralByRefEx(null, "global.global.custom:ratio",
0, null, ratio.toString());
}
}
|
- Test the result.
Open the HTML file in your browser. Modify the amount of the GBP field on the form. The corresponding value of the USD field changes consequentially as shown in figure 2. Because you registered an onChange event to the USD field, the event handler fieldOnChange() is invoked. It retrieves the amounts and ratio from the embedded form and formats them into a readable string on the bottom of the HTML file.
Figure 2. Testing the result, part 1
Then we can modify the ratio. Try adjusting the value in the field called Ratio Today from 2.0230 to 2.1230 and clicking the Set the Ratio button as shown in figure 3. You can see the USD field on the form; the summary text on the bottom changes accordingly.
Figure 3. Testing the result, part 2
For the detailed code, refer to the download file.
Using the JavaScript API with Lotus Forms Webform Server
Besides using the JavaScript API with Lotus Forms Viewer V3.0, you can also use it with Lotus Forms Webform Server V3.0 to interact with the rendered form. There are some differences between using the JavaScript API in Lotus Forms Viewer and in Lotus Forms Webform Server.
The Lotus Forms Webform Server translator supports the JavaScript API out of the box, but the Web application still needs to make JavaScript API calls. It is needed to import JavaScript libraries in JSPs as well. After calling the JavaScript API, Lotus Forms Webform Server passes the call back to the translator. To implement the JavaScript function, add the following method to register the form with the proper ID in the servlet that returns the rendered form:
this.setFormName(response, "myFormID");
setFormName() is one interface in com.ibm.form.webform.framework.servlet.IBMWorkplaceFormsServer Servlet that every customized servlet class must extend. To use the JavaScript API in a portlet that extends IBMWorkplaceFormsServerServlet, you must call this method.
Listing 5 shows the code snippet in the servlet.
Listing 5. Using the JavaScript API in a servlet
//set to use the HTML
this.useHTML(response, true);
//set the response content type
response.setContentType("application/vnd.xfdl");
//set the file name which is the default name to save rendered in Webform Server
this.setFilename(response, fileName);
//set the id of the form
this.setFormName(response, "myFormID");
OutputStream responseOS = response.getOutputStream();
//write the file to response output stream
|
For detailed usage and the API of IBMWorkplaceFormsServerServlet, refer to the Lotus Forms product documentation.
One way to use the JavaScript API to manipulate the rendered HTML form is to use two frames in the HTML file. One frame refers to a customized application page that interacts with Lotus Forms. It may contain the JavaScript API calls. The other frame refers to a servlet converting the XFDL to HTML. Here is a sample:
<FRAME SRC="/application/ViewFormServlet" name="bottom_frame">
This code refers to the customized servlet that converts the XFDL to HTML. The JavaScript code to manipulate the form is the same as the code used for Lotus Forms Viewer. The behaviors of the functions are also the same.
Conclusion
The Lotus Forms JavaScript API is a new API that integrates Lotus Forms with other forms such as HTML. It adds an event listening mechanism between Lotus Forms Viewer and JavaScript that gives you more flexibility when developing forms.
Download | Name | Size | Download method |
|---|
| exercise.zip | 14KB | HTTP |
Resources
About the authors | | | Gu Yi is a Lead Software Engineer on the IBM Software Services for Lotus (ISSL) Emerging Services Team in IBM's China Development Lab. Gu Yi has been involved in IBM Software Services projects since 2005 and has participated in several service projects involving IBM Lotus Forms. In addition, Gu Yi has two years of experience working with IBM WebSphere Portal and has four years of industry experience in J2EE development. You can reach him at guyi@cn.ibm.com. |
| | | Yi Ting Shan is a software engineer from IBM's China Development Lab (CDL). He has more than two years' experience in software development and project analysis. Currently, he works on the IBM Software Services for Lotus (ISSL) Emerging Services Team. |
Rate this page
| |
