Ajax con MooTools

La componente riguardante Ajax è, al pari di quella degli effetti, lo strumento più utilizzato e discusso di un framework Javascript.

Questo perché le richieste Ajax al server sono il "pane" del Web 2.0 ed è ormai raro vederne priva un'applicazione di nuova generazione. Per questo motivo, spesso gli sviluppatori tendono a realizzare un "framework nel framework" per quanto riguarda questo aspetto specifico.

Le classi che MooTools, nella versione 1.1, ci offre per lavorare con Ajax sono le seguenti:

• XHR: è un wrapper contenente tutte le proprietà, le opzioni e i metodi di base (è simile alla classe wrapper Fx vista nell'articolo MooTools: usare gli effetti Fx , anche se XHR può essere usato come oggetto autonomo per inviare richieste);
• Ajax: è la classe principale che estende le funzionalità di XHR e permette di creare richieste avanzate "per ogni esigenza asincrona", come indicato nella documentazione sul sito ufficiale.

Prima di iniziare con il tutorial tecnico, voglio elencare le caratteristiche e i vantaggi principali del framework Ajax offerto da MooTools:

• le classi XHR e Ajax, come ogni altro componente avanzato, sfruttano la sintassi del costruttore Class, quindi l'implementazione delle opzioni e dei relativi parametri è semplice e immediata;
• sono necessari solo i componenti delle sezioni Core, Class, Native (immancabili in ogni download) più il file Element.Form per il funzionamento di XHR e Ajax;
• è possibile racchiudere tutti gli input value di un form di qualsiasi dimensione e passarlo come corpo della richiesta semplicemente chiamando la funzione $ con l'id del form;
• è possible controllare ogni fase della richiesta, impostare le intestazioni desiderate e decidere se eseguire gli eventuali script restituiti dal server.

Detto questo, passiamo ora ad analizzare nel dettaglio tutte le opzioni che XHR e Ajax ci mettono a disposizione.

I costruttori XHR e Ajax

Il costruttore XHR accetta un solo parametro che rappesenta le opzioni della richiesta. Ecco la sintassi di base:

var myxhhr = new XHR(options);

Queste opzioni sono importantissime e verranno ereditate dalla superclasse Ajax. Vediamole:

• method: è il metodo con cui inviamo la richiesta: 'post' (default) o 'get';
• async: se true la richiesta sarà asincrona (default true);
• encoding: il tipo di codifica, di default 'utf-8';
• autoCancel: se impostata a true interrompe una richiesta già partita se ne viene effettuata un'altra (default false);
• headers: un oggetto che rappresenta le intestazioni di richiesta da inviare al server (nel caso di una richiesta post lo script invia automaticamante l'intestazione Content-Type impostata a 'application/x-www-form-urlencoded');
• onRequest: funzione da eseguire quando parte la richiesta (di default è una funzione vuota, Class.Empty) ;
• onSuccess: funzione da eseguire quando la richiesta viene completata (default Class.Empty);
• onStateChange: funzione azionata quando cambia lo stato della richiesta;
• onFailure: funzione da eseguire se la richiesta fallisce.

XHR mette inoltre a disposizione le seguenti due proprietà:

• running: è settato a true se la richiesta è in corso, altrimenti false;
• response: un oggetto accessibile nell'opzione onSuccess le cui proprietà text e xml rappresentano il contenuto della risposta del server.

Prima abbiamo affermato che XHR può essere utilizzato come oggetto autonomo, per questo definisce i seguenti metodi:

• setHeader (name, value): imposta l'intestazione 'name' al valore 'value', senza sovrascrivere quelle impostate nelle opzioni;
• send (url, data): esegue la richiesta vera e propria inviando i dati 'data' all'indirizzo 'url';
• cancel: interrompe la richiesta.

Un esempio di semplice richiesta con la classe XHR è il seguente:

// invia una richiesta a mypage.php con una querystring
	var myReq = new XHR({method:'get', autoCancel:false}).send('mypage.php', 'name=Andy color=blue')
	

Ma la vera potenza del framework Ajax offerto da MooTools si ottiene con il costruttore Ajax:

	var myReq = new Ajax(url, options);
	

Esso accetta due parametri: l'url della pagina alla quale si vuole inviare la richiesta e un oggetto rappresentante le opzioni. Oltre a quelle appena elencate eredidate da XHR, la classe Ajax definisce le seguenti:

• data: i dati da inviare al server. Nell'esempio vedremo cosa possiamo inserire oltre alle querystring ed agli oggetti;
• update: l'elemento in cui visualizzare il contenuto della risposta del server quando la richiesta viene completata;
• evalScripts: esegue gli script presenti nella risposta se impostato a true (default false);
• evalResponse: forza l'esecuzione dell'intera risposta indipendemente dal Content-Type, se impostato a true (default false);
• onComplete: funzione da eseguire quando la richiesta viene completata.

Mentre per quanto riguarda i metodi abbiamo a disposizione:

• request (data): il metodo principale che invia la richiesta al server utilizzando le funzionalità del metodo send;
• getHeader (header): restituisce il valore dell'intestazione di risposta desiderata;
• evalScripts: esegue gli script presenti nella risposta.

Primo esempio: una semplice richiesta

Ora che abbiamo una panoramica completa riguardante XHR e Ajax possiamo passare alla creazione di esempi pratici.

In questo primo esempio creeremo una semplice richiesta al server, mostreremo un alert che ci avvisa del completamento dell'operzione e un avvertimento in caso la richiesta dovesse fallire:

		var ajax = new Ajax('mypage_1.php', {
			method: 'post',
			update: $('update'),
			onComplete: function() {
				alert("Richiesta completata!");
			},
			
			onFailure: function() {
				alert("Non è stato possibile eseguire la richiesta correttamente");
			}
		});
		
		// ora effettuiamo la richiesta
		ajax.request();
	

Secondo esempio: richiesta completa

In questo secondo esempio effettueremo una richiesta completa di tutte le sue componenti principali. Verrà mostrata la scritta "Loading..." mentre la richiesta è in corso e al completamento verrà mostrato tutto il contenuto della risposta restituito dal server:

	// struttura della nostra richiesta
	var ajax = new Ajax('mypage_2.php', {
		update: $('update'),
		onRequest: function() {
			this.options.update.setHTML("Loading...");
		},
		onComplete: function(text) {
			alert("Complete! " + text);
		},
		onFailure: function() {
			alert("Non è stato possibile eseguire la richiesta correttamente");
		}
	});
	
	// agganciamo l'evento all'invio del form
	$('send').addEvent('submit', function(event) {
		var event = new Event(event).stop();
		ajax.request();
	});
	

Terzo esempio: eseguire gli scripts

Ora che abbiamo visto come inviare richieste al server in due applicazioni pratiche, vediamo come eseguire gli script che potrebbero essere contenuti nella risposta. Come affermato nella stesura delle opzioni, occore impostare a true il valore di evalScript:

	var ajax = new Ajax(url || 'mypage_3.php', {
		update: $('update'),
		evalScripts: true,
		onRequest: function() {
			this.options.update.setHTML("Loading...");
		},
		onFailure: function() {
			alert("Non è stato possibile eseguire la richiesta correttamente");
		}
	});
	
	// settiamo sempre l'evento per azionare la richiesta
	$('send').addEvent('submit', function(event) {
		var event = new Event(event).stop();
		ajax.request();
	});
	

In questo modo se la pagina che andiamo a richiamare, in questo caso mypage_3.php, contiene del codice Javascript,
esso non verrà stampato come semplice testo o come nuovo elemento script inserito nella pagina, ma verrà eseguito come normale codice Javascript.

Quarto esempio: start/cancel

In questo esempio viene fornita una pulsantiera che permette di inviare e cancellare la richiesta, e di osservare se quest'ultima è in corso e di ottenere messaggi pertinenti. Ecco il codice:

	// url
	var url = $('send').getProperty("action");
		
	// struttura della richiesta 
	var ajax = new Ajax(url || 'mypage_4.php', {
		update: $('update'),
		evalScripts: true,
		onRequest: function() {
			if(this.running) this.options.update.setHTML("<img src='loading.gif' alt='' />");
			$('running').setHTML('Richiesta in corso');
		},
		onFailure: function() {
			$('running').setHTML('Richiesta fallita');
			alert("Non è stato possibile eseguire la richiesta correttamente");
		},
		onCancel:function() {
			this.options.update.setHTML("Richiesta interrotta");
			$('running').setHTML('');
			alert("Richiesta interrotta");
		},
		onComplete: function() {
			$('running').setHTML('');
		}
	});
	
	// evento che gestisce l'invio del form
	$('send').addEvent('submit', function(event) {
		var event = new Event(event).stop();
		ajax.request();
	});
	
	// evento che gestisce la cancellazione della richiesta
	$('cancel').addEvent('click', function(event) {
		var event = new Event(event).stop();
		ajax.cancel();
	});
	});
	

Quinto esempio: riunire gli input value di un form

In quest'ultimo esempio vedremo come riunire i dati di un form e inviarli al server, il tutto in maniera molto semplice:

	var ajax = new Ajax(url || 'mypage_5.php', {
			update: $('update'),
			data: $("send"),
			onRequest: function() {
				this.options.update.setHTML("<img src='loading.gif' alt='' />");
				$('running').setHTML('Richiesta in corso');
			},
			onFailure: function() {
				$('running').setHTML('Richiesta fallita');
				alert("Non è stato possibile eseguire la richiesta correttamente");
			},
			onCancel:function() {
				this.options.update.setHTML("Richiesta interrotta");
				$('running').setHTML('');
				alert("Richiesta interrotta");
			},
			onComplete: function() {
				$('running').setHTML('');
			}
		});
		
		// il form con id 'send' che abbiamo utilizzato per impostare il corpo della richiesta
		$('send').addEvent('submit', function(event) {
			var event = new Event(event).stop();
			ajax.request();
		});
	

Basta impostare all'opzione 'data' l'id del form con la funzione $, e tutti gli input values verranno elaborati automaticamente per formare la querystring da inviare. È possibile in alternativa utilizzare i metodi del
file Element.Form, come toQueryString, che svolgono la medesima operazione ma in modo sintatticamente differente.

Ecco tutte le cinque demo presenti in questo articolo pronte per il download, con tutte le
relative pagine in formato php che forniscono le risposte del server.

Demo ufficiali

Per avere una panoramica ancora più ampia di cosa è possibile fare con la classe Ajax, consiglio la lettura delle demo ufficiali presenti nella sezione demos di MooTools:

• Ajax
• Ajax Advanced
• Ajax.Form
• Ajax.Timed

Questi esempi sono scritti davvero bene e mostrano le più svariate operazioni avanzate che si possono effetuare con le classi XHR e Ajax.

Download e compatibilità

Come accennato in precendeza, per effettuare richieste asincrone con MooTools sono necessari i seguenti file:

• sezione Core (Core)
• sezione Class (Class, Class.Extras)
• sezione Native (Array, String, Function, Number, Element)
• sezione Element (Element.Form)
• sezione Remote (XHR, Ajax)

Includendo questi componenti si ottiene un framework Ajax davvero completo.

Come sempre, è un ottima tecnica includere questi file in uno script separato, chiamato ad esempio mootools_ajax.js. Se successivamente avremo bisogno di creare qualche effetto, scaricheremo i file occorrenti e includeremo mootools_effects.js (attenzione a non duplicare l'inserimento dei file Core, Native e cosi via. A questo proposito consiglio di riunire in un file base tutti questi componenti e successivamente scaricare quelli avanzati necessari), in modo da ottenere un'applicazione modulare con un peso non più elevato del necessario.

Ricordo che questo tutorial è relativo alla versione 1.1 di MooTools. Nella versione 1.2 le classi XHR e Ajax verranno sostituite rispettivamente dai costruttori Request e Request.HTML. Questi svolgono funzionalità parecchio simili, inserendo potenzialità aggiuntive e migliorie in termini di compattezza e strutturazione del codice.

Json.Remote e Request.Json

XHR e Ajax non sono le uniche due classi che MooTools ci fornisce per contattare il server. Esiste un terzo costruttore chiamato Json.Remote (che verrà sostituito da Request.Json nella versione 1.2) che estende XHR e permette di inviare e ricevere oggetti Javascript nel formato Json.

Conclusione

In questo articolo abbiamo esaminato dettagliatamente tutta la struttura e i componenti delle classi XHR e Ajax che costituiscono il framework MooTools per effettuare richieste asincrone al server. Abbiamo visto tutta l'elasticità e la semplicità offerte dalla libreria, che ha saputo offrire una risposta valida alle molte e ottime soluzioni che è possibile ottenere con altri framework.