Mit der Monatsbox [1] können Webanwendungen erweitert werden, um Übersichten beliebiger Monate darzustellen und im Sinne einer Bedienoberfläche mit ihrer Hilfe ein Datum auszuwählen. Ihre Verwendung ist in diesem Dokument beschrieben.
Installation
Die Monatsbox besteht aus den folgenden Teilen:
-
monatsbox.js- JavaScript-Code -
monatsbox.css- Gestaltungsvorgaben
Zu deren Installation müssen sie zunächst aus dem Code-Repository [2] heruntergeladen werden. Nach dem Herunterladen werden die oben angegebenen Dateien an einen Ort kopiert, wo sie im Zugriff für HTML-Seiten sind, die die Monatsbox verwenden sollen.
Ist beispielsweise eine Webanwendung im Ordner meine-app abgelegt, kann die Monatsbox beispielsweise mit in diesen Ordner gelegt werden. Der Ordnerinhalt sieht dann etwa wie folgt aus:
/meine-app index.html monatsbox.js monatsbox.css
Verwendung
Die Demoseite [3] zeigt die Monatsbox in Aktion. Ihre Verwendung ist nachfolgend orientiert an der Demoseite Schritt für Schritt beschrieben.
Einbinden
Um die Monatsbox verwenden zu können, muss eine Webseite ihre Bestandteile einbinden. Das geschieht wie folgt.
<html>
<head>
<link rel="stylesheet" type="text/css" href="monatsbox.css">
<!-- weitere Kopfdaten hier -->
</head>
<body>
<!-- hier kommt der Body der Seite hin -->
<script src="monatsbox.js"></script>
</body>
</html>Der Verweis zur Datei monatsbox.css gehört dabei in den Kopfteil der HTML-Datei im HTML-Tag <head>. Die JavaScript-Datei wird gewöhnlich am Ende des HTML-Body, also vor dem HTML-Tag </body> notiert.
Ziel-Element
Zur Erzeugnung einer Monatsbox innerhalb einer Webseite wird an der Stelle, wo die Monatsbox erscheinen soll, ein HTML-Element erzeugt. Die Demoseite [3] verwendet als Ziel-Element beispielsweise ein div-Element der Klasse monatsbox.
<div class="monatsbox"></div>Monatsbox erzeugen
Um an der Stelle des Ziel-Elements eine Monatsbox darzustellen, wird JavaScript verwendet. Wie auch mit der Demoseite [3] gezeigt, kann zu diesem Zweck das Ereignis DOMContentLoaded genutzt werden:
DOMContentLoaded verwendendocument.addEventListener('DOMContentLoaded', function () {
// Code zur Anzeige hier
});Die Erzeugung einer Monatsbox funktioniert wie in folgendem Code-Beispiel.
// irgendwo an globaler Stelle im Code
// eine globale Moantsbox-Fabrik eroeffnen
var fabrik = new MonatsboxFabrik();
.
.
// Parameter festlegen
var jahr = 2022;
var monat = 10; // Oktober
var starttag = 1; // Montag
var ruhetag = 0; // Sonntag
var ereignisse = '3,7,16';
// Erzeugung einer Monatsbox
var box = fabrik.monatsboxErzeugen(jahr, monat, starttag, ruhetag, ereignisse, function(event) {
// hier kann noch Code zur Handhabung
// von Klicks stehen
});
// das Element der Klasse '.monatsbox' ermitteln
var elem = document.querySelector('.monatsbox');
// die Monatsbox dem Element '.monatsbox' hinzufuegen
elem.appendChild(box);Eine Monatsbox wird mit der Funktion monatsboxErzeugen wie im vorangegangenen Code-Beispiel erzeugt. Die Funktion erwartet folgende Parameter.
jahr-
Ein Ganzzahl-Wert, der das Jahr bezeichnet, in dem der Monat liegt, dessen Monatsübersicht erzeugt werden soll.
monat-
Ein Ganzzahl-Wert (1=Januar .. 12=Dezember), der den Monat im Jahr bezeichnet, dessen Monatsübersicht erzeugt werden soll.
starttag-
Ein Ganzzahl-Wert (0=Sonntag .. 6=Samstag), der den Tag bezeichnet, mit dem eine Woche startet.
ruhetag-
Ein Ganzzahl-Wert (0=Sonntag .. 6=Samstag), der den Tag bezeichnet, der als Ruhetag gekennzeichnet werden soll.
ereignisse-
Eine mit Komma getrennte Folge von Ganzzahl-Werten, die die Tage bezeichnet, die in der Monatsübersicht markiert erscheinen sollen. Beispiel: Der Ausdruck
3,8,19markiert den 3., 8. und 19. des betreffenden Monats. Klick-Lauscher(event)-
Eine Funktion, die von der Monatsbox immer dann gerufen wird, wenn in die Monatsbox geklickt wird. Der Parameter
eventkann verwendet werden, um Informationen über das Klick-Ereignis zu ermitteln (vgl. [4]).
Datum wählen
Ein Klick in die Monatsbox bewirkt, dass die Funktion gerufen wird, die bei Erzeugung der Monatsbox als Klick-Lauscher übergeben wurde. Mit Hilfe der Funktion datum der Monatsbox kann der Tag ermittelt werden, der geklickt wurde, wie im folgenden Code-Beispiel dargestellt.
// irgendwo an globaler Stelle im Code
// eine globale Moantsbox-Fabrik eroeffnen
var fabrik = new MonatsboxFabrik();
.
.
var box = fabrik.monatsboxErzeugen(jahr, monat, starttag, ruhetag, ereignisse, function(event) {
// Klick verarbeiten: Datum ermitteln
// und anzeigen
var d = fabrik.datum(event);
document.querySelector('.datum-wahl').textContent =
d.toLocaleDateString('de-DE') + ' (' +
d.toISOString() + ')';
});Der Aufruf der Funktion datum gibt das gewählte Datum als JavaScript-Date-Objekt [5] zurück und bewirkt zugleich, dass der angeklickte Tag in der Monatsübersicht markiert wird.
Gestaltung anpassen
Die Gestaltung der Monatsbox wird über das Cascading Style Sheet monatsbox.css gesteuert. Nachfolgend zwei Beispiele zur Anpassung der Gestaltung.
- Markierung des gewählten Tages
-
Die Gestaltung der Markierung des gewählten Tages kann über
td.monatsboxGewaehltgeändert werden. - Markierung von Ereignissen
-
Die Gestaltung der Markierung von Ereignissen wird über
td.monatsboxFeiertaggesteuert.
Alle Einträge des Stylesheets können nach Wunsch beliebig geändert werden.