www.pixy.cz


DHTML Library

Popis

DHTML Lib je knihovna javascriptových funkcí pro snadnější manipulaci s HTML dokumentem. Byla navržena pouze pro prohlížeče podporující DOM, ale tím je myšlen i "DOM 0" (viz dále). Rozhodl jsem se nadále nepodporovat NN4 a jeho "layer", který je již mrtev - Netscape zastavil jeho podporu a není důvod si s ním již přidělávat problémy.

Knihovna obsahuje jednoduchý debugger - několik funkcí, které vám umožní v samostatném okně vypisovat proměnné a volání funkcí (viz Debugger dále).

Součástí knihovny jsou další doplňky v samostatných souborech - knihovny animator.js a scroller.js (viz níže).


Historie verzí

verze 1.2 (28. 9. 2001)
Aktuální verze. Změněn a doplněn ScrollerObj (v souboru "scroller.js") - přidáno horizontální posouvání a scrollování po stránkách. Obdobně změněn i AutoScrollerObj(). Viz popis "scroller.js" níže.
verze 1.1
Přidány funkce pro clipping (getObjClip() a setObjClip()). AnimatorObj() byl přesunut do samostatného souboru "animator.js". Nové objekty ScrollerObj() a AutoScrollerObj() - opět již v samostatném souboru "scroller.js".
verze 1.0
Drobné změny, podstatně předělán debugger (automatický výpis volání funkcí do plné hloubky). Úprava v AnimatorObj.Init(), aby mohly být zadány i hodnoty null. Udělal jsem konečně český popis (kdo minevěří, že je snazší programovat a popisovat funkce programu v angličtině?); smazán dlouhý komentář z kódu, popis převeden na web.
verze 0.9.1
Vylepšeno předávání parametrů; přidána funkce testBadWidths(); přidán AnimatorObj.
verze 0.9
První verze. Obsahuje funkce na nalezení objektu podle jména, zjištění a nastavení rozměrů a pozice boxů, zjištění a nastavení vlastností stylů, viditelnosti, z-indexu, velikostí okna atd. Navíc je zde objekt popisující verzi prohlížeče a integrovaný jednoduchý debugger pro trasování běhu funkcí.

Použití

  1. Vložte odkaz na tuto knihovnu jako první Javascript do své stránky:
    <SCRIPT SRC="dhtml_lib.js" TYPE="text/javascript"></SCRIPT>
  2. Použijte jakoukoli proměnnou či funkci z této knihovny ve svých skriptech a stránkách s absolutně pozicovanými prvky.

Tato knihovna bude fungovat pouze v prohlížeči s DOM 1 a výše, nebo alespoň tzv. "DOM 0", což znamená browsery podporující "document.getElementById()" nebo alespoň "document.all". Může být tedy použita v prohlížečích MSIE4+, Opera 5 (verzi pro Mac nedoporučuji; alespoň do doby, než bude hotová finální verze), NN6+/Mozilla, Konqueror atd. Zapomeňte na NN4 a starší.

Nejjednodušším způsobem, jak si prohlížeč ověřit, je použít ve skriptu proměnnou "jsDOM" z této knihovny. Ta má hodnotu "true", pokud prohlížeč podporuje alespoň DOM0 či více. Bohužel některé prohlížeče (beta verze Opery, MSIE4/Mac atd.) se sice tváří, že DOM podporují, ale mají s ním či s CSS mnoho problémů. Chcete-li zjistit o prohlížeči více, použijte objekt "BrIS" (viz níže).


Rozhraní DHTML Lib - dhtml_lib.js

Podrobnosti k jednotlivým proměnným a funkcím najdete také v historii.

Veřejné proměnné:

jsDOM0
má hodnotu true, pokud browser podporuje "document.all"
jsDOM1
má hodnotu true, pokud browser podporuje "DOM level 1" a vyšší
jsDOM
má hodnotu true, pokud browser podporuje alespoň jedno z výše uvedených
BrIs
objekt; informace o prohlížeči, viz níže

Veřejné funkce:

U všech funkcí, jejichž parametrem je "name", může být tímto parametrem jak jméno objektu, tak objekt sám. Pokud již jednou máme referenci objektu, je rychlejší používat tento objekt - pokud se použije jméno, musí se objekt pokaždé vyhledat.

getObj(name)
Je-li parametr "name" řetězec, vrací objekt odpovídající prvku daného jména (ID). Je-li parametrem "name" přímo objekt, funkce jej pouze vrátí zpět. Jinak vrací null.

Příklad: var obj = getObj("menu");

getObjX(name)
vrací X-souřadnici daného prvku (pozice Left)
getObjY(name)
vrací Y-souřadnici daného prvku (pozice Top)
getObjW(name)
vrací skutečnou šířku daného prvku (Width). Viz také dále "testBadWidths"
getObjH(name)
vrací skutečnou výšku daného prvku (Height). Viz také dále "testBadWidths"

Příklad:
x = getObjX("menu"); y = getObjY("menu");
při opakování se stejným prvkem je rychlejší:
var o = getObj("menu");
x=getObjX(o); y=getObjY(o); w=getObjW(o); h=getObjH(o);

getWinW()
vrací šířku aktuálního okna dokumentu
getWinH()
vrací výšku aktuálního okna dokumentu

Příklad: plochaOkna = getWinW() * getWinH();

moveObjTo(name,x,y)
přesune prvek "name" na pozici x, y (left, top); x i y může být "null" - potom se ignoruje;
vrací objekt odpovídající danému prvku
moveObjBy(name,dx,dy)
přesune prvek "name" relativně o dx, dy (left, top); x i y mohou být záporné
vrací objekt odpovídající danému prvku
resizeObjTo(name,w,h)
nastaví šířku a výšku prvku na hodnoty w a h; w i h může být "null" - potom se ignoruje
vrací objekt odpovídající danému prvku
resizeObjBy(name,wk,wh)
zvětší / zmenší prvek - jeho rozměry se vynásobí koeficienty wk a wh (wk,hk > 0)
vrací objekt odpovídající danému prvku

Příklad 1:
moveObjTo("menu",100,150); // posune "menu" na pozici 100,150
resizeObj("menu",360,40); // nastaví rozměry "menu" na 360x40
Příklad 2:
var obj = getObj("menu");
moveObjBy(obj,-10,15); // posune "menu" o 10px doleva a o 15px dolů
resizeObjBy(obj,2,1); // zvětší šířku prvku "menu" na dvojnásobek

getObjCSSProp(name,prop)
vrací CSS vlastnost "prop" prvku "name".
Pozor: v souladu se specifikací Javascriptu se vlastnosti neberou z tabulky stylů (stylesheet), ale pracuje se pouze se styly uvedenými přímo ve značce (tagu) daného prvku.
setObjCSSProp(name,prop,val)
nastaví CSS vlastnost "prop" prvku "name" na hodnotu "val" (uloží se do atributu "style" v tagu)
vrací objekt odpovídající danému prvku

Příklad:
getObjCSSProp("menu","color"); // vrátí hodnotu vlastnosti "color"
Příklad 2:
obj=setObjCSSProp("menu","fontSize","12px"); // nastaví font-size na 12px a vrátí objekt
setObjCSSProp(obj,"fontWeight","bold"); // nastaví font-weight na bold; už předáváme objekt, takže se nemusí podruhé hledat

getObjContent(name)
vrací HTML obsah daného prvku
setObjContent(name,html)
nastaví HTML obsah prvku na hodnotu "html"
vrací objekt odpovídající danému prvku

Příklad:
setObjContent("menu", getObjContent("menu")+" dodatek");

getObjVisible(name) = true|false
vrací false, pokud má prvek hodnotu visibility="hidden", jinak vrací true;
setObjVisible(name,show)
show je true | false; nastaví vlastnost visibility prvku (visible/hidden) podle hodnoty show
vrací objekt odpovídající danému prvku
getObjDisplayed(name) = true|false
vrací false, pokud má prvek hodnotu display="none", jinak vrací true;
setObjDisplayed(name,show)
show je true | false; nastaví vlastnost display prvku (block/none) podle hodnoty show
vrací objekt odpovídající danému prvku

Příklad:
setObjVisible("menu",false); // skryje "menu"
setObjDisplayed("menu", !getObjDisplayed("menu"));

 
getObjClip(name)
pokud má prvek definovanou vlastnost "clip", vrací její hodnoty jako pole ctyr prvku (0-3) v pořadí top, right, bootm a left. Pokud clip definován není, vrací false.
setObjClip(name,top,right,bottom,left)
nastaví vlastnost clip na hodnotu "rect(top,right,bottom,left)"
vrací objekt odpovídající danému prvku

Příklad:
var cl = getObjClip("menu");

topClip=cl[0]+10; bottomClip=cl[2]+10;
setObjClip("menu",topClip,cl[1],bottomClip,cl[3]);

getObjDepth(name)
vrací z-index prvku
setObjDepth(name,z)
nastaví z-index prvku na hodnotu z
vrací objekt odpovídající danému prvku

Příklad: setObjDepth("menu",2);

setObjBkgr(name,color,src)
nastaví pozadí prvku "name" na barvu "color" nebo obrázek "src"; color i src může být "null", potom se tato vlastnost ignoruje
setObjFont(name,family,size,color,weight,style)
nastaví vlastnosti písma - font-family, font-size, color, font-weight, resp. font-style; každý z param,etrů může být "null", pak se ignoruje
setObjBorder(name,style,width,color)
nastaví vlastnosti border (rámeček); style, width i color může být "null"
všechny tři funkce vrací objekt odpovídající danému prvku

Příklad:
setObjBkgr("menu","red",null);
setObjBkgr("menu",null,"/img/pozadimenu.gif");
setObjFont("menu","'Helvetica CE',serif","12px",null,"bold",null);
setObjBorder("menu","solid","1px","black");
- totéž jako setObjCSSProp("menu","background","1px solid black");

Chcete-li nastavit jiné vlastnosti CSS, použijte funkci setObjCSSProp()

addStylesheet(url)
vloží stylesheet s daným URL do dokumentu; tato funkce používá document.write, takže je nutno ji volat v jen sekci <HEAD> dokumentu.
activateStylesheet(n,active)
active = true | false; aktivuje stylesheet číslo n (pokud prohlížeč podporuje document.styleSheet)

Příklad:
addStylesheet("css/moje.css");
activateStylesheet(0,false); activateStylesheet(1,true);


objekt BrIs - informace o prohlížeči

Tento objekt obsahuje mnoho informací o použitém prohlížeči (BrIs = "Browser Is"). Obsahuje tyto vlastnosti:

v
informace o verzi (plný text)
vmaj
hlavní verze (jedno číslo, např. 4)
vmin
desetinná verze (např. 4.75)
br
"NN" v případě Netscape, "IE" v případe MSIE, jinak hodnota navigator.appName;
ua
hodnota navigator.userAgent převedená navíc do lower-case (jen malá písmena)
Ostatní vlastnosti jsou booleovské (true|false):
NN - jakýkoli Netscape
NN4 - Netscape 4.x
NNmin4 - Netscape 4.x a vyšší
NN6 - Netscape 6 a vyšší
IE - jakýkoli MSIE
IE4 - MSIE 4.x
Mac - prohlížeč běží na MacOS
IE4Mac - MSIE 4.x pro Mac (je tu extra uveden, neboť je to příšerný browser)
IEmin4 - MSIE 4+
IE5 - MSIE 5.x
IE55 - MSIE 5.5x
IE6 - MSIE 6.x
IEmin5 - MSIE 5.x a vyšší
OP - Opera
IEnotOP - MSIE, ale ne Opera
GEC - Gecko engine (Mozilla a podobné)

Použití objektu BrIs je jednoduché - stačí ve skriptu otestovat libovolnou z jeho vlastností:

Příklad:
if (BrIs.GEC || (BrIs.IEmin5 && BrIs.IEnotOP)) atd...

Testování chybných šířek:

Pomocí funkce testBadWidths() lze otestovat, zda prohlížeč počítá šířky objektů korektně (rozměrem prvku je rozměr jeho obsahu), nebo chybně - to je nejčastější chyba v implementaci CSS (např. všechny MSIE až do verze 6) -, kdy prohlížeč do rozměru počítá i velikost padding a border.

testBadWidths()
tato funkce vrací true, pokud prohlížeč počítá rozměry chybně, a false, pokud je počítá korektně.
Pozor: tato funkce za svého běhu vytvoří neviditelný (display:none) prvek DIV ve stránce. Počítejte s tím.

Příklad:
var jsouSpatneSirky = testBadWidths();
if (jsouSpatneSirky) {
   width = width-pad-bordr;
   ...


Debugger

Jednoduchý debugger sloužící k vypisování hodnot proměnných a volání funkcí.

jsDebug
globální proměnná ovládající debugování; hodnoty:
0: debugování vypnuto; výchozí hodnota
-1: debugování zapnuto; v samostatném okně vypisuje všechna volání doDebug();
n>0: debugování zapnuto pro n výpisů doDebug(); n se po každém výpisu dekrementuje
doDebug(result)
do zvláštního okna vypíše všechny volané funkce s jejich parametry až do místa, odkud byl doDebug() zavolán; do parametru result můžete dát libovolnou proměnnou (nebo řetězec) a její hodnota se rovněž vypíše v okně debuggeru.
Dump(result)
do okna vypíše jen hodnotu "result" - funkce se netrasují. Dump() můžete použít kdykoli a kdekoli, funguje bez ohledu na stav proměnné jsDebug.

Příklad:
function Test(n) {
var x = "0";
for (var i=0;i<n;i++) {
   x += "-" + i;

   doDebug(i+", "+x);

   }
}
...
jsDebug = -1;
window.onload = Test(3);

vypíše v okně debuggeru:
function onload() =>
function Test(3) =>
result: 1, 0-1
-----
function onload() =>
function Test(3) =>
result: 2, 0-1-2
-----
function onload() =>
function Test(3) =>
result: 3, 0-1-2-3
-----

Pokud změníme jsDebug na jsDebug=1, vypíše se jen první volání.
Pokud místo doDebug() zavoláme jen Dump() se stejnými parametry, vypíše se (při každém volání, neboť u Dump na nastavení jsDebug nezáleží):

Dump: 1, 0-1
-----
Dump: 2, 0-1-2
-----
Dump: 3, 0-1-2-3
-----

Pozn.: Funkce v této knihovně již obsahují volání doDebug(), můžete je pochopitelně přesunout na jiné místo, vložit jiný parametr, jehož hodnotu chcete vypisovat, nebo je úplně smazat. Pokud skončíte s laděním, debugovací příkazy zcela smažte, ať zbytečně nezpomalují váš kód.


animator.js

objekt AnimatorObj

Objekt sloužící k jednoduchým animacím prvků.

konstruktor AnimatorObj (instance_name,obj_name);
prvním parametrem je jméno instance (je potřeba pro opakované volání animace);
druhým parametrem je prvek, který chceme animovat
metoda Init(x,y,w,h,steps,speed,loop)
x,y je nová pozice; w,h je nová velikost; je-li některá položka null, hodnota se nebude animovat;
steps - počet kroků animace
speed - pauza mezi kroky - parametr pro setTimeout() - v milisekundách
loop - kolikrát se má animace zopakovat; -1 znamená věčné opakování (stále dokola)
metoda Go(true|false)
spustí (true) nebo zastaví (false) animaci
metoda Restore(steps,speed)
přesune prvek na původní pozici (pozice před první animací).

Příklad:
MyAnim = new AnimatorObj("MyAnim","menu"); //nový animátor
MyAnim.Init(100,150,320,null, 10,20,1); // přesun na pozici 100,150, změna šířky na 320px, výška se měnit nebude; 10 kroků, pauza 20ms, neopakovat (1 opakování)
MyAnim.Go(1); // start animace


scroller.js

objekty ScrollerObj a AutoScrollerObj

Objekty sloužící k posouvání (scrollování) obsahu. Rozhodl jsem se, že se vyhnu běžnému postupu, tedy udělat scroller pomocí vytváření nových objektů ve stránce. Prvky, které mají být scrollovány se normálně vytvoří ve stránce, takže jsou dostupné i pro starší prohlížeče bez JS nebo DOM. Teprve následně se předají níže uvedeným objektům, které je umožní posouvat ve vhodných prohlížečích - autor tak má navíc stále možnost scrollování přepínat - scroller zrušit a prvku např. nastavit overflow:scroll...

Pro vytvoření scrolleru je nutné mít dva vnořené (absolutně pozicované) prvky - vnější (outerObj) a vnitřní (innerObj), který se posouvá uvnitř vnějšího. Oba by měly mít padding i border = 0, aby se počítaly rozměry správně ve všech prohlížečích.

Upozornění: scroller.js používá dhtml_lib.js, která musí být do stránky načtena dříve.

konstruktor ScrollerObj(outerObj, innerObj, padding, allowFullscroll);
Prvním parametrem je jméno (nebo přímo objekt sám) vnějšího prvku; druhým parametrem obdobně vnitřní prvek (musí být potomkem vnějšího prvku); padding je odstup vnitřního prvku od vnějšího (náhrada klasického paddingu, který se při absolutním pozicování nepoužije). allowFullscroll je booleovská hodnota (true|false), určující, zda se má obsah scrollovat zcela (hodnota true; vnitřek se posouvá tak dlouho, až není ve vnějším prvku vidět), či zda se má rolovat jen v rámci dané plochy (hodnota false). Viz ukázku - true odpovídá běžnému scrollování textu v okně, false pak odpovídá chování autoscrolleru, kdy obsah "vyjede" z jedné strany a na druhé se zase "zanoří".
metoda Init()
normálně není třeba ji používat (volá se automaticky z konstruktoru). Použijete ji ale případě, že se za běhu změní velikost vnějšího prvku - např. pokud má prvek zadané relativní rozměry (v procentech či em) a nastane window.resize(). V tom případě zavolejte při resize tuto metodu -např. window.onresize = MyScroller.Init().
metoda Scroll(n)
svisle posune vnitřek o n bodů nahoru (n>0) nebo dolů (n<0) a vrátí true
pokud se již posunout nejde (je již na konci), vrátí false
metody ScrollPgUp() a ScrollPgDn()
svisle posune vnitřek o jednu stránku (o výšku rámečku) nahoru, resp. dolů
pokud se již posunout nejde (je již na konci), vrátí false
metody ScrollFullUp(), ScrollFullDn() a ScrollMid()
svisle posune vnitřek zcela nahoru, zcela dolů, resp. na střed
metoda Shift(n)
vodorovně posune vnitřek o n bodů vlevo (n>0) nebo vpravo (n<0) a vrátí true
pokud se již posunout nejde (je již na konci), vrátí false
metody ShiftFullLeft(), ShiftFullRight() a ShiftMid()
vodorovně posune vnitřek zcela vlevo, zcela vpravo, resp. na střed

Příklad:
var MyScroll = new ScrollerObj("vnejsiDIV","vnitrniDIV", 5, false);
MyScroll.Scroll(5);

MyScroll.ScrollFullDn();

viz rovněž ukázku použití scrollerů

Objekt AutoScrollerObj je nadstavbou Scrolleru, slouží k automatickému posouvání textu (panner) a především k vytváření animovaných bannerů - tím nemyslím žádnou reklamu, ale oblasti, v nichž cyklicky rotuje několik textů (krátké zprávy, oznámení, odkazy) - viz ukázku.

konstruktor AutoScrollerObj(selfname, outerObj, padding);
Prvním parametrem je jméno instance (je potřeba pro automatické volání v setTimeout())
outerObj je vnější prvek stejně jako u scrollerObj, stejný význam má padding. Vnitřní objekt se zde nepředává, k tomu slouží další metoda a je možné jich předat více.
metoda AddInner(innerObj,horiz,step1,step2,speed1,speed2,pause);
Přidá vnitřní objekt innerObj; jejich počet není nijak omezen - všechny tyto vnitřní objekty se budou postupně scrollovat jeden po druhém (tyto prvky musí být potomky vnějšího outerObj prvku). Ostatní parametry jsou pro nastavení způsobu scrollování.
"horiz" udává směr scrollování (horiz=true je vodorovně, horiz=false je svisle). "step1" a "step2" udávají hodnotu pro Scroll() - tedy o kolik bodů se má obsah posunout v jednom kroku (step>0 = posun zdola nahoru / zprava doleva, step<0 = posun shora dolů / zleva doprava). Větší hodnota zvýší rychlost animace, 1/-1 je pak nejpomalejší a nejplynulejší posuv. "step1" je hodnota pro první polovinu animace (od začátku do poloviny), "step2" pak pro druhou část (od poloviny do konce). "speed1" a "speed2" také ovlivňují rychlost animace - je to pauza mezi jednotlivými posuny (v milisekundách) - opět "speed1" pro první část, "speed2 pro druhou" (nájezd/odjezd). Čím menší číslo, tím je animace rychlejší. "pause" je pak doba, po níž se má animace zastavit, když je daný objekt přesně v polovině animace (tedy ve středu rámečku) - např. 0 = žádná mezera, animace pojede bez zastavenení; 3000 = animace s zastaví na 3s.
metoda Go(on);
on=true spustí animaci, on=false scrollování zastaví
metoda ReinitAll();
zavolá Init() pro všechny vnitřní objekty (viz ScrollerObj.Init výše) - použijte v případě, že za běhu změníte rozměr vnějšího prvku (třeba při onresize).

Příklad:
var MyBanner = new ScrollerObj("MyBanner","vnejsiDIV",5);

MyBanner.AddInner("zpravaDIV1",false,1,1,10,10,5000);
MyBanner.AddInner("zpravaDIV2",true,10,-10,1,1,5000);
MyBanner.AddInner("zpravaDIV3",true,-1,-1,100,100,0);
MyBanner.Go(1);

MyBanner.onclick = MyBanner.Go(0);

viz rovněž ukázku použití scrollerů


Licence

Kód DHTML Lib a všechny jeho části jsou zdarma a k volnému použití k nekomerční účelům. Komerční použití této knihovny ani jejích částí není povoleno (bez souhlasu autora). Autor za nic neručí a neposkytuje žádnou podporu týkající se tohoto produktu.


Download

Knihovnu si můžete stáhnout z níže uvedené adresy (má jen pár kB), stejně jako ostatní doplňky. Chcete-li si soubor stáhnout na disk, klepněte na odkaz se stisknutou Ctrl (na Macu s Alt) klávesou.

Výpis adresáře: dhtmllib/