Notițe ale programatorului pentru prototype.js

versiunea 1.3.1

de
ultima actualizare: 2 Octombrie 2005
traducere în românã de
Alte versiuni

Ce reprezintã prototype.js ?

În caz cã nu l-ați folosit încã, prototype.js este un framework JavaScript realizat de Sam Stephenson. Acest cod uimitor de bine scris, ce respectã standardele și ușor de învãtat, vã scutește efortul suținut și intens pe care îl depuneți pentru a crea paginile web interactive și atractive care caracterizeazã generația Web 2.0.

În cazul în care ați încercat sã utilizați aceastã bibiotecã, este posibil sã fi observat cã documentația nu este unul dintre punctele forte. Ca mulți alți programatori înaintea mea, am descoperit cum funcționeazã prototype.js citind codul sursã și exersând pe el. Am considerat util sã iau notițe și sã le împãrtãșesc altor programatori pe mãsurã ce învãțam .
Vã ofer o referințã neoficialã cãtre obiectele, clasele, funcțiile și extensiile oferite prin acest framework.

Funcțiile de utilitate

Framework-ul conține o serie de obiecte predefinite și funcții utile. Scopul evident al acestor funcții este de a evita multe repetiții în scrierea codului.

Utilizarea funcției $()

Funcția $() este o scurtãturã la îndemânã pentru foarte des întâlnita funcție document.getElementById(). Ca și funcția DOM, aceasta returneazã elementul care are id-ul trecut ca argument.

Spre deosebire de funcția DOM, $() merge mai departe.Utilizatorul poate trece mai multe id-uri, iar funcția $() va returna un obiect tablou cu toate elementele solicitate. Exemplul de mai jos ilustreazã acestea.

<HTML>
<HEAD>
<TITLE> Test Page </TITLE>
<script src="prototype-1.3.1.js"></script>

<script>
	function test1()
	{
		var d = $('myDiv');
		alert(d.innerHTML);
	}

	function test2()
	{
		var divs = $('myDiv','myOtherDiv');
		for(i=0; i<divs.length; i++)
		{
			alert(divs[i].innerHTML);
		}
	}
</script>
</HEAD>

<BODY>
	<div id="myDiv">
		<p>This is a paragraph</p>
	</div>
	<div id="myOtherDiv">
		<p>This is another paragraph</p>
	</div>

	<input type="button" value=Test1 onclick="test1();"><br> 
	<input type="button" value=Test2 onclick="test2();"><br> 

</BODY>
</HTML>

Un alt avantaj al acestei funcții îl reprezintã faptul cã utilizatorul poate trece fie șirul id sau obiectul în sine, ceea ce face aceastã funcție foarte utilã atunci când se dorește crearea unei alte funcții care poate sã ia orice formã a argumentului.

Utilizarea funcției $F ()

Funcția $F () reprezintã o altã scurtãturã binevenitã. Aceasta returneazã valoarea oricãrui câmp de tip text , cum ar fi casetele de text sau câmpuri de tip select. Funcția poate lua ca argument fie id-ul elementului, fie obiectul elementului în sine.

<script>
	function test3()
	{
		alert(  $F('userName')  );
	}
</script>

<input type="text" id="userName" value="Joe Doe"><br> 
<input type="button" value=Test3 onclick="test3();"><br> 
			

Utilizarea funcției Try.these()

Funcția Try.these() este foarte utilã și ușureazã munca programatorului atunci când acesta încearcã diferite interogãri ale funcției pânã una dintre ele funcționeazã . Este folosit un numãr mare de funcții ca argumente și sunt interogate una câte una, succesiv, pânã când una dintre ele funcționeazã, returnând rezultatul dorit al interogãrii funcției .

In exemplul de mai jos, funcția xmlNode.text funcționeazã în unele browsere, și xmlNode.textContent funcționezã în altele. Utilizând funcția Try.these() poate fi obținut doar rezultatul dorit.

<script>
  function getXmlNodeValue(xmlNode){
  return Try.these(
  function() {return xmlNode.text;},
  function() {return xmlNode.textContent;)
  );
  }
</script>
  

Obiectul Ajax

Funcțiile utile prezentate mai sus sunt interesante, dar sã recunoaștem…nu sunt cele mai avansate metode, nu-I asa? Este posibil ca orice programator sã aibã astfel de funcții în scriptul propriu. Aceste funcții sunt doar vârful icebergului.

Sunt convins cã interesul oricãrui programator pentru prototype.js este menținut și orientat mai ales datoritã oportunitãților oferite de AJAX . Consider necesar sã explic în ce mod vã face acest framework munca mai ușoarã atunci când trebuie urmatã logica AJAX

Obiectul Ajax este un obiect predefinit, creat de framework pentru a simplifica acel cod complicat implicat în redactarea funcționalitãții AJAX. Acest obiect conține un numãr de clase care au încapsulatã logica AJAX. Sã urmãrim unele dintre acestea.

Utilizarea clasei Ajax.Request

Fãrã a folosi vreun framework ajutãtor, se ajunge la scrierea unui cod amplu pentru a crea un obiect XMLHttpRequest și pentru a-i urmãri evoluția, pentru a obține un rãspuns și pentru a-l procesa. Iar situația în care trebuie suportat un singur tip de browser este una fericitã.

Pentru a ajuta în creșterea funcționalitãții AJAX, framework-ul definește clasa Ajax.Request

Sã presupunem cã existã o aplicație care poate comunica server-ului prin url-ul http://yoursever/app/get_sales?empID=1234&year=1998, care returneazã un rãspuns XML ca în exemplul de mai jos.

<?xml version="1.0" encoding="utf-8" ?> 
<ajax-response>
	<response type="object" id="productDetails">
		<monthly-sales>
			<employee-sales>
				<employee-id>1234</employee-id> 
				<year-month>1998-01</year-month> 
				<sales>$8,115.36</sales> 
			</employee-sales>
			<employee-sales>
				<employee-id>1234</employee-id> 
				<year-month>1998-02</year-month> 
				<sales>$11,147.51</sales> 
			</employee-sales>
		</monthly-sales>
	</response>
</ajax-response>			
			

Comunicarea server-ului de a gãsi și de a returna acest XML este suficient de simplã folosind un obiect Ajax.Request. Exemplul de mai jos aratã cum poate fi realizatã.

<script>
	function searchSales()
	{
		var empID = $F('lstEmployees');
		var y = $F('lstYears');
		var url = 'http://yoursever/app/get_sales';
		var pars = 'empID=' + empID + '&year=' + y;
		
var myAjax = new Ajax.Request( url, {method: 'get', parameters: pars, onComplete: showResponse} );
} function showResponse(originalRequest) { //put returned XML in the textarea $('result').value = originalRequest.responseText; } </script> <select id="lstEmployees" size="10" onchange="searchSales()"> <option value="5">Buchanan, Steven</option> <option value="8">Callahan, Laura</option> <option value="1">Davolio, Nancy</option> </select> <select id="lstYears" size="3" onchange="searchSales()"> <option selected="selected" value="1996">1996</option> <option value="1997">1997</option> <option value="1998">1998</option> </select> <br><textarea id=result cols=60 rows=10 ></textarea>

Observați cã al doilea parametru este pasat constructorului Ajax.Request . Parametrul {method: 'get', parameters: pars, onComplete: showResponse} reprezintã un obiect anonim în notația literalã. Acest fapt înseamnã cã este pasat un obiect care are o proprietate numitã method care conține șirul de caractere 'get', o altã proprietate numitã parameters care conține șirul de interogare al cererii HTTP, precum și o proprietate/metodã onComplete care conține funcția showResponse.

Sunt alte proprietãți în cadrul obiectului care pot fi definite, cum ar fi de exemplu asynchronous, care poate lua valorile true or false și determinã dacã apelul AJAX cãtre server poate fi fãcut asincron (valoarea inițialã este true.)

Acest parametru definește opțiunile pentru cererea de tip AJAX. În exemplul de fațã este cerut url-ul în primul argument prin comanda HTTP GET, pasând șirul de interogare conținut în variabila pars și obiectul Ajax.Request care va apela funcția showResponse atunci când terminã de returnat rãspunsul.

Așa dupã cum este posibil sã știți, XMLHttpRequest anunțã progresul în timpul cererii de tip HTTP. TProgramatorul este informat în care dintre cele 4 etape se aflã : Loading, Loaded, Interactive, or Complete. Cererea de tip Ajax.Request poate fi transformatã într-o funcție definitã de utilizator în oricare dintre aceste etape, însã Complete este cea mai des întâlnitã etapã în care se realizeazã aceastã transformare. Pentru ca obiectul sã știe de funcția definitã de programator, va trebui doar sã definiți o nouã proprietate/metodã de forma onXXXXX în opțiunile pentru apelare, așa cum funcția onComplete a fost definitã în exemplul nostru. Funcția trecutã va fi apelatã de obiectul cu un singur argument , care va deveni obiectul XMLHttpRequest însuși. Acest obiect poate ulterior utilizat pentru a obține datele returnate și posibil pentru a verifica proprietatea status care va conține codul HTTP rezultat din cerere.

Alte douã opțiuni interesante pot fi utilizate pentru procesarea rezultatelor. Poate fi specificatã opțiunea onSuccess ca și funcție care poate fi apelatã atunci când cererea de tip AJAX este executatã fãrã erori , și opțiunea onFailure poate fi apelatã atunci când se produc erori pe sever. Ca și funcțiile onXXXXX , acestea douã vor fi apelate pasând obiectul XMLHttpRequest care a purtat cererea de tip AJAX.

Exemplul nostru nu a procesat rãspunsul primit în XML în nici un mod. Tocmai am populat câmpul de tip textarea cu conținutul XML din rãspuns. O utilizare tipicã a rãspunsului ar gãsi probabil informația doritã în interiorul XML și ar actualiza, sau poate chiar ar transforma XSLT pentru a produce HTML în paginã.

Pentru explicații mai complete, vezi Ajax.Request reference și options reference.

Utilizarea clasei Ajax.Updater

Dacã existã pe server un script care returneazã date deja prelucrate în HTML, framework-ul ușureazã efortul cu ajutorul clasei Ajax.Updater. Utilizând aceastã clasã, programatorul doar transmite care element trebuie completat cu HTML-ul returnat din cererea de tip AJAX. Exemplul de mai jos este elocvent:

<script>
	function getHTML()
	{
		var url = 'http://yourserver/app/getSomeHTML';
		var pars = 'someParameter=ABC';
		
var myAjax = new Ajax.Updater('placeholder', url, {method: 'get', parameters: pars});
} </script> <input type=button value=GetHtml onclick="getHTML()"> <div id="placeholder"></div>

Dupã cum puteți observa, codul este similar cu cel dn exemplul anterior, cu excepția funcției onComplete și a elementului id pasat în constructor. Pentru a ilutra modul în care pot fi rezolvate erorile serverului clientului, voi modifica puțin codul.

Voi adãuga mai multe opțiuni apelãrii, specificând o funcție care va fi apelatã în momentul apariției iminente a unei erori. Aceastã operațiune este realizatã uitilizând opțiunea onFailure. . Specific faptul cã div-ul cu id-ul placeholder este populat doar în cazul în care operațiunea se realizeazã cu succes. Pentru a obține acest rezultat,voi schimba primul parametru dintr-un element cu un id, într-un obiect cu douã proprietãți, success (care va fi utilizat doar în cazul în care totul merge bine) și failure (utilizat când apar erori.) ). Nu voi utiliza proprietatea failure în exemplu, ci doar funcția reportError din opțiunea onFailure.

<script>
	function getHTML()
	{
		var url = 'http://yourserver/app/getSomeHTML';
		var pars = 'someParameter=ABC';
		
var myAjax = new Ajax.Updater( {success: 'placeholder'}, url, {method: 'get', parameters: pars, onFailure: reportError});
} function reportError(request) { alert('Sorry. There was an error.'); } </script> <input type=button value=GetHtml onclick="getHTML()"> <div id="placeholder"></div>

IDacã serverul returneaza cod JavaScript în loc de cod HTML, obiectul Ajax.Updater poate evalua codul JavaScript. Pentru ca obiectul sã trateze rãspunsul ca Java.Script, trebuie doar adãugat evalScripts: true; listei proprietãților din ultimul argument al constructorului obiectului.

Pentru explicații suplimentare, vezi Ajax.Updater reference și options reference.


Referințe pentru prototype.js

Extensii ale claselor JavaScript

Una dintre modalitãțile în care framework-ul prototype.js adaugã funcționalitate este prin extinderea claselor Java.Script deja existente.

Extensii pentru clasa Object

Metodã Tip Argumente Descriere
extend(destinație, sursã) static destinație: orice obiect, sursã: orice obiect Creeazã o modalitate de a impelmenta moștenirea prin copierea tuturor proprietãților și a metodelor din source în destination.
extend(obiect) instanțã orice obiect Creeazã o modalitate de a impelmenta moștenirea prin copierea tuturor proprietãților și a metodelor de la obiectul dat object.

Extensii pentru clasa Number

Metodã Tip Argumente Descriere
toColorPart() instanțã (nici unul) Returneazã reprezentarea hexadecimalã a numãrului.Este utilã atunci are loc transformarea componentelor RGB a unei culori în reprezentarea sa HTML.

Extensii pentru clasa Function s

Metodã Tip Argumente Descriere
bind(object) instanțã obiect: obiectul care are metoda Returneazã o instanțã a funcției suplimentarã functiei (=metodã)deținute de obiect. Funcția returnatã va avea aceleași argumente ca cea originalã.
bindAsEventListener(object) instanțã obiect: obiectul care are metoda Returneazã o instanțã a funcției suplimentarã functiei (=metodã)deținute de obiect. Funcția returnatã va avea ca argument obiectul curent declanșator al event

Iatã cum funcțoneazã aceste extensii .

<input type=checkbox id=myChk value=1> Test?
<script>
	//declaring the class
	var CheckboxWatcher = Class.create();

	//defining the rest of the class implmentation
	CheckboxWatcher.prototype = {

	   initialize: function(chkBox, message) {
			this.chkBox = $(chkBox);
			this.message = message;
			//assigning our method to the event
			this.chkBox.onclick = this.showMessage.bindAsEventListener(this);
	   },

	   showMessage: function(evt) {
		  alert(this.message + ' (' + evt.type + ')');
	   }
	};


	var watcher = new CheckboxWatcher('myChk', 'Changed');
</script>

			

Extensii pentru clasa String

Metodã Tip Argumente Descriere
stripTags() instanțã (nici unul) Returneazã orice șir de caractere eliminând orice etichetã HTML sau XML.
escapeHTML() instanțã (nici unul) Returneazã șirul de caractere in format HTML cu cod html neinterpretabil de browser.
unescapeHTML() instanțã (nici unul) Reversul funcției escapeHTML()

Extensii pentru obiectul document DOM

Metodã Tip Argumente Descriere
getElementsByClassName(className) instanțã className: numele unei clase CSS asociatã elementelor. Returneazã toate elementele care sunt asociate cu numele dat al clasei.

Extensii pentru obiectul Event

Proprietate Tip variabil Descriere
KEY_BACKSPACE Numãr 8: Constant. Cod pentru tasta Backspace.
KEY_TAB Numbãr 9: Constant. Cod pentru tasta Tab.
KEY_RETURN Numãr 13: Constant. Cod pentru tasta Return.
KEY_ESC Numãr 27: Constant. Cod pentru tasta Esc.
KEY_LEFT Numãr 37: Constant. Cod pentru tasta Sãgeatã spre stânga.
KEY_UP Numãr 38: Constant. Cod pentru tasta Sãgetã în sus.
KEY_RIGHT Numãr 39: Constant. Cod pentru tasta Sãgeatã spre dreapta.
KEY_DOWN Numãr 40: Constant. Cod pentru tasta Sãgeatã în jos.
KEY_DELETE Numãr 46: Constant. Cod pentru tasta Delete.
Observatori: Tablou Lista observatorilor in cache. Parte a detaliilor implementãrii interne a obiectului.

Metodã Tip Argumente Descriere
element(event) static eveniment: un obiect Event Returneazã elementul care a cauzat evenimentul.
isLeftClick(event) static eveniment: un obiect Event Returneazã true dacã s-a dat click pe butonul stâng al mouse-ului.
pointerX(event) static eveniment: un obiect Event Returneazã coordonata x a pointer-ului de mouse de pe paginã.
pointerY(event) static eveniment: un obiect Event Returneazã coordonata y a pointer-ului de mouse de pe paginã.
stop(event) static eveniment: un obiect Event Use this function to abort the default behavior of an event and to suspend its propagation.
findElement(event, tagName) static eveniment: un obiect Event, tagName: numele etichetei dorite. Traverses the DOM tree upwards, searching for the first element with the given tag name, starting from the element that originated the event.
observe(element, name, observer, useCapture) static element: obiect sau id, name: numele evenimentului (cum ar fi 'click', 'load', etc), observator: funcție care sã suporte evenimentul, useCapture: dacã are valoarea true, suportã evenimetul în faza capture dacã valoarea este false suportã evenimentul în faza bubbling . Adaugã o funcție apelatã la momentul declanșãrii unui eveniment .
stopObserving(element, name, observer, useCapture) static element: obiect sau id, name: numele evenimentului (cum ar fi 'click', etc), observator: functie care sa suporte evenimentul, useCapture: dacã are valoarea true, suportã evenimetul în faza capture dacã valoarea este false, suportã evenimetul în faza bubbling . Retrage o funcție apelatã la momentul declanșãrii unui eveniment.
_observeAndCache(element, name, observer, useCapture) static   O metodã privatã, care nu prezintã dificultãți.
unloadCache() static (nici unul) O metodã privatã, care nu prezintã dificultãți. Șterge din memorie toți observatorii in cache.

Sã observãm cum se folosește acest obiect pentru a adãuga o funcție apelatã la momentul declanșãrii unui eveniment al obiectului window .

<script>
	Event.observe(window, 'load', showMessage, false);

	function showMessage() {
	  alert('Page loaded.');
	}
</script>			
			

Clase și obiecte noi, definite de prototype.js

O altã modalitate prin care acest framework ajutã programatorii este prin furnizarea multor implementãri care reprezintã suport pentru design-urile orientate spre obiect, dar și datoritã funcționalitãții lor, în general.

Obiectul PeriodicalExecuter

Acest obiect furnizeazã logica pentru apelarea unei funcții date în mod repetat, la un interval dat.

Metodã Tip Argumente Descriere
[ctor](callback, interval) constructor callback: o funcție fãrã parametru, interval: numãr de secunde Creeazã o instanțã a acestui obiect care va apela funcția în mod repetat.

Proprietate Tip variabil Descriere
callback Function() Funcția care va fi apelatã.Nu îi va fi pasat nici un parametru.
frequency Numãr Reprezintã de fapt intervalul în secunde.
currentlyExecuting Boolean Indicã dacã apelarea funcției este în curs de desfãșurare.

Obiectul Prototype

Obiectul Prototype are drept rol important declararea versiunii framework-ului care este utilizat.

Proprietate Tip variabil Descriere
Version Șir de caractere Versiunea framework-ului.
emptyFunction Function() O funcție care nu returneazã nici o valoare.

Obiectul Class

Obiectul Class este utilizat atunci când are loc declararea altor clase în framework. Utilizarea acestui obiect atunci când se declarã o clasã, face ca nouã clasã sã suporte o metodã initialize() care se comportã ca un constructor. .

Vezi exemplul de mai jos:

//declaring the class
var MySampleClass = Class.create();

//defining the rest of the class implmentation
MySampleClass.prototype = {

   initialize: function(message) {
		this.message = message;
   },

   showMessage: function(ajaxResponse) {
      alert(this.message);
   }
};	

//now, let's instantiate and use one object
var myTalker = new MySampleClass('hi there.');
myTalker.showMessage(); //displays alert

			

Metodã Tip Argumente Descriere
create(*) instanțã (nici unul) Definește un constructor pentru o clasã nouã.

Obiectul Ajax

Acest obiect servește ca rãdãcinã pentru alte clase care furnizeazã funcționalitate AJAX.

Metodã tip Argumente Descriere
getTransport() instanțã (nici unul) Returneazã un nou obiect XMLHttpRequest

ClasaAjax.Base

Aceastã clasã este folositã ca rãdãcinã pentru alte clase definite în obiectul Ajax.

Metodã Tip Argumente Descriere
setOptions(options) instanțã opțiuni: AJAX options Seteazã opțiunile dorite pentru operațiunea AJAX. options
responseIsSuccess() instanțã (nici unul) Returneazã true dacã oprațiunea AJAX a reușit, în caz contrar, returneazã false
responseIsFailure() instanțã (nici unul ) Reprezintã opusul funcției responseIsSuccess().

Clasa Ajax.Request

Moștenește clasa Ajax.Base

Încapsuleazã operațiile AJAX

Proprietate Tip variabil Tip Descriere
Events Tablou static Listã a unor posibile evenimente/status-uri raportate în timpul unei operațiuni AJAX. Lista include: 'Uninitialized', 'Loading', 'Loaded', 'Interactive', and 'Complete.'
transport XMLHttpRequest instanțã Obiectul XMLHttpRequest care reprezintã operațiunea AJAX.

Metodã Tip Argumente Descriere
[ctor](url, options) constructor url: url-ul care ar fi extras, opțiuni: opțiunile AJAX Creeazã o instanțã pentru acest obiect care va face un request cãtre url dat utilizând opțiunile date. Important: Nu are nici o importanțã dacã url-ul ales este subiect pentru setãrile de securitate ale browser-ului. În multe cazuri, browser-ul nu va face un request cãtre un url, dacã acesta nu este de pe același host (domeniu) ca și pagina curentã.În mod ideal ar trebui folosite url-uri locale pentru a evita configurarea sau restricționarea utilizatorilor browser-ului.
request(url) instanțã url: url-ul țintã pentru apelarea AJAX Aceastã metodã nu este în mod obișnuit apelatã direct (extern) de cãtre obiect. Este deja chematã în timpul apelãrii constructorului.
setRequestHeaders() instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã direct (extern)de cãtre obiect. Este apelatã de obiectul însuși la crearea header-elor de tip HTTP ce vor fi trimise în timpul cererii de tip HTTP..
onStateChange() instanțã (noici unul) Aceastã metodã nu este în mod obișnuit apelatã direct (extern) de cãtre obiect.Este apelatã de obiectul însuși atunci când status-ul cererii de tip AJAX se modificã.
respondToReadyState(readyState) instanțã readyState: numãrul stãrii (1 to 4) Aceastã metodã nu este în mod obișnuit apelatã direct (extern) de cãtre obiect. Este apelatã de obiectul însuși atunci când status-ul cererii de tip AJAX se modificã.

Obiectul argument options

Un element important al operațiilor AJAX îl reprezintã argumentul options. Nu existã o clasã options pre-definitã. Orice obiect poate fi pasat, atâta timp cât are proprietãțile așteptate. Este o practicã obișnuitã crearea de obiecte anonime doar pentru interogãrile de tip AJAX.

Proprietate Tip variabilã Valoare inițialã Descriere
method Șir de caractere 'post' Metodã a cererii de tip HTTP
parameters Șir decaractere '' Lista formatatã a argumentelor din url trimise în cerere.
asynchronous booleanã true Indicã dacã cererea de tip AJAX va fi fãcutã asincronic.
postBody Șir de caractere nedefinitã CConținut pasat în corpul cererii în cazul unui HTTP POST.
requestHeaders Tablou nedefinitã Listã a header-elor HTTP ce vor fi pasate odatã cu cererea. . Aceastã listã trebuie sã aibã un numãr par de elemente, fiecare termen impar reprezentând numele unui header propriu, iar urmãtorul element par va fi un șir reprezentând valoarea acelui header. Exemplu:['my-header1', 'this is the value', 'my-other-header', 'another value']
onXXXXXXXX Funcția(XMLHttpRequest) nedefinitã Funcție definitã de cãtre programator care va fi apelatã atunci când respectivul eveniment/status este atins în timpul cererii de tip AJAX. Exemplu: var myOpts = {onComplete: showResponse, onLoaded: registerLoaded};. Funcția utilizatã va primi un argument, conținând obiectul XMLHttpRequest care înglobeazã operația AJAX.
onSuccess Funcția(XMLHttpRequest) nedefinitã Funcție definitã de cãtre programator care va fi apelatã atunci când cererea de tip AJAX se finalizeazã cu succes. Funcția utilizatã va primi un argument, conținând obiectul XMLHttpRequest care înglobeazã operația AJAX.
onFailure Funcție(XMLHttpRequest) nedefinitã Funcție definitã de cãtre programator care va fi apelatã atunci când cererea de tip AJAX se finalizeazã cu erori. Funcția utilizatã va primi un argument, conținând obiectul XMLHttpRequest care înglobeazã operația AJAX.
insertion Funcție(Obiect, Șir de caractere) nulã Funcție ce va fi apelatã pentru 'injectarea' textului returnat în cadrul unui element . Funcția va fi apelatã cu douã argumente, elementul obiect ce va fi actualizat și rãspunsul text se aplicã doar pentru obiecte Ajax.Updater .
evalScripts booleanã nedefinitã, falsã Determinã dacã blocãrile script-ului vor fi evaluate atunci când ajunge rãspunsul. Se aplicã doar obiectelor Ajax.Updater .
decay Numãr nedefinitã, 1 Determinã încetinirea progresivã a ratei de refresh a unui obiect Ajax.PeriodicalUpdater atunci când rãspunsul primit este același cu cel anterior. De exemplu, programatorul face o cerere și așteaptã un rãspuns; primește rãspunsul și îl evaluazã. dupã o secundã, face o nouã cerere, dacã obține același rãspuns, va face o cerere dupa 2 secunde, dacã obține același rãspuns, va face o nouã cerere dupã 4 secunde, samd. Se dubleazã intervalul de timp pentru a evita supraîncãrcarea server-ului.

Clasa Ajax.Updater

Moștenește clasa Ajax.Request

Used when the requested url returns HTML that you want to inject directly in a specific element of your page. You can also use this object when the url returns <script> blocks that will be evaluated upon arrival. Use the evalScripts option to work with scripts.

Proprietate Tip variabil Tip Descriere
ScriptFragment Șir de caractere static Expresie regulatã pentru identificarea script-urilor
containers Obiect instanțã Acest obiect conține 2 proprietãți : containers.success va fi folositã atunci când cererea de tip AJAX este o reușitã,iar containers.failure în caz contrar.

Metodã Tip Argumente Descriere
[ctor](container, url, options) constructor container:container: acesta poate fi id-ul unui element, elementul obiect însuși, sau un obiect cu douã proprietãți - object.success element (sau id) care va fi folosit în cazul în care carerea de tip AJAX are succes, și object.failure element (sau id) care va fi folositã în caz contrar. url: url-ul ce va fi extras, opțiuni: AJAX options Creeazã o instanțã a obiectului care va cere url-ul dat, folosind opțiunile date.
updateContent() instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã direct (extern) de cãtre obiect. Este apelatã de obiectul însuși atunci când este primit rãspunsul. IVa actualiza elementul potrivit cu HTML sau va apela funcția pasatã în opțiunea inserție. Funcția va fi apelatã cu douã argumente, elementul ce va fi actualizat și rãspunsul text..

Clasa Ajax.PeriodicalUpdater

Moștenește clasa Ajax.Base

Aceastã clasã instanțiazã și folosește în mod repetat un obiect Ajax.Updater pentru a reîmprospãta un element al paginii sau pentru a duce la îndeplinire alte task-uri pe care le poate indeplini Ajax.Updater . Ajax.Updater Consultați Ajax.Updater reference pentru mai multe informații.

Proprietate Tip variabil Tip Descriere
container Obiect instanțã Aceastã valoare va fi pasatã direct constructorului Ajax.Updater.
url String instanțã Aceastã valoare va fi pasatã direct constructorului Ajax.Updater.
frequency Numãr instanțã Interval (nu frecvențã) între refresh-uri, în secunde. Intervalele inițiale sunt pânã la 2 secunde. Acest numãr va fi multiplicat prin nivel curent de regres în apelarea obiectului Ajax.Updater.
decay Numãr instanțã Menține decalajul de nivel actual aplicat atunci când are loc reexecutarea comenzii.
updater Ajax.Updater instanțã Cel mai recent utilizat obiect Ajax.Updater.
timer Obiect instanțã Timer-ul JavaScript utilizat pentru anunța obiectul când este momentul pentru urmãtorul refresh.

Metodã Tip Argumente Descriere
[ctor](container, url, options) constructor container: acesta poate fi id-ul unui element, elementul obiect însuși, sau un obiect cu douã proprietãți - object.success element (sau id) care va fi folosit atunci când cererea de tip AJAX se realizeazã cu succes, și object.failure element (sau id) în caz contrar. url: url-ul ce va fi extras, opțiuni: : options Creeazã o instanțã a acestui obiect care va cere url-ul dat utilizând opțiunile date.
start() instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã direct (extern) de cãtre obiect. Este apelatã de obiect însuși pentru a începe realizarea task-urilor sale periodice.
stop() instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã direct (extern) de cãtre obiect. Este apelatã de obiect însuși pentru a opri realizarea task-urilor sale periodice
updateComplete() instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã direct (extern) de cãtre obiect. Este apelatã de Ajax.Updater-ul folosit în acel moment dupã completarea cererii. Este folositã pentru programarea urmãtorului refresh.
onTimerEvent() instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã direct (extern) de cãtre obiect. Este apelatã intern atunci când este momentul pentru urmãtoarea actualizare.

Obiectul Element

Acest obiect aduce o serie de funcții utile în manipularea elementelor în DOM.

Metodã Tip Argumente Descriere
toggle(elem1 [, elem2 [, elem3 [...]]]) instanțã elemN: element object sau id Face sã aparã sau sã disparã fiecare element pasat.
hide(elem1 [, elem2 [, elem3 [...]]]) instanțã elemN: element object sau id Ascunde fiecare element setând valoarea lui style.display în 'none'.
show(elem1 [, elem2 [, elem3 [...]]]) instanțã elemN: element object sau id Face vizibil fiecare element resetând style.display în ''.
remove(element) instanțã elemN: element object sau id Eliminã elementul din document.
getHeight(element) instanțã elemN: element object sau id Returneazã proprietatea offsetHeight a elementului.
addClassName(element, className) instanțã element: element object sau id, className: numele unei clase CSS Adaugã numele de clasã dat, numelui de clasã al elementului.
hasClassName(element, className) instanțã element: element object sau id, className: numele unei clase CSS Returneazã true dacã elementul are numele de clasã dat ca unul dintre numele de clase proprii.
removeClassName(element, className) instanțã element: element object sau id, className: numele unei clase CSS Eliminã numele de clasã dat dintre numele de clasã ale elementului.
cleanWhitespace(element) instanțã element: element object sau id Șterge orice nod copil de tip 'white space' al elementului dat.

Obiectul Abstract

Acest obiect servește ca rãdãcinã pentru alte clase ale framewor-ului. Nu are proprietãți sau metode.Clasele definite în acest obiect sunt de asemenea tratate drept clase abstracte.

Clasa Abstract.Insertion

Aceastã clasã este utilizatã ca și clasã de bazã pentru alte clase care vor furniza inserția dinamica a conținutului. Aceastã clasã este utilizatã drept clasã abstractã.

Metodã Tip Argumente Descriere
[ctor](element, content) constructor element: element object sau id, content: cod HTML de inserat Creeazã un obiect care va susține inserția dinamica a conținutului.

Proprietate Tip variabilã Tip Descriere
adjacency Șir caractere static, parametru Parametru care specificã unde va fi plasat conținutul în funcție de elementul dat. Valorile posibile sunt: 'beforeBegin', 'afterBegin', 'beforeEnd', si 'afterEnd'.
element Obiect instanțã Elementul obiect în funcție de care se va face inserția.
content Șir de caractere instanțã Codul HTML care va fi inserat

Obiectul Insertion

Acest obiect servește ca rãdãcinã pentru alte clase ale framewor-ului. Nu are proprietãți sau metode. Clasele definite în acest obiect sunt de asemenea tratate drept clase abstracte.

Clasa Insertion.Before

Moștenește clasa Abstract.Insertion

Insereazã HTML înaintea unui element.

Metodã Tip Argumente Descriere
[ctor](element, content) constructor element: element object sau id, content: HTML care va fi inserat Moștenește clasa Abstract.Insertion. Creeazã un obiect care va asista injectarea dinamicã de conținut.

Urmãtorul cod

<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>

<script> new Insertion.Before('person', 'Chief '); </script>
			

va transforma HTML în

<br>Hello, Chief <span id="person" style="color:red;">Wiggum. How's it going?</span>	
			

Clasa Insertion.Top

Moștenește clasa Abstract.Insertion

Insereazã HTML drept primul nod copil sub un element. Conținutul va fi trecut înaintea etichetei de închidere a elementului.

Metodã Tip Argumente Descriere
[ctor](element, content) constructor element: element object sau id, content: cod HTML care va fi inserat Moștenește clasa Abstract.Insertion. Creeazã un obiect care va asista injectarea dinamicã de conținut.

Urmãtorul cod

<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>

<script> new Insertion.Top('person', 'Mr. '); </script>
			

va transforma HTML în

<br>Hello, <span id="person" style="color:red;">Mr. Wiggum. How's it going?</span>	
			

Clasa Insertion.Bottom

Moștenește clasa Abstract.Insertion

Insereazã HTML drept primul nod copil sub un element. Conținutul va fi trecut înaintea etichetei de închidere a elementului.

Metodã Tip Argumente Descriere
[ctor](element, content) constructor element: element object sau id, content: HTML-ul care va fi inserat Moștenește clasa Abstract.Insertion. Creeazã un obiect care va asista injectarea dinamicã de conținut.

Urmãtorul cod

<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>

<script> new Insertion.Bottom('person', " What's up?"); </script>
			

va transforma HTML în

<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going? What's up?</span>	
			

Clasa Insertion.After

Moștenește clasa Abstract.Insertion

Insereazã HTML imediat dupã eticheta de inchidere e elementului.

Metodã Tip Argumente Descriere
[ctor](element, content) constructor element: element object sau id, content: HTML ce va fi inserat Moștenește clasa Abstract.Insertion. Creeazã un obiect care va asista injectarea dinamicã de conținut.

Urmãtorul cod

<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>

<script> new Insertion.After('person', ' Are you there?'); </script>
			

va transforma codul HTML în

<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> Are you there?	
			

Obiectul Field

Acest obiect furnizeazã funcții utile pentru lucrul cu câmpuri de control (input fields) în formulare

Metodã Tip Argumente Descriere
clear(field1 [, field2 [, field3 [...]]]) instanțã fieldN: elementul obiect al câmpului sau id Șterge valoarea fiecãrui element din formular.
present(field1 [, field2 [, field3 [...]]]) instanțã fieldN: elementul obiect al câmpului sau id Returneazã true dacã toate formularele nu au valori nule.
focus(field) instanțã field: elementul obiect al câmpului sau id Deplaseazã focus-ul cãtre câmpul formularului dat.
select(field) instanțã field: elementul obiect al câmpului sau id Selecteazã valoarea în câmpurile care sprijinã selectarea textului.
activate(field) instanțã field: elementul obiect al câmpului sau id Deplaseazã focalizarea și selecteazã valoarea în câmpurile care sprijinã selectarea textului.

Obiectul Form

Acest obiect furnizeazã o serie de funcții utile pentru lucrul cu formulare de introducere a datelor și cu câmpurile lor de control.

Metodã Tip Argumente Descriere
serialize(form) instanțã form: elementul obiect al formularului sau id Returneazã o listã formatatã a argumentelor din url trimise în cerere, de forma 'camp1=valoare1&camp2=valoare2&camp3=valoare3'
getElements(form) instanțã form: elementul obiect al formularului sau id Returneazã un tablou conținând toate câmpurile de tip input din formular.
getInputs(form [, typeName [, name]]) instanțã form: elementul obiect al formularului sau id, typeName: tipul de input element, name: denumirea input element-ului. Returneazã un tablou conținând toate elementele <input> din formular. Opțional, lista poate fi filtratã dupã tipul sau numele atributelor acelor elemente.
disable(form) instanțã form: elementul obiect al formularului sau id Dezactiveazã toate câmpurile de tip input din formular.
enable(form) instanțã form: elementul obiect al formularului sau id Activeazã toate câmpurile de tip input din formular (se includ și câmpurile de tip radio, select și checkbox).
focusFirstElement(form) instanțã form: elementul obiect al formularului sau id Focalizeazã primul câmp de tip input, activ și care nu este ascuns (hidden) din formular.
reset(form) instanțã form: elementul obiect al formularului sau id Reseteazã formularul. Același efect precum apelarea metodei reset() al obiectului form.

Obiectul Form.Element

Acest obiect furnizeazã o serie de funcții utile pentru lucrul cu elementele formularului, vizibile sau nu.

Metodã Tip Argumente Descriere
serialize(element) instanțã element: obiectul elementului sau id Returneazã perechea numele elementului=valoare, de genul 'elementName=elementValue'
getValue(element) instanțã element: obiectul elementului sau id Returneazã valoarea elementului.

Obiectul Form.Element.Serializers

Acest obiect furnizeazã o serie de funcții utile ce sunt folosite intern de aceastã librãrie pentru a susține extragerea valorilor curente ale elementelor din formular.

Metodã Tip Argumente Descriere
inputSelector(element) instanțã element: obiect sau id al elementului din formular care are proprietatea checked , cum ar fi un buton radio sau checkbox. Returneazã un tablou conținând numele și valoarea elementului, cum ar fi ['numeElement', 'valoareElement'].
textarea(element) instanțã element: obiect sau id al elementului din formular care are proprietatea value, cum ar fi un textbox, buton sau câmp de tip parolã. Returneazã un tablou conținând numele și valoarea elementului, cum ar fi ['numeElement', 'valoareElement'].
select(element) instanțã element: obiect sau id al unui element de tip <select> Returneazã un tablou conținând numele elementului și toate valorile sau textele opțiunilor selectate, cum ar fi ['numeElement', 'opțiuneSelectatã1 opțiuneSelectatã4 opțiuneSelectatã9']

Clasa Abstract.TimedObserver

Aceastã clasã este folositã drept clasã-pãrinte pentru alte clase care vor monitoriza un element pânã când valoarea sa (sau orice proprietate definitã în clasa derivatã) se modificã. Aceastã clasã se folosește precum o clasã abstractã.

Clasele care moștenesc pot fi create pentru a monitoriza valorile introduse pentru un element, sau unua dintre proprietãțile de stil, sau numãrul de rânduri dintr-un tabel, sau orice altceva a cãrui schimbare ar putea suscita interesul.

Metodã Tip Argumente Descriere
[ctor](element, frequency, callback) constructor element: obiectul element sau id, frecvențã: interval în secunde, callback: funcție ce va fi apelatã la modificarea elementului Creeazã un obiect care va monitoriza elementul.
getValue() instanțã, abstract (none) Clasele derivate trebuie sã implementeze aceastã metodã pentru a determina care este valoarea curentã monitorizatã a acelui element.
registerCallback() instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã direct (extern). Este apelatã de obiectul însuși pentru a începe monitorizarea elementului.
onTimerEvent instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã direct (extern). Este apelatã de obiectul însuși periodic pentru a verifica elementul.

Proprietate Tip Descriere
element Obiect Elementul obiect care este monitorizat.
frequency Numãr Acesta reprezintã în fapt intervalul în secunde dintre verificãri.
callback Funcție(Obiect, Șir de caractere) Funcția ce va fi apelatã oricând elementul se modificã. Aceasta va primi ca argumente elementul obiect și noua valoare.
lastValue Șir de caractere Ultima valoare verificatã în element.

Clasa Form.Element.Observer

Moștenește clasa Abstract.TimedObserver

Implementare a clasei Abstract.TimedObserver care monitorizeazã valoarea elementelor de tip input din formular. Aceastã clasã se utilizeazã atunci când se dorește monitorizarea unui element care nu are un eveniment ce raporteazã schimbarea valorii acestuia. În acest caz poate fi utilizatã clasa Form.Element.EventObserver

Metodã Kind Arguments Description
[ctor](element, frecvențã, callback) constructor element: obiectul element sau id, frecvențã: interval în secunde, callback: funcție ce va fi apelatã la modificarea elementului Moștenit de la Abstract.TimedObserver. Creeazã un obiect care va monitoriza valoarea sau proprietatea obiectului.
getValue() instanțã (nici unul) Returneazã valoarea elementului.

Clasa Form.Observer

Moștenește clasa Abstract.TimedObserver

Implementare a clasei Abstract.TimedObserver care monitorizeazã orice schimbãri ale valorilor introduse în formular. Aceastã clasã se utilizeazã atunci când se dorește monitorizarea unui formular ale cãrui elemente nu au un eveniment ce raporteazã schimbarea valorii acestora. În acest caz poate fi utilizatã clasa Form.EventObserver

Metodã Tip Argumente Descriere
[ctor](form, frecvențã, callback) constructor form: obiectul formular sau id, frecvențã: interval in secunde, funcție callback ce va fi apelatã la modificarea oricãrui element din formular. Moștenit de la Abstract.TimedObserver. Creeazã un obiect care va monitoriza orice modificare din formular.
getValue() instanțã (nici unul) Returneazã serializarea tutror datelor din formular.

Clasa Abstract.EventObserver

Aceastã clasã este folositã ca pãrinte pentru alte clase care executã o funcție callback oricând are loc un eveniment declanșator la schimbarea valorii unui element.

Obiecte multiple de tip Abstract.EventObserver pot fi legate de același element fãrã sã se afecteze reciproc. Funcțiile de tip callback vor fi executate în ordinea în care ele sunt atribuite elementului.

Evenimentul declanșator pentru butoanele de tip radio și checkbox este onClick, iar pentru campuri de tip text în general, dar și pentru câmpuri de tip select evenimentul declanșator este onChange.

Metodã Tip Argumente Descriere
[ctor](element, callback) constructor element: obiectul element sau id, callback: funcție ce va fi apelatã la declanșarea evenimentului. Creeazã un obiect ce va monitoriza elementul.
getValue() instanțã, abstract (nici unul) Clasele derivate trebuie sã implementeze aceastã metodã pentru a determina care este valoarea curentã monitorizatã a acelui element.
registerCallback() instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã extern. Este apelatã de obiect pentru atașa funcția de tip callback direct evenimentului acelui element.
registerFormCallbacks() instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã extern. Este apelatã de obiect pentru a atașa funcția de tip callback direct evenimentului tututor elementelor din formular.
onElementEvent() instanțã (nici unul) Aceastã metodã nu este în mod obișnuit apelatã extern. Se va apela la declanșarea evenimentului.

Proprietate Tip Descriere
element Obiect Elementul obiect ce va fi monitorizat.
callback Funcție(Obiect, Șir de caractere) Funcție ce va fi apelatã oricând elementul se schimbã. Va primi ca argumente elementul obiect și noua valoare.
lastValue Șir de caractere Ultima valoare verificatã a elementului.

Clasa Form.Element.EventObserver

Moștenește clasa Abstract.EventObserver

Implementare a clasei Abstract.EventObserver care executã o funcție de tip callback atașatã celui mai potrivit eveniment ce detecteazã schimbãri de valoare în cadrul elementelor unui formular. Dacã elementul nu are atașat nici un eveniment ce raporteazã schimbarea valorii, atunci se poate folosi clasa Form.Element.Observer

Metodã Tip Argumente Descriere
[ctor](element, callback) constructor element: obiectul element sau id, callback: funcție ce va fi apelatã la declanșarea evenimentului. Moștenit din Abstract.EventObserver. Creeazã un obiect ce va monitoriza valoarea proprietãții unui element.
getValue() instanțã (nici unul) Returneazã valoarea elementului.

Clasa Form.EventObserver

Moștenește clasa Abstract.EventObserver

Implementare a clasei Abstract.EventObserver ce monitorizeazã orice schimbare a oricãrui element ce suportã date introduse de utilizator dintr-un formular, utilizând evenimentele elementelor pentru a detecta schimbarea valorilor. Dacã formularul conține elemente care nu au atașate evenimente care sã reporteze schimbãri ale valorilor, atunci se poate folosi clasa Form.Observer

Metodã Tip Argumente Descriere
[ctor](form, callback) constructor form: obiectul formular sau id, callback: funcție ce va fi apelatã când valoarea unui element se schimbã. Moștenit de la Abstract.EventObserver. Creeazã un obiect ce va monitoriza schimbãrile din cadrul formularului.
getValue() instanțã (nici unul) Returneazã serializarea tuturor datelor din formular.

Obiectul Position ( documentație preliminarã )

Acest obiect furnizeazã o mulțime de funcții care ajutã atunci când se lucreazã cu poziționarea elementelor.

Metodã Tip Argumente Descriere
prepare() instanțã (nici unul) Ajusteazã proprietãțile deltaX și deltaY pentru acomodarea schimbãrilor în poziția scroll-ului. A nu se uita apelarea acestei metode înaintea metodei withinIncludingScrolloffset dupã ce se face scroll de mouse pe pagina.
realOffset(element) instanțã element: obiect Returneazã un tablou cu poziționãrile corecte ale acelui element, incluzând orice coordonate ce pot afecta intr-un fel sau altul acel element. Tabloul rezultat este similar cu [total_scroll_left, total_scroll_top]
cumulativeOffset(element) instanțã element: obiect Returneazã un tablou cu poziționãrile corecte ale elementului, incluzând și poziționãrile ce sunt impuse de elementele pãrinte poziționate. Tabloul returnat este similar cu [total_offset_left, total_offset_top]
within(element, x, y) instanțã element: obiect, x și y: coordonatele unui punct Testeazã dacã coordonatele unui punct dat se aflã în interiorul dreptunghiului delimitat de elementul
withinIncludingScrolloffsets(element, x, y) instanțã element: obiect, x și y: coordonatele unui point  
overlap(mode, element) instanțã mode: 'vertical' sau 'horizontal', element: obiect Metoda within() are nevoie sã fie apelatã chiar înaintea apelãrii acestei metode. Aceastã metodã va returna un numãr zecimal din intervalul 0.0 și 1.0 reprezentând procentul cu care o coordonatã depașește suprafața afișatã de un element. De exemplu, dacã elementul este un DIV pãtrat, cu latura de 100px și este poziționat în punctul (300,300), atunci funcția within(divPãtrat, 330, 330); overlap('vertical', divPãtrat); ar trebui sã returneze 0.10, însemnând cã punctul e la 10% (30px) distanțã de marginea de sus a DIV-ului.
clone(source, target) instanțã sursã: elementul obiect sau id, target: elementul obiect sau id Redimensioneazã și repoziționeazã elementul țintã identic cu elementul sursã.


Dacã se depisteazã erori, informații incomplete, inexacte sau fãrã sens, vã rog și voi încerca sã corectez cât mai repede.

Doresc pe această cale sã mulțumesc soției pentru sprijinul deosebit acordat în realizarea acestei traduceri.