JavaScript-Bibliothek agorum.cards/js/cards

Diese JavaScript-Bibliothek dient zur Unterstützung der Entwicklung von cardlets und decorators.

Verwendung

---

Diese Bibliothek binden Sie stets am Anfang eines Skripts ein:

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

Funktionen

---

eventHandler

Erzeugt einen standardisierten Ereignis-Handler, der als Funktion event eines cardlet-Handlers verwendet werden kann.

Der Cardlet-Handler nimmt alle einkommenden Ereignisse des cardlets entgegen und leitet sie an je Zielelement und Ereignistyp registrierte Funktionen weiter.

Syntax

let event = cards.eventHandler();

Das zurückgegebene Objekt event bietet folgende Funktionen:

path

Leitet die Registrierung einer Funktion als Handler für ein spezifisches Ereignis ein.

Syntax

event.path(<path>).on(<type>, <handler>);

Parameter	Beschreibung	Pflicht
path	Definiert eine Folge von Zeichenketten-Parametern, die einschränken, auf welche Zielelemente der Handler reagiert. Der Handler wird nur aufgerufen, wenn der Pfad bis zu einem Element all diese Namen enthält (siehe Eigene cardlets erstellen).	nein
type	Definiert den Namen des Ereignistyps, auf den der Handler reagiert.	ja
handler	Definiert die Funktion, die als Handler registriert werden soll und für passende Ereignisse aufgerufen wird.	ja

Tritt ein passendes Ereignis ein, ruft das System die Handler-Funktion mit dem cardlet-Kontext (siehe Eigene cardlets erstellen) und dem (optionalen) Parameter des Ereignisses auf.

Beispiel für einen Schaltflächen-Handler, der auf Ereignisse des Typs elementClicked unterhalb des Pfads [ 'buttons', 'ok' ] reagiert:

event.path('buttons', 'ok').on('elementClicked', (cx, param) => {
  // ...
});

link

Definiert Link-Typen. HTML-Hyperlinks und interaktive Elemente gelten als Links, deren Namen diesem Schema entsprechen:

<Link-Typ>:<Link-Parameter>

• Der Link-Typ ist eine Zeichenkette, die aus Kleinbuchstaben und Punkten bestehen darf.
• Bei Verwendung von HTML-Hyperlinks dürfen die Link-Parameter nur Zeichen enthalten, die in HTML-Attributen erlaubt sind.
• Bei Bedarf kann die Funktion escape der Bibliothek common/html verwendet werden.

Folgende Link-Typen sind vordefiniert:

Link-Typ	Beschreibung
object:<id/ref>	Verweist auf ein agorum-Objekt und bietet das Kontextmenü (Rechtsklick) und Öffnen-Aktion (Linksklick) an.
action:<action>:<parent>:<id1>:<id2>:...	Führt bei einem Linksklick die als action angegebene Aktion mit den als parent und idX angegebenen Objekten als folder und objects aus.
call:<service>:<args>	Ruft bei einem Linksklick den als service registrierten Dienst mit den Argumenten args auf.

Weitere Link-Typen definieren

Sie können über die Funktion link weitere Link-Typen definieren, die innerhalb des aktuellen cardlets unterstützt werden sollen.

Syntax

event.link(<type>, <handler>);

Parameter	Beschreibung	Pflicht
type	Definiert den Namen des Link-Typs, auf den der Handler reagiert.	ja
handler	Definiert die Funktion, die das System als Handler registriert und für passende Links aufruft.	ja

Klickt ein Benutzer einen derart registrierter Link an, ruft das System den hier registrierten Handler mit dem cardlet-Kontext (siehe Eigene cardlets erstellen), dem Link-Parameter und dem Namen der verwendeten Maustaste (left, right oder middle) auf.

Beispiel für einen Link-Handler, der auf Links des Typs agorum.log reagiert:

event.link('agorum.log', (cx, params, button) => {
  console.log('agorum.log', params, button);
});

Beispiel für die Verwendung eines Links in HTML:

<a name="agorum.log:Hallo Welt!">Test-Link</a>

Beispiel für die Verwendung eines Links in einem Element:

{
  type: 'agorum.chip',
  name: 'agorum.log:Hallo Welt!',
  text: 'Test-Link'
}

Beispiel für einen Objekt-Link in HTML:

Hier ist das gesuchte <a name="object:13bc3565-2a2e-4764-b9ec-e61944a3ac73">Dokument</a>.

link

Erstellt einen Objekt-Link aus einem Objekt, einer Objekt-ID oder einer Objektreferenz.

Syntax

let name = cards.link(<object/id/ref>);

Parameter

Sie können als Parameter object/ref entweder direkt ein agorum-Objekt übergeben oder eine Beschreibung eines agorum-Objekts in Form einer Objektreferenz. Letzteres verwenden Sie, wenn weder das zugehörige Objekt noch eine ID davon vorliegt, aber etwa eine Beschreibung, die in einer Indexsuche verwendet werden kann, um das Objekt zu finden. In diesem Fall wird das referenzierte Objekt erst bei Betätigung des Links gesucht, um unnötige Verzögerungen bei der Darstellung des cardlets zu vermeiden.

Für die Auflösung solcher Objektreferenzen sind resolver zuständig. Mitgeliefert ist der resolver agorum.search, der eine Objektreferenz per Indexsuche ermöglicht.

Ein Beispiel für die Verwendung einer Objektreferenz mit resolver agorum.search wäre:

cards.link({
  resolver: 'agorum.search',
  query: 'identifier:Lieferantenakte lieferantennummer:123456'
});

Bei einem Rechtsklick auf einen solchen Link würde die Lieferantenakte mit Lieferantennummer 123456 gesucht und deren Kontextmenü angezeigt werden.

Rückgabewerte

Sie erhalten eine Zeichenkette zurück, die Sie als Name eines HTML-Hyperlinks oder als Name eines Elements verwenden können.

resolve

Löst die übergebene Objektreferenz in eine Objekt-ID (typischerweise die UUID des Objekts) auf.

Diese Funktion ist hauptsächlich für die interne Anwendung bei agorum gedacht.

Syntax

let id = cards.resolve(<ref>);

Parameter

Übergeben Sie als Parameter die Objektreferenz, wie sie für einen Link verwendet werden könnte.

Rückgabewerte

Sie erhalten den Rückgabewert des aufgerufenen resolvers, im Regelfall die UUID des gefundenen Objekts.