Pageflow and Form Guide

CHAPTER 5

Pageflow Modeler

This chapter provides general information about how to create pageflow processes using the Pageflow Modeler. It has these sections:

• About the Pageflow Modeler

• Starting the Modeler

• About the Modeler window

• Adding activities

• Adding links

• Using scoped paths

• Creating link expressions

• Validating a process

• Adding and manipulating text labels

• Setting object display properties

• Using the layout features

• Using the zoom features

• Using the grid features

• Using the Bird's Eye View

• Creating a resource view for a pageflow

• Deleting a pageflow

About the Pageflow Modeler

The Pageflow Modeler allows you to create and save an XML document that can be executed by the pageflow engine at runtime. This document can be called a pageflow process or a process definition. Pageflow process refers to the graphical representation of the document; process definition more precisely refers to the underlying XML descriptor.

Basic procedure

Creating a pageflow process is a three-step procedure:

1. Use the graphing environment of the Pageflow Modeler to lay out the logic of your process:

   • Add activities

   • Create links between activities

   • Add labels (optional)

2. Use the Property Inspector to configure Activity and Link properties that link the process to the resources of your exteNd Director environment.

3. Save the process in your project resource set. The Pageflow Modeler translates it into the process definition that the pageflow engine can execute.

Creating a view for a pageflow

You can create a custom view of all resource files that are associated with a pageflow. Once you've created the view, you can use display it on the View tab.

exteNd Director allows you to export the contents of a view to a JAR. When you export resources from a view, exteNd Director creates a JAR that contains all of the elements in the view, including the directory structure—plus the XML file that defines the view from which the resources were exported. This JAR can then be imported into another resource set.

    For details on creating a view for a pageflow, see Creating a resource view for a pageflow.

Starting the Modeler

To start the Pageflow Modeler, you create a new process or open an existing one.

To create a pageflow process:

1. With your project open in exteNd Director, select File>New.

2. Click the Portlet tab and select Pageflow:

   

3. Click OK.

   The main window of the Pageflow Modeler opens in the editing area. The Mode activity is automatically added to the process:

   

To save a pageflow process:

1. Select File>Save from the exteNd Director menu.

   If the Pageflow Modeler detects any mistakes in the process, a popup message informs you and asks if you would like to save anyway. This validation occurs on all save events. You can address the warnings later.

2. Click Yes.

   If this is your first save, the Save As dialog appears.

   The contents of the pageflow-process folder display in your project resource set. Although you can specify another directory, it is recommended that you accept the default.

3. Specify a file name and click Save.

To open a pageflow process:

1. Select File>Open from the exteNd Director menu.

2. Navigate to the pageflow-process folder in your project resource set.

3. Double-click to open.

Process properties

You can access the process property sheet to view current information about the process and set properties.

To access process properties:

1. Do one of the following:

   • Click the Properties icon on the Modeler toolbar:

     

     OR

   • With the cursor in the Modeler window, right-click and select Properties.

   The Property Inspector displays the process properties:

   

2. Edit or view the process properties:

   Property	Description
   Name	The formal name of the process. The default is the name specified for the process descriptor. If you need to name your processes according to some naming convention, set it here.
   Description	A description of the process intended for the Pageflow Modeler user.
   Use Smart Linking	Indicates whether smart linking is enabled or disabled for the process. When smart linking is enabled, the pageflow engine identifies the target activity for a smart link and spawns a link from the current activity to the target activity. The spawned link may be cached for later use.
   Smartlink Verb	A key that is used to identify the HTTP request parameter whose value will be used to determine the target activity for a dynamic link.
   Show Precedence Labels	Specifies whether precedence labels should be displayed in the pageflow graph. When a particular activity is linked to more than one activity, the pageflow engine uses precedence to determine which link to follow. Each link has a precedence number associated with it. In cases where more than one link expression might evaluate to true, the engine evaluates the links in precedence order, following the first link that returns true.
   Template	Specifies whether this pageflow can be used as a template for the creation of other pageflows.

About the Modeler window

TIP:   To provide more screen space, you can close the Navigation and Output Panes in exteNd Director by clicking the panel view selectors:

Main features

Here are the main features of the Pageflow Modeler:

Navigating, selecting, and moving objects

To navigate the window:

1. With the General tab selected, click the Pan button on the toolbar to change the cursor to pan mode:

   

2. Drag the hand cursor on the graph area to scroll the graph in the editing area.

You can also use the horizontal and vertical scroll bars to achieve the same effect.

To select objects:

1. With the General tab selected, click the Select button on the toolbar.

   

   NOTE:   Select mode is the default.

2. Click any object to select it.

3. To select multiple objects, click empty space and drag the selection rectangle around the group. You can also select more than one object by holding down the Ctrl key while clicking objects with the mouse.

To move objects:

1. Select the objects.

2. Drag them to the desired location.

   If you move an activity, any links associated with that activity move with it.

Adding activities

An activity represents a task in a pageflow. A pageflow activity can present an interface to the user or perform background functions.

Pageflow activity types

Here is a summary of the activities in the Pageflow Modeler. For details about activity properties and usage, click the appropriate item:

Using activities

To add an activity:

1. Click the Activities tab.

   The activity toolbar displays:

   

2. Select an activity type.

       See Pageflow activity types for more information about the activity types.

3. Click anywhere on the graph to place the object.

To add a database activity:

1. Click the Database tab.

   The activity tool bar displays:

   

2. Select an activity type.

       See Pageflow activity types for more information about the activity types.

3. Click anywhere on the graph to place the object.

To delete an activity:

1. Select the activity.

2. Press the Delete key or right-click and select Delete.

To access activity properties:

1. Select the activity.

2. Right-click and select Properties, or click the Eye icon on the General tab.

3. Click the appropriate tab in the property sheet.

       The properties are specific for the activity type. For more information, see Pageflow activity types.

To open the source file for an activity:

1. Select the activity.

2. Click the General tab.

   The General toolbar displays:

   

3. Click the Open Primary Editor icon on the toolbar.

   

   The source file is displayed in an editor.

Adding links

A link is a single logical path from one activity to another activity. Links are represented by arrows in the Pageflow Modeler.

Pageflow link types

Below is a summary of the activities in the Pageflow Modeler. For details about usage and setting link properties, click on the appropriate item:

To create a link:

1. Click the Links tab.

   The link toolbar displays:

   

2. Select a link type.

3. Click an activity and drag from the starting activity to the target activity, then release the mouse button.

       You can use link segments to enhance the legibility and appearance of the pageflow. For more information on link segments, see Drawing a link segment.

To delete a link:

1. Select the link.

2. Press the Delete key or right-click and select Delete.

To access link properties:

1. Select the link.

2. Click the Eye icon on the General tab or right-click and select Properties.

3. Click the appropriate tab in the property sheet.

       Properties are specific for the link type. For more information, see Pageflow link types.

Drawing a link segment

A segment is the line between two points of a link. Segments are purely cosmetic. You can use them to enhance the legibility and appearance of the pageflow. Here is a pageflow diagram that shows a link (Link 2) with three segments:

To draw a segment:

1. Click any point on a link and drag in any direction.

   The point you drag becomes the bend in the link.

2. Release the mouse button at the point you want to end the segment.

3. Click again and drag to add another segment.

4. For the final segment, drag to the destination activity and click it.

Using scoped paths

Scoped paths allow you to associate data with pageflow activities and links. exteNd Director provides a set of predefined scoped paths that you can access using the scoped path dialogs and the Scoped Path Navigator.

    For background information about scoped paths, see the chapter on working with scoped paths in Developing exteNd Director Applications.

This section describes how to:

• Associate scoped paths directly with the primary property for an activity

• Copy scoped paths before or after an activity or a link executes in the flow

• View scoped paths used in a flow

• Copy scoped paths to the clipboard

    For information about scoped path usage with examples, see Using scoped paths in a pageflow.

Associating a scoped path with an activity

You can use a scoped path to associate an object with an activity. To do this, you specify a scoped path as the value for the activity's primary property. You can do this with any of the following types of activities:

• Form activity

• HTML activity

• XML activity

• Pageflow activity

• JSP activity

• Servlet activity

• Web Service activity

• Composer Service activity

• XSL activity

• Rule activity

• Java activity

To associate a scoped path with an activity's primary property:

1. Select the activity, then right-click and select Properties.

2. In the Property Inspector, click the tab that has the primary property. This tab typically has the same name as the activity. For example: the HTML activity has an HTML tab where you can set the primary property, and the Form activity has a Form tab.

3. Click the primary property for the selected activity. For details, see Pageflow activity types.

   The Choose The Scope dialog displays:

   

   The dialog displays the default predefined path for this activity type.

4. Use one of these methods to specify the path:

   • Type the path in the text box.

     This requires you to know the syntax for the scoped path. For more information, see the section on predefined scoped paths in Developing exteNd Director Applications.

     OR

   • Select any one of the paths already defined in this flow; these paths appear at the bottom of the dropdown list below the dashes.

     

     TIP:   If you choose a current path that accesses the resource set, you can display the contents of the file by clicking the icon next to the Browse button.

     OR

   • Select one of the predefined scopes at the top of the dropdown and click Browse.

     When you click Browse, the Scoped Path Navigator displays.

     

     The Scoped Path Navigator is an interactive tool that allows you to specify the path using a tree view (where applicable) and the XPath expression builder. The available options depend on the scoped path you selected.

         For more information on using the Scoped Path Navigator, see the section on using the scoped paths in Developing exteNd Director Applications.

5. After you specify the path, click OK.

Editing a scope   To edit an existing scoped path, repeat the procedure.

Copying scoped paths

With the exception of the Mode and Finish activities, you can copy scoped paths before or after the execution of any activity, and copy scoped paths after the execution of a any link.

    For design considerations that relate to copying scoped paths, see the section on copying scoped paths in Developing exteNd Director Applications.

To copy a scoped path before or after an activity:

1. Select the activity, then right-click and select Properties.

2. In the Property Inspector, click the Copy Scoped Paths tab:

   • To copy the scoped path before execution, click the link Edit Scoped Paths under Copy Before.

   • To copy the scoped path after execution, click the link Edit Scoped Paths under Copy After.

   The appropriate Copy dialog (Copy Before or Copy After) displays:

   

3. Click the ellipsis for From scope.

   The dialog displays the default predefined scope for this activity type. If you want to use another scope, select it from the dropdown list.

4. To specify the path, use one of the methods described in Step 3 in the preceding procedure (To associate a scoped path with an activity's primary property:).

5. Click the ellipsis for To scope. Repeat the procedure for specifying the From scope.

6. Click Add and then OK to exit the Copy Scope dialog.

To edit a scope   To edit an existing scope, repeat the procedure—but click Update instead of Add.

To copy a scoped path after the execution of a link:

1. Select the link, then right-click and select Properties.

2. In the Property Inspector, click the link Edit Scoped Paths under Copy Scoped Paths.

   The Copy Scoped Paths dialog displays:

   

3. Click the ellipsis for From scope

   The dialog displays the default predefined scope for this activity type. If you want to use another scope, select it from the dropdown list.

4. To specify the path, use one of the methods described in Step 3 in the preceding procedure (To associate a scoped path with an activity's primary property:).

5. Click the ellipsis for To scope. Repeat the procedure for specifying the From scope.

6. Click Add and OK to exit the Copy Scope dialog.

7. On the Copy Scope dialog click Add and OK to exit the Copy Scope dialog.

To edit a scope   To edit an existing scope, repeat the procedure—but click Update instead of Add.

Accessing scoped paths

You can view all of the current paths used for a selected object in the flow or for all objects in the flow.

To access current scoped paths for an activity or link:

1. Select the object.

2. Right-click and choose Scoped paths.

   The Available Scoped Paths dialog displays.

To access all current paths in the flow:

1. From the Pageflow menu

   • Select View Scoped Paths.

     OR

   • With no objects selected, right-click and choose Scoped paths.

   The Available Scoped Paths dialog displays.

2. Click a scoped path. Notice that the objects that use it are highlighted:

   

Copying a scoped path to the clipboard

From the Available Scoped Paths dialog you can copy a selected path to the clipboard and paste it wherever you want.

To copy a scoped path to the clipboard:

1. Access the scoped paths using one of the methods described in the preceding section.

2. Select the path you want to copy.

3. Double-click the path, or click Copy to Clipboard at the bottom of the dialog.

4. Go to where you want to copy the path and press Ctrl+V.

Creating link expressions

Link expressions let you use runtime values to choose between multiple target activities. When an activity finishes processing, you can use expressions to determine which activity should be executed next. The expression builder allows you to test runtime values in simple or compound expressions that evaluate to true or false. Expressions apply to simple links and button links only.

    For more information on simple links, see Simple link. For more information on button links, see Button link.

To specify a link expression:

1. Select a simple link or a button link, right-click, and select Properties.

2. In the Property Inspector, select Edit Expression.

   The Expression dialog displays:

   

3. Click ... to access a scope.

4. To specify the path, use one of the methods described in Step 4 in the procedure To associate a scoped path with an activity's primary property:.

5. In the Value field, specify the value to test against the scoped data.

6. Select the operator from the data operator dropdown list.

7. Select the data type (which must match the scoped data) in the data type dropdown.

   • For Boolean, you must enter true or false.

   • For Timestamp, use this format:

       MM/DD/YYY < optional: HH:MM:SS>
     

   The expression builder validates your entry.

8. Click Add.

   This adds the expression to the text area at the bottom.

9. To add additional clauses to the expression, select the appropriate item from the logical operator dropdown, complete the clause, and click Add. Add as many clauses as you need.

   NOTE:   To negate the current expression, enable the Not check box.

10. To edit or delete an expression, click Update or Delete.

11. Click OK when you're done.

Validating a process

You can validate a process at design time whenever you choose. The modeler analyzes the process structure and displays any errors encountered. Note that the validation applies to the design-time process structure only.

To validate a process:

• Select Validate Process from the Pageflow menu.

  OR

• With or without any objects selected, right-click and select Validate Process.

Adding and manipulating text labels

Labels are separate objects in the graphing environment and have their own property sheets. Labels have two forms:

• Floating labels

• Attached labels

Floating labels

Floating labels are simply text you place on your pageflow graph and have no association with another pageflow graph object. Titles, version numbers, notes, and legends are all good uses for floating labels.

To create a floating label:

1. From the Pageflow Modeler toolbar, select the Text Block button:

   

2. Click the location on the graph where you want the label to appear.

   The label appears as a box with the text Untitled inside.

3. From the toolbar, select the arrow button.

4. Double-click inside the new label and edit the text.

5. Click outside the label to save your changes.

Attached labels

Most labels are associated with an activity or link and are called attached labels. By default, activities and links start with a label.

To edit an attached label:

1. Right-click an activity icon or link.

2. From the popup menu, select Create Label.

   A label appears directly below the activity or link.

3. Double-click inside the label and edit the text.

4. Click outside the label to save your changes.

An activity or link can have many labels. You can reposition the attached label by dragging it to a new location. Note the line that appears as you drag. This line indicates the activity or link the label is attached to.

To format any label:

1. Right-click the label and select Properties.

   The Property Inspector displays showing the current formatting properties.

2. Make your changes. Properties are described in Setting object display properties.

   Changes are saved as you make them.

To delete a label:

1. Select the label.

2. Press the Delete key.

Setting object display properties

Each activity, link, and label has a set of properties associated with it. Select and right-click an element, and the properties of the element are displayed in the Property Inspector. The table below describes the graphical properties found on some or all of the elements:

Using the layout features

The layout is the arrangement of the activities, links, and labels in your graph. The Pageflow Modeler has a sophisticated layout feature that can completely rearrange your graph to maximize readability and minimize space.

You can specify whether you want the new arrangement to have a horizontal or vertical orientation and whether you want link links drawn as diagonal lines or composed of perpendicular segments.

There are two kinds of layout: full layout and incremental layout.

Full layout

Full layout gives the Pageflow Modeler great freedom to move activities, links, and labels around the graph.

For example, this figure displays a hand-arranged layout:

This figure shows the result of applying a full layout to the hand-arranged layout:

To apply a full layout:

• Choose Pageflow>Full Layout from the exteNd Director menu:

  OR

• Press Ctrl+Shift+L.

Incremental layout

Incremental layout tries to make a graph more attractive and organized but also tries to keep the basic design of your hand-arranged layout.

This figure shows the result of applying an incremental layout to the hand-arranged layout shown above:

TIP:   Try a layout on your graph. Select Edit>Undo to back out of a layout you don't want.

To apply an incremental layout:

• Choose Pageflow>Incremental Layout from the development environment menu.

  OR

• Press Ctrl+Shift+M.

Setting preferences

You can set layout preferences for a pageflow graph. These preferences let you specify whether you want the new arrangement to have a horizontal or vertical orientation and whether you want link links drawn as diagonal lines or composed of perpendicular segments.

To set layout preferences:

1. Choose Pageflow>Layout Settings from the development environment menu.

   

2. Select an orientation.

3. Select a link style.

4. Click OK.

Using the zoom features

The Pageflow Modeler gives you four ways to zoom:

Using the grid features

The Pageflow Modeler includes a drawing grid that works much like the grid in any graphics program:

• When the grid is visible, the corners of activity and label objects stick to the intersections of horizontal and vertical grid lines. This makes it much easier to line up objects and use consisting spacing.

• When the grid is invisible, objects can be positioned without constraint in one-pixel increments.

• Turning the grid on does not reposition existing items to align with the grid.

To turn the grid on or off:

• Choose Pageflow>Toggle Grid from the exteNd Director menu.

  OR

• Click the Grid button from the Pageflow Modeler toolbar:

  

  OR

• Press Ctrl+Shift+G.

To change the spacing of grid lines (grid size):

1. Choose Pageflow>Grid Size from the exteNd Director menu.

   The Grid Size dialog displays:

   

2. Enter a value in pixels from 7.5 to 1000.

   The default is 10.

3. Click OK.

Using the Bird's Eye View

The Bird's Eye View is a popup window that gives you a view of the entire pageflow graph to help you find your way around in a large graph. The Bird's Eye View window:

• Appears when you click the Bird's Eye View button on the Pageflow Modeler toolbar:

  

• Stays on top as you work in the graph area

• Is dismissed by clicking the X button in the upper-right corner

• Can be resized by dragging the corners

• Indicates the area visible in the graph window with a blue outline box

You can use the blue outline box of the Bird's Eye View window to do several useful things:

Creating a resource view for a pageflow

You can create a custom view of all resource files that are associated with a pageflow. Once you've created the view, you can display it on the View tab.

exteNd Director allows you to export the contents of a view to a JAR. When you export resources from a view, exteNd Director creates a JAR that contains all of the elements in the view, including the directory structure—plus the XML file that defines the view from which the resources were exported. This JAR can then be imported into another resource set.

TIP:   To get to the View tab, you need to first click the Resources tab in the exteNd Director Navigation Pane.

    For more information on views, see the chapter on working with views in Developing exteNd Director Applications.

To create a resource view for a pageflow process:

• Choose Pageflow>Create Resource View from the exteNd Director menu.

  The view created has the same name as the pageflow process descriptor. The view definition is stored as an XML document in the my-views folder within the resource set.

Deleting a pageflow

To remove a pageflow, you need to delete the pageflow process descriptor file. When you delete the descriptor file, any files referenced by the pageflow (such as Java source files, HTML files, XML files, and other resources) are not removed. Therefore, if you want to remove these files, you need to delete them by hand.

When you create a pageflow, the Pageflow Modeler saves a portlet fragment deployment descriptor in the resource set. When you delete a pageflow, you need to delete this descriptor and unregister the portlet as well.

    For more information about deleting portlets, see the section on deleting portlets in the Portal Guide.

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...