Adding the CommandBar component to a JSF application

Use the Business Process Choreographer Explorer CommandBar component to display a bar with buttons. These buttons represent commands that operate on the details view of an object or the selected objects in a list.

Why and when to perform this task

When the user clicks a button in the user interface, the corresponding command is run on the selected objects. You can add and extend the CommandBar component in your JSF application.

Steps for this task

  1. Add the CommandBar component to the JavaServer Pages (JSP) file.

    Add the bpe:commandbar tag to the <h:form> tag. The bpe:commandbar tag must contain a model attribute.

    The following example shows how to add a CommandBar component that provides refresh and claim commands for a task instance list.

    <h:form>
    
       <bpe:commandbar model="#{TaskInstanceList}">
          <bpe:command commandID="Refresh" >
                       action="#{TaskInstanceList.refreshList}"
                       label="Refresh"/>
    
          <bpe:command commandID="MyClaimCommand" >
                       label="Claim" >
                       commandClass="<customcode>"/> 
       </bpe:commandbar>
    
    </h:form>

    The model attribute refers to a managed bean. This bean must implement the ItemProvider interface and provide the selected Java™ objects. The CommandBar component is usually used with either the List component or the Details component in the same JSP file. Generally, the model that is specified in the tag is the same as the model that is specified in the List component or Details component on the same page. So for the List component, for example, the command acts on the selected items in the list.

    In this example, the model attribute refers to the TaskInstanceList managed bean. This bean provides the selected objects in the task instance list. The bean must implement the ItemProvider interface. This interface is implemented by the BPCListHandler class and the BPCDetailsHandler class.

  2. Optional: Configure the managed bean that is referred to in the bpe:commandbar tag.

    If the CommandBar model attribute refers to a managed bean that is already configured, for example, for a list or details handler, no further configuration is required. If you change the configuration of either of these handlers or you use a different managed bean, add a managed bean that implements the ItemProvider interface to the JSF configuration file.

  3. Add the code that implements the custom commands to the JSF application.

    The following code snippet shows how to write a command class that extends the command bar. This command class (MyClaimCommand) is referred to by the bpe:command tag in the JSP file.

    The command checks the preconditions and any other prerequisites, for example, the correct number of selected items. It then retrieves a reference to the human task API, HumanTaskManagerService. The command iterates over the selected objects and tries to process them. The task is claimed through the HumanTaskManagerService API by an ID. If an exception does not occur, the state is updated for the corresponding TaskInstanceBean object. This action avoids retrieving the value of the object from the server again.

    public class MyClaimCommand implements Command {
    
      public String execute(List selectedObjects) throws ClientException {
    	    if( selectedObjects != null && selectedObjects.size() > 0 ) {
      	     try {
             // Determine HumanTaskManagerService from an HTMConnection bean. 
             // Configure the bean in the faces-config.xml for easy access 
             // in the JSF application.
    		       FacesContext ctx = FacesContext.getCurrentInstance();
             ValueBinding vb = 
               ctx.getApplication().createValueBinding("{htmConnection}");
             HTMConnection htmConnection = (HTMConnection) htmVB.getValue(ctx);
             HumanTaskManagerService htm = 
                htmConnection.getHumanTaskManagerService();
    
             Iterator iter = selectedObjects.iterator() ;			
             while( iter.hasNext() ) {
               try {
                    TaskInstanceBean task = (TaskInstanceBean) iter.next() ;
                    TKIID tiid = task.getID() ; 
    						
                    htm.claim( tiid ) ;
                    task.setState( new Integer(TaskInstanceBean.STATE_CLAIMED ) ) ;
    						
               }
               catch( Exception e ) {
                 ;			// Error while iterating or claiming task instance.
                      // Ignore for better understanding of the sample.
               }
             }
           }
           catch( Exception e ) {
             ; 	// Configuration or communication error.
               // Ignore for better understanding of the sample
           }
         }
         return null;
      }
    
     // Default implementations
     public boolean isMultiSelectEnabled() { return false; }
     public boolean[] isApplicable(List itemsOnList) {return null; }
     public void setContext(Object targetModel) {; // Not used here }
    }
    
    The command is processed in the following way:
    1. A command is invoked when a user clicks the corresponding button in the command bar. The CommandBar component retrieves the selected items from the item provider that is specified in the model attribute and passes the list of selected objects to the execute method of the commandClass instance.
    2. The commandClass attribute refers to a custom command implementation that implements the Command interface. This means that the command must implement the public String execute(List selectedObjects) throws ClientException method. The command returns a result that is used to determine the next navigation rule for the JSF application.
    3. After the command completes, the CommandBar component evaluates the action attribute. The action attribute can be a static string or a method binding to a JSF action method with the public String Method() signature. Use the action attribute to override the outcome of a command class or to explicitly specify an outcome for the navigation rules. The action attribute is not processed if the command generates an exception other than an ErrorsInCommandException exception.

Result

Your JSF application now contains a JavaServer page that implements a customized command bar.

(c) Copyright IBM Corporation 2005, 2006.
This information center is powered by Eclipse technology (http://www.eclipse.org)