Creare un plugin per jQuery

Dopo aver analizzato 3 dei principali plugin per JQuery inseriti nel repository ufficiale, nell'articolo precedente, possiamo iniziare a realizzarne uno tutto nostro.

Il plugin che scriveremo introdurrà come al solito il maggior numero di aspetti di JQuery, comprendendo l'argomento in maniera quasi totale. Realizzeremo uno script che permetterà di creare una mini interfaccia per sondaggi a partire da una semplice lista HTML. Oltre alla manipolazione dell'HTML vedremo alcuni aspetti basati sulla gestione degli eventi "interni" al plugin, alla scrittura/lettura di cookie e all'invio dei dati sul server in maniera asincrona tramite AJAX.

Per aggiungere funzionalità al framework basterà aggiungere una funzione all'oggetto jQuery.fn tramite un costrutto di questo tipo:

jQuery.fn.myPlugin = function() {
  return this.each(function(){
    //logica implementativa del plugin
  });
};

Ovviamente il nome myPlugin rispecchierà il nome scelto per il plugin e l'iterazione this.each ci permette di implementare la logica non solo su un singolo elemento ma su un vettore
di elementi HTML. Sarà possibile invocare il plugin in questo modo:

// in questo caso eseguiremo la logica
// applicativa su tutti i div della pagina
$("div").myPlugin(); 
// in questo caso eseguiremo la logica applicativa
// solo su un div particolare
$("div#id-del-div").myPlugin();

Abbiamo quindi le basi per iniziare a realizzare il nostro plugin! Ecco la versione finale dello stesso.

Per la realizzazione ho utilizzato un ulteriore plugin di terze parti per l'accesso (sia in lettura che in scrittura) ai cookie. Il suo utilizzo è banale e ricalca la funzione setcookie utilizzata nel PHP.

Rispetto al solito adotteremo un approccio opposto: introdurremo subito tutto il codice completo del plugin e lo analizzeremo passo passo successivamente. Questo perchè il codice è relativamente breve e non presenta ostacoli di comprensione:

jQuery.fn.poll = function(o) {
  o = jQuery.extend({
    buttonText: "Invia",
    buttonDisabledText: "Già votato",
    optionalParams: {},
    radioName: Math.random(),
    errorMessage: "Si è verificato un errore",
    confirmMessage: "Grazie per aver votato",
    cookieName: "JQueryPoll",
    url: "#",
    cssClassName: "ul_poll"
  }, o);
  var buttonClickCallback = function() {
      var ul = $(this).prev();
      var els = ul.find("li input[@type=radio][@checked]");
      if (els.length == 1) sendData(els.val())
      else alert(o.errorMessage);
  };
  var sendData = function(answerIndex) {
    var data = o.optionalParams;
    data.answerIndex = answerIndex;
    $.post(o.url, data, sendDataCallback);
  };
  var sendDataCallback = function(response,success) {
    if(success != "success") alert(o.errorMessage);
    else {
      alert(o.confirmMessage);
      $.cookie(o.cookieName, true);
      button.text(o.buttonDisabledText);
      button.attr("disabled", "true");
    }
  };
  var buttonText = !$.cookie(o.cookieName) ? o.buttonText : o.buttonDisabledText;
  var button = $("<button>"+buttonText+"</button>");
  if($.cookie(o.cookieName)) button.attr("disabled", "true");
  button.click(buttonClickCallback);
  return this.each(function() {
    var el = $(this);
    el.addClass(o.cssClassName);
    var els = el.children("li");
    $.each(els, function(i,n) {
      $(n).prepend("<input type='radio' value='"+i+"' name='poll_"+o.radioName+"'/>");
    });
    el.after(button);
  });
}

Il codice del plugin è suddiviso in tre parti: innanzitutto definiamo alcune variabili di default, che potranno però essere modificate dall'utente tramite un oggetto di configurazione passato all'invocazione del metodo poll. Le variabili sono:

Variabile	Descrizione
buttonText	il testo da mostrare sul pulsante di submit
buttonDisabledText	il testo da mostrare sul pulsante di submit in caso di sondaggio già votato
optionalParams	eventuali parametri secondari da inviare allo script server-side oltre alla risposta selezionata (per esempio un eventuale id) [il valore di default è un oggetto vuoto]
radioName	il nome da assegnare agli elementi radio button (necessario per rendere il form vincolato ad un'unica scelta) [di default si utilizza un numero casuale]
errorMessage e confirmMessage	messaggi da mostrare all'utente in caso di insuccesso e successo
cookieName	nome del cookie dove verrà salvato lo stato
url	url verso il quale effettuare la richiesta asincrona [di default è la pagina stessa]
cssClassName	classe CSS assegnata all'ul per migliorare l'aspetto estetico [di default è ul_poll, classe definita un file CSS esterno allegato al plugin]

Per l'assegnazione di queste variabili utilizziamo la comoda funzione di utilità esposta dal framework: estend.

La seconda parte del codice include le varie funzioni invocate dal plugin:

• buttonClickCallback: funzione scatenata dal click sul bottone che ottiene l'indice del radio button selezionato e passa il parametro alla funzione di invio dati (in caso di errori stampa l'errorMessage)
• sendData: funzione che si occupa di effettuare la connessione verso il server inviando come parametri l'indice della risposta selezionata e gli eventuali parametri aggiuntivi definiti in fase di inizializzazione del plugin
• sendDataCallback: funzione callback della richiesta AJAX che stampa un messaggio per informare l'utente ed in caso di successo imposta il cookie e modifica lo stato del bottone

La terza ed ultima parte si occupa invece della creazione della parte HTML necessaria. Viene creato prima di tutto un bottone con uno stato che dipende dalla presenza o meno del cookie che segnala un preventivo invio dei dati. La definizione del bottone avviene al di fuori del return per il fatto che esso rappresenta un membro globale del plugin in quanto deve essere accessibile anche da altri metodi (sendDataCallback in primis).

Nel return invece viene modificata la struttura della pagina in quanto vengono inseriti dei radio button all'interno della lista e viene appeso alla fine di essa il bottone definito in precedenza.

Una volta definito il plugin basterà realizzare una pagina HTML di questo tipo:

<body>
  <ul>
    <li>Elemento 1.1</li>
    <li>Elemento 1.2</li>
    <li>Elemento 1.3</li>
    <li>Elemento 1.4</li>
  </ul>
</body>

ed invocare il plugin in questo modo:

$(document).ready(function() {
  $("ul").poll({
    optionalParams : {id:10}
  });
});