Der Dojo-Effekt 29.05.2007

Vor kurzem habe ich mit dem Ajax-Toolkit Dojo eine Microsite umgesetzt. Aus den Erfahrungen habe ich nun eine kleine Anleitung über den Fade-Effekt Anleitungen verfasst.

Zu Beginn benötigen wir eine HTML Datei mit Grundform, und das Toolkit. Der rund 3,7 MB große Download findet sich auf dojotoolkit.org.
Die Dateien des dojo-Archivs entpacken wir in einen Unterordner mit der Bezeichnung "dojo". Die HTML Datei sollte vor diesem Ordner liegen.

Im Kopf der HTML Datei binden wir zu aller erst zwei JavaScript-Dateien ein:

<script type="text/javascript" src="dojo/dojo.js"></script>
<script type="text/javascript" src="effect.js"></script>

Die "dojo/dojo.js" ist die einzige Datei, die man seitens des dojo-Toolkits einbinden muss. Später werden wir weitere Funktionalitäten über einen speziellen Befehl einbinden. Das Script "effect.js" ist jedoch noch nicht erstellt, dieses soll unsere selbst erstellten Funktionen bereit stellen.

Zuvor fehlt uns aber noch etwas in der HTML Datei. Was möchten wir überhaupt "faden"? Für das Beispiel reichen zwei Inhalte, die über Links in den Bereich "content" geladen werden. Ich habe dazu eine HTML Datei mit erweitertem "body", vorbereitet:

<a href="javascript:changeContent(1)">Inhalt 1</a> - 
<a href="javascript:changeContent(2)">Inhalt 2</a><br />
<div id="content">Aktivieren Sie JavaScript!</div>

Nun ist ein guter Zeitpunkt die Datei "effect.js" neben der HTML Datei zu erstellen und zu öffnen. Die Einbindung von "dojo/dojo.js" reicht jedoch nicht aus, um einen Fade-Effekt umzusetzen. Dojo teilt sein Repertoire auf, so gilt es mitzuteilen, dass wir das Ressort der Effekte benötigen:

dojo.require("dojo.lfx.html");

Dieser Befehl lädt die Effekt-Methoden des Objekts "dojo.lfx.html". Diese könnten wir auch direkt aufrufen. Doch gehen wir Schritt für Schritt vor. Dazu werden wir vier Funktionen erstellen, die aufeinander aufbauen. Die erste:

function changeContent(contentId) {
    dojo.io.bind({
         url: 'content'+contentId+'.txt',
         handler: contentCallback
    });
}

Diese Funktion wird von den Links aufgerufen und nimmt einen numerischen Wert in der Variable "contentId" an. Danach kommt die erste dojo-Methode "dojo.io.bind" zum Einsatz, die beim Einbinden von Datei-Inhalten hilft. Sie nimmt einen Dateiname als "url" entgegen, den wir mit der übergebenen "contentId" zusammen setzen. Dazu kommt der Parameter "handler", dem wir die Bezeichnung "contentCallback" übergeben. Dies ist der Name einer Funktion, die später von "dojo.io.bind" aus aufgerufen wird.

Nun gut, noch einmal durch gehen: Man klickt auf den Link zu Inhalt 2 und es wird der Funktion "changeContent" die Id-Nummer 2 übergeben. Danach wird mittels "dojo.io.bind" versucht, die Datei "content2.txt" zu öffnen. Auch wenn die Dateien noch nicht vorhanden sind, wird im Anaschluss die Funktion "contentCallback" aufgerufen:

function contentCallback(type, data, evt) {
    if (type == 'error') {
        alert('Inhalt liegt nicht vor!');
    } else {
        fadeContent(data);
    }
}

Dojo übergibt dieser Funktion drei Parameter, in unserem Beispiel sind nur zwei davon relevant, "type" und "data". Wenn ein Fehler vorliegt, können wir über "type" ermitteln, ob das Laden der Datei fehlschlug. In diesem Fall enthält "type" den Wert "error".
Den Fehler melden wir über alert(), ansonsten liegen uns die Daten der Datei in der Variable "data" vor. Diese können wir dann der folgenden Funktion übergeben:

function fadeContent(data) {
    dojo.html.toggleDisplay('content');
    dojo.byId('content').innerHTML = data;
    dojo.html.setOpacity(dojo.byId('content'), 0.0);
    dojo.html.toggleDisplay('content');
    sleep(150);
    dojo.lfx.html.fadeIn('content', 150).play();
}

Hier sind wir am Herzstück, diese Funktion nutzt die Methode des Fade-Effekts "dojo.lfx.html.fadeIn".
Zu der Befehlsfolge: Die Anzeige des alten Inhalts wird direkt deaktiviert, danach wird der Neue Inhalt, mit ein wenig Verzögerung, per Fade-Effekt eingeblendet. Das ist ein gewisses Resultat und muss nicht das Optimum sein.
Um den alten Inhalt auszublenden und die Inhalte im Bereich "content" auszutauschen werden einige dojo-Methoden gebraucht. "dojo.html.toggleDisplay" nimmt die Id eines Elements entgegen und wechselt dessen Anzeige. Hier ist es das div-Element, welches nach dem ersten Aufruf der Methode nicht mehr angezeigt wird. Danach wird das Element direkt angesprochen (als Objekt), dabei hilft "dojo.byId". Der Wert "innerHTML" stellt den Inhalt des Elements dar, wir ersetzen diesen also einfach mit den Daten aus unserer Datei. Neben der Anzeige kann man auch die Deckkraft eines Elements beeinflussen. Über "dojo.html.setOpacity" können wir dem Objekt des div-Elements den Wert 0.0 zuweisen, und machen es so unsichtbar. Das erneute Umschalten der Ansicht beeinflusst diesen Zustand nicht.
Nun setzen wir eine kleine Warteschleife ein, um den Effekt zu verzögern (sleep() siehe unten) und lassen danach den Bereich "content" über die Methode "dojo.lfx.html.fadeIn(...).play" einblenden. Die beiden numerischen Werte entsprechen 150 Millisekunden.

Bevor ich es vergesse, dem Script sollte man noch folgende Zeile hinzufügen:

dojo.addOnLoad(changeContent(1));

Dadurch veranlasst dojo, dass der erste Inhalt anfangs mit geladen wird. Dies entspricht dem reinen JavaScript Aufruf onload="" als Parameter des "body"-Elements.

Wie angesprochen, hier noch die Funktion sleep(), die einen numerischen Wert als Millisekunden annimmt und daraus einen zukünftigen Zeitpunkt berechnet. Sobald dieser erreicht ist (Verzögerung mittels Schleife), wird die Funktion verlassen:

function sleep(numberMillis) {
    var now = new Date();
    var exitTime = now.getTime() + numberMillis;
    while (true) {
        now = new Date();
        if (now.getTime() > exitTime) return;
    }
}

Hier, findet sich die komplette "effect.js" zum Download.