Dojo DTL Basics
by Nikolai Onken

In this tutorial I want to show you the basics of using the extremely powerful templating language DTL when writing your own custom widgets. Dijit already comes with a powerful template mechanism dijit._Templated but sometimes you need a bit more flexibility - dojox.dtl is exactly what you need in those cases.

DTL origins

DTL is the templating language of the Django framework (python based). Its syntax is very simple and extendable which lets you almost do anything you want. Neil Roberts has ported the Django Templating Language to Dojo which enables you to use the exact same syntax in the client and in your JavaScript procject.

dojox.dtl gives you different ways of rendering templates. In this tutorial we are looking into how we can incooperate DTL into widgets declared with dojo.declare and inheriting from dijit._Widget.

The result

We will be creating a little widget which will list store inventory in a simple a little boxy format.
Here is what it will look like:


View example externally

The skeleton

To get you started, open up a new file and put in following code:

dojo.provide("store.Inventory");
 
dojo.require("dijit._Widget");
dojo.require("dojox.dtl._DomTemplated");
 
dojo.declare("store.Inventory",
    [dijit._Widget, dojox.dtl._DomTemplated],
    {
 
});

This gives us a clean start to write our widget. If this code is not familiar to you - all we did here is that we defined a “Class” (though its not really a class) and made it inherit from two other “Classes”. The inheritance from dojox.dtl._DomTemplated is the one we are interested in.

Save this file in a directory called store and name it Inventory.js

The data

As the next step, we have to be aware of the data we would like to render in our widget. In this case as you might have guessed already, we are rendering the inventory of a shop.
Our data object looks like this:

var storeData = [
    {id: 3, name: "Serial", description: "Hmmm healthy", price: "23.33", quantity: "23"},
    {id: 3, name: "Bread", description: "Hmmm healthy", price: "23.33", quantity: "23"},
    {id: 3, name: "Juice", description: "Hmmm healthy", price: "23.33", quantity: "23"},
    {id: 3, name: "Coffee", description: "Hmmm healthy", price: "23.33", quantity: "23"},
    {id: 3, name: "Chocolate", description: "Hmmm healthy", price: "23.33", quantity: "23"},
    {id: 3, name: "Butter", description: "Hmmm healthy", price: "23.33", quantity: "23"},
    {id: 3, name: "Tea", description: "Hmmm healthy", price: "23.33", quantity: "23"},
    {id: 3, name: "Chicken", description: "Hmmm healthy", price: "23.33", quantity: "23"},
    {id: 3, name: "Pasata", description: "Hmmm healthy", price: "23.33", quantity: "23"},
    {id: 3, name: "Fries", description: "Hmmm healthy", price: "23.33", quantity: "23"}
];

We will incoperate this into the widget code in a second. Of course you could replace the object with a much more useful store or retrieve the data via XHR.

The template

We see that we several items with the same properties each. Now if we would want to render those items, each, within a template using DTL we could do it following way:

<div>
    {% for item in storeData %}
        <div>
            <h2>{{ item.name }}</h2>
            <p>{{ item.description }}<p>
            <div><button>Order</button></div>
        </div>
    {% endfor %}
</div>

Putting it all together

Now all we need to do to create a reusable widget is to put the data into the widget definition and tell the widget what template to use.

First create a new folder templates in the store folder and then create a file Inventory.html in that templates folder. Now edit the Inventory.js file we created earlier. We are going to add the templatePath and the data we would like to render.

dojo.provide("store.Inventory");
 
dojo.require("dijit._Widget");
dojo.require("dojox.dtl._DomTemplated");
 
dojo.declare("store.Inventory",
    [dijit._Widget, dojox.dtl._DomTemplated],
    {
    templatePath("store.templates", "Inventory.html"),
    postMixInProperties: function(){
        this.storeData = [
            {id: 3, name: "Serial", description: "Hmmm healthy", price: "23.33", quantity: "23"},
            {id: 3, name: "Bread", description: "Hmmm healthy", price: "23.33", quantity: "23"},
            {id: 3, name: "Juice", description: "Hmmm healthy", price: "23.33", quantity: "23"},
            {id: 3, name: "Coffee", description: "Hmmm healthy", price: "23.33", quantity: "23"},
            {id: 3, name: "Chocolate", description: "Hmmm healthy", price: "23.33", quantity: "23"},
            {id: 3, name: "Butter", description: "Hmmm healthy", price: "23.33", quantity: "23"},
            {id: 3, name: "Tea", description: "Hmmm healthy", price: "23.33", quantity: "23"},
            {id: 3, name: "Chicken", description: "Hmmm healthy", price: "23.33", quantity: "23"},
            {id: 3, name: "Pasata", description: "Hmmm healthy", price: "23.33", quantity: "23"},
            {id: 3, name: "Fries", description: "Hmmm healthy", price: "23.33", quantity: "23"}
        ];
    }
});

This is all there is to it. All we have left to do is to make this look fancy and style it using CSS.
The great thing about what we just did is the fact that we completely have externalized the rendering logic into the template. Some people might see a MVC structure rising but I prefer to just name it a super simple and useful thing :)

What is next?

We have looked at how we can use DTL in a widget but have only covered very few actual featured of DTL. To be sure that we can dive deeper into DTL, make sure you play around with what we have learned in this tutorial - create your own widgets, use data stores instead of plain hard-coded objects and enjoy the ease of creating customizable widgets.

More to come soon.

Source

Download the source example of this tutorial here

Tags: ,

This entry was posted on Friday, April 17th, 2009 at 9:22 am and is filed under Beginners, Dojo Cookies. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

4 Responses to “Dojo DTL Basics”

  1. Uxebu.com - JavaScript addicts » Dojo DTL Basics Says:

    [...] Dojo DTL Basics [...]

  2. Les Says:

    Nikolai , hi!

    Can you explain the code below?

    {% for item in storeData %}

    I was expecting:

    {% for var item in this.storeData %}

  3. mccain Says:

    @Les, the django templating language syntax that is, it is not JavaScript! The template is being parsed by the dojox.dtl engine and then it will be “run”
    for more info see the docs for the django templating language http://docs.djangoproject.com/en/dev/topics/templates/#templates

  4. weierophinney Says:

    You have an error in one of your listings. You have the following in the store.Inventory class:

    templatePath(”store.templates”, “Inventory.html”),

    It should be (based on viewing your source :) ):

    templatePath: dojo.moduleUrl(”store.templates”, Inventory.html”),

Leave a Reply

You must be logged in to post a comment.