Coding guidelines

Logging with Dojo

dojo supports five levels of console output: error, warn, info, debug, and log. We will align our client logging along those levels.

error/warn/info will always be written; debug and log are conditional.

We'll use a global object (defined in the index page) to manage debug and log:

var zlog =
{
  off   : Infinity,
  debug : 20,
  log   : 10,

  level : this.off,

  isDebug : function() { return (this.level <= this.debug); },
  isLog   : function() { return (this.level <= this.log);   }
}

Action: Guard your debug and log output as follows:

if (zlog.isDebug()) { console.debug("my debug message."); }
if (zlog.isLog()) { console.debug("my log message."); }

Settings to control the debug/log messages:

Setting	Debug messages appear?	Log messages appear?
Default	No	No
zlog.level = zlog.debug;	Yes	No
zlog.level = zlog.log;	Yes	Yes

Globalization

See the dojo book Internationalization (i18n) section of the dojo book for information about globalization.

We will follow the basic structure being used in the dijit code. From a directory perspective we will have a new "nls" directory for each widget which requires i18n enablement.

You can see the "zero.widget.ide.appmgr" widget as an example. I added "Nls" on the end of each nls js file so that we would not have a name conflict between the real js for the widget and the js for the nls support (dojo generally used the same name).

1. We have directories like this:
   
   • zero.widget.ide.appmgr
     • AppListRow.js
     • AppMgrUi.js
     • CreateAppDialog.js
     • : : :
   • zero.widget.ide.appmgr.nls
     • AppListRowNls.js
     • AppMgrUiNls.js
     • CommonAppDialogNls.js
   • zero.widget.ide.appmgr.templates
     • AppListRow.html
     • AppMgrUi.html
     • CreateAppDialog.html
     • : : :

If we get back translated bundles they would go under the nls directories like this:

1. If we get back translated bundles they would go under the nls directories like this:
   
   • zero.widget.ide.appmgr.nls
     • AppListRowNls.js
     • AppMgrUiNls.js
     • CommonAppDialogNls.js
   • zero.widget.ide.appmgr.nls.de
     • AppListRowNls.js
     • AppMgrUiNls.js
     • CommonAppDialogNls.js
   • zero.widget.ide.appmgr.nls.fr
     • AppListRowNls.js
     • AppMgrUiNls.js
     • CommonAppDialogNls.js

Action: These lines are needed in the widget js file to use the localization support:

1. Need to add the dojo.requireLocalization line like this:
   
   • dojo.requireLocalization("zero.ide.widget.appmgr", "AppMgrUiNls", null, "ROOT");
2. Need to add the call to get the messages from the nls file like this:
   
   • this.messages = dojo.i18n.getLocalization("zero.ide.widget.appmgr", "AppMgrUiNls", this.lang);
3. If the widget does not have a messages property, you will need to add one like this:
   
   • messages:null,

Here a sample so you can see where these lines go in the js file.

if(!dojo._hasResource["zero.ide.widget.appmgr.AppMgrUi"]){
dojo._hasResource["zero.ide.widget.appmgr.AppMgrUi"] = true;
dojo.provide("zero.ide.widget.appmgr.AppMgrUi");
dojo.requireLocalization("zero.ide.widget.appmgr", "AppMgrUiNls", null, "ROOT");
: : :
   messages:null,
: : :

postMixInProperties: function()
{
    zero.ide.widget.appmgr.AppMgrUi.superclass.postMixInProperties.apply(this, arguments);
    this.messages = dojo.i18n.getLocalization("zero.ide.widget.appmgr", "AppMgrUiNls", this.lang);
    :      :       :
},

Action: All hardcoded strings will need to be removed, and changed to use strings from the nls files:

1. Use the strings from the message bundle in the widget template like this:
   
   • ${messages.myapplications}

like this:   
   <h2 id="appMgrTitleBar">${messages.myapplications}</h2>
or this:
        <h3 class="selected">${messages.actions}</h3>

Tip: I have found it helpful to keep my message bundles with one space before the : and one space after the : so that I can find/replace all of my strings to add something like a ** in front of the string as a way to try to find strings which are still hard coded.