Eigene decorators erstellen

Zur Darstellung von Objekten verwendet agorum core an vielen Stellen cardlet-basierte Listen oder Ansichten. Für jedes darzustellende Objekt erzeugt das System ein cardlet des Typs agorum.object, das für die Anzeige dieses Objekts verantwortlich ist. Je nach Typ und Eigenschaften des Objekts kann diese unterschiedlich ausfallen, etwa sind bei einer E-Mail andere Daten interessant als bei einem Ordner.

Um die Darstellung von Objekten flexibel und erweiterbar gestalten zu können, greift das agorum.object-cardlet auf decorators zurück, die sich um die Ermittlung und Anzeige der Daten kümmern. Ein decorator hat immer eine definierte Aufgabe, wie die Anzeige des Icons oder des Dateinamens.

agorum core liefert für viele Standard-Merkmale von Objekten bereits decorators mit. Im Rahmen von Projektanforderungen, etwa das Darstellen weiterer Daten für Objekte oder das Ausblenden bestehender, können Sie eigene decorators einbinden.

Wichtig: Achten Sie bei der Entwicklung von decorators auf die Performance. Ein einziger langsamer decorator kann die Darstellung von Listen stark verzögern, denn agorum.object-cardlets können immer erst dargestellt werden, wenn alle decorators ihre Arbeit abgeschlossen haben. Tätigen Sie keine potenziell langsamen Operationen wie Suchen oder Zugriffe auf externe Datenquellen.

Definition

Ein decorator ist eine JavaScript-Bibliothek, die eine einzelne Funktion exportiert. agorum.object-cardlets rufen diese Funktion jedes Mal auf, wenn ein Objekt dargestellt werden soll, unabhängig vom Typ dieses Objekts.

module.exports = (cardlet, object, def) => {
  // ...
};

Parameter

Parameter	Beschreibung
cardlet	Definiert das von den zuvor aufgerufenen decorators erzeugte cardlet. Der decorator führt ggf. nötige Modifikationen durch.
object	Definiert das Objekt, das das System darstellt.
def	Definiert die cardlet-Definition, die das System zur Erstellung des agorum.object-cardlets verwendet hat. Eventuell sind Parameter vorhanden, die die Darstellung beeinflussen.

Einen decorator anlegen und registrieren

siehe cards decorator registrieren

Einen decorator implementieren

Der Aufbau eines decorators wird im Folgenden anhand des mitgelieferten icon-decorators beschrieben:

let decorators = require('/agorum/roi/customers/agorum.cards/js/decorators');
let icons = require('/agorum/roi/customers/agorum.icons/js/icons');

module.exports = (cardlet, object) => decorators.with(cardlet, 'icon', icon => icon.icon = icons.object(object).icon);

Das Beispiel verwendet neben der icons-Bibliothek die JavaScript-Bibliothek agorum.cards/js/decorators, die Funktionen zum einfachen Einfügen, Ändern und Entfernen von Informationen in dem zu erstellende cardlet enthält.

Das Beispiel sucht das Element mit dem Namen icon und hinterlegt dort das von icons.object() ermittelte Objekt-Icon, sofern es gefunden wurde. Das Element selbst wurde dabei schon von einem vorhergehenden decorator erzeugt, der für das grundsätzliche Layout des cardlets verantwortlich ist.

Aktuell sind folgende Elemente für die Verwendung in decorators verfügbar:

Name	Typ	Beschreibung
icon	agorum.img	Definiert das Icon, das für dieses Objekt erscheint. Im Standardfall handelt es sich hierbei um das Icon, das icons.object() zurückliefert. Ein abweichendes Icon kann dargestellt werden, etwa das Bild des Absenders für Notizen. Für eine indirekte Art, eine Objekt-card zu modifizieren und etwa ein Icon hinzuzufügen, siehe object icons registrieren.
title	agorum.text	Definiert eine Überschrift, die für dieses Objekt erscheint. Stellt im Standardfall den Parameter displayName des Objekts dar.
time	agorum.text	Definiert einen Zeitstempel, der für dieses Objekt erscheint. Im Standardfall wird der Zeitpunkt der letzten Änderung verwendet.
detail	agorum.text	Definiert einen kurzen Text, der wesentliche Eigenschaften des Objekts zusammenfasst. Beispiel Für Dateien erscheint die Größe, für E-Mails erscheinen Absender und Empfänger.
actions	Gruppe	Ist für Schnellaktionen reserviert, die Benutzer auf dem Objekt aus können. Beispiel Für Ordner wird eine Suche angeboten, die auf diesen Ordner beschränkt ist.
chips	Gruppe	Hinterlegt cardlets des Typs agorum.chip, die Sie etwa zur Anzeige von Benutzer-Tags verwenden können.
content	Gruppe	Stellt den Inhalt des Objekts oder ein Auszug davon dar. Die Darstellung variiert je nach Objekttyp.
location	Gruppe	Zeigt im Standard die Liste der Pfade an, unter denen das Objekt erreichbar ist.
super	Gruppe	Zeigt übergeordnete Objekte an, sofern vorhanden. Beispiel Zeigt bei einem E-Mail-Anhang die zugehörige E-Mail an.
sub	Gruppe	Zeigt untergeordnete Objekte an, sofern vorhanden. Beispiel Zeigt bei einer E-Mail die zugehörigen Anhänge an.

Hinweis: Je nach Detailgrad der Darstellung existieren eventuell einzelne dieser Elemente nicht. Das System wählt etwa für dargestellte E-Mail-Anhänge eine kompaktere Ansicht ohne die Gruppen content, super und sub. Verwenden Sie daher zunächst die Funktion decorators.with(), um das Element zu suchen, das das System zur Anzeige verwenden soll. Existiert dieses nicht, kann der decorator teilweise oder vollständig übersprungen werden.

Interaktivität

Da decorators im Gegensatz zu card-Handlern (siehe Eigene cardlets erstellen) keine Ereignisbehandlung durchführen können, können Sie nicht direkt auf Benutzerinteraktion reagieren. Möchten Sie dennoch interaktive Elemente in einem agorum.object-cardlet darstellen, existieren die folgenden Möglichkeiten.

Eigenes cardlet einbetten

Ein decorator kann zur Darstellung von interaktiven Elementen ein cardlet einbetten, das diese Funktion übernimmt. Das System stellt etwa die mitgelieferte Pfadanzeige auf diesem Weg dar.

Standard-Links verwenden

Neben den für alle cardlets verfügbaren Link-Typen wie object und action (siehe JavaScript-Bibliothek agorum.cards/js/cards) können Sie innerhalb von agorum.object-cardlets zusätzlich Links des Typs toggle verwenden, die folgendermaßen funktionieren:

Der Link (etwa toggle:my.test.value) wird als name-Attribut eines Hyperlinks in einem agorum.text-cardlet oder als name-Eigenschaft eines interaktiven cardlets gesetzt.
Wenn ein Benutzer auf ein solches Element klickt, wird in der Definition des umgebenden agorum.object-cardlets der boolesche Wert des so benannten Schlüssels (im Beispiel my.test.value) invertiert und das cardlet neu erzeugt.
Der decorator kann jetzt auf den Wert dieses Schlüssels in der Definition reagieren und seine Darstellung anpassen.

Die mitgelieferten Adress-cardlets verwenden toggle-Links, um den Bearbeitungsmodus an- und abzuschalten.

Erweiterung der automatischen Aktualisierung (def.watch)

Innerhalb eines decorators können Sie Einfluss darauf nehmen, welche Objekte für die automatische Aktualisierung des agorum.object-cardlets überwacht werden. Hierfür wird im Parameter def das Array watch bereitgestellt, das die UUIDs aller Objekte enthält, die überwacht werden sollen.

Im Standard ist hier die UUID des primär dargestellten Objekts enthalten. Wenn ein decorator Daten aus weiteren Objekten für die Darstellung verwendet und sich diese Objekte unabhängig ändern können, fügen Sie die UUIDs dieser Objekte zu diesem Array hinzu.