Typical workflow in creating a custom task user interface:

Worklist provides Worklist User Portal, a web-based user portal for interacting with tasks. This portal allows users to see the details of a task, and take actions on a task to move it through its life cycle. Each step in a task plan can define unique actions and thus present its own unique considerations to the user.

Worklist User Portal is an all-purpose user interface that uses the metadata for steps and actions to render a usable interface at each step. The user interface for a given step and action will differ from the user interface for other steps and actions by virtue of the differences in the metadata for those steps and actions. For example, when rendering the user interface at a given step, the Worklist User Portal shows the description and actions the task plan designer defined for that step. Worklist User Portal has only this information to work on when rendering the user interface, and cannot account for any more subtle needs a user may have with regard to this step (For example, summary information that would be needed to enter a value for an action's required properties, or calculations that may be applied to individual task properties to derive the result value for a property)

In some cases, like the previous examples, a given step or the actions that can be taken on that step may require a customized user interface. Worklist accounts for this need for extensibility by allowing a web developer to design a custom web user interface to be used for a given step, or an entire task plan. This custom web user interface is called a Custom Task User Interface. Custom Task UI allows a web developer to design custom pages only where needed, and still use the facilities of the default Worklist User Portal everywhere else. This allows a gradual investment in the customization of the user portal, instead of requiring a wholesale replacement of the Worklist User Portal interface.

A custom interface can be designed for just a step in a task plan or for the entire task plan.

Typical Workflow

Implementing the Custom Task UI Page Flow

By extending the custom controller with TaskUIPageFlowController.

Note:

This is the preferred method for implementing the custom task UI page flow and this is the method that is assumed in the rest of this section. For information about the various public helper methods available on the controller, see the Javadoc of the controller available at the following location:

By extending custom controller with the basic PageFlowController. For requirements that must be met when you use this controller, see Task UI Page Flow Requirements.

Task UI Page Flow Requirements

If you do not extend the custom controller using TaskUIPageFlowController, you must manually meet the following requirements of a task UI PageFlowController. These requirements allow a calling task work page flow to call into the task UI page flow and have that page flow return to it via actions the caller is guaranteed to have implemented.

May optionally extend com.bea.wli.worklist.TaskUIPageFlowController to provide common utility method implementations.
Must be marked as a nested page flow by setting the

@Jpf.Controller( nested=true )

annotation on the page flow controller class

Must implement a begin action taking no parameters. If the page flow controller extends TaskUIPageFlowController, this method must call the super.beginActionHelper() method to correctly initialize its state. Otherwise, this method should obtain an instance of TaskUIContextInfo to provide context information about the task work controller. This can be obtained from the HTTP session as follows:

import com.bea.wli.worklist.WorklistUIContextHelper;

WorklistUIContextHelper helper =

new WorklistUIContextHelper(getSession());

TaskUIContextInfo contextInfo = helper.getTaskUIContextInfo();

Must provide a user interface component that allows the user to take the done action for the custom task UI. This will end the user's session in the custom task UI. What it means to leave a session depends on what the host application that contains the Worklist UI has defined for the lifetime of the session. For example, in Worklist User Portal, leaving a session means to leave the "Work on Task" page and return to the "Home" page of the portal. The UI component for this action (for example, button or link) should use the done action context and label text provided in the TaskUIContextInfo.
Must return to the calling page flow under the following circumstances, and using the indicated exit/return action on the calling page flow.

After taking any action on the current step of the task, the taskUI page flow must return from an internal return action using the taskUIStepDoneAction on the caller. An example Forward annotation is given below:

@Jpf.Forward(name = "success", returnAction = "taskUIStepDoneAction")

When the taskUI user decides to leave the UI session (by clicking the required done action UI component), the taskUI page flow must return from an internal return action using the taskUISessionDoneAction on the caller. What it means to leave a session depends on what the host application that contains the Worklist UI has defined for the lifetime of the session. For example, leaving a session might mean to logout. An example Forward annotation is given below:

@Jpf.Forward(name = "success", returnAction = "taskUISessionDoneAction")

If the user selects a task view (from the list of task views provided in the TaskUIContextInfo instance passed into the begin action), the taskUI must return from an internal return action using the taskUIShowTaskListAction on the caller. An example Forward annotation is given below:

@Jpf.Forward(name = "success", returnAction = " taskUIShowTaskListAction")

where the returned Forward instance must have the selected task list view name (as a String) set on it. An example internal action and Forward construction statement is given below:

@Jpf.Action(forwards = {

@Jpf.Forward(name = "success",

returnAction="taskUIShowTaskListAction")

})

protected Forward showTaskListAction()

{

// JSP should pass the view name from the link/button

// etc. the user clicks on the page

String view = getRequest().getParameter("view");

Forward success = new Forward("success", view);

return success;

}

Creating a Page Flow

After determining the look and feel of the customized user interface pages, you need to define the logic and use of these pages by creating a Beehive Page Flow. Page Flows allow the design of an user interface on which actions can be defined. Page Flows control the actions and navigation of the web pages in the custom task interface.

In the Package Explorer pane, right-click the <web project name>\src folder, and select New Other. The Select a Wizard dialog appears.

The Web project corresponds to the Web application of Worklist that acts as the user interface for the system. For more information, see "Worklist Application" in Creating and Managing Worklist Task Plans in Using Worklist.

Figure 3-1 Creating a Page Flow

Creating a Page Flow

Click next to Web, select Page Flow, and click Next. The New Page Flow dialog appears.

Figure 3-2 Specify Page Flow Details

Specify Page Flow Details

Enter the name of the Page Flow folder.
Specify the parent folder of the Page Flow.
Enter the name of the Page Flow controller.
Select the Make this a nested page flow check box and click Finish.
The Open Associated Perspective dialog appears. Click Yes.

Figure 3-3 Open Associated Perspective

Open Associated Perspective

The Page Flow Editor appears.

Figure 3-4 Page Flow Editor

Page Flow Editor

Replace the following code in the <page flow controller>.java file

@Jpf.Controller(nested = true, simpleActions = { @Jpf.SimpleAction(name = "begin", path = "index.jsp") })

public class <page flow controller> extends PageFlowController

with

@Jpf.Controller(nested = true)

public class <page flow controller> extends com.bea.wli.worklist.TaskUIPageFlowController {

Note:

This change will result in some compilation errors saying `Action "begin" was not found.' This error will be resolved after you define the begin action. For information about the begin action, see Defining Actions on a Page Flow. To see a list of errors, warnings and information messages in the Problems View, select Window

Show View

Problems.

Creating Form Beans

For each web page that you need in the custom task UI, you need to create a Form Bean. These form beans can be represented as inner java classes of the Page Flow Controller, or they can be standalone java classes. Form Beans should implement java.io.Serializable as described in the JDK Javadoc.

Generating Setter and Getters Methods for Properties

Form Beans are the basis for the data handling done in the web pages for the custom task UI. The Form Bean is a JavaBean object with a number of properties. You need to generate the Setter and Getter methods for each of these properties.

Defining Actions on a Page Flow

You define actions on the page flow to move between the web pages in your custom task interface and to take appropriate actions on the task. Page Flow actions are methods on the Page Flow Controller that allow navigation within the interface and optionally, calculate results and pass Form Beans to the required web pages.

Form Beans are passed from an action to a web page to populate display fields on the page. These field values are collected and placed into properties on the Form Bean when the web page is submitted back to the server for processing.

Action methods can accept a Form Bean populated as the result of clicking a Submit button on a web page by defining the Form Bean as a parameter to the action method. Action methods can also pass a Form Bean on to a target web page to which the action is forwarding. This is done by passing a Forward Object that has a Form Bean Object set on it.

Define page flow actions for all actions that are designed and required for your custom task interface. In addition, you need to define the begin action for initializing the Page Flow Controller. The begin action initializes this controller and calls the super class helper (beginActionhelper) to initialize task context, standard form beans for a task and action, and property editing support.

Action Methods and Form Beans

Action methods can accept Form Beans and forward to pages using Form Beans. When submitting a web page and in the process of calling the action associated with a Submit, the NetUI framework creates a new form bean instance by default (using the no-arg public constructor for the Form Bean class). This new bean instance is then populated via Java reflection with data from data binding tags in the submitted web page form.

This process has some limitations. For example, if your Form Bean contains transient, hidden information that is not represented in the web page JSP tags, the Form Bean that actually gets passed to the action method (the bean that is created by the NetUI framework) will not have this information.

To avoid the overhead and possible behavioral problems of creating new beans each time an action method is called, you can specify a useFormBean field on the @Jpf.Action annotation for an action method. This allows to hold a single copy of the Form Bean in the Page Flow Controller's state and the action method then just fetches the object from that state instead of creating a new form bean object.

Worklist Property Editors and Actions

Worklist provides some built-in support for editing properties in your custom task UI. It includes a JSP tag, default editors, and some helper methods in the base TaskUIPageFlowController. These facilities allow you to easily edit the following types of properties using out-of-box UI:

Multi-line/multi-page text
JavaBean/XMLBean objects

In addition, the Property Editor facility allows human users using the custom task UI to easily edit properties using an inline editor (simple form field) as well as a standalone editor for the complex types mentioned above. This facility makes robust editing of properties a fairly simple matter.

Create the following actions in your custom page flow controller to handle task's user property editor:

okPropAction - The stand-alone editor returns to this action when you click OK to apply the edit. It returns on this action passing an EditorValueHolder holding the value that was created or edited in the editor. This action should specify the _editorValue field of your Page Flow in a useFormBean attribute in the @Jpf.Action annotation. This allows the returned or completed editor value form bean to be passed in the _editorValue field and avoids creating a copy of this potentially large form bean. For an example of this action and its annotations, see Tutorial: Building a Worklist Application
cancelPropAction - This is the action the stand-alone editor calls when the user clicks Cancel in the editor.
<edit property action> - This action handles an initiate stand-alone editor call that comes from the JSP and the worklist propertyEditor tag. Your action method should call the TaskUIPageFlowController.editPropActionHelper to calculate the stand-alone editor's URI, and then forwards to that URI. This editor is a nested page flow, and returns to this controller (the caller) via the okPropAction and cancelPropAction return actions.

Note: The actual name of the action is specified in the Worklist propertyEditor tag in the actionName attribute.

Creating Actions on a Page Flow

All the actions for the Page Flow are created. You should see code that is similar to the following:

Defining JSP Pages

Based on the interface mock ups that you designed, define JSP pages for the custom task UI using Beehive NetUI data binding JSP tags to render web forms that can read data from and write data into form beans. The use of these tags greatly simplifies the process of writing a data-driven JSP page.

Creating JSP Files

In the Page Flow Explorer, right-click Pages and select New JSP Page.

Note:

In the Page Flow Controller, if there is a reference to a unavailable JSP, grayed out JSP pages are automatically listed under the Pages node in the Page Flow Explorer View. You can right-click on these JSPs and select Create to create the JSP file.

Open the JSP file to view the following code:

<%@ page language="java" contentType="text/html;charset=UTF-8"%>

<%@taglib uri="http://beehive.apache.org/netui/tags-html-1.0" prefix="netui"%>

<%@taglib uri="http://beehive.apache.org/netui/tags-databinding-1.0" prefix="netui-data"%>

<%@taglib uri="http://beehive.apache.org/netui/tags-template-1.0" prefix="netui-template"%>

<netui:html>

    <head>

        <netui:base/>

    </head>

    <netui:body>

       <p>Beehive NetUI JavaServer Page - ${pageContext.request.requestURI}</p>

    </netui:body>

</netui:html>

To create the JSP page, delete the following code from the JSP:

<p>Beehive NetUI JavaServer Page - ${pageContext.request.requestURI}</p>

and insert the text form in between the <netui:body> and the </netui:body> tag.

To design the interface that should appear on the web page, drag and drop required elements from the NetUI folder in JSP Design Palette View into the JSP.

Figure 3-8 JSP Design Palette

JSP Design Palette

Use the NetUI form element to design the form for all the required actions.
Use the NetUI button element to enable navigation between forms and to take actions on the task.
Repeat the above steps for all the JSP pages required for your custom task UI.

Registering the Custom Task UI

After designing the custom task UI for a step in a task plan or for an entire task plan, you need to register the custom task UI. To register the custom task UI, you need to add mapping entries to <Web project name>/WebContent/WEB-INF/task-ui-registry.xml registry file.

This XML registry file is associated with the schema for the Worklist Task UI Registry, and this schema is registered with Workshop.

Open the file to edit it. In the Source tab, the initial contents of this XML file should look something like this:

In the Design tab, you can right-click any node in the tree view to act on it. You can delete nodes, and add children to nodes.

Task Plan ID - The ID of the task plan for which the custom task UI applies, in external format (example, /<path>/<task plan name>:<version>)
Step Name - Required only when registering the custom task UI for a specific step in the task plan.
Custom Task UI URI - The web URI of the Page Flow Controller that will control the UI to be applied to this step or task plan.
The URI has a .jpf extension even though the Page Flow Controller file is really .java file. This is needed to allow servlet filters in the web application to fire correctly.

To edit task-ui-registry.xml first switch to the Package Explorer view and then do the following in the Design tab of the editor:

In the Package Explorer, navigate to the <Web project name>/WebContent/WEB-INF/ folder and select task-ui-registry.xml.

Note:

Double-click the file to open it in the XML Editor.
In the editor, right-click task-ui-registry.xml, and select Add Child.Selectstep-override or task-plan override based on whether you created the custom task UI for a step or the entire task plan. This adds a new override element under the root element.

Figure 3-9 Adding Child Override Element

Adding Child Override Element

Expand the newly added step-override or task-plan-override element and specify the task plan ID, step name, and custom task UI URI.

Note:

Step name is not required if you are registering the custom task UI designed for the entire task plan and not just a step in the task plan.

For each of these elements, click on the right-hand value column, and replace the default values with the actual values.

Figure 3-10 Map entries in registry file

Map entries in registry file

Using Worklist User Portal

Customizing Worklist User Portal