A Dojo Widget: Rating

The title is a tutorial article on how to create a Dojo Widget: Rating by mindtrove' blog. I spent some evenings on this new adventure: Dojo Widget programming. I made some changes and tests to undertand how the Dojo's API working. It is a rewarding process.

Not All Browsers Support Dojo Widget Events

I tried it on Mac and Windows, Firefox, IE and Safari. The widget works fine in Firefox and IE. For Firefox, there was only one minor issue. When I have to Vimperaotr enabled, some keys are not working such as Left, Right, Home and End keys. What I found out is that those key events are trapped by Vimperator and never passed to the widget. After I set pass-through mode(Control-Z), the keys are working fine.

However, Safari is tough. It is a UI mouse driven based browser. It does not let key events to passed to the widget. Only a few HTML DOM controls such as button and text can receive focus but not for others like span. Not sure if there is any way to change Safari's blocking.

Separate Dojo Library from Widget Project

Mindtrove' structure is to put his widget in the folder of Dojo. I don't like this. I prefer to put my customer projects outside of Dojo. Therefore, I tried to put my files like in this structure:

-html (all the test hmtl files)
-images (all the image files)
-scripts
-dojo-release-1.2.0
 -[dojo folders]
 -mindtrove (customer widget)

The customer widget codes are in a separate folder mindtrove, in the same level of other Dojo API library folders.

Here is the codes to load Dojo library files:

<script type="text/javascript"
src="../scripts/dojo-release-1.2.0/dojo/dojo.js"
</script>

And JavaScripts codes to load the widget:

<script type="text/javascript">
  dojo.registerModulePath("info.mindtrove",
    "../../../scripts/dojo-release-1.2.0/mindtrove"
  );
  dojo.require("dojo.parser");
  dojo.require("info.mindtrove.Rating");
  ...
</script>

I tried to move my widget up one level, but the localization files could be not loaded by i18n.js. It looks like that i18n.js does not support cross domain scripts (widget codes outside of Dojo library folder could be treated as cross domain loading).

Add Debug and Double Click Event

When I learn something like this Dojo widget, I always like to add something at the same time. This helps me a lot to better understand structure, logic and codes. As I mentioned above to move my testing html page and Dojo library files not at the root like original codes did.

In addition to that, I have added one more attribute or property called debugKeyCode in the widget. This property is a bool(true or false) data type. I use this property to display keyCode value in the span's Title or tooltip. The keyCode value is saved in the local var preKeyCode when onkeypress event is fired on span object. In this way, I'll be able to see the key codes. Here are some codes I added to Rating.js(under mintrove folder):

dojo.declare('info.mindtrove.Rating', [dijit._Widget, dijit._Templated], {
  ...
  // After currentValue property I added two vars.
  // initial value
  currentValue: 0,
  // Add a property for deug key code, see Rating.html template as well.
  debugKeyCode: false,
  // this is a related property value to hold previous key code
  preKeyCode: "",
  ...
  postCreate: function() {
    ...
    this.connect(span, 'onclick',
      dojo.hitch(this, this._onClick, i+1));
      // listern for mouse doubleclick on the span with the value it
      // represents in the index of star
      this.connect(span, 'ondblclick',
        dojo.hitch(this, this._onDoublClick, i+1));
    ...
  },
  ...
  /*
   * Called when the user doubleclick a star.
   */
  _onDoublClick: function(value, event) {
    if ( this.currentValue >= value )
      this.currentValue -= 1
      this.currentValue = Math.max(this.currentValue, this.minimumValue);
      this._update();
  },
  ...
  _getDescription: function() {
    ...
    var str = dojo.string.substitute(template, [this.currentValue]);
        if ( this.debugKeyCode &&
            this.preKeyCode )
        {
          str = str + ' previous key code: ' + this.preKeyCode;
        }
        return str;
  },
  ...
  _onKeyDown: function(event) {
    ...
    this.preKeyCode = event.keyCode;
    ...
  }
});

In above codes I also added codes to handle double click event. Since Safari does allow span object to get focused and to get onkeypress event, I added this feature so that by using mouse, rating can be added and removed.

Using Firebug Addon
Firebug add-on is a great tool for developers. No only it saves you a lots of time and effort to debug JavaScript codes, but it also provides some information normally you cannot get from the browser.

For example, Dojo supports Firebug by using some attributes when Dojo library is loaded. If you enable two attributes in djConfig like in following codes, you will see the Get Dojo library files in Firebug's console tab. That great to see what is downloaded and what are failed if you set them in wrong location:

<script type="text/javascript">
  var djConfig={
    ...
    parseOnLoad:true,
    isDebug:false
    };
</script>

Another great feature of Firefbug is that you can view the dynamically created DOM elements. By using Dojo and jQuery, you can create DOM elements, change style class, do animations on fly. Normally, I would like to see those elements in html but they are not available from browser's View Page Source or View Selection Source. Firebug does reveal the dynamic changes. That's great help.

For example, if you view the HTML tab in Firebug for this Rating widget, you will see the spans dynamically created and hidden text as well. By learning this Widget tutorial, I discovered a lots of new things, both in Dojo and Firebug.