Seiteninhalt

Grafischer Countdown (JS - jQuery)

An dieser Stelle wird ein grafischer Countdown vorgestellt, der als jQuery-PlugIn umgesetzt wurde. Die erforderlichen Daten wie Datum, Uhrzeit oder Titel werden in einer XML-Datei bereit gestellt. Diese kann Informationen zu zahlreichen Countdowns beinhalten. Ausgelesen wird sie mittels Ajax.

Das PlugIn basiert auf der jQuery-Version 1.3.2 und steht nachfolgend in unterschiedlichen Versionen zum Download zur Verfügung.

Beispiel

Das Beispiel zeigt die Anzahl Tage, Stunden, Minuten und Sekunden bis zum nächsten Jahreswechsel an.

Integration in die Seite

Neben der erforderlichen jQuery-Datei (jquery-latest.pack.js), muss das benötigte JavaScript (jquery.qp_countdown.js) im <head>-Bereich des Dokuments als externe JS eingebunden werden. Damit steht das PlugIn mit seinen zusätzlichen Funktionalitäten zur Verfügung.

<script src="jquery-1.3.2.min.js" type="text/javascript"></script>
<script src="jquery.qp_countdown.js" type="text/javascript"></script>
Quellcode: Externe JavaScript-Dateien einbinden

HTML

Es wird ein Element mit einer ID benötigt. Dieses dient als Container, der die Anzeige des Countdowns aufnimmt.

<div id="container"></div>
Quellcode: HTML

Inline-JavaScript

Um das PlugIn für oben beschriebenen HTML-Container zu verwenden, muss es entweder im onload-Ereignis des Dokuments oder im Dokument nach dem Element aufgerufen werden. Diese Beschreibung behandelt lediglich das Einbinden im onload-Event.

Die Syntax folgt folgendem Schema:

obj = $(selector).qp_countdown([options]);
Quellcode: Syntax

Dabei steht $(selector) für ein gültiges jQuery-Objekt, an das der Rückwärtszähler gebunden werden soll. Zu beachten gilt, dass bei einer Kollektion von mehreren Objekten lediglich das erste mit einem Countdown versehen wird.

Mit Hilfe des des optionalen Parameters options können dem Countdown unterschiediche Optionen übergeben werden. Welche genau zur Verfügung stehen, wird weiter unten beschrieben.

Zurückgegeben wird eine Referenz auf das Countdown-Objekt. Diese bietet einige öffentliche Methoden, mit denen das Verhalten des Rückwärtszählers kontrolliert werden kann.

Optionen

Wie bereits weiter oben erwähnt, können Erscheinungsbild sowie Verhalten des Countdowns über einen optionalen Parameter angepasst werden. Übergeben wird er als Objektliteral, z.B. {a: 1, b: 2, ..., x:26}.

Nachfolgend werden die Optionen beschrieben, die vom PlugIn akzeptiert werden.

  • height (integer)
    Bestimmt die Höhe einer einzelnen Ziffer (Standard: 40 Pixel).
  • width (integer)
    Bestimmt die Breite einer einzelnen Ziffer (Standard: 36 Pixel).
  • digitSpace (integer)
    Bestimmt den Abstand zwischen zwei Ziffern innerhalb einer Gruppe (Standard: 1 Pixel).
  • groupSpace (integer)
    Bestimmt den Abstand zwischen zwei Gruppen (Standard: 9 Pixel).
  • clDigit (string)
    Dieser Option kann der Name einer CSS-Klasse übergeben werden, die zum Formatieren einer Ziffer dienen soll.
  • format (string)
    Es handelt sich um eine Zeichenkette, mit deren Hilfe das Anzeigeformat des Countdowns bestimmt werden kann. Hierfür stehen folgende Zeichen zur Verfügung:
    • d - Tage
    • h - Stunden
    • m - Minunten
    • s - Sekunden

    Aufeinanderfolgende Zeichen bilden eine Gruppe. Gruppen werden durch ein Minus (-) voneinander getrennt.

    // Standardformat
    format: 'ddd-hh-mm-ss'
  • img (array)
    Dieses Array enthält die Dateinamen der Grafiken für die Ziffern. Die Bilder sind aufsteigend angeordnet, beginnend bei Null, endend bei Neun.
    // Standard
    img: ['0.gif','1.gif',/*...*/,'9.gif']

    Sollen andere Grafiken verwendet werden, muss hier das komplette Array angegeben werden!

  • imgPath (string)
    Im übergebenen String wird der Pfad zum Ordner angegeben, in dem sich die Grafiken der Ziffern befinden. Sollten die Bilder nicht im gleichen Verzeichnis abgelegt sein, müssen die Pfade im img-Array mit angegeben werden. imgPath bekommt im Gegenzug eine leere Zeichenkette ("") übergeben.
  • xmlFile (string)

    In dieser Option wird eine Zeichenkette übergeben, die den Dateiname mit zugehörigem Pfad der XML-Datei repräsentiert. Dieses File beinhaltet Informationen wie Endzeitpunkt oder Titel zum Countdown.

    Da das File mittels Ajax ausgelesen wird, ist zu beachten, dass sich die XML-Datei unter der selben Domain befindet wie das aufrufende Dokument. Dies ist der Sicherheitsrichtlinie der gleichen Herkunft (same origin policy) von JavaScript geschultet.

  • xmlType (get/post)
    Methode mit der der Ajax-Request ausgeführt wird. Zur Verfügung stehen get und post.
  • number (integer)
    Der Zahlenwert entspricht der ID des zugehörigen Countdowns im XML-File.
  • onStart (function)
    Die callback-Funktion onStart wird unmittelbar vor dem Start des Countdowns ausgeführt.
    onStart: function(info){
      alert("Titel: " + info.title);
    }

    Der Funktion wird das Argument info übergeben. Dabei handelt es sich um ein Objekt mit den folgenden Komponenten:

    • info.year - Jahr in dem der Countdown endet
    • info.month - Monat in dem der Countdown endet
    • info.day - Tag an dem der Countdown endet
    • info.hour - Stunde zu der der Countdown endet
    • info.minute - Minute zu der der Countdown endet
    • info.title - Titel
    • info.target - String/Zeichenkette zur freien Verfügung
  • afterCountdown (function)
    Die callback-Funktion afterCountdown wird ausgeführt nachdem der Countdown abgelaufen ist.
    afterCountdown: function(info){
      alert("Titel: " + info.target);
    }

    Der Funktion wird das Argument info übergeben. Dabei handelt es sich um ein Objekt, dessen Beschreibung weiter oben unter der Option onStart nachgelesen werden kann.

Beispiel - Initialisierung eines Countdowns

Eine Beispielinitialisierung für einen Countdown könnte wie folgt aussehen:

$(function(){
  objCount = $('#container').qp_countdown({
    number: 1,
    height: 20,
    width: 18,
    clDigit: 'digit',
    digitSpace: 1,
    groupSpace: 6,
    xmlFile: 'countdown/date.xml.php',
    xmlType: 'post',
    imgPath: 'countdown/bilder/18x20/',
    format: 'ddd-hh-mm-ss',
    onStart: function(info){
      $('#titleID').html("Titel: " + info.title);
    },
    afterCountdown: function(info){
      alert('Habe fertig');
    }
  });
});
 
Quellcode: Beispiel

Die eigentliche Initialisierung erfolgt wie bereits weiter oben erwähnt im onload-Event - $(function(){/*Initialisierung*/});.

XML-Datei

Der Countdown bezieht seine Informationen aus einem zugehörigen XML-File. Dort können zahlreiche Rückwärtszähler verwaltet werden. Über deren ID (Integerzahlenwert) kann der gewünschte Countdown ausgewählt und ins Dokument eingebunden werden.

Die Datei beinhaltet Informationen zum Endzeitpunkt (Jahr, Monat, Tag, Stunde, Minute) und zum Titel. Desweiteren existiert ein Element (target) zur eigenen Verwendung.

Aufbau des XML-Files

Das folgende Codefragmet zeigt den grundsätzlichen Aufbau des zugehörigen XML-Files.

<?xml version="1.0" encoding="utf-8"?>
<countdown>
  <event>
    <id>1</id>
    <title>Titel 1</title><!-- Titel -->
    <targetdate year="2010" month="01" day="1" hour="20" minute="00" /><!-- Zieldatum -->
    <target>Zusatzinformation 1</target><!-- Zusatzinfo zur eigenen Verwendung -->
  </event>
  <event>
    <id>2</id>
    <title>Titel 2</title><!-- Titel -->
    <targetdate year="2011" month="01" day="1" hour="20" minute="00" /><!-- Zieldatum -->
    <target>Zusatzinformation 2</target><!-- Zusatzinfo zur eigenen Verwendung -->
  </event>
  <!-- ... -->
  <event>
    <id>n</id>
    <title>Titel n</title><!-- Titel -->
    <targetdate year="2051" month="01" day="1" hour="20" minute="00" /><!-- Zieldatum -->
    <target>Zusatzinformation n</target><!-- Zusatzinfo zur eigenen Verwendung -->
  </event>
</countdown>
Quellcode: XML-File (schematisch für n Events)

Bestandteile des XML-Files

Die Datei besteht aus unterschiedlichen Komponenten, die kurz beschrieben werden. Es wird davon ausgegangen, dass die Grundlagen zu XML bekannt sind.

  • countdown
    Definiert den Countdown-Body und schliesst alle zugehörigen Element ein.
  • event
    Jedes event-Element repräsentiert einen Countdown. Es enthält als untergeordnete Elemente alle erforderlichen Informationen
  • id
    Nimmt die ID als Integerwert (ganzzahliger Zahlenwert) des Countdowns auf. Der Option number kann beim Initialisieren des Countdown-Objekts diese ID übergeben und somit der Rückwärtszähler gewählt werden.
  • title
    Für jeden Countdown kann in diesem Element ein Titel hinterlegt werden.
  • targetdate

    Dieses Element bildet den Endzeitpunkt des Countdowns ab. Die Zeitangaben werden in den dafür vorgesehenen Attributen eingetragen.

    • year - Jahr in dem der Countdown endet
    • month - Monat in dem der Countdown endet
    • day - Tag an dem der Countdown endet
    • hour - Stunde zu der der Countdown endet
    • minute - Minute zu der der Countdown endet
  • target
    Ein Element, das individuell verwendet werden kann.

Browserkompatibilität

Das Script wurde in folgenden Browsern erfolgreich getestet.

  • IE 6+
  • Firefox 1.5+
  • Opera 8.5+
    (Opera 8.5 Probleme mit xmlType=post)
  • Netscape 7+
  • Mozilla 1.5+
  • Safari (Win) 3+

Anregungen und Verbesserungsvorschläge

Anregungen und Verbeserungsvorschläge können gerne hier gepostet werden. Selbstverständlich steht dafür auch das Kontaktformular zur Verfügung.

Autor: Quaese (09. Oktober 2009) | 0 Kommentare
Foto: aboutpixel.de | werlinfri
[top]

Neuer Kommentar

Kommentar
Name:
eMail:
Kommentar:
(max: 500 Zeichen)
Schutz:

Wegen des erhöhten Spamaufkommens muss eine Zeichenfolge als Sicherheitsabfrage eingegeben werden.

captcha

Lösung:

Reset
 
Aktualisiert: 04. Juli 2008
Quaese, 2005
Sitemap sitemap
Impressum | Datenschutzerklärung | Valides XHTML und CSS