Documentation

Classy JavaScript with dojo/_base/declare

The dojo/_base/declare module is the foundation of class creation within the Dojo Toolkit. declare allows for multiple inheritance to allow developers to create flexible code and avoid writing the same code routines. Dojo, Dijit, and Dojox modules all use declare; in this tutorial, you'll learn why you should too.

Difficulty: Beginner
Dojo Version: 1.8

Getting Started

Make sure you have reviewed the concepts presented in the modules tutorial.

Basic Dojo Class Creation with Dojo

The declare function is defined in the dojo/_base/declare module. declare accepts three arguments: className, superClass, and properties.

ClassName

The className argument represents the name of the class, including the namespace, to be created. Named classes are placed within the global scope. The className can also represent the inheritance chain via the namespace.

Named Class

// Create a new class named "mynamespace.MyClass"
declare("mynamespace.MyClass", null, {

	// Custom properties and methods here

});

A class named mynamespace.MyClass is now globally available within the application.

Named classes should only be created if they will be used with the Dojo parser. All other classes should omit the className parameter.

"Anonymous" Class

// Create a scoped, anonymous class
var MyClass = declare(null, {

	// Custom properties and methods here

});

The MyClass is now only available within its given scope.

SuperClass(es)

The SuperClass argument can be null, one existing class, or an array of existing classes. If a new class inherits from more than one class, the first class in the list will be the base prototype, the rest will be considered "mixins".

Class with No Inheritance

var MyClass = declare(null, {

	// Custom properties and methods here

});

null signifies that this class has no classes to inherit from.

Class Inheriting from Another Class

var MySubClass = declare(MyClass, {

	// MySubClass now has all of MyClass's properties and methods
	// These properties and methods override parent's

});

The new MySubClass will inherit MyClass's properties and methods. A parent class' method or property can be overridden by adding its key with a new definition within the third argument, which will be explained shortly.

Class with Multiple Inheritance

var MyMultiSubClass = declare([
	MySubClass,
	MyOtherClass,
	MyMixinClass
],{

	// MyMultiSubClass now has all of the properties and methods from:
	// MySubClass, MyOtherClass, and MyMixinClass

});

An array of classes signifies multiple inheritance. Properties and methods are inherited from left to right. The first class in the array serves as the base prototype, then the subsequent classes are mixins to that class.

If a property or method is specified in more than one inherited class, the property or method from the last inherited class is used.

Properties and Methods Object

The last argument of declare is an object containing methods and properties for the class prototype. Properties and methods provided via this argument will override their same namesake if inherited classes have the same properties.

Custom Properties and Methods

// Class with custom properties and methods
var MyClass = declare(MyParentClass, {
	// Any property
	myProperty1: 12,
	// Another
	myOtherProperty: "Hello",
	// A method
	myMethod: function(){

		// Perform any functionality here

		return result;
	}
});

Example: Basic Class Creation and Inheritance

The following code creates a widget that inherits from dijit/form/Button:

define([
	"dojo/_base/declare",
	"dijit/form/Button"
], function(declare, Button){
	return declare("mynamespace.Button", Button, {
		label: "My Button",
		onClick: function(evt){
			console.log("I was clicked!");
			this.inherited(arguments);
		}
	});
});

From the snippet above, it's easy to conclude:

The class' name is mynamespace.Button
The class may be referenced by the globally available mynamespace.Button or from the module's return value
The class inherits from dijit/form/Button (and thus Button's dependencies)
The class sets a few custom properties and methods

Let's dig deeper into class creation with Dojo by learning about the constructor method.

The constructor Method

Once of the special class methods is the constructor method. The constructor method is fired upon class instantiation, executed in the scope of the new object. This means that the this keyword references the instance, not the original class. The constructor method also accepts any number of instance-specific arguments.

// Create a new class
var Twitter = declare(null, {
	// The default username
	username: "defaultUser",

	// The constructor
	constructor: function(args){
		declare.safeMixin(this,args);
	}
});

Take the following instance creation:

var myInstance = new Twitter();

The username used within this instance will be "defaultUser" since no specific settings were provided to the instance. To leverage the safeMixin method, provide a username parameter:

var myInstance = new Twitter({
	username: "sitepen"
});

Now the instance uses sitepen as the username setting!

declare.safeMixin is also useful in class creation and inheritance. As the API docs state:

This function is used to mix in properties like lang._mixin does, but it skips a constructor property and decorates functions like dojo/_base/declare does. It is meant to be used with classes and objects produced with dojo/_base/declare. Functions mixed in with declare.safeMixin can use this.inherited() like normal methods. This function is used to implement extend() method of a constructor produced with declare().

declare.safeMixin is the perfect ally when creating classes with numerous options.

Inheritance

As stated above, inheritance is defined within the second argument of declare. Classes are mixed-in from left to right with each subsequent class' properties and methods getting priority over the previous if a property has already been defined. Take the following:

// Define class A
var A = declare(null, {
	// A few properties...
	propertyA: "Yes",
	propertyB: 2
});

// Define class B
var B = declare(A, {
	// A few properties...
	propertyA: "Maybe",
	propertyB: 1,
	propertyC: true
});

// Define class C
var C = declare([mynamespace.A, mynamespace.B], {
	// A few properties...
	propertyA: "No",
	propertyB: 99,
	propertyD: false
});

The result of the inherited class properties is:

// Create an instance
var instance = new C();

// instance.propertyA = "No" // overridden by B, then by C
// instance.propertyB = 99 // overridden by B, then by C
// instance.propertyC = true // kept from B
// instance.propertyD = false // created by C

Setting and overriding simple Number, String, and boolean variables is straight-forward. Be careful when using arrays and objects with dojo/_base/declare to ensure they are properly scoped. Arrays and objects defined in the return are shared by all instances of the object. Arrays and objects defined in the constructor are properties of each object instantiation. Refer to the dojo/_base/declare documentation for additional information.

this.inherited

While completely overriding methods is certainly useful, sometimes the constructor of each class up through the inheritance chain should be executed to preserve its original functionality. This is where the this.inherited(arguments) statement comes in handy. The this.inherited(arguments) statement calls the parent class' method of the same name. Consider the following:

// Define class A
var A = declare(null, {
	myMethod: function(){
		console.log("Hello!");
	}
});

// Define class B
var B = declare(A, {
	myMethod: function(){
		// Call A's myMethod
		this.inherited(arguments); // arguments provided to A's myMethod
		console.log("World!");
	}
});

// Create an instance of B
var myB = new B();
myB.myMethod();


// Would output:
//		Hello!
//		World!

The this.inherited method can be called at any time within the child class' code. There will be some cases where you will want to call inherited() in the middle of the child function, or even at the end. That said, you should not call it from within the constructor.

Conclusion

The declare function is the key to creating modular, reusable classes with the Dojo Toolkit. declare allows for complex class recreation with multiple inheritance and any number of properties and methods. Better yet is that declare is simple to learn and will allow developers to avoid repeating code.

dojo/_base/declare Resources

Looking for more detail about declare and class creation? Check out these great resources:

Error in the tutorial? Can’t find what you are looking for? Let us know!