- The Book of Dojo
- Quick Installation
- Hello World
- Debugging Tutorial
- Introduction
- Part 1: Life With Dojo
- Part 2: Dijit
- Part 3: JavaScript With Dojo and Dijit
- Part 4: Testing, Tuning and Debugging
- Part 5: DojoX
- The Dojo Book, 0.4
Formatting and Validation
Submitted by smoverton on Wed, 09/26/2007 - 20:24.
Dojo has the capability of formatting messages like what Java does. Message formatting functions are very important to the translatability of an application -- separating code and translatable materials and supporting application translation without any modification to the code. Furthermore, Dojo provides full functions for data formatting and validation based on Unicode CLDR data, just like what ICU library does. You can easily format your output and validate users' input in Dojo without invoking code at the server side.
- You must use dojo.string.substitute() to generate text output rather than simply use "+" between strings.
- You must use Dojo format functions to convert locale sensitive data into text.
- You must use Dojo validating and parsing functions to convert text from the users' input into data.
- You should not hard-code patterns and locales when formatting data.
You can use dojo.string.substitute() to substitute place holders in the message string. This function provides a function similar to the java.text.MessageFormat.format() function in Java. You must use this function to get your text output instead of simply using the "+" operator; otherwise your application loses its translatability. For example, an English message "File 'foo.txt' is not found in directory '/root/bar'." can be translated as "?'/root/bar'??????'foo.txt'???" in Chinese. If you write your code like msg = pieceA + fileName + pieceB + dirName + pieceC, you cannot translate this message into Chinese without modifying your code, because the positions of fileName and dirName are swapped. Therefore, the right approach is to write the code like this:
dojo.requireLocalization("my.app", "message");
var message = dojo.i18n.getLocalization("my.app", "message");
msg = dojo.string.substitute(message.FILE_NOT_FOUND_IN_DIR, ["foo.txt", "/root/bar"]);
var message = dojo.i18n.getLocalization("my.app", "message");
msg = dojo.string.substitute(message.FILE_NOT_FOUND_IN_DIR, ["foo.txt", "/root/bar"]);
And the resource bundle "message.js" is like this:
{
FILE_NOT_FOUND_IN_DIR: "File '${0}' is not found in directory '${1}'."
}
Now you can translate the message into Chinese by only providing a translated resource bundle in the locale "zh-cn":
FILE_NOT_FOUND_IN_DIR: "File '${0}' is not found in directory '${1}'."
}
{
FILE_NOT_FOUND_IN_DIR: "?'${1}'??????'${0}'???" FIXME!
}
Here are more examples of using dojo.string.substitute():
FILE_NOT_FOUND_IN_DIR: "?'${1}'??????'${0}'???" FIXME!
}
dojo.require('dojo.string');
dojo.require('dojo.number');
// Use format function.
// "dojo.number.format" is a format function defined by Dojo.
// It uses the default locale in Dojo, as defined by the user's environment
console.debug(dojo.string.substitute(
"The number of '${1}' is '${0:dojo.number.format}'.",["saved files", "123456"]));
// Output: The number of saved files is 123,456.
// Use named substitutions.
console.debug(dojo.string.substitute(
"The number of '${item}' is '${number:dojo.number.format}'.",
{item: "saved files", number: 123456}));
// Output: The number of saved files is 123,456.
dojo.require('dojo.number');
// Use format function.
// "dojo.number.format" is a format function defined by Dojo.
// It uses the default locale in Dojo, as defined by the user's environment
console.debug(dojo.string.substitute(
"The number of '${1}' is '${0:dojo.number.format}'.",["saved files", "123456"]));
// Output: The number of saved files is 123,456.
// Use named substitutions.
console.debug(dojo.string.substitute(
"The number of '${item}' is '${number:dojo.number.format}'.",
{item: "saved files", number: 123456}));
// Output: The number of saved files is 123,456.
Cultural Formatting and Validation
You must use Dojo format functions to convert locale sensitive data into text
Dojo utilizes the Unicode CLDR data to format and validate locale sensitive information, such as time, number, and currency. The built-in conversion functions in JavaScript like Date.toString() are not fully Unicode- compatible, and you should not use them in a globalized Web application. For dates and numbers, Dojo format functions are not needed to be called explicitly in your code, and the dojo.string.substitute() function mentioned above can combine the format capabilities with format functions. You only need to specify the format function name in the template string, for example:dojo.require('dojo.string');
dojo.require('dojo.number');
dojo.require('dojo.date.locale');
var msg = "Number of processed file number before ${1:dojo.date.locale.format}:"
+ "${0:dojo.number.format}";
console.debug(dojo.string.substitute(msg, [123456, new Date()]);
If you want more control over the output format and locale, you can use the specific format functions respectively. For details, refer to the API documents of the following functions:
dojo.require('dojo.number');
dojo.require('dojo.date.locale');
var msg = "Number of processed file number before ${1:dojo.date.locale.format}:"
+ "${0:dojo.number.format}";
console.debug(dojo.string.substitute(msg, [123456, new Date()]);
- dojo.number.format
- dojo.date.locale.format
You must use Dojo validating and parsing functions to convert text from the users' input into data
Although JavaScript provides some methods to convert text to data, it does not fully support localized text, for example, view plaincopy to clipboardprint?console.debug(new Number("123456"); // output: 123456
console.debug(new Number("123,456"); // output: NaN
You must use Dojo's functions to handle validation and parsing. For details, refer to the API documents of the following functions:
console.debug(new Number("123,456"); // output: NaN
- dojo.number.regexp
- dojo.number.parse
- dojo.date.locale.regexp
- dojo.date.locale.parse
You should not hard-code patterns and locales when formatting data
Usually, you only need to set the selector and the formatLength properties for date (type for number and currency for currency), and use the default values of other properties when calling formatting, validating, or parsing functions. Dojo looks for the correct pattern based on the current default locale. If you specify the pattern by hard coding, the output format cannot be changed with the user's locale.
Generating files for cultural support in other locales
Dojo uses the Unicode Common Locale Data Repository (CLDR) to format and parse locale-specific data. A subset of the locales supported by the CLDR is transformed to JavaScript and checked into the dojo.cldr package as resource bundles. Although only a handful of locales ship in dojo.cldr, any or all of the hundreds of locales supported by the CLDR may be generated easily by invoking a script. Dojo provides an Ant task to perform the transformation from LDML, an XML-based markup, to JSON files. The entire CLDR source is available with these tools in the util/buildscripts/cldr directory. To invoke this script, you need to check out the current Dojo source code or download the buildscripts archive file and overlay it with your Dojo build, and consult the README file in util/buildscripts/cldr for details. It is as simple as invoking 'ant' in that directory. After the script is executed, all transformed JSON files are added to the "dojo/cldr/nls" directory.
- Printer-friendly version
- Login or register to post comments
- Subscribe post
Unicode got munged?
"?'/root/bar'??????'foo.txt'???"
plaincopy/clipboardprint
needs some more cleanup. these are artifacts from some older CMS, I think.