jQuery UI Comment utiliser la fabrique de widgets

Nous allons créer une barre de progression. Comme le montre l'exemple ci-dessous, cela peut être fait en appelantjQuery.widget()pour y parvenir, qui prend deux paramètres : l'un est le nom du plugin à créer, et l'autre est un littéral d'objet contenant les fonctions qui prennent en charge le plugin. Lorsque le plugin est invoqué, il crée une nouvelle instance de plugin, et toutes les fonctions seront exécutées dans le contexte de cette instance. Cela diffère des plugins jQuery standard de deux manières importantes. Premièrement, le contexte est un objet, pas un élément DOM. Deuxièmement, le contexte est toujours un objet unique, pas une collection.

$.widget( "custom.progressbar", {
    _create: function() {
        var progress = this.options.value + "%";
        this.element
            .addClass( "progressbar" )
            .text( progress );
    }
});

Le nom du plugin doit contenir un espace de noms. Dans cet exemple, nous utilisons l'customespace de noms. Vous ne pouvez créer un espace de noms que sur un seul niveau, donccustom.progressbarest un nom de plugin valide, tandis quevery.custom.progressbarn'est pas un nom de plugin valide.

Nous pouvons voir que la Widget Factory nous fournit deux propriétés.this.elementest un objet jQuery contenant un élément. Si notre plugin est appelé sur un objet jQuery contenant plusieurs éléments, une instance de plugin distincte sera créée pour chaque élément, et chaque instance aura son proprethis.element. La deuxième propriété,this.options, est un hachage de paires clé/valeur contenant toutes les options du plugin. Ces options peuvent être passées au plugin comme suit :

$( "<div></div>" )
    .appendTo( "body" )
    .progressbar({ value: 20 });

Lorsque nous appelonsjQuery.widget(), il étend jQuery en ajoutant des fonctions àjQuery.fn(le système utilisé pour créer des plugins standard). Les noms des fonctions ajoutées sont basés sur le nom que vous passez àjQuery.widget()sans l'espace de noms - "progressbar". Les options passées au plugin sont les valeurs définies sur l'instance du plugin. Comme montré dans l'exemple ci-dessous, nous pouvons spécifier des valeurs par défaut pour n'importe quelle option. Lors de la conception de votre API, vous devez bien comprendre les cas d'utilisation les plus courants de votre plugin afin de pouvoir définir des valeurs par défaut appropriées et vous assurer que toutes les options sont réellement facultatives.

$.widget( "custom.progressbar", {
 
    // Default options.
    options: {
        value: 0
    },
    _create: function() {
        var progress = this.options.value + "%";
        this.element
            .addClass( "progressbar" )
            .text( progress );
    }
});

Appeler des méthodes

Maintenant que nous pouvons initialiser notre barre de progression, nous allons effectuer des actions en appelant des méthodes sur l'instance du plugin. Pour définir une méthode de plugin, nous référençons simplement une fonction dans l'objet que nous passons àjQuery.widget()l'objet. Nous pouvons également définir des méthodes « privées » en préfixant le nom de la fonction par un underscore.

$.widget( "custom.progressbar", {
 
    options: {
        value: 0
    },
 
    _create: function() {
        var progress = this.options.value + "%";
        this.element
            .addClass( "progressbar" )
            .text( progress );
    },
 
    // Create a public method.
    value: function( value ) {
 
        // No value passed, act as a getter.
        if ( value === undefined ) {
            return this.options.value;
        }
 
        // Value passed, act as a setter.
        this.options.value = this._constrain( value );
        var progress = this.options.value + "%";
        this.element.text( progress );
    },
 
    // Create a private method.
    _constrain: function( value ) {
        if ( value > 100 ) {
            value = 100;
        }
        if ( value < 0 ) {
            value = 0;
        }
        return value;
    }
});

Pour appeler une méthode sur l'instance du plugin, vous pouvez passer le nom de la méthode au plugin jQuery. Si la méthode que vous appelez accepte des paramètres, vous passez simplement ces paramètres après le nom de la méthode.

Remarque :Les méthodes sont exécutées en passant le nom de la méthode à la même fonction jQuery que celle utilisée pour initialiser le plugin. Cela permet d'éviter de polluer l'espace de noms jQuery tout en préservant le chaînage des méthodes. Plus loin dans ce chapitre, nous verrons d'autres utilisations qui semblent plus naturelles.

var bar = $( "<div></div>" )
    .appendTo( "body" )
    .progressbar({ value: 20 });
 
// Get the current value.
alert( bar.progressbar( "value" ) );
 
// Update the value.
bar.progressbar( "value", 50 );
 
// Get the current value again.
alert( bar.progressbar( "value" ) );

Utilisation des options

option()La méthode est automatiquement fournie au plugin.option()La méthode vous permet d'obtenir et de définir des options après l'initialisation. Cette méthode fonctionne comme la.css()et.attr()méthode : vous pouvez passer uniquement un nom pour l'utiliser comme getter, passer un nom et une valeur pour l'utiliser comme setter, ou passer un hash de paires clé/valeur pour définir plusieurs valeurs. Lorsqu'elle est utilisée comme getter, le plugin retourne la valeur actuelle de l'option correspondant au nom passé. Lorsqu'elle est utilisée comme setter, la_setOptionméthode sera appelée pour chaque option qui est définie. Nous pouvons spécifier une_setOptionméthode dans notre plugin pour réagir aux changements d'option. Pour les actions qui doivent être effectuées indépendamment lorsqu'une option change, nous pouvons surcharger_setOptions。

$.widget( "custom.progressbar", {
    options: {
        value: 0
    },
    _create: function() {
        this.options.value = this._constrain(this.options.value);
        this.element.addClass( "progressbar" );
        this.refresh();
    },
    _setOption: function( key, value ) {
        if ( key === "value" ) {
            value = this._constrain( value );
        }
        this._super( key, value );
    },
    _setOptions: function( options ) {
        this._super( options );
        this.refresh();
    },
    refresh: function() {
        var progress = this.options.value + "%";
        this.element.text( progress );
    },
    _constrain: function( value ) {
        if ( value > 100 ) {
            value = 100;
        }
        if ( value < 0 ) {
            value = 0;
        }
        return value;
    }
});

Ajout de callbacks

La façon la plus simple d'étendre un plugin est d'ajouter des callbacks afin que les utilisateurs puissent réagir lorsque l'état du plugin change. Nous pouvons voir dans l'exemple ci-dessous comment ajouter un callback à la barre de progression lorsque la progression atteint 100%._trigger()La méthode prend trois paramètres : le nom du callback, un objet événement jQuery qui déclenche le callback, et un hash de données lié à l'événement. Le nom du callback est le seul paramètre obligatoire, mais les autres paramètres sont très utiles pour les utilisateurs qui souhaitent implémenter des fonctionnalités personnalisées dans le plugin. Par exemple, si nous créons un plugin déplaçable, nous pouvons transmettre l'événement mousemove lors du déclenchement du callback de glissement, ce qui permettra aux utilisateurs de réagir au glissement en fonction des coordonnées x/y fournies par l'objet événement. Notez que l'événement transmis à_trigger()doit être un événement jQuery, et non un événement natif du navigateur.

$.widget( "custom.progressbar", {
    options: {
        value: 0
    },
    _create: function() {
        this.options.value = this._constrain(this.options.value);
        this.element.addClass( "progressbar" );
        this.refresh();
    },
    _setOption: function( key, value ) {
        if ( key === "value" ) {
            value = this._constrain( value );
        }
        this._super( key, value );
    },
    _setOptions: function( options ) {
        this._super( options );
        this.refresh();
    },
    refresh: function() {
        var progress = this.options.value + "%";
        this.element.text( progress );
        if ( this.options.value == 100 ) {
            this._trigger( "complete", null, { value: 100 } );
        }
    },
    _constrain: function( value ) {
        if ( value > 100 ) {
            value = 100;
        }
        if ( value < 0 ) {
            value = 0;
        }
        return value;
    }
});

Les callbacks ne sont essentiellement que des options supplémentaires, vous pouvez donc les obtenir et les définir comme n'importe quelle autre option. Chaque fois qu'un callback est exécuté, un événement correspondant est déclenché. Le type d'événement est déterminé en concaténant le nom du plugin et le nom du callback. Les callbacks et les événements acceptent tous deux les deux mêmes paramètres : un objet événement et un hash de données lié à l'événement, comme illustré dans l'exemple ci-dessous.

Votre plugin peut avoir besoin d'inclure des fonctionnalités qui empêchent les utilisateurs de l'utiliser. Pour ce faire, la meilleure façon est de créer un callback annulable. Les utilisateurs peuvent annuler le callback ou l'événement associé, comme ils annuleraient n'importe quel événement natif, en appelantevent.preventDefault()ou en renvoyantfalsepour ce faire. Si l'utilisateur annule le callback, la_trigger()méthode renverrafalse, afin que vous puissiez implémenter la fonctionnalité appropriée au sein du plugin.

var bar = $( "<div></div>" )
    .appendTo( "body" )
    .progressbar({
        complete: function( event, data ) {
            alert( "Callbacks are great!" );
        }
    })
    .bind( "progressbarcomplete", function( event, data ) {
        alert( "Events bubble and support many handlers for extreme flexibility." );
        alert( "The progress bar value is " + data.value );
    });
 
bar.progressbar( "option", "value", 100 );

Sous le capot

Maintenant que nous avons vu comment utiliser la Widget Factory pour créer un plugin, regardons comment elle fonctionne réellement. Lorsque vous appelezjQuery.widget(), cela créera une fonction constructeur pour le plugin et définira l'objet que vous avez passé comme prototype pour les instances du plugin. Toutes les fonctionnalités automatiquement ajoutées au plugin proviennent d'un prototype de widget de base, qui est défini commejQuery.Widget.prototype. Lors de la création d'une instance de plugin, utilisezjQuery.datapour le stocker sur l'élément DOM d'origine, avec le nom du plugin comme clé.

Comme l'instance du plugin est directement liée à l'élément DOM, vous pouvez accéder directement à l'instance du plugin sans passer par les méthodes du plugin. Cela vous permet d'appeler directement des méthodes sur l'instance du plugin sans passer le nom de la méthode sous forme de chaîne, et vous pouvez également accéder directement aux propriétés du plugin.

var bar = $( "<div></div>" )
    .appendTo( "body" )
    .progressbar()
    .data( "progressbar" );
 
// Call a method directly on the plugin instance.
bar.option( "value", 50 );
 
// Access properties on the plugin instance.
alert( bar.options.value );

Vous pouvez également créer une instance sans passer par les méthodes du plugin, en appelant directement le constructeur avec les options et l'élément :

var bar = $.custom.progressbar( {}, $( "<div></div>" ).appendTo( "body") );
 
// Same result as before.
alert( bar.options.value );

Extension du prototype du plugin

Le plus grand avantage d'un plugin ayant un constructeur et un prototype est qu'il est facile d'étendre le plugin. En ajoutant ou modifiant des méthodes sur le prototype du plugin, nous pouvons modifier le comportement de toutes les instances du plugin. Par exemple, si nous voulons ajouter une méthode à la barre de progression pour réinitialiser la progression à 0%, nous pouvons ajouter cette méthode au prototype, et elle sera appelable sur toutes les instances du plugin.

$.custom.progressbar.prototype.reset = function() {
    this._setOption( "value", 0 );
};

Pour plus de détails sur l'extension des widgets, et sur la façon de créer un tout nouveau widget au-dessus d'un widget existant, voirExtension des widgets avec la Widget Factory。

Nettoyage

Dans certains cas, il est utile de permettre aux utilisateurs d'appliquer un plugin puis de le désappliquer. Vous pouvez le faire via la_destroy()méthode. Dans la_destroy()méthode, vous devez annuler tout ce que le plugin a fait lors de l'initialisation et de l'utilisation ultérieure._destroy()est appelé via la.destroy(). La.destroy()est automatiquement appelée lorsque l'élément lié à l'instance du plugin est supprimé du DOM, donc cela peut être utilisé pour le ramasse-miettes. La base.destroy()méthode gère également certaines opérations de nettoyage courantes, comme la suppression de la référence à l'instance de l'élément DOM du widget, la dissociation de tous les événements de l'espace de noms du widget de l'élément, et la dissociation de tous les événements ajoutés avec_bind()événements ajoutés.

$.widget( "custom.progressbar", {
    options: {
        value: 0
    },
    _create: function() {
        this.options.value = this._constrain(this.options.value);
        this.element.addClass( "progressbar" );
        this.refresh();
    },
    _setOption: function( key, value ) {
        if ( key === "value" ) {
            value = this._constrain( value );
        }
        this._super( key, value );
    },
    _setOptions: function( options ) {
        this._super( options );
        this.refresh();
    },
    refresh: function() {
        var progress = this.options.value + "%";
        this.element.text( progress );
        if ( this.options.value == 100 ) {
            this._trigger( "complete", null, { value: 100 } );
        }
    },
    _constrain: function( value ) {
        if ( value > 100 ) {
            value = 100;
        }
        if ( value < 0 ) {
            value = 0;
        }
        return value;
    },
    _destroy: function() {
        this.element
            .removeClass( "progressbar" )
            .text( "" );
    }
});

Remarques finales

La Widget Factory n'est qu'une façon de créer des plugins avec état. Il existe plusieurs autres modèles différents que vous pouvez utiliser, chacun avec ses propres avantages et inconvénients. La Widget Factory résout de nombreux problèmes courants et améliore grandement l'efficacité, tout en améliorant grandement la réutilisation du code, ce qui la rend adaptée à jQuery UI et à d'autres plugins avec état.

Veuillez noter que dans ce chapitre nous avons utilisé lecustomnamespace. Leuinamespace est réservé aux plugins officiels de jQuery UI. Lorsque vous créez vos propres plugins, vous devez créer votre propre namespace. Cela indique plus clairement d'où vient le plugin et à quelle portée il appartient.

Autres extensions