Dziudek's jogger

Przed przejściem do lektury na temat pliku element.js polecam osobom, które o DOM mają małe pojęcie przeczytać trochę materiałów na ten temat. Osobiście polecam ten artykuł o obiektach DOM oraz wpisy Riddle'a na ten temat:

• Document Object Model, wstęp
• Sposoby odnajdywania elementów w DOM
• Węzły w DOM i podstawowe ich dodawanie

Plik element.js to moim zdaniem jeden z bardziej przydatnych elementów frameworka mootools. Udostępnia on nam funkcje pozwalające na manipulowanie drzewem dokumentu. Każdy kto pisał jakiekolwiek skrypty w JS wie, że operacje na DOM pozwalają na osiągnięcie większości pożądanych efektów. Właściwie bez operacji na DOM nie możemy zbyt wiele zrobić przy użyciu JS. Sam plik element.js udostępnia nam około 40 funkcji - niektóre to tylko aliasy standardowych funkcji służących do operacji na drzewie dokumentu, inne to funkcje wykonujące operacje na których wykonanie normalnie potrzebowalibyśmy wielu linijek kodu.

Tworzenie elementów drzewa dokumentu

Aby stworzyć element z użyciem klasy element należy stworzyć nowy obiekt Element, a jako parametry podać wszystkie cechy elementu jaki chcielibyśmy stworzyć. Schematycznie kod wygląda następująco:

new Element('typ_elementu', {
   'styles': {
      'właściwość1': 'wartość',
      'właściwość2': 'wartość'
   },
   'events': {
      'zdarzenie1': function(){
         // kod funkcji
      },
      'zdarzenie2': function(){
          // kod funkcji
      }
   },
   'class': 'nazwa klasy',
   'id': 'id_elementu',
   'href': 'link'
});

Typ elementu to oczywiście tag na przykład 'a', 'b', 'div' itd... Warto jeszcze pamiętać, że nazwy zdarzeń w obiekcie events podajemy bez przedrostka 'on' , oczywiście dodatkowe atrybuty elementu podajemy tak jak class, id i href .Tutaj trzeba dodać, że tak stworzony element nie znajduje się jeszcze w drzewie naszego dokumentu - musimy go dopiero w nim umieścić. Aby więc zaprezentować działanie przedstawionego wcześniej kodu, pozwolę sobie wykorzystać dwie z funkcji, które poznamy dopiero później - injectInside i setProperty. injectInside umieści nasz nowo powstały element w innym żądanym elemencie dokumentu, a setProperty ustawi żądaną wartość danego atrybutu.

PRZYKŁAD 1

Warto w tym miejscu wspomnieć o metodzie set, która działa podobnie jak tworzenie nowego elementu, ale z tą różnicą, że służy tylko do ustalania wartości właściwości elementu. Zatem gdy chcemy do elementu dodać style, zdarzenia to stosujemy takie obiekty jak w wypadku tworzenia nowego elementu i podajemy je jako argumenty metody set przypisane do danego elementu:

element.set(właściwości);

Selekcja elementów

Plik element.js zawiera dwie funkcje do selekcji elementów: $ i $$. Funkcja $ pozwala wybrać element posiadający id podany jako parametr tejże funkcji. Dla przykładu:

var div = $('jakis_div');

Po wykonaniu powyższego kodu zmienna div będzie odpowiadała divowi, który posiada id "jakis_div".

Gdy zajdzie potrzeba operowania na większej liczbie elementów, możemy skorzystać z funkcji $$, która zwróci nam tablicę elementów zgodnych z podanymi parametrami. Jeżeli do naszego frameworka nie dołączyliśmy pliku dom.js możemy wybierać elementy według nazwy tagu - a, b, div itd. Na przykład:

var linki = $$('a');

Zmienna linki będzie tablicą zawierającą wszystkie linki z naszego dokumentu. Gdy nasz framework zawiera także plik dom.js, możemy korzystać z selektorów CSS jako parametrów funkcji $$. Na przykład:

var linki_z_diva = $$('#jakis_div a');

Powyższy kod zwróci wszystkie linki zawarte w divie posiadającym identyfikator "jakis_div".

Więcej funkcji związanych z wybieraniem elementów z drzewa dokumentu znajduje się w pliku dom.js, który opiszę w kolejnych częściach kursu...

Metody klasy Element

W dalszej części kursu pozwolę sobie grupować podobne funkcje tak by skrócić wpis - opisanie każdej z prawie 50 funkcji zajęłoby wiele miejsca gdybym robił to oddzielnie, a tak pogrupuję powiązane typem przykłady i skrócę w ten sposób wpis do akceptowalnej długości ;)

injectBefore, injectAfter, injectInside, injectTop

Funkcje ze słowem inject w nazwie służą do umieszczania elementów w odpowiednim miejscu względem innych elementów. Zatem funkcja injectBefore umieści dany element przed innym, funkcja injectAfter umieści element po innym elemencie, funkcja injectInside umieści dany element wewnątrz innego elementu, a funkcja injectTop umieści dany element na początku innego elementu (w swym działaniu podobna jest do injectInside tylko umieszcza element na początku, a nie na końcu). Budowa tych funkcji jest podobna i wygląda następująco:

$('element_1').inject*****('element_2');

Gdzie element_1 oznacza id elementu, który zostanie przemieszczony względem elementu posiadającego id element_2.

Przykładowe kody dla danych funkcji wraz z otrzymywanym kodem:

Początkowy kod xHTML:

<div id="div1">pierwszy div</div>
<div id="div2">drugi div</div>

Kod JS:

$('div2').injectBefore('div1');

Otrzymywany kod xHTML:

<div id="div2">drugi div</div>
<div id="div1">pierwszy div</div>

W dalszych dwóch przykładach kod xHTML na początku jest taki sam, więc podaję tylko kod JS i otrzymywany kod xHTML:

Kod JS:

$('div1').injectAfter('div2');

Otrzymywany kod xHTML:

<div id="div2">drugi div</div>
<div id="div1">pierwszy div</div>

Kod JS:

$('div1').injectInside('div2');

Otrzymywany kod xHTML:

<div id="div2">drugi div
    <div id="div1">pierwszy div</div>
</div>

Przykład prezentujący działanie powyższych funkcji:

PRZYKŁAD 2

Początkowy kod xHTML:

<div id="div1">pierwszy div</div>
<div id="div2">
   drugi div
   <div id="div3">    </div> </div>

$('div1').injectTop('div2');

Otrzymywany kod xHTML:

<div id="div1">pierwszy div</div>
<div id="div2">
   <div id="div1">pierwszy div</div>
   drugi div
   <div id="div3">    </div> </div>

adopt, remove , clone , replaceWith

Funkcje adopt, remove, clone i replaceWith służą odpowiednio do umieszczania elementu wewnątrz innego, usuwania elementu, powielania elementu i zastępowania elementów.

Funkcja adopt działa na tej samej zasadzie co injectInside. Różni sie jedynie zapis:

$('div1').adopt('div2');

Powyższy kod spowoduje, że div posiadający id div2 znajdzie się wewnątrz diva z id div1 (tak więc w stosunku do zapisu injectInside oprócz zmiany nazwy funkcji mamy też zmianę kolejności elementów - umieszczanego wewnątrz i elementu w którym inny element jest umieszczany).

Użycie funkcji remove jest banalnie proste :

$('id_elementu').remove();

Po wykonaniu powyższego kodu z drzewa dokumentu zniknie element posiadający id id_elementu.

Funkcja clone pozwala nam kopiować dany element. Składnie ma podobną do funkcji remove:

var div_kopia = $('div1').clone();

Kod znajdujący się powyżej spowoduje przypisanie zmiennej div_kopia kopii elementu posiadającego id div1. Oczywiście element ten nie znajduje się jeszcze w drzewie dokumentu - trzeba go tam umieścić na przykład korzystając z funkcji typu inject.

Ostatnia z tej grupy funkcji - replaceWith, jak sama nazwa wskazuje służy do zamiany miejscami elementów. Składnia wygląda następująco :

$('element_1').replaceWith($('element_2'));

Po wykonaniu powyższego kodu element posiadający id element_1 zostanie zamieniony na element posiadający id element_2.

I przykład pokazujący działanie wyżej wymienionych funkcji:

PRZYKŁAD 3

appendText, setHTML

Funkcje appendText i setHTML służą do ustawiania zawartości elementu. appendText służy do dodawania tekstu w elemencie, natomiast setHTML służy do operowania na zawartości elementu - nie tylko tekstowej (działanie takie samo jak innerHTML).

Przyjrzyjmy się działaniu funkcji appendText:

Przyjmijmy, że mamy element typu div posiadający tekst "to jest div " i chcielibyśmy zmienić ten ciąg znaków na "to jest div testowy":

kod xHTML:

<div id="element">to jest div </div>

kod JS:

$('element').appendText('testowy');

Po wykonaniu kod nasz kod xHTML będzie wyglądał następująco:

<div id="element">to jest div testowy</div>

A gdybyśmy chcieli aby treść tego diva wyglądała tak jak wcześniej ale, żeby napis "testowy" był pogrubiony ? Korzystamy w tym wypadku z setHTML:

var kodXHTML = 'to jest div <strong>testowy</strong>';
$('element').appendText(kodXHTML);

I przykłady działania:

PRZYKŁAD 4

hasClass, addClass, removeClass, toggleClass

Funkcje, które zawierają w nazwie człon Class służą do operowania na atrybucie class elementu.

Składnia wszystkich funkcji z tej grupy wygląda następująco:

$('id_elementu').******Class('nazwa_klasy');

Funkcja hasClass służy do sprawdzenia czy dany element posiada daną klasę w atrybucie class. Jeżeli element posiada daną klasę to funkcja zwraca wartość logiczną true, w przeciwnym wypadku false. Przykłady :

kod xHTML:

<div id="div1" class="klasa1">Div 1</div>
<div id="div2" class="klasa2">Div 2</div>

kod JS:

var pierwszy = $('div1').hasClass('klasa1');
var drugi = $('div2').hasClass('klasa1');

Po wykonaniu powyższego kodu zmienna pierwszy przyjmie wartość true, natomiast zmienna drugi przyjmie wartość false (ponieważ div posiadający id div2 ma atrybut class równy klasa2, a nie klasa1).

Aby dodać/usunąć klasę z naszego elementu korzystamy z funkcji addClass (dodawanie klasy) i removeClass (usuwanie klasy). Przykład użycia:

kod xHTML:

<div id="div1" class="klasa1">Div 1</div>
<div id="div2" class="klasa2">Div 2</div>

kod JS:

$('div1').addClass('klasa2');
$('div2').removeClass('klasa2');

Otrzymamy następujący kod xHTML:

<div id="div1" class="klasa1 klasa2">Div 1</div>
<div id="div2" class="">Div 2</div>

Funkcja toggleClass służy do naprzemiennego dodawania i usuwania danej klasy z atrybutu class elementu:

kod xHTML:

<div id="element" class="klasa1">Div</div>

kod JS:

$('element').toggleClass('klasa1');

otrzymamy kod xHTML:

<div id="element" class="">Div</div>

Po ponownym wykonaniu kodu JS:

$('element').toggleClass('klasa1');

otrzymamy kod xHTML taki jak na początku:

<div id="element" class="klasa1">Div</div>

Strona z prezentacją przykładów:

PRZYKŁAD 5

setStyle, setStyles, setOpacity, getStyle

Funkcje z tej grupy służą do operowania na stylu elementów.

Funkcja setStyle służy do ustawiania wartości właściwości CSS. Jej składnia wygląda następująco:

$('id_elementu').setStyle('właściwość', 'wartość');

Zatem, jeśli chcielibyśmy ustawić wysokość diva posiadającego id "testowy" na 250 pikseli wykorzystamy zapis:

$('testowy').setStyle('height','250px');

Ograniczeniem funkcji setStyle jest fakt, że możemy za jej pomocą ustawić wartość tylko jednej właściwości. Gdy chcemy zmienić naraz wartości kilku właściwości, korzystamy z funkcji setStyles, która posiada następującą składnię:

$('id_elementu').setStyles({
    właściwość_1: 'wartość',
    właściwość_2: 'wartość',
    właściwość_3: 'wartość',
          ...
    właściwość_n: 'wartość'
});

Dla przykładu - gdybyśmy chcieli zmienić jednocześnie wysokość, szerokość i padding diva posiadającego id "testowy", stosujemy zapis:

$('testowy').setStyles({
    width: '500px',
    height: '500px',
    padding: '10px'
});

Kiedy chcemy zmienić poziom przezroczystości elementu, stosujemy funkcję setOpacity:

$('id_elementu').setOpacity(poziom_przezroczystości);

Gdzie zmienna poziom_przezroczystości przyjmuje wartości od 0 do 1, natomiast wartości z tego przedziału zapisujemy używając kropki np.: 0.2 .

Przykładowo, gdybyśmy chcieli uzyskać przezroczystość na poziomie 35% dla diva posiadającego id "testowy", zapiszemy:

$('testowy').setOpacity(0.35);

Na koniec z tej grupy funkcji, pozostała nam getStyle, służąca do pobierania aktualnej wartości właściwości CSS danego elementu. Jej składnia wygląda następująco:

$('id_elementu').getStyle('właściwość');

I przykład - pobierzemy wartość właściwości width diva posiadającego id "testowy":

$('testowy').getStyle('width');

Na koniec tej części przykład pokazujący w akcji przedstawione wyżej funkcje:

PRZYKŁAD 6

addEvent, removeEvents, fireEvent

Funkcje posiadające w nazwie człon "Event" służą do operowania na zdarzeniach elementów. Ich użyteczność jest bardzo wysoka, ponieważ dają nam taką samą funkcjonalność jak przedstawiania kiedyś przeze mnie klasa Behaviour .

Zatem gdy chcemy dodać zdarzenie do danego elementu, będziemy korzystali z funkcji addEvent. Jej składnia wygląda następująco:

$('id_elementu').addEvent('zdarzenie', function(){
    kod_funkcji_jaka_się_wykona_przy_wystąpieniu_zdarzenia;
});

Gdzie zmienna zdarzenie to nazwa zdarzenia bez przedrostka "on" np.: onclick zapiszemy jako click, onmouseover zapiszemy jako mouseover itd.

Drugi argument tej funkcji to funkcja, która się wykona w wypadku wystąpienia naszego zdarzenia.

I przykład - przyjmijmy, że chcemy aby po kliknięciu diva posiadającego id "testowy" pokazał się alert z napisem "Div został klikniety":

$('testowy').addEvent('click',function(){ alert('Div został kliknięty') });

Gdy mamy przypisane zdarzenia do danego elementu, możemy je usunąć wszystkie naraz, korzystając z funkcji removeEvents. Możemy też usunąć wybrane zdarzenia. Wszystko zależy od zapisu. Gdy zapiszemy:

$('id_elementu').removeEvents();

Zostaną usunięte wszystkie zdarzenia. Jeśli jednak zapiszemy:

$('id_elementu').removeEvents('zdarzenie_1', 'zdarzenie_2', 'zdarzenie_3');

To zostaną usunięte tylko wybrane zdarzenia danego elementu...

Ciekawą funkcją jest funkcja fireEvent, która powoduje wykonanie wszystkich funkcji przypisanych zdarzeniom danego elementu. Jej składnia wygląda następująco:

$('id_elementu').fireEvent();

Przykładowo gdy mamy element div posiadający id "testowy", który ma określone zdarzenia onclick i onmouseover to przy wywołaniu:

$('testowy').fireEvent();

Zostaną wykonane obie funkcje przypisane zdarzeniom tego elementu (np.: zostaną pokazane dwa alerty).

Na koniec tej części przykład obrazujący działanie wyżej przedstawionych funkcji:

PRZYKŁAD 7

getPrevious, getNext, getFirst, getLast, getParent, getChildren, hasChild

Funkcje, których nazwy są przedstawione w tytule tej części wpisu, służą do selekcji elementów na podstawie relacji pomiędzy nimi w drzewie dokumentu. Ponieważ nie będę się tu rozpisywał na temat samego DOM odsyłam po raz kolejny do linków umieszczonych na początku wpisu.

Tą część możemy potraktować jako teoretyczną i opiszę tylko pokrótce działanie tychże funkcji:

• getPrevious - zwraca element umieszczony bezpośrednio przed danym elementem,
• getNext - zwraca element umieszczony bezpośrednio za danym elementem,
• getFirst - zwraca pierwszy element-dziecko danego elementu,
• getLast - zwraca ostatni element-dziecko danego elementu,
• getParent - zwraca element-rodzica danego elementu,
• getChildren - zwraca wszystkie elementy-dzieci danego elementu,
• hasChild - zwraca true gdy dany element posiada elementy-dzieci.

Wszystkie powyższe funkcje wywołujemy tak samo przez składnię:

$('id_elementu').get**********();

setProperty, setProperties, getProperty, getTag, removeProperty

Funkcje z tej grupy służą do operowania na atrybutach elementów i pobierania takich danych jak wartość pola formularza czy tagu danego elementu.

Funkcja setProperty służy do ustawiania wartości danego atrybutu. Jej składnia jest taka jak funkcji setStyle:

$('id_elementu').setProperty('atrybut','wartosc');

Analogicznie funkcja setProperties ma taką samą składnię jak funkcja setStyles:

$('id_elementu').setStyles({
    atrybut_1: 'wartość',
    atrybut_2: 'wartość',
    atrybut_3: 'wartość',
        ...
    atrybut_n: 'wartość'
});

Funkcje getProperty i getTag służą do pobierania informacji o elemencie - odpowiednio: wartości danego atrybutu, typu elementu (tagu) i wartości pola formularza.

Składnie tych funkcji prezentują się następująco:

$('id_elementu').getProperty('alt');

Powyższy kod zwróci wartość atrybutu alt elementu.

var tag = $('id_elementu').getTag();

Zmienna tag przyjmie wartość "img" jeżeli w kodzie strony mamy zapis:

<img src="ścieżka" id="id_elementu" alt="tekst" />

Działanie powyższych funkcji zostało przedstawione w poniższym przykładzie:

PRZYKŁAD 8

Funkcja removeProperty służy do usuwania właściwości elementu .

Składnia tej funkcji prezentuje się następująco:

$('id_elementu').removeProperty('alt');

Powyższy kod usunie atrybut alt z elementu.

empty

Metoda empty służy do usunięcia wszystkich elementów - dzieci z danego elementu. Po wykonaniu tej operacji metoda ta zwraca element z którego usuwała elementy potomne. Składnia funkcji wygląda następująco:

$('div_id').empty();

Powyższy kod spowoduje, że cała zawartość diva "div_id" zostanie usunięta...

I tym sposobem dotarliśmy do końca omawiania jednego z najbardziej rozbudowanych elementów frameworka mootools - posiadającego dużo funkcji przydatnych przy wielu typowych zastosowaniach JavaScript.