How to use IBM Form Lookup functionAuthor: Tao Liu (firstname.lastname@example.org)
This document introduced the development of IBM Form lookup function during BPF to ICM transition project,Introduction
IBM Form provides a Lookup Extensions interface that allows custom lookup capability to be provided for individual Case fields in such a way that one of three possible results will always occur for a correctly configured lookup.
- If more than one matching record is found, a popup will be displayed showing the fields and values for each record in a tabular form. When the user clicks on one of the rows in this popup table, the configured Case field(s) will be updated with the selected value(s).
- If user select one record and click finish button, the configured Case field(s) will automatically be updated with the value(s) returned. The screen shot shown user choose the record with ID “14-123”, then the case fields “Customer Name”, “Customer Number” and “Date” is automatically updated with the value(s) returned.
This functionality is typically (but not necessarily) provided by a custom JSP page that needs to be written and configured as the Lookup Service URL for individual lookup button. Other options might include a servlet or a specially written web service.
In the guide, I will show you how to develop a custom JSP page to implement the Lookup function. It can be divided into two steps. One step is to design the lookup button on IBM Form template in the IBM Form designer. The other step is to develop the JSP page.Develop a custom lookup function by JSPStep 1. Design the lookup button on IBM Form template
You can follow below steps to Design the lookup button:
1.Create a Button on the form template.
2.Select the button, and right click it, select “Action Editor””Custom Action Editor”.
3.Input below script code in the ”Custom Action Editor”:
As the script shown, the Form API webform.launchModalDialog(String URL,String DialogName,String DialogHeight,String DialogWidth,’on’,’off’)is used to pop up the lookup Dialog, and most important parameter for the API is The URL. The URL is point to the lookup JSP page. In the sample, we used the JSP page “/Samples/SampleForms/sampleForEllen/dynamiclookup.jsp”.
Another thing you need to know is how to send the parameter the JSP page. Since the lookup results should base on the input value of the lookup field, the value of the lookup field must be send to the JSP page. We used the Http Get method here. In the script, below code is added to the JSP:
key='+. get('instance("Generated")/page1/pane1/pane5/field9', '', 'xforms')
Key is the parameter name in httpRequest. And the Form function get(reference, referenceType, scheme) is used to return the value of the case field. There are 3 parameters for the function. The first parameter “reference” is the most important. It is the reference of the case field. To get the reference value of the field, you can click the filed on the form template in Form designer, and then switch the viewer to source, and then the reference can be found, such as:
The ref is the reference. The detailed instruction of function get is put in the appendix of this document.
Note: To enable source view, you must open the perspective to Advanced Lotus Forms Designer.
And then choose the Source:
4.Find the xForm XML data model of the case fields which you want to update by lookups. The xForm XML data model can be found from Source view of the form template. For example, in the sample, we want to update the case fields “Customer Name”, “Customer Number” and “Date” by the look up. Then we can find below xForm XML data model from the source:
The “Customer Name” is field9, the “Customer Number” is amount, the “Date” is date in the xForm XML data model.Step 2. Develop the JSP page
In the WebformSampleApp.ear I have developed a Look up JSP page dynamiclookup.jsp. I will take this JSP page as an example to explain how to develop to JSP. You can follow below steps to develop the JSP page:
1.Get the lookup key from the Http request. At step 1, the value of lookup case field is send to the JSP as a lookup key, the key can be gotten from Http request by following code:
2.Obtain the lookup records and generate the table. The lookup records can be selected from Database by JDBC or file or other data source. In the sample, I used the transactionLookup.csv file as the data source, and use the dojox.data.CsvStore to select the records which start with the lookup key from the transactionLookup.csv file, and then use dojox.grid.DataGrid to generate the table.
3.After the user select one record, generate result XML and use form API XFDL.getCurrentForm().updateXFormsInstance(null, String theNodeRef, null, String theUpdateXML, XFDL.UFL_XFORMS_UPDATE_REPLACE)
to update the form fields.
In the updateXFormsInstance
API, the most important parameter is theNodeRef
It is An XPath reference to the instance (or portion of an instance) you want to insert data into or replace. An empty string indicates the default instance of the selected model. Since At step1 we have found the xForm XML data model, and we can find the XPath reference is "instance('Generated')/page1/pane1/pane5".
It is the input XML String that provides the data that replaces or adds to the XForms instance. Note that this data must be UTF-8. Since at step 1, we have found the xForm XML data model, and the XML is:
Below code can be used to generate the updateXML:
Gets the value of either an XFDL option or an element in the XForms model.Syntax
get(reference, referenceType, scheme)
The value of the form option reference or an empty string if an error occurs.Examples
In this example, get retrieves the value of "Field1", which is "gold".
The following sample demonstrates how to use the get function to retrieve a value (“Tatyana Kartoff”) from the XForms data model element “name”:
<xforms:instance id = 'loan'>
...other data model elements...
- The get function does not support XPath referencing for the entire form. Use XPath references only when getting data from the XForms data model.
- If you use the instance function to access a particular data instance, you must use the escape sequence for the quotations marks (") around the parameter. For example: get('instance("loan")/Borrower/Name', '','xforms')
- If you intend to use the XForms scheme, you must surround the parameter with single quotation marks. For example: 'xforms'
- If you attempt to get the value of an element in the XForms data model, and that element is a parent (that is, it contains child elements), then the value of the first child text node is returned.
- If you reference an item that changes, the change does not automatically trigger a re-evaluation of the function.
- The get and set functions are the only XFDL functions you should use to modify the XForms