Customizing HTML-Dojo forms for Business Space powered by WebSphere

IBM® WebSphere® Process Server V6.1.2 has a new component called Business Space powered by WebSphere, which bridges the gap between Web 2.0 and human-centric business process management (BPM). With Business Space, you can create Web 2.0 applications by using multiple widgets to unite the functionality of WebSphere Process Server, WebSphere Business Monitor, and other products in one Web front end. To display human tasks in Business Space, you generate a user interface in WebSphere Integration Developer, which results in an HTML-Dojo form that might not immediately fit your needs. This article describes how you can customize the HTML-Dojo form when adapting a business integration solution, and demonstrates common modifications with short examples. This content is part of the IBM WebSphere Developer Technical Journal.

Klaus Schaefers (KSCHAEF@de.ibm.com), IT Specialist, IBM

Klaus Schaefers photoKlaus Schaefers is an IT Specialist in IBM's Development Center in Boeblingen, Germany. His job responsibilities include the development of Eclipse plug-ins and Ajax components. His current interests are Web 2.0 and software development in general. He graduated from the University of Münster with a graduate degree in Information Systems.



Marius Kreis (marius.kreis@de.ibm.com), IT Specialist, IBM

Marius Kreis photoMarius Kreis is an IT Specialist in IBM's Development Center in Boeblingen, Germany, and working for System Verification Test, WebSphere Integration Developer. His previous assignment at IBM was the development of a Web application framework for the Open Source project SBLIM, which offers a Web-based Enterprise Management (WBEM) instrumentation for Linux. His current interests are still in Web application development, Linux, and software engineering.



09 April 2009 (First published 08 October 2008)

Also available in Chinese

Introduction

With Business Space, users can work with business processes that require human interactions, which are modeled as human tasks. For each task, the client settings in the human task editor refer to a user interface. This user interface is displayed so that users can interact with each task. IBM Lotus® Forms and HTML-Dojo forms are supported, but for the scope of this article we will focus on the HTML-Dojo forms.

To understand how this user interface for the human task works, it helps to understand certain facets of human tasks. Human tasks expose an interface to a runtime environment that consists of an input and output message. In Business Space, a human task can be displayed in three modes. In the first mode, called init in this article, the user wants to start a process through a human task and does so by entering and then submitting initial data.

To work on a human task that someone has already started working on, the user works in the second mode, called the edit mode in this article. This human task might have been assigned to the user or the user might have claimed it. The business user must read the input message and then enter a correct output message.

The user works in the third mode, called the view mode in this article, when he or she wants to see the status of a human task or the result of another human task that is finished. In the view mode, the user does not enter information; he or she just reads the input message and the output message.

Now we will explain the different requirements for the visualizations in each mode of operation. In the init mode, the user enters only the required information in the input message. In this mode, the user cannot see or enter data in the output message. In the edit mode, the user can see both the input and output messages. However, in this mode, the user cannot change the information that the input message delivers. In the view mode, the user sees the information for each type of message but cannot alter it. The input fields are locked by default.

Figure 1 summarizes the different modes.

Figure 1. Summary of the init, edit, and view modes
Init, edit, and view modes

Human tasks can have the same message type for both input and output. For example, a user might want to review the input data and copy the reviewed and possibly changed data into the output form of the review processes. In this case, the message is handled in a way that makes it easier for the user to work with the HTML-Dojo form. The time and effort of copying all of the input data to the output form is saved by prepopulation. The view mode remains unchanged; the business user just enters the information as he did to initiate a task. The difference is in the edit mode. The user thinks that he is working in the same form that the initiator of the task used because the user interface looks the same and already contains the data that the user would update. To achieve this user interface, no separated input and output message is displayed. Instead, the input form is hidden and its data is used to prepopulate the output form. Figure 2 summarizes how the user interface is displayed if the human task has the same input and output message.

Figure 2. Summarizes how the user interface is displayed if the human task has the same input and output message
Summarizes how user interface is displayed

Prerequisites

To work with Business Space, you need to install:

  • WebSphere Integration Developer V6.1.2
  • WebSphere Process Server V6.1.2

Understanding the generated HTML

As we described before, each human task consists of an input and an output message, which the HTML form must also reflect. Therefore, the generated HTML pages contain a section for the input message and another section for the output message. These message sections are compiled from Dojo widgets that are used to display the input elements that the user interacts with. Both sections are wrapped in a <form> element. Furthermore, the HTML pages that are generated in WebSphere Integration Developer contain a wrapping <div> element around the form and a cascading style sheet (CSS) definition. Figure 3 depicts the generated HTML-Dojo form:

Figure 3. Generated HTML-Dojo form
Generated HTML-Dojo form

Because all generated pages use the same CSS classes, a change in one file affects all HTML pages in Business Space unless you use an extra <div> element with a custom CSS class. With this extra <div> element, you can specify the CSS selectors that address only the elements in this scope.

Business Space assigns different CSS styles to the <form> element, depending on the mode (init, edit, or view) that the form displays in; therefore, the <form> element must not be removed. The class names are the mode names init, edit and view. With the <form> element, how the message display is controlled. Listing 1 shows three CSS definitions:

Listing 1. Three CSS definitions
   	    .http_//myNameSpace .init div.businessObject {
      		visibility :collapse;
			display: none;
	    }	    

	    .http_//myNameSpace .edit div.businessObject {
			
	    }	    

	    .http_//myNameSpace .view div.businessObject {
			color: gray;
	    }

The first line of each definition consists of three selectors that narrow the number of affected elements down.

The first selector, .http_//myNameSpace, is the class of the surrounding <div> element, which narrows the selection down to the elements that are included in this <div> element and, therefore, excludes all elements in Business Space that are not part of this HTML form.

The second selector, .init, .edit or .view, specifies the mode of operation for which this CSS definition is valid.

The third selector, div.businessObject, is an example class of one <div> element that is included in the form, one that has the class businessObject. This selector could be any other element in the form that you want to define a CSS for.

These selectors define the style differently in Business Space.

The <div> element with the class businessObject will not be visible if the <form> node has the class init. If the <form> is displayed in the edit mode, the form has the class edit and the element, therefore, is displayed. In view mode, the <form> has the class view and the <div> element is visible, although the text will be gray.

The next important concept to understand is how the messages are constructed out of the message fields. The following text is a sample of what a generated Dojo widget definition looks like:

Listing 2. Text is a sample of how a generated Dojo widget definition looks
<input type="text" name="output1/foo/bar" value=""
       dojoType="dijit.form.ValidationTextBox" regExp=".*"
       id=" http_//myNameSpace " sdoMessageType="output"
       sdoPrepopulation="/input1/foo/bar" required="true"
       class="fieldInput"/>

In WebSphere Integration Developer 6.2, the input element has an additional attribute called "sdoPosition", which is described in the table below.

In addition to the typical HTML-Dojo attributes, this widget definition contains custom attributes that each have a semantic in Business Space. Table 1 contains a summary of the attributes and their usage.

Table 1. Summary of the attributes and their usage
AttributeSemantic
nameThe name attribute binds the <input> element to an element of the input message. The binding will be specified in as an XPath-like statement that refers to a specific part of the message that this input field represents. Note: If you change these statements, runtime failures will occur when a message is created out of the form.
sdoMessageTypeThe sdoMessageType attribute specifies whether the widget belongs to the input or output message. It is required for enabling or disabling form elements depending on the current mode. It can have the values input and output.
requiredThe required attribute specifies whether the widget contains mandatory fields. If the required attribute is set to true, the user cannot submit the form until he has entered valid data.
sdoPrepopulationThe sdoPrepopulation attribute specifies that the value of the widget will be prepopulated with a value of the input message, saving the user the effort of copying every value from the input to the output form. The message contents are automatically generated into the HTML forms if the interface of the human task has identical message types for both the input and output. You can use the sdoPrepopulation attribute only for widgets that belong to the output message, and then only for when the user is in edit mode. The binding is specified as an XPath-like statement.
sdoPositionThis new attribute in WebSphere Integration Developer 6.2 specifies a sequence number for all input fields. This switches the ordering of the fields while still maintaining the correct order upon later form processing. Therefore, you cannot change this number.

Understanding the loading process

When a user works with a human task, Business Space loads the HTML-Dojo form that is specified in the client settings of the human task. When the page is loaded, the raw HTML code is preprocessed, which includes, among other actions, setting the class attribute of the <form> node. Depending on which mode the page is displayed in, the value is set to init, edit, or view. Then the prepared HTML code is added to the DOM tree, which triggers the Dojo parser to render the new fragment of the page. Hereafter, Business Space loads the input and output message if the page is opened in edit or view mode. If the messages are not empty, the content is added to the Dojo widgets on the page. Notice that the Dojo widgets of the input and output are enabled or disabled depending on the mode that the HTML page is displayed in.

In WebSphere Integration Developer 6.2, references in the source HTML form, which point to JavaScript files or Dojo widgets, will be added to the page context. This enables you to use custom JavaScript and custom widgets.

However, if a business user has just claimed a task, he could not have entered any data for the output message. In this case, Business Space receives an empty message and copies values form the input message to the Dojo widgets, placing a matching value in the sdoPrepopulation attribute.

Now we will introduce a sample scenario that we will use later to illustrate typical customizations of the HTML form.


Sample scenario

Imagine that you want to modify the user interface of a human task that is used to approve incoming money transfers. Figure 4 shows the approveTransfer operation in this human task.

Figure 4. The approveTransfer operation of a human task
The approveTransfer operation

Figure 5 shows three business objects: ApprovalRequest, BankTransferInformation, and Remark. BankTransferInformation, which is a child business object of the ApprovalRequest business object, contains fields that describe the details of the transfer (such as who it is from and who is the beneficiary) as well as metadata (such as when it was received and what the phone number and e-mail address are). Either the PhoneNumber field or the EmailAddress field stores contact details, depending on how the request is received. An additional array with child business objects of type Remark stores comments from the employees who handle the transfer.

Figure 5. ApprovalRequest, BankTransferInformation, and Remark business objects
Shows three business objects

Common uses

Most customizations do not require special knowledge about Business Space, only experience in Web development, so we will focus on some issues that might arise because of how Business Space handles HTML pages.

Most of the customizations that work in a typical HTML page will work in Business Space as long as these changes are restricted to the content between the body tags or the CSS definitions. All of the other changes outside of these tags are ignored.

The most typical customization is to rename the input element labels because the names are originally derived from the business objects, which are not the names that you want to expose to the business user. You can rename the input element labels by editing the HTML file with a text or HTML editor and changing the value between the label tags.

In addition, you can include images using the img tag, referring to files using both absolute and relative URLs. Using relative URL makes developing the HTML pages easier because you can test them in WebSphere Integration Developer.

Furthermore, you can externalize the style sheets, which is useful when all human task forms should have a common appearance. Instead of changing the CSS in each file, you can remove the existing CSS from the pages, replacing the CSS with the following import statement that refers to a common style sheet, style.css:

<style type="text/css">
	@import "style.css";
</style>

The following examples show you how to handle customizations that you would handle differently in typical HTML forms.

Example 1: Removing or hiding fields

Imagine that you want to remove the EmailAddress field from the generated HTML form because the bank wants this field kept empty for transfers that are received over the phone. In a typical HTML form, you would remove the EmailAddress field from the generated HTML, either by deleting it directly from the source code or by using a visual tool, such as the Page Designer included with WebSphere Integration Developer. The corresponding field in the business object is automatically set to null.

However, you should not remove an input field when the field is required or should be set to a default value because the field is required. Instead, you must hide the particular field type and set its value attribute. Because attributes other than type, name, and value are used only when the field is displayed, the necessary HTML tag is short:

<input type="hidden" name="/transferInformation/EmailAddress"
       value="no address provided" />

In this case, the EmailAddress field is not displayed, although the value “no address provided” is submitted.

Example 2: Prepopulation

Imagine that you want to manually retrofit prepopulated fields into a generated HTML form. By default, prepopulation is enabled when an interface contains the same business object type for the input and output. In other cases, such as when the input is a child business object of the output, prepopulation is not triggered. Therefore, you must add prepopulation manually.

The ApproveTransfer interface is one of these cases. The BankTransferInformation input business object is a child business object of the ApprovalRequest output business object (see Figure 5). Therefore, you can prepopulate all of the fields of this child business object with the values from the input business object, by following the steps described in the paragraph below.

As mentioned before, the sdoPrepopulation attribute of the <input> tag determines which part of the input message should be used to initialize the value of the field. In this example, you want to populate the Amount field of the BankTransferInformation child business object with its corresponding value of the input message. To accomplish this, find the <input> tag for the field that you want by searching for the XPath expression /output/Transfer/Amount. Then, change the sdoPrepopulation attribute to the XPath that points to the correct part of the input message. In this case, the value is /input/Amount. The updated piece of HTML would look like this:

Listing 3. Updated HTML
<input type="text" name="/output/Transfer/Amount" value=""
       dojoType="dijit.form.ValidationTextBox" regExp="\d*([.|,]\d*)?"
       sdoMessageType="output" required="true" class="fieldInput"
       sdoPrepopulation="/input/Amount"/>

If you are not sure about the correct XPath, you can look it up in the input part of the generated HTML file. It contains <input> elements for each field of the input business object that has the correct XPath statements as the value of their name attributes.

Example 3: Changing the input field order

The order of the input fields on the generated page depends on the order in which the corresponding fields are defined in the business object definition. Because these fields are typically ordered arbitrarily, without usability considerations, you might want to re-order the input fields to better suit the user’s needs.

In WebSphere Integration Developer 6.2, the order of the input fields is stored in the attribute "sdoPostion". Therefore, changing the sequence of the input fields will no longer render the form unusable.

As mentioned above, you can completely customize the appearance of HTML-Dojo form by editing the HTML and CSS; however, editing the generated HTML source code will make the resulting file incompatible with Business Space. Because business object generation using the data in the form relies on the sequence of the fields, the order of the input elements in the HTML must not change. Therefore, rearrange the input fields using a custom CSS class with relative positioning.

In the following example, two new CSS classes, fromAccount and amount, have been inserted to define a position offset of 40 pixels, which is the approximate distance of two consecutive rows. Elements of the fromAccount class will move downwards by 40 pixels and elements of the amount class will move upwards; therefore, switching the vertical position of these classes. To switch an input field with its label, assign the CSS classes to both the field and the label as illustrated in Listing 4:

Listing 4. HTML code shows the assignment of the CSS classes to both the field and the label
	<style type="text/css">
...
		.fromAccount {
			position:relative;
			top: 40px;
		}
		
		.amount {
			position:relative;
			top: -40px;
			}
		
	</style>

...
		<div class="http___FinancialInstituteApproveTransfer">
			<form dojoType="dijit.form.Form" class="view">
				
				<div class="businessObject_input" SDOMinOccurrence="1"
					SDOMaxOccurrence="1">
	<h3 class="input">input</h3>
	<div class="fieldContainer_input">
	<label class="fieldLabel fromAccount" for="http___…WidgetID">
		FromAccount *
	</label>
	<div class="fieldInput fromAccount">
		<input type="text" name="/input/FromAccount" value=""
			dojoType="dijit.form.NumberTextBox" id="http___…WidgetID"
			constraints="{min:-2147483648,max:2147483647,places:0}"
		 sdoMessageType="input"  sdoPrepopulation="" required=
     "true" class="fieldInput"/>
	</div>
</div>
<div class="fieldContainer_input">
	<label class="fieldLabel amount" for="http___…WidgetID">
		Amount *
	</label>
	<div class="fieldInput amount">
		<input type="text" name="/input/Amount" value=""
			dojoType="dijit.form.ValidationTextBox" id="http___…WidgetID"
			regExp="\d*([.|,]\d*)?"
			sdoMessageType="input"  sdoPrepopulation="" required="true"
			class="fieldInput"/>
	</div>
</div>
...

Example 4: Working with array containers

As mentioned earlier, the BankTransferInformation business object can have multiple Remarks business objects as children. Business Space supports this scenario by using a Dojo widget, the bpc.widgets.FormArrayContainer, which contains the input elements for the child business object and enables you to add the input elements multiple times. Inspecting the generated source code, you can see the following lines in Listing 5:

Listing 5. Generated source code
<div name="/input1/Remarks[]" class="arrayBO_input" 
	dojoType="bpc.widgets.FormArrayContainer" 
sdoMessageType="input" SDOMinOccurrence="0" SDOMaxOccurrence="-1">
  		<img dojoAttachPoint="collapseImage"></img>
  		<span class="arrayLabel_input">Remarks</span>
<button dojoType="dijit.form.Button" style="color: green" 
class="addButton button_input" title="+">
<b>+</b>
</button>
   		<button dojoType="dijit.form.Button" style="color: red"
class="removeButton button_input" title="-">
<b>-</b>
</button>
  		<div dojoAttachPoint="ArrayTemplate" class="arrayTemplate">
			...
<input type="text" name="/input1/Remarks[]/Name" value=""
dojoType="dijit.form.ValidationTextBox" regExp=".*"
				sdoMessageType="input"  sdoPrepopulation="" 
required="false" class="fieldInput"/>
			...
		</div>
</div>

The important element to customize is the <div> element with the arrayTemplate class. When you click the plus sign (+), the inner HTML code is copied into a new <div> element, which is added as a new child business object to the FormArrayContainer so that you can customize the HTML as long as you meet the restrictions that we described in the previous examples.

Example 5: Changing the input field widgets

WebSphere Integration Developer selects the best-fitting Dojo widget for each field of the business object, depending on data type. In some cases, these automatically selected widgets do not fit your requirements. Luckily, you can easily change the widgets as long as they are the standard Dojo widgets at the Dojo Web site. The only exception is the TextArea, which cannot be disabled because of limitations in the version 1.02 release of Dojo. Due to technical restriction, it’s not possible to add custom widgets to the page. Adding those widgets prevents the entire form from being shown.

In WebSphere Integration Developer 6.2, you can use custom JavaScript files and custom widgets.


Testing the HTML form faster using WebSphere Integration Developer

Testing the customized HTML file for the first time involves completing the steps that you would follow to deploy the Web project that contains the file to the server. After deployment, the form is displayed when the associated human task opens, for example when the user starts a new task. When the human task opens, the HTML page is loaded and is displayed in the Task Information widget.

If the form requires further customizations, you can enable “Validate, update deploy code, and update running servers” in the Build view to avoid redeploying the Web project, which is time consuming, and instead redeploy only changed files. In this case, the HTML page is redeployed each time that it is saved.

Figure 6. Shows how to enable “Validate, update, deploy code, and update running servers in the build view
Enables “Validate, update, deploy code

Important: Turn off caching in the WebSphere Integration Developer embedded browser; otherwise, a previous version of the HTML page is displayed in Business Space instead of the updated HTML page. To turn off caching on systems that run Internet Explorer on Microsoft® Windows®, complete the following steps:

  1. Start Internet Explorer.
  2. In the main menu, select Tools => Internet Options.
  3. Select the General tab.
  4. In the Browsing history section, click Settings and then select “Every time I visit the webpage”.
  5. Click OK on all of the windows.

Conclusion

You now know how the HTML-Dojo forms are used in Business Space and which rules you must follow to successfully customize human task forms to satisfy the needs of your users and business.

Resources

Learn

Get products and technologies

  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=342755
ArticleTitle=Customizing HTML-Dojo forms for Business Space powered by WebSphere
publish-date=04092009