Interfeţe Web

Constructorul lui Request primeste un singur parametru, optional, care este un hash de optiuni, dintre care cele mai importante sunt:

• url, un string care reprezinta adresa la care se face cererea (implicit este null)
• method, un string care reprezinta metoda cu care se va face cererea (in mod uzual, post sau get; implicit, este post)
• data, un string care contine datele care vor fi trimise in mod implicit (vom vedea imediat ce inseamna asta), sau un hash de perechi cheie-valoare care vor fi transformate intr-un query string – si care implicit este null
• link, un string care spune cum se va comporta o instanta de Request atunci cand este in mijlocul unei cereri si este facuta o noua cerere. Cele 3 valori posibile sunt:
  • ignore – valoarea implicita – spune ca noua cerere va fi pur si simplu ignorata
  • cancel va revoca cererea care se petrecea si va trimite cea mai recenta cerere
  • chain spune ca noua cerere va fi inlantuita de orice alte cereri existente in acel moment – cererile vor fi puse intr-o coada de asteptare si vor fi facute una dupa ce se termina precedenta
• async este un boolean – implicit true – care spune daca cererea va fi facuta asincron sau nu (vezi discutia de la Introducere in AJAX)
• headers – un hash de headere care vor fi setate pentru cerere
• evalScripts este un boolean – implicit true – care spune daca codul din tagurile <script> ale raspunsului va fi executat

Restul optiunilor sunt explicate pe pagina de documentatie oficiala.

Daca atunci cand foloseam XMLHttpRequest-ul nativ aveam la dispozitie o singura metoda – onreadystatechange – in care trebuia sa tratam atat cazurile de eroare cat si cazurile de succes, MooTools ne pune la dispozitie cativa ascultatori de evenimente pentru cele mai comune cazuri (si care pot fi adaugati ca orice ascultatori de evenimente in MooTools, sau chiar ca in cazul DOM0: cerere.onComplete = function() {...}):

• request, complete, cancel sunt declansate cand cererea este trimisa / s-a terminat / a fost revocata. Oricare dintre cele 3 va fi o functie careia nu ii este transmis niciun parametru.
• success este declansat cand cererea s-a terminat cu succes (deci daca sunt atasati ascultatori atat la complete, cat si la success, sunt apelati toti ascultatorii la amandoua tipurile de evenimente). Functia atasata primeste doi parametri – primul, un string care reprezinta raspunsul, iar al doilea este un arbore DOM, dar este nenul numai daca raspunsul a fost XML.
• failure este declansat cand cererea s-a terminat, dar nu cu succes (de exemplu, am primit un 404). Functia atasata primeste un singur parametru, si anume instanta XMLHttpRequest cu care s-a facut cererea (de la care se poate obtine codul de eroare)
• exception este declansat atunci cand esueaza setarea unui header al cererii. Functia atasata primeste doi parametri de tip string: numele headerului si valoarea sa

De asemenea, orice instanta de Request are doua proprietati: running, care este true sau false dupa cum cererea este in curs de desfasurare sau nu, si response, un hash care are doua chei, text si XML, in care sunt raspunsul cererii ca text, si reprezarea DOM a raspunsului, daca acesta a fost XML.

Modificarea headerelor trimise se face prin metoda setHeader care primeste doi parametri de tip string, header-ul de setat si valoarea la care va fi setat. Valoarea returnata de aceasta este instanta de Request insasi (ceea ce e util pentru inlantuirea metodelor). Daca sunt de interes header-ele raspunsului, se foloseste metoda getHeader care primeste ca parametru un string – numele header-ului – si intoarce un string ce reprezinta valoarea headerului (sau null daca header-ul nu exista).

Cat despre trimiterea efectiva a cererii, metoda send face toate treaba. Poate primi un parametru optional, care poate fi string – si atunci acestea vor fi datele trimise si vor suprascrie pe cele implicite – sau un hash cu aceleasi chei ca si constructorul. Asta inseamna ca se pot face doua cereri complet diferite, folosind aceeasi instanta de Request. Valoarea intoarsa de Request.send este instanta de Request, astfel ca si send se poate folosi in inlantuiri de metode. Request.cancel revoca cererea curenta. Sa vedem si un exemplu:

var req = new Request({
    url: 'test.php',
    method: 'get',
    headers: {
        'X-Requested-By': 'me'
    },
    data: 'name=Bob',
    link: 'chain'
});
req.addEvent('success', function(response) {
    var rLog = $('response-log');
    rLog.set('html',rLog.get('html')+response+'<br />');
});
req.setHeader('X-Requested-With','MooTools')
   .send() // este trimis name=Bob (valoarea implicita pentru data)
   .send('name=Alice') // este trimis name=Alice
   .send({
       method: 'post'
   });

Puteti vedea exemplul in actiune, aici. Daca mai tineti minte, cand am vorbit de manipularea DOM cu MooTools, am amintit de metodele Element.set, Element.get (numite in continuare setter, getter) care adaugau proprietati custom elementelor, si spuneam ca o sa vedem cum ne ajuta in unele situatii. Un bun exemplu este la cererile AJAX: fiecare element are implicit o instanta de request intr-un setter/getter cu numele 'send' (deci accesul la aceasta se face cu un_element.get('send'), iar cu un_element.set('send', { /* optiuni */ })) sunt setate optiunile pentru instanta de Request, la fel ca la constructor). Nici macar nu e nevoie sa obtinem instanta de Request prin getter pentru a trimite date, pentru ca exista inca o metoda a lui Element, Element.send, care se comporta exact ca Request.send. De notat ca instanta de Request nu e creata automat (ar fi de altfel o risipa de memorie din moment ce numai un numar mic din elementele unui document ar avea nevoie de asa ceva), ci este creata prima data cand se apeleaza Element.get('send') sau Element.send, si refolosita la orice apeluri ulterioare. Aceasta face ca trimiterea unui formular prin AJAX sa se faca atat de simplu ca un apel formular.send() (pentru orice element, un apel send fara parametri creaza datele trimise din elementele input, textarea, select si orice alte elemente caracteristice formularelor, care sunt continute in acel element. In plus, daca este vorma de un element form, url-ul la care se face cererea este luat automat din atributul action, iar metoda din atributul method). Asta da simplu!

Dar ajutorul oferit de MooTools pentru cereri AJAX nu se opreste aici! Request este o clasa generica pentru cereri AJAX, insa creatorii MooTools au gasit doua cazuri de utilizare a cererilor AJAX foarte comune, astfel ca au creat doua subclase (din nou, clasele din terminologia MooTools, deci obiecte) care sa simplifice folosirea AJAX in astfel de cazuri.

Prima dintre acestea se numeste Request.HTML, si trateaza cazul foarte comun in care se face o cerere la server si tot raspunsul primit se insereaza intr-un element din pagina. Constructorul este acelasi cu cel de la Request, insa in optiuni poate aparea o cheie care la Request nu era luata in considerare: numele acesteia este update, iar valoarea sa este elementul in care se va insera raspunsul. Atentie, elementul va fi golit de continutul sau anterior. Singura deosebire fata de Request este la functia onSuccess (evenimentul success) – in acest caz aceasta primeste 4 parametri, nu 2 ca la Request: ierarhia de elemente intoarse ca raspuns, un vector care contine toate elementele intoarse (practic, toate elementele din ierarhia primita ca prim parametru, dar puse intr-un vector), continutul intors de cerere, dar ca string, si un string reprezentand codul JavaScript din raspuns. De asemenea, asa cum la Request aveam pusa la dispozitie o scurtatura de a folosi o asemenea cerere prin setter-ul/getter-ul/metoda send, si in acest caz exista un setter/getter/o metoda load care se comporta exact la fel ca send, doar ca optiunea update (elementul care va fi updatat cu raspunsul de la server) este pre-setat la elementul curent. Astfel este suficient un simplu apel un_element.load('/cale/catre/script') pentru a incarca raspunsul in elementul un_element.

A doua este Request.JSON si trateaza cazul, din ce in ce mai comun, in care raspunsul primit de la server este in format JSON. Constructorul primeste acelasi parametru optional ca si Request, cu o singura cheie specifica: secure care trebuie sa fie true sau false (iar implicit este true) si care spune daca ar trebui sau nu ca raspunsul primit sa aiba sintaxa verificata. De data aceasta, onSuccess primeste doi parametri, primul fiind obiectul primit ca JSON, iar al doilea fiind textul raspunsului, ca string.

Urmatoarele articole vor fi o introducere in jQuery, dupa care vom incerca sa punem in practica tot ce am invatat despre MooTools si jQuery.