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.
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. |
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. |
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. |
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. |
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
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
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:
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. |
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 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. |
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 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 |
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.
|
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.
Subclass WcmController.
Implement the abstract callback methods.
Implement the following get...Page:
getBootstrapPage. Return 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. If you don't want to use a bootstrap page, return null.
getConfiguredHome. Return the configured home page. For example, you can make the home page a settable option in your preferences mechanism, such as the FileNet P8 Workplace application does. The getConfiguredHome() method should be called from your default page, as is done in the WcmDefault.jsp page included with the FileNet P8 Workplace application. If you don't want to use a home page, return null.
getDefaultPage. Return 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. If you don't want to use a default page, return null.
getErrorPage. This returns the name of the error page. We recommend that you base your error page on WcmError.jsp included with the FileNet P8 Workplace application. If you don't want to use an error page, return null.
getSignInPage. This returns the name of the sign-in page. In the FileNet P8 Workplace application, the sign-in is WcmSignIn.jsp. If you don't want to use a sign-in page, return null.
Implement page-related callbacks.
isStickyPage
isValidHome
Implement getRouters. Provide a list of the Process Engine connection points
that your application will be using; otherwise, return null.
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.
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.
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.
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.
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).
The following technical notes have been compiled from questions raised by developers who have built Toolkit-based Web applications:
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 InterpretedThe controller framework interprets a set of request parameters in one of two ways:
getPageUrl(null,null)
call
will give you this.
WcmController.getPageParameter(...)
signatures. In scenarios where you would want to return to the JSP
page, such as when a wizard is completed, you include a
returnUrl
parameter in the request.
WcmController.peekNewPageParameters()
to test for new
page parameters. When true, the UI module initializes for the new
invocation and/or cleans up from a previous invocation of the page.
Getting Return URLsThere 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.
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.
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.
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.
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.
setCurrentPanelSelection(int
panelNumber)
method to tell the tab bar object which item should
be highlighted as the current selection. For example:
yourTabBar.setCurrentSelection(panelNumber);
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.
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.
The children can also access the parent's module and class properties
through the WcmModule.getParent()
module method.
WcmDataStore
properties (setValue/getValue) are scoped to the entire application
session. Using the module method
WcmModule.getDataStore()
, you can retrieve data stored in
the global keys.