Creating forms in WEMPe 

• Preeti Sharma (sharma.preeti@in.ibm.com)
• Kiran Rao (kiran.rao@in.ibm.com)

IBM WebSphere Everyplace Mobile Portal enable (WEMPe) is a product which extends WebSphere Portal to deliver optimized web content to a wide range of mobile handsets. WEMPe follows a “write once, render many” approach. A portlet is coded only once and it renders on a variety of mobile handsets.

WEMPe greatly reduces the development effort required to get a mobile portal up and running to support thousands of devices; and at the same time, support traditional PC browsers too, since a suitably designed portlet can serve both the mobile channel and web channel.

Mobile web sites can be divided into two categories based on the mode of interaction with the user:

• Navigation-oriented: In such sites, the input from the user is primarily in form of “clicks” to navigate through the site. There is not much in form of user-entered input. Examples of such sites include content-centric sites and news sites.
• User-input oriented: These are sites where the service provided depends on some form input from the user. Examples include mobile banking and stock quote sites.

The key entities in the user-input oriented sites are forms. This article provides various tips & tricks, best practices to follow, frequently faced problems/limitations and ways to work around them when using forms in WEMPe. It includes XDIME code samples to demonstrate these best practices.

Specifically, this article explores the following topics:

1. Handling events on multiple buttons on a form in WEMPe without using javascript.

2. Creating multilingual forms in WEMPe.

There are two main artifacts one needs for creating and displaying a form in WEMPe

1. A Form format in the page canvas
2. An element in the JSP which binds to the form in the canvas

The Form format is created in the layout policy using the Mobile Portal Toolkit. Here is a screenshot of the layout canvas with the Form.

The skeleton XDIME code for this form is as follows:

 <xfform name=”frm” … … >

 //Code for the Form UI Elements here

</xfform>

Notice that the value of the name attribute (i.e., “frm”) on the xfform element is exactly the same as the name of the Form in the layout policy. It is this name attribute that binds the xfform to the specific form format on the canvas.

The various form UI elements used in this example are:

• xfaction – this is used to create a button.
• xftextinput – this is a text box, the XDIME equivalent of HTML’s
• xfsiselect – this is used for exclusive selection. It can be formatted to render either as a radio-box or a combo-box.

Please refer to the WEMPe InfoCenter for more details about the various for UI elements.

http://publib.boulder.ibm.com/infocenter/pvccom/v6r0m1/topic/com.volantis.mcs.eclipse.doc/wag/xdime_pr_er.html

Handling Multiple Buttons on Forms.

When there is a requirement to have multiple buttons associated with a form, HTML developers would use Javascript to keep track of the button that has been clicked and the action that has to be performed. A value would be passed from the JSP to the processAction method to identify the event. However, it is not recommended to use JavaScript for mobile applications since there are varied numbers of mobile devices, of which some support JavaScript and some do not. Also, various devices differ in the version of Javascript that they support.

The following technique can be used to handle multiple buttons on a form without using JS in WEMPe. This technique is based in the premise that when there are multiple buttons on a form, and one of them is clicked, only the button which is clicked has a non-null parameter value. This is explained in more detail with the help of snippets as follows:

1. In the JSP, define a button using the xfaction tag and give caption and name values.



<xfaction type="submit"

   caption="UPDATE DETAILS" 

    name="UPDATE_DETAILS"

    captionPane="pane_cap.7" 

     entryPane="pane_cap.7" />

2. In the portlet’s action processing method, do a request.getParameter(), passing the button name as parameter. This returns the caption of the button clicked. When there are multiple buttons only the caption for the clicked button will be a valid value. The captions for all other buttons will be null.

String btnclicked = actionRequest.getParameter(“UPDATE_DETAILS”)

if (btnclicked.equalsIgnoreCase(“UPDATE DETAILS”))

{

    //perform action

}

Example

Please refer to the attached Project Interchange with source code for the complete working sample. Here, we look at the relevant sections of the sample, i.e., the JSP and the Portlet java code.

The scenario used for this example is that of an employee database. A user who is logged in to the system is presented a text box to enter an employee code. The user can then click on the “Get Emp Details” button to get the employee details. This refreshes the page and fetches the employee record. It details displayed include the employee’s band, Account number, Department etc.

The first screenshot displays the JSP used for rendering such a form. Notice how multiple buttons are defined within a single form by including multiple tags within a single element.

In the processAction() method, action handling is performed based on the caption of the clicked button.

As we saw in the preceding sections, fetching the captions of the buttons is a good way to ascertain the button which was the source of the action. However, this presents a challenge in case of multilingual forms. For example, how does one type in a caption which is in a double-byte language, in the Java source?

The answer is to simply examine the null-ness of the caption. Remember, as has been pointed out earlier, all caption values, except that for the button which has been clicked, are null. Hence, calling the equalsIgnoreCase() is not really necessary. All that is needed is to find that button for which the getParameter() is non-null. This is the button which has been clicked!

 

String btnclicked = actionRequest.getParameter(“UPDATE_DETAILS”)

if (btnclicked!=null)

{

    //perform action

}

The screenshot below shows the previous code, re-factored to suit cases where the form is multilingual.

Conclusion

To summarize what’s been discussed in this article:

• Creating a form in WEMPe involves

1. Adding a Form within the canvas layout
2. Coding the JSP using the XDIME xfform tag; creating actions with the xfaction tag; and associating the xfform with the layout using the name attribute
• If it is required to have multiple buttons within a form, one can take advantage of the fact that only the button which has been clicked will return a caption when the getParameter() method is invoked. All other buttons return null values
• The same principle can be applied for having multi-lingual forms with multiple buttons.

Extras

The article is accompanied by a source code project interchange (Forms.zip) and a deployable portlet (Forms.war)

 https://greenhouse.lotus.com/files/app/person/4c98c940-b16a-102c-87bf-946fab8fcf80/file/f63d6144-93e6-4ff0-9805-d1c86e24155f|Creating_Forms_WEMPe_extras.zip">Creating_Forms_WEMPe_extras.zip">https://greenhouse.lotus.com/files/app/person/4c98c940-b16a-102c-87bf-946fab8fcf80/file/f63d6144-93e6-4ff0-9805-d1c86e24155f|Creating_Forms_WEMPe_extras.zip