Eigene cardlets erstellen 

Sie können einen eigenen cardlet-Typ erstellen, etwa wenn Sie Teile einer Ansicht wiederverwenden möchten oder wenn eine eigene Ereignisbehandlung erforderlich ist.

cardlet-Handler

---

Ein cardlet-Handler ist eine JavaScript-Bibliothek, die die Funktionen build und event exportiert.

build

Das System ruft diese Funktion auf, wenn ein agorum.cards.view-Widget ein cardlet des zugehörigen Typs darstellen soll.

• Die Funktion erhält als Parameter ihre zu erzeugenden cardlets und die Definition, die zur Erstellung verwendet wurde.
• Die Funktion erwartet als Rückgabewert das erstellte cardlet.

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
};

def

Übergibt zusätzliche Parameter, die für deren Darstellung relevant sind.

event

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:

• den cardlet-Kontext
• den Namen des Ereignis-Typs
• den relativen Pfad zu dem Element, auf dem das Ereignis ausgelöst wurde
• einen eventuellen Parameter, der zu diesem Ereignis gehört

let event = (cx, type, path, param) => {
 // ...
};

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.

cardlet-Kontext

---

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.

Allgemein

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.

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'
});

remove

Entfernt ein Element aus der cardlet-Struktur.

cx.remove(<path>);

replace

Entfernt ein Element aus der cardlet-Struktur und ersetzt es durch ein neues.

cx.replace(<path>, <def>);

append

Fügt dem Zielelement ein neues Unterelement hinzu.

cx.append(<path>, <def>);

insert

Fügt ein neues Element vor dem Zielelement ein.

cx.insert(<path>, <def>);

fire

Löst ein benutzerdefiniertes Ereignis aus, das von einem übergeordneten cardlet-Handler behandelt werden kann.

cx.fire(<type>, <param>);

sub

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>);

cancel

Hebt alle bisher bestehenden Broadcast-Registrierungen auf.

cx.sub(<channels>);

Standard-Ereignisse

---

elementClicked, elementRightClicked, elementMiddleClicked, elementDblClicked

Löst aus, sobald ein Benutzer auf Elemente klickt, die Sie als interactive: true oder selectable: true definiert haben.

linkClicked, linkRightClicked, linkMiddleClicked, linkDblClicked

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>

broadcast

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);
});

Einen cardlet-Handler anlegen und registrieren

Siehe cards cardlet registrieren.

Einen cardlet-Handler implementieren

---

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.