Fejlesztői jegyzet a prototype.js használatához
verzió 1.4.0
Mi is ez?
Abban az esetben ha még nem találkoztál volna vele, a prototype.js egy JavaScript könyvtár, melyet Sam Stephenson készített. Ez a szabványos, nagyon jól átgondolt és megírt könyvtár nagy terhet vesz le mindazok válláról, akik a Web 2.0-t jellemző interaktivitást szeretnének az oldalaikon implementálni.
Ha már próbáltad használni ezt a könyvtárat akkor feltünhetett, hogy a dokumentáció nem a legerősebb oldala. Mint sok más hozzám hasonló fejlesztő, próbáltam a forráskódot olvasgatni és kísérletezni vele. Gondoltam jó dologl enne jegyzetelni miközben megismerem és ezt megosztani másokkal is.
Ezenkívül figyelmedbe ajánlok egy nem hivatalos referenciát a könyvtár által szolgáltatott objektumokról, osztályokról, függvényekről és kiterjesztésekről.
Azok a fejlesztők akik járatosak a Ruby programozási nyelvben, a példák és a referencia tanulmányozása közben észreveszik majd a hasonlóságot a Ruby sok beépített osztályával és a könyvtár által implementált kiterjesztésekkel.
A segédfüggvények
A könyvtár rengeteg előre definiált objektumot és segédfüggvényt tartalmaz. Ezen függvények nyilvánvaló célja, hogy sok felesleges gépeléstől és munkától mentse meg a fejlesztőt.
A $() függvény használata
A $() függyvény egy könnyen használható rövidítése a gyakran használt document.getElementById() DOM függvénynek. Az eredetihez hasonlóan a paraméterben átadott azonosítóval rendelkező elemmel tér vissza.
De tovább is megy egy kicsit, így több azonosítót is át lehet adni neki paraméterként és ebben az esetben egy objektum tömbbel fog visszatérni, ami tartalmazza az összes kért elemet. A következő példa ezt mutatja be.
<HTML> <HEAD> <TITLE> Tesztoldal </TITLE> <script src="prototype-1.4.0.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>Ez egy bekezdés</p> </div> <div id="myOtherDiv"> <p>Ez egy újabb bekezdés</p> </div> <input type="button" value=Test1 onclick="test1();"><br> <input type="button" value=Test2 onclick="test2();"><br> </BODY> </HTML>
Egy másik hasznos tulajdonsága ennek a függvénynek, hogy nem pusztán az azonosítót lehet neki átadni szövegként, hanem magát az elemet mint objektumot, ez pedig igen hasznos lehet azokban az esetekben amikor új függvényeket készítünk melyekben mindkét fajta paraméterezésre lehetőséget szeretnénk biztosítani.
Az $F() függvény használata
Az $F() függvény is egy hasznos rövidítés, bármilyen beviteli mező értékét képes visszaadni, akár egy lenyíló listáét is. A már az előzőekben leírtakhoz hasonlóan az azonosítót vagy magát az objektumot is át lehet adni paraméterként.
<script>
function test3()
{
alert( $F('userName') );
}
</script>
<input type="text" id="userName" value="Joe Doe"><br>
<input type="button" value=Test3 onclick="test3();"><br>
Az $A() függvény használata
Az $A() függvény a kapott paramétert tömbbé konvertálja.
Ez a függvény az Array osztály kiterjesztéseivel együtt használva sokkal egyszerűbbé teszi olyan függvények írását, melyekben változó számú paramétereket akarunk fogadni.
<script>
function shoutOut(){
sayHi('Hello, ', 'Homer', 'Bart', 'Marge', 'Snowball');
}
function sayHi(){
var names = $A(arguments).slice(1);
var phrase = arguments[0];
for(i=0; i<names.length; i++)
alert(phrase + names[i]);
}
</script>
<input type="button" value="Say hi to everybody" onclick="shoutOut();" >
A $H() függvény használata
A $H() függvény bármilyen asszociatív tömböt egy Hash objektummá konvertál.
<script>
function testHash()
{
var a = [];
//az asszociatív tömb feltöltése
a['first'] = 10;
a['second'] = 20;
a['third'] = 30;
//konvertájuk
var h = $H(a);
alert(h.toQueryString()); //displays: first=10&second=20&third=30
}
</script>
Az $R() függvény használata
Az $R() függvény pusztán csak egy rövidítése a new ObjectRange(lowerBound, upperBound, excludeBounds)-nek.
Az ObjectRange osztály dokumentációjában megtalálhatod a bővebb leírást. De azért nézzünk meg gyorsan egy egyszerű példát ami megmutatja, hogyan kell végigiterálni az each metódus segítségével. Erről a metódusról pedig az Enumerable osztály dokumentációjában olvashatsz bővebben.
<script>
function demoDollar_R(){
var range = $R(10, 20, false);
range.each(function(value, index){
alert(value);
});
}
</script>
<input type="button" value="Sample Count" onclick="demoDollar_R();" >
A Try.these() függvény használata
A Try.these() függvény akkor lehet hasznos számodra, ha több függvényhívást szeretnél egymás után végrehajtatni, mindaddig amíg az egyik sikeres nem lesz. Értelemszerűen több függvényt lehet neki paraméterként átadni és ezeket sorra elkezdi meghívni mindaddig amíg az egyik nem működik, és a függvény visszatérési értéke ennek visszadott értéke lesz.
A következő példában használt xmlNode.text függvény csak bizonyos böngészők esetében működik, a xmlNode.textContent függvény pedig más böngészőkkel vezet sikerre. A Try.these() használatával azzal kapjuk vissza a megfelelő eredményt amely működött.
<script>
function getXmlNodeValue(xmlNode){
return Try.these(
function() {return xmlNode.text;},
function() {return xmlNode.textContent;)
);
}
</script>
Az Ajax objektum
Az eddig leírt segédfüggvények szépek és jók, de valljuk be, nem igazán rengetik meg a világot. Talán ezeket magad is megcsináltad és ott vannak már a saját szkriptjeidben. De ezek a függvények csak a jéghegy csúcsát jelentik.
Biztos vagyok benne, hogy a prototype.js AJAX lehetőségei keltik fel majd igazán az érdeklődésedet. Csapjunk is bele, nézzük meg miként teszi könnyebbé az életedet a könyvtár ha AJAX használtára szükséged.
Az Ajax objektum egy előre definiált objetum amit a könyvtár hoz létre azért, hogy elfedje és egyszerűsítse a trükközést ami az AJAX funkcionalitáshoz szükséges. Az objektum több osztályt is tartalmaz amely AJAX logikát tartalmaz. Nézzünk meg párat ezekből.
Az Ajax.Request osztály
Ha nem használsz semmiféle könyvtárat akkor elég sok kódot kell írnod ahhoz, hogy létrehozz egy XMLHttpRequest objektumot és nyomonkövesd a folyamatokat aszinkron, majd feldolgozd a választ. Na és szerencsésnek mondhatod magad, ha csak egyfajta böngészővel foglalkoznod.
Ennek segítésére a könyvtárban definiálva van az Ajax.Request osztály.
Vegyünk egy példát, mondjuk van egy alkalmazásod ami képes kommunikálni a szerverrel a http://yoursever/app/get_sales?empID=1234&year=1998 hivatkozáson keresztül és a választ a következő XML formában küldi vissza.
<?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>
Az Ajax.Request objektum segítségével nagyon egyszerű a szerverhez eljuttatni a kérést és a kapott választ feldolgozni. A következő példa ezt mutatja be.
<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>
Megfigyelted az Ajax.Request objektumnak átadott paramétert? Ez {method: 'get', parameters: pars, onComplete: showResponse} egy névtelen objektumot reprezentál. Ez azt jelenti, hogy egy olyan objektumot adunk át amelynek a method tulajdonsága a 'get' szöveges értéket tartalmazza, a parameters tulajdonság a HTTP kérés paramétereit, az onComplete pedig a showResponse függvényre való hivatkozást tartalmazza.
Ezeken kívül van még néhány olyan tulajdonság amit meg lehet adni, ilyen például az asynchronous, aminek az értéke true vagy false lehet és azt határozza meg, hogy az AJAX hívás a szerver felé aszinkron módon fog-e történni (az alapértelmezett érték a true).
Összességében ez a paraméter határozza meg az AJAX hívás opcióit. A példánkban az első paraméterben átadott címet hívjuk meg HTTP GET paranccsal és a pars paraméterben megadott paraméterlistát kapja meg, majd az Ajax.Request objektum a showResponse függvényt fogja meghívni miután megérkezett a válasz a kérésünkre.
Mint ahogy ismeretes, az XMLHttpRequest folyamatosan jelzi a HTTP kérés állapotát. Ez az állapot négy különböző esetet takar: Loading, Loaded, Interactive, vagy Complete. Megmondhatod az Ajax.Request objektumnak, hogy hívjon meg egy adott függvényt valamilyen állapot elérésekor, ezek közül a Complete a leggyakrabban használt. Ahhoz, hogy az objektum tudja milyen függvényt kell meghívnia az állapot elérésekor, egyszerűen az onXXXXX tulajdonságon keresztül lehet megadni számára, mint ahogy a fenti példában az onComplete szerepel. Ez a függvény egy paramétert fog megkapni, ami maga az XMLHttpRequest objektum lesz. Ezt az objektumot tudod arra használni, hogy kinyerd a visszakapott választ vagy éppen leellenőrizd a status tulajdonságot, ami a HTTP kérés válaszkódja.
Van még két másik érdekes opció az eredmények feldolgozásához. Meg tudunk adni a onSuccess paraméterben egy függvényt amit sikeres AJAX hívás esetén fog meghívni, míg az onFailure tulajdonságon keresztül olyan függvényt, amit akkor hív meg, ha szerveroldali hiba történt. Az onXXXXX opciókhoz hasonlóan ezek is az XMLHttpRequest objektumot fogják megkapni egyetlen paraméterként.
Az 1.4.0-s verzióban egy újfajta eseménykezelés került bevezetésre. Ha van olyan kódod amit mindig le kellene futtatni egy adott esemény kiváltódásakor, függetlenül attól, hogy melyik AJAX kérés váltotta azt ki, akkor az új Ajax.Responders objektumot tudod használni.
Tegyük fel, hogy szeretnél valamiféle látványelemet használni arra, hogy a felhasználó felé jelezd azt, hogy az AJAX hívás folyamatban van. Ekkor két globális eseménykezelőt tudsz használni, az egyik megjeleníti az ikont az első hívás kezdetén, a másik pedig elrejtni amikor az utolsó válasz is megérkezett. Na de lássuk a példát.
<script>
var myGlobalHandlers = {
onCreate: function(){
Element.show('systemWorking');
},
onComplete: function() {
if(Ajax.activeRequestCount == 0){
Element.hide('systemWorking');
}
}
};
Ajax.Responders.register(myGlobalHandlers);
</script>
<div id='systemWorking'><img src='spinner.gif'>Loading...</div>
Az eddigi példákban nem dolgoztuk fel a kapott XML választ, hanem csak egyszerűen beraktuk egy szövegdobozba. Valós környezetben először ki kell nyerni az értékes információt belőle majd néhány elemet az oldalon módosítani, vagy esetleg XSLT transzformáció segítségével HTML kimenetet produkálunk az oldal számára.
Erről bővebben az Ajax.Request és az options referenciákbál találhatsz.
Az Ajax.Updater osztály használata
Ha esetleg a szerver már HTML formában küldi a választ a kérésre, akkor a könyvtár Ajax.Updater osztályával könnyebbé teheti az életedet, hiszen ennek csak meg kell mondanod, hogy melyik elemet szeretnéd feltölteni az AJAX hívásra kapott HTML válasszal. De a példa beszédesebb, mint ahogy le tudnám írni.
<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>
Mint észrevetted, a kód nagyon hasonló az eddigi példákban találhatókhoz az onComplete függvény megadásának kivételével illetve a konstruktorban található elemazonosítóval. Na de változtassunk egy kicsit a kódon, hogy megnézzük miként is lehet a szerveroldali hibákat lekezelni.
Ehhez meg kell adnunk egy, a már fentebb leírt opciót, ez pedig az onFailure. Ezenkívül azt is meghatározzuk, hogy a megadott placeholder csak abban az esetben kerüljön feltöltésre, ha a művelet sikeres volt. Ehhez az elsőnek átadott elemazonosító paraméter helyett egy objektumot kell átadni két tulajdonsággal: success (akkor hívódik meg ha minden sikeres volt) és failure (ez pedig akkor ha gond volt). De mi most nem fogjuk használni az failure tulajdonságot, hanem az onFailure tulajdonságban megadjuk a reportError függvényt.
<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('Bocsi, ez nem jött össze.');
}
</script>
<input type=button value=GetHtml onclick="getHTML()">
<div id="placeholder"></div>
De akkor sem kell pánikba esni, ha a szerver HTML formátum helyett egy JavaScript kódot ad válaszként, mert az Ajax.Updater objektum ebben az esetben kiértékeli azt. Ahhoz, hogy az objektum a választ JavaScriptként kezelje, egyszerűen a tulajdonságok listájához hozzá kell adni az evalScripts: true; paramétert utolsóként az objektum konstruktorában.
Bővebb leírást erről az Ajax.Updater és az options referenciáinál találhatsz.
prototype.js referencia
Kiterjesztések a JavaScript osztályokhoz
Az egyik módja annak, hogy a prototype.js könyvtár új funkciókat biztosít számunkra az, hogy kiterjeszti a már meglévő JavaScript osztályokat.
Kiterjesztések az Object osztályhoz
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| extend(destination, source) | statikus | destination: bármilyen objektum, source: bármilyen objektum | Az örököltetést valósítja meg oly módon, hogy átmásolja a source összes tulajdonságát és metódusát a destination objektumba. |
| inspect(targetObj) | statikus | targetObj: bármilyen objektum | Szöveges, könnyen olvasható formában reprezentálja a targetObj objektumot. Ez adja meg az alapértelmezett visszatérési értékét a toString függvénynek, ha az adott objektumban nincs definiálva az inspect példánymetódus. |
Kiterjesztések a Number osztályhoz
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| toColorPart() | példány | (nincs) | A számot hexadecimális formában adja vissza. Ez hasznos amikor az RGB komponenst a HTML reprezentációra akarjuk konvertálni. |
| succ() | példány | (nincs) | A következő számot adja vissza, ez olyan esetben használható amikor iterátor van. |
| times(iterator) | példány | iterator: egy Function(value, index) függvény objektum | Meghívja az iterator függvényt folyamatosan átadva neki a value és index paramétereket, ami az iterátor jelenlegi értékét és a aktuális indexét tartalmazza. |
A következ példa 10 ablakot fog egymás után megnyitni, melyekben 0-tól kezdve 9-ig jelennek meg számok.
<script>
function demoTimes(){
var n = 10;
n.times(function(value, index){
alert(index);
});
/***************************
* De így is lehet használni:
* (10).times( .... );
***************************/
}
</script>
<input type=button value="Test Number.times()" onclick="demoTimes()">
Kiterjesztések a Function osztályhoz
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| bind(object) | példány | object: az objektum ami tartalmazza a metódust | Visszadja egy példányát a függvénynek a függvényt(= metódust) tartalmazó objektumból. A visszaadott függvénynek ugyanazon argumentumai lesznek, mint az eredetinek volt. |
| bindAsEventListener(object) | példány | object: az objektum ami tartalmazza a metódust | Visszadja egy példányát a függvénynek a függvényt(= metódust) tartalmazó objektumból. A visszaadott függvénynek az adott event objektum lesz a paramétere. |
Nézzük meg az egyik kiterjesztést a gyakorlatban.
<input type=checkbox id=myChk value=1> Test?
<script>
//Az osztály deklarációja
var CheckboxWatcher =
Class.create(); //az osztály implementációjának definíciója
CheckboxWatcher.prototype = {
initialize: function(chkBox, message) {
this.chkBox = $(chkBox);
this.message = message;
//adjuk meg a metódust az eseményhez
this.chkBox.onclick =
this.showMessage.bindAsEventListener(this);
},
showMessage: function(evt) {
alert(this.message + ' (' + evt.type + ')');
}
};
var watcher = new CheckboxWatcher('myChk', 'Changed');
</script>
Kiterjesztések a String osztályhoz
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| stripTags() | példány | (nincs) | Visszaadja s szöveget HTML és XML tagok nélkül |
| stripScripts() | példány | (nincs) | Visszaadja s szöveget <script /> blokkok nélkül |
| escapeHTML() | példány | (nincs) | Visszaadja s szöveget a HTML karakterek eszképelése után. |
| unescapeHTML() | példány | (nincs) | Az escapeHTML() fordítottja |
| extractScripts() | példány | (nincs) | Egy Array objektumot ad vissza, ami tartalmazza a szövegben található összes <script /> blokkot. |
| evalScripts() | példány | (nincs) | Kiértékeli a szövegben található összes <script /> blokkot. |
| toQueryParams() | példány | (nincs) | A paraméterlistát szétválasztja egy asszociatív tömbbe ami a paraméter neve által van indexelve. |
| parseQuery() | példány | (nincs) | Ugyanaz, mint a toQueryParams(). |
| toArray() | példány | (nincs) | A szöveg karaktereit szétválasztja egy tömbbe. |
| camelize() | példány | (nincs) | Egy kötöjellel elválasztott szöveget camelCase formára konvertál. Ez nagyon hasznos lehet, ha olyan kódot írunk ami stílus tulajdonságokat használ. |
Kiterjesztések az Array osztályhoz
Először is az Array az Enumerable kiterjsztése, így minden metódus elérhető ami az Enumerable objektumban megtalálható. Emellet a következő metódusok lettek implementálva:
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| clear() | példány | (nincs) | Kiüríti a tömböt és visszaadja magát a tömböt. |
| first() | példány | (nincs) | Visszaadja a tömb első elemét. |
| last() | példány | (nincs) | Visszaadja a tömb utolsó elemét. |
| compact() | példány | (nincs) | Visszaadja a tömböt azon elemek nélkül melyekben null vagy undefined szerepel. Ez a metódus nem változtaja meg magát a tömböt. |
| flatten() | példány | (nincs) | Egy dimenziós tömböt ad vissza úgy, hogy rekurzívan végigmegy az elemeken és azok amelyek tömböt tartalmaznak, szintén belekerülnek a visszaadott tömbbe. |
| without(value1 [, value2 [, .. valueN]]) | példány | value1 ... valueN: értékek amelyeket ki kell venni a tömbbol. | Visszaadja a paraméterekben megadott értékek nélküli tömbböt. |
| indexOf(value) | példány | value: az érték amit keresünk. | Visszaadja a pozícióját annak az elemnek ami tartalmazza a megadott value értékét. Az eredmény -1 lesz ha a value nem található. |
| reverse([applyToSelf]) | példány | applyToSelf: azt jelöli, hogy magát a tömböt is meg kell-e fordítani. | Megfordítja az elemek sorrendjét a tömbben és azt adja vissza. Ha nincs paraméter megadva vagy az értéke true, akkor magát a tömbböt is megfordítja. Egyéb esetben változatlan marad. |
| shift() | példány | (nincs) | Visszaadja az első elemet és kiveszi a tömbből, így annak mérete eggyel csökken. |
| inspect() | példány | (nincs) | Szövegesen formázott formában adja vissza a tömb elemeit. |
Kiterjesztések a document DOM objektumhoz
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| getElementsByClassName(className [, parentElement]) | példány | className: a CSS osztály neve, parentElement: objektum vagy elemazonosító amely a keresett elemeket tartalmazhatja. |
Visszaadja az összes olyan elemet amely kapcsolatban van a megadott CSS osztállyal. Ha nincs parentElement megadva, akkor az egész dokumentumban keres. |
Kiterjesztések az Event osztályhoz
| Tulajdonság | Típus | Leírás |
|---|---|---|
| KEY_BACKSPACE | Number | 8: Konstans, a Backspace kódja. |
| KEY_TAB | Number | 9: Konstans, a Tab kódja. |
| KEY_RETURN | Number | 13: Konstans, a Return kódja. |
| KEY_ESC | Number | 27: Konstans, az Esc kódja. |
| KEY_LEFT | Number | 37: Konstans, a balra nyíl kódja. |
| KEY_UP | Number | 38: Konstans, a felfele nyíl kódja. |
| KEY_RIGHT | Number | 39: Konstans, a jobbra nyíl kódja. |
| KEY_DOWN | Number | 40: Konstans, a lefelé nyíl kódja. |
| KEY_DELETE | Number | 46: Konstans, a Delete kódja. |
| observers: | Array | A cachelt obszerverek listája. |
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| element(event) | statikus | event: egy Event objektum | Az eseményt kiváltó elemet adja vissza. |
| isLeftClick(event) | statikus | event: egy Event objektum | true a visszatérési értéke ha az egér bal gombjával lett kattintva. |
| pointerX(event) | statikus | event: egy Event objektum | Az egér mutatójának x koordinátáját adja vissza az oldalon. |
| pointerY(event) | statikus | event: egy Event objektum | Az egér mutatójának y koordinátáját adja vissza az oldalon. |
| stop(event) | statikus | event: egy Event objektum | Akkor használd, ha meg akarsz szakítani egy adott eseményt. |
| findElement(event, tagName) | statikus | event: egy Event objektum, tagName: a keresett tag neve. |
Megkeresi a DOM fában felfelé indulva az első olyan elemet ami az adott névvel rendelkezik, kezdve attól az elemtől ahol az esemény kiváltódott. |
| observe(element, name, observer, useCapture) | statikus | element: objektum vagy azonosító, name: az esemény neve (pl. 'click', 'load'), observer: a függvény ami lekezeli az eseményt, useCapture: ha true, akkor a capture fázisban, ha pedig false akkor bubbling fázisban kezeli le az eseményt. |
Egy eseménykezelő függvényt lehet adni egy eseményhez. |
| stopObserving(element, name, observer, useCapture) | statikus | element: objektum vagy azonosító,
name: az esemény neve (pl. 'click', 'load'), observer: a függvény ami lekezeli az eseményt, ha true, akkor a capture fázisban, ha pedig false akkor bubbling fázisban kezeli le az eseményt. |
Leveszi az eseménykezelőt az eseményről. |
| _observeAndCache(element, name, observer, useCapture) | statikus | Privát metódus, nem kell foglalkozni vele. | |
| unloadCache() | statikus | (nincs) | Privát metódus, nem kell foglalkozni vele. Kitörli az összes cachelt obszervert a memóriából. |
Nézzük meg hogyan tudjuk ezt az objektumot használni a window objektum load eseményére.
<script>
Event.observe(window, 'load', showMessage, false);
function showMessage() {
alert('Page loaded.');
}
</script>
A prototype.js által deinifált új objektumok és osztályok
A másik út amin keresztül a a könyvtár segít neked, hogy sok olyan objektumot tartamaz amely egyrészt segíti az objektumorientált tervezést, másrészt pedig közös funkcionalitásokat tartalmaz.
A PeriodicalExecuter objektum
Az objektum arra szolgáltat logikát, hogy adott időközönként egy függvényt folyamatosan meg tudjunk hívni.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](callback, interval) | konstruktor | callback: egy paraméter nélküli függvény, interval: másodpercek száma | Létrehozza egy példányát az objektumnak ami a függvényt folyamatosan meghívja. |
| Tulajdonság | Típus | Leírás |
|---|---|---|
| callback | Function() | A meghívandó függvény, nem fog semmilyen paramétert átadni neki. |
| frequency | Number | Az intervallum másodpercekben |
| currentlyExecuting | Boolean | Az jelzi, hogy a függvényhívás folyamatban van-e. |
A Prototype objektum
A Prototype objektumnak nincs semmi különösebb szerepe, egyszerűen csak deklarálja a használt könyvtár verzióját.
| Tulajdonság | Típus | Leírás |
|---|---|---|
| Version | String | A könyvtár verziószáma |
| emptyFunction | Function() | Egy üres függvény objektum |
| K | Function(obj) | Egy függvény objektum ami visszaadja az átadott paramétert. |
Az Enumerable objektum
Az Enumerable objektum segítségével sokkal elegánsabb kódot lehet írni elemek iterálására egy listaszerű struktúrában.
Sok egyéb objektum terjeszti ki az Enumerable objektumot.
| Tulajdonság | Típus | Leírás |
|---|---|---|
| Version | String | A könyvtár verziószáma |
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| each(iterator) | példány | iterator: egy függvény objektum Function(value, index) formában | Az adott iterátor meghívja a függvényt átadva neki az első paraméterben az adott elemet a listában, a második paraméterben pedig az elem indexét. |
| all([iterator]) | példány | iterator: egy függvény objektum Function(value, index) formában, opcionális. | Ez a függvény arra jó, hogy tesztüljük az egész gyüjteményt az adott függvény használatával. Az all false értéket ad vissza, ha az iterator függvény false vagy null értéket ad vissza bármelyik elemre. Egyébként pedig true lesz a visszatérési értéke. Ha nincs iterátor megadva, akkor magán az elemen vizsgálja meg a false vagy null értéket. |
| any(iterator) | példány | iterator: egy függvény objektum Function(value, index) formában, opcionális. | >Ez a függvény arra jó, hogy tesztüljük az egész gyüjteményt az adott függvény használatával. Az any true értéket ad vissza, ha az iterator függvény nem false vagy null értéket ad vissza bármelyik elemre. Egyébként pedig false lesz a visszatérési értéke. Ha nincs iterátor megadva, akkor magán az elemen vizsgálja meg hogy az értéke más-e mint false vagy null. |
| collect(iterator) | példány | iterator: egy függvény objektum Function(value, index) formában | Meghívja az iterator függvényt minden egyes elemre és minden eredményt egy tömbben ad vissza a megfelelő sorrendben. |
| detect(iterator) | példány | iterator: egy függvény objektum Function(value, index) formában | Meghívja az iterator függvényt minden egyes elemre és az első olyan elemmel fog visszatérni aminél az iterator függvény visszatérési értéke true (vagy pontosabban nem false). Ha nincs ilyen elem, akkor a detect null ;rt;ket fog visszaadni. |
| entries() | példány | (nincs) | Ugyanaz, mint a toArray(). |
| find(iterator) | példány | iterator: egy függvény objektum Function(value, index) formában | Ugyanaz, mint a detect(). |
| findAll(iterator) | példány | iterator: egy függvény objektum Function(value, index) formában | Meghívja az iterator függvényt minden egyes elemre és egy tömbben visszaadja mindazokat, amelyeknél az iterátor függvény visszatérési értéke true volt. Ez a függvény a reject() ellentéte. |
| grep(pattern [, iterator]) | példány | pattern: egy RegExp objektum ami az elemek kiválasztására használhatunk, iterator: egy függvény objektum Function(value, index) formában | Az összes elemet megvizsgálja az átadott pattern ellenében. A függvény egy tömbben fogja visszaadni azokat az elemeket, melyek megfeleltek a reguláris kifejezésnek. Ha az iterator meg van adva, akkor a visszaadott tömb a hívás eredményeit fogja tartalmazni minden egyes elemre amit megfelelt a kifejezésnek. |
| include(obj) | példány | obj: bármilyen objektum | Megpróbálja megkeresni az adott objektumot a gyűjteményben. true lesz a visszatérési értéke ha megtalálta, egyébként pedig false. |
| inject(initialValue, iterator) | példány | initialValue: bármilyen objektum ami inicializáló értékként felhasználható, iterator: egy függvény objektum Function(value, index) formában | Összeköti az összes elemet az iterator függvény segítésével. Az iterátort az előző iteráció eredményével hívja meg az accumulator paraméterben. Az első iteráció az initialValue értékét veszi az accumulator paraméterben. A visszatérési érték az utolsó hívás eredménye lesz. |
| invoke(methodName [, arg1 [, arg2 [...]]]) | példány | methodName: a metódus nevet ami minde egyes elemre meg lesz hívva, arg1..argN: argumentumok, melyek a metódusnak át lesznek adva. | A megadott metódust meghívja minden egyes elemre átadva neki az adott paramétereket (arg1 to argN), a visszatérési érték pedig a függvényhívások eredménye lesz egy tömbben. |
| map(iterator) | példány | iterator: egy függvény objektum Function(value, index) formában | Ugyanaz mint a collect(). |
| max([iterator]) | példány | iterator: egy függvény objektum Function(value, index) formában | A legnagyobb értékű elemet adja vissza a gyűjteményben vagy a legnagyobb eredéményét az iterátorhívásoknak, ha az iterator meg volt adva. |
| include(obj) | példány | obj: bármilyen objektum | Ugyanaz mint az include(). |
| min([iterator]) | példány | iterator: egy függvény objektum Function(value, index) formában | A legkisebb értékű elemet adja vissza a gyűjteményben vagy a legkisebb eredéményét az iterátorhívásoknak, ha az iterator meg volt adva. |
| partition([iterator]) | példány | iterator: egy függvény objektum Function(value, index) formában | Egy tömbböt fog visszaadni amely másik két tömbböt tartalmaz. Az első az összes olyan elemet tartalmazza, melyen az iterátorhívás true eredményt produkált, a másikban pedig a többi elem lesz. Ha az iterator nem volt megadva, akkor az első tömbben azon elemek lesznek, melyek true értéket produkálnak, a másikban pedig értelemszerűen a többi elem lesz. |
| pluck(propertyName) | példány | propertyName: a tulajdonság neve, melzet minden elemből ki kell olvasni. Név helyett tartalmazhatja a tulajdonság indexét is. | Egy tömbben az adott tulajdonság értékeit adja vissza minden egyes elemből. |
| reject(iterator) | példány | iterator: egy függvény objektum Function(value, index) formában | Meghívja az iterator függvényt minden egyes elemre és egy tömbben visszaadja mindazokat, amelyeknél az iterátor függvény visszatérési értéke false volt. Ez a függvény a findAll() ellentéte. |
| select(iterator) | példány | iterator: aegy függvény objektum Function(value, index) formában | Ugyanaz mint a findAll(). |
| sortBy(iterator) | példány | iterator: egy függvény objektum Function(value, index) formában | Az elemeket sorbarendezve egy tömbben fogja visszaadni a függvényhívás eredményétől függően. |
| toArray() | példány | (nincs) | Egy tömbben adja vissza a gyűjtemény összes elemét. |
| zip(collection1[, collection2 [, ... collectionN [,transform]]]) | példány | collection1 .. collectionN: enumerációk az egyesítéshez, transform: egy függvény objektum Function(value, index) formában | Összevonja az adott gyűjteményeket az eredeti gyűjteménnyel. Az eredménye egy új tömb lesz, amiben az elemek száma megegyezik az eredetiével és minden egyes elem egy újabb tömb. Ha a transform függvény meg van adva, akkor a belső tömbbök a visszatérés előtt ezzel lesznek feldolgozva. Egy gyors példa: [1,2,3].zip([4,5,6], [7,8,9]).inspect() visszatérési értéke "[ [1,4,7],[2,5,8],[3,6,9] ]" |
A Hash objektum
A Hash objektum egy hash struktúrát implementál, azaz Kulcs:Érték párosok gyűjteménye.
Minden elem a Hash objektumban egy tümb két elemmel: az első a kulcs, a másik pedig az érték. Minden elemnek két tulajdonsága van: a key és a value.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| keys() | példány | (nincs) | Egy tömbben visszaadja az elemek kulcsait. |
| values() | példány | (nincs) | Egy tömbben visszaadja az elemek értékeit. |
| merge(otherHash) | példány | otherHash: Hash objektum | Az adott has objektumot összevonja az átadott hash objektummal és egy új hash objektumot fog visszaadni. |
| toQueryString() | példány | (nincs) | Az öszes elemet a hash objektumban szöveges formában fogja visszaadni, 'key1=value1&key2=value2&key3=value3' |
| inspect() | példány | (nincs) | Szintén egy jól formázott szövegként adja vissza a hash kulcs:érték párosait. |
Az ObjectRange osztály
Az Enumerable osztályból származik
Értékek sorozatát reprezentája alsó és felső határokkal.
| Tulajdonság | Típus | Kind | Leírás |
|---|---|---|---|
| start | (bármi) | példány | Az alsó határa a tartománynak |
| end | (bármi) | példány | A felső határa a tartománynak |
| exclusive | Boolean | példány | Azt határozza meg, hogy a határok beleértendőek-e a tartományba. |
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](start, end, exclusive) | konstruktor | start: az alsó határ, end: a felső határ, exclusive: a határok benne lesznek a a tartományban | Egy tartományt hoz létre, kezdve a start paramétertől az end paraméter értékéig. Fontos megjegyezni, hogy a start és end objektumoknak ugyanolyan típusnak kell lennie és kell definiálniuk egy succ() metódust. |
| include(searchedValue) | példány | searchedValue: a keresett érték | Megvizsgálja, hogy az adott értéket tartalmazza-e a tartomány. A visszatérési érték true vagy false lehet. |
A Class objektum
A Class objektum más osztályok deklarálásakor használatos a könyvtárban. Ennek az objektumnak a használatával egy osztály deklarációjánál azt érjük el, hogy támogatni fogja az initialize() metódust, amely konstruktorként működik.
Lássunk egy példát.
//deklaráljuk az osztályt
var MySampleClass = Class.create();
//implementáljuk magát az osztályt
MySampleClass.prototype = {
initialize: function(message) {
this.message = message;
},
showMessage: function(ajaxResponse) {
alert(this.message);
}
};
//most pedig példányosítsuk
var myTalker = new MySampleClass('hi there.');
myTalker.showMessage(); //mutassuk meg az üzenetet
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| create(*) | példány | (bármi) | Definiál egy konstruktort az új osztályhoz. |
Az Ajax objektum
Ez az objektum szolgáltat kiindulást rengeteg más osztályhoz, amely AJAX funkcionalitást hivatott szolgáltatni.
| Tulajdonság | Típus | Kind | Leírás |
|---|---|---|---|
| activeRequestCount | Number | példány | A folyamatban lévő AJAX kérések száma. |
| Method | Kind | Arguments | Leírás |
|---|---|---|---|
| getTransport() | példány | (nincs) | Egy új XMLHttpRequest objektumot ad vissza |
Az Ajax.Responders objektum
Az Enumerable objektumból származik.
Az objektum olyan objektumok listáját tartalmazza, amelyek Ajaxhoz kapcsolódó eseményekkor hívódnak meg. Ezt az objektumot lehet például használni, amikor egy globális kivételkezelést akarunk megvalósítani az AJAX műveletekhez.
| Tulajdonság | Típus | Kind | Leírás |
|---|---|---|---|
| responders | Array | példány | Azon objektumok listája, melyek AJAX eseményekre vannak beregisztrálva. |
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| register(responderToAdd) | példány | responderToAdd: meghívandó objektum. | Az responderToAdd paraméterben megadott objektumnak tartalmazni kell az AJAX eseményekhez tartozó metódosuokat(onCreate, onComplete, onException, stb.) Amikor a megfelelő esemény kiváltódik, akkor az összes regisztrált objektumon meghívódik a megfelelő lekezelő metódus. |
| unregister(responderToRemove) | példány | responderToRemove: objektum, amit szeretnénk a listából kivenni. | A responderToRemove paraméterben átadott objektumot kiveszi a regisztrált objektumok listájából. |
| dispatch(callback, request, transport, json) | példány | callback: az AJAX esemény neve, request: az Ajax.Request objektum ami az eseményt kiváltja, transport: az XMLHttpRequest objektum amely tartalmazta (vagy tartalmazza) az AJAX hívást, json: a X-JSON fejléce a válasznak (ha van) | Végigmegy a regisztrált objektumok listáján és megkeresi azokat, amelyek tartalmazzák callback paraméterben megadott metódost. Ezután ezeket meghívja a másik 3 paraméterrel. Ha az AJAX válasz tartalmaz X-JSON HTTP fejlécet JSON tartalommal, akkor az ki lesz értékelve és átadja paraméterként. Ha az esemény onException, akkor a transport paraméter értéke a kivétel lesz és nem a >json. |
Az Ajax.Base osztály
Ez az osztály szolgál alaposztályul a legtöbb osztályhoz az Ajax objektumban.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| setOptions(options) | példány | options: AJAX options | Beállítja a kívánt opciókat az AJAX művelethez |
| responseIsSuccess() | példány | (nincs) | true lesz a visszatérési érték, ha az AJAX művelet sikeres volt, egyébként pedig false |
| responseIsFailure() | példány | (nincs) | Az ellentéte az responseIsSuccess() metódusnak. |
Az Ajax.Request osztály
Az Ajax.Base osztályból származik
Összefoglalja az AJAX műveleteket
| Tulajdonság | Típus | Kind | Leírás |
|---|---|---|---|
| Events | Array | statikus | A lehetséges események/állapotok listája egy AJAX művelethez. A lista értékei: 'Uninitialized', 'Loading', 'Loaded', 'Interactive', és 'Complete.' |
| transport | XMLHttpRequest | példány | Az XMLHttpRequest objektum ami tartalmazz az AJAX műveletet |
| url | String | példány | A kéréshez tartozó URL. |
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](url, options) | konstruktor | url: a hívandó url, options: AJAX opciók | Létrehozza az adott objektum egy példányát ami meg fogja hívni az adott url-t a megadott opciókkal. Az onCreate esemény ki fog váltódni a konstruktor hívása közben. Fontos: Semmi nem fog történni ha az adott url nem felel meg a böngésző biztonsági beállításainak. Sok esetben a böngésző nem fogja lekérni az adott hivatkozást ha az nem ugyanarra a hostra (domain) mutat mint az aktuális oldalé. (Köszi Clay). |
| evalJSON() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Belülről hívódik meg az az AJAX válasz X-JSON HTTP fejléc tartalmának kiértékelésére. |
| evalReponse() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Ha az AJAX válasznak a Content-type fejléce text/javascript, akkor a válasz tartalma ki lesz értékelve ennek a metódusnak a segítségével. |
| header(name) | példány | name: HTTP fejléc neve | Ezt a metódus tipikusan nem szokás kívülről meghívni. Az AJAX válasz adott HTTP fejlécének lekérdezésére szolgál. |
| onStateChange() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Ezt maga az objektum hívja meg az AJAX hívás státuszának változásakor. |
| request(url) | példány | url: az AJAX hívás url-je | Ezt a metódus tipikusan nem szokás kívülről meghívni. Ez már a konstruktorban meghívódik. |
| respondToReadyState(readyState) | példány | readyState: állapotazonosító (1-től 4-ig) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Ezt maga az objektum hívja meg az AJAX hívás státuszának változásakor. |
| setRequestHeaders() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Ezt maga az objektum hívja meg a HTTP fejléc összerakására. |
Az options argumentum objektum
Az AJAX műveletek fontos része az options argumentum. Önmagában nem létezik az options osztály. Bármilyen objektum átadható, amennyiben rendelkezik a szükséges tulajdonságokkal. Ez hasonló az anoním függvények készítéséhez az AJAX hívások esetén.
| Tulajdonság | Típus | Alapérték | Leírás |
|---|---|---|---|
| method | String | 'post' | A HTTP kérés módja |
| parameters | String | '' | url-formázott listája az kérésben átadandó értékeknek |
| asynchronous | Boolean | true | Azt jelzi, hogy az AJAX hívást asszinkron módon kell-e végezni |
| postBody | String | undefined | Content passed to in the request's body in case of a HTTP POST |
| requestHeaders | Array | undefined | A hívásban átadandó HTTP fejlécek listája. Az elemek számának párosnak kell lennie, minden páratlan elem egy fejléc elem nevét tartalmazza, az azt követő értéknek pedig az értéknek szöveges formában. Például:['my-header1', 'this is the value', 'my-other-header', 'another value'] |
| onXXXXXXXX | Function(XMLHttpRequest) | undefined | Egyedi függvény ami a megfelelő esemény/státusz elérésekor hívódik meg az AJAX hívás során. Például var myOpts = {onComplete: showResponse, onLoaded: registerLoaded};. A függvény egy paramétert fog kapni, ami az XMLHttpRequest objektumot tartalmazza. |
| onSuccess | Function(XMLHttpRequest) | undefined | Egyedi függvény ami a az AJAX hívás sikeres befejezésekor hívódik meg. A függvény egy paramétert fog kapni, ami az XMLHttpRequest objektumot tartalmazza. |
| onFailure | Function(XMLHttpRequest) | undefined | Egyedi függvény ami a az AJAX hívás sikertelen befejezésekor hívódik meg. A függvény egy paramétert fog kapni, ami az XMLHttpRequest objektumot tartalmazza. |
| insertion | Function(Object, String) | null | Olyan függvény amely a visszaadott szöveget beszúrja egy adott elembe. Két paramétere van, az elsőben a frissítendő elemet, mint objektumot kell átadni, míg a másodikban a szöveget. Csak az Ajax.Updater objektummal használható. |
| evalScripts | Boolean | undefined, false | Azt határozza meg, hogy a válasz érkezésekor ki kell-e értékelni a szkript blokkot. Csak az Ajax.Updater objektummal használható. |
| decay | Number | undefined, 1 | Meghatározza a folyamatos lelassulást(növekedést) az Ajax.PeriodicalUpdater objektum frissítési gyakoriságában amikor az utolsó válasz azonos az előzőével. Például ha 2 a beállított érték és egy frissítés után azonos válasz érkezik az előzővel, akkor az objektum kétszer annyi ideig fog várni a következő frissítéssel. Ha ez újra megismétlődik, akkor legközelebb már négyszer annyi ideig vár és így tovább. Hagyd undefined értéken vagy adj át 1-t a lassulás elkerülésére. |
Az Ajax.Updater osztály
Az Ajax.Request objektumból öröklődik.
Akkor haszálatios, ha a lekért url HTML formában adja vissza a választ és azt az oldal egy adott elemébe akarjuk beszúrni. De akkor is használhatjuk, ha a válasz <script> blokkokat tartalmaz amit ki kell értékelni. Ebben az esetben használd az evalScripts tulajdonságot.
| Tulajdonság | Típus | Fajta | Leírás |
|---|---|---|---|
| containers | Object | példány | Az objektum két tulajdonságot tartalmaz: containers.success használatos amikor az AJAX hívás sikeres, és containers.failure használatos egyéb esetekben. |
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](container, url, options) | konstruktor | container: egy elemazonosító, maga az elem vagy egy objektum két tulajdonsággal - object.success elem (vagy azonosító) ami sikeres AJAX hívás esetén lesz használatos, és object.failure elem (vagy azonosító) ami egyéb esetekben lesz használva. url: a meghívandó url, options: AJAX options | Létrehozza egy példányát az objektumnak ami meghívja az adott url-t a megfelelő opciókkal. |
| updateContent() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Az objektum hívja meg amikor megérkezik a válasz, frissíti az adott elem tartalmát a HTML válasszal vagy meghívja az insertion opcióban megadott függvényt. Két paramétere van, az elsőben a frissítendő elemet, mint objektumot adja át, a másodikban a szöveget. |
Az Ajax.PeriodicalUpdater osztály
Az Ajax.Base osztályból származik.
Ez az osztály ismétlődően példányosít és használ egy Ajax.Updater objektumot egy oldalelem frissítésére, vagy bármilyen más feladatot elvégez amit az Ajax.Updater el tud végezni. Bővebben az Ajax.Updater leírásánál talász információt.
| Tulajdonság | Típus | Fajta | Leírás |
|---|---|---|---|
| container | Object | példány | Ez egyenesen az Ajax.Updater konstruktorának lesz átpasszolva. |
| url | String | példány | Ez egyenesen az Ajax.Updater konstruktorának lesz átpasszolva. |
| frequency | Number | példány | A frissítési intervallum (nem gyakoriság) másodpercben. Az alapértéke 2 másodperc. Ez az érték lesz szorozva a decay értékével amikor meghívódik az Ajax.Updater objektum. |
| decay | Number | példány | A feladat újravégrehajtásánál használatos lassítási érték. |
| updater | Ajax.Updater | példány | Ajax.Updater objektum |
| timer | Object | példány | JavaScript időzítő ami arra szolgál, hogy értesítse az objektumot a következő frissítésről. |
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](container, url, options) | konstruktor | container: egy elemazonosító, maga az elem vagy egy objektum két tulajdonsággal - object.success elem (vagy azonosító) ami sikeres AJAX hívás esetén lesz használatos, és object.failure elem (vagy azonosító) ami egyéb esetekben lesz használva. url: a meghívandó url, options: AJAX options | Létrehozza egy példányát az objektumnak ami meghívja az adott url-t a megfelelő opciókkal. |
| start() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Maga az objektum hívja meg az ismétlődő feladatok elindításához. |
| stop() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Maga az objektum hívja meg az ismétlődő feladatok leállításához. |
| updateComplete() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Az aktuális Ajax.Updater hívja meg miután befejeződött a kérés. Az újabb frissítés időzítésére használatos. |
| onTimerEvent() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Belülről hívódik meg a következő frissítéskor. |
Az Element objektum
Ez az objektum pár hasznos függvényt tartalmaz DOM manipulációkhoz.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| addClassName(element, className) | példány | element: elemazonosító vagy maga az elem, className: egy CSS osztály neve |
Az adott elem class elemeihez hozzáadja a paraméterben átadottat. |
| classNames(element) | példány | element: elemazonosító vagy maga az elem | Egy Element.ClassNames objektummal tér vissza, ami az adott elemhez kapcsolódó CSS osztályok neveit reprezentálja. |
| cleanWhitespace(element) | példány | element: elemazonosító vagy maga az elem | Eltávolít minden kihagyást az elemből. |
| empty(element) | példány | element: elemazonosító vagy maga az elem | Boolean értékkel tér vissza azt jelölve, hogy az adott elem üres-e (vagy csak kihagyások vannak benne). |
| getDimensions(element) | példány | element: elemazonosító vagy maga az elem | |
| getHeight(element) | példány | element: elemazonosító vagy maga az elem | Megadja az elem offsetHeight értékét |
| getStyle(element, cssProperty) | példány | element: elemazonosító vagy maga az elem, cssProperty: A CSS tulajdonság neve (a 'prop-name' és a 'propName' formátum is működik). |
Visszaadja az adott elem CSS tulajdonságának az értékét, ha nincs akkor null lesz az eredmény. |
| hasClassName(element, className) | példány | element: elemazonosító vagy maga az elem, className: egy CSS osztály neve |
true értékkel tér vissza ha a class elemeiben szerepel a paraméterben átadott név. |
| hide(elem1 [, elem2 [, elem3 [...]]]) | példány | elemN: elemazonosító vagy maga az elem | Elrejti az összes elemet a style.display beállításával 'none' értékre. |
| makeClipping(element) | példány | element: elemazonosító vagy maga az elem | |
| makePositioned(element) | példány | element: elemazonosító vagy maga az elem | |
| remove(element) | példány | element: elemazonosító vagy maga az elem | Kiveszi az adott elemet a dokumentumból. |
| removeClassName(element, className) | példány | element: elemazonosító vagy maga az elem, className: egy CSS osztály neve |
Az adott elem class elemeiből eltávolítja a paraméterben átadottat. |
| setStyle(element, cssProperty) | példány | element: elemazonosító vagy maga az elem, cssProperty: A CSS tulajdonság neve (a 'prop-name' és a 'propName' formátum is működik). |
Beállítja az eelem az adott CSS tulajdonság értékét. |
| show(elem1 [, elem2 [, elem3 [...]]]) | példány | elemN: elemazonosító vagy maga az elem | Megjeleníti az összes elemet a style.display beállításával '' értékre. |
| scrollTo(element) | példány | element: elemazonosító vagy maga az elem | Az ablakban az adott elem pozíciójához görget. |
| toggle(elem1 [, elem2 [, elem3 [...]]]) | példány | elemN: elemazonosító vagy maga az elem | Átállítja az összes elem láthatóságát. |
| undoClipping(element) | példány | element: elemazonosító vagy maga az elem | |
| undoPositioned(element) | példány | element: elemazonosító vagy maga az elem | |
| update(element, html) | példány | element: elemazonosító vagy maga az elem, html: html tartalom |
Átírja az adott elem belsejét (inner html) a paraméterben megadott html értékre. Ha az adott html tartalmaz <script> blokkokat, akkor azok nem kerülnek beszúrásra viszont kiértékelődnek. |
| visible(element) | példány | element: elemazonosító vagy maga az elem | Boolean a visszatérési értéke és azt jelöli, hogy látható-e az elem. |
Az Abstract objektum
Az objektum más osztályok számára szolgál gyökérként a könyvtárban. Nincs semmiféle tulajdonsága vagy metódusa. Az ezen definiált osztályok absztrakt osztályokként kezelendőek.
Az Abstract.Insertion osztály
Olyan osztályok számára szolgáltat gyökeret ez az osztály amelyek dinamikus tartalomgenerálást szolgáltatnak. Absztrakt osztályként használható.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](element, content) | konstruktor | element: elemazonosító vagy maga az elem, content: a beszurandó HTML tartalom | Egy objektumot hoz létre amely a dinamikus tartalombeszúrást segíti. |
| contentFromAnonymousTable() | példány | (nincs) |
| Tulajdonság | Típus | Fajta | Leírás |
|---|---|---|---|
| adjacency | String | statikus, paraméter | Paraméter ami azt határozza meg, hogy a tartalom az adott elemhez képest hová szúródik be. A lehetséges értékei: 'beforeBegin', 'afterBegin', 'beforeEnd', és 'afterEnd'. |
| element | Object | példány | Az elem amihez képest be kell szúrni a tartalmat. |
| content | String | példány | A beszúrandó HTML tartalom. |
Az Insertion objektum
Az objektum más osztályok számára szolgál gyökérként a könyvtárban. Nincs semmiféle tulajdonsága vagy metódusa. Az ezen definiált osztályok absztrakt osztályokként kezelendőek.
Az Insertion.Before osztály
Az Abstract.Insertion osztályból származik.
A HTML tartalmat az elem elé szúrja be.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](element, content) | konstruktor | element: elemazonosító vagy maga az elem, content: a beszúrandó HTML tartalom | Az Abstract.Insertion osztályból származik. Egy objektumot hoz létre amely a dinamikus tartalombeszúrást segíti. |
A következő példa
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>
<script> new Insertion.Before('person', 'Chief '); </script>
a HTML tartalmat erre változtatja
<br>Hello, Chief <span id="person" style="color:red;">Wiggum. How's it going?</span>
Az Insertion.Top osztály
Az Abstract.Insertion osztályból származik.
A HTML tartalmat az elem után első helyre szúrja be.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](element, content) | konstruktor | element: elemazonosító vagy maga az elem, content: a beszúrandó HTML tartalom | Az Abstract.Insertion osztályból származik. Egy objektumot hoz létre amely a dinamikus tartalombeszúrást segíti. |
A következő példa
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>
<script> new Insertion.Top('person', 'Mr. '); </script>
a HTML tartalmat erre változtatja
<br>Hello, <span id="person" style="color:red;">Mr. Wiggum. How's it going?</span>
Az Insertion.Bottom osztály
Az Abstract.Insertion osztályból származik.
A HTML tartalmat az elem legaljára szúrja be. A taratlom közvetlenül a záró tag előtt fog megjelenni.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](element, content) | konstruktor | element: elemazonosító vagy maga az elem, content: a beszúrandó HTML tartalom | Az Abstract.Insertion osztályból származik. Egy objektumot hoz létre amely a dinamikus tartalombeszúrást segíti. |
A következő példa
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>
<script> new Insertion.Bottom('person', " What's up?"); </script>
a HTML tartalmat erre változtatja
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going? What's up?</span>
Az Insertion.After osztály
Az Abstract.Insertion osztályból származik.
A HTML tartalmat közvetlenül az elem zárótagja után szúrja be.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](element, content) | konstruktor | element: elemazonosító vagy maga az elem, content: a beszúrandó HTML tartalom | Az Abstract.Insertion osztályból származik. Egy objektumot hoz létre amely a dinamikus tartalombeszúrást segíti. |
A következő példa
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span>
<script> new Insertion.After('person', ' Are you there?'); </script>
a HTML tartalmat erre változtatja
<br>Hello, <span id="person" style="color:red;">Wiggum. How's it going?</span> Are you there?
A Field objektum
Az objektum pár hasznos függvényt tartalmaz a beviteli mezőkkel való munkához.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| clear(field1 [, field2 [, field3 [...]]]) | példány | fieldN: a beviteli mező azonosítója vagy maga az mező | Az összes átadott mező értékét kitörli. |
| present(field1 [, field2 [, field3 [...]]]) | példány | fieldN: a beviteli mező azonosítója vagy maga az mező | true lesz a visszatérési értéke ha mindegyik mező tartalmaz valamilyen értéket(nem üres). |
| focus(field) | példány | field: a beviteli mező azonosítója vagy maga az mező | A fókuszt az adott mezőre állítja. |
| select(field) | példány | field: a beviteli mező azonosítója vagy maga az mező | Kijelöli az értéket a mezőben ha az támogatja a szövegkijelölést. |
| activate(field) | példány | field: a beviteli mező azonosítója vagy maga az mező | A fókuszt az adott mezőre állítja és kijelöli az értéket a mezőben ha az támogatja a szövegkijelölést. |
A Form objektum
Az objektum pár hasznos függvényt tartalmaz az űrlapokkal és azok beviteli mezőivel való munkához.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| serialize(form) | példány | form: az űrlap azonosítója vagy maga az űrlap | a mezők neveit és azok értékeit egy url-formázott formában adja vissza, pl. 'field1=value1&field2=value2&field3=value3' |
| findFirstElement(form) | példány | form: az űrlap azonosítója vagy maga az űrlap | Visszaadja az első engedélyezett mezőt az űrlapon. |
| getElements(form) | példány | form: az űrlap azonosítója vagy maga az űrlap | Egy tömbben adja vissza az összes beviteli mezőt az űrlapon belül. |
| getInputs(form [, typeName [, name]]) | példány | form: az űrlap azonosítója vagy maga az űrlap, typeName: a beviteli mező típusa, name: a beviteli mező neve. | Egy tömböt ad vissza, ami tartalmazz az összes <input> elemet az űrlapon. Opcinálisan a lista szűrhető a megadott type vagy name paraméter segítségével. |
| disable(form) | példány | form: az űrlap azonosítója vagy maga az űrlap | Letiltja az összes bevizeli mezőt az űrlapon belül. |
| enable(form) | példány | form: az űrlap azonosítója vagy maga az űrlap | Engedélyezi az összes bevizeli mezőt az űrlapon belül. |
| focusFirstElement(form) | példány | form: az űrlap azonosítója vagy maga az űrlap | Activates the first visible, enabled input field in the form. |
| reset(form) | példány | form: az űrlap azonosítója vagy maga az űrlap | Visszaállítja az eredeti értékeket az űrlapon. Ugyanazt mint a reset() metódos hívása a form objektumon. |
A Form.Element objektum
Az objektum pár hasznos függvényt tartalmaz az űrlap elemekkel való munkához.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| serialize(element) | példány | element: elemazonosító vagy maga az elem | Az elemet egy név=érték páros formájában adja vissza, pl. 'elementName=elementValue' |
| getValue(element) | példány | element: elemazonosító vagy maga az elem | Visszaadja az elem értékét. |
A Form.Element.Serializers objektum
Az objektum pár olyan hasznos függvényt ami a könyvtáron belül van használva, hogy segítse az űrlap elemek aktuális értékének kinyerését.
| Method | Kind | Arguments | Leírás |
|---|---|---|---|
| inputSelector(element) | példány | element: objektum vagy az azonosítója egy olyan űrlap elemnek, melynek van checked tulajdonsága, ilyen például a radio button vagy a checkbox. | Egy tömböt ad vissza az elem nevével és értékével, pl. ['elementName', 'elementValue'] |
| textarea(element) | példány | element: objektum vagy az azonosítója egy olyan űrlap elemnek, melynek van value tulajdonsága, ilyen például a textbox, button vagy a password. | Egy tömböt ad vissza az elem nevével és értékével, pl. ['elementName', 'elementValue'] |
| select(element) | példány | element: objektum vagy az azonosítója egy <select> elemnek | Egy tömböt ad vissza az elem nevével és az összes kiválasztott opció értékével vagy szövegével, pl. ['elementName', 'selOpt1 selOpt4 selOpt9'] |
Az Abstract.TimedObserver osztály
Ez az osztály szolgálhat alapul más olyan osztályok számára aminek az a célja, hogy pl. egy adott elem értékének változását figyelje (vagy bármilyen más tulajdonságét amit a származtatott osztály definiál). Ez az osztály absztarkt osztályként használatos.
Az osztályok figyelhetik mondjuk abevizeli mező értékét, vagy például az egyik stílus tulajdonságot, de igazából bármit aminek a változására kiváncsi vagy.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](element, frequency, callback) | konstruktor | element: elemazonosító vagy maga az elem, frequency: az intervallum másodpercben, callback: a függvény amit az elem változásakor meg kell hívni | Létrehoz egy objektumot ami figyeli az elemet. |
| registerCallback() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Ezt maga az objektum hívja meg a monitorozás elindítására. |
| onTimerEvent() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Ezt maga az objektum hívja meg a folyamatosan az elem ellenörzésére. It is called by the object itself periodically to check |
| Tulajdonság | Típus | Leírás |
|---|---|---|
| element | Object | A figyelendő elem, mint objektum. |
| frequency | Number | Az intervallum értéke másodpercben az ellenörzések között. |
| callback | Function(Object, String) | A függvény amit meg kell hívni az elem változásakor. Paraméterként megkapja az elemet és az új értéket. |
| lastValue | String | Az utoljára ellenörzött értéke az elemnek. |
A Form.Element.Observer osztály
Az Abstract.TimedObserver osztályból származik.
Az Abstract.TimedObserver implementációja egy beviteli mező értékének figyelésére. Akkor használd ezt az osztályt, ha egy olyan elemet szeretnél figyelni ami az értékének változásakor nem generál eseményt. Ellenkező esetben használd a Form.Element.EventObserver osztályt ehelyett.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](element, frequency, callback) | konstruktor | element: elemazonosító vagy maga az elem, frequency: intervallum másodpercben, callback: a függvény amit meg kell hívni az elem változásakor | Az Abstract.TimedObserver osztályból származik. Létrehoz egy objektumot ami az adott elem value tulajdonságát figyeli. |
| getValue() | példány | (nincs) | Visszaadja az elem értékét. |
A Form.Observer osztály
Az Abstract.TimedObserver osztályból származik.
Az Abstract.TimedObserver implementációja és arra szolgál, hogy egy adott űrlap összes mezőjének a változását figyelje. Akkor használd ezt az osztályt, ha egy olyan űrlapot akarsz figyelni ami tartalmaz olyan elemeket, melyek az értékének változásakor nem generálnak eseményt. Ellenkező esetben használd a Form.EventObserver osztályt ehelyett.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](form, frequency, callback) | konstruktor | form: űrlap azonosító vagy maga az űrlap objektum, frequency: intervallum másodpercben, callback: a függvény amit meg kell hívni az űrlap bármelyik elemének változásakor | Az Abstract.TimedObserver osztályból származik. Létrehoz egy objektumot ami az adott űrlap változásait figyeli. |
| getValue() | példány | (nincs) | A form adatait adja vissza szerializát formában. |
Az Abstract.EventObserver osztály
Ez az osztály szolgál alapul más olyan osztályok számára amelyek egy callback függvényt hajtanak végre amikor egy értékváltozás történik egy adott elemen.
Többfajta Abstract.EventObserver objektum csatolható ugyanahhoz az elemhez anélkül, hogy törölnék a a másikat. A hívások abban a sorrendben fognak megtörténni ahogyan az elemhez lettek rendelve.
A kiváltó esemény az onclick egy radio button és checkboxe esetén, az onchange pedig textbox és listbox/dropdown esetén.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](element, callback) | konstruktor | element: elemazonosító vagy maga az elem, callback: függvény amit meg kell hívni az esemény beköveztekor | Létrehoz egy objektumot ami monitorozza az elemet. |
| registerCallback() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Ezt maga az objektum hívja meg, hogy beregisztrálja magát az elem adott eseményére. |
| registerFormCallbacks() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Ezt maga az objektum hívja meg, hogy beregisztrálja magát az űrlap összes beviteli elemének adott eseményére. |
| onElementEvent() | példány | (nincs) | Ezt a metódus tipikusan nem szokás kívülről meghívni. Ez lesz az eseményhez kapcsolva. |
| Tulajdonság | Típus | Leírás |
|---|---|---|
| element | Object | Az elem ami monitorozva lesz. |
| callback | Function(Object, String) | A függvény ami meghívásra kerül az elem változásakor. Paraméterként megkapja az elemet és az új értéket. |
| lastValue | String | Az utoljára ellenörzött értéke az elemnek. |
A Form.Element.EventObserver osztály
Az Abstract.EventObserver osztályból származik.
Az Abstract.EventObserver implenetációja a callback függvényhívások végrehajtásához az adott esemény figyelésével az elemen ahhoz, hogy észlelni lehessen a változást. Ha az elem nem vált ki semmiféle eseményt a változáskor, akkor használd a Form.Element.Observer osztályt ehelyett.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](element, callback) | konstruktor | element: elemazonosító vagy maga az elem, callback: függvény amit meg kell hívni az esemény kiváltódásakor | Az Abstract.EventObserver osztályból származik. Létrehoz egy objektumot, hogy figyelje az elem value tulajdonságát. |
| getValue() | példány | (nincs) | Visszaadja az elem értékét |
A Form.EventObserver osztály
A Abstract.EventObserver osztályból öröklődik
Az Abstract.EventObserver implementációja ahhoz, hogy figyelje az adott űrlapon összes elemén az adott eseményt az értékváltozás észleléséhez. Ha az űrlap tartalmaz olyan elemeket, amelyek nem váltanak ki eseményt az érték változásakor, akkor használd a Form.Observer osztályt ehelyett.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| [ctor](form, callback) | konstruktor | form: űrlap azonosító vagy maga az űrlap objektum, callback: a függvény amit meg kell hívni az űrlap bármelyik elemének változásakor | Az Abstract.EventObserver osztályból származik. Létrehoz egy objektumot a változás figyelésére. |
| getValue() | példány | (nincs) | A form adatait adja vissza szerializát formában. |
A Position objektum (előzetes dokumentáció)
Az objektum olyan függvényeket tartalmaz amelyek segítenek az elemek pozícionálásával kapcsolatban.
| Metódus | Típus | Paraméterek | Leírás |
|---|---|---|---|
| prepare() | példány | (nincs) | Beállítja a deltaX ás deltaY tulajdonságot a görgető(látható/scroll) pozíciójának változásához való igazodáshoz. Ne felejtsd el meghívni mielőtt meghívásra kerül a withinIncludingScrolloffset az oldal görgetése után. |
| realOffset(element) | példány | element: objektum | Egy tömböt ad vissza az elem pontos látható eltolási értékeivel, ebbe beleértendő az összes látható eltolási érték ami kapcsolatban van az elemmel. A visszaadott tömb így fog kinézni: [total_scroll_left, total_scroll_top] |
| cumulativeOffset(element) | példány | element: objektum | Egy tömböt ad vissza az elem teljes eltolási értékeivel, ebbe beleértendő az összes teljes érték ami kapcsolatban van az elemmel. A visszaadott tömb így fog kinézni: [total_offset_left, total_offset_top] |
| within(element, x, y) | példány | element: objektum, x és y: a pont koordinátái | Megvizsgálja, hogy az adott koordináta belül van-e az adott elem téglalapjában |
| withinIncludingScrolloffsets(element, x, y) | példány | element: objektum, x és y: a pont koordinátái | |
| overlap(mode, element) | példány | mode: 'vertical' vagy 'horizontal', element: objektum | Meg kell hívni a within() metódust ezelőtt a metódus előtt. Egy decimális számot fog visszaadni 0.0 és 1.0 között ami a százalékosan azt jelzi, hogy a koordináta hol fedi az elemet. Például, ha az adott elem egy 100px méretű négyzet és a pozíciója 300, 300), akkor a within(divSquare, 330, 330); overlap('vertical', divSquare); eredménye 0.10 lesz, ami azt jelenti, hogy a pont 10%-ra (30px) van az adott DIV felső szélétől. |
| clone(source, target) | példány | source: elemazonosító vagy maga az elem, target: elemazonosító vagy maga az elem | Újraméretezi és pozícionálja a target elemet a source elemmel megegyezően. |
A dokumentáció az 1.4.0-s verzióhoz még folyamatosan készül.
Figyeld folyamatosan a változásokat.
Ha találsz valami hibát, elütést, helyesírási hibát, pontatlan vagy téves
információt, akkor
és megpróbálom javítani a legrövidebb időn belül.