Mit Scrivito lassen sich Websites erstellen, die interne oder externe Daten nutzen und diese ansprechend darstellen, seien es persönliche Daten in einem Portal oder Produktdaten in einem Online-Shop. Lange war dies Entwicklern vorbehalten, doch seit es dafür APIs im Scrivito SDK gibt, können solche Websites auch von Redakteuren erstellt werden. Hierfür die Grundlagen zu schaffen, bleibt jedoch weiterhin eine Aufgabe für Entwickler, die allerdings deutlich leichter bewältigt werden kann.

Diese Anleitung möchte Ihnen einen Einblick in das Räderwerk geben, mit dem interne und externe Daten auf Webseiten angezeigt und geändert werden können. Der Attributtyp datalocator auf der einen Seite und Datenklassen auf der anderen bilden das Fundament, auf dem Daten aus jeder beliebigen Quelle eingebettet werden können, die eine JavaScript-basierte Applikation verarbeiten kann. Wir werden hier ein universelles Datenlisten-Widget für die Scrivito Example App entwickeln und es mittels einer Datenklasse mit einer kleinen handgefertigten Mitarbeiterdatenbank verbinden, um zu zeigen und zu vermitteln, wie die Rädchen ineinandergreifen. Als Sahnehäubchen werden wir dann eine Mitarbeiter-Detailseite hinzufügen und aus dem „DataListWidget“ heraus verlinken.

Wir steigen direkt ein und setzen lediglich voraus, dass Sie sich mit dem Datenmodell von Scrivito ein wenig vertraut gemacht und idealerweise bereits ein Widget erweitert oder gar entwickelt haben.

Der Attributtyp datalocator ermöglicht es Redakteuren, Daten aus internen oder externen Quellen als Inhalte zu Webseiten hinzuzufügen. Interne Daten stammen typischerweise von CMS-Datenobjekten, die auf einer Objektklasse basieren, die beispielsweise Stellenangebote, Veranstaltungen, Produkte oder ähnliches repräsentiert.

Für die Arbeit mit Daten wird eine Datenklasse („data class“) benötigt, die mindestens einen Callback enthält, mit dem die Daten abgerufen werden können. Sieht ein Anwendungsfall vor, dass Daten auch erstellt, aktualisiert oder gelöscht werden können sollen, können hierfür ebenfalls Callbacks definiert werden.

Hat ein Widget ein Attribut des Typs datalocator, können Redakteure über das User-Interface von Scrivito einen Objekttyp oder eine Datenklasse als die von diesem Attribut zu verwendende Datenquelle auswählen. Darüber hinaus können die Quelldaten nach ihren Eigenschaften gefiltert sowie deren Sortierung und die maximale Größe der Ergebnismenge festgelegt werden. Das Widget wird dann entsprechend dieser Ergebnismenge gerendert.

Ein datalocator-Attribut gehört üblicherweise zu einem Widget, das es auch rendert. Eine einfache Definition einer Widget-Klasse mit einem solchen Attribut könnte wie dieses “DataListWidget“ aussehen:

Neben dem Attribut data hat das Widget eines namens content vom Typ widgetlist. Wir verwenden es, um die Mitarbeiterdaten aus dem datalocator zu rendern. Damit das Widget beispielsweise im Widget-Auswahldialog oder in der Seitenleiste leicht auffindbar ist, sollte es mittels Konfiguration einen title (und vielleicht auch eine description) erhalten:

Um instanzen des DataListWidgets zu rendern, liest dessen Komponente zunächst mit get das data-Attribut aus und macht diesen Inhalt mit dem useDataLocator-Hook zu einem DataScope, d.h. zu einer Liste aus DataItems. Diese Liste wird dann iteriert, um ebenso viele Scrivito.ContentTag-Komponenten für die content-Widget-Liste zu rendern wie der DataScope Elemente enthält:

Der „Trick“ besteht hier darin, dass das dataContext-Property jedes Mal, wenn Scrivito.ContentTag gerendert wird, das betreffende DataItem erhält, einschließlich aller seiner Attribute. Fügt ein Redakteur nun ein Widget als Inhalt zu einer der content-widgetlisten hinzu, etwa ein Text-Widget, dient der Datenkontext des jeweiligen DataItems mit seinen Attributen als die Quelle, der die Attributwerte beispielsweise über Platzhalter entnommen und dargestellt werden können.

Um exemplarisch zu zeigen, wie interne oder externe Daten in einer Scrivito-basierten Webapplikation verfügbar gemacht werden können, so dass Redakteure sie auf Webseiten unterbringen können, werden wir eine applikationsinterne „Datenbank” einrichten, ein JSON-Array mit einigen wenigen Datensätzen. In einem richtigen Anwendungsfall würde man solche Daten natürlich über die API-Endpunkte beziehen, die die Datenquelle zur Verfügung stellt.

Doch erst einmal sollten wir die App für solche Daten vorbereiten, indem wir die erforderliche „Infrastruktur“ für all dies schaffen und dann die Datenklasse bereitstellen.

Legen Sie in Ihrer Code-Basis zunächst den Verzeichnispfad “src/Data/Employee” an, analog zu “src/Objects/…” and “src/Widgets/…”. Stellen Sie anschließend bitte sicher, dass die Dateien, in denen die Klassen und die Konfiguration für die redaktionelle Bearbeitung definiert sind, importiert werden, wenn die App gestartet wird.

Nun, da alles vorbereitet ist, können wir uns mit der Datenklasse Employee befassen und sie definieren. Ihre Aufgabe besteht darin, den Zugriff auf die Mitarbeiterdaten zu ermöglichen und diese über das datalocator-Attribut unseres DataListWidgets an die App weiterzureichen. Mit anderen Worten dient eine Datenklasse dem SDK als ein Interface zur Datenquelle. Wann immer eine Komponente Ihrer App ein datalocator-Attribut nutzt, bedient sich das SDK der Callback-Routinen in der entsprechenden Datenklasse, um die betreffenden Datenfragmente abzurufen (get), aufzulisten (index), anzulegen (create), zu aktualisieren (update) oder zu löschen (delete).

Unsere Employee-Datenklasse implementiert nicht sämtliche dieser Callbacks, sondern lediglich get und index, um einzelne Datensätze abzufragen bzw. die Mitarbeiterdaten im Ganzen aufzulisten und zu filtern. Die Datei enthält auch die „Mitarbeiterdatenbank“:

Der obige Aufruf von Scrivito.provideDataClass erzeugt unsere Employee-Datenklasse. Ihr get-Callback gibt den Datensatz zurück, der durch die übergebene id referenziert wird.

Der index-Callback filtert zunächst die Datenbank nach den Kriterien, die für das datalocator-Attribut angegeben wurden. Normalerweise würde man dies mit einer Anfrage an den entsprechenden Webservice erledigen. Der index-Callback gibt ein Objekt mit einem Array zurück, das die IDs der nach der Filterung übrig gebliebenen Datensätze enthält.

Damit Redakteure die in den Datensätzen enthaltenen benannten Werte in Seiteninhalte einfügen können, werden wir ihnen nun die relevanten Eigenschaften als Platzhalter zur Verfügung stellen. Hierfür benötigen wir für die Employee-Datenklasse eine Konfiguration für die redaktionelle Bearbeitung:

Um unser neues “DataListWidget” in Verbindung mit der Mitarbeiterdatenbank zu testen, haben wir eine Seite zu der Example-App hinzugefügt und zwei Widgets darauf platziert. Das erste filtert die dept-Eigenschaft nach „Marketing“, wie auf dem obigen Screenshot zu sehen ist, das zweite filtert nach „Sales“. Beide enthalten ein Text-Widget mit Platzhaltern für die Mitarbeiterdaten.

Voilà!

In Verbindung mit einer Datenliste dient eine Detailseite dazu, einige oder alle Eigenschaften eines einzelnen Listenelements anzuzeigen oder zu bearbeiten. Eine solche Seite bereitzustellen ist sinnvoll, wenn die Elemente über mehr Eigenschaften verfügen als diejenigen, die in der Liste gerendert werden sollen, was definitiv nicht auf unsere Mitarbeiterdaten mit nur drei Eigenschaften zutrifft. Um jedoch zu zeigen, wie Sie eine solche Seite aufsetzen können, legen wir hier eine für die individuellen Mitarbeiter an.

Im Prinzip kann eine Detailseite als eine Standardseite betrachtet und angelegt werden, die mit einem datalocator-Attribut namens data ausgestattet ist. Scrivito erkennt eine Detailseite ausschließlich an dieser Kombination aus einem Attribut namens data und dessen Attributtyp datalocator, spezifiziert in der betreffenden Objektklasse. Ist dies bei einer Seiteninstanz gegeben, fügt das User-Interface von Scrivito automatisch einen Reiter „Daten“ zu den Seiteneigenschaften hinzu. Dort kann man als Redakteur nun die Datenklasse der Elemente angeben, für die diese Detailseite vorgesehen ist, und in dem dazugehörenden Listen-Widget einen Link auf sie zeigen lassen. Folgt man dann diesem Link, kann man auf der Detailseite die Eigenschaften der Listenelemente als Platzhalter einfügen. Außerdem können Sie mit Scrivito.useDataItem auf das aktuelle Element zugreifen, wenn Sie eine Seitenkomponente wie beispielsweise ein Widget entwickeln.

Für unsere Detailseitenklasse für Mitarbeiterdaten haben wir lediglich die „Page“-Standardklasse mit ihrer Komponente und der Konfiguration für die Bearbeitung kopiert und die Dateien „DetailsPage*“ genannt. Dann haben wir die Namen und Titel angepasst, den Code ein bisschen aufgeräumt und das data-Attribut hinzugefügt:

Aufbauend auf der obigen generischen Objektklasse “DetailsPage” können Sie nun Ihre tatsächliche spezialisierte Mitarbeiter-Detailseite entwerfen. Öffnen Sie hierfür deren Seiteneigenschaften und wählen Sie „Employee“ auf dem „Data“-Reiter als die Datenquelle der Details.

Kehren Sie als Nächstes zu der Seite mit der Mitarbeiter-Datenliste zurück und verlinken Sie darin ein Textfragment Ihrer Wahl mit der neuen Detailseite. Wir haben den Mitarbeiternamen verlinkt, aber jeder beliebige Link auf die Detailseite in einem Widget innerhalb des DataListWidgets erfüllt seinen Zweck.

Navigieren Sie schließlich über Ihren erstellten Link zur Detailseite und fügen Sie ein Text- oder Headline-Widget zu dieser Seite hinzu, um darin Variablen für Mitarbeiterdaten nach Bedarf einzufügen!

Ein DataScope wie der, den wir in unserer obigen Widget-Komponente verwendet haben, hat eine create-Methode, mit der DataItems erzeugt werden können. Um ein DataItem zu aktualisieren oder zu löschen, sind dessen Methoden update and delete verfügbar. Diese Methoden sind natürlich nur nutzbar, wenn die betreffende DataClass mit den entsprechenden Callbacks ausgestattet ist.

Daten lassen sich mit Scrivito.provideDataItem auch global als DataItem verfügbar machen.