In questa guida cercheremo di guidare il lettore alla scoperta del progetto jQuery UI che raccoglie una serie di plugin per realizzare interfacce utente (UI sta per User Interface) usabili, dinamiche ed accattivanti grazie al supporto della libreria jQuery.
Per attivare le jQuery UI basta scaricare – dal sito ufficiale del progetto – il file dei plugin e del tema grafico che si desidera utilizzare. Come potete notare sul sito di jQuery UI è disponibile una funzionalità di download avanzata che consente di scegliere esattamente quali componenti scaricare. Inizialmente è consigliabile scaricare il pacchetto completo (per effettuare prove e test) ma in fase di produzione (cioè quando il sito verrà messo on-line) è preferibile effettuare una selezione dei soli plugin necessari al fine di alleggerire il peso della libreria.
Una volta scaricata la libreria sarà necessario includerla all’interno delle nostre pagine web:
<link type="text/css" href="css/themes/base/jquery.ui.all.css" rel="stylesheet" />
<script type="text/javascript" src="js/jquery-1.4.2.js"></script>
<script type="text/javascript" src="js/ui/jquery.ui.core.js"></script>
<script type="text/javascript" src="js/ui/jquery.ui.widget.js"></script>
<script type="text/javascript" src="js/ui/jquery.ui.mouse.js"></script>
<script type="text/javascript" src="js/ui/jquery.ui.draggable.js"></script>Come potete notare è necessario includere diversi file in quanto ci sono delle dipendenze da rispettare. Con la prima riga abbiamo inserito il tema, mentre con le altre abbiamo inserito (oltre a jQuery) il core e tutte le utility fondamentali al funzionamento delle UI. L’ultima riga, invece, inserisce il plugin desiderato, in questo caso "draggable".
Personalizzare la grafica
Sul sito di jQuery UI sono disponibili diversi temi grafici tra i quali è possibile scegliere quello che meglio si adatta al look and feel delle nostre pagine web. Al fine di adattare l’aspetto grafico delle UI alle nostre pagine web, inoltre, possiamo ricorrere allo strumento ThemeRoller: si tratta di un ottimo servizio, offerto dal sito ufficiale, grazie al quale è possibile modificare ogni singolo elemento del plugin, customizzandone l’aspetto agendo, ad esempio, sui colori e sul font.
Interazioni, Widget ed Effetti
I plugin forniti sono suddivisi, essenzialmente, in tre categorie principali:
- interazioni
- widget
- effetti
In questa guida ci soffermeremo sulle principali interazioni (draggable, droppable, resizable, selectable e sortable) e sui principali widget (accordion, autocomplete, datepicker, dialog e tabs) ed, infine, accenneremo alle migliorie introdotte per le animazioni mediante il metodo effect().
Sintassi
Nelle lezioni che seguiranno passeremo in rassegna, come detto, i principali plugin della raccolta jQuery UI. Al fine di non ripeterci in continuazione vedremo una sola volta, in questa lezione, gli aspetti generali relativi alla sintassi, in quanto comuni a tutti i plugin che andremo ad analizzare.
Per gli esempi di questa lezione faremo riferimento al plugin Draggable (che analizzeremo nella lezione successiva) ma la sintassi esposta può essere applicata anche agli altri plugin.
Dopo questa doverosa premessa possiamo passare al "succo" della lezione: la sintassi dei plugin.
Per prima cosa vediamo come inizializzare il plugin: per farlo non faccio altro che applicare il metodo relativo – in questo caso draggable() – ad un selettore:
$("#trascinami").draggable();Volendo è possibile personalizzare l’effetto prodotto passando al metodo una serie di parametri nella forma opzione:valore:
$("#trascinami").draggable({cursor: 'pointer'});Una volta che l’effetto è stato già inizializzato, invece, posso agire per ricavare il valore di un’opzione o per modificarlo attraverso il metodo "option". Vediamo separatamente le due circostanze:
// recupero il valore dell'opzione opacity
var opzione = $("#trascinami").draggable("option","opacity");// imposto un nuovo valore per opacity
$("#trascinami").draggable("option","opacity",0.40);Draggable (trascinare gli elementi)
Cominciamo con il parlare del plugin Draggable. Questo plugin permette di rendere un elemento draggabile, ovvero trascinabile, all’interno della nostra pagina: è una riproduzione dell’effetto che possiamo ottenere muovendo un file, ad esempio, all’interno nostro desktop spostandolo da una cartella all’altra.
Il plugin imposta due classi diverse a seconda dello stato in cui si trova l’elemento:
- viene impostata la classe ui-draggable a tutti gli elementi che sono potenzialmente "draggabili"
- durante il trascinamento viene aggiunta all’elemento la classe ui-draggable-dragging
Questa metodologia è utilizzata anche da altri plugin, per evidenziare i diversi stati in cui si trova l’elemento. Vediamo un esempio dell’uso di questo plugin:
<script type="text/javascript">
$(function() {
$("#trascinami").draggable();
});
</script>
<div id="trascinami">
<p>Prova a trascinarmi...</p>
</div>A questa pagina puoi vedere un esempio funzionante.
Il plugin è richiamabile mediante il metodo draggable() che, ovviamente, supporta diverse opzioni di personalizzazione che possono essere specificate, come abbiamo già detto alla precedente lezione, mediante la seguente sintassi:
$("#trascinami").draggable({opzione:valore});Vediamo alcuni delle opzioni del metodo draggable():
| Opzione | Tipo | Default | Descrizione |
| axis | stringa | false | Limita il drag solo orizzontalmente (‘x’) o verticalmente (‘y’). |
| containment | selettore, elemento, stringa, array | false | Delimita l’area entro il quale l’elemento può essere draggato. Possibili stringhe sono ‘document’, ‘parent’, ‘window’. |
| cursor | stringa | ‘auto’ | Serve per determinare l’aspetto del cursore del mouse durante l’effetto; si utilizzano le specifiche dei CSS per l’attributo cursor (ad es. pointer). |
| delay | intero | 0 | Tempo in millisecondi tra l’azione dell’utente (click e trascinamento) e lo scatenarsi dell’effetto. Serve per evitare drag accidentali. |
| disabled | booleano | false | Disabilita il plugin se impostato a true. |
| distance | intero | 1 | Indica la distanza minima (in pixel) del trascinamento prima che si scateni l’effetto. Anche questo serve a prevenire drag non voluti. |
| handle | elemento, selettore | false | Defisce un elemento che fungerà da "maniglia" per il trascinamento. L’effetto partirà quando l’utente cliccherà ed effettuerà il trascinamento di questo elemento. |
| helper | stringa, funzione | ‘original’ | Elemento da mostrare durante il drag. Strighe possibili: ‘original’ o ‘clone’. Se impostato su ‘clone’, ad esempio, verrà creato un clone dell’oggetto da trascinare e sarà spostato quest’ultimo invece dell’elemento originale fino al suo rilascio. Qui un esempio. |
| opacity | float | false | Imposta l’opacità dell’helper mentre è in movimento. Può essere utile, infatti, creare un effetto trasparenza sull’elemento in movimento. |
| revert | booleano, stringa | false | Se impostato a true, l’elemento ritorna nella posizione iniziale quando il drag è terminato. Possibili stringhe: ‘valid’ o ‘invalid’. Se impostato a ‘invalid’ il revert avviene solamente se il draggable non viene droppato da un elemento droppable. Per ‘valid’ è il contrario. |
Funzioni di callback
Oltre alle opzioni è possibile associare all’oggetto draggato delle funzioni di callback associate agli eventi generati dall’elemento: start, drag e stop, rispettivamente per segnalare l’inizio, il movimento e il termine dell’azione di drag. Vediamo un semplice esempio di utilizzo impostando, appunto, dei messaggi che evidenzino gli eventi generati:
$("#trascinami").draggable({
start: function() {
alert("Inizio...");
},
drag: function() {
alert("...mi stai trascinando...");
},
stop: function() {
alert("...sono fermo");
}
});Oltre alle opzioni ed alle funzioni di callback viste precedentemente, è possibile utilizzare dei metodi che modificano il comportamento del plugin. I metodi si utilizzano nel seguente modo:
$("#trascinami").draggable("nome_metodo"[,parametri]);Ecco un elenco dei metodi disponibili:
- .draggable("destroy"): rimuove le funzionalità del plugin facendo ritornare l’elemento al suo stato iniziale;
- .draggable("disable"): disabilita la possibilità di effettuare il drag;
- .draggable("enable"): abilita la possibilità di effettuare il drag;
- .draggable("option",nome_opzione,[valore]): metodo utilizzato per prelevare o settare un’opzione;
- .draggable("widget"): ritorna l’elemento con classe ui-draggable (ovvero draggabile);
Come potete notare solamente il metodo option ha dei parametri, ovvero il nome dell’opzione e l’eventuale valore in caso di operazione di set. I metodi, come vedremo, sono pressoché identici per quasi tutti i plugin in quanto le operazioni possibili sono sempre le stesse.
Droppable (gestire il rilascio degli elementi trascinati)
Il plugin Droppable permette di definire un target (destinazione) per un elemento draggable.
In altre parole definisce un elemento (il target, appunto) il quale si attiverà o compierà una data azione, solamente quando un’altro elemento (draggable) vi è trascinato sopra.
Come si può facilmente intuire, questo plugin è strettamente legato agli elementi draggabili visti nella lezione precedente.
Ecco un esempio:
<script type="text/javascript">
$(document).ready(function() {
$("#trascinami").draggable();
$("#destinazione").droppable({
drop: function(event, ui) {
$(this).find('p').html('Eccomi!');
}
});
});
</script>
<div id="trascinami">
<p>Spostami all'interno del box qui accanto...</p>
</div>
<div id="destinazione">
<p>Portami qui dentro!</p>
</div>A questa pagina puoi vedere l’esempio funzionante.
Come per Draggable, anche per questo plugin è possibile effettuare delle personalizzazioni tramite parametri, metodi e callback relative a determinati eventi. Ecco le opzioni che possiamo utilizzare:
| Opzione | Tipo | Default | Descrizione |
| accept | selettore, funzione | ‘*’ | Permette di definire quele elemento draggable sarà accettato. Di default tutti, ma si possono anche effettuare diversificazioni (indicando, ad esempio, il selettore del solo elemento accettato). |
| activeClass | stringa | false | Classe da aggiungere all’elemento droppable mentre avviene il drop. |
| disabled | booleano | false | Disabilita il plugin se impostato a true. |
| tolerance | stringa | ‘intersect’ | Definisce la modalità con la quale considerare avvenuto il drop. Le possibili stringhe sono:
|
Gli eventi annessi a questo plugin sono i seguenti:
- activate: comincia il movimento dell’elemento draggabile (si fa riferimento all’elemento draggabile accettato da quello droppabile);
- deactive: termina il movimento dell’elemento draggabile accettato;
- over: l’elemento draggabile accettato è sopra a quello droppabile (rispetto a tolerance);
- out: l’elemento draggabile accettato sta uscendo da quello droppabile;
- drop: l’elemento droppabile accettato è stato rilasciato (cioè è terminato il trascinamento).
I metodi previsti da questo plugin sono i mederimi visti per Draggable cioè: destroy, disable, enable, option e widget. Circa il loro utilizzo si faccia riferimento, quindi, alla lezione precedente.
Resizable (ridimensionare gli elementi)
Come dice il nome stesso, grazie al plugin Resizable è possibile ottenere elementi ridimensionabili. Per ottenere l’effetto è necessario richiamare il metodo resizable() come possiamo vedere da questo semplice esempio:
<script type="text/javascript">
$(function() {
$("#ridimensionami").resizable();
});
</script>
<div id="ridimensionami">
<p>Prova a ridimensionarmi...</p>
</div>Un esempio funzionante può essere visto a questa pagina.
Come al solito sono presenti numerosi parametri che permettono di personalizzare il comportamento del plugin. Vediamo i più importanti:
| Opzione | Tipo | Default | Descrizione |
| animate | booleano | false | Se impostata a true il ridimensionamento avviene tramite un’animazione. |
| animateDuration | intero, stringa | ‘slow’ | Indica la durata – in millisecondi – dell’animazione. |
| aspectRatio | booleano, float | false | Se impostato a true mantiene le proporzioni dell’elemento; in alternativa è possibile impostare delle proporzioni personalizzate (ad es. 16/9). |
| containment | stringa, elemento, selettore | false | Indica l’elemento contenitore entro il quale deve avvenire il resize (serve per limitare le possibilità di ridimensionamento dell’elemento a dei confini prestabiliti). |
| delay | intero | 0 | Tempo di latenza – in millisecondi – dopo il quale parte il resize. |
| disabled | booleano | false | Disabilita il plugin se impostato a true. |
| distance | intero | 1 | Definisce di quanti pixel il mouse deve muoversi per attivare il resize. |
| ghost | booleano | false | Se messo a true mostra un helper semitrasparente che fa da traccia durante il resize. |
| handles | stringa | ‘e, s, se’ | Indica la posizione delle "maniglie" attraverso le quali può essere operato il resize. Si utilizza una stringa contenente le iniziali delle coordinate cartesiane separate da virgola. I possibili valori sono:
|
| maxHeight, maxWidth | intero | null | Indicano le dimensioni massime (altezza e larghezza) che può assumere l’elemento resizable. |
| minHeight, minWidth | intero | null | Indicano le dimensioni minime (altezza e larghezza) che può assumere l’elemento resizable. |
Di seguito i link a degliesempi che mostrano l’effetto prodotto mediante alcune delle opzioni citate:
Per catturare gli eventi sono messe a disposizione dell’utente 3 callback che richiamano gli stati in cui si trova il nostro elemento:
- start: avvio del ridimensionamento;
- resize: ridimensionamento in corso;
- stop: ridimensionamento terminato.
Il loro utilizzo è identico a quanto già visto per gli altri plugin:
$("#ridimensionami").resizable({
stop: function(event, ui) {
alert("Il ridimensionamento è terminato!");
}
});Anche i metodi messi a disposizione sono gli stessi presenti negli altri plugin (destroy, disable, enable, option e widget) e per il loro utilizzo, quindi, si rimanda alle lezioni precedenti.
Selectable (selezionare elementi)
Tramite il plugin Selectable è possibile rendere selezionabile un elemento o un gruppo di elementi. La selezione di un elemento può essere fatta tramite il semplice click del mouse e sono possibili selezioni multiple (di elementi contigui) tramite il trascinamento del mouse oppure (in caso di elementi non contigui) attraverso il tasto Ctrl.
Il metodo selectable() offre un sistema alternativo ai classici strumenti di selezione che si basano sui i checkbox oppure sull’uso del tag <select>.
Questo metodo viene normalmente applicato a degli elenchi (puntati o numerati) mediante il selettore del tag di apertura (<ul> o <ol>). Vediamo un esempio:
<script type="text/javascript">
$(function() {
$("#lista").selectable();
});
</script>
<ul id="lista">
<li>Valore uno</li>
<li>Valore due</li>
<li>Valore tre</li>
</ul>A questa pagina è disponibile l’esempio funzionante.
Anche per il metodo selectable() sono presenti una serie di parametri che permettono di modificare l’esecuzione del plugin:
| Opzione | Tipo | Default | Descrizione |
| delay | intero | 0 | Determina il tempo di latenza – in millisecondi – tra il click e la selezione. |
| distance | integer | 0 | Determina la distanza in pixel che il mouse deve fare per attivare il plugin. |
| filter | selettore | * | Permette di determinare quali specifici elementi possono essere selezionati (vedi un esempio). |
| tolerance | stringa | ‘touch’ | Determina il metodo attraverso il quale si genere la selezione; i possibili valori sono:
|
Come per gli altri plugin sono presenti delle callback per la gestione degli eventi. Ecco gli eventi generati da questo plugin:
- start: inizio della selezione;
- stop: fine della selezione;
- selected: fine dell’operazione di selezione (per ogni elemento);
- selecting: durante la selezione (per ogni elemento);
- unselected: fine dell’operazione di rimozione della selezione (per ogni elemento);
- unselecting: durante la rimozione dalla selezione (per ogni elemento).
Vediamo un esempio:
<script type="text/javascript">
$(function() {
$("#lista").selectable({
selected: function(event, ui) {
alert('Hai selezionato un elemento!');
}
});
});
</script>Questo esempio può essere testato a questa pagina.
Sortable (ordinare elementi)
Il plugin Sortable permette di ottenere una lista dinamica, ovvero una lista i cui elementi sono "muovibili" (scammbiabili di posizione, trascinabili in altre liste, ecc.).
Per "lista" non si deve pensare solo alla solita classica lista creata mediante elenchi puntati e numerati, ma anche a griglie ed elementi contenitori come div, ai quali è applicata la caratteristica, appunto, di poter essere scambiati tra loro. Un esempio molto utilizzato, e di notevole impatto visivom è proprio quello ottenuto applicando il plugin ad un div contenitore di tutta la pagina. Si dà all’utente la possibilità di poter muovere, spostare e scambiare tra loro tutti i vari div contenuti su quello principale: la pagina risultate è estremamente interattiva, al punto tale che sia la struttura che la grafica possono essere personalizzate dall’utente!
Un semplice esempio di utilizzo di questo plugin applicato ad una lista può essere visualizzato a questa pagina.
Questo plugin supporta moltissime personalizzazioni e quindi si adatta a molte delle esigenze che l’utente potrebbe avere (un tipico utilizzo di questo plugin consiste nella creazione di un sistema di ordinamento degli elementi prelevati da un database).
L’applicazione del plugin avviene, come al solito, tramite il metodo che porta il nome dello stesso, ovvero sortable(). Vediamo un piccolo codice di esempio:
<script type="text/javascript">
$(function() {
$("#sortable").sortable();
$("#sortable").disableSelection(); //non fa selezionare l'interno - necessario
});
</script>
<ul id="sortable">
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
<li>Item 4</li>
<li>Item 5</li>
</ul>Ci sono come al solito 3 livelli di personalizzazione, ovvero mediate parametri, callback di cattura degli eventi e metodi. Per prima cosa, come sempre, andiamo a vedere i parametri ammessi da questto metodo.
Alcuni parametri sono comuni al metodo draggable(): circa i parametri axis, containment, cursor, delay, distance, helper, opacity e revert si faccia riferimento a questa lezione.
Di seguito alcune opzioni proprie del metodo sortable():
| Opzione | Tipo | Default | Descrizione |
| connectWith | selettore | false | Permette di collegare due liste al fine di consentire lo scambio dei rispettivi elementi che potranno essere trascinati da una lista all’altra (vedi l’esempio). |
| dropOnEmpty | booleano | true | Se impostato su false gli elementi della lista non possono essere rilasciati all’interno di una lista collegata (con connectWith) se quest’ultima è vuota. |
| items | selettore | ‘> *’ | Consente di specificare quali elementi della lista possono essere ordinati. |
| tolerance | stringa | ‘intersect’ | Definisce la modalità con la quale considerare avvenuto il drop. Le possibili stringhe sono:
|
Ora passiamo alle callback per catturare gli eventi:
- start: comincia l’azione di ordinamento;
- sort: durante l’ordinamento;
- change: durante l’ordinamento, ma solo se c’è un cambiamento di posizione;
- beforeStop: l’ordinamento termina, ma l’helper è ancora disponibile;
- stop: l’ordinameto termina;
- update: l’ordinamento è terminato e ci sono stati dei cambiamenti di posizione;
- receive: una lista collegata riceve un elemento;
- remove: un elemento è stato mosso da una lista ed è andato in un’altra;
- over: un elemento è mosso dentro un’altra lista collegata;
- out: elemento mosso fuori da una lista collegata;
- activate: l’avvio dell’ordinamento viene notificato a tutte le liste collegate;
- deactive: la terminazione dell’ordinamento viene notificata a tutte le liste collegate.
Questo plugin accetta i soliti metodi – visti in occasione della lezione su draggable() – più alcuni specifici:
- .sortable("serialize"): serializza gli ID degli elementi della lista ritornando una stringa sotto forma di chiave[1]=valore&chiave[2]=valore&…;
- .sortable("toArray"): restituisce gli ID degli elementi della lista e li ritorna sotto forma di array JavaScript;
- .sortable("refresh"): aggiorna la lista aggiungendo i nuovi elementi caricati (ad esempio tramite Ajax) dopo l’inizializzazione del metodo sortable();
- .sortable("cancel"): annulla l’ultima operazione di orinamento compiuta dall’utente;
Accordion (Widget)
Passiamo alla categoria dei Widget, ovvero plugin più complessi che mettono insieme più funzioni di jquery, sia a livello di grafica sia a livello di logica. In generale servono per risolvere problemi comuni e frequenti in maniera efficiente.
Il primo widget che tratteremo è Accordion. Questo widget permette di creare delle sezioni espandibili e richiudibili al click o al passaggio del mouse creando un effetto suggestivo per l’utente. Viene molto utilizzato quando si devono creare dei menù interni a delle pagine e si devono nascondere/mostrare inizialmente solo alcune porzioni del documento.
La struttura base è data da una serie di header (<h3>) e da una serie di sezioni (<div>), alternate tra loro, che definiscono appunto la voce cliccabile e il testo (associato) da mostrare.
<script type="text/javascript">
$(function() {
$("#accordion").accordion();
});
</script>
<div id="accordion">
<h3><a href="#">Sezione 1</a></h3>
<div>
<p>Testo sezione 1</p>
</div>
<h3><a href="#">Sezione 2</a></h3>
<div>
<p>Testo sezione 2</p>
</div>
<h3><a href="#">Sezione 3</a></h3>
<div>
<p>Testo sezione 3</p>
</div>
</div>Un semplice esempio è disponibile a questa pagina.
Sono disponibili diverse personalizzazioni:
- apertura e chiusura al click o al semplice passaggio del mouse;
- utilizzo di icone personalizzabili sull’header delle sezioni;
- possibilità di ordinare le sezioni tramite semplice drag.
Ecco alcuni dei parametri con cui possiamo modificare il comportamento del plugin:
| Opzione | Tipo | Default | Descrizione |
| active | selettore, elemento, booleano, numero | first child | Selettore dell’eventuale elemento attivo (usare false per non attivare alcun elemento all’avvio; in questo caso l’opzione collapsible deve essere true). |
| animated | booleano, stringa | ‘slide’ | Consente di definire il tipo di animazione da utilizzare (false per disabilitarla). |
| autoHeight | booleano | true | Se impostato, l’altezza dell’elemento più alto è utilizzata come riferimento. |
| collapsible | booleano | false | Se impostato su true ammette che tutte le sezioni dell’elemento possano essere chiuse (in caso contrario un elemento deve sempre essere attivo). |
| event | stringa | ‘click’ | Evento con il quale viene attivato il widget (ad es: ‘mouseover’ o ‘click’). |
| fillSpace | booleano | false | Se settata su true, la sezione aperta riempirà tutta l’altezza dell’elemento genitore. |
| header | selettore | Seleziona quale deve essere l’header (ad esempio: ‘header: h3’). | |
| icons | object | Icona da utilizzare per l’header. |
Gli eventi che possono essere gestiti riguardano il cambiamento del menu.
- change: quando c’è un cambiamento (dopo l’animazione se prevista);
- changestart: quando inizia un cambiamento.
Inoltre, come per le interazioni, sono presenti dei metodi che modicano il comportamento del plugin in esecuzione. Alcuni di questi metodi sono comuni a tutti i widget:
- .accordion("destroy"): rimuove completamente le funzionalità del widget;
- .accordion("disable"): disabilita il widget;
- .accordion("enable"): abilita il widget;
- .accordion("option",nome_opzione,[valore]): consente di recuperare o settare il valore delle opzioni viste precedentemente;
- .accordion("widget"): ritorna l’elemento a cui è applicato il widget (nel caso del plugin accordion sarà l’elemento con classe .ui-accordion);
Tra i metodi specifici segnaliamo:
- .accordion("activate",index): attiva una sezione attraverso l’indicazione del suo indice (parte da 0);
- .accordion("resize"): ricalcola l’altezza quando è utilizzata l’opzione fillSpace; utile se il contenitore è resizable e quindi le sue dimensioni non sono fisse.
Per questo plugin, come capirete, è molto importante curare attentamente l’aspetto grafico. Al solito ThemeRoller ci permette di definire interessanti combinazioni di stili e ci fornisce immagini personalizzate da utilizzare negli header.
Autocomplete (Widget)
Il widget Autocomplete è un plugin molto utile che fornisce una specie di "suggerimento" automatico circa il testo da inserire in un campo input.
Il funzionamento è il seguente: mentre l’utente digita il testo da inserire, viene mostrato un elenco delle possibili parole, prelevate da un insieme di dati (array Javasciript). Questi dati possono essere recuperati localmente o anche tramite chiamate AJAX, che permettono quindi di interagire con un database.
Un esempio di questa funzionalità può essere visto su Google, che attualmente utilizza un meccanismo di "suggerimenti per la ricerca" basato, appunto, sulla logica del plugin in questione:
La struttura a cui applicare il plugin è, ovviamente, una input, come ad esempio le textbox:
<script type="text/javascript">
$(function() {
var valori = ["pippo", "pino", "pittore", "picasso", "pianeta", "piccolino"];
$("#testo").autocomplete({
source: valori
});
});
</script>
<label for="testo">Inserisci il testo: </label>
<input type="text" id="testo">A questa pagina potete vedere un esempio funzionante.
Vediamo le opzioni che possono essere impostate nel nostro plugin:
| Opzione | Tipo | Default | Descrizione |
| delay | intero | 300 | Ritardo (in millisecondi) dopo la pressione di un tasto |
| minLenght | intero | 1 | Numero minimo di caratteri da premere perchè Autocomplete si avvii. |
| source | stringa, array, callback | Dati da utilizzare per l’autocompletamento. |
Ecco invece gli eventi che possiamo catturare:
- search: prima che la richiesta venga inviata;
- open: comparsa del menù di scelta;
- focus: passaggio del mouse sopra un elemento del menù (di default viene sostituito il valore nella textbox);
- select: elemento selezionato dal menù (di default viene sostituito il valore nella textbox);
- close: quando la lista è nascosta o non vi sono elementi da mostrare.
- change: dopo che un elemento è stato selezionato (sempre dopo l’evento ‘close’).
Molto utili sono due metodi caratteristici di questo widget e che permettono di gestire al meglio il menù dei suggerimenti:
- .autocomplete("search",[valore]): avvia la ricerca dei valori suggeriti. L’unico parametro presente (opzionale) è la parola da ricercare; se nessun valore è passato invece viene utilizzato quello dell’input;
- .autocomplete("close"): chiude il menù dei suggerimenti.
Per quanto riguarda i temi, il ThemeRoller ci fornisce lo stile di personalizzazione del menu a tendina in cui compaiono i suggerimenti, oltre ad un font differente per elementi selezionati e non, ecc.
Datepicker (Widget)
Il plugin Datepicker permette di mostrare un calendario da cui l’utente più selezionare una data, generalmente utilizzata per valorizzare correttamente un campo input all’interno di un form.
Sono possibili diversi livelli di personalizzazione, come il formato della data, la definizione di un range, ecc.
Oltre ad essere molto "comodo", questo widget consente risolvere una volta per tutte il problema legato al formato della data in relazione ai diversai standard locali, essendo possibile impostare, in modo semplice, il formato di data da utilizzare.
La struttura a cui applicare il plugin è una input di tipo text, dove appunto comparirà la data selezionata dal calendario.
<script type="text/javascript">
$(function() {
$("#data").datepicker();
});
</script>
<p>Seleziona la data: <input type="text" id="data"></p>Potete vedere un esempio funzionante a questa pagina.
Vediamo ora alcuni dei numerosi parametri è possibile impostare in fase di inizializzazione del plugin.
| Opzione | Tipo | Default | Descrizione |
| appendText | stringa | ” | Testo da aggiungere dopo il campo che conterrà la data (utile se si vuole specificare il formato: es: ‘gg-mm-aaaa’) |
| autoSize | booleano | false | Se settato a true l’input prende automaticamente la grandezza del formato specificato dal parametro ‘dateFormat’ |
| buttonImage | stringa | ” | URL dell’icona da cliccare per mostrare il calendario. |
| buttonImageOnly | booleano | false | Se impostata su true l’icona sarà l’unico mezzo per visualizzare il calendario. |
| buttonText | stringa | ‘…’ | Definisce il testo da mostrare all’interno del bottone; se è prevista un’immagine come bottone il testo viene utilizzato come valore dell’attributo alt dell’immagine. |
| changeMonth | booleano | false | Permette di cambiare il mese selezionandolo da un menu a discesa. |
| changeYear | booleano | false | Permette di cambiare l’anno selezionandolo da un menu a discesa. |
| constrainInput | booleano | true | Permette l’inserimento manuale solo di valori corrispondenti al formato della data selezionato. |
| currentText | stringa | ‘Today’ | Testo da mostrare per il giorno corrente. |
| dateFormat | stringa | ‘mm/dd/yy’ | Formato della data. |
| duration | stringa, numero | ‘normal’ | Velocità dell’animazione: in millisecondi o espressa come ‘slow’, ‘normal’ o ‘fast’. |
| hideIfNoPrevNext | booleano | false | Nasconde i pulsanti ‘prev’ o ‘next’. |
| maxDate | data, numero, stringa | null | Massima data selezionabile. Possibili valori sono una data specifica (anche in formato stringa), il numero dei giorni a partire dal giorno corrente (es: +7) o una stringa di valori e periodi (es: ‘+1m +1w’). |
| minDate | data, numero, stringa | null | Minima data possibile. I valori sono esprimibili come per maxDate. |
| numberOfMonths | numero, array | 1 | Numero di mesi da mostrare quando viene aperto il calendario. |
| selectOtherMonths | booleano | false | Permette la selezione diretta dei mesi prima e dopo quello attuale. |
| showAnim | stringa | ‘show’ | Animazione da usare per mostrare il calendario. |
| showOn | stringa | ‘focus’ | Consente di definire quale evento deve scatenare l’apertura del calendario: ‘focus’ al focus sull’input, ‘button’ al click sul bottone, ‘both’ in entrambe le situazioni. |
| showOptions | options | {} | Opzioni aggiuntive da passare al metodo showAnim, relative all’animazione. |
Di seguito alcuni esempi realizzati attraverso le diverse opzioni disponibili:
- Esempio con minDate e maxDate
- Esempio con comprasa ad effetto slide down
- Esempio con calendario che compare al click sull’icona
Inoltre ecco gli eventi generati dal calendario e che è possibile catturare e gestire:
- beforeShow: prima che il calendario è mostrato;
- beforeShowDay: prima che venga mostrato il giorno;
- onChangeMonthYear: il mese e/o l’anno vengono cambiati;
- onClose: chiusura del calendario;
- onSelect: selezione della data del calendario.
Oltre ai soliti metodi sono presenti anche 2 metodi importanti per poter settare o prelevare la data.
- .datepicker("getDate"): ritorna la data selezionata;
- .datepicker("setDate", date): imposta la data. Utilizza lo stesso formato dei parametri maxDate/minDate.
Con il ThemeRoller è possibile scegliere tra diversi temi che permettono di definire i bordi, lo sfondo, il font e tutto quello che serve alla visualizzazione del calendario; viene anche fornita un’icona di default per permettere l’apertura del calendario.
Dialog (Widget)
Il plugin Dialog permette di mostrare dei messaggi in overlay, ovvero sopra a tutti gli altri elementi della pagina. L’effetto che si ottiene è una sorta di popup, con annessa barra del titolo, interno alla pagina corrente. Le finestre di tipo dialog vengono normalmente utilizzate per fornire delle notifiche oppure in sostituzizone delle classiche finiestrelle di tipo alert, prompt e confirm.
Di seguito un esempio di base di utilizzo del metodo dialog()>:
<script type="text/javascript">
$(function() {
$("#dialog").dialog();
});
</script>
<div id="dialog" title="Titolo del dialog">
<p>Contenuto del dialog</p>
</div>Per vedere un esempio clicca su questo link.
Molto spesso questi messaggi vengono utilizzati disattivando gli elementi sottostanti, così che l’utente non possa interagire con essi (sino alla chiusura del dialog); questo risultato si ottine attivando la funzionalita modal.
I messaggi non sono nient’altro che dei tag <div> in cui è possibile, naturalmente, inserire anche altre strutture (form, ecc.) oltre a del semplice testo: l’effetto desiderato è quello di creare delle vere e proprie finestre con cui far interagire l’utente.
Di seguito alcune delle opzioni che è possibile definire per questo widget:
| Opzione | Tipo | Default | Descrizione |
| autoOpen | booleano | true | Apertura automatica del dialog quando viene chiamato. Se impostato su false sarà necessario utilizzare il metodo .dialog("open"). |
| buttons | object | {} | Bottoni da mostrare nel dialog. Coppia key/value in cui la key è il testo del bottone e il value la callback da eseguire (clicca qui per vedere un esempio). |
| closeOnEscape | booleano | true | Se impostato su true il dialog viene chiuso alla pressione del tasto ESC. |
| closeText | stringa | ‘close’ | Testo del bottone di chiusura. |
| draggable | booleano | true | Il dialog è trascinabile tramite la barra del titolo. |
| height | numero | ‘auto’ | Altezza dialog in pixel. |
| hide | string | null | Effetto da usare quando il dialog viene chiuso (es: ‘slide’) |
| maxHeight/minHeight | numero | false | Massima/minima altezza in pixel del dialog. |
| maxWidth/minWidth | numero | false | Massima/minima larghezza in pixel del dialog. |
| modal | booleano | false | Se messo a true quando il dialog è mostrato gli altri elementi della pagina vengono disabilitati (clicca qui per vedere un esempio). |
| position | string, array | ‘center’ | Posizione in cui il dialog viene mostrato. Stringhe possibili: ‘center’, ‘left’, ‘right’, ‘top’ e ‘bottom’. Utilizzare l’array per indiacare le coordinate in pixel o la posizione. Es: [300,200] o [‘left’,’top’]. |
| resizable | booleano | true | Imposta il dialog ridimensionabile. |
| show | string | null | Effetto da usare per mostrare il dialog. Speculare a hide. |
| stack | booleano | true | Specifica se il dialog sarà posizionato al di sopra di altri dialog, ovvero sarà di fronte ad essi. |
| title | stringa | ” | Titolo del dialog. Si può anche usare l’attributo title dell’elemento (come nel codice visto all’inizio della lezione). |
| width | numero | 300 | Larghezza del dialog in pixel. |
| zIndex | intero | 1000 | zIndex iniziale del dialog. Lo zIndex determina la sovrapposizione degli elementi (in primo piano o no). |
Gli eventi che si possono gestire sono essenzialmente quelli che abbiamo visto per i plugin draggable e resize, in quanto queste finestre hanno anche le proprieta di essere trascinabili e ridimensionabili.
- beforeClose: prima che il dialog sia chiuso;
- open: all’apertura del dialog;
- focus: quando il dialog viene selezionato;
- dragStart: quando comincia il trascinamento;
- drag: mentre il dialog viene trascinato;
- dragStop: quando è terminata l’operazione di drag;
- resizeStart: quando comincia il resize;
- resize: quando l’elemento è in fase di resize;
- resizeStop: alla fine del resize;
- close: alla chiusura del dialog.
Oltre ai soliti metodi disponibili per tutti i widget, il plugin in oggetto dispone di metodi propri; vediamo i più interessanti:
- .dialog("close"): chiude il dialog;
- .dialog("isOpen"): verifica se il dialog è aperto;
- .dialog("moveToTop"): muove il dialog in alto allo stack dei dialog;
- .dialog("open"): apre il dialog (se autoOpen è impostato a false);
Tabs (Widget)
Ultimo widget che vi presento è Tabs. Questo widget è, per molti aspetti, molto simile ad Accordion in quanto, come questo, consente di "separare" diversi contenuti della stessa pagina rendendoli navigabili (visualizzabili) attraverso appositi link. A differenza di Accordion (che ha uno sviluppo verticale) il plugin Tabs crea un sistema orizzontale di navigazione attraverso "etichette".
La struttura di base è differente rispetto a quella di Accordion: il tutto è basato su una serie di ancore (<a>) legate alle rispettive sezioni da mostrare (<div>). I contenuti da mostrare possono essere presenti all’interno del docuemnto HTML oppure possono essere caricati dinamicamente mediante Ajax.
Vediamo un esempio di base di utilizzo di Tabs in cui i contenuti sono già presenti nella pagina web:
<script type="text/javascript">
$(function() {
$("#etichette").tabs();
});
</script>
<div id="etichette">
<ul>
<li><a href="#tab1">Sezione 1</a></li>
<li><a href="#tab2">Sezione 2</a></li>
<li><a href="#tab3">Sezione 3</a></li>
</ul>
<div id="tab1">
<p>Sezione 1</p>
</div>
<div id="tab2">
<p>Sezione 2</p>
</div>
<div id="tab3">
<p>Sezione 3</p>
</div>
</div>A questa pagina potete vedere un esempio funzionante.
L’utilizzo, come detto, è simile a quello di Accordion, ma per completezza vi mostro qui i vari parametri, eventi e metodi:
| Opzione | Tipo | Default | Descrizione |
| ajaxOptions | options | null | E’ un oggetto che contiene le opzioni da passare alla funzione $.ajax() per caricare il contenuto del tab. |
| cache | booleano | false | Caricare il contenuto di un tab remoto (Ajax) solo una volta o ad ogni evento (es click). |
| collapsible | booleano | false | Permette di collassare tutte le schede lasciando visibili solo le etichette. |
| cookie | object | null | Memorizza l’utlimo tab selezionato in un cookie (è necessario il plugin cookie). |
| event | string | ‘click’ | Evento da utilizzare per selezionare un tab (di default è il click, ma se prefereite potete optare per mouseover). |
| panelTemplate | string | ‘<div></div>’ | Si tratta della struttura che verrà utilizzata da Ajax per aggiungere un nuovo contenuto (vedi anche tabTemplate). |
| selected | numero | 0 | Numero di tab da selezionare inizialmente. Gli indici partono da 0. |
| tabTemplate | string | ‘<li><a href="#{href}">#{label}</a></li>’ | Si tratta della struttura che verrà utilizzata da Ajax per aggiungere una nuova etichetta. |
Vediamo ora gli eventi:
- select: al click sul tab;
- load: il contenuto di un tab remoto è stato caricato;
- show: un tab è mostrato;
- add: un nuovo tab è stato aggiunto;
- remove: un tab è stato rimosso;
- enable: un tab è abilitato;
- disable: un tab è disabilitato.
Ed infine i metodi specifici di questo plugin:
- .tabs("add",url,label,[index]): aggiunge un nuovo tab. Il secondo parametro è l’url del tab (ancora interna alla pagina o link ad una pagina esterna in caso di tab remoto). Label è il testo per l’etichetta. Index è la posizione (indice che parte da 0) del tab (di default viene aggiunto alla fine);
- .tabs("remove",index): rimuove un tab in base all’indice passato;
- .tabs("enable",index): abilita un tab in base all’indice;
- .tabs("disable",index): disabilita un tab in base all’indice;
- .tabs("select",index): seleziona un tab in base all’indice (simula l’effetto del click);
- .tabs("load",index): ricarica il contenuto di un tab remoto (il metodo ha effetto anche se il parametro cache è impostato a true);
- .tabs("url",index, url): cambia l’url di un tab;
- .tabs("lenght"): restituisce il numero di tab caricate nel widget;
- .tabs("abort"): ferma tutte le richieste AJAX di caricamento del contenuto dei tab e blocca anche tutte le animazioni;
- .tabs("rotate",ms,[continue]): imposta una rotazione automatica dei tab. Il secondo parametro sono i millisecondi tra un tab e l’altro. L’ultimo parametro serve per impostare se la rotazione deve terminare o meno quando l’utente seleziona un tab (di default: false). Puoi vedere un esempio a questa pagina.
Il metodo effect() per gestire gli effetti speciali
Nella guida a jQuery abbiamo già visto come sia possibile realizzare delle vere e proprie animazioni sfruttando il metodo animate(). Il progetto jQuery UI estende le capacità originarie della libreria aggiungendone di nuove attraverso il metodo effect(). La sintassi completa del metodo è la seguente:
effect(effetto, opzioni, durata, callback)Nella sua forma più semplice, tuttavia, il metodo effect() può essere utilizzato semplicemente indicando il tipo di effetto da applicare, in questo modo:
<script type="text/javascript">
$(function() {
$("#box").effect("shake");
});
</script>
<div id="box">
Contenuto del box su cui apllicare l'effetto
</div>Per vedere l’effetto prodotto da questo codice clicca qui.
Di seguito l’elenco degli effetti supportati da questo metodo:
- blind (esempio)
- bounce (esempio)
- clip (esempio)
- drop (esempio)
- explode (esempio)
- fade (esempio)
- fold (esempio)
- highlight (esempio)
- puff (esempio)
- pulsate (esempio)
- scale (esempio)
- shake (esempio)
- size (esempio)
- slide (esempio)
- transfer (esempio)
Come detto, il metodo effect() supporta, oltre al tipo d’effetto, anche altri parametri:
- opzioni: ogni effetto dispone di diverse opzioni (potete vederle a questa pagina della documentazione ufficiale). Ad esempio, l’effetto slide prevede tre opzioni: direction (left, right, up, down), distance e mode (show, hide).
- durata: la durata dell’effetto espressa in millisecondi.
- callback: funzione da eseguire al termine dell’effetto.
Vediamo un esempio completo:
<script type="text/javascript">
$(function() {
$("#box").effect("slide", {direction: "down"}, 500, domanda);
});
function domanda(){
setTimeout(function(){
alert("Ti è piaciuto l'effetto?");
}, 1000);
};
</script>
<div id="box">
Contenuto del box su cui apllicare l'effetto
</div>Per vedere questo esempio all’opera clicca qui.
Alcuni degli effetti prodotti dal metodo effect() possono essere gestiti mediante alcune scorciatoie, rappresentate dai metodi di jQuery show(), hide() e toggle(). Questi metodi accettano come parametro il tipo di effetto che verrà applicato per mostrare o nascondere l’elemento cui è associato. Esempio:
// mostro un box con effetto blind
$("#box").show("blind");
// nascondo un box con effetto slide
$("#box").hide("slide");Si noti che queste scorciatoie non funzionano con tutti gli effetti (come ad esempio highlight); per gli effetti non supportati, pertanto, è sempre necessario ricorrere al metodo effect().
