Home | Websydian Documentation
Search | Print

Order Catalog Example

Order Catalog

The Order Catalog business process offers registered users the possibility to order a number of catalogs.

The business process is installed with the demo site and can be accessed using the Order Catalog menu item in the top menu. Please note that this menu item is not shown before you have logged into the demo site.

Overview

Overview of the Order Catalog business process:

The main points in this example:

Flow

The list below gives an overview of how the program and the specific actions of the user interacts. The programs being activated in each case are specified. Each program is described in detail below.

1. Start Business Process

The user presses the Order Catalog menu item in the top menu. This is registered by the runtime and the ProcessEntryPoint WICATORD is called.

This function calls the List Catalog PageGenerator WXCATLPG as this is the first page to show.

The List Catalog Page shows a list of the available catalogs, based on the Catalog file WICATAPF.

The PageGenerator starts by calling a function that handles the load of the grid (WXCATLOADG).

WXCATLOADG reads the records in the Catalog file and writes the relevant information to the grid. In addition to this, the program sets the key of the catalog file, and the key of the order header as parameters for the update event.

After calling WXCATLOADG, the PageGenerator sets the key of the order header as a parameter for the confirm event, after which it uses the template WICATORD and the values specified by the load grid function to generate the list page.

 

2. User orders a quantity of a specific catalog

The user enter a number in  the input field for a catalog line in the grid, and presses "Update".

This step can be repeated a number of times - as the user can order a number of catalogs.

 

3. Handle Update Event

The runtime receives the request and calls the Update EventHandler WICATORDU.

This program retrieves the values for the key of the order header and the identification of the selected catalog set as parameters by the load grid function. The integrity of these values are validated (it is checked that the values are the same as the ones set by the PageGenerator).

The EventHandler retrieves the quantity to order entered by the user.

It is checked whether an order is already registered (if not - this is the first catalog ordered for the session). If no order is registered, an order header is created.

An order line is created (or updated) for the catalog.

If any error has occurred, the standard error page is called. Otherwise, the list catalog page (WXCATLPG) is shown again - so that the user can order other catalogs from the list (see step 1 for a description of the functionality for the list catalog page).

This is done each time a user presses an update button on the list catalog page (step 2).

 

4. User confirms selection of catalogs

The user presses the confirm button on the list catalog page.

This is done once (after all of the catalogs are selected).

 

5. Handle Confirm Event

The runtime receives the request and calls the Confirm EventHandler WICATORDC.

This program retrieves the values for the key of the order header set as a parameter by the List Page PageGenerator. The integrity of the value is validated (it is checked that the value is the same as the one set by the PageGenerator).

The EventHandler updates the order status for the order header to confirmed.

If an error has occurred, the standard error page is called.

If no order id has been specified (no catalogs has been selected) - the list catalog page (WXCATLPG) is called again.

Otherwise the Success Page WXCATSPG is called.

The Success Page shows all of the catalogs ordered by the customer.

The first thing the Success PageGenerator does is to call the function that loads the grid showing the ordered catalogs(WXCATLOADS).

WXCATLOADS reads all of the order lines and writes information for each line to the grid.

After loading the grid, the PageGenerator finds information about the user currently logged on to the session and writes this information to the template.

Finally, the PageGenerator uses the template WXCATORDCONF to create the webpage. This page is sent to the browser.

 

Objects

The source code for the program objects can be found in the WXCATSRC source file in the library chosen as the runtime library during the installation (default WXP11PGM/WXP12PGM).

 

Detailed Program Description

ProcessEntryPoint WICATORD

A general description of ProcessEntryPoint functions can be found here.

The Order Catalog ProcessEntryPoint WICATORD is the program which is called by the Websydian Express runtime, when the Order Catalog business process is activated from the menu.

The name of the ProcessEntryPoint must correspond to the process ID defined for the process (see the documentation for Process Maintenance in the administration interface)

Interface:

As for all ProcessEntryPoints, this function must have an interface with exactly one parameter (a 7 character return code).

Functionality:

The Order Catalog ProcessEntryPoint just calls the PageGenerator WXCATLPG.

 

PageGenerator WXCATLPG

A general description of PageGenerator functions can be found here.

The List Catalog PageGenerator is called as the first page in the business process, it is called when the Update event has been activated, additionally it is called when the Confirm event has been activated before any catalogs has been selected.

The page shows a list of the catalogs that can be ordered.

Interface:

The interface consists of the Order ID for the order being handled by the session. The order header specified by this ID is created when the first catalog is selected.

Functionality:

The PageGenerator performs three basic steps:

1. Call the function that loads the grid

2. Set secure parameters for event

3. Write Page to Browser

 

Load Grid Function WXCATLOADG

The fact that the example uses a separate function to load the grid does not mean that this is the way you have to do it. It is just as valid to load the grid from the PageGenerator.

However, there is one benefit from having a separate load grid function - and that is that as we have the template as a parameter, this load grid function can be reused if the same grid is to be shown on another page.

In the example, this function is only called by the List Catalog PageGenerator.

Interface:

The interface is an identification of the template to write the grid values to and an identification of the order header currently being handled.

Functionality:

The function reads through all of the records in the Catalog file (WICATAPF).

For each record, the function does the following:

1. Set Grid Output

2. Set secure parameter for grid events

 

PageGenerator WXCATSPG

The Order Catalog Success page is called when a user has confirmed the selection of catalogs he would like to receive, and the order has been updated accordingly.

The page shows a list of the ordered catalogs and name and e-mail of the user ordering the catalogs.

Interface:

The Order ID identifying the order header that has been confirmed.

Functionality:

The PageGenerator performs three basic steps:

1. Call the function that load the grid

2. Set output for detail values

3. Write Page to browser

 

Load Grid Function WXCATLOADS

This function is called by the PageGenerator WXCATSPG. The functions handles the loading of the grid for the page.

Interface:

The interface is an identification of the template to write the grid values to and an identification of the order header currently being handled.

The function reads all of the order lines belonging to the order header identified by the parameter OrderID.

For each record the function performs the following:

1. Set Grid Output

 

EventHandler WICATORDU

A general description of the EventHandler functions can be found here.

The EventHandler is called by the runtime when the Update button in the List Catalog grid is pressed.

Interface:

As for all EventHandlers, the interface consists of two fields: A 7 character return code field and a one character Action Field.

Functionality:

1. Handle Event Registration

2. Retrieve and validate secure parameters

3. Retrieve input

4. Business Logic

5. Write Page to Browser

 

EventHandler WICATORDC

The EventHandler is called by the runtime when the Confirm button on the List Catalog Page is pressed.

Interface:

As for all EventHandlers, the interface consists of two fields: A 7 character return code field and a one character Action Field.

Functionality:

1. Handle Event Registration

2. Retrive and validate secure parameters

3. Business Logic

4. Write Page to Browser

 

Templates

HTML template: Order Catalog Page WICATORD

This HTML template is used to generate the Order Catalog Page. The Order Catalog Page is the initial page in the Order Catalog business process. On this page the user can see and order catalogs.

For more information on how HTML templates are used to generate HTML pages please read HTML Templates and Replacement Markers.

HTML template: Confirmation Page WICATORDCONF

This HTML template is used to generate the Confirmation Page which will be displayed when a user has created an order. The Confirmation Page displays a list of the catalogs that have been ordered.

Recap

The example shows how to write values to a grid using the SetGridOutput API.

It also shows how you can add secure parameters to an event using the SetParm and the SetGridParm APIs, how to retrieve these values again using the GetParm API, and how to validate the integrity of the transferred parameters using the ValidateParm API.

Additionally, it introduces the WriteErrorPage API calling a generic error page for easy reporting of errors to the user.