jQuery Boilerplate è un semplice framework, orientato agli oggetti, per la creazione di plugin jQuery. Il concept alla base di Boilerplate è in qualche modo ispirato alla gestione degli oggetti di Prototype, in cui ciascun oggetto (o classe) dispone di un metodo privato di inizializzazione (chiamato init). Stoyan Stefanov ha dedicato ampio spazio a questo pattern nel suo libro JavaScript Patterns (che vi consiglio). Vediamo ora la struttura di Boilerplate.
Boilerplate inizia con la definizione di un plugin fittizio il cui nome andrà sostituito con quello del plugin che vogliamo definire:
(function($) {
// here it goes!
$.fn.pluginName = function(method) {
};
})(jQuery);
La sintassi di Boilerplate prevede che i metodi del plugin non vengano uniti direttamente al namespace di jQuery, ma legati ad un oggetto methods e richiamati in questo modo:
element.pluginName('methodName', arg1, arg2, ... argn)
L'oggetto methods viene definito come segue:
var methods = {
// this the constructor method that gets called when the object is created
init : function(options) {
// the plugin's final properties are the merged default and user-provided properties (if any)
// this has the advantage of not polluting the defaults, making them re-usable
this.pluginName.settings = $.extend({}, this.pluginName.defaults, options);
// iterate through all the DOM elements we are attaching the plugin to
return this.each(function() {
var $element = $(this), // reference to the jQuery version of the current DOM element
element = this; // reference to the actual DOM element
// code goes here
});
}
}
Questo oggetto ha il compito di definire ed inizializzare le opzioni del plugin che andremo a creare, ma tenendo sempre separate le opzioni interne da quelle definite dall'utente. Quindi conclude la sua azione con un canonico ciclo each() per associare il plugin a tutte le istanze dell'elemento selezionato.
La parte veramente importante di Boilerplate è la gestione dei metodi del plugin:
// if a method as the given argument exists
if (methods[method]) {
// call the respective method
return methods[method].apply(this, Array.prototype.slice.call(arguments, 1));
// if an object is given as method OR nothing is given as argument
} else if (typeof method === 'object' || !method) {
// call the initialization method
return methods.init.apply(this, arguments);
// otherwise
} else {
// trigger an error
$.error( 'Method "' + method + '" does not exist in pluginName plugin!');
}
In pratica si possono usare sia funzioni che oggetti all'interno dell'oggetto methods. Se si tratta di funzioni, vengono usate direttamente, se invece si tratta di oggetti (o se non ci sono argomenti), viene richiamato direttamente il metodo init() di methods, che quindi considererà l'argomento passato come oggetto e non cercherà di eseguirlo. In tutti gli altri casi viene restituito un errore.
Infine, Boilerplate definisce gli oggetti per gestire le opzioni del plugin:
// plugin's default options
$.fn.pluginName.defaults = {
foo: 'bar'
}
// this will hold the merged default and user-provided options
// you will have access to these options like:
// this.pluginName.settings.propertyName from inside the plugin or
// element.pluginName.settings.propertyName from outside the plugin, where "element" is the element the
// plugin is attached to;
$.fn.pluginName.settings = {}
In pratica, Boilerplate può essere usato come un modello (o "stampo") da usare per creare i nostri plugin, definendo semplicemente all'interno del codice visto in precedenza il nome del plugin, i suoi metodi e le sue opzioni.