API¶

Generell ist der offene Web-Kalender da, um ohne Enschränkung genutzt zu werden. Die API kann genutzt werden, um Kalender dynamisch anzupassen.

Dieses Dokument ist von Belang, wenn davon was zutrifft:

Du bist ein Web-Entwickler, der den offenen Web-Kalender einbauen möchte.
Du möchtest die volle Flexibilität, nicht nur das, was mit der Konfigurationsseite möglich ist.
Du nutzt JavaScript, um dynamisch das Kalenderdesign und die Optionen anzupassen.
Du möchtest die Funktionalität des offenen Web-Kalenders erweitern.
Du möchtest den offenen Web-Kalender als Proxy benutzen, um JSON-Daten zu Terminen selbst anzuzeigen.

Endpunkte¶

Diese Endpunkte benutzen die selben Parameter:

/index.html - Editiere den Kalender
/about.html - Zeige die Beschreibung des Kalenders an
/calendar.html - Zeige den Kalender an
/calendar.spec - Lade die Spezifikation herunter
/calendar.ics - Lade die ICS-Kalenderdatei herunter
/calendar.json -Informationen über den Kalender und seinen Inhalt als JSON
/calendar.events.json - FLEXIBEL - hole die Termine als JSON. Bitte wisse, dass Du das nutzen KANNST aber nicht sicher sein kannst, dass das JSON-Schema so bleibt. Wenn du das willst, füge neue Tests hinzu.

/calendar.events.json benötigt zusätzliche Parameter:

timezone=UTC - die Zeitzone, in der die Termine angezeigt werden
from=YYYY-MM-DD - der Start des Zeitabschnitts, der angezeit werden soll (eingeschlossen)
to=YYYY-MM-DD - Das Ende des Zeitabschnitts, in dem Termine angezeigt werden sollen (nicht eingeschlossen)

Parameter¶

Alle Konfigurationsparameter sind ausreichend in der default_specification beschrieben. Das ist die Referenz. Z.B. wenn Du den Parameter title in der default_specification findest, dann hast du mehrere Optionen:

URL-ParameterYAMLJSON

Ändere den Titel in den URL-Parametern:

/index.html?title=calendar

Ändere den Titel in der YAML-Spezifikation:

title: calendar

Ändere den Titel in der JSON-Spezifikation:

{
  "title": "calendar"
}

Die Spezifikation Zusammenstellen¶

Du kannst das Aussehen und Verhalten des Kalenders mit Parametern anpassen. Wenn der selbe Parameter an verschiedenen Stellen angegeben ist, dann hast der erste Ort in dieser Liste Vorrang. Hier kannst Du Parameter setzen:

URL-Parameter¶

Alle Parameter eines Kalenders werden zur Spezifikation zusammengefasst. Die Query-Parameter der URL haben Vorrang vor allen anderen.

Examples:

index.html?language=de
calendar.html?title=CALENDAR

specification_url¶

Wenn Du diesen Query-Parameter in der URL setzt, werden die Editor-Einstallungen auch von dieser URL geladen. Die Query-Parameter in der URL überschreiben immer noch die Parameter in dieser Datei. Das als Dateiformat kannst Du YAML oder JSON verwenden.

Examples:

calendar.html?specification_url=https://github.com/niccokunzmann/open-web-calendar/raw/master/open_web_calendar/default_specification.yml

open_web_calendar.app.DEFAULT_SPECIFICATION¶

Das ist für Entwickler und Python-intern.

from open_web_calendar.app import DEFAULT_SPECIFICATION
DEFAULT_SPECIFICATION['title'] = 'calendar'

OWC_SPECIFICATION¶

Das ist eine optionale Umgebungsvariable. Lies mehr dazu in den Servereinstellungen.

default_specification ¶

Diese Datei enthält die Standardparameter. Diese dürfen nicht irgendwo im Quelltext gesetzt werden. Alle Parameter sind hier gelistet und dokumentiert, damit diese Datei als Referenz dient. Modifiziere diese Datei besser nicht sondern nutze die OWC_SPECIFICATION-Variable.

Parameter hinzufügen¶

Wenn Du als Entwickler einen neuen Parameter hinzufügst:

Füge den Parameter mit einem Standardwert zur default_specification hinzu
Add an implementation, depending on its use in the app.py or the templates of the JavaScript files. The specification is already available in all of them to use.
Add tests in features/configure-the-calendar.feature to check that the calendar responds to the feature.
Add tests in features/edit-the-calendar.feature to make sure that the parameter can be used when a calendar is edited.

Spezifikation im Kalender¶

app.py compiles the specification from the given parameters in get_specification(). In the template you can access the specification through the specification variable. The specification is available to JavaScript as the specification variable.

Siehe auch:

JavaScript Customization

Spezifikation auf der Index-Seite¶

The default specification is available before the calendar is built via JavaScript in the configuration.default_specification variable. There is a getSpecification() function which created the specification from the inputs. Generally, the specification variable should be used.

Architektur¶

Das Bild der Architektur ist hier unten.

architecture

The base of a calendar is the specification, given in the various forms. This specification influences all the steps.

After the specification is compiled, the calendar (ics) files are downloaded from the locations on the Internet.

From the calendar files, the events are generated.

Then, different views are chosen to display the events.

In the end, these lead to HTML and style changes of the calendar website.

In the real application, these steps are bit bit mixed up and unordered or omitted but this explains simply the basic, initial idea behind the event processing.