Details for JS-API Collection-Viewer v4 (in Bearbeitung)
Das ProgOnline System lässt sich über die JavaScript Schnittstelle einbinden. Diese wird bereits von verschiedenen Webseiten aktiv verwendet.
Für die JavaScript Einbindung (JS-API) gibt es eine Beispiel Seite:
https://programmzeitung.progdev.sneakapeek.ch/HTML/Beispielseite
Einführung
Mit der API für den Collection Viewer greifen Sie auf jeweils eine Sammlung in Ihrer ProgOnline Datenbank zu und geben die Events darin auf der Webseite aus. Die Sammlung muss öffentlich zugänglich sein. Für die Ausgabe auf der Webseite nutzen wir benutzerdefinierte HTML Tags, Attribute und Klassen, welche auf dieser Seite genauer erklärt werden.
Die Daten aus der Datenbank werden im JSON Format an den Browser geliefert. Welche Daten im JSON genau enthalten sind, wird über das Attribut “field” bestimmt, das in bestimmten HTML Tags verwendet werden kann. Für die Navigation durch ein JSON-Objekt empfehlen wir JSONata.
JavaScript File einbinden ???
Sie benötigen ein JavaScript-File mit der folgenden URL:
Collection Viewer im HTML einbinden
TAG <collection-viewer>
Kennzeichnet im HTML den Ort, an dem die Events angezeigt werden.
Attribut | Werte | Beispiel |
|---|
Attribut | Werte | Beispiel |
|---|---|---|
collection | String, der eine Collection eindeutig bezeichnet. Stammt aus ProgOnline und entspricht “space.document”. | collection =”Content.Example” |
template | eindeutige id aus dem Template-Tag | template=”#exampleVeranstaltungenTemplate” |
params | im JSON-Format: fromDate | params='{“param1”:”value”, “param2”:”value”}' |
size | int | size = “10” |
page | int | page=”3” |
Innerhalb vom Tag <collection-viewer> können weitere HTML Tags genutzt werden (z.B. <ul>). Auf diesen können/müssen noch spezielle Klassen vergeben werden, damit die Einbindung klappt.
Klasse | Zweck |
|---|
Klasse | Zweck |
|---|---|
collection-viewer-hook | erforderlich: kennzeichnet den Tag im HTML, an den das Template eingefügt wird |
cel-swiper | optional: Die Collection wird in einem Container angezeigt, welcher nach links und rechts gewischt werden kann, damit mehr Veranstaltungen angezeigt werden. |
TAG <template>
Mit diesem Tag wird eine Vorlage definiert, die bestimmt, wie eine Veranstaltung aus ProgOnline im Collection-Viewer dargestellt wird. Vergeben Sie eine eindeutige ID, damit Sie das Template im <collection-viewer> klar angeben können.
TAGs und Attribute für das Template
Alle Tags unterstützen die globalen Attribute und weitere Tag-spezifische Attribute z.B. “alt” für <img>.
Innerhalb des Templates können folgende Tags und ihre Attribute genutzt werden um Daten aus ProgOnline anzuzeigen.
<cel-data-datetime>
Attribute | Werte | Zweck/Beispiel |
|---|
Attribute | Werte | Zweck/Beispiel |
|---|---|---|
field | siehe Liste weiter unten | bezieht sich auf die Daten aus ProgOnline |
options (JSON-Format) |
| |
debug | -- | Das Attribut “debug” führt zu einer Anzeige “undefined”, wenn ?? |
<cel-data-time>
Attribute | Werte | Zweck/Beispiel |
|---|
Attribute | Werte | Zweck/Beispiel |
|---|---|---|
field | siehe Liste weiter unten | bezieht sich auf die Daten aus ProgOnline |
debug | -- | Das Attribut “debug” führt zu einer Anzeige “undefined”, wenn ?? |
<cel-data-a>
Attribute | Werte | Zweck/Beispiel |
|---|
Attribute | Werte | Zweck/Beispiel |
|---|---|---|
field | siehe Liste weiter unten | bezieht sich auf die Daten aus ProgOnline |
extract | JSONata-String | Damit kann man im verschachtelten JSON-Objekt navigieren und z.B. die Darstellung an Bedingungen knüpfen. |
<cel-data-img>
Attribute | Werte | Zweck/Beispiel |
|---|
Attribute | Werte | Zweck/Beispiel |
|---|---|---|
field | siehe Liste weiter unten | bezieht sich auf die Daten aus ProgOnline |
src-fallback | URL | Wenn das richtige Bild nicht geladen werden kann, wird das Fallback-Bild benutzt. |
<cel-data>
Attribute | Werte | Zweck/Beispiel |
|---|
Attribute | Werte | Zweck/Beispiel |
|---|---|---|
field | siehe Liste weiter unten | bezieht sich auf die Daten aus ProgOnline |
extract | JSONata-String | Damit kann man im verschachtelten JSON-Objekt navigieren und z.B. die Darstellung an Bedingungen knüpfen. |
debug | -- | Das Attribut “debug” führt zu einer Anzeige “undefined”, wenn ?? |
weitere wichtige Klassen
Klasse | Zweck |
|---|
Klasse | Zweck |
|---|---|
cel-data-root | erforderlich. z.B. auf <li> ergänzen. |
cel-data-empty | wird automatisch gesetzt (am collection-viewer-hook), wenn keine Daten vorhanden sind. |
Liste möglicher field-Values (Stand September 2023)
Value | Erklärung |
|---|
Value | Erklärung |
|---|---|
all | Gibt alle vorhandenen und abgefüllten fields aus. Kann z.B. genutzt werden um anhand einer Beispielveranstaltung herauszufinden, wie das JSON aussieht, wie die möglichen fields heissen und was sie beinhalten. |
performanceId |
|
progOnEventId |
|
state |
|
title |
|
titleRaw |
|
description |
|
descriptionAddition |
|
startDateTime |
|
endDateTime |
|
eventGenres |
|
eventForm |
|
category_1_name |
|
createDate |
|
changeDate |
|
location |
|
location_fullName |
|
location_name |
|
location_street |
|
location_streeAddition |
|
location_zip |
|
location_city |
|
location_cityAddition |
|
location_addressDescription |
|
location_country |
|
location_latitude |
|
location_longitude |
|
location_phone |
|
location_fax |
|
location_mobile |
|
location_email |
|
location_url |
|
organiser |
|
organiser_fullName |
|
organiser_name |
|
organiser_phone |
|
organiser_fax |
|
organiser_mobile |
|
organiser_email |
|
organiser_url |
|
urls | Liefert im JSON alle vorhandenen Links zurück. Um einen konkreten Link einzubinden nutzt man urls_{key}. Dies kann man z.B. dem JSON mit allen urls entnehmen. |
urls_image |
|
|
|
Die Filter-(und Such-)Funktion ist Serverseitig (TODO: überarbeiten)
Der Filter kann auf dem collection-viewer Objekt wie folgt konfiguriert werden:
setSearchConfig : function(fromdate, todate, searchterm, category)
Somit kann die "Suche"/Filter mit einem Von-, Bis-Datum einem Such-Text und einer Kategorie eingeschränkt werden. Die Kategorien sind im ProgOnline konfigurierbar. Die volle Filter Funktionalität ist auf der ProgrammZeitung Homepage sichtbar: https://www.programmzeitung.ch/Alles
Wegen den CORS Browser Restriktionen empfehlen wir die progonApiJS direkt vom *.prog.online einzubinden, zusätzliche benötigte JS-Bibliotheken wie z.B. Prototype.js können Sie auch direkt von Ihren Servern einbinden.