Bien débuter avec la conception de plugins jQuery

L'un des sujets récurents de ce blog est la création de plugins jQuery. Ces plugins sont toujours construit selon le même principe. Je ne peux malheureusement pas répéter les mêmes explications à longueur d'articles pour ne pas les rendre encore plus longs et répétitifs. Pourtant, je ne peux pas non plus aborder la conception d'un plugin sans en développer les bases.

Cet article aborde, une bonne fois pour toutes, le B-A BA du développement orienté jQuery.

Un plugin jQuery c'est quoi ?

Les plugins jQuery permettent d'agencer le code afin qu'il soit rapidement et facilement réutilisé.
Je n'apprends rien à personne, un plugin s'applique aux éléments d'une page comme ceci :

$('div, #id, .class').myPlugin();

Le plugin myPlugin() s'appliquera à tous les éléments précisés par le sélecteur, ici les div, l'élement portant l'identifiant id ou la classe .class. La librairie jQuery s'étend facilement et un plugin se créé simplement comme ceci pour les méthodes applicables à des éléments en particulier.

$.fn.myPlugin = function() {}

Ou sous forme de fonctions d'utilisation plus globale.

$.myFunction = function() {}

Compatibilité

Attention au conflit, d'autres librairies telle que Prototype ou Mootools utilisent également le $ comme nom de fonction. $ n'est qu'un alias de l'objet jQuery. Pour éviter tout conflit, il faudrait utiliser la forme suivante dénuée du fameux $.

jQuery.fn.myPlugin = function() {}

Il est franchement dommage de ne pas pouvoir profiter de l'alias tout au long du développement de notre plugin. Heureusement, le plugin peut s'encapsuler dans une fonction anonyme à laquelle on passe l'objet jQuery qu'on récupère sous la forme $.

(function($){
    $.fn.myPlugin = function() {}
})(jQuery);

Chaînabilité

Le ou les éléments sur lesquels le plugin est appliqué sont passés en tant que contexte. this sera donc une référence à l'objet jQuery appliqué aux éléments en question. Il est maintenant facile d'interagir avec eux. Ici chaque élément verra son background devenir rouge.

(function($){
    $.fn.myPlugin = function() {  
        this.css('background', 'red');  
    }
})(jQuery);

L'une des forces de jQuery est sa chaînabilité (Expliqué ici pour PHP). Elle permet de placer les méthodes les unes à la suites des autres, comme par exemple $('div').find('.class').show(). Pour se faire le plugin doit retourner l'objet jQuery lorsque cela est possible. Modifions notre petit plugin et ajoutons un return qui reverra l'élément traité par jQuery.

(function($){
    $.fn.myPlugin = function() {  
        return this.css('background', 'red');  
    }
})(jQuery);

Notre plugin fonctionne déjà. Pour un résultat un peu plus élaboré, il est obligatoire d'itérer les éléments pour agir individuellement dessus. jQuery propose la fonction each() qui passe en revue les éléments afin d'y appliquer une fonction.

(function($){
    $.fn.myPlugin = function() {
        return this.each(function() {
            $(this).css('color', 'white')
                   .css('background', 'red');
            alert('Couleurs appliquées');
        });
    };
})(jQuery);

Ici, la fonction each() retourne chaque élément brut trouvé et non l'objet jQuery comme précédement. C'est pour ça que $(this) est utilisé à la place d'un simple this.

Configuration

Un bon plugin est un plugin flexible et modulable. L'utilisateur doit avoir la possibilité de configurer quelques options. Il est très courant de passer un objet littérale plutôt qu'une séries de paramètres.

$('div, #id, .class').myPlugin({
    color:'gray',
    background:'black'
});

Le plugin doit également pouvoir s'utiliser simplement sans aucune configuration. Il faut prévoir des valeurs par défaut que l'utilisateur pourra écraser le cas échéant.

(function($){
    $.fn.myPlugin = function(options) {
        var defaults = {
            color: 'white',
            background: 'red'
        }
        var options = $.extend(defaults, options);

        return this.each(function() {
           $(this).css({
                color: options.color,
                background: options.background
            });
        });
    };
})(jQuery);

Les paramètres de l'utilisateur sont ajoutés aux valeurs par défaut par $.extend(). Les paramètres sont disponibles tout au long de notre plugin par la variable options. Une alternative intéressante est d'externaliser des valeurs par défaut.

(function($){
    $.myPlugin = {
        defaults: {
            color: 'white',
            background: 'red'
        }
    }
    
    $.fn.myPlugin = function(options) {
        var options = $.extend({}, $.myPlugin.defaults, options);

        return this.each(function() {
            $(this).css({
                color: options.color,
                background: options.background
            });
        });
    };    
})(jQuery);  

Cela permettra à l'utilisateur de paramétrer les valeurs de plusieurs instances en une seule fois.

$.myPlugin.defaults.color = 'yellow';

$('div').myPlugin();
$('.class').myPlugin({ background: 'blue' });

Fonctionnalités

Pour ne pas s'emmêler les pinceaux au sein des différentes méthodes utilisées, il est préférable de rentre global l'élément principale en court. J'ai pour habitude de prendre le raccourci $$ pour faire référence à l'objet courant : var $$ = $(this);.

Rendons l'exemple un peu plus concret. Ainsi, notre plugin colorera le fond des éléments survolés pour les remettre finalement dans leur état d'origine.

(function($){
    $.fn.myPlugin = function(options) {
        var defaults = {
            color: 'white',
            background: 'red'
        }
        var options = $.extend(defaults, options);

        return this.each(function() {
            var $$ = $(this);
            var original = {
                background: $$.css('backgroundColor'),
                color: $$.css('color')
            }

            $$.hover(function() {
                $$.css({
                    color: options.color,
                    background: options.background
                });
            }, function() {
                $$.css({
                    color: original.color,
                    background: original.background
                });
            });
        });
    };
})(jQuery);

Ensuite, tout est question d'organisation. Ajoutez autant de méthodes que vous souhaitez.

(function($){
    $.fn.myPlugin = function(options) {
        var defaults = {
            color: 'white',
            background: 'red'
        }
        var options = $.extend(defaults, options);

        return this.each(function() {
            var $$ = $(this);
            var original = {
                background: $$.css('backgroundColor'),
                color: $$.css('color')
            }

            $$.hover(function() {
                on();
            }, function() {
                off();
            });
			
            var on = function() {
                $$.css({
                    color: options.color,
                    background: options.background
                });
            };
			
            var off = function() {
                $$.css({
                    color: original.color,
                    background: original.background
                });
            };
        });
    };
})(jQuery);

Quelques conseils

Quelques règles sont à suivre pour la diffusion de votre plugin. Il est d'usage que le fichier se nomme ainsi : jquery.myplugin.js. Il est aussi possible d'en proposer une version compressée, avec packer par exemple. Dans ce cas le fichier pourra se nommer jquery.myplugin.pack.js. Veillez à bien formater votre code et de terminer vos fonctions par un point-virgule (;). Sinon la compression échouera.

Conclusion

Ca y est, je me suis enfin acquitté d'une explication détaillée sur le sujet. J'espère qu'elle éclairera les moins aguerris. Un lien vers cette page sera ajouté à chaque futur tutoriel sur la conception de plugin.

Vous n'être maintenant plus un débutant. Si vous souhaitez vous attaquer à quelque chose de plus consistant, ou tout simplement trouver l'inspiration, je vous conseille les articles suivant sur la création de plugin de :

• Sélection de couleurs
• Détection/indication d'activation de la touche CapsLock
• Traduction de contenu in-line en ajax
• Un Traduction de mots en ajax
• Tracking de clics d'utilisateurs
• Affichage d'infobulles

Ou une liste plus à jour ici.