You are viewing an older version of Mapbox.js. Check out v3.0.1 for the latest.

Class

L.Class powers the OOP facilities of Leaflet and is used to create almost all of the Leaflet classes documented here.

In addition to implementing a simple classical inheritance model, it introduces several special properties for convenient code organization — options, includes and statics.

var MyClass = L.Class.extend({
	initialize: function (greeter) {
this.greeter = greeter;
// class constructor
	},

	greet: function (name) {
alert(this.greeter + ', ' + name)
	}
});

// create instance of MyClass, passing "Hello" to the constructor
var a = new MyClass("Hello");

// call greet method, alerting "Hello, World"
a.greet("World");

Class Factories

You may have noticed that Leaflet objects are created without using the new keyword. This is achieved by complementing each class with a lowercase factory method:

new L.Map('map'); // becomes:
L.map('map');

The factories are implemented very easily, and you can do this for your own classes:

L.map = function (id, options) {
	return new L.Map(id, options);
};

Inheritance

You use L.Class.extend to define new classes, but you can use the same method on any class to inherit from it:

var MyChildClass = MyClass.extend({
	// ... new properties and methods
});

This will create a class that inherits all methods and properties of the parent class (through a proper prototype chain), adding or overriding the ones you pass to extend. It will also properly react to instanceof:

var a = new MyChildClass();
a instanceof MyChildClass; // true
a instanceof MyClass; // true

You can call parent methods (including constructor) from corresponding child ones (as you do with super calls in other languages) by accessing parent class prototype and using JavaScript's call or apply:

var MyChildClass = MyClass.extend({
	initialize: function () {
MyClass.prototype.initialize.call(this, "Yo");
	},

	greet: function (name) {
MyClass.prototype.greet.call(this, 'bro ' + name + '!');
	}
});

var a = new MyChildClass();
a.greet('Jason'); // alerts "Yo, bro Jason!"

Options

options is a special property that unlike other objects that you pass to extend will be merged with the parent one instead of overriding it completely, which makes managing configuration of objects and default values convenient:

var MyClass = L.Class.extend({
	options: {
myOption1: 'foo',
myOption2: 'bar'
	}
});

var MyChildClass = MyClass.extend({
	options: {
myOption1: 'baz',
myOption3: 5
	}
});

var a = new MyChildClass();
a.options.myOption1; // 'baz'
a.options.myOption2; // 'bar'
a.options.myOption3; // 5

There's also L.Util.setOptions, a method for conveniently merging options passed to constructor with the defauls defines in the class:

var MyClass = L.Class.extend({
	options: {
foo: 'bar',
bla: 5
	},

	initialize: function (options) {
L.Util.setOptions(this, options);
...
	}
});

var a = new MyClass({bla: 10});
a.options; // {foo: 'bar', bla: 10}

Includes

includes is a special class property that merges all specified objects into the class (such objects are called mixins). A good example of this is L.Mixin.Events that event-related methods like on, off and fire to the class.

 var MyMixin = {
	foo: function () { ... },
	bar: 5
};

var MyClass = L.Class.extend({
	includes: MyMixin
});

var a = new MyClass();
a.foo();

You can also do such includes in runtime with the include method:

MyClass.include(MyMixin);

Statics

statics is just a convenience property that injects specified object properties as the static properties of the class, useful for defining constants:

var MyClass = L.Class.extend({
	statics: {
FOO: 'bar',
BLA: 5
	}
});

MyClass.FOO; // 'bar'

Constructor Hooks

If you're a plugin developer, you often need to add additional initialization code to existing classes (e.g. editing hooks for L.Polyline). Leaflet comes with a way to do it easily using the addInitHook method:

MyClass.addInitHook(function () {
	// ... do something in constructor additionally
	// e.g. add event listeners, set custom properties etc.
});

You can also use the following shortcut when you just need to make one additional method call:

MyClass.addInitHook('methodName', arg1, arg2, …);