The first Dojo Toolkit 1.0 Release Candidate is complete. To celebrate, let’s take a look at one of the new features in Dijit’s dijit.Declaration.

We are already familiar with Dijit’s capabilities to render widgets in markup. This is a powerful way of providing widgets in your page with about the same effort as styling with CSS. Recently, Alex Russell blogged about new Dojo alternate script types as a way of attaching code via markup through a creative use of the script tag’s type attribute. One of the newest features in the Dojo Toolkit, dijit.Declaration, extends that approach by giving us a way to define widgets in markup.

Let’s start with a bare-bones HTML document that includes the Dojo Core, dojo.parser, and Dijit. The new parameter “parseOnLoad=true”, included as part of the djConfig attribute in our initial script tag, tells the dojo.parser to go to work. It’s the standard mechanism used when defining a user interface using the markup versions of Dijit constructors. We then include our resources: dijit.Declaration and the dojo.parser.

Now, within the body tag, we will create a placeholder for the widgets that we will be defining. This will be the definition of our widget.

We have created our root element, and gave it a dojoType of dijit.Declaration. This tells the dojo.parser that we intend for this to be the declaration of a widget, including the widget’s template. The widgetClass is the name of our widget, and we have set a property default of defaultText to an empty string. Note the defaults object is in quotes.

If we tried to display the page now, it will be blank. That’s because this is a declaration and the parser consumed it, converted into a constructor object, and is now waiting to be instantiated. In other words, we have to create the actual widget based on our template, emulating the new constructor:

Note that we called our widgetClass, and set the property. Now when we refresh the page, our widget is created:

Example of a widget created with dijit.Declaration

Our widget is displayed, and as you can see, the parser read in the template and found our placeholder for the defaultText property, and replaced it with the value.

Now that we have our markup widget, let’s give it some methods. Let us say if the user leaves a blank field, we want to insert the default text. We will use the alternate script types that Alex showed us:

Using a script-type of dojo/method, the browser skips the script. The dojo.parser then picks it up and converts it to code and inserts it into our widget. Since this is a method type, we’re creating a function, which fires on the onchange event we attached to the input node.

Let’s finish it up. On creation, we will lighten the font color, and when a user clicks on the field, the default text is removed:

Note that to tie into the creation of the widget, we used dojo/connect and, using the Dojo event method “dojo.connect” behind the scenes, connected to the native postCreate method of the widget. Then we created another method, and wired that up to the additional event we attached: onfocus.

Additionally, you could create a base form widget, and extend that with various input and buttons widgets. To extend another markup widget, you would use the mixins method, which might look something like this:

Validation and user feedback can be written, coded, and styled all on the same page. You can see the possibilities of this technique, not only with form fields but with page layouts and more, all quickly prototyped without the need for an extensive supporting infrastructure.