|
|
Introduction Implementing Parts
This page walks through the entities and function objects in the Message Store module.
The data model implemented with the Message Store pattern consists of 4 main entities and an abstract Language entity:
The 4 main entities are comprised by the Message Store pattern. The Language entity is abstract and should be replaced by an implemented Language entity.
The MessageType entity describes the different kinds of Messages used by the Websydian application. When applying the Message Store pattern, all standard CA Plex and Websydian system and application error messages have been defined in advance.
Each Message Type in the application corresponds to a Create Message function scoped under the MessageFunctions suite.
Message Type records are created by generating, building, and running the EditMessageTypes.UpdateMessageTypes function.
Fields:
| MessageFunctionSurrogate | Unique Message Type definition specifying the internal CA Plex surrogate number of the Create Message function corresponding to the Message Type record. |
| MessageFunctionModelName | The unscoped name of the corresponding Create Message function in the CA Plex model. |
| MessageTypeCategory | A Message can be either System Error,
Application Error, Alarm, Warning,
Informative, or Other. All the
pre-defined messages are System or Application Errors.
The category is specified by a option NME-triple. If no option-triple is defined, the Message Type will have the category-field set to Other. |
| DefaultTemplateText | The message text used when no Language Code is specified.
The default text will also be assigned to the
TemplateText field when generating new
Template records for a selected language.
The DefaultTemplateText field will by default be set to the large property of the DefaultTemplateText CA Plex message object scoped by the Create Message function. |
An instance of the Template entity describes the text of a specific Message Type for a specific Language. Template records are created by running the LoadMessageTemplates scoped under the TemplateMessageTranslation function which reads a file of translated Message Type records.
The Template entity is owned by the MessageType entity as well as an abstract Language which must be replaced by an implemented Language entity.
Fields:
| TemplateText | Message text translated to the specified language.
The Template text may contains substitutions markers (e.g. #1) which are replaced by the input parameters to the Create Message function. |
The Message entity contains the records created each time a Create Message function is called. In this way, the Message table will contain all messages generated by the application.
Fields:
| MessageSeq | Unique message ID. Will usually be set by applying inheritance from the FOUNDATION/Surrogate pattern. |
| MessageCreateDate | Set to the date of the message creation. |
| MessageCreateTime | Set to the time of the message creation. |
The MessageParameter entity specifies the parameter values received by a Create Message function. For each input field recieved in the MessageFields variable by a Create Message function, a MessageParameter record is created for the corresponding Message record.
When retrieving the message text (by the ReturnTextFromMessageStore function), the replacement markers in the message text are replaced with MessageParameter values.
Fields:
| MessageParameterSeq | Unique identifier of Message Parameter records within a Message record. The sequence field is increased by one for each parameter record created. |
| MessageParameterValue | Contains the alphanumeric value of the corresponding Message input field. |
| MessageParameterImplName | Implementation name for the parameter input field. The field is currently not being used by the Message Store pattern. |
| MessageParameterSurrogate | Internal CA Plex surrogate for parameter input field. The field is currently not being used by the Message Store pattern. |
The MessageFunction suite contains the Create Message functions corresponding to the different Message Types reported by the application.
A Create Message function (based on the abstract CreateMessage function pattern) is specified for each Message Type reported by the Websydian application. Create Message functions may be specified in two levels within the MessageFunction suite.
All standard CA Plex and Websydian system and application errors have been specified as System Message functions scoped under the SystemPlex and SystemWebsydian function suites respectively.
A Create Message function is scoped under the SystemPlex function suite for each type standard CA Plex error message generated by the web application (e.g. Function Call Failed).
Some of the CA Plex error Create Message functions are receiving Environment fields as input (e.g. *ReturnedStatus).
A Create Message function is scoped under the SystemWebsydian function suite for each type of Websydian error message generated by the web application. I.e. the Websydian error Create Message functions are reporting Websydian specific system or application errors (e.g. Unable to open Document Template).
None of the Websydian system message functions are receiving any input parameters .
The Abstract entity contains the CreateMessage and the ActivateMessageStore abstract function pattern described below.
An abstract Language entity is included in the MessageStore pattern. During implementation of a Message Store, this Language entity must be replaced by a Language entity already implemented in the application.
The Abstract.Langauge entity is known by a LanguageCode field which must also be replaced (by the key field of the implemented Language entity).
All Create Message functions (including the pre-defined CA Plex and Websydian system message functions) inherit from the CreateMessage function pattern. When a Create Message function is called, a record is created in the Message table.
The CreateMessage function receives a MessageSeq field as dual input. This field must be assigned a unique number by the implemented Create Message functions (typically implemented by inheritance from the FOUNDATION/Surrogate pattern).
The abstract CreateMessage function scopes a DefaultTemplateText CA Plex message object which is inherited to all the implemented Create Message functions in the application model. The default message text of the Create Message function is specified in the large property of the DefaultTemplateText message object.
Specify the default message text in the large property of DefaultTemplateText message object scoped under the Create Message function.
The Template text may contains substitution markers (e.g. #1) which are replaced by the input parameters to the Create Message function. If using Export and Import of translation files for message translation, the message text must not include line-shifts.
For each input field recieved in the MessageFields variable by a Create Message function, a MessageParameter record is created for the corresponding Message record, and when retrieving the message text again (by the ReturnTextFromMessageStore function), the replacement markers in the message text are replaced with the MessageParameter values.
Created Message functions do not always receive parameter input.
Inheritance from the ActivateMessageStore function pattern results in system errors to be saved and reported by the Message Store pattern. Typically, all Page Generator and Event Handler functions in a Websydian application will inherit from the abstract ActivateMessageStore function.
The ActivateMessageStore function also provides a Get and report message subroutine to be called for displaying application-specific messages. This subroutine is called just after the call of a Create Message function, and it uses the MessageStoreFields<MessageSeq> field to contain the identification of the Message record just created.
Finally, the ActivateMessageStore function defines a MessageStoreFields<LanguageCode> field in which the selected user language is stored.
The abstract Dispatcher function itself inherits from the ActivateMessageStore, and the Dispatcher function of the application must inherit from this abstract Dispatcher. In order to apply the Message Store Dispatcher function, the value of the MessageStoreFields<LanguageCode> field must be set. In addition, the Language Code must be assigned to a value in the CallFirstPageGenerator scoped under the Dispatcher.
A number of service functions are provided by the Message Store pattern.
The SaveSystemMessageInStore function is called from the Send message subroutine in case of system or application errors. Based on an incoming Environment<*Message ID> field, the SaveSystemMessageInStore function will create an instance of the matching system message. And, as output the function will return the expanded message text in the specified language.
The SaveSystemMessageInStore function will be called automatically in case of system errors when inheriting from the ActivateMessageStore function
Based on a MessageSeq and the LanguageCode fields, the ReturnTextFromMessageStore function will return the message text of the corresponding message record. Stored parameters for the created Message record are merged into the Message text template, and the resulting message text is returned by the function.
If ReturnTextFromMessageStore receives a blank LanguageCode, the DefaultTemplateText field of the associated MessageType record will be used as basis for the parameter substitution.
A call to the ReturnTextFromMessageStore function is included in the Get and report message subroutine inherited from the ActivateMessageStore function pattern.
This utility function reads the Language Code from or writes the Language Code to the global parameter store.
The EditMessageTypes function lists the MessageType records from the database. For a selected Message Type, the language Templates associated to the Message Type can be shown.
The Edit Message Type panel displays the Message Types used by the Websydian application.
The Edit Message Types panel includes a File Transfer push buttom to call the TemplateMessageTranslation panel and a Model Update buttom calling the UpdateMessageTypes process.
The Edit Templates panel lists the different language Template texts belonging to a Message Type.
Translation of message texts can be done directly from this panel, or it can be done by Import and Export of translation files as explained in the Implementation page.
The TemplateMessageTranslation function is called from the EditMessageTypes function, and it allows the user to trigger Export and Import of translation files.
Panel to Export (Dump) and Import (Load) translation files.
When Exporting or Importing a translation file, a language must be specified. During Export, existing Template files for the selected language will be read from the Template table (and from the DefaultTemplateText field in the MessageType table if a Template record does not exist). During Import, the language will determine the Template records to be created or updated.
The DumpMessageTemplates function scoped under TemplateMessageTranslation must be re-generated and built each time new Create Message functions are added to the Websydian development model.
The UpdateMessageTypes function is called from the EditMessageTypes function, and it updates the MessageType entity with new Create Message functions specified in the development model. If the Update Chg. check box is checked from the EditMessageTypes function, existing DefaultMessageText values will also be updated if changed.
The UpdateMessageTypes function must be re-generated and built each time new Create Message functions are added to the Websydian development model.
Online documentation - Websydian v6.5