JavaScript-Bibliothek agorum.composite.user-settings

Mit user-settings können Sie benutzerspezifische Einstellungen Ihres Widgets, wie beispielsweise UI-Zustände, speichern und beim erneuten Öffnen automatisch wiederherstellen. Dadurch erhält jeder Anwender das Widget stets in seinem zuletzt genutzten Zustand.

Die Persistenz erfolgt, indem Sie jede zu speichernde Einstellung als Property am Widget mit passendem Event modellieren und diese Property deklarativ mit der Bibliothek verbinden.

Hinweis: Die Bibliothek user-settings ist ausschließlich für den Einsatz im UI-Thread konzipiert. Sowohl die Funktion bucket() als auch alle Methoden des zurückgegebenen Bucket-Objekts dürfen nur innerhalb von aguila-Widget-Skripten aufgerufen werden.

Ein Aufruf außerhalb des UI-Threads (z. B. in Backend-Skripten, Workern oder serverseitigen Verarbeitungen) führt zu Fehlern, da intern UI-spezifische Mechanismen verwendet werden.

Verwendung

Binden Sie die Bibliothek stets am Anfang eines Skripts ein:

let userSettings = require('/agorum/roi/customers/agorum.composite/js/user-settings');

Vorgehensweise zum Persistieren von Benutzereinstellungen im Widget

user-settings Bibliothek einbinden
Widget als Applikation oder Komponente registrieren
Persistierbare Properties mit zugehörigem Change-Event am Widget anlegen
Einen Bucket für das Widget erzeugen
Properties mittels persist an den Bucket binden
Properties mit der UI synchronisieren (z. B. Forms)

Verwendungsbeispiel: Persistenter Checkbox-Zustand und Widget-Dimensionen

In diesem Beispiel wird der Zustand eines Formulars bzw. dessen Größe und der Zustand einer Checkbox (angehakt, nicht angehakt) persistiert und dem Benutzer beim nächsten Öffnen wie zuvor angezeigt.

/* global parameters */

let aguila = require('common/aguila');
let userSettings = require('/agorum/roi/customers/agorum.composite/js/user-settings');

let widget = aguila.create({
  properties: ['someState'],
  type: 'agorum.border',
  height: 500,
  width: 500,
  docked: {
    center: {
      title: 'center',
      name: 'form',
      type: 'agorum.composite.form.basic',
      elements: [
        {
          name: 'someState',
          type: 'agorum.composite.form.element.boolean',
          text: 'Lorem ipsum',
        },
      ],
    },
    east: {
      // TODO
      properties: ['myProperty'],
      name: 'right',
      title: 'right',
      type: 'agorum.vbox',
      width: 200,
      collapsible: true,
    },
  },
});

// register application in namespace
// userSettings.application(widget, parameters.type);
userSettings.application(widget, 'agorum.test.user.settings');
// .component()

// get bucket and persist properties
// IMPORTANT: Only call from the UI thread.
setImmediate(() => {
  let state = userSettings.bucket(widget);

// all persist calls must also be made on the UI thread
  state.persist('width', widget, 'width');
  state.persist('height', widget, 'height');
  state.persist('someState', widget, 'someState');
  state.persist('right.width', widget.down('right'), 'width');
  state.persist('right.collapsed', widget.down('right'), 'collapsed');
});

// ...

// synchronize UI logic and properties
let form = widget.down('form');

widget.on('someStateChanged', someState => form.set('someState.value', someState));
form.on('valueChanged', value => (widget.someState = value.someState));

widget;

Funktionen

application

Die Funktion application registriert ein Hauptwidget als Anwendungsnamensraum.

Syntax

userSettings.application(widget, name);

Parameter

Parameter	Beschreibung	Pflicht	Standard
widget	Das zu registrierende Hauptwidget	ja	-
name	Eindeutiger Name des Anwendungsnamensraums	ja	-

Beispiel

let userSettings = require('/agorum/roi/customers/agorum.composite/js/user-settings');
userSettings.application(widget, 'agorum.test.user.settings');

component

Die Funktion component registriert ein Subwidget als Komponente innerhalb eines Anwendungsnamensraums.

Syntax

userSettings.component(widget, name);

Parameter

Parameter	Beschreibung	Pflicht	Standard
widget	Das zu registrierende Hauptwidget	ja	-
name	Eindeutiger Name des Anwendungsnamensraums	ja	-

Beispiel

let userSettings = require('/agorum/roi/customers/agorum.composite/js/user-settings');
userSettings.component(widget, 'agorum.test.user.settings');

bucket

Die Funktion bucket erzeugt einen Bucket, der die persistierten Einstellungen für das konkrete Widget (bzw, Komponentenscope) kapselt.

Achtung: Die Funktion bucket() darf ausschließlich im UI-Thread aufgerufen werden. Ein Aufruf außerhalb des UI-Threads (z. B. in einem Backend-Skript oder Worker) führt zu Fehlern, da die Funktion intern UI-spezifische Mechanismen verwendet. Gleiches gilt für alle Methoden des zurückgegebenen Bucket-Objekts.
Stellen Sie sicher, dass bucket() nur innerhalb von aguila-Widget-Skripten aufgerufen wird.

Syntax

let state = userSettings.bucket(widget);

Parameter

Parameter	Beschreibung	Pflicht	Standard
widget	Das Widget, für dessen Scope ein Bucket erstellt werden soll.	ja	–

Beispiel

let userSettings = require('/agorum/roi/customers/agorum.composite/js/user-settings');
let state = userSettings.bucket(widget);

Rückgabe

Ein Bucket-Objekt mit verschiedenen Funktionen, insbesondere der Funktion persist.

persist

Die Funktion persist bindet eine Property eines Widgets persistent an einen Bucket-Schlüssel.

Wichtig:

Die zugehörige Property muss beim Wertwechsel ein Changed-Event auslösen.
Diese Funktion darf nur im UI-Thread aufgerufen werden, da sie auf dem Bucket-Objekt operiert und intern UI-spezifische Mechanismen verwendet.

Syntax

state.persist(key, widget, propertyName);

Parameter

Parameter	Beschreibung	Pflicht	Standard
key	Schlüssel der zu persistierenden Einstellung	ja	–
widget	Das Widget, dessen Property persistiert werden soll.	ja	-
propertyName	Name der Property (String), mit passendem Changed-Event	ja	-

Beispiel

let userSettings = require('/agorum/roi/customers/agorum.composite/js/user-settings');
let state = userSettings.bucket(widget);

state.persist('width', widget, 'width');