Datepicker

Molto probabilmente ognuno di noi si sarà imbattuto, durante la compilazione di un form, in spiegazioni ed etichette di campo del tipo gg/mm/aaaa oppure gg/mm/aa. Altrettanto spesso si sarà trovato di fronte a tre menu a tendina dai quali dover scegliere giorno, mese ed anno, magari chiedendosi che giorno della settimana sarà il 14 Aprile 2010.

Tutti questi passaggi, controlli, etichette e spiegazioni mettono in evidenza come sia difficile lavorare in maniera intuitiva e diretta con le date.

La risposta di jQuery UI al problema è il widget datepicker che in italiano definiremmo calendario.

L'utilizzo principale di questo tipo di controllo è da una parte quello di facilitare l'utente nell'inserimento di date in vario formato, dall'altro quello di ridurre al minimo errori nella formattazione delle date stesse.

Nella sua forma più semplice, il widget è attivabile su ogni elemento di input testuale selezionabile con jQuery (esempio):

$(".data:input").datepicker();

Opzioni

Data la diversità di utilizzo e la necessità di adattamento a vari formati di data (sia per sintassi che per lingua), datepicker offre un nutrito numero di opzioni che spaziano dall'impostazione del formato restituito, al restringimento delle date selezionabili a determinati range. Il tutto concorre ad ottimizzare l'esperienza utente e la gestione dell'input nella fase di rielaborazione dei dati.

L'esempio più classico nel quale si ha necessità di personalizzare il widget datepicker
è quello di un modulo di prenotazione nel quale è necessario prevedere più lingue ed evitare che accidentalmente un utente possa richedere una prenotazione per date nel passato.

Per sintetizzare, le caratteristiche personalizzabili del widget riguardano l'interazione (in che modo il controllo viene attivato), il formato della data e gli elementi visibili del calendario.

Opzioni per l'interazione

• buttonImage: (stringa : '')
  indica quale immagine utilizzare come bottone per richiamare il widget. È possibile associarla all'opzione buttonImageOnly impostata su true per rendere l'immagine (solitamente un'icona) l'unico mezzo per visualizzare il calendario.
• minDate / maxDate
  imposta un limite entro il quale è possibile selezionare una data. I valori accettati sono un oggetto Date, un numero (per esempio +7) o una stringa con valori e periodi ('y' per gli anni, 'm' per i mesi, 'w' per le settimane, 'd' per i giorni, ad esempio '+1m +1w').

Opzioni di formato

Di default, il linguaggio di datepicker è l'inglese, compresa la formattazione della data secondo lo schema mese/giorno/anno. Il modo più semplice per impostare il formato corretto in base al proprio linguaggio è quello di richiamare uno dei file di lingua presenti nella cartella i18n. In questo modo la localizzazione prescelta sarà applicata automaticamente ad ogni istanza del widget.

Nei casi in cui si dovessero gestire più lingue basterà includere il file di lingua completo jquery-ui-i18n.js ed impostare un linguaggio specifico richiamandolo nell'inizializzazione del widget:

$("#calendario").datepicker($.datepicker.regional['it']);

oppure impostandolo globalmente:

$.datepicker.setDefaults($.datepicker.regional['it']);

Le opzioni impostate in questo modo sono le seguenti:

• closeText: il testo per il link che chiude il calendario;
• prevText / nextText: il testo per i link al mese precente e successivo;
• currentText : il testo per "oggi";
• monthNames / monthNamesShort: i nomi dei mesi in formato esteso (Gennaio) e abbreviato (Gen);
• dayNames / dayNamesShort / dayNamesMin: i nomi dei giorni della settimana in formato esteso (Lunedì), abbreviato (Lun) e minimo (Lu);
• dateFormat: il formato della data, in italiano dd/mm/yy (giorno, mese e anno in due cifre);
• firstDay: il primo giorno della settimana, 0 per domenica (nel calendario inglese), 1 per Lunedì;
• isRTL: se impostato su true i giorni saranno elencati da destra verso sinistra.

Ecco un esempio di localizzazione in italiano.

Opzioni di visualizzazione

Le opzioni di questo gruppo servono per aggiungere o personalizzare il modo in cui viene visualizzato il calendario:

• changeMonth / changeYear: (booleano : false)
  se impostate su true, queste opzioni aggiungono in alto un menu a tendina che permette di scegliere velocemente il mese o l'anno. In questo modo l'utente può selezionare più rapidamente date moto distanti nel
  futuro senza dover cliccare ripetutamente sui link di navigazione (esempio);
• duration: indica la durata dell'animazione con cui il calendario appare. Basandosi sulle animazioni di jQuery i valori accettati sono numeri (millisecondi) oppure stringhe ('slow', 'normal', 'fast');
• numberOfMonths: (intero, array : 1)
  indica il numero di mesi da mostrare contemporaneamente nel widget. Può essere un numero intero (2
  mostrerà il mese corrente ed il prossimo) oppure un array numerico che definisca il numero di righe e colonne da riempire con i mesi ([2,3] mostrerà sei calendari disposti su due righe e tre colonne). Ecco un esempio;
• showAnim: (stringa : 'show')
  indica il tipo di animazione da usare per mostrare il calendario. Può essere usata una qualsiasi delle animazioni disponibili con jQuery o jQuery UI.

Eventi

Datepicker accetta fra le sue opzioni anche una serie di eventi, utili per impostare l'interazione fra il widget ed altri elementi della pagina:

• beforeShow: lanciato appena prima che il calendario venga mostrato. La funzione collegata accetta due argomenti, un'istanza dell'input a cui è associato il widget e un'istanza del datapicker stesso;
• beforeShowDay: lanciato prima della visualizzazione del calendario. La funzione accetta come argomento una data e deve restituire un array con tre elementi: true o false per rendere il giorno selezionabile, una stringa che rappresenti una classe CSS per la presentazione di default, un tooltip da associare al
  giorno. Fate attenzione che questa funzione verrà applicata a tutti i giorni presenti nel widget comportando una
  diminuzione nelle performance del controllo soprattutto durante la visualizzazione iniziale e se sono visualizzati più mesi tramite l'opzione numberOfMonths;
• beforeShow: permette di definire una funzione personalizzata quando il datepicker passa da un mese/anno all'altro. Accetta come argomenti l'anno selezionato, il mese (1-12), e l'istanza del datepicker. In questo caso this si riferisce all'input associato al widget;
• onClose: lanciato quando il datepicker viene chiuso. Accetta come argomenti la data selezionata in formato stringa e un'istanza del datepicker stesso. L'evento viene lanciato anche se non è stata selezionata una data;
• onSelect: lanciato quando il datepicker viene selezionato. Accetta come argomenti la data selezionata in formato stringa e un'istanza del datepicker stesso.

Metodi specifici

Il widget, oltre ai metodi generali di jQuery UI visti in precedenza, offre metodi specifici per interagire con i dati provenenti dal controllo, nonché per interagire con lo stesso.

• hide / show: nasconde e mostra il datepicker. Utile quando si vuole mostrare il calendario senza attendere che l'utente attivi il comportamento predefinito;
• getData / setData: ricava ed imposta la data del datepicker. Per setData è necessario fornire un ulteriore argomento seguendo la stessa sintassi richiesta delle opzioni minDate e maxDate;
• dialog: apre il datepicker in un overlay (o finestra di dialogo). È necessario indicare come ulteriore argomento la data iniziale per il datepicker, mentre si possono aggiungere opzionalmente altri tre argomenti: una funzione di callback a seguito della selezione di una data, un oggetto JavaScript con nuove opzioni per la visualizzazione, la posizione dell'overlay alto/sinistra in formato [x, y] oppure un evento del mouse contenente tali coordinate. Se questo argomento non viene specificato, la finestra sarà centrata nello schermo.