Monday, 3 May 2010

Variable Substitution and getMsg

Gadgets use messages, stored in messagebundles, for internationalization. The most common way to access the messages your gadget has is with variable substitution. For example, a message called north can be specified as

<msg name="north">Nord</msg>

and accessed by using __MSG_north__ your code. The copious underscores lead to the affectionate term “hangman variables” for this substitution notation. Before your code runs, the exact text __MSG_north__ is replaced everywhere with the appropriate value from the messagebundle. In this example it will be “Nord” (French for North, no quotes). This happens in the appropriate places in the XML of your gadget spec as well. So your enum values can be replaced before the controls are made that will show them and everything works as expected. But suppose you have some text in your code that uses a message, something like

dirbox.innerHTML = '__MSG_north__';

This will work fine as well because the substitution happens before the code runs. Now let’s take another message

<msg name="dinername">Chez Sophie</msg>
And some similar Javascript

dinersign.innerHTML = '__MSG_dinername__';

Everything works fine until we add the English translation

<msg name="dinername">Sophie's Place</msg>

And the code the gadget tries to run is

dinersign.innerHTML = 'Sophie's Place';

where of course the string ends early and the browser will correctly emit some odd error on seeing the first s after the apostrophe. This could be cited as an unterminated string literal, a missing semicolon or an illegal character (if you get a different character for your apostrophe).

The gadgets.Prefs.getMsg() function will correctly read the dinername as the string which it’s meant to be.

var init = function () {
var prefs = new gadgets.Prefs();
dinersign = document.getElementById("dinersign");
dinersign.innerHTML = prefs.getMsg("dinername");


The getMsg function should help make more reliable, robust gadgets in many cases and it might help resolve some of those errors your users get using languages translations that you don’t use so often.