wrld.js

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.

Usage example

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 = L.Class.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 defaults 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).

 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 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, …);

Functions

Function Returns Description
extend(<Object> props) Function Extends the current class given the properties to be included. Returns a Javascript function that is a class constructor (to be called with new).
include(<Object> properties) this Includes a mixin into the current class.
mergeOptions(<Object> options) this Merges options into the defaults of the class.
addInitHook(<Function> fn) this Adds a constructor hook to the class.
v0.1.1427