CMS-Frontend und Grundlagen

Zugriff auf das CMS-Frontend

Auf das CMS-Frontend kann per Webbrowser zugegriffen werden über die

• URL des CMS-Frontends ¹
• NeuroomNet-Startseite (sofern das CMS-Frontend über dessen URL dort als Kachel angelegt wurde)

Nach erfolgreichem Login erscheint die sog. "Project View":

Anmerkung zum Screenshot: Der Screenshot stammt aus einer internen Test-Umgebung der inSynergie, wo aber auch zum Teil Entwicklungsstände realer Daten aus früheren Kundenprojekten enthalten sind². Für Anonymität der Kunden werden in Screenshot Informationen, welche auf die konkreten Kunden hindeuten, mit blauen Rechtecken unkenntlich gemacht.

Hierarchischer Aufbau des CMS

Die im NeuroomNet-CMS vorhandenen Daten sind in 3 Ebenen hierarchisch eingeordnet, welche auch in der Project View zu sehen sind:

• Ebene 1: Projekt (Project), siehe 1 und darunter
• Ebene 2: Namensraum (Namespace) oder, synonym, Application, siehe 2 und darunter
• Ebene 3: API oder, synonym, Collection, siehe 3 und darunter
• (unter 4 befinden sich optionale Beschreibungen der APIs / Collections)

Also beispielsweise ist im Fall des Screenshots, s.o.,

• "BrightSign Demo" ein Projekt ³,
• "Medien" ein Namespace (Application) des Projekts "BrightSign Demo" und
• "Medien" eine gleichnamige API (Collection) des Namespaces "Medien" des Projekts "BrightSign Demo"

Ebene 1: Projekte

Die Ebene Projekte dient der Übersichtlichkeit für Parteien / Mandanten, die an mehreren Projekten arbeiten oder um große Projekte aufzuteilen. Die meisten Benutzer werden hier nur ein Projekt sehen - das Projekt, das für sie relevant ist.

Ebene 2: Namespaces

Ein Projekt besteht aus mindestens einem Namespace⁴: Ein Namespace steht dabei i.d.R. für mindestens einen der folgenden Aspekte

• Verschiedene Anwendungen / Apps, wie bspw. Exponate
• Themenbereiche
• Eine Partei / Mandant
• (Das komplette Projekt)

Technische Hinweise für Software-Entwickler bei Anlegung neuer Namespaces: Während die Projekte (Ebene 1) primär der Übersichtlichkeit für Menschen dienen, sind die Namespaces (und die APIs / Collections in der nachfolgenden Ebene 3) technisch relevant für Zugriffe auf das CMS und die Rechteverwaltung. Von daher, aus technischen Gründen und für die Herstellung einer einfachen Rechteverwaltung (inkl. insbes. Verwendung von Wildcards, siehe später) und insbes. Mandantenfähigkeit sind folgende Hinweise zu beachten⁵:

• Die Namespaces, welche technisch Texte (String) sind, müssen eindeutig sein
• Die Namespaces dürfen keine Whitespaces enthalten
• Doe Namespaces dürfen kein / (Slash) enthalten oder sonstige Zeichen, welche in URLs nicht enthalten sein dürfen
• Die Namespaces sollten ein sinnvolles Präfix haben wie bspw.:
  • Die entwickelnde Firma in umgekehrter Domänen-Notation
  • Eindeutiger Projektname
  • Eindeutiger Kundenname
• Die Namespaces können (optional) einen Anzeige-Namen haben, welcher im CMS-Frontend angezeigt wird (dieser muss dann nicht eindeutig sein oder die vorgenannten Hinweise beachten)
• In einem Namespace gelten dieselben Sprachen (definiert über eine dort anzulegende API / Collection languages), sofern Lokalisierbarkeit / Übersetzbarkeit relevant ist

Beispiele für sinnvolle Namespace-Namen:

• de.insynergie.BrightsignDemo
• Museum-fuer-Kunst123.exponat.impressionismus2
• Museum-fuer-Kunst123.backend
• de.insynergie.Museum-fuer-Kunst123.backend
• org.microsoft.Museum-fuer-Kunst123.backend

Beispiele für ungünstige Namespace-Namen:

• BrightsignDemo
• Impressionismus2
• backend

Anmerkung: Die im obigen Screenshot sichtbaren Namespaces sind fast alle nicht gut gewählt (zum Teil sind es aber auch Anzeige-Namen; in dem CMS-Frontend wird nämlich der Anzeigename angezeigt, falls dieser vorhanden ist).

Ebene 3: APIs / Collections

In der Ebene 3 werden die eigentlichen Daten abgelegt. Ein Namespace kann hier eine oder mehrere APIs / Collections (synonym⁶) enthalten. Für jede dieser APIs gilt Folgendes:

1. Enthält eine Liste 0 bis n strukturell gleichförmigen Datensätzen
2. Auf diese Liste und zugrundeliegende Struktur kann über eine Programmierschnittstelle mit folgenden Operationen zugegriffen werden:

  a. Elemente auslesen  
  b. Ein neues Element hinzufügen
  c. Ein bestehendes Element löschen  
  d. Ein bestehendes Element modifizieren
  e. Struktur der Liste ändern  

3. Über das CMS-Frontend lassen sich die Operationen 2.a - 2.d ausführen (2.e bzw. die Struktur lässt sich derzeit nur über die Programmierschnittstelle ändern).

Wichtig zu wissen für Nicht-Software-Entwickler: Die Daten im CMS können sich über das Frontend jeweils in den Collections anschauen und ändern lassen.

Schon mal für Software-Entwickler: Der Zugriff auf eine Collection / API erfolgt über HTTP-Operationen (Post, Put, Delete etc.) an https:<base-url>/<"schema" or "data">/<namespace>/<collection>. Dementsprechend dürfen in Collection-Namen keine ungültigen Zeichen für URLs enthalten sein.

Daten von APIs einsehen und editieren

Um Daten einer Collection anzusehen oder zu editieren, klickt man auf die entsprechende API 1:

Daten einer API einsehen: API-Ansicht

Nach Klicken auf eine API wird die API-Ansicht / View angezeigt, wo die dort enthaltenen Datensätze (Elemente) der API in einer Tabelle angezeigt werden:

Die einzelnen Datensätze sind durch Zeilen der Tabelle repräsentiert. Die Spalten korrespondieren zu einzelnen Attributen (Feldern), mit definierten Datentypen, der Datensätze (die Attribute und Datentypen der Datensätze sind im sog. Schema der API definiert).

In diesem Fall / Beispiel sind in der Tabelle Städte (in welchen weltbekannte Gebäude lokalisiert sind) eingetragen mit folgenden Daten und Datentypen (letztere in Klammern)

• CMS Identifier: Technische ID des Datensatzes (Anmerkung: Diese wird oft ausgeblendet; in diesem Beispiel / API wird sie angezeigt)
• Name (String / Text): Name der Stadt
• Postal code (String / Text): Postleitzahl
• Country (String): Land
• Continent (String): Kontinent
• Population (Number): Einwohnerzahl
• GPS Location (Geo-Point): GPS-Koordinaten der Stadt
• Image (File): Bild-Datei (in diesem Fall mit einem automatisch generierten Thumbnail in Größe 192x108)
• Description (String): Beschreibung

Z.B. hat der erste Datensatz (Element) 1 folgende konkrete Werte der Attribute:

• CMS Identifier: 373ba654-53af-48bc-8601-738eabdaea0a
• Name (String / Text): Gizeh
• Postal code (String / Text): 12512
• Country (String): Egypt
• Continent (String): Africa
• Population (Number): 4100000
• GPS Location (Geo-Point): 29.9775, 31.1325
• Image (File): Ein Satelliten-Bild (im Endeffekt eine jpg-Datei)
• Description (String): Location of the pyramids of Gizeh (Anmerkung: Dies ist ein lokalisierter Text für die Sprache Englisch, dazu später mehr)

Die in der Tabelle angezeigten Datensätze können durch den Filter-Button 2 sowie die Paging-Buttons 3 beeinflusst werden.

Element einer API hinzufügen

Um ein neues Element einer API hinzuzufügen, klickt man auf den Button "Add new item" 4 in der API-View. Es öffnet sich dann ein Popup mit der Editier-Ansicht eines API-Elements (API-Element-View), in dem konkrete Werte für das neue Element / Datensatz eingetragen werden können (gleiche View wie beim Editieren eines API-Elements, siehe folgenden Abschnitt).

Element einer API editieren (API-Element-View)

Um ein bereits existierendes Element einer API zu editieren, klickt man auf die entsprechende Zeile des Elements in der API-View. Dann öffnet sich ein Popup mit der Editier-Ansicht des geklickten API-Elements (API-Element-View) - in diesem Beispiel: Die Zeile zum Eiffelturm / Paris:

Hier können die Werte der einzelnen Attribute entsprechend geändert werden (beim Attribut "Image" gibt es bspw. einen Upload-Button, um eine andere Datei hochzuladen) oder einzelne Werte zurückgesetzt bzw. gelöscht werden über die roten Mülleimer-Icons. Der entsprechend geänderte Zustand des Elements kann gespeichert werden via "Save" 3. Alternativ kann der ggf. geänderte Zustand auch wieder verworfen werden, sofern noch nicht gespeichert wurde über den zuvor genannten Button, mittels Button "Cancel" 2.

Sofern entsprechend konfiguriert, gibt es auch eine Sprachenauswahl, so dass die Attributswerte (inkl. Mediendateien) pro Sprache definiert werden können: Dazu lässt sich per Sprachen-Buttons 6 die jeweilige Sprache auswählen, die gerade angezeigt wird. Pro Sprache lassen sich dann verschiedene Werte der Attribute eingeben (und speichern) für Attribute, die als lokalisierbar (localizable) im API-Schema definiert wurden⁷: In diesem Beispiel / API ist dies ausschließlich das Attribut "Description" 8 ganz unten auf dem unteren Screenshot (erkennbar am Icon links neben dem roten Mülleimer-Icon).

Über den Button "Clone" 4 lässt sich das aktuelle Element duplizieren.

Falls entsprechend konfiguriert, lässt sich über einen Button "Preview" ganz rechts oben (hier im Beispiel nicht sichtbar / konfiguriert) 7 die sog. Preview aufrufen. Später hierzu mehr, aber es kann im CMS ein anderes System definiert werden, welche dann den aktuellen (oder genauer gesagt zuletzt gespeicherten) Zustand des aktuellen Collection-Elements anzeigt. Diese Funktionalität dient primär zu Test- oder Debugging-Zwecken.

Beispiel: Übersetzungen einpflegen für ein API-Element / Datensatz

Als kleines, nicht untypisches Beispiel betrachten wir folgenden Fall: Angenommen, man möchte eine entsprechende französische Lokalisierung / Übersetzung des API-Elements zu Paris / Eiffelturm anfertigen, dann würde man wie folgt vorgehen (siehe Screenshot unten):

• In der geöffneten API-Element-View wählt man die Sprache "Französisch" aus über einen Maus-Click bei 1
• Man sieht ganz unten 2, dass das lokalisierbare Attribut Description noch leer ist (also hier fehlt offenbar noch ein französischer Text)
• Dementsprechend gibt man dort den französischen Text ein (z.B. "Localisation de la Tour Eiffel")
• Und klickt auf "Save" 3

Nun ist der französische Text entsprechend im CMS gespeichert und verfügbar für andere Software, welche diesen anzeigt oder sonst verwendet (ggf. muss die andere Software neu gestartet werden oder ähnlich, bis der neue Texte dort entsprechend verfügbar ist - abhängig vom konkreten Setup der anderen Software bzw. wann diese den Content vom CMS neu lädt / sich updated).

Element einer API löschen

Über die Editieransicht eines Elements einer API (API-Element-View) lässt sich ebenfalls dasselbe Element löschen - mittels Button "Delete" (5).

Importieren und Exportieren von Daten

Das CMS-Frontend erlaubt es, komplette Collection zu importieren und exportieren als JSON-Dateien.

Typische Anwendungsfälle hierfür sind:

• Lokale Backups von aktuellen Zuständen des Datenbestands erstellen oder wieder importieren
• Ggf. als Zwischen-Datei-Format, damit externe Übersetzer in Excel Übersetzungen anfertigen können⁸

Exportieren

Aktuelle Datenbestände (inkl. zugrundeliegender Schemas) lassen sich exportieren wie folgt:

• Ganze Projekte oder Namespaces über entsprechende Download-Buttons 6 respektive 7 in der Project-View
• Ganze Collections über den Button "Export" rechts oben in der jeweiligen Collection-Ansicht

Importieren

Über den Button "Import" 8 in der Project-View lassen sich zuvor exportierte Zip-Files wieder importieren.

Während ein Export unkritisch ist (höchstens länger dauert, falls große Mediendateien darin enthalten sind), ist ein Import potenziell gefährlich, weil existierende Daten überschrieben werden können je nach Szenario (falls es schon gleichnamige Namespaces und APIs im CMS gibt). Daher sollte dies nur von Sachkundigen durchgeführt werden (oder nur in Fällen, wo es definitiv noch keine Daten oder Strukturen im CMS zu den zu importierenden Daten / Strukturen gibt).

Der Import wird in der Entwickler-Dokumentation Export und Import genauer beschrieben.

Rechte-Konzept / Rechteverwaltung

Da das NeuroomNet-CMS auch ohne NeuroomNet verwendbar sein soll, wird hierfür nicht das NeuroomNet-Modul Rechteverwaltung verwendet, sondern ein spezieller Namespace "cms", welcher für entsprechend authorisierte Benutzer in der sog. Namespace-View sichtbar ist. Diese Namespace-View ist erreichbar über Button 9 rechts oben in der Project-View.

Im Namespace "cms" können dann neue Benutzer angelegt werden in Collection "users" über Button "add new item", wie in einer normalen Collection⁹ (und bestehende Users können auch analog editiert oder gelöscht werden).

Für weitere Erläuterungen zur Rechteverwaltung, die, auch wenn rein über das CMS-Frontend machbar, etwas technischer ist, siehe Benutzerrechte festlegen im technischen Teil.

Footnotes

1. Die konkrete URL ist abhängig vom individuellen Netzwerk-Setup und NeuroomNet- / CMS-Konfiguration (im Zweifel Ihre Vertrauensperson bei inSynergie fragen :-)). I.d.R. endet die URL mit "/form/", wie bspw. https://mysubdomain.mydomain.de/form/. ↩

2. Am Anfang der Durchführung von Kunden-Projekten ist es eine durchaus übliche Vorgehensweise, das über das Internet verfügbare CMS von inSynergie zu verwenden, bis ein entsprechender Kunden-NeuroomNet-CMS-Server im Kunden-Intranet verfügbar ist (was manchmal etwas dauern kann). Sobald der endgültige Kunden-NeuroomNet-CMS-Server verfügbar ist, können bis dahin im insynergie-NeuroomNet-CMS-Server verfügbare Daten und Strukturen, dort entsprechend importiert werden. ↩

3. In vielen Fällen empfiehlt es sich NICHT, BrightSign-Content über das NeuroomNet-CMS zur Verfügung zu stellen. Es ist aber grundsätzlich technisch möglich und kann sinnvoll sein, ist aber etwas "tricky". ↩

4. Technisch kann auch ein Namespace existieren ohne ein zugehöriges Projekt. Solche Namespaces (und zugehörige APIs) sieht man dann nicht in der Project-View, sondern nur in der Namespace-View. ↩

5. Zumindest wenn ein konkreter CMS-Server von vielen Parteien genutzt wird, sollten diese Hinweise beachtet werden. ↩

6. Ab jetzt wird primär der Begriff API (anstatt Collection) genutzt werden für eine einfachere Kommunikation. ↩

7. Die entsprechende Einrichtung / Konfiguration zur Lokalisierbarkeit wird im Kapitel für Software-Entwickler beschrieben. Vorweg: Es reicht nicht alleine das Konfigurieren von einzelnen Attributen als localizable, es müssen auch für den Namespace die verfügbaren Sprachen definiert werden über eine spezielle API languages. ↩

8. Die Empfehlung ist, dass auch externe Übersetzer direkt im CMS Texte übersetzen. In der Praxis ist es aber häufiger so, dass externe Übersetzer doch lieber mit Excel arbeiten. ↩

9. Im Namespace cms, welcher abgesehen von seiner Sichtbarkeit ein ganz normaler Namespace ist, gibt es auch noch die Collections "apps", "rights", "roles": Diese werden derzeit nicht genutzt. ↩