jQuery.info
Découvrir et utiliser jQuery, la librairie javascript du XXIIème siècle

Accueil du site > Débuter > Comment développer un plugin jQuery

Comment développer un plugin jQuery

mercredi 12 août 2009, par Craig Buckler, XF75013

Traduction d’un article de Craig Buckler sur SitePoint


jQuery est la plus populaire des bibliothèques JavaScript, de nombreux sites l’ont adopté pour ses effets dynamiques et ses fonctions AJAX [NdT : Microsoft et Nokia l’ont intégré à leurs outils de développement]. Toutefois, relativement peu de développeurs poussent jusqu’à développer des plug-ins.

Dans ce tutoriel, nous allons découvrir les bases de la création de plug-in à l’aide d’un exemple simple. Notre code aura pour effet d’intervertir les lettres dans un ou plusieurs nœuds (éléments) choisis - page de démonstration.

Pourquoi créer un plug-in jQuery ?

En un mot : la réutilisation. En étendant jQuery, vous créez des composants réutilisables qui peuvent être mis en œuvre sur n’importe quelle page web. Votre code est encapsulé et il y a ainsi moins de risques que vous utilisiez par ailleurs le même nom de fonction [NdT : la nouvelle fonction remplacerait alors l’ancienne].

Comment jQuery fonctionne

À la base, jQuery manipule des éléments du DOM ou une chaine définie par un sélecteur CSS. Il retourne un objet jQuery, qui est un tableau de type liste de nœuds DOM. Une ou plusieurs méthodes peuvent être chaînées (appliquées successivement) à ce groupe de nœuds, par exemple :

// Colore tous les tags <p> en rouge
$("p").css("color", "red");

Remarque  : bien que la bibliothèque de jQuery se nomme « jQuery », « $ » est le raccourci qui fait référence à cette variable. Soyez conscient que d’autres bibliothèques peuvent utiliser « $ » pour leur propre usage.

Comment fonctionne les plug-ins jQuery

jQuery autorise l’ajout de méthodes à sa bibliothèque. Lorsqu’elles sont appelées, ces méthodes reçoivent l’objet jQuery sans utiliser l’objet JavaScript « this ». Les nœuds DOM peuvent être manipulés selon les besoins et la méthode retourne en général « this » afin que d’autres fonctions puissent être chainées.

Notre plug-in exemple sera exécuté grâce à ce code :

// Inverse le texte dans tous les tags <p>
$("p").reverseText();

Nous allons aussi ajouter deux paramètres facultatifs, minlength et maxlength. Quand ils sont définis, la longueur de la chaine doit se situer entre ces limites pour que l’interversion se fasse.

Déclarer le plug-in

Les plug-ins sont définis en utilisant la fonction jQuery fn, par exemple :

jQuery.fn.reverseText = function(params) { ... };

L’utilisation de « jQuery » plutôt que « $ » assure il n’y aura pas de conflits avec d’autres bibliothèques JavaScript. Tout notre code interne doit également se référer à « jQuery » plutôt que « $ ». Cependant, nous pouvons limiter un peu la frappe et réduire la taille du fichier en utilisant une fonction anonyme :

(function($) {
        $.fn.reverseText = function(params) { ... };
})(jQuery);

Cette fonction s’exécute immédiatement et jQuery lui est passé comme un paramètre nommé « $ ». Ensuite « $ » est une variable locale, nous pouvons supposer qu’il se réfère toujours à la bibliothèque de jQuery plutôt que d’une autre bibliothèque qui aurai utilisé la variable globale « $ » en premier.

paramètres du plug-in

Nous avons besoin de deux paramètres pour notre plug-in : minlength et maxlength. Il est plus facile de les définir comme arguments de ces fonctions, par exemple :

(function($) {
        $.fn.reverseText = function(minlength, maxlength) { ... };
})(jQuery);
// example
$("p").reverseText(0, 100);

Mais si nous décidons d’ajouter d’autres paramètres plus tard ? Notre plug-in pourrait avoir des dizaines d’options — la gestion des paramètres devient rapidement compliquée.

Comme alternative, nous pouvons passer un seul objet JSON, par exemple :

(function($) {
        $.fn.reverseText = function(params) { ... }
})(jQuery);
// exemple
$("p").reverseText( { minlength: 0, maxlength: 100 } );

La première ligne de notre fonction reverseText devrait définir un ensemble de paramètres par défaut puis remplacer ceux-ci avec n’importe quelles valeurs définies par l’utilisateur.

La fonction extend de jQuery peut réaliser cela pour nous :

// Fusionner les paramètres par défaut et ceux de l'utilisateur
params = $.extend( {minlength: 0, maxlength: 99999}, params);

Ainsi, la valeur de params.minlength est de 0 et la valeur de params.maxlength est de 99999 sauf si le code appelant remplace ces valeurs.

Le code du plug-in

Nous pouvons maintenant écrire le code principal de notre plug-in :

// Traverser tous les nœuds.
this.each(function() {

        // Exprimer un nœud seul en objet jQuery
        var $t = $(this);

        // récupérer le texte
        var origText = $t.text(), newText = '';

        // Est-ce que la longueur du texte est dans les limites définies ?
        if (origText.length >= params.minlength &&  origText.length <= params.maxlength) {
                // Inverser le texte
                for (var i = origText.length-1; i >= 0; i--) newText += origText.substr(i, 1);
                        $t.text(newText);
        }
});

Explications :

  1. La fonction this.each explore l’ensemble des nœuds DOM de l’objet jQuery et appelle une fonction anonyme.
  2. Au sein de la fonction, « this » contient un seul nœud. Un nœud de collecte jQuery est assigné à « $ » pour que les méthodes jQuery fonctionnent.
  3. La variable origText est affectée à la chaine de caractères du nœud DOM. newText est initialisé en une chaine de caractères vide.
  4. Si la longueur de origText se situe entre params.minlength et params.maxlength, la boucle crée une chaine de caractères inversé dans la variable newText. Le nœud DOM est ensuite mis à jour en conséquence.

Ne brisez pas la chaine !

Enfin, nous devons nous souvenir de retourner l’objet jQuery pour que d’autres méthodes puissent être chainées :

return this;

Le code terminé

Le code de notre plug-in est maintenant terminé :

(function($) {
        // définition du plugin jQuery
        $.fn.reverseText = function(params) {
                // Fusionner les paramètres par défaut et ceux de l'utilisateur
                params = $.extend( {minlength: 0, maxlength: 99999}, params);
                // Traverser tous les nœuds.
                this.each(function() {
                        // Exprimer un nœud seul en objet jQuery
                        var $t = $(this);
                        // récupérer le texte
                        var origText = $t.text(), newText = '';
                        // Est-ce que la longueur du texte est dans les limites définies ?
                        if (origText.length >= params.minlength &&  origText.length <= params.maxlength) {
                                // Inverser le texte
                                for (var i = origText.length-1; i >= 0; i--) newText += origText.substr(i, 1);
                                        $t.text(newText);
                        }
                });
        // Permettre le chaînage par jQuery
        return this;
        };
})(jQuery);

Ce fichier est enregistré sous le nom de jquery.reversetext.js. On peut alors l’inclure dans toute page HTML après avoir chargé la bibliothèque jQuery, par exemple :

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
        <title>plugin jQuery : démonstration de reverseText </title>
</head>
<body>
        <h1>plugin jQuery : reverseText</h1>
        <p>Ce plugin jQuery inverse tout le texte dans les nœuds sélectionnés.</p>
        <ul>
                <li>Ce texte va être inversé</li>
                <li>Ce texte ne sera pas inversé</li>
                <li>Inversé</li>
                <li>Pas inversé</li>
        </ul>
<script type="text/javascript" src="jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="jquery.reversetext.js"></script>
<script type="text/javascript"> // Inverse le texte des tags <li> pairs
        $("ul li:even").reverseText();
</script>
</body>
</html>

La liste dans cette page a maintenant le texte inversé sur le premier et troisième élément (rappelez-vous, le premier élément est numéroté de 0) :

PNG - 1.1 ko

Ressources :

Vous devriez maintenant avoir une bonne base pour le développement de plug-ins jQuery. Le forum javascript de Sitepoint est aussi une excellente source pour obtenir de l’aide et des conseils.

Prochainement : un nouveau tutoriel en trois parties décrivant comment construire un composant de page en plug-in jQuery. [NdT : Nous verrons si cet article aussi vaudra d’être traduit et si nous en avons l’autorisation]

Répondre à cet article


Derniers commentaires

Nouveautés sur le Web