Messages Programming

Sending a message from an API based language script (Javascript) 1

What are messages?

A message is a text which can be sent to the user using a script statement when certain conditions arise. The characteristics of messages are:

They are issued under program control i.e. they are only displayed when the appropriate script statement is executed
They are automatically removed once the user has seen them
They can be multi-lingual i.e. the appropriate language text is selected at runtime based on the language
Issuing a message can optionally cause the system to stop processing the current event and return to the user immediately with the message
They can contain any number of variables to be substituted dynamically at runtime with the values of one or more form fields or table columns
They can be styled depending on the context of the message e.g. error messages might be in red

There are four types of message:

· Error messages – typically these inform the user about an error that must be corrected

· Warning messages – typically these inform the user that something might be wrong – the user has the option of continuing

· Info messages – typically informs the user of a successful action

· Final page messages – these are a legacy feature - a special type of message that is displayed on the optional Ebase final page

Sending a message from an API based language script (Javascript)

Error, warning and info messages can be issued at form, page or control level by invoking one of the addXxxMessage() or addXxxMessageText() methods shown below. (These methods are included in the MessageContainer interface which is implemented by form, page and all controls.)

These methods provide the option to stop processing, which stops all script execution immediately and re-displays the current page to the user so the message can be acted on. Alternatively processing can continue and this makes it possible to generate and display multiple messages in a single pass; when this option is selected, the script may subsequently need to use the EventContext.stopExecution() method to stop script processing after all messages have been issued (see example below). Unless otherwise specified, error messages have a default that processing should stop immediately, whereas warning and info messages default to continue processing.

The available methods are:

// Add an error message string

addErrorMessage(String message);

addErrorMessage(String message, boolean stopProcessing);

// Add a pre-configured error message text – supports variable substitution in the text and multi-lingual texts

addErrorMessageText(Text text);

addErrorMessageText(Text text, String[] replaceParameters);

addErrorMessageText (Text text, String[] replaceParameters, boolean stopProcessing);

// Add a warning message string

addWarningMessage(String message);

addWarningMessage(String message, boolean stopProcessing);

// Add a pre-configured warning message text – supports variable substitution in the text and multi-lingual texts

addWarningMessage(Text text);

addWarningMessage(Text text, String[] replaceParameters);

addWarningMessage(Text text, String[] replaceParameters, boolean stopProcessing);

// Add an info message string

addInfoMessage(String message);

addInfoMessage(String message, boolean stopProcessing);

// Add a pre-configured info message text – supports variable substitution in the text and multi-lingual texts

addInfoMessage(Text text);

addInfoMessage(Text text, String[] replaceParameters);

addInfoMessage(Text text, String[] replaceParameters, boolean stopProcessing);

Many of these methods accept a Text object as a parameter. All the available Text objects within a form or component are accessible via the texts variable and the code-assist feature within the Javascript editor can be used to present a list of available texts (see examples below).

The methods that support a Text object parameter give the ability to substitute variables into the message text. For example, if text Msg25 contains text:

"You cannot order && with &&"

and a script contains statement:

addErrorMessageText(texts.Msg25, [fields.EXTRA_ORDER_ITEM1.value, fields.MAIN_ORDER_ITEM.value]);

then the user will get a message something like :

"You cannot order ketchup with caviar"

Messages can be added to an individual control or page by invoking a method on that specific Control or Page object. But it’s often more convenient to add the message to the Control or Page that owns the current event – for example a button click event is owned by a Button Control etc. This is achieved like this:

event.owner.addErrorMessage("something has gone wrong");

Examples:

// simple error message

event.owner.addErrorMessage("Please supply a reference code");

// simple info message

event.owner.addErrorMessage("Profile updated successfully");

// numbered message with substitution

// might be displayed as… “Order type CREDIT is invalid for customer type PUBLIC”

event.owner.addErrorMessageText(texts.Msg100, [fields.ORDER_TYPE.value, fields.CUSTOMER_TYPE.value]);

// multiple messages added to an explicit control – need to stop processing when done

controls.FIELDCONTROL1.addErrorMessage("First error message", false);

controls.FIELDCONTROL1.addErrorMessage("Second error message", false);

controls.FIELDCONTROL1.addWarningMessage("First warning message", false);

event.stopExecution()

Sending a message from an FPL script

The script command to send a message is either:

message type, textid [,parm1, parm2, parm3 ......] (this is a standard format message)

or simply...

message 'text' (this is a simple format message)

The type can be set as:

E error message

W warning message

I info message

F information message to be displayed on the final page

Each message is attached to the owning form element e.g. messages issued from control events are attached to the control etc. The message is displayed when the page is next displayed.

· error messages cause event processing to stop immediately, and a re-display of the page to the user with the error message. The user must correct the error to proceed. Error messages cannot be issued from form level events.

· warning messages do not cause form processing to stop but will stop the user from paging forwards using a Next Page Button – the intention being that the message must be seen by the user. Warning messages cannot be issued from form level events.

· info messages do not cause form processing to stop. Info messages cannot be issued from form level events.

· final page messages will be displayed on the Ebase final page that is displayed after form processing has completed. They normally contain information about what the form has done and feedback information on numbers of records created, e.g. order numbers, etc. Final page messages can be issued at any time during form processing and are accumulated for display on the form's final page.

The simple syntax is a shortcut for issuing an error message. This syntax does not provide support for multiple languages, substitution of form field variables into the message, or warning or final messages.

All three types of message allow form field values to be substituted into the message text. For example, if text Msg25 contains:

"You cannot order && with &&"

and field EXTRA_ORDER_ITEM1 has value ketchup and field MAIN_ORDER_ITEM has value caviar

and a script contains command :

message E, Msg25, EXTRA_ORDER_ITEM1, MAIN_ORDER_ITEM;

then the user will get a message saying :

"You cannot order ketchup with caviar"

Positioning of messages

The position of a message depends on the settings in the Message control properties for the control to which the message is attached; for page messages (issued from page-level events) this is the root Page Control. There are basically two options:

If the Use Message Control option is used, then the message is attached to the specified Message Control and the messages will be displayed at its location on the page. Use this option if you want to display multiple messages in a single location. You can also route messages for all child controls within a container (e.g. a Panel Control or a Page Control) to a single Message Control – to do this configure the Message control properties of the container to use the desired Message Control, then configure all child controls to Use parent control setting (this is the default).
If the Local Message option is used, then the message is shown at the location of the control to which it is attached. The exact position depends on the layout used, but in most circumstances a message is shown before the control to which it applies.

Styling messages

· Control messages (issued from control-level events) are attached to the owning control.

· Page messages (issued from page-level events) are attached to the Page Control – this is the root control for each page.

· Form messages are treated the same as page messages on the current page and are attached to the Page Control for that page.

Messages can be displayed either locally to the owning control or at another location on the same page represented by a Message Control. This choice is configured in the Message options property for each control – click here for further details. Local messaging means that the message will be displayed adjacent to (usually above) the control to which it relates. Message Controls provide the ability to display all messages for a page in a single area, or to group messages for logical areas of a page.

Messages are styled for local messages by configuring Message control properties, and for Message Controls by configuring properties of the Message Control.

A page is scrolled automatically to ensure that error, warning and info messages are visible to the user.