Open Source Dokumentenmanagement
Dokumentation
Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht
Navigation: Dokumentationen agorum core > agorum core cards
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.
|
| 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.