Resources

The Resources layer enables you to maintain common framework capabilities such as localization, translation, and common code libraries.

Internationalization and localization

NexJ CRM provides the following capabilities:

• Support for English
• Built to work with Unicode
• Specific formatting is supported for dates, currency, and numbers
• Multi-language support is built into the business model for code values
• Selectable at runtime

.string and .locale files are not part of the Model Description Language. They are lists of key and value pairs, and are considered to be properties files or property resources.

String resources

Strings are used for captions, messages, and other elements and properties that switch their display text depending on the current user's language preference. 

Configuring supported client locales

To configure supported client regional locales, you must modify the corresponding *.locale file by adding the ids.format.regionalLocale property (if it does not already exist). The locale files can be found in the Resources > Locales tab in NexJ Studio. They can also be found in the meta/locales directory in the project folder (for example, finance/meta/locales).

The value for this property should be a valid combination of a language code and a region code separated by a hyphen, for example, en-CA (Canadian English).

It is important to note the format and capitalization for the value of this property. The full property and value added to a *.locale file should look similar to: 
ids.format.regionalLocale=en-CA

Each *.locale file can have its own value for this property. For example, the property mentioned above can be added to the en.locale file, and the following property can be added to the fr.locale file:
ids.format.regionalLocale=fr-CA

By adding this property to the *.locale files, the values attached to them build the supported client locales accepted by the application.

Setting locale

You can change locale via URL or via browser language.

To change locale via URL, you must add a l parameter to the URL and the value specified should be an exact match for the value of the ids.format.regionalLocale property in the *.locale file. For example, http://www.nexj.com/nexj/ui/portal?l=en-CA

To change the locale to match the browser, use the browser settings to change the browser language.

Configuring a project default locale

A project default locale can be configured and used if the incoming locale, either entered as the URL or the current user’s browser locale, is not supported by the application. To set a desired project default locale, modify the FALLBACK_LOCALE attribute in the User class (User.meta).

Locale selection precedence

Because there are multiple different ways to set locale, which can have varying values, for example, URL, browser, project default, and so on, there is a priority system in place to determine which value has precedence.

The priority, from highest to lowest, is:

• URL
• User model (locale attribute in User.meta)
• Browser locale
• Project default
• en-CA

A locale specified in the URL has the highest priority. As long as the locale value in the URL is supported, that client locale is used.

If there is no locale set in the URL, the user locale value is checked. If supported, the user locale value is used. Otherwise, the browser locale is checked. If the browser locale is supported, it is used. If the browser locale is not supported, the project default locale is used.

If the project default locale that has been configured is not a valid supported client regional locale (by misconfiguration, for example), the application defaults to en-CA.

Using a flag to determine User model precedence

You can use the ignoreUserLocale flag from the framework to determine when the User#locale value should take precedence or not. 

When the value for the flag is false, which is the default value, the User#locale is used. If the value is true, the User model value may not match the locale value that was set in the URL, and the client locale should be used instead. In this case, the returned value is the existing clientLocale value, as tracked by the framework.

The following example shows the usage of the flag in finance. It is taken from the locale attribute for User.meta in finance. The methods, which get and set the ignoreUserLocale flag, exist for the nexj.core.runtime.InvocationContext class, and therefore a nexj.core.runtime.InvocationContext instance is needed to call these methods.

(cond
   //If the flag is TRUE (locale set from URL), then we can’t use the User model value, therefore, use the client locale value tracked by the framework (InvocationContext#getClientLocale).
   (((invocation-context)'ignoreUserLocale) ((invocation-context)'clientLocale))
   //ELSE the flag is FALSE (locale not set in URL), continue to User model logic
   (else
      … 
   //Retrieve user model locale/validate/use fallback/etc.

Model Description Language elements

• Strings - Not actually part of the XML language. They are simple string files.
• Locale - Not actually part of the XML language. Standard string file with a pre-defined set of strings to control currency, date, time, ...
• Libraries - Not actually part of the XML language. Global script files in Scheme (.scm) or JavaScript (.njs).
• ExternalLibrary - External Libraries reference jar files located in the project's /lib folder.
  
• Action - Custom Actions used to extend the Workflow or Service palette.
• Scratchpad - Not actually part of the XML language. Script files for development and testing from the /etc/scratchpads folder.
• Component - Custom component to enhance server behaviors.
• Web - Not actually part of the XML language. Static web content wrapped up in the model and available at <serverRoot>/ (Note: Content needs to be white listed).