PageHandler

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

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

The PageHandler itself includes variables and the following kinds of logic--

Note: The OnPageLoad function is identified in PageHandler property onPageLoadFunction; the name can be any valid EGL function name. The OnPageLoad function automatically retrieves any user-supplied arguments that were passed to it; can invoke other functions or call other programs; 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.
The variables in the PageHandler are accessed in two ways:

The PageHandler part should be simple. Although the part might include lightweight 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 PageHandler

When you save a PageHandler, EGL places a JSP file in the project folder WebContent\WEB-INF, but only in this case:
  • You assigned a value to the PageHandler view property, which specifies a JSP file name
  • The folder WebContent\WEB-INF does not contain a JSP file of the specified name

When generating a PageHandler, EGL never overwrites a JSP file.

If a Workbench preference is set to automatic build on save, PageHandler generation occurs whenever you save the PageHandler. In any case, when you generate a PageHandler, 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. In the documentation that refers to runtime events, the word PageHandleris sometimes used to refer to the page bean.
  • 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 PageHandler) with the JSP file to be invoked.
  • A JSP file, in the same situation as when you save the PageHandler.

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 runtime does the necessary processing as soon as the user submits the Web page. If errors are found, the JSF runtime may re-display the page without passing control to the PageHandler. If the PageHandler receives control, however, it may conduct a set of EGL-based validations.

The EGL-based validations occur if you specify the following details when you declare the PageHandler:
  • 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 validator functions for individual input fields.
  • The validator function for the PageHandler as a whole.
The PageHandler oversees the edits in the following order, but only for fields 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 PageHandler field 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 fields defined in the PageHandler, from top to bottom. If validationOrder is defined for some but not all of the fields in a PageHandler, validation of all fields with the validationOrder property occurs first, in the specified order. Then, validation of fields without the validationOrder property occurs in the order of fields in the PageHandler, from top to bottom.

If the EGL runtime finds an error outside of a validator function, the JSF runtime code re-displays the same Web page with embedded error messages. If a validator function finds an error, the function can forward control to another Web page, but the default behavior is to re-display the same Web page.

Runtime scenario

This section gives a technical overview of the runtime interaction of user and Web application server.

When the user invokes a JSP that is supported by a PageHandler, the following steps occur:
  1. The Web application server initializes the environment--
    1. Constructs a session object to retain data that is needed across multiple interactions with the user:
      • If the PageHandler scope property is set to session, the page bean will be assigned to the session object.
      • In any case, EGL provides the following system functions, which let you place data into the session object and let you retrieve or clear data from the session object: J2EELib.setSessionAttr, J2EELib.getSessionAttr, and J2EELib.clearSessionAttr.
    2. Constructs a request object to retain data on the user's current interaction with the user:
      • If the PageHandler scope property is set to request, the page bean will be assigned to the request object
      • In any case, EGL provides the following system functions, which let you place data into the request object and let you retrieve or clear data from the request object: J2EELib.setRequestAttr, J2EELib.RequestAttr, and J2EELib.clearRequestAttr
    3. Initializes the JSF runtime code
    Note: Even when a PageHandler scope property is set to session, the data in that PageHandler is not necessarily available throughout the user session. If PageHandler A forwards control to PageHandler B, for example, the data in PageHandler A is no longer available unless you took action like the following:
    • Included the data in arguments that are passed to the new PageHandler; or
    • Included the data in the session or request object; or
    • Included the data in a relational database or other data store.
  2. The JSF runtime code acts as follows--
    1. Invokes the JSP file, which a JSF configuration table associates with a particular page bean
    2. Creates the page bean
    3. Assigns the page bean to the session or request object, depending on the value of the PageHandler scope property
    4. Gives control to the page bean's onPageLoad function (if any), providing any user-specified arguments
  3. The JSP accesses data directly from the page bean, for inclusion in the Web page; then displays the Web page to the user, leaving the session object in place and (more temporarily) leaving the request object in place
  4. The user might (for example) supply data in the on-screen fields associated with an HTML <FORM> tag, then click the SUBMIT button to invoke a PageHandler function.
  5. The JSF runtime acts as follows:
    1. Destroys the request object; and, if the scope property for the PageHandler was set to request, removes the page bean
    2. Constructs a new request object
    3. Does the next steps only if the PageHandler scope was set to request:
      1. Creates the page bean
      2. Assigns the page bean to the request object
      3. Gives control to the page bean's onPageLoad function (if any), providing any user-specified arguments
    4. Handles JSF validation (but only a subset of JSF validation is possible in the context of EGL PageHandler processing):
      • Places the user data into the page bean (if the input was found to be valid from a JSF point of view); or
      • Re-displays the Web page with JSF messages (if the input was found to be invalid). The subsequent steps in this scenario occur if the input data was valid.
    5. Places the data received from the submitted form into the page bean, for EGL validation (which is described earlier). If no error occurs, the JSF runtime code invokes the PageHandler function requested by the user:
      • If the function ends without issuing a forward statement, the JSF runtime code re-displays the same Web page without re-invoking the OnPageLoad function.
      • If the function ends with a forward statement that refers to the same Web page, the situation is the same as in the previous case; the OnPageLoad function is not re-invoked
      • If the function ends with a forward statement that refers to a different page, the data in the page bean is lost, although you may pass arguments and retain values in either the session or request object
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.