In dieser Anleitung wird beschrieben wie Du den jQuery-basierten DMRL Client in Deine eigene Homepage integrieren kannst.
Du solltest wissen, dass dieser DMRL Client in JavaScript realisiert ist und somit nur lauffähig ist, wenn die Anwender die Deine Homepage aufrufen die Ausführung von JavaScript aktiviert haben. Bei allen anderen Usern wird der DMRL Client nicht laufen.
Dieses Problem wird allerdings in dieser Anleitung dahingehend berücksichtigt, dass bei ausgeschaltetem JavaScript im Browser einfach der entsprechende Bereich unsichtbar geschaltet wird. Deine Homepage wird in diesem Fall für den Anwender genauso dargestellt wie bisher, ohne dass eine Rangliste angezeigt wird.
Weiterhin sei darauf hingewiesen, dass der bereitgestellte DMRL Client auf jQuery basiert. Es ist nicht auszuschließen, dass es zu Konflikten kommt, falls Du bereits ein anderes JavaScript-Framework zur DOM-Manipulation verwendest. In diesem Fall wäre ich Dir sehr dankbar, wenn Du mich über die Probleme informieren würdest.
Die Software DMRL stellt mehrere Dienste zur Verfügung. In dieser Anleitung wird davon ausgegangen, dass Du eine Homepage für einen Minigolf-Club betreibst und auf dieser Homepage nun den Ausschnitt der Deutschen Minigolf Rangliste anzeigen willst der nur die Spieler Deines Vereins enthält. Genau für diesen Zweck stellt DMRL einen Service „playersByTeam“ zur Verfügung, dem man als Aufrufparameter einfach den Namen des gewünschten Vereins übergibt.
Es wird davon ausgegangen, dass Du bereits eine eigene Homepage betreibst. Um in dieser Anleitung jedoch etwas konkreter werden zu können bezieht sich die Anleitung auf die frei erfundene Homepage des fiktiven „1. Minigolf Clubs Vaucluse“, auch „1. MGCV“ genannt.
Da dies noch ein sehr junger Club mit äußerst wenigen Mitgliedern ist, ist die Homepage noch im Aufbau befindlich. Bisher gibt es nur die Datei index.html, die folgenden Inhalt hat:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="de" lang="de"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>1. MGCV</title> </head> <body> <h1>Herzlich Willkommen auf der Homepage des 1. MGCV</h1> <h2>Neuigkeiten</h2> <p>Bisher haben wir noch keine eigene Minigolfanlage auf der wir spielen können.</p> <p>Wir freuen uns jederzeit über neue Mitglieder.</p> <h2>Externe Links</h2> <ul> <li><a href="http://www.minigolf-france.fr/">Website des Verbandes</a></li> <li><a href="http://www.camping-carpe-diem.com/">schöne Übernachtungsmöglichkeit im Herzen des Vaucluse</a></li> <li><a href="http://de.wikipedia.org/wiki/Vaucluse">Das Vaucluse auf Wikipedia</a></li> </ul> </body> </html>
Sofern Du noch keine Homepage hast solltest Du einfach mit dieser Beispieldatei beginnen. Lege einfach mit einem beliebigen Texteditor eine Datei mit dem Namen index.html an und kopiere den oben dargestellten Inhalt in die Datei. Nachdem Du die Datei gespeichert hast, öffnest Du diese einfach mit einem Doppelklick im Browser. Du solltest im Browser jetzt die rudimentäre Homepage angezeigt bekommen.
Hier findet Du den Quellcode zum Kapitel "Vorbereitung" .
Zunächst einmal musst Du die benötigten jQuery-Bibliotheken in Deine Homepage einbinden. Um eine rudimentäre Funktionsprüfung zu haben wird sinnvollerweise nach dem Laden der Seite eine Meldung auf den Bildschirm ausgegeben. Sobald dies funktioniert kann dann die Meldung wieder ausgebaut werden.
Dazu fügst Du einfach im <head>-Bereich Deiner Homepage folgenden Inhalt ein:
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>1. MGCV</title>
<script type="text/javascript"
src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
<script type="text/javascript"
src="http://www.meikel.at/dmrl/0.1/jquery.dump.js"></script>
<script type="text/javascript">
$(document).ready(function() {
alert('Here I am.');
});</script>
</head>
Nehme die hier gezeigten Änderungen an der Datei index.html vor und führe im Browser ein Refresh durch. Nachdem die Seite neu im Browser geladen wurde sollte jetzt ein Meldungsfenster mit dem Inhalt "Here I am." erscheinen.
Durch diese Änderungen hast Du folgendes erreicht: die ersten beiden <script>-Anweisungen führen dazu, dass sowohl die jQuery-Core Bibliothek als auch eine Hilfsbibliothek geladen werden. Diese Änderung alleine hätte noch keinerlei sichtbare Auswirkung. Um eine rudimentäre Funktionsprüfung zu haben, d.h. um zu sehen ob die jQuery-Core-Bibliothek wirklich vom Browser geladen wird, wird deshalb mit dem letzten <script>-Befehl ein JavaScript hinterlegt, das direkt nach dem Laden des Dokumentes die Meldung "Here I am." ausgibt. Wenn diese Meldung erscheint, dann hast Du die Gewissheit, dass Deine Änderungen bis hierher schonmal funktionieren.
Hier findet Du den Quellcode zum Kapitel "jQuery einbinden" .
Nun baust Du in den <body>-Bereich der Datei einen Rahmen ein in dem die Rangliste dann dargestellt werden soll. Dies sieht folgendermaßen aus:
<div style="display: none" id="ranglisteContainer"> <h2>Rangliste</h2> <div id="ranglisteBody">Die Rangliste wird geladen ...</div> <div id="ranglisteDebug">Debugbereich</div> </div>
Zusätzlich musst Du im <head>-Bereich eine weitere JavaScript Bibliothek laden, nämlich den DMRL Client selbst. Außerdem kannst Du die JavaScript Funktion die sich ebenfalls im <head>-Bereich befindet so umschreiben, dass kein alert() mehr ausgeführt wird sondern statt dessen der DMRL Client aufgerufen wird. Dazu nimmst Du folgende Änderungen vor:
<script type="text/javascript"
src="http://www.meikel.at/dmrl/0.1/dmrl-client.js"></script>
<script type="text/javascript">
$(document).ready(function() {
jQuery('#ranglisteContainer').css("display", "block");
DMRL_CLIENT.api('#ranglisteDebug').playersByTeam('SG%20Weiterstadt%201886', '#ranglisteBody');
});</script>
Was hast Du durch diese Änderungen erreicht? Zunächst einmal hast Du einen weiteren Inhalt zu Deiner Homepage hinzugefügt. Um diesen Bereich möglichst einfach sichtbar und unsichtbar schalten zu können, wird der gesamte Bereich einfach in ein <div>-Element gepackt und dieses bekommt eine Id zugewiesen, in diesem Fall de Id "ranglisteContainer". Dieses <div>-Element wird per CSS unsichtbar geschaltet. Der JavaScript Code wird später dafür sorgen, dass der Bereich sichtbar geschaltet wird. Ein Browser der kein JavaScript aktiviert hat, wird den gesamten Bereich also niemals anzeigen.
Der neue (vorerst noch unsichtbare) Inhalt besteht aus einer Überschrift (<h2>) sowie zwei <div>-Elementen, die über ihre beiden Ids "ranglisteBody" und "ranglisteDebug" angesprochen werden können. Das erste der beiden Elemente soll später die Rangliste anzeigen, im zweiten können von der API Debugmeldungen ausgegeben werden.
Durch die Änderungen am JavaScript Code ereichst Du erstens, dass der neu Inhalt sichtbar geschaltet wird und zweitens, dass ein API Aufruf zum Laden und anzeigen der gewünschten Daten erfolgt. Als Aufrufparameter wird im Beispiel der Wert "SG%20Weiterstadt%201886" verwendet, wobei zu beachten ist, dass Leerzeichen mittels %20 maskiert wurden. Der übergebene Wert entspricht somit der Zeichenkette "SG Weiterstadt 1886". Mit diesem Aufruf werden also alle Spieler angezeigt, die für die SG Weiterstadt 1886 spielen. Folgende Werte sind hier als Aufrufparameter anstatt des Wertes "SG%20Weiterstadt%201886" zulässig: ... TODO ...
Hier findet Du den Quellcode zum Kapitel "DMRL Client integrieren" .
Nachdem der eingebaute Code funktionsfähig ist müssen nun noch kleinere Aufräumarbeiten durchgeführt werden: da keine Debugmeldungen mehr angezeit werden sollen sind einige kleine Korrekturen notwendig.
Dem DMRL Client muss mitgeteilt werden, dass keine Debugmeldungen ausgegeben werden sollen. Dazu wird im Funktionsaufruf DMRL_CLIENT.api(refDebug) einfach der Aufrufparameter refDebug entfernt, es wird also DMRL_CLIENT.api() stattdessen aufgerufen. Danach wird das <div>-Element mit der Id "ranglisteDebug" entfernt. Wenn Du nach diesen Änderungen im Browser ein Refresh durchführst, dann werden jetzt keine Debugmeldungen mehr angezeigt. Die endgültige Version der Homepage sieht jetzt so aus:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="de" lang="de">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>1. MGCV</title>
<script type="text/javascript"
src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
<script type="text/javascript"
src="http://www.meikel.at/dmrl/0.1/jquery.dump.js"></script>
<script type="text/javascript"
src="http://www.meikel.at/dmrl/0.1/dmrl-client.js"></script>
<script type="text/javascript">
$(document).ready(function() {
jQuery('#ranglisteContainer').css("display", "block");
DMRL_CLIENT.api().playersByTeam('SG%20Weiterstadt%201886', '#ranglisteBody');
});</script>
</head>
<body>
<h1>Herzlich Willkommen auf der Homepage des 1. MGCV</h1>
<h2>Neuigkeiten</h2>
<p>Bisher haben wir noch keine eigene Minigolfanlage auf der wir
spielen können.</p>
<p>Wir freuen uns jederzeit über neue Mitglieder.</p>
<h2>Externe Links</h2>
<ul>
<li><a href="http://www.minigolf-france.fr/">Website des
Verbandes</a></li>
<li><a href="http://www.camping-carpe-diem.com/">schöne
Übernachtungsmöglichkeit im Herzen des Vaucluse</a></li>
<li><a href="http://de.wikipedia.org/wiki/Vaucluse">Das
Vaucluse auf Wikipedia</a></li>
</ul>
<div style="display: none" id="ranglisteContainer">
<h2>Rangliste</h2>
<div id="ranglisteBody">Die Rangliste wird geladen ...</div>
</div>
</body>
</html>
Hier findet Du den Quellcode zum Kapitel "Debugmeldungen entfernen" .