Entwicklungs-HOWTO

Dieses Feature gibt es seit Stud.IP Version 2.0

Um in Stud,IP eine Kalenderansicht zu generieren, benötigt man die Klasse CalendarView (zu finden in lib/calendar/CalendarView.class.php).

Zuerst erzeugt man sich eine Instanz der Klasse, füllt diese Instanz mit Spalten und zeigt sie dann an. Ein Beispiel:

Zeile 1: Es wird eine leere Kalendaransicht erzeugt.
Zeile 2: Dem Kalendar wird eine neue Spalte hinzugefügt.
Zeile 3-10: Der Spalte wird ein neuer Eintrag hinzugefügt. Dafür übergibt man ein Array, das mindestens start, end und title beinhaltet. Eine vollständige Liste aller möglichen Werte steht weiter unten.
Zeile 13: Das gibt die gerenderte Ansicht aus.

1.  Beispiel-Plugin

In dem folgenden Test-Plugin kann man gut erkennen, was man alles machen kann/muss, um eine derartige Kalenderansicht zu bekommen.

Attach::TestPluginKalenderAPI.zip Δ

2.  Die Struktur eines Eintrags

Der CalendarView umfasst quasi den ganzen Bereich des Kalenders mit mehreren Tagen (oder was auch sonst an Spalten gewünscht ist) und den Einträgen und den Beschriftungen der Stunden auf der linken Seite.

Jeder Tag (wobei auch etwas anderes als ein Tag eine Spalte repräsentieren kann) ist eine Instanz der Klasse CalendarColumn, bekommt einen Titel und mehrere Arrays, wovon jedes einzelne einem Termin entspricht. Die Struktur für so ein Termin-Array ist (wovon manche Einträge optional sind):

array (

  'id',
  'start_formatted',
  'end_formatted',
  'title',
  'content',
  'url',
  'start'
  'end',
  'onClick',
  'color',
  'visible'

)

Relevant von diesen Angaben sind start, end und title. Diese Angaben müssen gemacht werden, ansonsten lässt sich der Termin nicht ordentlich darstellen.

• id: Eigentlich ist die id nur wichtig, wenn auch onClick angegeben wurde, damit die Javascript-Funktion auch weiß, um welchen Eintrag es sich handelt.
• title: Titel in der Kopfzeile des Termins. Muss angegeben werden.
• content: Kleiner Text unter dem Titel im Körper des Termins. Kann so lang sein, wie er will. Falls der Platz nicht ausreicht, wird das automatisch abgeschnitten.
• url: Man kann ja auch auf einen Termin klicken. Und url gibt die Seite an, zu der man dann gelangt.
• start: Muss angegeben werden. Dies ist einfach eine Zahl, die so kodiert ist <stunde><minute>. Für 12 Uhr 31 schreibt man also 1231. Und für 6 Uhr und sieben Minuten schreibt man 0607.
• end: Muss angegeben werden. Format wie bei start.
• onClick: Gibt eine Javascript-Funktion an, die beim Klick auf den Termin ausgeführt wird. Es kann auch eine anonyme Funktion daklariert werden wie "function (id) {}". Falls keine anonyme Funktion angegeben wird, darf nur der Funktionsname ohne die Klammern angegeben werden. Diese Funktion bekommt dann die id des Termins übermittelt. Zudem wird natürlich verhindert, dass die "url" aufgerufen wird, wenn man drauf klickt.
• color: Farbe im CSS-Stile, also wie "#ff0000" oder "rgba(255, 0, 0, 0.5)" oder einfach "cyan". Mit dieser Farbe wird der Termin dargestellt.
• visible: ist der Termin sichtbar?
• start_formatted: Start-Uhrzeit in schriftlicher Form. Wird nur für die visuelle Ausgabe benutzt und nur in der alten API. (deprecated)
• end_formatted: Ende-Uhrzeit in schriftlicher Form. Wird nur für die visuelle Ausgabe benutzt und nur in der alten API. (deprecated)

Es gibt auch die von CalendarView abgeleitete Klasse CalendarWeekView. Diese Klasse ist speziell für eine Wochenansicht gedacht. Sie hat spezielle Methoden wie setDays, die sicher stellen, dass auch Tage angezeigt werden, die eventuell keine Termine besitzen.