PageHandler part in EGL source format

You declare a pageHandler part in an EGL file, which is described in EGL projects, packages, and files. This part is a primary part, which means that it must be at the top level of the file and must have the same name as the file.

An example of a pageHandler part is as follows: 

package pagehandlers ;
/* Page designer requires that all page handler parts
   be in a package named "pagehandlers". */
PageHandler ListCustomers {onPageLoad=onPageLoad}  

    use CustomerLib3;       // Library for customer table access

    customerList Customer[] {maxSize=100}; // List of customers

    Function onPageLoad()
        startkey CustomerId;   // Starting key to retrieve customers
        status int;            // Result from library cal
        
        startKey = 0;
        // Retrieve up to 100 customer records
        CustomerLib3.getCustomersByCustomerId(startKey, customerList, status);
         if ( status != 0 && status != 100 ) 
            setError("Retrieval of Customers Failed.");
         end
    End
    function returnToIntroductionClicked()
        forward to "Introduction";
    end
End

The diagram of a pageHandler part is as follows:


Syntax diagram for a pageHandler part

PageHandler pageHandlerPartName ... end

Identifies the part as a page handler and specifies the part name. For the rules of naming, see Naming conventions.

pageHandlerProperty

A page-handler property. For details, see Properties of the page handler.

use dataTablePartName, use libraryPartName

A use declaration that simplifies access of a data table or library. For details, see Use declaration.

private

Indicates that the variable, constant, or function is unavailable to the JSP that renders the Web page. If you omit the term private, you can bind the variable, constant, or function to a control on the Web page.

dataItemName

Name of a data item (a variable). For rules, see Naming conventions.

primitiveType

The primitive type assigned to the data item.

length

The structure item's length, which is an integer. The value of a memory area that is based on the structure item includes the specified number of characters or digits.

decimals

For a numeric type (BIN, DECIMAL, NUM, NUMC, or PACF), you may specify decimals, which is an integer that represents the number of places after the decimal point. The maximum number of decimal positions is the smaller of two numbers: 18 or the number of digits declared as length. The decimal point is not stored with the data.

dataItemPartName

The name of a dataItem part that is a model of format for the data item, as described in typeDef. The dataItem part must be visible to the pageHandler part, as described in References to parts.

itemProperty

An item property. For details, see Page item properties.

recordName

Name of a record (a variable). For rules, see Naming conventions.

recordPartName

The name of a record part that is a model of format for the record, as described in typeDef. The record part must be visible to the pageHandler part, as described in References to parts.

recordProperty

An override of a record property. For details on the record properties, see one of the following descriptions, depending on the type of record in recordPartName:

itemName

Name of the record item whose properties you intend to override.

itemProperty

An override of an item property. For details, see Overview of EGL properties and overrides.

constantName literal

Name and value of a constant. For rules, see Naming conventions.

arrayName

Name of a dynamic or static array of records or data items. If you use this option, the other symbols to the right (dataItemPartName, primitiveType, and so on) refer to each element of the array.

functionPart

An embedded function. For details on the syntax, see Function part in EGL source format.

Properties of the page handler

The properties of the page handler are as follows and are optional:

alias = alias

A string that is incorporated into the names of generated output. If you do not specify an alias, the pageHandler part name is used instead.

allowUnqualifiedItemReferences = no, allowUnqualifiedItemReferences = yes

Specifies whether to allow your code to reference structure items but to exclude the name of the container, which is the data table, record, or form that holds the structure item. Consider the following record part, for example: 

  Record aRecordPart type basicRecord
    10 myItem01 CHAR(5);
    10 myItem02 CHAR(5);
  end

The following variable is based on that part: 

  myRecord aRecordPart;

If you accept the default value of allowUnqualifiedItemReferences (no), specify the record name when referring to myItem01, as in this assignment: 

  myValue = myRecord.myItem01;

If you set the property allowUnqualifiedItemReferences to yes, however, you can avoid specifying the record name: 

  myValue = myItem01;

It is recommended that you accept the default value, which promotes a best practice. By specifying the container name, you reduces ambiguity for people who read your code and for EGL.

EGL uses a set of rules to determine the area of memory to which a variable name or item name refers. For details, see References to variables and constants.

includeReferencedFunctions = no, includeReferencedFunctions = yes

Indicates whether the page-handler bean contains a copy of each function that is neither inside the page handler nor in a library accessed by the page handler. The default value is no, which means that you can ignore this property if you are fulfilling the following practices at development time, as is recommended:

  • Place shared functions in a library

  • Place non-shared functions in the page handler

If you are using shared functions that are not in a library, generation is possible only if you set the property includeReferencedFunctions to yes.

msgResource = logicalName

Identifies a Java resource bundle or properties file that is used in error-message presentation. The content of the resource bundle or properties file is composed of a set of keys and related values.

A particular value is displayed in response to the program's invoking the EGL system function sysLib.setError, when the invocation includes use of the key for that value.

onPageLoad = functionName

The name of a page handler function that receives control when the related JSP initially displays a Web page. This function can be used to set up initial values of the data displayed in the page.

title = literal

The title property is a bind property, which means that the assigned value is used as a default when you are working in Page Designer. The property specifies the title of the page.

literal is a quoted string.

validationBypassFunctions = (functionNames)

Identifies one or more event handlers, which are page-handler functions that are associated with a button control in the JSP. Each function name is separated from the next by a comma.

If you specify an event handler in this context, the EGL run time skips input-field and page validations when the user clicks the button or hypertext link that is or related to the event handler. This property is useful for reserving a user action that ends the current page-handler processing and that immediately transfers control to another Web resource.

validator = functionName

Identifies the page-handler validator function, which is invoked after all the item validators are invoked, as described in Validation in Web applications built with EGL.

view = JSPFileName

Identifies the name and subdirectory path to the Java Server Page (JSP) that is bound to the page handler. JSPFileName is a quoted string.

The default value is the name of the page handler, with the file extension .jsp. If you specify this property, include the file extension, if any.

When you save or generate a page handler, EGL adds a JSP file to your project for subsequent customization, unless a JSP file of the same name (the name specified in the view property) is already in the appropriate folder (the folder WebContent\WEB-INF). EGL never overwrites a JSP.

Related concepts
EGL projects, packages, and files
Overview of EGL properties and overrides
PageHandler part
References to parts
References to variables and constants
Typedef

Related reference
Function part in EGL source format
Naming conventions
Page item properties
Primitive types
sysLib.setError
Use declaration