Creating messages
To create messages, begin by opening the NLS Workspace - Indexed Messages window. Select NLS > Maintenance > Workspace: Indexed Messages from the Tools menu of the Transcript.
The Workspace contains sample scripts for defining a message group, creating messages, and deleting messages.
Declaring a message group
Before you can define messages, you must declare a message group for your application. The first sample script in the Workspace provides the code for declaring a message group:
"Declaring a message group for your application."
MyApp abtNlmDeclareGroupInfo: 'MyGroup'
messageAnnotationFormat: 'product.component.%n.%e'
helpFilename: 'MyHelp'
helpPrefix: nil.
To declare a message group for an application such as AddressApplication, you might Display or Execute the following:
"Declaring a message group for your application."
AddressApplication abtNlmDeclareGroupInfo: 'AddressMsgs'
messageAnnotationFormat: 'add.view.%n.%e'
helpFilename: 'address'
helpPrefix: 'add'.
Evaluating this script adds the private class method _PRAGMA_AddressMsgs to AddressApplication. If the method already exists, it is simply updated. You must never change this method directly. The parameters for this method are as follows:
abtNlmDeclareGroupInfo:
Specifies the name of the Smalltalk pool dictionary that will hold your message identifiers and message strings. For example, specifying 'AddressMsgs' for the value creates a pool dictionary called AddressMsgs.
To display a message, you must complete the steps in
Displaying messages to add the pool dictionary to the class definition for your application and then use the pool dictionary name in scripts to display the message in a message box.
messageAnnotationFormat:
Specifies a prefix that identifies a group of messages within your product or application. It can contain placeholders: %n for the message ID number and %e for the message type.
For AddressApplication, you might specify 'add.view.%n.%e'.
helpFilename:
Specifies the name of your help file. For example, for AddressApplication, specify address.
If helpFilename: is set to nil, then message help cannot be associated with any of the messages in the application. The help button will not appear on the dialogs used to display the messages.
helpPrefix:
Specifies a help prefix. This parameter determines how your application looks up help for messages. If a value of nil is given, the message number is used as the key into the help file. For example, if the message number is 15, the help key is the integer 15.
If an integer is given, helpPrefix is treated as a base address. The message number plus the helpPrefix is used as the key into the help file. This is useful if you are using a single help file for more than one application and want to assign numeric ranges to the help messages for each application. (App1 uses 1...100, App2 uses 101...200, and so on). For example, if helpPrefix is 200 and the message number is 15, then the help key is the integer 215.
If the value is a string, the string followed by the message number is used as the key into the help file. For example, if helpPrefix is 'msghlp' and the message number is 15, the help key is the string 'msghlp15'.
For AddressApplication, you might specify the string 'add'.
Adding messages
After you declare a message group, you can add messages to your application. You can add a single message or you can add several messages at one time. The sample scripts for adding messages shown in the NLS Workspace - Indexed Messages window are as follows:
"Adding one message at a time."
MyApp abtNlmAddIndexedMessage: (
AbtNlsEditItem id: 1
constName: 'MyConstName'
type: $i
string: 'MyString'
translatable: true).
"Adding many messages at a time."
MyApp abtNlmAddAllIndexedMessages: (
OrderedCollection new
add:(AbtNlsEditItem id: 1
constName: 'MyConstName'
type: $i
string: 'MyString'
translatable: true) ;
add:(AbtNlsEditItem id: 2
constName: 'MySecondConstName'
type: $i
string: 'MySecondString'
translatable: true);
yourself).
To add error, warning, and question messages to AddressApplication, you might change the second script to the following:
"Adding many messages at a time."
AddressApplication abtNlmAddAllIndexedMessages: (
OrderedCollection new
add:(AbtNlsEditItem id: 1
constName: 'MsgNoName'
type: $e
string: 'Name is too long. Make it less than 40 characters.'
translatable: true);
add:(AbtNlsEditItem id: 2
constName: 'MsgZipCodeNotValid'
type: $w
string: 'Zip Code is not valid or does not exist.'
translatable: true);
add:(AbtNlsEditItem id: 3
constName: 'MsgSelect'
type: $q
string: 'You selected %1. Continue?'
translatable: true);
yourself).
Evaluating this script declares the three messages in the private class method _PRAGMA_AddressMsgs of AddressApplication and adds constants for the indices to the application's pool dictionary AddressMsgs. The message text is stored in the library.
The parameters in the above scripts set the following:
id:
Specifies a number for a message identifier.
constName:
Specifies a symbolic name for the message number. The name you specify represents the message in a pool dictionary. You will use this symbolic name to retrieve the message when you display it.
The name you specify must be alphanumeric and begin with an uppercase letter. The name cannot contain a double-byte character string (DBCS).
type:
Determines which icon is displayed in the message box for the message. Specify $e for error, $w for warning, $i for information, or $q for question.
string:
Specifies the message text. If you want to substitute values into the message text when you display the message, specify %n (such as %1 or %2) wherever you want the replacement text to go. These replacement tags can be 1...9 or a...z representing indices 1...35 in the parameter array.
translatable:
Specifies whether you want the message to be translatable. If you plan on translating the message text, specify true; otherwise, specify false.
National language support contains examples that show how to translate messages in
AddressApplication. If you are doing the example, keep the default value
true.
After you define a message group and messages, the _PRAGMA_AddressMsgs method in your application resembles the one shown below for AddressApplication:
_PRAGMA_AddressMsgs
"%%PRAGMA DECLARE
(name: AddressMsgs isPool: true isConstant: false)
(pool: AddressMsgs declarations: (
(name: MsgNoName isConstant: false comment: '1')
(name: MsgZipCodeNotValid isConstant: false comment: '2')
(name: MsgSelect isConstant: false comment: '3')
))"
Removing and changing messages
After you add messages to your application, you can later remove or change them using the scripts in the NLS Workspace - Indexed Messages window.
Removing one message
To remove a single message from AddressApplication, evaluate the code below. Specify the message ID for the message you want removed after the abtNlmRemoveIndex: parameter. To remove message 3, you evaluate:
"Removing a single indexed message"
AddressApplication abtNlmRemoveIndex: 3 ifAbsent: self halt].
Removing all messages
To remove all messages from AddressApplication, evaluate code such as the following:
"Removing all indexed messages"
AddressApplication abtNlmRemoveAllIndices.
Evaluating this code removes the script _PRAGMA_AddressGroup from the application.
Changing messages
To change a message, revise the script used to add messages and then evaluate the script again.