Appendixes

JAR File Dependencies

This section lists the direct JAR dependencies for p8toolkit.jar and p8workplacePresentation.jar, the two primary JARs for building a Toolkit-based application. This section also includes an alternative presentation of the dependencies, listing both the direct and indirect JAR dependencies for a Toolkit-based application.

The required .jar files are installed with the FileNet P8 Workplace software, in <app_root>/WEB-INF/lib. Do not substitute other copies of .jar files with the same names.

p8toolkit.jar Direct Dependencies

Toolkit-based applications require the p8tookit.jar file. In the following table, the direct JAR dependencies for p8tookit.jar are identified, and the use of bolding and color are applied to the identified JAR file names to differentiate between the various types of dependency.

.jar File Contains ...
commons-collections-3.1.jar Apache extensions to Java Collections Framework.
commons-fileupload-2.0.jar Apache JAR providing file upload capability.
commons-jxpath-1.2.jar Apache XPath Utilities.
commons-lang-2.1.jar Apache extensions to java.lang API.
eforms.jar Application Engine eForms API. Required only if the FileNet P8 eForms features of Web Application Toolkit are going to be used. If you have purchased the FileNet P8 eForms features for the Toolkit and installed the documentation, see eforms.jar Dependencies.
jace.jar CEMP Java API.
javaapi.jar Content Java API. See "Required .jar Files" for javaapi.jar dependencies in the FileNet Content Java API Developer's Guide.
pe.jar Process Java API. See Configuring the Process Development Environment for pe.jar dependencies.
psclient.jar Process Java API dependency. The psclient.jar file has one dependency, pe.jar.
rmapi.jar Records Manager API. Required only if Records Manager features of Web Application Toolkit are going to be used. If you have purchased the Records Manager product and installed the documentation, see Required .jar files for rmapi.jar dependencies.
serializer.jar Used in conjunction with xalan.jar.
xalan.jar Apache XSLT processor.
xercesImpl.jar Xerces 2.5.0 XML parser. This .jar file contains all of the standard APIs implemented by the parser (DOM, SAX, and Java™ API for XML Processing (JAXP)). Both this .jar file and xml-apis.jar must be present in the classpath.

NOTE  To troubleshoot performance or functional problems, position this and the xml-apis.jar file ahead of all other XML parsers in the classpath.

xml-apis.jar Xerces 2.5.0 XML parser. This .jar file contains all of the standard APIs implemented by the parser (DOM, SAX, and JAXP). Both this .jar file and xercesImpl.jar must be present in the classpath.

NOTE  To troubleshoot performance or functional problems, position this and the xercesImpl.jar file ahead of all other XML parsers in the classpath.

p8workplacePresentation.jar Direct Dependencies

The p8workplacePresentation.jar file is an optional file that you can use to leverage Workplace presentation behavior. In the following table, the direct JAR dependencies for p8workplacePresentation.jar are identified, and the use of bolding and color are applied to the identified JAR file names to differentiate between the various types of dependency.

.jar File Contains ...
p8toolkit.jar The required .jar file for Toolkit-based applications, plus its dependencies.
xml-apis.jar Xerces 2.5.0 XML parser. This .jar file contains all of the standard APIs implemented by the parser (DOM, SAX, and JAXP). Both this .jar file and xercesImpl.jar must be present in the classpath. (xercesImpl.jar is a direct dependency of p8toolkit.jar.)

NOTE  To troubleshoot performance or functional problems, position this and the xercesImpl.jar file ahead of all other XML parsers in the classpath.

JAR Dependencies for a Toolkit-based Application

To develop and run a custom Toolkit application, you need p8toolkit.jar, which contains the base interfaces and classes. Optionally, you can also use p8workplacePresentation.jar, which contains the interfaces and classes that define and implement Workplace presentation behavior. The following table lists all of the JAR dependencies for p8toolkit.jar, including the indirect third-party .jar files (required by the Content Java API - javaapi.jar and the Process Java API - process.jar). The use of bolding, italics and color are applied to the identified JAR file names to differentiate between the various types of dependency.

.jar File Contains ...
aeeforms.jar Application Engine eForms integration API.
addressing.jar Process Java API dependency (with axis.jar).
axis.jar Process Java API dependency.
axis-schema.jar Process Java API dependency (with axis.jar).
commons-collections-3.1.jar Apache extensions to Java Collections Framework.
commons-discovery.jar PE Java API dependency (with axis.jar).
commons-fileupload-2.0.jar Apache JAR providing file upload capability.
commons-httpclient-2.0.2.jar Apache HTTP utilities.
commons-jxpath-1.2.jar Apache XPATH utilities.
commons-lang-2.1.jar Apache extensions to java.lang API.
commons-logging.jar Commons logging.
eforms.jar Application Engine eForms API. Required only if the FileNet P8 eForms features of Web Application Toolkit are going to be used. If you have purchased the FileNet P8 eForms features for the Toolkit and installed the documentation, see eForms.jar Dependencies.
eforms-resources.jar FileNet P8 eForms strings resources (with eforms.jar).
itext-1.3.jar PDF Generator API.
jace.jar CEMP Java API.
jai_codec.jar Java Advanced Imaging API.
javaapi.jar

Content Java API. See "Required .jar Files" for javaapi.jar dependencies in the FileNet Content Java API Developer's Guide.

jaxrpc.jar PE Java API dependency.
juddi.jar UDDI API for Java.
listener.jar Content Java API dependency.
log4j-1.2.8.jar Content Java API dependency.
mail.jar Sun JavaMail™ API.
mailapi.jar Content & Process Java API dependency.
pe.jar Process Java API. See Configuring the Process Development Environment for pe.jar dependencies.
peresources.jar Resource strings for pe.jar.
psclient.jar Process Java API dependency. The psclient.jar file has one dependency, pe.jar.
psresources.jar Resource strings for psclient.jar.
rmapi.jar Records Manager API. Required only if Records Manager features of Toolkit are going to be used. If you have purchased the Records Manager product and installed the documentation, see Required .jar files for rmapi.jar dependencies.
saaj.jar Process Java API dependency.
sandesha.jar Messaging support for Axis (with axis.jar).
serializer.jar Used in conjunction with xalan.jar.
smtp.jar Used in conjunction with mail.jar.
soap.jar Content & Process Java API dependency.
uddi4j.jar Process Java API dependency.
wsdl4j.jar Process Java API dependency.
xalan.jar Apache XSLT processor.
xercesImpl.jar Xerces 2.5.0 XML parser. This .jar file contains all of the standard APIs implemented by the parser (DOM, SAX, and JAXP). Both this .jar file and xml-apis.jar must be present in the classpath.

NOTE  To troubleshoot performance or functional problems, position this and the xml-apis.jar file ahead of all other XML parsers in the classpath.

xml-apis.jar Xerces 2.5.0 XML parser. This .jar file contains all of the standard APIs implemented by the parser (DOM, SAX, and JAXP). Both this .jar file and xercesImpl.jar must be present in the classpath.

NOTE  To troubleshoot performance or functional problems, position this and the xercesImpl.jar file ahead of all other XML parsers in the classpath.

xpp3-1.1.3.4.M.jar Process Java API dependency.

eForms.jar Dependencies

The eforms.jar and p8eforms.jar files are required if your Toolkit-based application is going to use FileNet P8 eForms features. The following table lists all of the JAR dependencies for eforms.jar, and the use of bolding and italics are applied to the identified JAR file names to differentiate between the various types of dependency. p8eforms.jar does not have any dependencies.

.jar File Contains ...
commons-fileupload-2.0.jar Apache JAR providing file upload capability.
commons-httpclient-2.0.2.jar Apache HTTP utilities.
commons-lang-2.1.jar Apache extensions to java.lang API.
commons-logging.jar Commons logging.
itext-1.3.jar PDF Generator API.
jai_codec.jar Java Advanced Imaging API.
servlet-api.jar Contains the javax.servlet.http package for the Tomcat application server.
xalan.jar Apache XSLT processor.
xercesImpl.jar Xerces 2.5.0 XML parser. This .jar file contains all of the standard APIs implemented by the parser (DOM, SAX, and JAXP). Both this .jar file and xml-apis.jar must be present in the classpath.

NOTE  To troubleshoot performance or functional problems, position this and the xercesImpl.jar file ahead of all other XML parsers in the classpath.

xml-apis.jar Xerces 2.5.0 XML parser. This .jar file contains all of the standard APIs implemented by the parser (DOM, SAX, and JAXP). Both this .jar file and xercesImpl.jar must be present in the classpath.

NOTE  To troubleshoot performance or functional problems, position this and the xml-apis.jar file ahead of all other XML parsers in the classpath.

Toolkit Packages

Many of the Toolkit Java packages are described below. For a comprehensive list, see the Web Application Toolkit Java API Reference.

Note that the Toolkit packages are contained in p8toolkit.jar, located in this FileNet P8 Workplace directory: Workplace/WEB-INF/lib.

Other packages that you may find useful are contained in p8workplacePresentation.jar, located in the Workplace/WEB-INF/lib directory. The classes in this JAR define Workplace presentation behavior, which you can also use to build custom UIs. See Leveraging Workplace Presentation Behavior.

For a list of deprecated or obsolete APIs from these packages, see Upgrade Custom Applications > Web Application Toolkit. For a list of any new APIs or other significant modifications to the Web Application Toolkit, see the section "What's New - Developer Help - Web Application Toolkit" in the IBM FileNet P8 Platform Release Notes. To download this document from the IBM support page, see Accessing IBM FileNet documentation.

See Also
Toolkit Modules
Base UI Modules

New Classes for Web Application Toolkit v4.0

The following Web Application Toolkit classes were introduced in version 4.0. The classes are organized by package.

com.filenet.wcm.toolkit.server.dp

com.filenet.wcm.toolkit.server.servlet

com.filenet.wcm.toolkit.server.util

com.filenet.wcm.toolkit.server.util.prefs

com.filenet.wcm.toolkit.server.util.webcontent

com.filenet.wcm.toolkit.server.util.xml

FileNet P8 Form Data Java API

The FileNet P8 Form Data Java API provides custom application or feature developers with the ability to access a Form Data instance associated with a given running Workflow. The API is built specifically for scenarios where customers would like to repurpose the Form Data generated from a running Workflow and associated Workflow Policy.

The API is packaged as com.filenet.eforms.api in the <app_root>/WEB-INF/lib/p8eforms.jar file. (Note that this is the same package path as the FileNet P8 eForms Java API.) The jar file has no dependencies on any other Workplace jar file and is implemented directly against the Content Engine Java API.

The API features the following classes and methods:

P8FormUtil Class

The P8FormUtil class provides helper methods for working with FileNet P8 eForms Form Data.

Method Description
getFormData

Retrieves Form Data instance information associated with the current Workflow step and returns the current version information as a single P8ObjectRef object or as a list of these objects, depending on the configuration specified by the Workflow Policy. The formId parameter of this method is for the Form Template used to create the Form Data, which can be used to filter the results when more than one Form Data instance is returned. If formId is null, no filtering will take place and the return value could either be a single P8ObjectRef or an array of P8ObjectRefs.

connectDocumentFormData

Sets Content Engine object value properties on a Form Data instance in order to associate the Form Policy with the Form Template. (The actual Form Template reference information is retrieved from the Workflow Policy content.)

connectWorkflowFormData

Like the connectDocumentFormData method, this method also sets Content Engine object value properties on a Form Data instance in order to associate the Form Policy with the Form Template. (The actual Form Template reference information is retrieved from the Workflow Policy content.)

In addition, connectWorkflowFormData also creates the FormProxy object for the running Workflow, which is used internally to associate running Workflow steps with the Workflow Form Policy. The runningWorkflowNumber parameter is required. If there is an existing FormProxy object that specifies the same running Workflow number, then an IllegalArgumentException will be thrown.

NOTE  This method does not launch, complete or dispatch a Workflow step; it can only be used to establish connectivity with a running Workflow. Before this method can be called, the Workflow must be launched.

P8ObjectRef Class

The P8ObjectRef class provides methods for maintaining references to objects used in the context of managing FileNet P8 eForms data from your custom Toolkit-based application.

Method Description
clearData

Cleans up existing data members of the class.

setValue

Adds a specified object to the class, which can be referenced using the key parameter.

getValue

Retrieves a specified object from the class, which can be referenced using the key parameter.

P8XMLUtil Class

P8XMLUtil is a utility class that provides helper methods for working with XML data. The class implements a basic tag name look up scheme to retrieve node data, rather than the XPath syntax mechanism offered by the XPathUtil utility.

NOTE  The values of string parameters passed to P8XMLUtil class methods must be simple, such as "propdesc/symname". P8XMLUtil does not use Xpath, and therefore, does not handle query string formatting, such as "propdesc[symname = 'myprop']".

Method Description
getDocumentFromInputStream

Obtains document data from the Java input stream.

getChildNode

Locates the child node under a specified parent, that contains the specified XML element tag name.

getSelectNode

Locates the child node under a specified parent, that resides at the specified XML path location.

getChildNodeText

Locates the child node under a specified parent, that contains the specified XML element tag name and returns the text value for that child.

getNodeText

Returns the text value for a specified node.

getSelectNodeList

Locates an array list of child nodes under a specified parent, that reside at the specified XML path location.

getChildNodeWithValue

Locates the child node from a specified array list of nodes, that contains both the passed in XML element tag name and the passed in XML element value.

addChildren

Locates child nodes in a specified parent that contain the specified XML element tag name, and then adds the matching nodes to an array list of children passed into the method.

ConfigurableController Preferences

The out-of-the-box implemented controller, ConfigurableController, is configured with XML-based preferences, stored in the <app_root>/WEB-INF/p8controller.xml file. The table below describes the preferences. In p8controller.xml, the preferences are expressed as subelements of the <list key="controllerConfig"> element. Unless otherwise specified, a setting is required.

For details on how these preferences are used by ConfigurableController, see ConfigurableController Preferences Classes.

Setting / Array / List Key Description
configurationName The name of the configuration.
signInPolicy The fully qualified name of the sign-in policy class. See Creating a Sign-In Policy.
headerModule The fully qualified name of the HTML-header class. See HTML Headers -- Using Default Implementation.
configuration The fully qualified name of the preferences configuration class. See WcmConfiguration.
staticInitializer Optional. The fully qualified class name of a class implementing StaticInitializerInterface. If defined, rather than calling its own initializeStaticClasses method, the controller constructs an instance of the specified class and calls the class' initializeStaticClasses method instead.

This setting provides more direct control over static class initialization within a Web application.
ignoreFilterCredentials

Optional. The ignoreFilterCredentials preference only applies when Workplace or your custom Toolkit-based application is configured for container-managed authentication. Use of the preference is intended for situations where a user challenge is required that represents a user different from the container-managed authenticated user. When container-managed authentication is in use, this preference appears below staticInitializer in the element definition.

When no value is specified, the preference is set to false (default). To cause the configured controller to ignore any container-managed authenticated user supplied credentials, (in other words, to cause the controller to behave as though it were running under application-managed authentication), set ignoreFilterCredentials to true.

bootstrapPage The bootstrap page that's automatically displayed the first time a user with administrator privileges signs into your application. In the FileNet P8 Workplace application, the bootstrap is WcmBootstrap.jsp. To not use a bootstrap page, set bootstrapRequired to false.
defaultPage The name of the default page -- the page that should be loaded when one is not specified in the client request. We recommend that you base your default page on WcmDefault.jsp.
signInPage The sign-in page. In the FileNet P8 Workplace application, the sign-in is WcmSignIn.jsp. To not use a sign-in page, set signInRequired to false.
errorPage The name of the error page. We recommend that you base your error page on WcmError.jsp included with the FileNet P8 Workplace application.
bootstrapRequired When set to true, indicates that the bootstrap.properties file must have a valid object store configured as the location for saving site and user preferences.

The persistence mechanism in the implementation of WcmConfigurationInterface, defined in the configuration preference, determines whether or not bootstrapRequired should be set to true.
signInRequired Set to true if your application requires validated user credentials in order to function.
defaultHomeKeyword The first page to load when your application starts. The value of this element must match the value of one of the <setting key="keyword"> elements, a subelement of <list key="homePages">.

The ConfigurableController.getConfiguredHome() method returns this value. This method should be called from your default page, as is done in the WcmDefault.jsp page included with the FileNet P8 Workplace application.
defaultRouter The Process Engine connection point that your application will be using.

NOTE  In FileNet P8 4.0.0, Process Engine routers have been replaced with Process Engine connection points. For more information, see Migrate Process Routers in the Help for Enterprise-wide Administration on the FileNet P8 Platform documentation server.
internalTokensEnabled Backward compatibility setting for version 2.x Toolkit-based applications using ConfigurableController. Set to false for the best sign-in backward compatibility. Set to true to take advantage of the simplified secure sign-in credentials-passing mechanism.
windowIdCompatibility Backward compatibility setting for version 2.x Toolkit-based applications using ConfigurableController. Set to true for the best windowId-backward compatibility. Set to false to take advantage of the inline windowId feature, and windowId aging/expiration feature.
preControllerEvents Lists events that the controller handles without executing the page cycle (initialize, event routing, start page, render). Pre-controller events typically do a redirect, making page execution unnecessary. See Phase Notification.
controllerEvents Lists events that are routed in the event phase of the page cycle.
homePages Lists home pages -- top-level Java™Server Pages (JSP) pages that initiate main application functions: browse, search, tasks, and so on. Each home page preference specifies the JSP page and guest permission (allowed/not allowed).

The value of one of the <setting key="keyword"> subelements must match the value of the <setting key="defaultHomeKeyword"> element.

Implementing a Controller

As an alternative to using ConfigurableController, the Toolkit-supplied default controller, you can create your own custom implementation, as defined in the abstract WcmController class.

  1. Subclass WcmController.

  2. Implement the abstract callback methods.

Toolkit Implementation of MVC

The controller framework is based on the Model-View-Controller design pattern (MVC). The model is the application object, the view is its screen presentation, and the controller maps end-user events to model operations. MVC design decouples views and models. Because there is no business logic within the view, you can easily attach multiple views to a model for different end-user presentations.

The graphic below shows the application flow in the controller framework. In the controller phase, end-user events, in the form of HTTP requests, are dispatched to the model components then forwarded to the view components. In the model phase, the data required for presentation is retrieved and passed to the view components. In the view phase, XML data is rendered into HTML and sent to the end user.

The components in the controller framework are connected dynamically to each other. Any UI or data provider module can have one or more data provider modules connected to it, and multiple modules can connect to the data store. Typically, a model will have several UI module and data provider beans instantiated within it, with each UI module requesting data from multiple data providers, and each data provider handling requests from multiple UI modules.

MVC diagram

Controller Phase

The controller portion of the design consists of event JSP pages (one per core functionality), and a controller bean. These components map view actions (events) from the user to model operations. Once the model operations have been performed, the controller forwards the request to a corresponding UI JSP page, which generates dynamic HTML output to the end user.

An event JSP page instantiates and connects all necessary UI modules, data providers, and the controller bean. It then registers the modules with the controller, and calls the controller's handleEvent method to dispatch the event, either to a UI module or the controller itself. Note that if the event is directed to the controller, such as a page switch event, the controller will call the cleanup methods for each module, and then redirect to the applicable event JSP page. If the event is directed to a UI module, then the controller dispatches the event to the target module, then redirects to the applicable UI JSP page for rendering.

Model Phase

The model portion of the design consists of several Java™Beans: UI modules, data providers, and the data store. In this phase, the controller calls an event handler in a UI module. The UI module requests data from a data provider and updates the model as needed. In effect, the UI module bean models data in memory for its area of functionality, for example, folder browsing or searching. (In the view phase, the UI module generates the new UI view with the data reflected in the updated model.)

The data providers gather data from the Content Java API running against a Content Engine, or from the Process Java API running against the Process Engine. A single data provider can handle data requests from several UI module beans, and a single UI module can request data from multiple data providers.

The data store bean persists session state data, holding current state information in memory for any modules, including data providers and UI modules.

View Phase

In the View phase, XML data received from the model is rendered into an HTML page for end-user presentation. The view portion of the MVC design consists of UI JSP pages, corresponding to different UI functional areas. A UI JSP page consists of template HTML tags and JSP scriptlets that call the render methods of UI modules.

As illustrated below, when a render method is invoked in a UI JSP page, XML data—requested initially in the event handler of the UI module in the model phase—is returned to the UI module. Also returned are user and site preferences cached in the data store, some of which affect the end-user display of the data. In the graphic, the UI module's content is rendered with an XSL transformation object, as implemented in the FileNet P8 Workplace application. However, you can create UI modules that render the content (Java-based rendering), or UI modules that delegate rendering to JSP pages (JSP-based rendering).

XSLT-based rendering

Technical Notes

The following technical notes have been compiled from questions raised by developers who have built Toolkit-based Web applications:

Return URLs - Best Practices

This technical note discusses how to best use return URLs -- in the context of returning to JSP pages. Launching a wizard from a JSP page is a case in point. In the HTTP request for the wizard, you'd want to include the URL of the JSP that launches the wizard, and cache the return URL in the data store. When a user cancels or exits from the wizard, you would retrieve the return URL from the data store, and return the user to the JSP page that launched the wizard.

Request Parameters - How They're Interpreted

The controller framework interprets a set of request parameters in one of two ways:

Getting Return URLs

There are different ways of getting a return URL. Our best practice recommendation is to leverage the Toolkit to build a return URL, pass it as a request parameter, cache it in the data store, and retrieve it from the data store when a request is made for the return URL.

The following code snippet shows how to build a return URL.

String requestString = WcmParameter.RETURN_URL + "=" +
   URLEncoder.encode( ((String)dataStore.getValue(WcmDataStore.BASE_URL_KEY)) + "/" +
   getPageUrl(null, null) );

In your UI module, retrieve the value of the returnUrl parameter from the request string, and cache it in the data store. For example, in the code snippet below, the WcmController.peekNewPageParameters() method determines whether or not the specified page parameter is new. If not, then the parameter value is retrieved and cached.

public void onStartPage(HttpServletRequest request, HttpServletResponse response) throws Exception
{
   if ( getController.peekNewPageParameters() )
   {
      returnUrl = controller.getPageParameter(WcmParameter.RETURN_URL);
      setModuleProperty(WcmParameter.RETURN_URL, returnUrl);
   }
}

If you do not want to build and pass a return URL as a parameter to a UI module, you can rely on the request object to get the URL of the referer. For example:

public void onStartPage(HttpServletRequest request, HttpServletResponse response) throws Exception
{
   if ( getController.peekNewPageParameters() )
       setModuleProperty( WcmParameter.RETURN_URL, request.getHeader("referer") );
}

In your wizard's onExit handler, retrieve the returnUrl value from the data store and use it to redirect to the referer JSP. For example:

public void onExit(HttpServletRequest request, HttpServletResponse response) throws Exception
{
   String returnUrl = (String)getModuleProperty( WcmParameter.RETURN_URL );
   if ( returnUrl != null )
      response.sendRedirect( returnUrl );
   else
      doSomethingSane();
}

For further illustration of retrieving returnURL, see the onExit(...) method in the WcmMultiPanelModule source code, the base UI module from which Workplace wizards derive.

Wizard Cache Clearing

If a user exits a wizard in a way other than through a wizard link ("Cancel" or "Finish" for example), data is left in the cache (data store) until the user next launches the wizard. Upon relaunch, the base class, WcmMultiPanelModule, calls WcmController.peekNewPageParameters() to test for new page parameters. If true, the module cleans up from the previous invocation of the wizard page.

Capturing Form Data in a Multi-Panel UI

This technical note outlines the steps to capture HTML form data in a multi-panel UI. To start, you would write a UI module with a form presentation, and with an event handler (for example, "onSubmit") that reads the data with calls to request.getParameter(). To store the data on a backend server, such as in a database, you would pass it to a data provider that accesses the database. If, on the other hand, you want to save the form data to a stateful bucket in your Web application, there are several Toolkit methods for storing stateful data.

After creating the UI module with a form presentation, you must incorporate it as a panel in your multi-panel UI. The following steps describe how to do this, in the context of using a tab bar to page between panels, and using JSP-based rendering of the multi-panel UI.

  1. Subclass WcmMultiPanelModule.
  2. In the initialize() method, create an instance of your tab bar module, and call the addChild(...) method to add the tab bar object as a child of the multi-panel subclass.
  3. Create a public accessor to get the tab bar object, so that you can retrieve it from the rendering JSP page.
  4. To add panel-selection URLs to the tab bar, implement the abstract addPanelSelectionAnchor(int panelNumber)method. The URLs will be generated by WcmAnchor objects, which represent "SelectTab" event URLs. The following code snippet shows how to do this. ( To use a panel-selection technique other than a tab bar, for example, a hierarchical tree menu, adapt this code accordingly.)
    WcmEventURL eventURL = new WcmEventURL(this, "SelectPanel", WcmParameter.PAGE_ID + "=" + panelNumber);
    WcmPanel panel = getModule(panelNumber);
    WcmAnchor anchor = new WcmAnchor(eventURL, panel.title);
    anchor.setToolTip(panel.toolTip);
    yourTabBar.addAnchor(anchor);

    The above code creates an anchor that will fire the SelectPanel event in order to select the panelNumber specified. The anchor label is defined as the panel's configured title, and the anchor uses the panel's tooltip string.

  5. Implement the abstract setCurrentPanelSelection(int panelNumber)method to tell the tab bar object which item should be highlighted as the current selection. For example:

    yourTabBar.setCurrentSelection(panelNumber);

  6. In your tab bar module, implement a method for highlighting the current section.

By setting up your multi-panel UI this way, if the panel that is showing has a form on it, and you've properly implemented the getFormName() method for your panel, the WcmEventURL(...) method will submit all of the form data from the panel that you're switching from on the SelectPanel event, so that you can statefully persist it on the server.

You have the option of either overriding the selectPanel method to handle this persistence, or using the panel framework by subclassing from WcmMultiPanelViewModule, and then implementing WcmViewPanelInterface on your panels. This interface defines a callback method named panelSave, with which you can implement panelSave in your panels and persist form data.

Storing Stateful Data

Web Application Toolkit provides several options for storing stateful data, as listed below. Note that your primary consideration in choosing an option is one of scoping.