Working with Messages

Sending a message from an API based language script 2

What are messages?

A message is a language dependent text which can be sent to the user programmatically when certain conditions arise. Once the message has been displayed to the user, it is removed automatically.

There are three types of message:

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

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

· Final page messages – a special category of message: these messages are displayed on the optional Ebase final page that is displayed after form processing has completed

Sending a message from an FPL script

The script command to send a message is either :

message type, messagenumber [,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

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 – the intention being that the user must see the message. Warning 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 message 1234 contains text :

"You cannot order && with &&"

and a script contains command :

message E, 1234, EXTRA_ORDER_ITEM1, MAIN_ORDER_ITEM;

then the user may get a message saying :

"You cannot order ketchup with caviar"

Sending a message from an API based language script

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

These addXXXMessage() methods provide the option of stopping processing immediately – this 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 need to use the EventContext.stopExecution() method (see example below) to stop script processing after all messages have been issued. Unless otherwise specified, error messages have a default that processing should stop immediately, whereas warning 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 using its message number – allows for variable substitution in the message text

addErrorMessage(int messageNo, String[] replaceParameters);

addErrorMessage(int messageNo);

addErrorMessage(int messageNo, String[] replaceParameters, boolean stopProcessing);

// Add a warning message string

addWarningMessage(String message);

addWarningMessage(String message, boolean stopProcessing);

// Add a pre-configured warning message using its message number – allows for variable substitution in the message text

addWarningMessage(int messageNo);

addWarningMessage(int messageNo, String[] replaceParameters);

addWarningMessage(int messageNo, String[] replaceParameters, boolean stopProcessing);

The methods above that support a message number (messageNo) give the ability to substitute variables into the message text. For example, if message 1234 contains text :

"You cannot order && with &&"

and a script contains:

addErrorMessage(1234, [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 specifically to an individual control or page by invoking a method on that specific Control or Page object. But it’s usually 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");

// numbered message with substitution

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

event.owner.addErrorMessage(1006, [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()

Presentation of 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 and warning messages are visible to the user.

Global Messages

Global messages created in the GLOBAL project are accessible by all forms. They are referenced in exactly the same way as for any other message (as described above) except that they begin their numbering from 100,000 as opposed to 1,000 for messages in all other projects.

Global messages are also used with components (See Working with Components for more information).

Working with messages

Messages are created and maintained using the message editor. Numbering of messages is performed automatically by the system and each project will have its own set of messages. A message can only be issued by a script within the same project. The message editor is opened by clicking once on Messages under the project name in the hierarchy tree panel.

In the language selection you can select all the languages which you wish to maintain (hold the CTRL key to select multiple languages). Then click the Refresh button.

Messages can be added or deleted using the toolbar or by right-clicking in the messages table area.

The message text can contain any text that you require. You can expand the text entry area by right-clicking over it or by double-clicking in the number or language columns for the appropriate row of the table. To substitute a form field dynamically at runtime into the message text, enter && into the message text. You can have up to 10 such substitutable parameters within each message. See the message FPL script command above for an example of how to specify the form fields to be used for the substitution.

To save the messages, click the Save icon on the toolbar.