Interfeţe Web

La fel cum MooTools avea un mod generic de a face cereri AJAX, dar si cateva scurtaturi pentru cazuri comune, la fel si jQuery ne ofera un mod generic si cateva scurtaturi.

In cazul cel mai generic, se foloseste metoda ajax din namespace-ul jQuery/$: $.ajax, care primeste ca parametru un hash de optiuni (cele mai multe asemanatoare cu cele de la MooTools) si intoarce instanta de XHR folosita pentru cererea creata (dar care in mod normal nu va fi folosita decat daca se vrea revocarea manuala a cererii – de exemplu la interactiunea cu utilizatorul). Aceste optiuni (vezi si documentatia) sunt:

• url reprezinta URL-ul catre care se face cererea
• type reprezinta tipul de cerere care se va face catre server (in mod uzual, GET sau POST). Implicit are valoarea 'GET'
• data sunt datele ce vor fi trimise in cererea AJAX. Poate fi un query string, sau un hash care va fi transformat in query string
• async, un boolean setat la true daca cererea va fi facuta asincron sau false altfel; implicit este true
• dataType este un string care spune ce tip de raspuns asteptam de la server. Valorile pentru aceasta optiune ar trebui sa fie dintre urmatoarele: 'xml' (daca raspunsul asteptat este un XML), 'html' (daca raspunsul asteptat este un fragment de cod HTML; orice taguri script din raspuns sunt evaluate daca acest fragment este inserat in DOM), 'script' (daca asteptam cod JavaScript), 'json' (daca asteptam date in formatul JSON), 'jsonp' (daca cererile se fac catre un server altul decat al site-ului nostru si se foloseste JSONP) sau 'text' (daca raspunsul asteptat este pur si simplu text, fara sa aiba un format anume)
• cache este un boolean care spune daca datele primite vor fi cache-uite sau nu. Implicit este true (deci vor fi cache-uite) pentru orice dataType diferit de 'script' si false daca dataType este 'script'
• timeout reprezinta intervalul de timp, in milisecunde, cat se asteapta raspunsul de la server. Daca serverul nu raspunde dupa acest interval de timp, cererea este anulata si se apeleaza functiile error si complete
• jsonp este un string care da numele parametrului din query string pentru functia de callback, in cazul in care se face o cerere JSONP (nu este nevoie de numele functiei pentru ca obiectul intors de raspuns este transmis ca parametru functiei success – in schimb se foloseste ? pe post de nume al functiei si jQuery completeaza automat acest parametru; de exemplu daca vrem sa transmitem un parametru nume si numele parametrului pentru functia de callback este callback, optiunea data ar putea avea valoarea 'http://www.exemplu.com/script.php?nume=Test&callback=?')
• contentType este un string care seteaza header-ul Content-Type al cererii. Implicit este 'application/x-www-form-urlencoded' (ceea ce ar trebui sa fie ok pentru majoritatea cererilor)
• scriptCharset este un string care spune care este setul de caractere al raspunsului pentru cererile de tip script/jsonp, si este necesar daca setul de caractere din raspuns este diferit de cel al documentului curent
• dataFilter este o functie care va procesa raspunsul primit de la server si va intoarce raspunsul procesat. Acesta va fi raspunsul folosit in toate celelalte functii care folosesc raspunsul de la server. Functiei ii sunt transmisi ca parametri datele primite de la server si tipul datelor (optiunea dataType de care am vorbit mai sus).
• global, un boolean care spune daca vor fi generate evenimentele globale (vom vorbi de acestea mai jos). Implicit este true si evenimentele vor fi generate
• ifModified, un boolean care, daca e setat la true (iar implicit e false), spune ca cererea ar trebui sa se incheie cu eroare daca raspunsul nu a fost modificat de la ultima cerere, prin verificarea headerului Last-Modified.
• username, password sunt doi parametri folositi pe post de username si parola, daca URL-ul la care se face cererea are nevoie de autentificare HTTP
• processData este un boolean (implicit true) care spune daca, atunci cand optiunea data nu este un string ci un obiect, acesta ar trebui sau nu convertit intr-un query string
• beforeSend, o functie care este apelata inainte ca cererea sa fie trimisa catre server. Acesteia ii este transmis un singur parametru, instanta de XHR care va fi folosita pentru a face cererea AJAX. Daca vrem sa setam headere pentru cererea noastra, aici ar trebui setate. De asemenea, poate dorim sa anulam cererea – pentru aceasta este suficient sa returnam false din aceasta functie. Contextul functiei este hash-ul de optiuni ale cererii AJAX.
• complete este o functie care este apelata daca cererea s-a terminat. Ii sunt trimisi 2 parametri: instanta de XHR cu care a fost facuta cererea, si un string ce descrie status-ul cererii. Contextul functiei este hash-ul de optiuni ale cererii AJAX. Aceasta functie este apelata dupa ce au fost apelate functiile pentru cerere efectuata sau nu cu succes (adica optiunile success si error)
• error este o functie care va fi apelata daca cererea s-a terminat cu esec. Contextul functiei este hash-ul de optiuni al cererii AJAX. Parametrii transmisi sunt instanta XHR, textul care descriere status-ul cererii (si care poate fi "timeout" – daca cererea a depasit timpul setat ca timeout -, "error" – daca a fost vorba de o eroare de la server -, "notmodified" – daca raspunsul primit a fost not modified (deci s-a folosit optiunea ifModified) – sau "parsererror" – daca a aparut o eroare la procesarea datelor primite) si, optional, exceptia care a fost aruncata la eroare (daca a existat o astfel de exceptie)
• success este o functie care este apelata atunci cand cererea a fost efectuata cu succes. Ii sunt trimisi 2 parametri: datele primite de la server, procesate (deci daca am primit date in format JSON, parametrul va fi un obiect; daca am primit xml, va fi un document xml, daca am primit text va fi un string etc.), si un string care descrie statusul cererii (si care va fi intotdeauna success)
• xhr reprezinta o functie care va fi apelata pentru a obtine instanta de XHR cu care se face cererea.

Este posibil sa setam valori implicite pentru toate cererile AJAX prin intermediul metodei ajaxSetup ($.ajaxSetup) care primeste acelasi hash ca si $.ajax, insa de aceasta data optiunile transmise ca parametri vor fi cele implicite, pentru orice cerere AJAX care va fi facuta dupa apelul acestei metode.

Cat despre evenimentele globale de care vorbeam mai sus, ar trebui spuse urmatoarele: in jQuery exista doua tipuri de evenimente care pot fi declansate atunci cand se fac cereri AJAX: evenimente locale (atasate cererii) si evenimente globale (pe care le vor primi toate elementele din DOM care au atasati ascultatori la astfel de evenimente). Evenimentele locale sunt cele de care am vorbit mai sus: functiile care sunt apelate inainte sau dupa ce s-a facut cererea AJAX: beforeSend, complete, success, error. Evenimentele globale se ataseaza elementelor din dom la fel ca orice alt tip de eveniment, si sunt:

• ajaxStart, care este declansat atunci cand nu este in curs nicio alta cerere AJAX si inainte ca cererea care a generat evenimentul sa fie transmisa
• ajaxSend, care este declansat inainte sa fie transmisa o noua cerere AJAX (deosebirea fata de tipul anterior este ca acest eveniment se va declansa chiar daca erau alte cereri in curs)
• ajaxComplete, care este declansat cand o cerere AJAX s-a incheiat (cu succes sau nu)
• ajaxSuccess, care este declansat cand o cerere AJAX s-a incheiat cu succes
• ajaxError, care este declansat cand o cerere AJAX s-a incheiat fara succes
• ajaxStop, care este declansat atunci cand nu mai exista nicio cerere AJAX in curs de procesare

Cat despre ajutorul pe care il ofera jQuery pentru cazuri comune de utilizare, avem la dispozitie urmatoarele:

• $().load trimite o cerere la server, iar raspunsul primit il injecteaza in fiecare element din setul jQuery. Primeste 3 parametri: primul, URL-ul la care se face cererea – acesta este un string care poate contine si un selector CSS dupa care va fi filtrat HTML-ul din raspuns (selectorul CSS ar trebui sa fie separat de URL printr-un spatiu); al doilea, optional, un hash care va fi transformat in query string si va fi trimis serverului; al treilea, tot optional, este o functie care va fi apelata cand cererea s-a terminat (cu succes sau nu) si care va primi ca parametri raspunsul de la server, un string care descrie statusul cererii, si instanta de XHR cu care s-a facut cererea (contextul acestei functii va fi elementul curent din set)
• $.get, $.post sunt niste scurtaturi pentru a face cereri cu GET/POST fara a avea nevoie de optiuni avansate ca la $.ajax. Primeste ca parametri: URL-ul la care se face cererea (singurul parametru obligatoriu), un hash de date care va fi transformat intr-un query string, o functie care va fi apelata daca cererea s-a terminat cu succes (si care primeste ca parametri raspunsul serverului si un string care descrie statusul cererii – dar care va fi intotdeauna 'success'; datele sunt in functie de tipul de raspuns asteptat, la fel ca la $.ajax) si un string care reprezinta tipul de date asteptat de la server (vezi optiunea dataType de la $.ajax)
• $.getJSON face o cerere catre un URL si asteapta sa primeasca date in format JSON (este posibil sa se faca cereri catre un alt server decat cel curent, cu JSONP). Metoda primeste 3 parametri, dintre care doar primul este obligatoriu: URL-ul la care se face cererea (si care spuneam ca poate fi extern; daca serverul la care suporta cererea suporta JSONP, numele functiei de callback ar trebui sa fie ? – astfel va fi apelata functia de succes), un hash cu date ce va fi convertit la query string si o functie ce va fi apelata daca cererea s-a terminat cu succes, care va primi ca parametri obiectul intors de cerere si un string care descrie statusul cererii (dar care va fi intotdeauna 'success').
• $.getScript face o cerere catre server si asteapta ca raspuns cod JavaScript (cererea poate fi facuta si catre un server extern), pe care il executa. Primeste 2 parametri: URL-ul la care se va face cererea, si, optional, o functie care va fi apelata daca cererea s-a efectuat cu succes (si care primeste ca parametri un string – codul JS intors de server – si un string care descrie status-ul, dar care va fi intotdeauna 'success')

Ultimele doua metode care ajuta la cereri AJAX, sunt:

• $().serialize(), care intoarce un query string bazat pe valorile tuturor elementelor de tip form input (input, textarea, select) care au un atribut name
• $().serializeArray() lucreaza la fel ca $().serialize dar nu intoarce un query string, ci un vector de obiecte – folositor pentru lucrul cu date in format JSON

Articolul de azi a fost lipsit de exemple (desi sunt destule pe paginile de documentatie), insa urmatoarele cateva articole vor fi punerea in practica a tot ce am invatat pana acum despre MooTools si jQuery.

The Framework-uri JavaScript: AJAX cu jQuery by Interfeţe Web, unless otherwise expressly stated, is licensed under a Creative Commons Attribution-Share Alike 3.0 Romania License.