FullCalendar, un calendario/agenda in jQuery

Vi sarà sicuramente capitato di utilizzare, o comunque anche solo di sentir parlare, di Google Calendar. Il plugin FullCalendar di jQuery permette di creare un calendario proprio sullo stile del calendario di Google e di poterlo includere nelle vostre pagine web: si possono impostare eventi, durate e ogni altro tipo di informazione che è possibile associare ad un calendario.

Come si può capire, il plugin in discorso risulta molto utile in diverse situazioni, ad esempio nella creazione di agende personalizzate o per schedulare eventi ad orari e giorni predefiniti.

Il plugin fornisce la possibilità di trascinare eventi tramite il drag & drop e di utilizzare AJAX per caricare al volo gli eventi senza refresh pagina. Inoltre è prevista anche un’estensione per caricare direttamente gli eventi da Google Calendar, molto utile se si vogliono importare eventi in tale formato.

Come tutti i calendari che si rispettino, Fullcalendar offre tre diversi tipi di visualizzazione:

• Mese
• Settimana
• Giorno

Ognuna di queste visualizzazioni è personalizzabile a seconda delle vostre esigenze.

Un’altra nota a favore di questo plugin è il fatto di poter utilizzare temi per rendere ancora più apprezzabile il nostro calendario.

Vediamo subito alcuni esempi e alcuni delle personalizzazioni più interessanti che si possono ottenere grazie a questo plugin. Innanzitutto per caricare far funzionare il tutto abbiamo bisogno, come per ogni plugin, di jQuery. Inoltre, visto che sono possibili gli effetti di drag & drop e resize è necessario importare anche le jQuery UI relative a questi effetti. Per il resto basta importare il plugin come una qualsiasi libreria Javascript ed includere il file CSS relativo al calendario.

<link rel='stylesheet' type='text/css' href='../fullcalendar.css' /> 
<script type='text/javascript' src='../jquery/jquery.js'></script> 
<script type='text/javascript' src='../jquery/ui.core.js'></script> 
<script type='text/javascript' src='../jquery/ui.draggable.js'></script> 
<script type='text/javascript' src='../jquery/ui.resizable.js'></script> 
<script type='text/javascript' src='../fullcalendar.min.js'></script>

Per avviare il plugin è sufficiente richiamare la funzione fullCalendar(), ovviamente inserendo gli opportuni parametri. Vediamo un semplice esempio partendo dal codice Javascript:

<script type='text/javascript'>
$(document).ready(function() {
  var date = new Date();
  var d = date.getDate();
  var m = date.getMonth();
  var y = date.getFullYear();
  $('#calendar').fullCalendar({ 
    header: { 
      left: 'prev,next today',
      center: 'title',   
      right: 'month,agendaWeek,agendaDay'
    },   
    editable: true, 
    events: [
      {     
      title: 'Evento che dura tutto il giorno',   
      start: new Date(y, m, 1) 
      },     
      {           
      title: 'Evento che dura piu giorni',     
      start: new Date(y, m, d-5),   
      end: new Date(y, m, d-2)   
      },       
      {       
      id: 999,   
      title: 'Evento ripetuto',     
      start: new Date(y, m, d-3, 16, 0), 
      allDay: false   
      },
      {       
      id: 999,   
      title: 'Evento ripetuto', 
      start: new Date(y, m, d+4, 16, 0), 
      allDay: false       
      },
      {       
      title: 'Incontro',     
      start: new Date(y, m, d, 10, 30), 
      allDay: false       
      }, 
      {           
      title: 'Pranzo',       
      start: new Date(y, m, d, 12, 0),   
      end: new Date(y, m, d, 14, 0), 
      allDay: false         
      },
      {           
      title: 'Compleanno',         
      start: new Date(y, m, d+1, 19, 0),   
      end: new Date(y, m, d+1, 22, 30), 
      allDay: false       
      },
      {           
      title: 'Evento con link esterno',       
      start: new Date(y, m, 28),     
      end: new Date(y, m, 29),   
      url: '/' 
      }
    ]     
  });   
}); 
</script>

Ecco il codice HTML/CSS in cui verrà mostrato il calendario:

<style type='text/css'>
#calendar { 
  width: 800px;
  margin: 0 auto;
}
</style>
<div id='calendar'></div>

Come funziona il plugin?

Come potete vedere in quest’esempio il calendario è generato – dinamicamente – all’interno di un <div> con ID #calendar. Per quanto riguarda il codice Javascript: dopo aver recuperato la data corrente viene istanziato il metodo fullCalendar() al quale vengono passati diversi paramentri che ne consentono la personalizzazione. Come per molti plugin la sintassi da utilizzare è quella JSON, ovvero si deve passare una coppia chiave/valore per definire, appunto, i diversi parametri.

Come prima cosa è stato creato l’header del calendario, più precisamente:

• sono stati inseriti a sinistra i pulsanti per muoversi all’interno del calendario (ovvero i pulsanti precedente, successivo e oggi);
• al centro è inserito il titolo, che non è altro che l’identificativo della schermata che viene mostrata all’utente (se si sta visualizzando il calendario in modalità mese, ad esempio, il titolo sarà il mese visualizzato);
• a destra vengono mostrati i pulsanti che permettono di cambiare le varie modalità di visualizzazione.

Il successivo parametro passato è il parametro editable: questo permette di rendere gli eventi modificabili dall’utente, ovvero di poterli spostare e ridimensionare (cambiare la durata) a piacimento.

Finalmente passiamo agli eventi (events). In questo semplice esempio abbiamo raggruppato diverse tipologie di eventi che l’utente può utilizzare all’interno del calendario. Gli eventi sono identificati per mezzo del paramentro "events" che è un array di oggetti Javascript i quali possono contenere a loro volta diverse proprietà, qui di seguito elencate:

• id: Stringa o intero che identifica univocamente l’evento (per ripetere un’evento bisogna utilizzare lo stesso valore);
• title: Testo che compare all’interno dell’evento sul calendario;
• allDay: true o false. Permette di determinare se un evento dura tutto il giorno oppure no (di default è true);
• start: Oggetto Date di Javascript utilizzato per indicare l’inizio di un evento. I formati supportati sono IETF ("Wed, 18 Oct 2009 14:00:00 EST"), ISO8601 ("2009-11-05T13:15:30Z") o il formato UNIX timestamp;
• end: stesso che per start, ma identifica la fine dell’evento;
• url: stringa che identifica l’URL dell’evento e che sarà attivato al click su di esso;
• className: stringa o array di classi CSS da applicare all’evento;
• editable: true o false. Rende l’evento modificabile o meno. Sovrascrive il parametro "editable" visto sopra;
• source: sorgente dell’evento. Può essere un array, una stringa o una funzione. Questo parametro è riempito automaticamente dal plugin, quindi non deve essere settato a mano.

Le uniche proprietà obbligatorie sono title e start. Vediamo quindi come abbiamo utilizzato queste proprietà.

Il primo evento creato è un evento che dura tutto il giorno. E’ sufficiente, quindi, impostare solamente il title e start. Il secondo evento che viene inserito invece rientra nella casistica di eventi che durano più di un giorno: in questo caso non basta fare nient’altro che impostare correttamente la data di inizio e di fine, facendo cadere la fine, ovviamente, su un giorno differente. Per creare un evento che si ripete più volte, basta invece utilizzare lo stesso ID. Se non viene impostata una data di termine e il valore di allDay è impostato a false, viene utilizzato un valore di durata di default (2h di solito). L’ultimo caso interessante è quello dell’ultimo evento, il quale contiene il parametro "url" che permette di definire il comportamente dell’elemento al click.

Interagire con Google Calendar

Abbiamo detto all’inizio di questo articolo che è possibile ottenere un calendario simile a Google Calendar, ma che è anche possibile interagire con esso. Nel semplice esempio che segue (preso dal sito ufficiale) si prelevano dal calendario di Google le festività americane e si mostrano all’interno del plugin.

<script type='text/javascript'>
$(document).ready(function() { 
  $('#calendar').fullCalendar({
    // US Holidays 
    events: $.fullCalendar.gcalFeed('http://www.google.com/....public/basic'),
    eventClick: function(event) { 
      // opens events in a popup window 
      window.open(event.url, 'gcalevent', 'width=700,height=600');
      return false;   
    },   
    loading: function(bool) { 
      if (bool) $('#loading').show(); 
      else $('#loading').hide();
    }       
  });      
});
</script>

Come si può intuire il cambiamento principale consiste nella modalità di caricamento degli eventi: infatti viene sfruttata la funzione gcalFeed() che tramite un link di Google Calendar, preleva tutti gli eventi di quel determinato calendario. Per il resto, in quest’esempio, vediamo l’utilizzo del parametro eventClick che permette di definire il comportamento del click su di un evento che, in questo caso, definisce appunto l’apertura – all’interno di un popup – della url (prelevata tramite event.url). Il parametro loading, invece, è utilizzato solo per mostrare o nascondere una gif animata o una scritta per far capire all’utente che la pagina è ancora in fase di caricamento. Molto utile proprio quando si devono effettuare caricamenti di eventi da remoto e, quindi, non immediatamente disponibili.

Caricare gli eventi in Fullcalendar tramite JSON

Oltre che da Google Calendar, gli eventi possono essere caricati anche da una qualsiasi pagina esterna che ritorna una stringa JSON. Nella realtà implementativa questo caso risulta essere molto utile in quanto si desidera prelevare eventi da un database. Vediamo un semplice esempio:

<script type='text/javascript'>
$(document).ready(function() {
  $('#calendar').fullCalendar({
    editable: true,   
    events: "json-events.php",
    eventDrop: function(event, delta) {
      alert(event.title + ' modificato ');
    }, 
    loading: function(bool) { 
      if (bool) $('#loading').show(); 
      else $('#loading').hide();
    } 
  });
});
</script>

In questo esempio gli eventi vengono prelevati dalla pagina "json-events.php" e caricati nel nostro calendario. Gli eventi caricati avranno naturalmente le stesse proprietà degli oggetti caricati negli altri modi, ovvero avranno un title, uno start ecc. Per chiarezza credo sia utile mostrare l’ipotetico sorgente della pagina "json-events.php":

$year = date('Y');
$month = date('m');

echo json_encode(array(
  array(
    'id' => 111,
    'title' => "Evento 1",
    'start' => "$year-$month-10",
    'url' => "http://www.esempio.com/url-evento.html"
  ),
  array(
    'id' => 222,
    'title' => "Evento 2",
    'start' => "2010-04-06T13:15:30Z",
    'end' => "2010-04-06T14:15:30Z",
    'allDay' => false
  ),
  array(
    'id' => 333,
    'title' => "Evento 3",
    'start' => "$year-$month-20",
    'end' => "$year-$month-22",
    'url' => "http://www.google.it/"
  )
));

In questo esempio è stato utilizzato il linguaggio PHP per realizzare lo script, ma è possibile, ovviamente, utilizzare una qualsiasi altra tecnologia lato server. Come si vede viene creato un’array con chiavi i nomi delle proprietà dell’evento e come valore il relativo valore. Successivamente tramite la funzione "json_encode()" è creata la stringa JSON e stampata a video tramite (in questo caso la pagina è statica, ma si può ricreare l’array anche prelevando i dati da un database).

Tornando al codice Javascript credo sia utile soffermarsi un attimo sull’evento eventDrop: in questo esempio viene solo lanciato un messaggio (tramite un alert) per dire che è stato modificato un evento, ma se i dati vengono prelevati da database, si potrebbe effetturare una chiamata AJAX e modificare tale evento sul database, così da avere un calendario sincronizzato con la visualizzazione.

Per ulteriori informazioni riguardo ai metodi ed alle opzioni impostabili in questo plugin rimando alla documentazione ufficiale.