Allgemeines

Ein Anspruch auf Verfügbarkeit und fehlerfreie Funktion der Veranstaltungs-API besteht nicht. Die Nutzung der API ist kostenfrei und setzt lediglich voraus, dass du

  1. in deiner Umgebung php-Scripte selbst einbinden und ausführen kannst
  2. und über ausreichend Kenntnisse in der php-Programmierung hast, um unsere Musterscripte an deine Bedürfnisse anpassen zu können.

php-Script und Templates

Um Veranstaltungen des Veranstaltungs-Netzwerks auf deinen Webseiten anzuzeigen, benötigst du neben der auf unserem Server liegenden API lediglich folgende Komponenten:

  1. JSON-Events_volXmusik_de.php:
    Ein php-Script, das die von der API im JSON-Format bereitgestellten Daten von unserem Server abruft und via php include die nächsten 3 Templates einbindet.
  2. /includes/inc_event_functions.html5:
    Ein Set von Funktionen, die z.B. codiert gelieferte Daten in ein lesbares Format verwandeln.
  3. /includes/inc_json_eventlist.html5:
    Ein (Beispiel-)Template, das die bereitgestellten Daten als Veranstaltungsliste ausgibt.
    Der im Beispiel-Template verwendete Name der Seite für die Ausgabe der Veranstaltungsdetails ist json-termine-ausgabe.html und kann jederzeit angepasst werden.
  4. /includes/inc_json_event.html5:
    Ein weiteres (Beispiel-)Template, das die Daten einer einzelnen Veranstaltung ausgibt (Detailanzeige).

Einbindung in deine Webseiten

Installation des php-Scripts und der (Beispiel-)Templates

  1. Kopiere das php-Script in dein php-Script-Verzeichnis!
  2. Kopiere die beiden Templates in das Unterverzeichnis /includes!

Ausgabe der Veranstaltungsliste:

  1. Erstelle ggfs. eine neue Seite für die Liste!
  2. Binde das php-Script in diese Seite ein!
  3. Der Umfang der ausgegebenen Termine kann jederzeit über Filter-Parameter (s.o.) beeinflusst werden.

Ausgabe der Veranstaltungsdetails:

  1. Erstelle ggfs. eine neue Seite für die Ausgabe der Details einer einzelnen Veranstaltung
    und nenne diese json-termine-ausgabe
    oder passe das Template /includes/inc_json_event.html5 (s.u.) entsprechend an!
  2. Binde dass php-Script auch in diese Seite ein!
  3. Der Aufruf dieser Seite erfolgt mit Übergabe des GET-Parameters id (= ID des Termins)
    z.B. json-termine-ausgabe.html?id=4711

Filtern der angezeigten Daten

Werden keine Parameter übergeben liefert das php-Script alle veröffentlichten Veranstaltungen für den Zeitraum 1 Monat ab heute.
Soll die Ausgabe der Liste gefiltert werden, können folgende Parameter entweder via HTTP_POST oder via HTTP_GET an das php-Script übergeben werden:

  • s: Startdatum im UNIX-Timestamp Format (z.B. 1515020400 für 1.4.2018), das den Anfang des gewünschten Zeitraumes angibt, in dem die selektierten Veranstaltungen beginnen sollen.
  • e: analog zu [s], jedoch Ende des gewünschten Zeitraumes
  • r: Regione(en), in denen die Veranstaltungen stattfinden sollen. Eine durch Kommata getrennte Liste von Werten. Welche Werte für welche Region stehen, findest du leicht heraus, wenn du die Filter-Funktion des Veranstaltungskalenders auf volXmusik.de nutzt.
  • c: Kategorie(n) der gewünschten Veranstaltungen. Analog zu [r] ebenfalls eine Liste von Werten.
  • limit: über diesen Wert kannst du die maximale Anzahl der selektierten Werte vorgeben.
  • offset (Nur in Kombination mit [limit] erlaubt): Die Anzahl der Datensätze, die in der Selektion übersprungen werden sollen.
  • id: ID einer einzelnen Veranstaltung zur Anzeige deren Veranstaltungsdetails.

Durch die API bereitgestellte Felder

  • id: Eindeutige numerische Kennung jeder einzelnen Veranstaltung (numerisch)
  • time_stamp: Datum der letzten Änderung der Veranstaltung (Unixzeit)
  • titel: Titel der Veranstaltung (unformatierter Text)
  • startdatum: Datum des Beginns der Veranstaltung (Unixzeit)
  • startzeit_H: Stunde des Beginns der Veranstaltung (codiert)
  • startzeit_i: Viertelstunde des Beginns der Veranstaltung (codiert)
  • enddatum: Datum des Endes der Veranstaltung (Unixzeit)
  • endzeit_H: Stunde des Endes der Veranstaltung (codiert)
  • endzeit_i: Viertelstunde des Endes der Veranstaltung (codiert)
  • plz: Postleitzahl des Veranstaltungsortes (numerisch)
  • event_loc: Veranstaltungsort (unformatierter Text)
  • event_address: Postadresse der Veranstaltung (unformatierter Text)
  • event_address_suffix: Weitere Hilfreiche Angaben zur Adresse wie z.B. Stadthalle, Vereinsheim, … (unformatierter Text)
  • region: Region, in der die Veranstaltung stattfindet (unformatierter Text)
  • kategorie: Veranstaltungs-Kategorie (unformatierter Text)
  • beschreibung: Beschreibung der Veranstaltung (HTML-formatierter Text)
  • kontakt: Name und ggfs. Adressdaten der Kontaktperson (unformatierter Text)
  • kontakt_email: E-Mail-Adresse der Kontaktperson  (unformatierter Text)
  • entrance_fee0: (Eintritts-)Kosten regular (numerisch, ohne Euro-Zeichen)
  • entrance_fee1: (Eintritts-)Kosten ermäßigt (numerisch, ohne Euro-Zeichen)
  • entrance_fee_text: (Eintritts-)Kosten (unformatierter Text)
  • event_organizer: Name/Bezeichnung des Veranstalters (unformatierter Text)
  • event_org_url: Webseite des Veranstalters (unformatierter Text, URL)
  • bild:  volXmusik.de-interne URL eines Fotos zur Veranstaltung (zur Anzeige auf fremden Seiten ist die vorherige Freischaltung durch den Webmaster erforderlich)
  • canceled: 1, wenn die Veranstaltung abgesagt wurde, sonst leer