bloggers bloggers

Il modulo di YUI 3 denominato io consente di gestire le richieste Http sincrone e asincrone. Può fare molte cose, oltre alle ormai usatissime chiamate ajax : è in grado ad esempio di inviare i dati di un form html serializzati, eseguire upload di file, code di transazioni asincone, transazioni “cross-domain” (utilizzando Flash ...si, proprio flash, al posto dell'oggetto XMLHttpRequest che supporta solo transazioni all'interno dello stesso dominio), ed è provvista di un set di eventi custom che si occupano di gestire la transazione con il server.

Il modulo – vista anche la sua complessità- è diviso in diverse “sottolibrerie” in grado di gestire atomicamente le funzionalità sopra descritte.
Eccellenti funzionalità e grande flessibilità al costo di un complessità di utilizzo non banale.

Vediamo di capire il più possibile, fornendo qualche esempio di utilizzo, rimandando all'url di yui3 per ulteriori approfondimenti.


Cominciamo con il descrivere il metodo io(), il metodo principale per eseguire richieste http. Il metodo accetta 2 parametri :

1. un url per la transazione
2. un oggetto literal di configurazione (opzionale)

Vediamo un esempio semplice di transazione asincrona che NON utilizza il secondo parametro, ma soltanto il primo :

YUI().use("io-base", function(Y) {

var uri = "get.php?foo=bar";

// funzione di callback.
function complete(id, o, args) {
var id = id; // Transaction ID.
var data = o.responseText; // Response data.
var args = args[1]; // 'ipsum'.
};

// registra un evento
Y.on('io:complete', complete, Y, ['lorem', 'ipsum']);

//esegue la chiamata HTTP al 'get.php'.
var request = Y.io(uri);
});

La prima parte dello script non è difficile : viene definita una variabile che contiene l'url da invocare e viene definita una funzione. Questa funzione -qui viene il bello- viene passata al metodo on() descritto nell'articolo precedente di introduzione a YUI 3, nella parte riguardante la gestione degli eventi.


La risposta che il server ci invia in risposta sarà un oggetto composto dalle seguenti proprietà :

1. status lo status code HTTP di questa transazione
2. statusText HTTP status message.
3. getResponseHeader(headername) Una funzione che ritorna il valore dell'header HTTP passato come parametro.
4. getAllResponseHeaders() Funzione che ritorna gli headers HTTP. responseText
5. responseText corpo della risposta ritornata dal server
6. responseXML corpo della risposta ritornata dal server come documento XML.

Il modulo io è fornito una serie di eventi custom che definiscono un momento preciso della transazione. Eccoli in dettaglio :

1. io:start : viene triggerato quando inizia una transazione
2. io:complete : viene triggerato quando la transazione è completa e sono disponibili i dati inviati dal server
3. io:success : viene triggerato ogni volta che una chiamata è andata a buon fine (SE L'HEADER HTTP STATUS == 2XX)
4. io:failure : viene triggerato ogni volta che una chiamata non è andata a buon fine (SE L'HEADER HTTP STATUS == 4XX OR 5XX )
5. io:end : viene triggerato alla fine di una transazione
6. io:xdrReady : viene triggerato quando l'oggetto flash utilizzato per le transazioni cross-domani è pronto all'uso
   
   

Nel nostro esempio, alla riga

Y.on('io:complete', complete, Y, ['lorem', 'ipsum']);

viene invocato il metodo on() e gli vengono passati 4 parametri :

1. 'io:complete' - il tipo di evento a cui vogliamo sottoscrivere la nostra funzione
2. il riferimento alla funzione di callback che volgiamo venga eseguita sull'evento
3. L'oggetto YUI stesso, al quale possiamo riferirci all'interno della funzione di callback.
4. Una serie di parametri che verranno passati alla funzione di callback che abbiamo difinito. Nel nostro esempio il quarto parametro è un array.
   

L'ultima riga dello script esegue la chiamata invocando il metodo io(), passando l'url come parametro.


Aumentiamo un po' la complessità mostrando qualche esempio di ulitizzo di io() passando anche un secondo parametro, ovvero l'oggetto literal di configurazione.
Questo oggetto, ci consente una configurazione capillare di tutto ciò che succede all’interno della transazione.
Per esempio possiamo decidere se la transazione con il server deve essere sincrona o asincrona; oppure, attraverso la proprietà chiamata ‘method’, possiamo specificare se la transazione deve avvenire tramite ‘get’o ‘post’,
inviando gli eventuali parametri come parte dell’url, o come corpo della richiesta.
L'oggetto 'on' -composto a sua volta di altri oggetti literal - ci permette di specificare il tipo di evento e la funzione di callback
da eseguire quando l'evento stesso viene scatenato. L'oggetto 'arguments' ci consente invece di costruire un oggetto che verrà passato alle funzioni di callback che abbiamo definito.

Ecco un breve esempio di come possiamo costruire questo oggetto :

var config = {
sync : true,
method : ‘POST’,
on : {
complete : function() {
//codice
},
start : function() {
// codice
}
},
arguments: {
param1 : 'pippo',
param2 : function() {
//codice
}
}
};



Vediamo adesso un esempio molto interessante che ci consente di inviare i campi di un form serializzati in una stringa, contenente coppie di parametri
in forma chiave-valore, e di agganciarli al nostro url (nel caso di una transazione ‘get’ ), oppure di inviarli insieme al corpo della risposta ( nel caso di ‘post’).
Per realizzare questa interessante funzionalità utilizziamo il modulo 'io-form' insieme ad altre proprietà dell’oggetto literal di configurazione :

YUI().use("io-form", function(Y) {

// popoliamo l’oggetto di configurazione
var cfg = {
method: 'POST',
form: {
id: <formObject>,
useDisabled: true
}
};

// Definiamo una funzione di callback...
function complete(id, o, args) {
var id = id; // Transaction ID.
var data = o.responseText; // Response data.
var argomenti = args.foo; // 'bar'.
};

// Subscribe to event "io:complete", and pass an array
// as an argument to the event handler "complete".
Y.on('io:complete', complete, Y, { 'foo':'bar' });

// Start the transaction.
var request = Y.io(uri, cfg);
});

L’oggetto‘form’espone due proprietà, una che indica l’id del form da serializzare; l’altra proprietà booleana ‘useDisabled’, indica invece se serializzare
anche i campi del form disabilitati. Il codice è quasi analogo a quello dell'esempio, precedente. Quello che cambia è ovviamente l'oggetto literal di configurazione.

Vediamo un ultimo esempio - non meno interessante - che consente di inviare un file in upload. L'oggetto di configurazione è simile al precedente, ma dietro le quinte il modulo "io-upload-iframe"
che utilizziamo si servirà di un iframe per inviare al server il file che vogliamo caricare. Ecco il codice :


YUI().use("io-upload-iframe", function(Y) {

// costruiamo l'oggetto literal di configurazione settando a true
// la proprietà upload dell'oggetto 'form' interno
var cfg = {
method: 'POST',
form: {
id: formObject,
upload: true
}
};

// callback
function start(id, args) {
var id = id; // Transaction ID.
var args = args.foo; // 'bar'
}

// callback
function complete(id, o, args) {
var id = id; // Transaction ID.
var data = o.responseText; // Response data.
var args = args[1]; // 'ipsum'.
};

// sottoscrivo la mia funzione all' evento onstart
Y.on('io:start', start, Y, { 'foo':'bar' });

// sottoscrivo la mia funzione all' evento on complete
Y.on('io:complete', complete, Y, ['lorem', 'ipsum']);

// parte la transazione
var request = Y.io(uri, cfg);
});

Alla prossima !