The Page Flow is a diagrammatic representation of the
Pages and
Actions in an application. It provides a top-level view of the application as well as a place to find and define application-wide features. There is only one
Page Flow file for each application.
The Page Flow file is based on the Business Process Execution Language (BPEL), so a
Page Flow file is a BPEL file, ending in the
.bpel suffix. The
Page Flow contains a represntation of each
Page in the application. You use the Page Flow Editor to add new
Pages to the application, and to edit the
Actions that each
Page can access.
The ActiveGrid Studio provides a Page Flow Editor that allows you to work with your
Page Flows without directly editing the BPEL file itself. Although you don’t need to know BPEL to create ActiveGrid Applications, it helps to understand a little about the structure of the
Page Flow.
The Page Flow contains a reference to every
Page in the application and it defines each
Action that is available to each
Page. An
Action is essentially a piece of logic that does something and then (usually) invokes another
Page. You use the Page Flow Editor to add
Pages and
Actions to your application.
While you typically work with Pages in the Page Editor, you first add the
Pages in the Page Flow Editor. You can add predefined
Pages or custom
Pages:
•
|
Predefined Pages: The Page Flow Editor provides a variety Predefined Pages that you can add to your application ( Adding Predefined Pages). These are standard Pages that perform typical tasks, such as querying the database or list Pages for listing data from the database. A predefined Page includes all the associated Actions for that type of Page, so you don’t have to create the Actions by hand. If you want to do any further customization to the Page, open it in the Page Editor ( “Working with the Page Editor” on page 10).
|
•
|
Custom Pages: Custom Pages are just skeleton Pages. They contain no actions or Page elements. Use the Page Flow Editor to add any Actions that the Page needs to access and then use the Page Editor to add and arrange Page elements ( “Working with Pages” on page 1).
|
Once you create a Page, you can open it in the Page Editor at any time. There you can add, delete and rearrange
Page elements. You can also define
Page Variables and edit the
Page Message in the Page Editor. For more information on adding
Pages to the
Page Flow, see
Adding Pages to a Page Flow.
Before you can add a button or link to a Page, you must first specify what you want the application to do when the user clicks that link or button. In ActiveGrid Applications, that specification is called an
Action.
Actions are little snippets of logic that tell the ActiveGrid Server exactly what to do when it receives the associated submit. You create and edit
Actions in the
Page Flow (
.bpel) file.
Actions orchestrate the flow between the different
Pages. Some
Actions send specific data to the
Page and some simply call the
Page without sending any data. When you add an
Action to a
Page in the
Page Flow file, the backing data of the
Page provides the input for that
Action. The input for the
Action is held in an implicitly declared variable called
message. This variable contains the backing data of the
Page with the user changes applied.
To get things done, Actions invoke
service operations. A service operation is any operation that is available to the application. This includes operations defined in registered web services or custom code services, as well as data service operations. The most common “service operation” is simply invoking another
Page in the application.
Within each Page, a
Submit defines each button or link with which a user can send a request back to the Server. Each
Submit on a
Page references an
Action in the Page Flow Editor. Each Action must define all operations that you want the Server to perform when the user clicks the button or link:
1.
|
Before it invokes an Action, the Server applies all changes the user has made on the client to the source objects of the data (the Page can limit the changes to those relevant to the Action).
|
3.
|
When invoked, every Action implicitly has one defined variable, called message. This variable contains the backing data of the Page with the user changes applied. The message variable has the same type as the Page Message. The message variable might be empty if the Action was not invoked by a Page.
|
4.
|
What happens when the Action is invoked depends on what is in the definition of the Action. Typically, an Action populates variables with data and then pass the populated variables to service invocations. See About Custom Actions for more information.
|
To open the Page Flow Editor, open an application in the ActiveGrid Studio, and double-click on the
Page Flow (
.bpel) file in the Project Panel. The Page Flow Editor appears.
In addition to the Project Panel, which displays all the files for the project, the Page Flow Editor contains four major panels that allow you to work with different aspects of the Flow:
•
|
Tree View Panel: Shows and allows you to select Pages and Actions in the Page Flow. When you select an element in the Tree View, the item is selected in the Page Flow Editor and its properties are displayed in the Property Editor.
|
•
|
Page Flow Editor: Displays the Pages that comprise the application, including the Actions that they contain. If you double-click on an Action in the Page Flow Editor, the Action opens in either the Action Wizard or the Custom Action Editor ( The Page Flow Editor Panel).
|
•
|
Message and Log Panel: Displays messages and logs from the Server and logs from the Server and the ActiveGrid Studio.
|
•
|
Property Editor: Allows you to view and edit the properties for the selected item.
|
Each Page is displayed in a separate box under a
Page icon. The name of the
Page is the line at the top of the box and the
Actions for that
Page are listed beneath it.
When you select an Action in the Page Flow Editor, the properties associated with that
Action appear in the Property Editor.
If an Action invokes another Page, the Page Flow Editor shows a
flow arrow leading from the
Action to the invoked
Page.
In addition to the boxes representing the Pages in the application, the Page Flow Editor always includes a box called “Startup Actions”. The Startup Actions box contains the
Begin Action (
The Begin Action).
The Begin Action is a special
Action in the application that provides a default starting place for the application flow. The application calls the
Begin Action if no operation is explicitly invoked. Typically, the
Begin Action simply invokes a
Page.
The Page Frame (
PageFrame.xform) acts as a “frame” or “container” for each individual
Page in your application. Other
Pages are rendered in the MainAJAXFrame within the
Page Frame. The
Page Frame has one or two dotted flow arrows: one to the Home
Page, if it exists, and one to the
Page invoked by the
Begin Action.
The Page Frame can also contain
Actions and, if these invoke other
Pages, then those flow arrows are regular flow arrows indicating an invoke.
While most of your work with Pages takes place in the Page Editor, you do need to use the Page Flow Editor to add and delete
Pages, and to add
Actions to an existing
Page. This section explains how to add new
Pages to the
Page Flow. For more information on editing
Pages and on
Pages in general, see
“Working with Pages” on page 1.
To add a new Page to an existing
Page Flow, right-click in the Page Flow Editor to see the Page Flow Editor menu, choose the
Insert Page rollover menu and select the type of
Page you want to add to the application.
The ActiveGrid Studio provides several predefined Pages that serve as
Page templates. After you insert a predefined
Page, you can use it as-is, or you can customize it in the Page Editor. Each predefined
Page is associated with a table in the
Data Model. All are fully customizable. Each template provides layout and functionality for a commonly-occurring role in an application:
•
|
Search ( Adding a Search Page) Creates a Page that allows users to search on specified fields. You typically display the Search Page when a user clicks a Search button on another Page. When the user performs the Search, you typically display the results in a List Page.
|
•
|
List ( Adding a List Page) Creates a Page that displays a list of data items. For example, you could use a List Page to display a list of products in a catalog. When a user selects an item in the list, you might then display a Detail Page to display detailed information about that item.
|
•
|
Detail ( Adding a Detail Page) Creates a Page that displays detailed information, typically for an item that the end-user selects from a List Page. For example, you could use a Detail Page to present all the information about a product that the user selects from a catalog Page.
|
•
|
Edit ( Adding an Edit Page). Creates a Page for users to edit session or database information. For example, you could use an Edit Page for users to change their account information. The Edit Page typically displays existing data in text-entry fields.
|
•
|
Insert ( Adding an Insert Page). Creates a Page for users to add new items to the database. For example, you could use an Insert Page for a new user to create a new account.
|
You can also add a Custom Page (
Adding a Custom Page) or Service Call and Response
Pages (Adding Service Call and Response Pages). To learn more about
Pages in ActiveGrid Applications, refer to
“About Pages” on page 1.
The Search Page is a basic
Page that you display when a user clicks a Search button somewhere in the application. The default Search
Page provides an input field for each “query field” you select. It includes a
Query button for submitting the search request and an
Insert button that invokes an associated Insert
Page for users to add the data.
To add a Search Page to your application, right-click in the Page Flow Editor and in the
Insert Page rollover menu, choose the
Search... option. After you add the Search
Page, you need to add a Search
Action (
Adding a Search Action).
You typically use the List Page to display a list of data that the user has requested. For example, you might use a List
Page to show the results of the results of an
Action in another
Page, such as a Search
Action or an Edit
Action.
To add a List Page to your application, right-click in the Page Flow Editor and in the
Insert Page rollover menu,
choose the
List... option.
You typically use a Detail Page to display details about data that the user has selected. For example, if the user selects an item from a list of products, you might use a Detail
Page to display more information about the product.
To add a Detail Page to your application, right-click in the Page Flow Editor and in the
Insert Page rollover menu,
choose the
Detail... option.
You typically use a Edit Page to display data for the user to change. For example, you might use an Edit
Page to a change of address form in which the user can type in and submit a new shipping address.
To add an Edit Page to your application, right-click in the Page Flow Editor and in the
Insert Page rollover menu,
choose the
Edit... option.
You typically use an Insert Page to allow users to add new data to the database. For example, you might present an Insert
Page to a user who has asked to create a new account.
To add an Insert Page to your application, right-click in the Page Flow Editor and in the
Insert Page rollover menu,
choose the
Insert... option.
You typically use a SignOn Page to provide a
Page for users to sign into their accounts. The SignOn form is based on a table in a
Data Model, and the username and password fields are mapped to two columns from that table.
To add a SignOn Page to your application, right-click in the Page Flow Editor and in the
Insert Page rollover menu,
choose the
SignOn... option.
If your user passwords are encrypted, click to select the Is Password Encrypted? check box. When you check this box, ActiveGrid expects passwords in database (or LDAP) to be encrypted with the hash algorithm. The authentication logic hashes the user-entered password before doing a comparison. For more information on the ActiveGrid’s password encryption model, refer to
“Changing the Hash Algorithm” on page 197.
After you create your SignOn Page, you can change which
Pages require users to be signed in. You do this by editing each
Page individually. To change whether a
Page requires login, open the
Page in the Page Editor. Select the top element in the
Page. The properties for that
Page appear in the Property Editor. Click to select or deselect the
SignOn Required property. When signon is required, there is a check mark next to
SignOn Required.
Because they do not reference a table in the Data Model, Custom
Pages are typically used for local service calls or for static content. If you want to create a
Page to interact with the data in your
Data Model, create one of the predefined
Pages (
Adding Pages to a Page Flow) and modify it to suit your needs.
To add a Custom Page to your application, To add an Insert
Page to your application, right-click in the Page Flow Editor and in the
Insert Page rollover menu,
choose the
Custom... option. After you create the Custom
Page, you can:
The Page Flow Editor provides a Service Invocation Wizard that helps you create a
Page that calls a web or local service, along with a
Page to display the response to the call. The precise steps in the Service Invocation Wizard depend on the type of service you’re calling. For detailed information on using the Service Invocation Wizard for adding different types of services, see
“Adding Services to an Application” on page 138.
Use the Page Flow Editor to add an Actions to a
Page. You can add predefined
Actions, custom
Actions, or Actions that call custom code:
•
|
:Predefined Actions: The ActiveGrid Studio provides a variety of predefined Actions, such as Goto, Search, Rollback and Delete ( Adding Predefined Actions).
|
•
|
Custom Actions. You can build a custom Action, or customize a predefined Action, in the Custom Action Editor ( Customizing Actions). You need to create custom Actions when you want to add functionality that is not provided by the predefined Actions. For example, you create a custom Action to call web or custom code services.
|
•
|
Call Custom Code. You can create an Action to call your own Python or PHP code as a Local service. The ActiveGrid Studio provides a wizard to generate a skeleton code file for you in Python or PHP. The ActiveGrid Studio Tutorial contains a section that steps you through this entire process, including setting up the variables and invocations in the Action, and the input and output messages in the Service Definition file.
|
Additionally, the Page Flow always contains a Begin Action, which is a special
Action required by the application (
The Begin Action).
The Begin Action is a special
Action in the application that provides a default starting place for the application flow. The application calls the
Begin Action if no operation is explicitly invoked. Typically, the
Begin Action simply invokes a
Page.
To edit the Begin Action to invoke a different
Page, double-click on the
Begin Action and
select the
Page you want to use for the
Begin Action from the pull-down menu.
•
|
GoTo: Invoke the specified Page.
|
•
|
Update: Update the data for the corresponding Page.
|
•
|
Delete: Delete a selected data entry.
|
•
|
Search: Search the data specified by the corresponding Page.
|
•
|
Commit: Write changes to the data source.
|
•
|
Rollback: Like an “Undo”. Deletes any changes the user has made since the last commit and displays the specified Page.
|
•
|
SignOut: The SignOut Action logs the user out of the application.
|
The GoTo Action invokes another
Page. To create a GoTo
Action in a
Page, right-click in the Page Flow Editor and in the
Insert Action rollover menu,
choose the
GoTo... option.
The Insert Action either saves this new data in the session, or commits it (writes it to the data source) depending on how you configure the
Action. To create an Insert
Action in a
Page, right-click in the Page Flow Editor and in the
Insert Action rollover menu,
choose the
Insert... option.
Note: For the Commit Changes check box: If you check this box, then the application writes the user’s changes to the database when they click the submit button for this
Action. If you uncheck this check box, the application saves the users’ changes in the session but does not commit them.
To create an Update Action in a
Page, right-click in the Page Flow Editor and in the
Insert Action rollover menu,
choose the
Update... option.
Note: For the Commit Changes check box: If you check this box, then the application writes the user’s changes to the database when they click the submit button for this
Action. If you uncheck this check box, the application saves the users’ changes in the session but does not commit them.
To create a Delete Action in a
Page, right-click in the Page Flow Editor and in the
Insert Action rollover menu,
choose the
Delete... option.
Note: For the Commit Changes check box: If you check this box, then the application writes the user’s changes to the database when they click the submit button for this
Action. If you uncheck this check box, the application saves the users’ changes in the session but does not commit them.
To create a Search Action in a
Page, right-click in the Page Flow Editor and in the
Insert Action rollover menu,
choose the
Search... option.
To create a Commit Action in a
Page, right-click in the Page Flow Editor and in the
Insert Action rollover menu,
choose the
Commit... option.
To create a Rollback Action in a
Page, right-click in the Page Flow Editor and in the
Insert Action rollover menu,
choose the
Rollback... option.
The SignOut Action loads a results
Page and terminates the session (logging the user out). Inserting the SignOut
Action is extremely simple, but understanding how and when to use it can be a little tricky. Here are some things to keep in mind:
•
|
The SignOut Action loads the results Page before terminating the session. This allows you to create a personalized “good-bye” Page, with session information. When the user takes an action on this results Page, the session is terminated and no session information is available.
|
•
|
The SignOut Action is intended to provide a way for the user to terminate a session on Pages that are accessible only when the user is logged in. To set up your application so that each Page contains a sign-in or sign-out button (depending on whether the user is logged in or not) you need to create some custom code.
|
To create a SignOut Action in a
Page, right-click in the Page Flow Editor and in the
Insert Action rollover menu,
choose the
SignOut... option.
To customize an Action, right-click on it in the Page Flow Editor and select the
Customize Action option from the resulting pop-up menu. This opens the
Action in the Custom Action Editor.
Your custom Actions can include any of the following elements:
•
|
Reply: Specify a Reply (return statement) to return data to the caller, typically replying to a Web client.
|
When you double-click on a custom Action in the Page Flow Editor, the Custom Action Editor appears. You can also open any
Action in the Custom Action Editor by right-clicking on the
Action and selecting the
Customize Action... item. The following illustration shows an Action in theCustom Action Editor.
•
|
Invokes and Replies are displayed in ovals.
|
•
|
Sets, Case, and Otherwise statements appear in rectangles.
|
To add an element to the Action, right-click to access the menu, then select the element you want to add to the
Action.
To delete an element from the Action, select the element, then click the
Delete button on your keyboard.
To edit an element in the Action, select the element, then use the Property Editor to edit the properties for that element.
When you select the Action in the Page Flow Editor, these attributes appear as fields appear in the Property Editor:
When invoked, every Action implicitly contains a special variable called
message. The message variable contains the “backing” data of the
Page to which the
Action belongs. The backing data for the
Page is defined by the
Page Message for that
Page (
“Page Message” on page 5).
When the Action is invoked, the ActiveGrid Server updates the
Page data with whatever the user submitted when the
Action was called and then passes the updated data into the
Action’s message variable (with the user’s changes applied).
The Message Variable has the same type as the
Page Message. The
Message Variable might be empty if the
Action was not invoked by a
Page.
ActiveGrid provides a few variables that you can use to access session information. These variables are accessible in the Custom Action Editor as part of the
Message Variable. (You can also access these variables on the
Page itself, through
Page Variables and
Page Messages (
“Accessing Session Information on the Page” on page 7).
You can use these variables to populate Action variables (using a
Set). To use these variables, select them from the XPath picker.
The Page Flow (
.bpel) file uses variables to hold the data for
Actions. When you customize an
Action, you can define your own
Action variables and populate them with data.
When you define the variable, you must specify its data type. The available types are displayed in the Type list. This list includes all the
Page Messages for the application, as well as all the input and output messages for custom code and web services. It also contains simple types, as well as all the complex types defined in the
Data Model.
If you’re going to pass the variable into a Page, the data type for the variable should match the
Page Message for that
Page. Similarly, if you’re going to pass the variable into a service, the data type should match the service’s input message.
Typically, you populate an Action variable with a
Set (
Populating Action Variables with Data: Sets). Alternatively, you can populate a variable by invoking a service that updates the variable directly (with an output variable).
Note: The Message Variable (
How Actions Get Data: The Message Variable)
for the
Action does not appear in the
Variables section. You can access the data in the
Message Variable when you use a
Set to populate another variable.
You can set the value of a variable by adding a Set operation in the Custom Action Editor.
Sets use XPath to identify the variable to set. The
Set dialog provides an
XPath Ref... button that allows you to easily navigate to and select the variable, or the part of the variable, that you want to set.
For the other side of the
Set, the thing you’re setting the variable
from, you either use XPath again or, for a complex type, you can use a database query to set the variable.
•
|
Use the XPath Ref... button to select something from the incoming message, or from another variable, or one of the ActiveGrid session information variables ( How Actions Get Data: The Message Variable), such as the sys/selected variable. You can also use XPath arithmetic operations, boolean values, and so on.
|
The Database Query screen provides a Filter area in which you can select a specific column and choose operators that allow you to build a SQL-like query. If your query returns a single item and you want to reference it as a single item, rather than a list, remember to click the
Single Item check box.
After you pick the variable to set, you can use an XPath reference and/or an XPath expression to set the value of the variable. To use an XPath reference, just click the XPath Ref... button and navigate to the appropriate variable or variable part. Here you can choose something from the
Message Variable which includes the built-in session variable,
sys. When you make a selection here, the XPath for that selection appears in the text area.
You can also type an XPath expression in the text area. This allows you to filter the data using an XPath expression that works like a SQL “where” clause when the query is executed. Your XPath expression can use any of the following:
To do null comparisons, use the null() function combined with
= or
!= .
If the variable you’re setting is a complex type from the Data Model, then you can populate it with a database query:
•
|
Use the Filter buttons to build a filter for the Query.
|
•
|
Check the Single check box to specify that at most one object can be returned and that it should be returned directly rather than in a list.
|
•
|
Use the Page Size field to specify the number of rows to display in each Page. The default value is 30.
|
Invokes are essentially service calls.
Actions can invoke custom code service operations, web service operations, data service operations and
Page invocations. The following types of services are available to your ActiveGrid Application:
•
|
Data Service: You can invoke ActiveGrid’s built-in Data Service ( Invoking the Data Service) to perform database operations. The available operations are save, commit, rollback, insert, and delete. The Data Service does not require an input or output variable. Do not attempt to call getObject or getObjects from the Data Service. Instead, set a variable and use the database query feature.
|
•
|
Page invocations: Calls to invoke another Page in the application. If you want to send data to the Page that you’re invoking, you need to specify an input variable with the Message Type that matches the Page Message of the Page you’re invoking. For Page invocations you do not need to specify an output variable. See Invoking Another Page.
|
•
|
Reply: A Reply returns a populated variable (in XML) to the AJAXFrame from which the Action was launched. A Reply does not takes a variable argument.
|
Each custom Action must end with either with a
Page invocation or with a
Reply.
Depending on the type of invoke, you might need to specify an input variable, an output variable or both. To do this, double-click on the invoke in the Custom Action Editor. The Invoke Details screen appears. Here you specify the service and operation for the invoke, along with the input and output variable.
When you insert an Invoke in an
Action, you are prompted to specify the following:
•
|
Service: From this pull-down list, select the Service that has the operation you want to invoke. The Service list contains all the services that are in use by the application. This can be any Page in the application or the Data Service or, for Local and Web Services, the WSDL file where the messages and inputs/outputs are declared for the service.
|
•
|
Operation: The operation itself. To invoke a Page, the operation is called default.
|
•
|
Input Variable: Specifies the variable that contains the inputs for the operation.
|
•
|
Output Variable: Specifies the variable that contains the output for the operation.
|
To invoke an existing Page from an
Action, you insert an
Invoke (
Invoking a Service Operation in an Action) and make the following selection in the Invoke Wizard:
•
|
Service: From this pull-down list, select the Page that you want to invoke.
|
•
|
Operation: When you select a Page to invoke, the Wizard automatically selects the default operation. Leave this selection.
|
•
|
Input Variable: You can leave this blank or you can select an input variable for the Page. The input variable must be of the same Message Type as the Page Message.
|
The Data Service provides operations to insert/delete/save objects, or commit/rollback the transaction. To invoke the
Data Service from an Action, you insert an
Invoke (
Invoking a Service Operation in an Action) and make the following selection in the Invoke Wizard:
•
|
Service: From this pull-down list, select Data Service.
|
•
|
Input Variable: Insert, delete, and save operations require an input message with a single part containing the objects to be operated on. Select the message from the pull-down list.
|
•
|
Output Variable: Specify a variable for the output of the operation, if needed.
|
•
|
Service: From this pull-down list, select the service that you want to invoke.
|
•
|
Operation: Select an operation from the list. The valid operations are defined in the corresponding .wsdl file.
|
•
|
Input Variable: Specifies the variable that contains the inputs for the operation.
|
•
|
Output Variable: Specifies the variable that contains the output for the operation.
|
You can insert a Switch to branch the flow, invoking different operations when specified conditions are met.
Add Case statements to the
Switch and, optionally, an
Otherwise statement. For each statement you add to the
Switch, add an
Invoke or a
Set to define what the
Action does for that
Case.
To add a Case Statement to a
Switch, right-click on the
Switch and choose the
Add Case... menu option. When the Case Condition screen appears, type in the condition statement and click
Finish.
Then right-click on the Case statement and insert either an
Invoke, a
Set or a
Reply. This is what the
Action will do when the
Case condition statement is met (is true).
To add an Otherwise statement to a Switch, right-click on the Switch and choose the
Add Otherwise menu option. The
Otherwise statement appears in the Custom Action Editor. Right-click on the
Otherwise statement and insert either an
Invoke, a
Set or a
Reply. This is what the
Action will do when none of the
Case condition statements are met (are true).
You can add an Action that calls any custom code that you’ve added to your application. The
ActiveGrid Studio Tutorial has a section that walks you through this process. To create a Local Service
Action in a
Page, right-click in the Page Flow Editor and in the
Insert Action rollover menu,
choose the
Call Custom Code... option.
•
|
Service Name: from this pull-down list, select service that you want to call. To create a new Local Service, click the New button.
|
•
|
Action Name: By default, the Wizard names this Action based on the name of the operation that you selected. You can leave the default name or change the name.
|