Durchsuchbare Dokumentation aufrufen
Zurück zur Dokumentationsübersicht
Sie können einen eigenen cardlet-Typ erstellen, etwa wenn Sie Teile einer Ansicht wiederverwenden möchten oder wenn eine eigene Ereignisbehandlung erforderlich ist.
Ein cardlet-Handler ist eine JavaScript-Bibliothek, die die Funktionen build und event exportiert.
Das System ruft diese Funktion auf, wenn ein agorum.cards.view-Widget ein cardlet des zugehörigen Typs darstellen soll.
let build = (cx, def) => {
// ...
};
cx
Sie können den cardlet-Kontext in der build-Funktion dazu verwenden, um Informationen über den inneren Zustand des cardlets zu hinterlegen, die später für die Verarbeitung von Events notwendig sind.
In folgendem Beispiel würde das System etwa für ein aufklappbares cardlet die Information speichern, ob das cardlet gerade geöffnet oder geschlossen ist:
cx.meta = {
expanded: false
};
Hinweis: Sie können ausschließlich das Feld meta des Kontexts zur Speicherung von Zustandsinformationen verwenden.
def
Übergibt zusätzliche Parameter, die für deren Darstellung relevant sind.
Das System ruft diese Funktion auf, wenn ein Ereignis innerhalb des cardlets ausgelöst und noch nicht von einem anderen handler behandelt wurde.
Die Funktion erhält als Parameter:
let event = (cx, type, path, param) => {
// ...
};
Tipp: Verwenden Sie die JavaScript-Bibliothek agorum.cards/js/cards, um gezielt auf bestimmte Ereignisse von bestimmten Elementen zu reagieren.
cx
Sie können den cardlet-Kontext in der event-Funktion neben dem Zugriff auf das Feld meta dazu verwenden, um das cardlet selbst zu ändern und eigene Ereignisse auszulösen (siehe cardlet-Kontext).
type
Übergibt den Namen des Ereignis-Typs.
Zur Übersicht der Standard-Ereignistypen siehe Standard-Ereignisse
path
Enthält ein Array aus den Namen aller benannten Elemente ab dem cardlet selbst bis zu dem Zielelement des Ereignisses.
{
type: 'agorum.card',
items: [
{
type: 'agorum.horizontal',
name: 'buttons',
items: [
{
type: 'agorum.button',
name: 'ok',
text: 'OK'
},
{
type: 'agorum.button',
name: 'cancel',
text: 'Cancel'
}
]
}
]
}
Ein Klick auf die OK-Schaltfläche dieses cardlets würde diesen Pfad zur Folge haben:
[ 'buttons', 'ok' ]
param
Übergibt weitere Daten über das ausgelöste Ereignis.
Das System übergibt den Funktionen build und event jeweils als erster Parameter den cardlet-Kontext. Während dieser in der build-Funktion hauptsächlich verwendet wird, um Zustandsinformationen im Feld meta zu hinterlegen, existieren in der event-Funktion weitere Möglichkeiten.
Die Modifikator-Funktionen remove, replace, insert und append erwarten jeweils einen (optionalen) Pfad als die ersten n-Parameter, der das Zielelement dieser Modifikation adressiert.
Geben Sie den Pfad nicht an, bezieht sich die Modifikation auf das gesamte cardlet, zu dem dieser Kontext gehört.
Hinweis: Modifikator-Funktionen stehen in der Funktion build bislang nicht zur Verfügung.
Beispiel für die Adressierung eines Unterelements
cx.replace('buttons', 'ok', {
type: 'agorum.button',
name: 'ok',
text: 'OK'
});
Beispiel für die Adressierung des gesamten cardlets
cx.append({
type: 'agorum.display',
text: 'Neuer Text'
});
Entfernt ein Element aus der cardlet-Struktur.
cx.remove(<path>);
Entfernt ein Element aus der cardlet-Struktur und ersetzt es durch ein neues.
cx.replace(<path>, <def>);
Fügt dem Zielelement ein neues Unterelement hinzu.
cx.append(<path>, <def>);
Fügt ein neues Element vor dem Zielelement ein.
cx.insert(<path>, <def>);
Löst ein benutzerdefiniertes Ereignis aus, das von einem übergeordneten cardlet-Handler behandelt werden kann.
cx.fire(<type>, <param>);
Hinweis: Der auslösende cardlet-Handler kann ein derart ausgelöstes Ereignis nicht selbst behandeln, sondern propagiert es strikt aufwärts.
Registriert das cardlet für die als String-Array übergebenen Broadcast-Kanäle.
Wird auf einem dieser Kanäle eine Nachricht empfangen, löst das Ereignis broadcast dieses cardlets aus.
cx.sub(<channels>);
Hebt alle bisher bestehenden Broadcast-Registrierungen auf.
cx.sub(<channels>);
Löst aus, sobald ein Benutzer auf Elemente klickt, die Sie als interactive: true oder selectable: true definiert haben.
Löst aus, sobald ein Benutzer auf Links innerhalb von Elementen des Typs agorum.text klickt, die ein name-Attribut besitzen.
Beispiel für einen Link
<a name="link-name">Link-Text</a>
Löst aus, sobald eine Nachricht auf einem registrierten Broadcast-Kanal empfangen wird.
Als Parameter werden der Name des Kanals sowie das Daten-Objekt der Nachricht übergeben.
Verwendungsbeispiel
exports.build = (cx, def) => {
// ...
cx.sub(['object-updated-' + def.id]);
// ...
};
// ...
exports.event = cards.eventHandler();
exports.event.path().on('broadcast', (cx, [channel, data]) => {
console.log('received broadcast event', channel, data);
});
Siehe cards cardlet registrieren.
Zur Illustration der Konzepte der vorherigen Abschnitte folgt ein Beispiel für einen cardlet-Handler mit internem Zustand (Anzahl Klicks auf OK), Ereignisbehandlung, Modifikationen und selbst ausgelösten Ereignissen:
let cards = require('/agorum/roi/customers/agorum.cards/js/cards');
// build() and event handlers are called outside the UI thread
let build = (cx, def) => {
// the cx.meta field is saved alongside the built cardlet and can be used in event handlers
cx.meta = {
count: 0
};
return {
type: 'agorum.card',
items: [
{
type: 'agorum.horizontal',
items: [
{
type: 'agorum.img',
icon: def.icon,
size: 32
},
{
type: 'agorum.display',
name: 'display',
text: def.text,
size: 'l'
}
]
},
{
type: 'agorum.horizontal',
name: 'buttons',
items: [
{
type: 'agorum.button',
name: 'ok',
text: 'OK'
},
{
type: 'agorum.button',
name: 'cancel',
text: 'Cancel'
}
]
}
]
};
};
let event = cards.eventHandler();
event.path('buttons', 'ok').on('elementClicked', (cx, param) => {
// increase the number of clicks
++cx.meta.count;
// replace the OK button to change its text
cx.replace('buttons', 'ok', {
type: 'agorum.button',
name: 'ok',
text: 'OK (' + cx.meta.count + ')'
});
// fire an event that can be handled by the containing cardlet
cx.fire('ok', cx.meta.count);
});
event.path('buttons', 'cancel').on('elementClicked', (cx, param) => {
// reset the number of clicks
cx.meta.count = 0;
// replace the OK button to reset its text
cx.replace('buttons', 'ok', {
type: 'agorum.button',
name: 'ok',
text: 'OK'
});
// fire an event that can be handled by the containing cardlet
cx.fire('cancel');
});
module.exports = {
build: build,
event: event
};
Registrieren Sie diesen cardlet-Handler etwa als beispiel.paket.mein.cardlet, können Sie ihn etwa in einem aguila-Skript verwenden:
let aguila = require('common/aguila');
let widget = aguila.create({
type: 'agorum.cards.view',
width: 400,
height: 200
});
widget.replace({
type: 'beispiel.paket.mein.cardlet',
text: 'Beispieltext\nZeile 2',
icon: 'mdi:warning;color=FireBrick'
});
widget
.on('ok', count => {
console.log('ok', count);
})
.on('cancel', () => {
console.log('cancel');
});
widget;
Das System leitet die durch das cardlet ausgelösten cardlet-Ereignisse ok und cancel automatisch inklusive ihrer Parameter als aguila-Ereignisse weiter, wenn sie nicht von einem cardlet-Handler behandelt werden.