IBM Forms Server 4 - Forms View Portlet (FVP) Documentation  |
|
ShowTable of Contents Overview
The Forms View Portlet (FVP) integrates IBM Forms into a WebSphere Portal page. The FVP provides the following functionality:
- Renders an IBM Form using IBM Forms Server - Webform Server and supports all standard IBM Form functionality
- Provides rich configuration via portlet edit modes. No programming is required.
- Supports Portal's JSR-286 eventing functionality:
- includes dynamic events based on form contents so that live form data can move between the FVP and other portlets
- includes predefined standard form life-cycle events (open, close, submit, etc.)
- Supports Portal's Dynamic Page capabilities
Audience
This documentation is intended for WebSphere Portal administrators or those familiar with portlet configuration, portal page set-up, events, and wiring. This document also assumes some prior knowledge of IBM Forms, including the usage of XForms instance data and XPath. Supported Environments
Portal 6.1.5 - with APAR PM23541
Portal 7 - with APAR PM23540 and APAR PM25659
A clustered Portal environment is supported.
The FVP must be used in conjunction with the identical version of Webform Server. Limitations and Known Issues
- Portal themes using client-side aggregation (CSA) are not supported by the FVP. This includes the "PortalWeb2" theme in Portal 6.1.5 and the "Page Builder" and "Portal" themes in Portal 7 with CSA mode enabled.
- The FVP does not support the rendering of forms using the IBM Forms Viewer. XFDL forms are always rendered in HTML using Webform Server.
- To have multiple FVP's with different event definitions you must clone the FVP.
- Erroneous behaviour may result if multiple portlets on the same Portal page try to fire events at the same time. Avoid having multiple FVP's on the same page that each define events with the 'Fire this event on open' option selected.
- Due to a limitation in the encoding algorithm in Portal's "security.css.protection" setting, the FVP cannot determine if < and > are encoded versions of < and > or if the user actually entered the strings < or > into a form field. For more information, search for "security.css.protection" in the Portal documentation.
- Form events will only work with forms that contain XForms instance data.
- The FVP is a closed source asset and is not intended to be extended.
- The FVP is capable of displaying forms circulated by Lotus Forms Turbo however anonymous access to Turbo forms is not permitted. Therefore you must enable Single Sign-On (SSO) authentication between the Portal server and the Turbo server.
Installation
The FVP is distributed with the IBM Forms Server installer. Select "Forms Applications Components" when running the installer. After installation, the FVP can be found at [IBM Forms Server install dir]/WebformServer/FormsViewPortlet/IBMForms_FormsViewPortlet-[version].war
The FVP has no special installation requirements or instructions. Refer to the WebSphere Portal documentation for normal portlet installation.
Note: The FVP does not require the deployment of the IBM Forms Server API to the WebSphere Portal server as is required for other IBM Forms offerings.
General Configuration
The FVP provides a rich set of configuration GUIs in both the "Edit Shared Settings" and "Configure" portlet modes. Some settings for the FVP are only available in the "Configure" mode. Refer to the Portal documentation for more information on the difference between these two modes:
Form URL
An absolute URL to a XFDL form. Only the 'http' and 'https' protocols are supported. The form URL must be accessible from the Portal server. Webform Server URL
Dynamic Page Support
The FVP can be placed on a dynamic Portal page. If the FVP is on a dynamic page then you can pass it a form URL to open using the property broker API. The name of the property to use can be configured as an additional setting of the FVP's 'Open' event (see below).
Refer to the Portal documentation for full details on creating dynamic user interfaces. Submission Handling
Resolving the Submission URL
The following table summarizes how a form's final submission URL is resolved:
| Form URL | Base Submission URL | Additional Submission URL | Final Submission URL |
|---|
| http://loadServer/loadBase/loadServlet | http://submitServer/submitBase/submitServlet | http://formServer/formBase/formServlet | http://formServer/formBase/formServlet |
| http://loadServer/loadBase/loadServlet | http://submitServer/submitBase/submitServlet | (none) | http://submitServer/submitBase/submitServlet |
| http://loadServer/loadBase/loadServlet | (none) | (none) | http://loadServer/loadBase/loadServlet |
| http://loadServer/loadBase/loadServlet | (none) | saveServlet | http://loadServer/loadBase/saveServlet |
| http://loadServer/loadBase/loadServlet | http://submitServer/submitBase/submitServlet | ?paramX=y | http://submitServer/submitBase/submitServlet?paramX=y |
| http://loadServer/loadBase/loadServlet | http://submitServer/submitBase/submitServlet | ../otherBase/otherServlet | http://submitServer/otherBase/otherServlet |
| http://loadServer/loadBase/loadServlet | http://submitServer/submitBase/submitServlet?paramZ=a | ?paramX=y | http://submitServer/submitBase/submitServlet?paramX=y |
| http://loadServer/loadBase/loadServlet | (none) | ../otherBase/otherServlet | http://loadServer/otherBase/otherServlet |
Base Submission URL- as specified in Submit event settings
Additional Submission URL - as specified in the form or in the payload of a Submit event
Only the 'http' and 'https' protocols are supported for submissions. The final submission URL must be accessible from the Portal server. Valid Submission Server Responses
Success (HTTP response code 200):
- Supported response content
- no response body - The FVP displays its own "success" message.
- text/html, text/xml, and text/plain - FVP retrieves and caches the response content and displays it in an iFrame. The response content should be "UTF-8" encoded. If the response is a HTML page, then relative URLs must be avoided or a base tag should be specified in the returned HTML.
- application/vnd.xfdl - The returned XFDL content is sent to Webform Server and displayed in the FVP as HTML.
- Location response header - If the response content is not XFDL, then an optional Location response header can also be specified. It is expected that the value of this header is the URL that should be used to retrieve the submitted form. This URL is used in combination with the "Do not clear the form after it is submitted" option in the 'OnSubmit' event configuration settings. This URL, if specified, is also sent as the payload of the 'OnSubmit' event.
Redirect (HTTP response codes 301, 302, 303, or 307):
- FVP displays the URL given by the 'Location' response header directly in an iFrame.
Error (Any other HTTP response code):
- The FVP displays its own "error" message.
Post Submission Behavior
The 'OnSubmit' event has the following three post-submission options:
1. Clear the form after it is submitted - A fresh copy of the form is displayed after submission.
2. Do not clear the form after it is submitted - After submission, the FVP will display the submitted form, instead of a fresh copy. This option must be used in combination with a 'Location' response header from the submission server so that the FVP knows where to retrieve the submitted form from. See "Valid Submission Server Responses" above.
3. Close the dynamic page - If the FVP is displayed on a dynamically generated Portal page, then selecting this option will close the dynamic page after submitting the form.
Best Practices
Due to Portal's server-side eventing system, the firing of events will cause the browser page to refresh. Therefore, it is advisable to reduce the number of 'on change' form events to the minimal set required for your scenario.
It is considered a best practice in the Portal environment to hide the 'Open' and 'Save' buttons in the form's toolbar. For more information refer to http://www-10.lotus.com/ldd/lfwiki.nsf/dx/portals-disable-unnecessary-toolbar-buttons Single Sign-On (SSO)
The FVP will pass along LTPA tokens so that single sign-on (SSO) authentication can be used between the Portal server and a remote server hosting forms, handling form submissions, or providing event data conversion functionality.
Events
Static Portlet Events
The FVP sends and receives some basic form life-cycle events. These events are independent of the particular form being rendered and therefore are referred to as 'static' events. The intention of these events is to make it possible for the FVP to part of a greater solution require the communication between multiple portlets. Portlet events can only be configured in the FVP's "Configure" mode.
| Event Name | Direction | Payload | Description | Additional Settings |
|---|
| Open | incoming | a form URL | Displays the given form in the FVP | Context Property Variable Name: See "Dynamic Page Support" above. |
| Submit | incoming | a submission URL | Submits the current form to the given URL | Submission URL: can be used in addition to the URL specified in the event payload. Refer below to the table in "Resolving the Submission URL". |
| OnOpen | outgoing | a form URL | Fired when a new form is opened by the FVP | Fire this event on open: The OnOpen event is disabled by default. It can be enabled with this setting |
| OnSubmit | outgoing | URL of submitted form | Fired when a form is submitted | See "Post Submission Behaviour" below |
| OnClose | outgoing | a submission URL | Fired when the FVP stops rendering a form | none |
Dynamic Form Events
The FVP provides the ability to publish portlet events and process portlet events that pertain to the data used by a specific form. The intention of these 'form events' is to make it possible for data from other portlets to be pushed into a rendered form, or alternatively, for the rendered form to send its data to other portlets. Form events can only be defined and configured in the FVP's "Configure" mode.
You can create form events manually or they can be automatically generated. When the Form URL is changed the FVP will ask if you want events to be automatically generated. Events are automatically generated by looking at any form data that has been marked as 'Public' using the IBM Forms Designer. Refer to the IBM Forms Designer documentation for more information.
At configuration time, outgoing (publishing) and incoming (processing) details are defined under a single form event. For example, a single form event defined with a name of Surname will result in the Wires portlet displaying publish:{http://FormPortlet/}on-Surname-change as an option for a wire's sending endpoint and process:{http://FormPortlet/}set-Surname-value as an option for a wire's receiving endpoint. We denote the events that correspond to these endpoints as a form "on change event" and a form "set value event" respectively.
A form event has a trigger and a payload. Each of these is specified by an XPath 1.0 expression which relates to the XForms data instances contained within a form. Refer to XPath 1.0 specification at http://www.w3.org/TR/xpath . XPath statements should be kept fairly simple. Not all XPath functions are supported.
The FVP publishes and processes three main data types: String, JSON, and XML. For full details see "Form Event Data Type Conversions" below.
On Change Events (outgoing)
A form event's trigger XPath is used to determine when an 'on change' event should be published. A change in any data referred to by the trigger XPath will cause an 'on change' event to fire. The payload of the 'on change' event is determined by the payload XPath.
The 'Fire this event on open' option can be used if you want the FVP to fire an 'on change' event when the form is first displayed. The event will fire regardless of whether or not the data referred to by the trigger XPath changes when the form is first displayed.
See "Form Event Data Type Conversions" below for full details on how the payload of an 'on change' event is generated.
Set Value Events (incoming)
A form event's payload XPath is used to determine which specific XML element in a XForms instance is target for the payload of the incoming 'set value' event .
Four types of actions are available for 'set value' events:
1. replace - Replaces the specified element with the incoming payload
2. insert - Adds the data as a sibling of the specified element. This sibling is placed before the specified element. You cannot insert before the root element of the instance.
3. append - Adds the data to the end of the specified data instance or element as a child element
4. delete - Delete the specified data element. You cannot delete the entire instance.
See "Form Event Data Type Conversions" below for full details on how the payload of a 'set value' event is handled.
External Event Payload Converters
Any external application can be used to convert event payload by specifying a 'Converter URL' in an event's configuration settings. Only the 'http' and 'https' protocols are supported. The converter URL must be accessible from the Portal server. Form Event Data Type Conversions
All valid data conversions are listed in the attached "FVP Form Event Data Conversions.pdf".
 Note: Any conversions that are not semantically equivalent to those listed in "FVP Form Event Data Conversions.pdf are not valid.
|
|
|
|
| Version 131 |
April 7, 2011 |
12:02:52 AM |
by Chris Dawes  |
|
|