Dojo is our Javascript toolkit of choice and we’ve recently upgraded to Dojo 1.1.1. We’re going to try to pass on some of the knowledge we’ve accrued, starting with how to create your own custom widgets.

Step 1. Determining Inheritance – Typically you’re going to be subclassing an existing widget, so naturally you’ll need to inherit from that widget. But there are several other widgets you may chose to inherit from.

• dijit._Widget: Pretty basic, if you follow each widget’s inheritence you’ll eventually get here, so you probably won’t need to inherit from this unless you’re starting from scratch.
• dijit._Templated: If you want your widget to pull in and use an HTML template
• dijit.layout.ContentPane: Includes some AJAX, as well as layout methods
• dijit._Contained / dijit._Container: To establish parent child relationships between two widgets, the child and parent will need to inherit from each respective widget

Step 2. Writing the Code – Each widget has some pretty basic methods you’ll want to override or add to, check out the widget life cycle to learn about all of them.

Code examples are after the jump.

Basic skeleton of the js:
// The widget you are providing
dojo.provide("sagrader.widget.Awesome");

// anything you inherit from or use
dojo.require("dijit._Templated");
// needed for contained
dojo.require("dijit._Container");

// params: "name of widget", widgets inherited from, your code
dojo.declare( "sagrader.widget.Awesome", [ dijit._Contained, dijit._Templated ], {
    // Your template, can also use templateString and just put it inline.
    // If you are inheriting from a widget using templateString you'll
    // need to set "templateString: null" in your widget
    templatePath: dojo.moduleUrl("sagrader.widget", "templates/Awesome.html"),

    // Your widget's attributes, correspond to attributes you set in the HTML
    some_attribute: '',
    heres_one_that_has_a_default: true,
    myButtonWidget: null,

    // called after the widget is created, typically used as an init function
    postCreate: function(args, frag){

        // You call a superclass method this way, "arguments" is important
        this.inherited("postCreate", arguments);

        console.info("I'm called as soon as I'm loaded!");

        // myButton is in the template as a dojoAttachPoint
        this.myButtonWidget = new dijit.form.Button( {value: "Click Me!"}, this.myButton);

        // Connect the onClick from the button to a function called "buttonClick"
        dojo.connect(this.myButtonWidget, "onClick", "buttonClick");
    },

    buttonClick: function() {
        console.info("Click!");
    }
});

Basic template
<div class="outer_div">
<style type="text/css">
    // whatever css you want needs to be in this file
    .outer_div {
        color: green;
    }
</style>
<div dojoAttachPoint="myButton"></div>
<span>${some_attribute}</span>
</div>

You have access to any dojoAttachPoint nodes in the js.

What you’ll put in your main HTML file
<script type="text/javascript">
    dojo.require("sagrader.widget.Awesome");
</script>
<div dojoType="sagrader.widget.Awesome" some_attribute="Some Text">
</div>

“Some Text” will appear in the widget template as well as be accessible in the Javascript.

Hopefully that helps get you started, hit up the comments if you have any questions.