Writing server scripts
When
editing Web pages in Page view of the HTML editor, you use the integrated
Script editor to add scripts for events appropriate to the context
in which you are working. You add scripts for the server events
and write other server scripts the same way you do for client event
scripts. For more information about using the integrated Script
editor, see Chapter 6, “Writing Scripts “.
System Tree
The System Tree lists the objects, methods (including EAServer methods), properties,
events, parameters, and variables you can access from server scripts:
You can drag any of these items from the System Tree and drop
them onto the Script editor (or into Source view of the HTML editor).
When you drop methods or properties into a script, the appropriate
format for the call appears; you need only supply the arguments.
psPage object
The psPage object represents a 4GL Web page. It is a global
object on the server that encapsulates the extensions to the Web
Target object model and controls page processing for 4GL Web pages.
For information about page processing, see “How page request processing
works”.
Responding to events on your page
An event-driven architecture is the foundation for working
with 4GL Web pages. Writing scripts to respond to server events
controls the data that displays on your Web page.
Server events In the events list of the Script editor, server events appear
in blue text. You must enable the 4GL Web server-side event model
to display these events in the events list (a 4GL Web page is required).
When you write a script to handle an event, an icon identifies which
events have associated scripts.
Server events for a page appear in the events list for the
window object; server events for a control appear in the events
list for a control object. Here the events list shows a partial
listing of the server events available for the page (window object):
Client events You can also write scripts for client-side JavaScript events. Client
events appear in black text in the events list. You do not need
to enable the 4GL mode to write scripts for these events.
Summary of principal events for a page
For most 4GL Web pages, you should add scripts to handle initialization, response
to page controls, and validation:
| To do this | Write a script to handle this event |
|---|---|
| Initialize page the first time a user visits it |
FirstTime |
| For pages that use self-navigation, initialize a page on subsequent visits during the same user session |
BeforeBinding |
| Respond to an action that a user performed using a page control (such as clicking a button) |
ServerAction |
| Validate a page | Validate and ValidationError |
Example 1: Initialize a page for a first visit Here the page retrieves the data about a user and displays
it in the Web DataWindow dw_cart when the page initializes:
Example 2: Validate page If the ValidationError event is fired in response to a page
validation error, the user sees the following message in an alert
box:
Summary of optional events for a page
The following
events are available on 4GL Web pages:
| This event | Occurs |
|---|---|
| RequestStart | At the very beginning of page processing, before server-side objects have been created and before any data binding or variable retrieval. |
| AfterBinding | After the controls have been bound to the input data and all validation has been done, but before any actions are performed. |
| BeforeAction | After data binding and validation and just before performing any action. |
| AfterAction | After all actions have been performed but before page generation. |
| BeforeGenerate | Before any generation happens. It is triggered both when the page is requested for the first time and when a self-navigation is done. |
| AfterGenerate | When all generation has taken place. |
| RequestFinish | After all generation is complete. It is the last event to occur on the page. |
| ServerError | When the ReportError method is called. It can be used to alert you when something goes wrong during processing. |
psDocumentWrite HTML generation occurs after the BeforeGenerate event. Do
not place psDocument.Write in a script before
this event. The appearance of the resulting page would be unpredictable.
Events for page controls
4GL Web pages also provide events for the various types of
controls:
| For these controls | These events are available |
|---|---|
| SingleLineText | Validate, ValidationError, ItemChanged |
| TextArea | Validate, ValidationError, ItemChanged |
| RadioButton group | ItemChanged |
| ListBox | ItemChanged |
| PushButton | ServerAction |
| CheckBox | ItemChanged |
| StaticText | ServerAction |
| DataWindow | AfterAction, AfterRetrieve, AfterUpdate, BeforeAction, BeforeRetrieve, BeforeUpdate, OnDBError, Validate, ValidationError |
For a description of server-side events on Web DataWindows,
see the DataWindow Reference
. For a description
of the server-side events on other controls on 4GL pages, see the Web
and JSP Target Reference
.
In addition to viewing the events available for a control
from the events list in the integrated Script editor, you can expand
a control on the Page tab page of the System Tree to see a list
of events for that control.
To view a list of events available for a control:
-
On the Page tab page of the System Tree,
click the name of the control. -
Expand the item for the control, then expand its
Events folder.
Adding scripts to 4GL Web pages
The extensions
to the Web Target object model give you other ways to customize
a page by writing scripts to access:
- Properties
and methods for the psPage object - Methods for objects that represent controls
Properties and methods of the psPage object
The psPage object represents an entire 4GL Web page. You can
add properties as well as methods for the psPage object to your
page by dragging them from the System Tree, dropping them into the
appropriate place in the Script editor (or in Source view of the
HTML editor), then defining arguments.
For a list and description of psPage properties and methods,
see the Web and JSP Target Reference
.
All psPage methods (except Redirect) help
fine-tune error reporting for your page. The psPage Alert method
lets you display a client-side Alert box to make sure that users
of your Web application see important messages. If you use the Alert method
to inform users about validation errors, it lets them correct entries that
are not in the correct syntax.
Here is how you can use the Alert method
in a script in response to a ValidationError event:
Adding scripts for properties
of controls
Objects for controls also have associated properties that
you can access in server-side scripts:
| Property | Description |
|---|---|
| name | The name of the control. This is a read-only property. |
| value | The label for the control. |
| visible | Sets whether or not the client control is generated. If not visible, there is no access to the client control. |
| enabled | Sets whether or not the control allows focus. (This property works only in browsers that support the DISABLED attribute.) |
Typically you set values for object properties on the property
pages for the control rather than in server scripts.
Using the psPage prefix
When referring to read-write variables in script for client-side
events, it is best to include the psPage prefix before the variable
name. Otherwise, client-modified values might not be passed
on to a target page–initial values are passed if the prefix
is not included in the script. Page parameters cannot be accessed
in client-side script. You can optionally use the psPage prefix
for the names of controls on the page.
Example 1: Client-side code This script in a client-side onchange event will set the v1
read-write
variable to a value the client enters in the sle_1 text
box (an alert message should not be prefixed with psPage on the
client side):
|
1 |
alert("This is the client-side onchange event");<br /> psPage.v1=psPage.sle_1.value; |
Example 2: Server-side code This same script in a server-side event (such as ItemChanged
or ServerAction) should omit the references to psPage, except for
code that calls methods on the server page object:
|
1 |
psPage.Alert("This is a server-side event");<br /> v1=sle_1.value; |
For more information on scripting, see Chapter 6, “Writing Scripts “ and Chapter 7, “Working with Application
Servers and Transaction Servers”.
Writing scripts to access EAServer components
4GL
Web pages provide ready access to EAServer components from server scripts.
You can drag and drop a method for an EAServer component into
a script or access a variable for an EAServer component.
Adding EAServer methods to server scripts
You can drag any component method
visible in the System Tree to a server script.
The following illustration shows the result of dragging the getInfo method
of the Artist component to the integrated Script editor in the script
for the BeforeGenerate server-side event. The method is called when
the BeforeGenerate event is triggered for the page.
If you drag and drop a method that requires arguments, you
simply type the arguments in the Script editor.
For how to set up access to an EAServer server to view components
and component methods installed on a server, see “Working with EAServer components “.
Manipulating variables that represent EAServer components
Scripts can also
access EAServer components represented as variables on your page.
Whenever you drag an EAServer component from the System Tree and drop
it on your page, the component is available as a variable. The variable name
is the same as the component name unless you change it.
To view the EAServer variables for your page:
-
Right-click in a 4GL Web page open in the
HTML editor, then select Page Properties from the pop-up menu. -
In the Page Properties dialog box, click the EAServer
tab.On the EAServer page, you see the list of EAServer components
and the associated variables.