agorum.composite/message-Modul

Dieses Modul bietet verschiedene Arten von Message-Boxen. Sie können die Message-Boxen so gestalten, dass Benutzer zum Bestätigen und Schließen des Dialogs die Enter-Taste und zum Abbrechen und Schließen die Escape-Taste verwenden können.

Verwendung

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');

Funktionen

alert

Zeigt einen Hinweistext mit einer Überschrift.

 

Beispielhafter Code zur Abbildung

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');

message.alert('Alert', 'This is the text');

Rückmeldung beim Schließen

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');

message.alert('Alert', 'This is the text').then(state => {
  // wird aufgerufen, wenn die Meldung geschlossen wurde
});

Optionale Breite mitgeben

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');

message.alert('Alert', 'This is the text', 500); // Breite liegt im Standard bei 300

Im then-Teil liefert das System als Parameter einen Zustand zurück, je nachdem, was der Benutzer angeklickt hat:

Zustand	Wert	Beschreibung
state	true	OK oder die Enter-Taste wurde gedrückt.
state	undefined	Fenster wurde geschlossen (mit X oder Escape-Taste).

alertHtml

Zeigt einen Hinweistext mit einer Überschrift.

• Der Text kann HTML beinhalten.
• Sonstige Verwendung siehe Funktion alert.

 

 

Beispielhafter Code zur Abbildung

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');

message.alertHtml('Alert', 'This is the html <b>text</b>');

confirm

Zeigt einen Hinweistext mit einer Überschriftund bietet 2 Schaltflächen für Ja /Nein.

 

Beispielhafter Code zur Abbildung

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');

message.confirm('Confirm', 'Press any button').then(state => {
  console.log('button is pressed: ' + state);
});

Im then-Teil liefert das System als Parameter einen Zustand zurück, je nachdem, was der Benutzer angeklickt hat:

Zustand	Wert	Beschreibung
state	true	Ja oder die Enter-Taste wurde gedrückt.
state	false	Nein wurde gedrückt.
state	undefined	Fenster wurde geschlossen (mit X oder Escape-Taste).

prompt

Zeigt einen Hinweistext mit einer Überschrift und bietet ein Text-Eingabefeld sowie die Schaltflächen OK und Abbrechen.

 

Beispielhafter Code zur Abbildung

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');

message.prompt('Prompt', 'Please input some text', 'pre-filled text').then(input => {
  console.log('text input: ' + input);
});

Als Ergebnis des Promises können Sie im then-Teil die Eingabe auswerten:

Eingabe	Wert	Beschreibung
input	<eingegebener Text>	Die Eingabetaste oder OK wurde gedrückt.
input	false	Die Escape-Taste oder Abbrechen wurde gedrückt, oder das Fenster wurde geschlossen.

popup

Diese Funktion ermöglicht es Ihnen, benutzerdefinierte Nachrichtenfenster mit verschiedenen Konfigurationsoptionen zu erstellen und anzuzeigen. Dadurch können Sie komplexe Dialoge erstellen.

Aufruf

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');
let myMessage = message.popup('Wichtige Mitteilung');

 

Funktionen

Die folgenden Funktionen stehen zur Verfügung, um die Eigenschaften und das Verhalten des Nachrichtenfensters zu konfigurieren. Alle funktionen können aneinandergereiht werden und geben das Mesage-Objekt zurück.

Funktion	Beschreibung
text	Definiert den Textinhalt der Nachricht.
icon	Definiert das Symbol für das Nachrichtenfenster. Verwenden Sie zum Erstellen der Symbole die Funktion Icon erstellen des agorum core template managers. Folgende Standard-Symbole sind vorhanden: Anzeige Code   message.ICONS.INFO   message.ICONS.HINT   message.ICONS.QUESTION   message.ICONS.CANCEL   message.ICONS.SETTINGS   message.ICONS.SUCCESS   message.ICONS.DANGER   message.ICONS.WARNING
width	Definiert die Breite des Nachrichtenfensters in Pixeln.
element	Fügt ein form-element zur Nachricht hinzu. Sie können die Funktion mehrfach aufrufen. Die form-elemente werden automatisch untereinander angeordnet.
value	Weist der Nachricht einen Wert für die form-elemente zu.
focus	Definiert das Element oder die zu fokussierende Schaltfläche. Optional kann als zweiter Parameter ein Objekt mit start und end übergeben werden, um im fokussierten Textfeld gleichzeitig einen Textbereich zu selektieren.
button	Fügt eine Schaltfläche zur Nachricht hinzu. Sie können die Funktion mehrfach aufrufen. Schaltflächen werden automatisch nebeneinander angeordnet.
accept	Setzt die Schaltfläche Akzeptieren für die Nachricht. Optional kann ein Button-Objekt übergeben werden (siehe button()). Die Schaltfläche wird automatisch fokussiert, sofern focus() nicht verwendet wurde. Sie können die Funktion mehrfach aufrufen. Schaltflächen werden automatisch nebeneinander angeordnet. Nur die erste Schaltfläche wird fokussiert. Diese wird automatisch ausgelöst, wenn Enter gedrückt wird. Zudem wird automatisch eine Validierung der Formular-Felder ausgeführt und die Schaltfläche deaktiviert, wenn die Validierung fehlschlägt.
abort	Setzt die Schaltfläche Abbrechen für die Nachricht. Optional kann ein Button-Objekt übergeben werden (siehe button()). Sie können die Funktion mehrfach aufrufen. Schaltflächen werden automatisch nebeneinander angeordnet. Diese wird automatisch ausgelöst, wenn Escape gedrückt oder das Fenster geschlossen wird.
ok	Fügt die standardmäßige OK-Schaltfläche hinzu. Der Name der Schaltfläche lautet ok.
apply	Fügt die standardmäßige Übernehmen-Schaltfläche hinzu. Der Name der Schaltfläche lautet apply.
cancel	Fügt die standardmäßige Abbrechen-Schaltfläche hinzu. Der Name der Schaltfläche lautet cancel.
close	Fügt die standardmäßige Schließen-Schaltfläche hinzu. Der Name der Schaltfläche lautet close.
yes	Fügt die standardmäßige Ja-Schaltfläche hinzu. Der Name der Schaltfläche lautet yes.
no	Fügt die standardmäßige Nein-Schaltfläche hinzu. Der Name der Schaltfläche lautet no.
delete	Fügt die standardmäßige Löschen-Schaltfläche hinzu. Der Name der Schaltfläche lautet delete.
save	Fügt die standardmäßige Speichern-Schaltfläche hinzu. Der Name der Schaltfläche lautet save.
show	Zeigt die Nachricht als Pop-up an. In der Funktion wird eine Callback-Funktion übergeben, die sowohl den Namen der Schaltfläche als auch die Werte der form-elemente als Parameter enthält. Im Callback kann ein Promise zurückgegeben werden, damit der Dialog so lange offen bleibt, bis der Promise ausgelöst wird, etwa im Rahmen von aguila.fork (siehe Beispiel). Liefert der Callback den Wert true zurück, bleibt der Dialog offen und wird nicht automatisch geschlossen. Während der Callback-Promise läuft, wird das Fenster gesperrt und Benutzerinteraktionen werden blockiert.
modal	Legt fest, ob das Popup sich modal verhält. Ein modales Fenster (modal:true) verhindert, dass der Benutzer andere Fenster oder Bereiche der Anwendung bedient, solange das Popup sichtbar ist.
align	Bestimmt die Ausrichtung/Position des Fensters auf dem Bildschirm. Übergeben wird dazu ein Ausrichtungsobjekt (z. B. { top: 5}), welches steuert, wo das Popup auf dem Bildschirm erscheint.

 

Button-Eigenschaften

Beim Erstellen von benutzerdefinierten Buttons mit button(), accept() oder abort() können folgende Eigenschaften übergeben werden: 

Eigenschaft	Beschreibung
name (string)	Eindeutiger Name der Schaltfläche (erforderlich)
text (string)	Beschriftung der Schaltfläche
icon (string)	Icon für die Schaltfläche
validate (boolean)	Wenn true, wird die Schaltfläche deaktiviert, bis alle Formularfelder valide sind.

Beispiele

Einfache Nachricht erstellen

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');
message.popup('Informationsmeldung').text('Dies ist eine wichtige Information für den Benutzer.').ok().show();

 

 

Nachricht mit mehreren Schaltflächen und einer Callback-Funktion

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');

message
  .popup('Bestätigung erforderlich')
  .text('Möchten Sie die Änderungen speichern?')
  .icon(message.ICONS.QUESTION)
  .save()
  .width(400)
  .button({
    name: 'dontSave',
    text: 'Nicht speichern',
    icon: 'mdi:cancel',
  })
  .cancel()
  .show(buttonName => {
    if (buttonName === 'save') {
      console.log('Änderungen wurden gespeichert.');
    } else if (buttonName === 'dontSave') {
      console.log('Änderungen wurden nicht gespeichert.');
    } else {
      console.log('Vorgang wurde abgebrochen.');
    }
  });

 

 

Umfangreiches Verwendungsbeispiel inklusive Form-Elemente

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');

message
  .popup('Name eingeben')
  .text('Bitte geben Sie einen Namen ein')
  .icon('agorum:circle;color=#0069b5|mdi:edit;color=white;slot=center') // ein Textelement für den Namen hinzufügen
  .element({
    type: 'agorum.composite.form.element.text',
    name: 'name',
    label: 'Neuer Name',
    validation: [
      {
        required: true,
      },
    ],
  }) // add a description element
  .element({
    type: 'agorum.composite.form.element.text',
    name: 'description',
    label: 'Beschreibung',
    validation: [
      {
        required: false,
      },
    ],
  }) // set an initial value for name
  .value({
    name: 'Alter Name',
  }) // den Fokus auf das name-Feld setzen
  .focus('name') // eine Schaltfläche zum Umbenennen hinzufügen, die das Form-Feld validieren soll
  .accept({
    name: 'rename',
    text: 'Umbenennen',
    icon: 'ionicon:checkbox;color=LimeGreen',
    validate: true,
  }) // add a cancel button
  .cancel() // show the popup
  .show((buttonName, value) => {
    // Dieser Callback wird aufgerufen, wenn ein Button gedrückt wird, das Fenster geschlossen oder Escape oder Enter gedrückt wird
    if (buttonName === 'rename') {
      console.log('Umbenennen in ' + value.name + ', Beschreibung: ' + value.description);
    } else if (buttonName === 'cancel') {
      console.log('Vorgang wurde abgebrochen.');
    }
  });

 

 

Beispiel mit Textselektion im fokussierten Feld

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');

message
  .popup('Datei umbenennen')
  .element({
    type: 'agorum.composite.form.element.text',
    name: 'fileName',
    label: 'Dateiname',
  })
  .value({
    fileName: 'dokument.pdf',
  })
  .focus('fileName', { start: 0, end: 8 })
  .accept({
    name: 'rename',
    text: 'Umbenennen',
    validate: true,
  })
  .cancel()
  .show((buttonName, value) => {
    if (buttonName === 'rename') {
      console.log('Neuer Name: ' + value.fileName);
    }
  });

In diesem Beispiel wird das Feld fileName fokussiert und gleichzeitig der Dateiname ohne Endung selektiert (Zeichen 0 bis 8). Der Benutzer kann den selektierten Text sofort durch Tippen ersetzen.

 

 

Beispiel zur Verwendung asynchroner Aufrufe im callback von show()

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');
let aguila = require('common/aguila');

message
  .popup('Langlaufende Aktion')
  .text('Beispiel, mit dem demonstriert wird, dass etwas länger laufen kann im Callback von show.')
  .icon('ionicon:information-circle')
  .save()
  .cancel()
  .show(buttonName => {
    if (buttonName === 'save') {
      return aguila.fork(() => {
        // asynchrone Funktion. Wird der Promise von Fork als Return-Wert zurückgegeben, wartet die Maske, bis
        // der Fork fertig ist, bevor das Fenster geschlossen wird.
        // Dann kann zum Beispiel auch auf Fehler reagiert werden, ohne, dass der Dialog geschlossen wird.

        throw new Error('Ein Beispiel-Fehler');
      });
    } else {
      console.log('Vorgang wurde abgebrochen.');
    }
  });

 

 

Beispiel für das Offenlassen von Dialogen nach dem Ausführen einer Aktion

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');
let aguila = require('common/aguila');

message
  .popup('Langlaufende Aktion')
  .text('Beispiel, mit dem demonstriert wird, dass etwas länger laufen kann im Callback von show.')
  .icon(message.ICONS.SUCCESS)
  .width(800)
  .button({
    name: 'error',
    text: 'Erzeuge Fehler',
  })
  .button({
    name: 'stayOpen',
    text: 'Fenster offen lassen mit fork',
  })
  .button({
    name: 'stayOpen2',
    text: 'Fenster offen lassen',
  })
  .save()
  .cancel()
  .show(buttonName => {
    if (buttonName === 'error') {
      return aguila.fork(() => {
        // asynchrone Funktion. Wird der Promise von Fork als Return-Wert zurückgegeben, wartet die Maske, bis
        // der Fork fertig ist, bevor das Fenster geschlossen wird.
        // Dann kann zum Beispiel auch auf Fehler reagiert werden, ohne, dass der Dialog geschlossen wird.

        throw new Error('Ein Beispiel-Fehler');
      });
    } else if (buttonName === 'stayOpen') {
      return aguila.fork(() => {
        // wenn in der Callback-Funktion true zurückgeliefert wird, bleibt das Fenster offen
        console.log('Fenster offen lassen mit aguila.fork');
        return true;
      });
    } else if (buttonName === 'stayOpen2') {
      // wenn in der Callback-Funktion true zurückgeliefert wird, bleibt das Fenster offen
      console.log('Fenster offen lassen');
      return true;
    } else if (buttonName === 'save') {
      console.log('Speichen...');
    } else {
      console.log('Vorgang wurde abgebrochen.');
    }
  });

 

Beispiel: Warnung als zweites Fenster über einem Dialog

Der Callback des ersten Dialogs gibt ein Promise zurück. Dadurch bleibt der Dialog offen und gesperrt. Das zweite Fenster löst das Promise auf. Mit resolve(true) bleibt der erste Dialog offen. Löst das Promise mit einem anderen Wert als true auf, schließt sich der Dialog, sobald das Promise fertig ist.

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');
let aguila = require('common/aguila');

let confirmWarning = resolve =>
  message
    .popup('Warnung')
    .icon(message.ICONS.WARNING)
    .text('Es gibt schon einen Eintrag. Möchten Sie trotzdem speichern?')
    .ok({ name: 'proceed', text: 'Trotzdem speichern' })
    .cancel({ name: 'back', text: 'Zurück' })
    .show(buttonName => {
      if (buttonName === 'proceed') {
        // der erste Dialog bleibt gesperrt, bis der Fork fertig ist, und schließt sich danach
        resolve(aguila.fork(() => console.log('Speichern ...')));
      } else {
        // true lässt den ersten Dialog offen
        resolve(true);
      }
    });

message
  .popup('Eintrag anlegen')
  .icon(message.ICONS.INFO)
  .element({ type: 'agorum.composite.form.element.text', name: 'name', label: 'Name' })
  .save()
  .cancel()
  .show(buttonName => {
    if (buttonName === 'save') {
      // ein zurückgegebenes Promise hält den Dialog offen und gesperrt
      return new Promise(resolve => confirmWarning(resolve));
    }
  });

Beispiel mit allen Standard-Buttons

let message = require('/agorum/roi/customers/agorum.composite/js/lib/message');
message
  .popup('Popup-Dialog')
  .text('Das ist ein Beispiel für die Standard-Buttons.')
  .icon(message.ICONS.SUCCESS)
  .width(700)
  .modal(true)
  .align({ left: 20, top: 5 })
  .cancel()
  .ok()
  .apply()
  .yes()
  .no()
  .delete()
  .save()
  .close()
  .show();