OOP with dojo/_base/declare

dojo/_base/declare is Dojo's answer to the boilerplate of raw JavaScript prototype inheritance. Instead of manually wiring up prototype chains, copying constructors, and setting up super calls, you describe your class as a plain object literal and let declare handle the rest.

function Dog(name) {
  Animal.call(this, name);
}
Dog.prototype =
  Object.create(Animal.prototype);
Dog.prototype.constructor = Dog;
Dog.prototype.speak = function() {
  return Animal.prototype
    .speak.call(this) + " (woof)";
};

var Dog = declare(Animal, {
  speak: function() {
    return this.inherited(arguments)
      + " (woof)";
  }
});

Beyond cleaner syntax, declare gives you:

• C3 linearization for multiple inheritance — deterministic method resolution order even with diamond inheritance
• this.inherited() — call any ancestor's implementation of the current method without knowing the class name
• declaredClass — every instance knows its class name as a string, useful for debugging
• Widget lifecycle hooks — when combined with dijit/_Widget, all 8 lifecycle methods are called automatically in order

// declare(superclass, properties)
// superclass: a single class, or null for a base class
// properties: object literal — methods + default property values

var Shape = declare(null, {
  color: "black",
  sides: 0,

  constructor: function(props) {
    // props is the argument passed to new Shape({...})
    // declare automatically mixes props into 'this'
    // so you usually don't need to do anything here
    // unless you need initialization logic
    console.log("Shape created:", this.color);
  },

  describe: function() {
    return "A " + this.color + " shape with " + this.sides + " sides";
  },

  area: function() {
    return 0;  // subclasses override this
  }
});

var Rectangle = declare(Shape, {
  sides: 4,
  width: 0,
  height: 0,

  area: function() {
    return this.width * this.height;
  },

  describe: function() {
    // Call Shape.describe() then add our info
    var base = this.inherited(arguments);
    return base + " (" + this.width + "x" + this.height + ")";
  }
});

var r = new Rectangle({ color: "red", width: 5, height: 3 });
console.log(r.describe());  // "A red shape with 4 sides (5x3)"
console.log(r.area());      // 15
console.log(r instanceof Rectangle);  // true
console.log(r instanceof Shape);      // true
console.log(r.declaredClass);         // "Object" (unnamed) or "myapp/Rectangle" if named

The constructor Hook

// constructor() fires BEFORE the DOM exists
// Use it ONLY for:
//   - initializing per-instance objects/arrays (avoid prototype trap)
//   - storing constructor arguments for later use
// Do NOT use it for:
//   - DOM queries (DOM doesn't exist yet)
//   - calling methods that need the widget to be placed in the page

var MyWidget = declare([_Widget], {
  constructor: function(params, srcNodeRef) {
    // params: config object passed to new MyWidget({...})
    // srcNodeRef: DOM node or id to replace (optional)

    // Safe in constructor: initialize per-instance data
    this._handles = [];
    this._data = [];

    // NOT safe in constructor: this.domNode doesn't exist yet
    // this.domNode.style.color = "red";  �? will throw
  }
});

When the first argument to declare is an array, the first element is the true superclass and the rest are mixins. Mixins contribute methods and properties but are not treated as full superclasses for instanceof checks.

// Define reusable mixin behaviors
var Serializable = declare(null, {
  serialize: function() {
    return JSON.stringify(this._getData());
  },
  _getData: function() {
    return {};   // override in subclass
  }
});

var Validatable = declare(null, {
  isValid: function() {
    return this._validate();
  },
  _validate: function() {
    return true;  // override in subclass
  },
  getErrors: function() {
    return [];
  }
});

// Combine: UserModel inherits from BaseModel and gets both mixins
var UserModel = declare([BaseModel, Serializable, Validatable], {
  name:  "",
  email: "",

  _getData: function() {
    return { name: this.name, email: this.email };
  },

  _validate: function() {
    return this.name.length > 0 && this.email.indexOf("@") > -1;
  }
});

var user = new UserModel({ name: "Alice", email: "alice@example.com" });
console.log(user.isValid());    // true
console.log(user.serialize());  // '{"name":"Alice","email":"alice@example.com"}'

Method Resolution Order (MRO)

When multiple classes in the mixin chain define the same method, declare uses C3 linearization to determine which runs first. The rule is: left-to-right, depth-first, with the declared class's own method winning.

var A = declare(null,  { greet: function() { return "A"; } });
var B = declare([A],   { greet: function() { return "B+" + this.inherited(arguments); } });
var C = declare([A],   { greet: function() { return "C+" + this.inherited(arguments); } });
var D = declare([B,C], { greet: function() { return "D+" + this.inherited(arguments); } });

var d = new D();
console.log(d.greet());
// "D+B+C+A"
// Order: D → B → C → A  (C3 linearization)

Dijit's Built-in Mixin Stack

this.inherited(arguments) calls the same-named method in the nearest ancestor class. It uses the live arguments object to identify which method is currently running and passes the same arguments up the chain.

// Basic usage — pass arguments straight through
var Base = declare(null, {
  init: function(config) {
    this.config = config;
    console.log("Base.init");
  }
});

var Middle = declare(Base, {
  init: function(config) {
    console.log("Middle.init — before super");
    this.inherited(arguments);   // calls Base.init(config)
    console.log("Middle.init — after super");
  }
});

var Child = declare(Middle, {
  init: function(config) {
    console.log("Child.init");
    this.inherited(arguments);   // calls Middle.init(config) → Base.init(config)
  }
});

new Child().init({ debug: true });
// Child.init
// Middle.init — before super
// Base.init
// Middle.init — after super

Overriding Arguments Before Passing Up

// Pass modified arguments to the parent
var MyButton = declare([dijit.form.Button], {
  onClick: function(e) {
    // Enrich the event before passing to parent handler
    e.widgetSource = this.id;
    this.inherited(arguments);   // Button.onClick(e) — with our enriched event
  }
});

// Or pass entirely different arguments:
var MyWidget = declare([_Widget], {
  resize: function(newSize) {
    // Double the size before passing to parent
    this.inherited(arguments, [{ w: newSize.w * 2, h: newSize.h * 2 }]);
    //                         ↑ second arg overrides what gets passed up
  }
});

Checking If a Parent Method Exists

// Safe pattern when you're not sure if a parent implements the method
var result = this.inherited(arguments);
// If no parent has this method, inherited() returns undefined — no error thrown

// Alternatively, check explicitly:
if (this.inherited) {
  this.inherited(arguments);
}

Every dijit/_Widget subclass goes through a precise sequence of lifecycle hooks. Understanding which hook fires when — and what the DOM state is at each point — is the single most important skill in Dojo widget development.

// Complete widget with all lifecycle hooks annotated
define([
  "dojo/_base/declare",
  "dojo/_base/lang",
  "dijit/_Widget",
  "dijit/_TemplatedMixin",
  "dojo/on",
  "dojo/topic",
  "dojo/text!./templates/MyWidget.html"
], function(declare, lang, _Widget, _TemplatedMixin, on, topic, template) {

  return declare([_Widget, _TemplatedMixin], {
    templateString: template,

    // Default properties (on prototype — safe for primitives)
    label:    "Default Label",
    selected: false,

    // ── Hook 1: constructor ──────────────────────────────────
    constructor: function(params, srcNodeRef) {
      this._handles = [];   // per-instance array — SAFE
      this._cache   = {};   // per-instance object — SAFE
    },

    // ── Hook 2: postMixInProperties ─────────────────────────
    postMixInProperties: function() {
      this.inherited(arguments);
      // label is now set from params — compute derived value for template
      this.ariaLabel = this.label + " button";
    },

    // ── Hook 3: buildRendering ───────────────────────────────
    buildRendering: function() {
      this.inherited(arguments);
      // domNode is now set — template is parsed
      // attach points (data-dojo-attach-point) are wired
      this.domNode.setAttribute("role", "button");
    },

    // ── Hook 4: postCreate ───────────────────────────────────
    postCreate: function() {
      this.inherited(arguments);
      // Wire events — store handles for cleanup
      this._handles.push(
        on(this.domNode, "click", lang.hitch(this, "_onClick"))
      );
      this._handles.push(
        topic.subscribe("app/reset", lang.hitch(this, "_onReset"))
      );
    },

    // ── Hook 6: startup ──────────────────────────────────────
    startup: function() {
      if (this._started) return;  // guard — startup should only run once
      this.inherited(arguments);
      // Safe to use offsetWidth here
      this._initialWidth = this.domNode.offsetWidth;
    },

    // ── Private methods ──────────────────────────────────────
    _onClick: function(e) {
      this.set("selected", !this.selected);
      this.emit("change", { selected: this.selected });
    },

    _onReset: function() {
      this.set("selected", false);
    },

    // ── Hook 7: destroy ──────────────────────────────────────
    destroy: function(preserveDom) {
      // Remove ALL stored handles
      this._handles.forEach(function(h) { h.remove(); });
      this._handles = [];
      this._cache = null;
      this.inherited(arguments);   // MUST call — cleans up dijit registry
    }
  });
});

This is the most common source of layout bugs in Dojo applications. The rule is simple but easy to forget:

// WRONG — checking size in postCreate
postCreate: function() {
  this.inherited(arguments);
  var w = this.domNode.offsetWidth;   // always 0 — widget not in page yet
  this._setColumnWidths(w);           // bug: calculates with 0
},

// CORRECT — size-dependent logic in startup
postCreate: function() {
  this.inherited(arguments);
  on(this.domNode, "click", lang.hitch(this, "_onClick"));  // event: OK here
},
startup: function() {
  if (this._started) return;
  this.inherited(arguments);
  var w = this.domNode.offsetWidth;   // correct — widget is in the page
  this._setColumnWidths(w);
}

Failing to destroy widgets is the most common source of memory leaks in large Dojo applications. Every widget you create programmatically that is later removed from the page must be explicitly destroyed.

// Common scenario: replace a tab's content
function refreshTab(tabContainer) {
  var tab = dijit.byId("dataTab");

  // Destroy old content BEFORE adding new content
  tab.destroyDescendants();  // keeps the tab, destroys its children

  // Or destroy the entire tab and recreate:
  // tab.destroyRecursive();
  // tabContainer.addChild(new ContentPane({...}));
}

// Scenario: a dialog that creates widgets inside
var dlg = new Dialog({...});
dlg.show();

// When done — destroyRecursive to get widgets inside the dialog too
dlg.on("hide", function() {
  dlg.destroyRecursive();
});

// Registry check — after destroy, widget should not be in registry
var widget = new MyWidget({id: "myW"}).placeAt("body").startup();
widget.destroyRecursive();
console.log(dijit.byId("myW"));  // undefined — correctly removed from registry

dijit/_TemplatedMixin lets you define your widget's DOM structure as an HTML string (usually loaded with dojo/text!). It processes the template, substitutes ${property} values, and wires up attach points and attach events automatically.

<!-- myapp/templates/UserCard.html -->
<!-- Rules:
     1. Must have exactly ONE root element
     2. ${prop} = one-time substitution at create time (not reactive)
     3. data-dojo-attach-point = creates this.nameRef property on the widget
     4. data-dojo-attach-event = auto-wires event to widget method
-->
<div class="user-card ${extraClass}"
     data-dojo-attach-point="containerNode">

  <div class="user-avatar"
       style="background-color: ${avatarColor}">
    <span data-dojo-attach-point="initialsNode">${initials}</span>
  </div>

  <div class="user-info">
    <h3 data-dojo-attach-point="nameNode">${name}</h3>
    <p  data-dojo-attach-point="roleNode">${role}</p>
  </div>

  <button data-dojo-attach-point="editBtn"
          data-dojo-attach-event="onclick:_onEdit">
    Edit
  </button>
</div>

// myapp/widgets/UserCard.js
define([
  "dojo/_base/declare",
  "dojo/_base/lang",
  "dijit/_Widget",
  "dijit/_TemplatedMixin",
  "dojo/text!./templates/UserCard.html"
], function(declare, lang, _Widget, _TemplatedMixin, template) {

  return declare([_Widget, _TemplatedMixin], {
    templateString: template,

    // These match ${...} substitutions in the template
    name:        "Unknown User",
    role:        "viewer",
    extraClass:  "",
    avatarColor: "#6366f1",
    initials:    "?",

    postMixInProperties: function() {
      this.inherited(arguments);
      // Compute initials before template renders
      if (this.name && this.name !== "Unknown User") {
        this.initials = this.name
          .split(" ")
          .map(function(w) { return w[0].toUpperCase(); })
          .join("");
      }
    },

    postCreate: function() {
      this.inherited(arguments);
      // attach points are now available as widget properties:
      // this.containerNode — the root div
      // this.initialsNode  — the span inside avatar
      // this.nameNode      — the h3
      // this.roleNode      — the p
      // this.editBtn       — the button
      // (data-dojo-attach-event already wired _onEdit to button click)

      if (this.role === "admin") {
        this.containerNode.classList.add("is-admin");
      }
    },

    // Called by data-dojo-attach-event
    _onEdit: function(e) {
      e.stopPropagation();
      this.emit("edit", { user: { name: this.name, role: this.role } });
    },

    // Reactive property update — called when set("name", newValue)
    _setNameAttr: function(name) {
      this._set("name", name);        // updates this.name
      if (this.nameNode) {            // guard: may not exist if called before postCreate
        this.nameNode.textContent = name;
      }
    }
  });
});

${prop} Substitution vs _setXxxAttr

Use ${prop} for values that never change after creation (CSS classes, ARIA roles). Use _setXxxAttr for values that the app will update at runtime.

When your template contains declarative Dojo widgets (elements with data-dojo-type), add _WidgetsInTemplateMixin. It runs the parser on your template so nested widgets are instantiated as part of your widget's creation.

<!-- templates/SearchBar.html -->
<div class="search-bar">
  <!-- Nested Dijit widget inside this widget's template -->
  <input data-dojo-type="dijit/form/ValidationTextBox"
         data-dojo-props="placeholder:'Search...', required:true"
         data-dojo-attach-point="inputWidget" />

  <button data-dojo-type="dijit/form/Button"
          data-dojo-props="label:'Go', iconClass:'dijitIconSearch'"
          data-dojo-attach-point="searchBtn"
          data-dojo-attach-event="onClick:_onSearch">
  </button>
</div>

define([
  "dojo/_base/declare",
  "dijit/_Widget",
  "dijit/_TemplatedMixin",
  "dijit/_WidgetsInTemplateMixin",   // �? ADD this mixin
  "dojo/text!./templates/SearchBar.html",
  "dijit/form/ValidationTextBox",    // �? MUST require nested widget types
  "dijit/form/Button"
], function(declare, _Widget, _TemplatedMixin, _WidgetsInTemplateMixin,
            template, ValidationTextBox, Button) {

  return declare([_Widget, _TemplatedMixin, _WidgetsInTemplateMixin], {
    templateString: template,

    postCreate: function() {
      this.inherited(arguments);
      // this.inputWidget — the ValidationTextBox INSTANCE (not a DOM node)
      // this.searchBtn   — the Button INSTANCE
    },

    startup: function() {
      if (this._started) return;
      this.inherited(arguments);
      // Start nested widgets (required for layout widgets inside template)
      this.inputWidget.startup();
      this.searchBtn.startup();
    },

    _onSearch: function() {
      if (this.inputWidget.isValid()) {
        this.emit("search", { query: this.inputWidget.get("value") });
      }
    },

    destroy: function(preserveDom) {
      // destroyRecursive handles nested widgets automatically
      // but if you stored extra references, clean them up here
      this.inherited(arguments);
    }
  });
});

A real-world migration showing the same "ExpandablePanel" component — first as a jQuery plugin, then rewritten as a proper Dijit widget.

Original jQuery Plugin

// jQuery version — problems: no lifecycle, no cleanup, no registry,
// no proper events, no property system
$.fn.expandablePanel = function(options) {
  var settings = $.extend({ title: "Panel", collapsed: false }, options);

  return this.each(function() {
    var $el = $(this);
    var $header = $("<div class='panel-header'>" + settings.title + "</div>");
    var $body   = $("<div class='panel-body'>").append($el.children());

    $el.empty().append($header).append($body);

    if (settings.collapsed) $body.hide();

    $header.on("click", function() {
      $body.toggle();
      $el.trigger("toggle", [$body.is(":visible")]);
    });
    // No cleanup. No way to find this "widget" later. No property updates.
  });
};

Rewritten as a Dijit Widget

// Dijit version — full lifecycle, registry, events, property system
define([
  "dojo/_base/declare",
  "dojo/_base/lang",
  "dijit/_Widget",
  "dijit/_TemplatedMixin",
  "dojo/on",
  "dojo/dom-class",
  "dojo/text!./templates/ExpandablePanel.html"
], function(declare, lang, _Widget, _TemplatedMixin, on, domClass, template) {

  return declare([_Widget, _TemplatedMixin], {
    templateString: template,

    // Public API — settable via constructor or set()
    title:     "Panel",
    collapsed: false,

    postCreate: function() {
      this.inherited(arguments);
      this._handles.push(
        on(this.headerNode, "click", lang.hitch(this, "_onHeaderClick"))
      );
      if (this.collapsed) {
        domClass.add(this.domNode, "is-collapsed");
      }
    },

    constructor: function() {
      this._handles = [];
    },

    _onHeaderClick: function() {
      this.set("collapsed", !this.collapsed);
    },

    // Reactive setter — fires when set("collapsed", value) is called
    _setCollapsedAttr: function(val) {
      this._set("collapsed", val);
      domClass.toggle(this.domNode, "is-collapsed", val);
      // Emit a Dojo event (listeners use widget.on("toggle", ...))
      this.emit("toggle", { collapsed: val });
    },

    // Reactive setter for title
    _setTitleAttr: { node: "titleNode", type: "innerHTML" },
    // shorthand: automatically sets titleNode.innerHTML = value

    destroy: function(preserveDom) {
      this._handles.forEach(function(h) { h.remove(); });
      this.inherited(arguments);
    }
  });
});

// Usage — clean, discoverable, proper lifecycle
var panel = new ExpandablePanel({
  title: "Server Stats",
  collapsed: false
}).placeAt("sidebarArea");
panel.startup();

// Listen to events cleanly
panel.on("toggle", function(e) {
  console.log("Panel is now", e.collapsed ? "collapsed" : "expanded");
});

// Later: update properties reactively
panel.set("title", "Updated Title");
panel.set("collapsed", true);

// Find it later from anywhere
var samePanel = dijit.byId(panel.id);

// When done — proper cleanup
panel.destroyRecursive();