jQuery.ajax()

La funzione $.ajax() è alla base di tutte le richieste Ajax inviate da jQuery. Spesso non è necessario chiamare direttamente questa funzione, poiché sono disponibili diverse alternative di livello superiore come $.get() e .load() che sono più facili da usare. Se però sono richieste opzioni meno comuni, $.ajax() può essere usato in modo più flessibile.

Nella sua forma più semplice, la funzione $.ajax() può essere chiamata senza argomenti:

$.ajax();

Nota: Le impostazioni predefinite possono essere impostate globalmente utilizzando la funzione $.ajaxSetup().

Questo esempio, senza opzioni, carica il contenuto della pagina corrente, ma non fa nulla con il risultato. Per usare il risultato, si può implementare una delle funzioni di callback.

L’oggetto jqXHR

L’oggetto jQuery XMLHttpRequest (jqXHR) restituito da $.ajax() a partire da jQuery 1.5 è un superset dell’oggetto XMLHttpRequest nativo del browser. Per esempio, contiene le proprietà responseText e responseXML, così come un metodo getResponseHeader(). Quando il meccanismo di trasporto è qualcosa di diverso da XMLHttpRequest (per esempio, un tag script per una richiesta JSONP) l’oggetto jqXHR simula le funzionalità XHR native dove possibile.

A partire da jQuery 1.5.1, l’oggetto jqXHR contiene anche il metodo overrideMimeType() (era disponibile anche in jQuery 1.4.x, ma è stato temporaneamente rimosso in jQuery 1.5). Il metodo .overrideMimeType() può essere usato nella funzione di callback beforeSend(), per esempio, per modificare l’intestazione content-type della risposta:

Gli oggetti jqXHR restituiti da $.ajax() da jQuery 1.5 implementano l’interfaccia Promise, dando loro tutte le proprietà, i metodi e il comportamento di una Promise (vedi oggetto Deferred per maggiori informazioni). Questi metodi prendono uno o più argomenti di funzione che vengono chiamati quando la richiesta $.ajax() termina. Questo permette di assegnare più callback su una singola richiesta, e anche di assegnare callback dopo che la richiesta potrebbe essere stata completata. (Se la richiesta è già completa, il callback viene sparato immediatamente.) I metodi Promise disponibili dell’oggetto jqXHR includono:

Il riferimento this all’interno di tutte le callback è l’oggetto nell’opzione context passata a $.ajax nelle impostazioni; se context non è specificato, this è un riferimento alle impostazioni Ajax stesse.

Per compatibilità con XMLHttpRequest, un oggetto jqXHR esporrà le seguenti proprietà e metodi:

• readyState
• responseXML e/o responseText quando la richiesta sottostante risponde con xml e/o testo, rispettivamente
• status
• statusText (può essere una stringa vuota in HTTP/2)
• abort( )
• getAllResponseHeaders() come stringa
• getResponseHeader( name )
• overrideMimeType( mimeType )
• setRequestHeader( name, value ) che si discosta dallo standard sostituendo il vecchio valore con quello nuovo piuttosto che concatenare il nuovo valore al vecchio
• statusCode( callbacksByStatusCode )

Non viene fornito alcun meccanismo onreadystatechange, tuttavia, poiché donefailalways, e statusCode coprono tutte le esigenze possibili.

Code di funzioni di callback

I beforeSenderrordataFiltersuccess e complete opzioni accettano tutte funzioni di callback che vengono invocate al momento opportuno.

A partire da jQuery 1.5, le opzioni fail e done, e, a partire da jQuery 1.6, always gli hook di callback sono first-in, first-out managed queues, permettendo più di un callback per ogni hook. Vedere i metodi Deferred object, che sono implementati internamente per questi $.ajax() hook di callback.

Gli agganci di callback forniti da $.ajax() sono i seguenti:

1. beforeSend viene invocata l’opzione callback; essa riceve l’oggetto jqXHR e l’oggetto settings come parametri.
2. error opzione callback è invocata, se la richiesta fallisce. Riceve il jqXHR, una stringa che indica il tipo di errore e un oggetto eccezione, se applicabile. Alcuni errori incorporati forniranno una stringa come oggetto di eccezione: “abort”, “timeout”, “No Transport”.
3. dataFilter l’opzione di callback viene invocata immediatamente dopo aver ricevuto con successo i dati della risposta. Riceve i dati restituiti e il valore di dataType, e deve restituire i dati (eventualmente alterati) da passare a success.
4. success opzione callback è invocata, se la richiesta ha successo. Riceve i dati restituiti, una stringa contenente il codice di successo e l’oggetto jqXHR.
5. Le callback Promise – .done().fail().always(), e .then() – sono invocate, nell’ordine in cui sono registrate.
6. complete opzione callback scatta, quando la richiesta termina, sia in caso di fallimento che di successo. Riceve l’oggetto jqXHR, così come una stringa contenente il codice di successo o di errore.

Tipi di dati

Diversi tipi di risposta alla chiamata $.ajax() sono sottoposti a diversi tipi di pre-elaborazione prima di essere passati al gestore di successo. Il tipo di pre-elaborazione dipende per default dal Content-Type della risposta, ma può essere impostato esplicitamente usando l’opzione dataType. Se l’opzione dataType è fornita, l’intestazione Content-Type della risposta sarà ignorata.

I tipi di dati disponibili sono texthtmlxmljsonjsonp, e script.

Se viene specificato text o html, non avviene alcuna pre-elaborazione. I dati vengono semplicemente passati al gestore di successo e resi disponibili attraverso la proprietà responseText dell’oggetto jqXHR.

Se viene specificato xml, la risposta viene analizzata usando jQuery.parseXML prima di essere passata, come XMLDocument, al gestore del successo. Il documento XML è reso disponibile attraverso la proprietà responseXML dell’oggetto jqXHR.

Se viene specificato json, la risposta viene analizzata usando jQuery.parseJSON prima di essere passata, come oggetto, al gestore del successo. L’oggetto JSON analizzato è reso disponibile attraverso la proprietà responseJSON dell’oggetto jqXHR.

Se script è specificato, $.ajax() eseguirà il JavaScript ricevuto dal server prima di passarlo al gestore di successo come stringa.

Se viene specificato jsonp$.ajax() aggiungerà automaticamente un parametro di query string (per default) callback=? all’URL. Le proprietà jsonp e jsonpCallback delle impostazioni passate a $.ajax() possono essere usate per specificare, rispettivamente, il nome del parametro della query string e il nome della funzione di callback JSONP. Il server dovrebbe restituire un JavaScript valido che passi la risposta JSON nella funzione di callback. $.ajax() eseguirà il JavaScript restituito, chiamando la funzione di callback JSONP, prima di passare l’oggetto JSON contenuto nella risposta al gestore di successo $.ajax().

Per maggiori informazioni su JSONP, si veda il post originale che ne descrive l’uso.

Invio di dati al server

Di default, le richieste Ajax sono inviate utilizzando il metodo HTTP GET. Se è richiesto il metodo POST, il metodo può essere specificato impostando un valore per l’opzione type. Questa opzione influisce su come il contenuto dell’opzione data viene inviato al server. I dati POST saranno sempre trasmessi al server usando il charset UTF-8, secondo lo standard W3C XMLHTTPRequest.

L’opzione data può contenere sia una query string della forma key1=value1&key2=value2, sia un oggetto della forma {key1: 'value1', key2: 'value2'}. Se viene utilizzata quest’ultima forma, i dati vengono convertiti in una stringa di query utilizzando jQuery.param() prima di essere inviati. Questa elaborazione può essere aggirata impostando processData a false. L’elaborazione potrebbe essere indesiderata se si desidera inviare un oggetto XML al server; in questo caso, cambiare l’opzione contentType da application/x-www-form-urlencoded a un tipo MIME più appropriato.

Opzioni avanzate

L’opzione global impedisce ai gestori registrati usando .ajaxSend().ajaxError(), e metodi simili di attivarsi quando questa richiesta li attiverebbe. Questo può essere utile, per esempio, per sopprimere un indicatore di caricamento che è stato implementato con .ajaxSend() se le richieste sono frequenti e brevi. Con lo script cross-domain e le richieste JSONP, l’opzione globale è automaticamente impostata su false. Vedere le descrizioni di questi metodi qui sotto per maggiori dettagli.

Se il server esegue l’autenticazione HTTP prima di fornire una risposta, la coppia nome utente e password può essere inviata tramite le opzioni username e password.

Le richieste Ajax sono limitate nel tempo, quindi gli errori possono essere catturati e gestiti per fornire una migliore esperienza utente. I timeout delle richieste sono solitamente lasciati al loro valore predefinito o impostati come predefiniti globali usando $.ajaxSetup() piuttosto che essere sovrascritti per richieste specifiche con l’opzione timeout.

Per impostazione predefinita, le richieste sono sempre emesse, ma il browser può servire i risultati dalla sua cache. Per non permettere l’uso dei risultati della cache, impostare cache a false. Per far sì che la richiesta riporti un fallimento se la risorsa non è stata modificata dall’ultima richiesta, impostare ifModified a true.

Il scriptCharset permette di specificare esplicitamente il set di caratteri per le richieste che utilizzano un tag <script> (cioè un tipo di script o jsonp). Questo è utile se lo script e la pagina host hanno set di caratteri diversi.

La prima lettera di Ajax sta per “asincrono”, il che significa che l’operazione avviene in parallelo e l’ordine di completamento non è garantito. L’opzione async per $.ajax() è di default true, indicando che l’esecuzione del codice può continuare dopo la richiesta. Impostare questa opzione su false (e quindi rendere la chiamata non più asincrona) è fortemente sconsigliato, in quanto può causare la mancata risposta del browser.

La funzione $.ajax() ritorna l’oggetto XMLHttpRequest che crea. Normalmente jQuery gestisce la creazione di questo oggetto internamente, ma una funzione personalizzata per produrne uno può essere specificata usando l’opzione xhr. L’oggetto restituito può essere generalmente scartato, ma fornisce un’interfaccia di livello inferiore per osservare e manipolare la richiesta. In particolare, chiamando .abort() sull’oggetto si arresterà la richiesta prima che venga completata.

Estendere Ajax

A partire da jQuery 1.5, l’implementazione Ajax di jQuery include prefiltri, trasporti e convertitori che permettono di estendere Ajax con una grande flessibilità.

Utilizzare i convertitori

$.ajax() i convertitori supportano la mappatura dei tipi di dati in altri tipi di dati. Se, tuttavia, si vuole mappare un tipo di dati personalizzato su un tipo conosciuto (ad esempio json), è necessario aggiungere una corrispondenza tra il Content-Type della risposta e il tipo di dati effettivo usando l’opzione contents:

Questo oggetto extra è necessario perché i Content-Types della risposta e i tipi di dati non hanno mai una stretta corrispondenza uno-a-uno (da qui l’espressione regolare).

Per convertire da un tipo supportato (es.g textjson) a un tipo di dati personalizzato e viceversa, utilizzare un altro convertitore pass-through:

Questo permette ora di passare da text a mycustomtype e poi mycustomtype a json.