Iron Speed Designer Help - Customizing Error and Validation Message Strings

Customizing Error and Validation Message Strings

Applications built with Iron Speed Designer contain a variety of data validation, information, and error messages that are automatically included in your application. The error message and validation message strings displayed by your application are contained in:

The base class library.
( ...\<Iron Speed Designer>\BaseClasses\Bin\ )
The application resource library.
( ...\<Iron Speed Designer>\ProjectTemplates\Resources\ )

These libraries contain translation resources for a number of cultures and languages. In addition you may change these messages to conform to the language and format of your choice. They are physically contained in two separate resource files (RESX), which are copied to your application. The files that are copied are considered part of your application and should be included when you move your application into production. Messages are retrieved from the files by your application at run-time. The files are:

BaseClasses.<UI Culture>.resx. These system messages are primarily used for non-application specific messages in applications. Examples include bad input data format and concurrency handling messages.
ProjectTemplate.<UI Culture>.resx. These application messages are used by your application for displaying data validation errors and for other application-level uses.

<UI Culture> is the valid ISO culture name, e.g.:

MyApp1.en-US.resx

MyApp1.de-DE.resx

MyApp1.it-IT.resx

BaseClasses.<UI Culture>.resx

When you create an application or select a new culture, Iron Speed Designer selects a file from the base class library and places it into your application’s project folder:

...\<App Name>\bin\BaseClasses.<Culture>.resx

The actual file names depend on your application’s chosen locales, e.g.:

...\<App Name>\bin\BaseClasses.es-PA.resx

...\<App Name>\bin\BaseClasses.en-US.resx

You can edit these text strings directly. We recommend using the Visual Studio XML editor. (Note: You should never modify files in the Base Classes library (folders) directly, since these files are automatically upgraded by Iron Speed Designer when installing new versions.)

ProjectTemplate.<UI Culture>.resx

When you create an application or select a new culture, Iron Speed Designer selects a file from the application resource library and places it into your application’s project folder:

...\<App Name>\bin\<App Name>.<UI Culture>.resx

The actual file names depend on your application’s chosen locales, e.g.:

...\<App Name>\bin\<App Name>.es-PA.resx

...\<App Name>\bin\<App Name>.en-US.resx

You can edit these text strings directly. We recommend using the Visual Studio XML editor. (Note: You should never modify files in the application resource library (folders) directly, since these files are automatically upgraded by Iron Speed Designer when installing new versions.)

Resource files at run-time

In some cases, your resource file or specific resource strings in the resource file may not be used at application run-time. When the .NET Framework is unable to locate your resource files or a particular resource string within a resource file, it uses the resource name by default because it does not have any other information. This can occur for a variety of reasons, including:

The application is not configured for the proper language. If there is a mismatch between the culture setting in your application’s pages and the resource file you want to use, then the resource file will be ignored.
The application resource file is not contained in the Bin directory of the application. You may also need to copy the resource file into the application’s Bin directory or let Iron Speed Designer copy it to the Bin directory during Build time.

Example: Internationalize table column headings (field names)

Step 1: Use the Application Wizard to add multiple languages for your application. This creates a resource file (RESX) for each selected language in your application’s App_GlobalResources folder, e.g.:

AcmeOMS.de.resx

AcmeOMS.en-US.resx

AcmeOMS.fr.resx

AcmeOMS.it.resx

AcmeOMS.resx

Step 2: In your application’s App_GlobalResources folder, open each resource file and add resource entries for the column headings, e.g.:

Resource Key	Value
Txt:Customer	Customer
Txt:OrderID	Order Number

The Resource Keys should be the same, regardless of language. However, the string values should be language specific.

Step 3: In Iron Speed Designer, open the page that will use these column heading strings. Then navigate to the table panel containing the column headings.

Step 4: In the Layout Editor, select the label control you wish to have a language-specific text string.

Step 5: In the Property Sheet, change the Text property to use the resource key you entered in your application’s resource files.

Group	Property	Value
Appearance	Text	{Txt:Customer}

Be sure to enclose the resource key in curly braces. This instructs Iron Speed Designer to emit code that retrieves the string from the resource file.

Step 6: Build and run your application.

Step 7: In your application, select the appropriate language from the Upper Tool Bar and your page will update to display the correct language-specific labels.

Resource File Format

Resource files are straightforward XML files that follow a format defined by Microsoft and used by Iron Speed Designer and by your applications. An example ProjectTemplate.resx file is shown below.

<?xml version="1.0" encoding="utf-8"?>

<root>

</data>

<value>{FieldName} value is required.</value>

</data>

<value>The {FieldName} value you entered is invalid. It may be invalid for a number of reasons. You may have entered a value that is longer than what is allowed, the value may contain invalid characters or the value might be out of range of allowed values. Please review the value and correct it and submit the changes again.</value>

</data>

<value>Value for {FieldName} is too long</value>

</data>

Each entry in the resource file has a Name and a Value. The Name is the name of the string resource, called a Resource Key. The value is the localized string to be used in your application.

Some validation messages, such as “field value” validation messages, are parameterized by name. You can localize (translate) the message text. However, do not translate or change the substitution parameters, e.g., {FieldName}, because your application uses these substitution parameters at run-time.

Resource keys have prefixes, called Resource Key Prefixes: "Txt" (for Text), "Val" (for Validation Message), and "Btn" (for Button). Their primary purpose is to distinguish keys from values when viewing and editing the string resource files.

Resource Key Prefix	Use
Btn	Button text.
Err	Error messages.
Txt	Dialog box titles and other general purpose text strings.
Val	Validation error messages.

The following caveats apply:

Resource Keys are case sensitive. For example, Btn:Edit is acceptable but Btn:edit will not work.
Resource Key Prefixes are case sensitive. For example, Btn:Edit is acceptable but btn:Edit will not work.
Parameter names are case insensitive. For example, {TableName} and {TABLENAME} both will work.

Editing Resource Files

You should only edit the resource’s value and leave the resource’s name alone. There is no need to add or remove rows from the resource file.

You should refrain from adding your own new string resources to the resource files provided or created by Iron Speed Designer. Iron Speed Designer applications do not provide a mechanism for retrieving these strings from the resource file, either at application generation time or at application run-time.

Resource files should be saved in UTF-8 format, so be sure to use an editor that supports saving in this format. This ensures that the character set you use will be manifested in the resulting text strings. Your particular text editor may default to an encoding format other than UTF-8 (e.g., BIG5), which is frequently the case for Asian-language editors. In this case, you may need to explicitly save your resource file in UTF-8. While the UTF-8 format can result in larger-sized resource files than other encoding formats, UTF-8 is the most popular encoding format for web applications and most applications support this format.

Resource Files and the Property Sheet

Some strings in the resource files can be edited directly in the page’s Property Sheet. If you change the text for a field in the Property Sheet, this text is saved in the properties file for the particular page. At this point, Iron Speed Designer will no longer look to the resource file for that field’s string. Instead, that field’s string will be taken from the page’s properties file, giving the properties file precedence over the string resource file.

Language Translation Reminder

When an application specifies a country, or uses a language not listed above, Iron Speed Designer makes a copy of the closest culture / language (English is the default). It remembers the original language and displays a reminder to translate the file if necessary.

After translating the file, including making minor adjustments to their specific country's dialect, set the "Language" property at the top of the file to the language indicated in the file name. For instance, after adjusting a Spanish translation for the Costa Rican variant, change “es-ES” to “es-CR” to match the file extension. You may also change the Translator fields to show the proper values.

Here is what the XML at the top of the .RESX file looks like before the change:

</data>

<value>Frank Jones</value>

</data>

<value>Your Company, Inc.</value>

</data>

Upgrading Iron Speed Designer

Please be aware that installing future versions of Iron Speed Designer may overwrite the application base class library with a more current version. Thus, you should make a copy of any modified source code files so you can re-apply the changes made to any new version you may install.