PageHandler part

An EGL page handler is an example of page code; it controls a user's run-time interaction with a Web page and can do any of these tasks:

• Assign data values for submission to a JSP file. Those values are ultimately displayed on a Web page.

• Change the data returned from the user or from a called program.

• Forward control to another JSP file.

You can work most easily by customizing a JSP file and creating the page handler in Page Designer; for details, see Page Designer support for EGL.

The page handler itself includes variables and the following kinds of logic--

• An OnPageLoad function, which is invoked the first time that the JSP renders the Web page

• A set of event handler functions, each of which is invoked in response to a specific user action (specifically, by the user clicking a button or hypertext link)

• Optionally, validation functions that are used to validate Web-page input fields

• Private functions that can be invoked only by other page-handler functions

The variables in the page handler are accessed in two ways:

• The run-time environment accesses the data automatically. If a field in the JSP is bound to an item in the page handler, the result is as follows--
  • After the OnPageLoad function runs and before the Web page is displayed, each page-handler item value is written to the JSP field to which the data is bound.

  • When the user submits a form in which bound JSP fields reside, the value in each field of the submitted form is copied to the associated page-handler item. Only then is control passed to an event handler. (However, this description does not include the validation steps, which are covered later in this topic.)

• The event handlers and the OnPageLoad function also can interact with the data, as well as with data stores (such as SQL databases) and with called programs.

The pageHandler part should be simple. Although the part might include light-weight data validations such as range checks, you are advised to invoke other programs to perform complex business logic. Database access, for example, should be reserved to a called program.

Output associated with a page handler

When you save a page handler, EGL places a JSP file in the project folder WebContent\WEB-INF, but only in this case:

• You assigned a value to the page-handler view property, which specifies a JSP file name

• The folder WebContent\WEB-INF does not contain a JSP file of the specified name

EGL never overwrites a JSP file.

If a Workbench preference is set to automatic build on save, page-handler generation occurs whenever you save the page handler. In any case, when you generate a page handler, the output is composed of the following objects:

• The page bean is a Java class that contains data and that provides initialization, data validation, and event-handling services for the Web page.

• A <managed-bean> element is placed in the JSF configuration file in your project, to identify the page bean at run time.

• A <navigation-rule> element is created in the JSF application configuration file to associate a JSF outcome (the name of the page handler) with the JSP file to be invoked.

• A JSP file, in the same situation as when you save the page handler.

All data tables and records that are used by the part handler are also generated.

Validation

If the JSP-based JSF tags perform data conversion, validation, or event handling, the JSF run time does the necessary processing as soon as the user submits the Web page. If errors are found, the JSF run time may re-display the page without passing control to the run-time page handler. If the page handler receives control, however, the page handler may conduct a set of EGL-based validations.

The EGL-based validations occur if you specify the following details when you declare the page handler:

• The element edits (such as minimum input length) for individual input fields.

• The type-based edits (character, numeric) for individual fields.

• The DataTable edits (range, match valid, and match invalid) for individual input fields, as explained in DataTable part.

• The edit functions for individual input fields.

• The edit function for the page handler as a whole.

The page handler oversees the edits in the following order, but only for items whose values were changed by the user:

1. All the elementary and type-based edits, even if some fail

2. (If the prior edits were successful) all the table edits, even if some fail

3. (If the prior edits were successful) all the field-edit functions, even if some fail

4. (If all prior edits were successful) the pageHandler edit function

The page-item property validationOrder defines the order in which both the individual input fields are edited and the field validator functions are invoked.

If no validationOrder properties are specified, the default is the order of items defined in the page handler, from top to bottom. If validationOrder is defined for some but not all of the items in a page handler, validation of all items with the validationOrder property occurs first, in the specified order. Then, validation of items without the validationOrder property occurs in the order of items in the page handler, from top to bottom.

Run-time scenario

This section gives a technical overview of the run-time interaction of user and Web application server.

When the user invokes a JSP that is supported by a page handler, the following steps occur:

1. The Web application server initializes the environment--
   1. Constructs a session object to retain data that the user-accessed applications need across multiple interactions

   2. Constructs a request object to retain data on the user's current interaction

   3. Invokes the JSP

2. The JSP processes a series of JSF tags to construct a Web page--
   1. Creates an instance of the page handler, causes the onPageLoad function (if any) to be invoked with user-specified arguments, and places the page handler into the request object

   2. Accesses data stored in the request and session objects, for inclusion in the Web page

   Note: The pageHandler part has a property called OnPageLoad, which identifies the page-handler function that is invoked at JSP startup. The function automatically retrieves any user-supplied arguments that were passed to it; can call other code; and can place additional data in the request or session object of the Web application server; but the function can neither forward control to another page nor cause an error message to be displayed when the page is first presented to the user.

3. The JSP submits the Web page to the user, and the Web application server destroys the response object, leaving the session object and the JSP.

If the user supplies data in the on-screen fields associated with an HTML <FORM> tag and submits the form, the following steps occur:

1. The Web application server re-initializes the environment--
   1. Constructs a request object

   2. Places the received data for the submitted form into the page bean, for validation

   3. Re-invokes the JSP

2. The JSP processes a series of JSF tags to store the received data in the page bean.

3. The run-time page handler validates data:
   1. Does relatively elementary edits (such as minimum input length), as specified in the pageHandler data declarations

   2. Invokes any item-specific validation functions, as specified in the pageHandler data declarations

   3. Invokes a pageHandler validator function, as is needed if you wish to validate one field at least partially on the basis of the content of another field

   (For details on validation, see the previous section.)

4. If an error occurs, the EGL run time places errors on a JSF queue, and the JSP re-displays the Web page with embedded messages. If no error occurs, however, the result is as follows:
   1. Data stored in the page bean is written to the record bean

   2. Subsequent processing is determined by an event handler, which is identified in the JSF tag that is associated with the user-clicked button or hyperlink.

The event handler may forward processing to a JSF label, which identifies a mapping in a run-time JSF-based configuration file. The mapping in turn identifies the object to invoke, whether a JSP (usually one associated with an EGL page handler) or a servlet.

Related concepts
References to parts
Web support

Related reference
Page Designer support for EGL
PageHandler part in EGL source format
Page item properties