Vous avez toujours voulu être branché ? Non ? Pourquoi tu dis rien ?

T’aimes pas les accroches interrogatives

Voici donc la suite de notre série d’articles consacrés à jQuery, avec aujourd’hui : le plugin !

La conception de jQuery, centrée sur un même objet, permet d’étendre naturellement notre bibliothèque en créant de nouvelles méthodes. Un plugin sera alors utilisé de cette façon :

$("p").monplugin();

Nous créerons pour l’exemple un plugin qui fait danser les éléments sélectionnés, appelons-le « jQuery Dance ».

On pourra éventuellement lui passer des options : le tempo, et la taille de la piste de danse bien entendu !

Il sera utilisé ainsi :

$("p").dance();

Ah, vous l’aviez certainement noté : la sonorité de jQuery est proche de celle de charcuterie. Et comme pour la rosette, certaines règles sont à respecter pour créer un plugin de qualité, les voici.

Nommez votre fichier

Un plugin doit toujours se nommer ainsi, de manière à ce qu’il soit immédiatement identifiable : jquery.nom_du_plugin.js
Notre fichier se nommera donc jquery.dance.js.

Isolez votre code

Dans ce fichier nouvellement créé, nous allons commencer par englober tout ce qui va être écrit dans une fonction anonyme qui sera immédiatement executée. De cette manière, toutes les variables que vous créerez ne rentrerons pas en collision avec les autres scripts présents sur la page.

(function(){
	// Code
})()

Nous allons en profiter pour passer la variable jQuery (dont $ n’est qu’un alias) à cette fonction, de cette manière :

(function($){
	// Code
})(jQuery)

Cela permettra d’utiliser la variable $ à l’intérieur de notre fonction.
Pourquoi, puisque $ est déjà un alias de jQuery ?

jQuery permet de renommer cette fonction à l’aide de jQuery.noConflict().
Il est donc possible de faire cohabiter jQuery et l’une des nombreuses librairies utilisant la fonction $() (comme Prototype), en renommant l’alias comme bon nous semble :

var $j = jQuery.noConflict();

Nous devons donc nous assurer que la fonction $() existe bien, et que nous n’utilisons pas une autre librairie à la place de jQuery.

Ajoutez votre nouvelle méthode à jQuery.fn

Après avoir créé notre environnement, nous sommes prêts à écrire notre plugin.
Nous voulons donc ajouter une nouvelle méthode aux objets jQuery. Il faut pour cela ajouter une nouvelle fonction à l’objet jQuery.fn. Dans cette fonction, le mot-clé this représente l’objet jQuery sélectionné par l’utilisateur de votre plugin.

Dans le cas où notre plugin serait défini de cette façon :

(function($){
	$.fn.dance = function(){
		alert(this == ma_selection);
	};
})(jQuery)

Et qu’une variable globale (absence du mot var) ma_selection soit définie ainsi :

// Au chargement...
$(function(){
	ma_selection = $("p");
	ma_selection.dance();
});

Le message affiché par la fonction alert() serait true.

Bouclez sur les éléments sélectionnés

Vous devez toujours considérer que plusieurs éléments ont été sélectionnés avant d’appeler votre méthode.

Pour traiter chacun de ces éléments, la méthode each() de jQuery sera utilisée. cette méthode prend en paramètre une fonction, qui sera executée pour chaque élément. Dans cette boucle, le mot this correspondra cette fois à chacun des éléments DOM de cette sélection.
Pour obtenir un objet jQuery, il faudra passer cet élément à la fonction $().

(function($){
	$.fn.dance = function(){
		this.each(function(){
		  // this : élément DOM classique
		  // $(this) : élément jQuery
		});
	};
})(jQuery)

Gardez à l’esprit que cette fonction est executée pour chacun des éléments de la sélection. Il est donc préférable de ne placer dans cette fonction que les traitements liés à chaque élément en particulier.

(function($){
	$.fn.dance = function(){

		// Le tempo est le même pour tous les éléments,
		// inutile de le redéfinir à chaque  fois.
		var tempo = 300;

		// Cette fonction n'est définie qu'une fois,
		// puis appelée par chacun des éléments.
		function move(jElt){
			// Nous placerons ici le code permettant
			// de faire danser le Boogie Woogie à un élément
		};

		this.each(function(){
			move( $(this) );
		});
	};
})(jQuery)

Retournez l’objet sélectionné

Cette pratique permettra d’utiliser plusieurs méthodes en chaîne :

$("p").dance().css("color", "red");

Evidemment, si votre plugin renvoie une information, il ne sera alors pas possible de chaîner plusieurs méthodes (comme avec la méthode width() par exemple).

Il faudra donc que votre méthode retourne this avant de se terminer.

(function($){
	$.fn.dance = function(){

		// Code...

		return this;
	};
})(jQuery)

Et puisque la méthode each() de jQuery renvoie l’élément sélectionné, vous pouvez retourner votre sélection en bouclant sur chacun des éléments :

(function($){
	$.fn.dance = function(){

		// Code...

		return this.each(function(){
			move( $(this) );
		});
	};
})(jQuery)

Bien, nous avons vu les bases de la création d’un plugin. Le plugin « jQuery Dance » peut maintenant être utilisé de cette façon :

$("p").dance().css("border","1px");

Passez des paramètres à votre méthode

Comme nous l’avons vu au début de cet article, la méthode dance() prendra deux paramètres : tempo et dancefloorArea, correspondant respectivement à la fréquence d’execution de chaque mouvement(en millisecondes), et à la surface que pourra utiliser cet élément (en pixels).

Définir des paramètres pour notre méthode est très simple :

(function($){
	$.fn.dance = function(tempo, dancefloorArea){

		// Code...

	};
})(jQuery)

La méthode pourra donc être appelée de cette façon :

$("p").dance(300, 400)

Etendez vos paramètres optionnels

Avant d’avancer dans la réalisation de jQuery Dance et de permettre à nos éléments de se déhancher sur le dancefloor, nous allons voir une dernière technique, permettant de passer des paramètres optionnels à une méthode jQuery.

Nos paramètres ne seront alors plus passés directement, mais à l’aide d’un tableau associatif :

$("p").dance({tempo: 300, danceFloorArea: 400})

La fonction jQuery.extend(a, b) permet d’étendre un objet a avec un objet b, en écrasant les propriétés redéfinies.
Voici un exemple :

var objet_a = {
	param_1: "Bonjour",
	param_2: "les p'tits gars"
};
var objet_b = {
	param_2: "tout le monde",
	param_3: "ça va ?"
};

$.extend(objet_a, objet_b);

alert(objet_a.param_1); // Bonjour
alert(objet_a.param_2); // tout le monde
alert(objet_a.param_3); // ça va ?

En plus de l’étendre, cette fonction renvoie le premier objet modifié, ce qui est très pratique lorsque le premier objet est défini en paramètre :

var objet_b = {
	param_2: "tout le monde",
	param_3: "ça va ?"
};

var objet_a = $.extend({
	param_1: "Bonjour",
	param_2: "les p'tits gars"
}, objet_b);

Nous utiliserons cette technique pour étendre nos paramètres par défaut avec ceux passés à la méthode, de cette façon :

(function($){
	$.fn.dance = function(params){

		// Si aucun paramètre n'est passé
		// et que params est vide, alors $.extend()
		// renverra simplement le premier objet passé
		var params = $.extend({
			tempo: 300,
			dancefloorArea: 400
		},params);

		function move(jElt){
			// Boogie Woogie
		};

		return this.each(function(){
			move( $(this) );
		});
	};
})(jQuery)

Voulez-vous danser mademoiselle ?

Chacun de nos éléments sera déplacé, au hasard, sur la surface définie par dancefloorArea (400px par défaut). Chacun de ces déplacements sera déclenché selon l’intervalle définie par tempo (300 millisecondes par défaut).

Nous allons définir une nouvelle fonction (tirée de la documentation Mozilla), permettant d’obtenir un nombre entier situé entre les deux passés en paramètres.

Nous allons également définir les variables minPosition et maxPosition d’après params.dancefloorArea

(function($){
	$.fn.dance = function(params){

		// Paramètres
		var params = $.extend({
			tempo: 300,
			dancefloorArea: 400
		},params);

		// Renvoie un entier situé entre min et max
		function getRandomInt(min, max){
		  return Math.floor(Math.random() * (max - min + 1)) + min;
		};

		// Positions minimales et maximales
		// que pourra prendre un élément
		var minPosition = -(params.dancefloorArea/2);
		var maxPosition = params.dancefloorArea/2;

		// Mouvement d'un élément
		function move(jElt){
			var topPos = getRandomInt(minPosition, maxPosition);
			var leftPos = getRandomInt(minPosition, maxPosition);
		};

		return this.each(function(){
			move( $(this) );
		});
	};
})(jQuery)

Pour chaque élément, une position sera définie à l’aide des variables leftPos et topPos.

Il nous reste donc à animer notre élément vers cette position pendant le temps défini par tempo, puis à appeler cette fonction, encore et encore, jusqu’au bout de la nuit. Nous utiliserons la méthode animate() de jQuery. Les éléments seront également positionnés en relatif pour être déplacés par rapport à leur position, sans gêner les voisins parce que bon, ils n’ont rien demandé eux.

(function($){
	$.fn.dance = function(params){

		// Paramètres
		var params = $.extend({
			tempo: 300,
			dancefloorArea: 400
		},params);

		// Renvoie un entier situé entre min et max
		function getRandomInt(min, max){
		  return Math.floor(Math.random() * (max - min + 1)) + min;
		};

		// Positions minimales et maximales
		// que pourra prendre un élément
		var minPosition = -(params.dancefloorArea/2);
		var maxPosition = params.dancefloorArea/2;

		// Mouvement d'un élément
		function move(jElt){
			var topPos = getRandomInt(minPosition, maxPosition);
			var leftPos = getRandomInt(minPosition, maxPosition);

			// Préfixer une variable par la lettre j
			// (ou ce qui vous semblera pertinent)
			// permet d'identifier facilement un objet jQuery.
			jElt.animate(

				// Premier paramètre : les nouvelles propriétés CSS
				// vers lesquelles l'élément va être animé.
				{
					top: topPos + "px",
					left: leftPos + "px"
				},

				// Deuxième paramètre : le temps que durera l'animation
				params.tempo,

				// Troisième paramètre, la fonction qui sera appelée
				// lorsque l'animation sera terminée.
				function(){
					move(jElt); // Nous appelons à nouveau la fonction move()
				}
			);
		};

		return this.css("position", "relative").each(function(){
			move( $(this) );
		});
	};
})(jQuery)

Vous trouverez une démonstration de notre plugin à cette adresse : httpswww.lesintegristes.net/demos/jquery/dance.html

Je dois avouer, et vous le reconnaîtrez sûrement, que le résultat est affligeant. Mais bon, hein.