Websydian v6.1 online documentationOnline documentation - Websydian v6.5

Other Uses of the Event Handler

Contents

Define Own Template Event Handler

When defining new Event Handlers, inheritance can be specified from an application specific Template Event Handler from which all application Event Handlers inherit.  All common definitions can then be placed in this template pattern.  An example of such additional definitions could be Session Management.

Validate HTML Form Input Fields

Through the pattern EventHandlerWithValidation, validation functionality becomes a part of the Websydian Event Handler functionality.  The implemented validation is similar to the validation functionality implemented by the UISTYLE/InsertEdit pattern.

The field WsyBase<InstanceValid> indicates if any errors were found during validation.  If an error was found, the developer may call an Error Page function.  In this way, it is up to the Websydian developer to define the appropriate action when errors are found during validation (e.g. return without updating if error).

The validation may be suppressed by defining Event Handler functions that do not inherit from the EventHandlerWithValidation pattern.

Definition of Common Event Handler Functions

An Event Handler function can be reused even though it is scoped under another Page Generator function.  This may be the case if a web event is identical with an event on another HTML page.

An Event Handler function from another page can be used by an HTML page by using the FNC comprises FNC triple.

Example:

WWW Display employees triples

The Page Generator function specified above uses its own five 'private' event handler functions as well as it refers to the Event Handler function WebDisplayDepartments.

Comprising an Event Handler function scoped elsewhere in the model like this works the same way as the normal inclusion of Event Handler functions.

Event Handler functions used in more than one HTML page may be scoped within a Page Generator function or they can be put elsewhere in the model.

Conversion Between Internal and External Field Representation

If a field has an internal and external form that differs (specified by a FLD displayed as FLD triple), the field is interpreted according to its external representation and converted to the internal representation.  This is specified by inheritance from the EventHandlerWithFieldConversion.

Remember to add the target field of the FLD displayed as FLD triple to the WebInput variable and hide the source field by declaring it for the Hidden variable.

Conversion fields between internal and external representation can be suppressed by defining Event Handler functions that do not inherit from the EventHandlerWithFieldConversion pattern.

Caption Text of Push Buttons

The caption text of the push buttons generated from Event Handler functions will by default be set to the unqualified name of the Event Handler function. If a FNC name NME triple is specified for the Event Handler then the name of the NME object will be used for the push button.

Special characters not supported by Plex names for the caption text of a push button can be specified manually in the Document Template by an HTML editor.

Appearance and Interpretation of Language Dependent Fields

Various options can be set for the Dispatcher function influencing the appearance and interpretation of the date/time and number input fields on the generated HTML documents. Refer to the section Specification of Field Appearance and Interpretation in the Event Dispatcher help pages.

POST and GET as HTML Form Output Methods

When the web user triggers an event, an event HTML form is sent to the web server. In HTML, this can be done either by the POST method or the GET method. The Event Handler function supports both methods (an Error Page is generated by the Event Handler function if the form method is not recognized at all).

HTML forms in the template documents generated by the Document Template Generator functions are generated with POST as their form method. We recommend always to use the POST method as the GET method may give rise to problems when passing parameters and if using a proxy server (requests may not be reloaded on a proxy server using the GET method).

If, for some reason, the GET method is preferred, the generated HTML template documents should be edited manually.

Option to disable trim spaces (Windows only)

By default the EventHandler function will remove trailing spaces in character fields when data is parsed from the user request sent from the browser.

This functionality can be disabled using the following function option:

Source Object Verb Target Object
MyEventHandler option NME
...value SYS
Trim trailing blanks
No

Option to add target frame information to EventHandlers

The option Target frame enables the developer to specify a target frame for an EventHandler function. Doing this has the effect that the PageGenerator function called by the EventHandler function will send the generated output to the specified frame.

The name of the frames being used is defined by the implementation name of the EventHandler functions comprised or included by the FramesetPageGenerator.

For example consider the following definition of a FramesetPageGenerator scoping two frames: TopFrame and BottomFrame.

Source Object Verb Target Object
MyFrameSetPageGenerator is a FNC FramesetPageGenerator
includes FNC TopFrame
BottomFrame
impl name NME FramePage
file name NME FramePage
TopFrame is a FNC EventHandler
calls FNC TopFramePageGenerator
BottomFrame is a FNC EventHandler

For an event to be located in the TopFrame but targeting the BottomFrame the following triples must be added:

Source Object Verb Target Object
TopFramePageGenerator includes MyEventHandler
MyEventHandler option NME
...value SYS
WSYBASE/Target frame
Yes
comprises FNC BottomFrame

Adding _blank target frame (new window) to the EventHandler

It is possible to specify that the target frame should be a new window by using the _blank frame name. To implement this create a dummy EventHandler function that represents the _blank frame.

Source Object Verb Target Object
NewWindowTarget is a FNC EventHandler
file name NME _blank
impl name NME _blank
implement SYS No

Now add the option to the event handler that is required to have a target frame information.

Source Object Verb Target Object
MyEventHandler option NME
...value SYS
WSYBASE/Target frame
Yes
comprises FNC NewWindowTarget

Option to add target _top frame information to EventHandlers

The option Target top enables the developer to specify that the _top frame (entire page) should be the target for the output generated by the PageGenerator function.

Source Object Verb Target Object
MyEventHandler option NME
...value SYS
WSYBASE/Target top
Yes

With the above triples the PageGenerator functions called by the MyEventHandler functon will be sent to the _top frame, thereby reloading the entire browser window.