Pageflow and Form Guide

CHAPTER 2

Working with Pageflows

This chapter introduces pageflow processes and provides several examples of complete pageflows. It includes these topics:

About the pageflow process

The core of a pageflow application is the process descriptor, an XML file that you create visually using the Pageflow Modeler. A pageflow process, which is the visual representation of the process descriptor, is a branching series of activities and links that models a set of user interactions within a portlet.

The pageflow process descriptor is placed in the pageflow-process folder within the resource set.

Process object Each pageflow process contains a global object called the process object that defines some general settings for the process as a whole.

For more information For details on setting the properties associated with the process, see Process properties.

Subflows (flows within flows) You can include a pageflow process within another pageflow process. When you do this, the embedded flow is included within the containing flow.

About the pageflow portlet descriptor

When you save a pageflow, the Pageflow Modeler saves a portlet fragment deployment descriptor in the resource set that maps your pageflow to a pageflow runner. The pageflow runner is a Java class that is implemented as a portlet. exteNd Director ships with a prepackaged pageflow runner (com.novell.afw.portal.portlet.pf.pageFlowRunner). This class can run any pageflow. You can write your own pageflow runner, but this is not necessary.

For more information about the portlet fragment deployment descriptor, see the section on the portlet fragment deployment descriptor in the Portal Guide.

Each pageflow has a separate descriptor Although all pageflows use the same portlet runner class, each pageflow has its own descriptor. The descriptor has a unique name that distinguishes it from other portlet descriptors. By default, the name given to the descriptor is the same as the name given to the pageflow. Therefore, when you save a pageflow in the Pageflow Modeler, you get two XML descriptors with the same name. These descriptors are placed in different folders within the resource set:

The pageflow process descriptor is placed in the pageflow-process folder
The pageflow portlet descriptor is placed in the portal-portlet folder

To display a pageflow on a portal page, the user must select the portlet that runs the pageflow (not the pageflow itself).

What's inside the descriptor Each portlet descriptor created for a pageflow specifies distinct initialization parameters, settings, and preferences. One of the initialization parameters, called PF_ID, specifies the name of the pageflow process to run:

  <init-param>
    <description>Pageflow ID</description>
    <name>PF_ID</name>
    <value>MyPageflow</value>
  </init-param>

Sample pageflow portlet descriptor Here is an example of a portlet descriptor that was generated for a pageflow called MyPageflow:

  <portlet xmlns="http://www.novell.com/xml/ns/portlet-fragment" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <description>MyPageflow</description>
     <portlet-name>MyPageflow</portlet-name>
     <display-name>MyPageflow</display-name>
     <portlet-class>com.novell.afw.portal.portlet.pf.pageFlowRunner
     </portlet-class>
     <init-param>
        <description>Pageflow ID</description>
        <name>PF_ID</name>
        <value>MyPageflow</value>
     </init-param>
     <expiration-cache>0</expiration-cache>
     <supports>
        <mime-type>text/html</mime-type>
        <portlet-mode>view</portlet-mode>
     </supports>
     <portlet-info>
        <title>MyPageflow</title>
        <short-title>MyPageflow</short-title>
        <keywords>MyPageflow</keywords>
     </portlet-info>
     <portlet-preferences>
        <preference>
           <name>width</name>
           <value>400px</value>
           <read-only>false</read-only>
           <data-type>String</data-type>
           <required>false</required>
           <multi-valued>false</multi-valued>
        </preference>
        <preference>
           <name>height</name>
           <value>400px</value>
           <read-only>false</read-only>
           <data-type>String</data-type>
           <required>false</required>
           <multi-valued>false</multi-valued>
        </preference>
        <preference>
           <name>Restrict Portlet Size</name>
           <value>false</value>
           <read-only>false</read-only>
           <data-type>Boolean</data-type>
           <required>false</required>
           <multi-valued>false</multi-valued>
        </preference>
     </portlet-preferences>
     <enable-title-bar>1</enable-title-bar>
     <supported-option>Restart</supported-option>
     <supported-option>edit</supported-option>
     <preview-image></preview-image>
     <auto-register enabled="true">
        <registration-id>MyPageflow</registration-id>
     </auto-register>
  </portlet>

Pageflow portlet preferences The portlet descriptor for a pageflow includes three preferences that can be used to control the runtime display of the portlet:

Preference	Description
Restrict Portlet Size	Controls whether <div> tags are placed around the result of the pageflow request. This is useful for flows that are very wide or tall. The tags will be added to the HTML only if Restrict Portlet Size is set to true and the portlet is not in a maximized state. NOTE: When the Restrict Portlet Size preference is set to true, the pageflow runner portlet automatically sets the content type to text/html. The default value for Restrict Portlet Size is false.
width	Specifies the width (in pixels) when the Restrict Portlet Size preference is set to true. This preference is ignored when Restrict Portlet Size is set to false. The default value for width is 400px.
height	Specifies the height (in pixels) when the Restrict Portlet Size preference is set to true. This preference is ignored when Restrict Portlet Size is set to false. The default value for height is 400px.

Preference

Description

Restrict Portlet Size

Controls whether <div> tags are placed around the result of the pageflow request. This is useful for flows that are very wide or tall.

The tags will be added to the HTML only if Restrict Portlet Size is set to true and the portlet is not in a maximized state.

NOTE: When the Restrict Portlet Size preference is set to true, the pageflow runner portlet automatically sets the content type to text/html.

The default value for Restrict Portlet Size is false.

width

Specifies the width (in pixels) when the Restrict Portlet Size preference is set to true. This preference is ignored when Restrict Portlet Size is set to false.

The default value for width is 400px.

height

Specifies the height (in pixels) when the Restrict Portlet Size preference is set to true. This preference is ignored when Restrict Portlet Size is set to false.

The default value for height is 400px.

Using scoped paths in a pageflow

Scoped paths allow you to access different kinds of data from your pageflow process. exteNd Director includes a group of predefined scoped paths that are available from the Pageflow Modeler and through the Scoped Path API.

Data can be in either a nonpersistent or a persistent state. Data is nonpersistent if it is available to a single user for a single application session. Data is persistent if it is available to multiple users and, potentially, other applications. In the context of scoped paths, a path is the physical location of the data within a specified scope.

Scoped paths in the Pageflow Modeler

In the Pageflow Modeler, you use scoped paths in several ways:

To bind an activity to an object (such as a rule, Java class, Web Service, HTML document, XHTML form, or other external pageflow)
To specify the instance data for an activity
To copy data from one location to another

Scopes you can use within a pageflow

All of the predefined scopes are available within a pageflow.

For more information For complete details on using the predefined scopes, see the chapter on scoped paths in Developing exteNd Director Applications.

These are some examples of scoped paths you might use within a pageflow.

Scoped path	Possible runtime value
/Request/prop/User-Agent	Mozilla 6.0 (MSIE 6.0)
/String/true	true
/ResourceSet/html/myHTML.html	The contents of the myHTML.html file.
/ResourceSet/document-template/employees.xml/emp_list/employees[@id='12345']/firstName	The first name string of the employee whose ID is 12345. This value is located in the employees.xml file within the resource set.
/Flow/document/InstanceData	The contents of an XML document stored in the document folder of the Flow scope.

Restrictions Although you can use any of the predefined scopes within a pageflow, some restrictions apply to the Request and Response scopes. For more information, see Pageflows and portlet runtime behavior.

Pageflows and portlet runtime behavior

This section discusses some of the ways in which portlet runtime behavior can change the behavior of a pageflow.

Scoped paths and portlet runtime context

At each point in the execution of a pageflow, the runtime behavior of the pageflow runner portlet has a direct effect on what kind of information is available to scoped paths. Therefore, when you're deciding which scoped paths to use in a pageflow, you need to be aware of the underlying portlet runtime context, particularly when using the Request and Response scopes.

Restrictions that apply to the Request and Response scopes When working with the Request and Response scopes, you need to be aware of these restrictions:

The api option on the Request scope is available only on render requests (in other words, during the execution of the render() method of the pageflow runner portlet).
The render option on the Response scope is also available only on render requests (within the execution of the render() method of the pageflow runner portlet).

All other Request and Response options are available on either a render (within the execution of the render() method of the pageflow runner portlet) or an action (within the execution of the processAction() method of the pageflow runner portlet).

Determining which portlet runtime context is available The following rules determine which context applies at each stage of processing within a pageflow:

When a pageflow is first loaded, the pageflow runner portlet executes the render() method. If the first activity following the Mode activity is a presentation activity (HTML, Form, JSP, or Servlet), the runner performs any Copy Before operations specified for the activity and then executes the presentation activity itself.

If there are any system activities (such as a Web Service activity, Composer activity, or Java activity), the runner portlet executes these activities in order. Any Copy Before and Copy After operations specified for these activities are also performed.

All Copy Before and Copy After operations are therefore performed within the render() phase from the time the pageflow is first initiated until the first presentation activity is executed.
If an action occurs on the first presentation activity within the flow, any Copy After operations associated with this activity are performed. The Copy After processing occurs within the processAction() method. However, if a rerender occurs (because the user clicks on a render URL or hits the browser refresh), the Copy After is performed only if the activity is preceded by a CheckPoint activity. If it is not preceded by a CheckPoint activity, the Copy After operation is not performed. The reason for this is that the Copy After is performed only when the engine moves to another activity (as it does in the case of the CheckPoint activity).

In the event of a rerender, all Copy After processing occurs within the render() method.

NOTE: Different contexts are being used under the covers for the processAction() and render() phases, so it is important to be aware of which context is available.
When system activities are executed within a pageflow, all Copy Before and Copy After processing occurs in the phase in which they run. If a system activity follows a CheckPoint, the Copy Before and Copy After operations will be executed within the render() method. If the activity does not occur after a CheckPoint, then the Copy Before and Copy After operations all occur in the processAction() method.

NOTE: All system activities executed before the first presentation activity are executed within the render() method, regardless of whether a CheckPoint is present.

Pageflow performance and portlet caching

The caching behavior of the pageflow runner portlet has a direct effect on the performance of a pageflow.

You can define an expiration cache in the portlet descriptor for a pageflow:

A value of 0 disables caching for the portlet. When you specify 0, the portlet content is never cached.
A value of -1 means the cached content never expires for that portlet. When you specify -1, the cached content is used indefinitely.
Any other positive value defines an expiration cache whose content expires after the number of seconds specified by the value. A positive value indicates the number of seconds to cache before allowing render calls.

If you want to minimize the number of render operations associated with a pageflow, you may want to set the expiration cache to a positive number.

Here's an example that shows how you might set the expiration cache:

  <portlet xmlns="http://www.novell.com/xml/ns/portlet-fragment" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <description>MyPageflow</description>
     <portlet-name>MyPageflow</portlet-name>
     <display-name>MyPageflow</display-name>
     <portlet-class>com.novell.afw.portal.portlet.pf.pageFlowRunner</portlet-class>
  <init-param>
        <description>Pageflow ID</description>
        <name>PF_ID</name>
        <value>tdbphonelistPageflow</value>
  </init-param>
  <expiration-cache>1000</expiration-cache>
  ...
  </portlet>

Pageflow logging

The following logs are provided to help you gather information about the runtime behavior of a pageflow:

Log	Description
PageFlowLog	Logs information that is common to all pageflows.
PageFlowFormLog	Logs information related to XForms processing associated with pageflows.

To modify the settings associated with these logs, you can edit the config.xml file for the Pageflow subsystem.

For example, you might want to increase the logging level for these logs from 3 to 5 to get more information about pageflows running in your application:

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE properties PUBLIC "-//SilverStream Software, LLC//DTD Framework Config XML 3.0//EN" "framework-config_3_0.dtd">
   <properties>
      <property>
          <key>PageflowService/engine-id</key>
          <value>engine-id</value>
      </property>
  	 ...
  	 <property>
          <key>PageFlowLog.LoggingLevel</key>
          <value>5</value>
      </property>
      <property>
          <key>PageFlowLog.LogFieldSeparator</key>
          <value>|</value>
      </property>
      <property>
          <key>PageFlowLog.LoggingProvider</key>
  	 	 <value>com.sssw.fw.log.EboStandardOutLoggingProvider</value>
      </property>
      <property>
          <key>PageFlowFormLog.LoggingLevel</key>
          <value>5</value>
      </property>
      <property>
          <key>PageFlowFormLog.LogFieldSeparator</key>
          <value>|</value>
      </property>
      <property>
          <key>PageFlowFormLog.LoggingProvider</key>
  	 	 <value>com.sssw.fw.log.EboStandardOutLoggingProvider</value>
      </property>
  	 ...
  </properties>

NOTE: You can also change the logging levels in the Director Administration Console.

Examples

This section presents some examples that illustrate basic pageflow concepts.

Example 1: Simple flow with HTML activities

This is a simple pageflow that shows the required Mode Activity, followed by two HTML activities connected by simple links. HTML activities are presentation activities that display static pages to the user:

Example1

Example 2: Flow with link expressions

This example shows how link expressions can be used to control the navigation paths within a pageflow. The expressions for Link 2 and Link 3 determine which button the user clicked on HTML 1. Depending on which button was clicked, the user sees HTML 2 or HTML 3:

Example2

Example 3: Flow with a system activity

The following flow shows the use of the XSL activity, which is a system activity. XSL activity 1 transforms some XML instance data. The resulting HTML output is then used as input to HTML 1.

Since the XSL activity is a system activity, it is not visible to the user. When this flow is initiated, the user sees only the HTML page:

Example3

Example 4: Web Service and XHTML forms

This flow contains a Web Service activity, another example of a system activity. This activity invokes a Web Service that gets a stock quote. Before the Web Service is invoked, the user specifies the stock symbol on an XHTML form associated with a Form activity. When the Web Service has finished processing, a second Form activity displays the quote results. To handle browser refreshes, this flow includes a CheckPoint activity. Whenever a refresh occurs, the flow returns to the Quote CheckPoint activity and continues from that point forward:

Example4

An Exception activity has also been added to this flow to handle exceptions that may occur at runtime. For example, if the Web Service being called is unavailable for some reason, the Exception activity takes control. This activity forwards processing to an HTML activity called Display Exception that displays a helpful message to the user.

This flow also shows the use of smart linking. Smart linking reduces clutter within a pageflow when many activities need to link to a common activity. In this example, the Help HTML activity is accessed by means of a dynamic link generated at runtime.

Example 5: Database pageflow

This example shows a typical database pageflow used to access a single table. It includes several database activities and forms that allow the user to enter search criteria and view search results. Also it includes activities and forms that permit the user to perform inserts, updates, and deletes.

Every database pageflow process includes a Data Set object that provides all the information required to access the database:

DBPageFlow1

This flow was generated by the Database Pageflow Wizard.

For more information on the Database Pageflow Wizard, see Database Pageflow Wizard.