Home | Websydian Documentation
Search | Print

2E Function Templates

Overview

When developing with Websydian Express 2E developer, there are a small number of function types that will be made over and over again.

A 2E function template has been made for each of these types, providing parameter definitions (if the parameter interface is determined by the function type), a certain amount of program logic, and a proposed structure for the action diagram code (made by sequences in the action diagrams).

You do not have to use these 2E function templates to create your own functions, but it is recommended that you do so - or that you based on the delivered 2Efunction templates make your own versions.

A certain risk of confusion is present here.

2E uses the term templates to describe a function that you can use as a basis for you own user functions.

Websydian Express uses the tem templates to describe a html file that is used run time to generate the page sent to the browser.

To distinguish between these two very different things, the term "2E function template" is used in this documentation to specify the 2E templates.

As part of the import process, five 2E function templates is created under the *Templates file:

 

Each of these will be described in detail below.

Find more information about the three basic types of functions here.

To use a 2E function template to create your own function, go to the 2E panel "Edit Functions" and press F21.

Select the 2E function template you want to use as basis for your function.

Specify the name you want the function to have and press "enter".

You can read more about the 2E function templates and how to use them in the 2E documentation.

If you want to make your own version of the 2E function templates, do not change the delivered ones as they are likely to be adjusted in later releases. Copy the delivered 2E function templates, and make your own version of the functions instead.

If you do introduce changes to the delivered templates, they are likely to be overwritten when updating to a later release.

W2E/ProcessEntryPoint

The ProcessEntryPoint functions are called when a menu item is pressed or when a frame is populated with a business process by the frameset loader.

The normal behavior of the ProcessEntryPoint is just to call the PageGenerator for the first page shown in the business process.

Exactly one ProcessEntryPoint is made for each business process.

Parameters:

No parameters are defined for the ProcessEntryPoint.

As the ProcessEntryPoint functions are called dynamically by the runtime, you are not allowed to change the parameter interface.

Action diagram:

Normally, you should just enter a call to the PageGenerator right after the comment "Enter call to initial PageGenerator".

In some cases you might want to retrieve information from the session/user/other tables to either determine which initial PageGenerator to call or to find parameters needed to call the initial PageGenerator.

W2E/PageGenerator

The PageGenerator functions are called by either EventHandlers or ProcessEntryPoints. The PageGenerator functions specifies the values to show on the generated web page, and uses HTML template files to create the final web page. The generated page is sent to the browser.

Parameters:

No parameters are defined for the 2E function template. There are no restrictions on the interface.

Action diagram:

Change Template Name

The first thing you should do when creating a PageGenerator is to change the value for LCL.W2E/TemplateName to the name of the template used to generate the page (see the PageModeler definitions if you are in doubt).

Set values for output fields

In this section, make one call to the SetOutput API to specify the value to show for each output field shown on the page.

Set initial value for input fields

In this section, make one call to the SetOutput API for each input field for each event shown on the page.

Set parameters for events

In this section, make one call to the SetParm API for each parameter that should be transferred to the EventHandler. Please note that if the same field is needed by two EventHandler functions, you have to call SetParm twice.

WritePage:

The call to the WritePage API should be the final call in the PageGenerator. This call merges the specified HTML template with the values set by the SetOutput, SetParm APIs and sends the resulting web page to the user's browser.

W2E/EventHandler

The EventHandler functions are called when a user request is received by the Websydian Express runtime (e.g. when a user has pressed a button/link in a business process). The EventHandlers should retrieve the information entered by the user and any information transferred as secure parameters by the PageGenerator, finally the EventHandler has to call a PageGenerator function.

Parameters:

The W2E/eventHandler template defines the parameter interface of the EventHandler functions - one field, an ActionCode, is used as an input parameter.

As the EventHandler functions are called dynamically by the runtime, no changes can be made to the interface for the EventHandler functions.

Action diagram code:

In the following description the content of the 2E function template W2E/EventHandler will be shown.

This will of course also be the initial content of the function you create based on the 2E function template.

Registration of event

All functions used as EventHandlers by Websydian Express must have this behavior. You should never place any statements before this case-statement. You should always just leave the statement as it is.

Retrieve parameters set by the PageGenerator

The first thing you must do in an EventHandler function is to retrieve any secure parameters set by the PageGenerator.

Enter one call to the GetParm API for each parameter set by the PageGenerator (The PageGenerator sets these parameters using the SetParm/SetGridParm APIs).

The calls must be entered before the call to ValidateParm.

The call to the ValidateParm function is part of the content of  the 2E function template. This function checks the integrity of the parameters transferred from the PageGenerator (checks whether the retrieved values are the same as the ones set by the PageGenerator).

An error returned by the ValidateParm API indicates either a programming error (that the parameters retrieved by the EventHandler is not the same as the ones set by the PageGenerator) or an attempt to illegally change one or more parameters. Either way, this is an error that indicates that the retrieved parameters are invalid.

The W2E/EventHandler Function template retrieves an error message and calls the WriteErrorPage API. This shows the retrieved error message to the user. After this the program is terminated.

If you want to, you can call an error page which you develop yourself or you can change the message being shown. What is important is that some message is shown to the user - and that the program terminates.

Retrieve user input:

In this sequence you should enter one call to the GetInput API for each input field for the event. This retrieves the values entered in the input fields by the user.

Business logic:

Use this sequence for the necessary business logic for the event. Part of this logic will normally be to validate any user input - and if numeric data has been entered to convert the received character string to a numeric field.

Please note that you can't make any assumptions about the data entered by the user.

This holds true even if you have validated the input in the browser using JavaScript.

There is nothing which stops users from e.g. disabling JavaScript in the browser - and entering alphabetical data in a numeric field 8or invalid dates in a date field etc.). This means that the business logic you make must always be robust enough to handle invalid data.

Call Page Generator

As the final action in an EventHandler, a PageGenerator has to be called. This should be the final action made in the EventHandler.

You can of course use Case statements etc. to choose which PageGenerator to call, what is important is that exactly one PageGenerator is called for each activation of an EventHandler.

If no PageGenerator is called the user's browser will remain empty while the progress bar in the browser continues to show action - until the time out limit is reached for the request.

Instead of calling one of your own PageGenerators, you can call the WriteErrorPage API in error situations.

W2E/GridPageGenerator

A GridPageGenereator is structured exactly like the normal PageGenerators, the only difference is that the GridPageGenerator calls a function W2E/LoadGrid. This function contains the functionality for loading the grid.

When creating a function based on the W2E/GridPageGenerator, a function called W2E/LoadGrid will also be created - this function will be scoped under the same file as the W2E/GridPageGenerator.

See the description for W2E/PageGenerator for a description of the three sequences.

Calling W2E/LoadGrid

When using the W2E/GridPageGenerator function template to create a function, this function will call the created W2E/LoadGrid function with the following interface:

If you use the retrieval index for the W2E/LoadGrid, and want to show all of the records in the grid - just leave the interface as it is.

If you use the retrieval index for the W2E/LoadGrid, and want to show a subset of the records in the grid - map the key with a field containing the start position in the grid (typically received as a parameter.

If you use another access path to order the list, change the parameter to the correct access path - if you want to see a subset of the grid, map the key parameters with the start position of the grid.

If you want to make your own function loading the grid (e.g. if the data are not read from the database) - just delete the call to the W2E/LoadGrid function and enter a call to your own function.

W2E/LoadGrid

The W2E/LoadGrid function template is a "Retrieve object" function that can be used to load a grid to a web page.

The W2E/LoadGrid function is created automatically when a function is created based on the W2E/GridPageGenerator function template.

When the W2E/Loadgrid function is created, it has the retrieval index for the scoping file assigned as access path. If you need the data to be shown in another order, change the access path defined for the function.

Parameters:

If you change the access path used by the function, you should also change the parameter access path defining the key of the view to be the one used to order the list.

After doing this, you should change the parameter mapping in the function that was based on the W2E/GridPageGenerator function template.

The parameter W2E/TemplateName specifies the template the values set by the function will be written to. Having this field as a parameter allows you to use the same function to load the grid for several templates (if they should show the data in the same order.

Action diagram:

User point: Initialize routine

This user point contains an initialization of the counter used to specify the current row in the grid.

User Point: Process Data record

In this user point, each record is handled - much like a record shown in the detail region is handled in functions based on the W2E/PageGenerator function.

Set values for output fields in the grid

In this sequence you should make one call to the API SetGridOutput for each output field in the grid. Use the Par.W2E/TemplateName and LCL.W2EGridrow to map the two first parameters for the API call.

Set initial values for input fields for events

In this sequence you should make one call to the API SetGridOutput for each input field for each event in the grid. Use the PAR.W2E/TemplateName and LCL.W2EGridrow fields to map the two first parameters for the API call.

Set parameter for events

In this sequence you should make one call to the API SetGridParm for each parameter you want each event to transfer. Use the PAR.W2E/TemplateName and LCL.W2EGridrow fields to map the two first parameters for the API call.

For each grid event you will normally be transferring a unique identification of the current record. This makes it possible for the event to identify (and read) the line that the button, which was pressed was placed on.

Limiting the amount of data shown

The W2E/LoadGrid function normally loads all of the records found in the file.

In some situations you want to load the grid from a specific position. In the GridPageGenerator map the POS parameter with a field specifying the start position (after ensuring that the parameter access path is the same one used for ordering the records).

Other limitations (RST etc. are alsodone in the normal manner, just define the appropriate parameter interface and map with suitable fields).

 if you want to only load a limited number of records, make a Case statement in the Process Data Record, where you check whether enough records has been handled - if the number of records you want to show has been handled, exit the program.