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.
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.
- 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
to display some of the properties of a task instance.
<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 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 properties
of the Java objects and it must implement the ItemProvider
interface. This interface is implemented by the BPCListHandler class and the
BPCDetailsHandler class. It also includes a custom claim command.
- 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
have changed the configuration of either of these handlers or you have used
a different managed bean, add a managed bean that implements the ItemProvider
interface to the JSF configuration file.
- 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:
- 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.
- The commandClass attribute refers to a custom command
implementation that implements the Command interface. The command must implement
the public String execute(List selectedObjects)throws ClientException method.
The command returns an outcome that is used to determine the next navigation
rule for the JSF application.
- 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 throws an exception other than an ErrorsInCommandException
exception.
Your JSF application now contains a JavaServer page that implements
a customized command bar.