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.

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

1. user-settings Bibliothek einbinden
2. Widget als Applikation oder Komponente registrieren 
3. Persistierbare Properties mit zugehörigem Change-Event am Widget anlegen
4. Einen Bucket für das Widget erzeugen
5. Properties mittels persist an den Bucket binden
6. 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: {
      properties: ['myProperty'],
      name: 'right',
      title: 'right',
      type: 'agorum.vbox',
      width: 200,
      collapsible: true,
    },
  },
});

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

// 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 Subwidget	ja	-
name	Eindeutiger Name der Komponente innerhalb des Anwendungsnamensraums	ja	-

 

Beispiel

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

bucket 

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

 

Syntax

let state = userSettings.bucket(widget);
let state = userSettings.bucket(widget, true); // standalone-Modus

 

Parameter

Parameter	Beschreibung	Pflicht	Standard
widget	Das Widget, für dessen Scope ein Bucket erstellt werden soll.	ja	–
standalone	Aktiviert den standalone-Modus. Wenn true, werden Einstellungen unter der innersten Applikation gespeichert statt unter der äußersten. Details siehe Abschnitt Modus: Standard vs. standalone.	nein	false

 

Beispiel

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

// Standard-Modus: Einstellungen werden unter der äußersten Applikation gespeichert
let state = userSettings.bucket(widget);

// Standalone-Modus: Einstellungen werden unter der innersten Applikation gespeichert
let state = userSettings.bucket(widget, true);

 

Rückgabe

Ein Bucket-Objekt mit folgenden Funktionen:

Funktion	Beschreibung
persist(key, widget, propertyName)	Bindet eine Widget-Property persistent an einen Bucket-Schlüssel (siehe unten).
get(key)	Liest den gespeicherten Wert für den angegebenen Schlüssel.
set(key, value)	Setzt einen Wert für den angegebenen Schlüssel. Gibt ein Promise zurück, das nach dem Schreiben aufgelöst wird.
clear(subPrefix)	Löscht gespeicherte Einstellungen. Ohne Parameter werden alle Einstellungen des Buckets gelöscht. Mit subPrefix werden nur Schlüssel gelöscht, die mit dem angegebenen Präfix beginnen.

 

Modus: Standard vs. standalone

Beim Erzeugen eines Buckets bestimmt der Parameter standalone, unter welcher Applikation die Einstellungen gespeichert werden. Dies ist relevant, wenn Widgets verschachtelt in mehreren Applikationen laufen, z. B. wenn ein eigenes Widget als Tab innerhalb des Home-Bereichs geöffnet wird.

 

Hintergrund

Jedes Widget, das mit application() registriert wird, bildet einen Anwendungsnamensraum. Wird ein Widget innerhalb einer anderen Applikation eingebettet (z. B. als Tab im Home-Bereich), entsteht eine Kette von Namensraum-Knoten:

Home-Applikation (außen) → Meine-Applikation (innen) → Komponente

Beim Abruf eines Buckets muss das System entscheiden, welcher Applikationsknoten als Speicherort dient:

 

Modus	Verhalten	Typischer Einsatz
Standard bucket(widget)	Verwendet die äußerste Applikation als Speicherort. Alle inneren Applikationen und Komponenten werden als Offset-Pfad angehängt.	Widgets, die fest in eine übergeordnete Applikation integriert sind und deren Einstellungen im Kontext der äußeren Applikation gespeichert werden sollen.
standalone bucket(widget, true)	Verwendet die innerste Applikation als Speicherort. Nur nachfolgende Komponenten werden als Offset-Pfad angehängt.	Widgets, die eigenständig funktionieren und ihre Einstellungen unabhängig von der umgebenden Applikation speichern sollen – z. B. wenn ein Widget sowohl als eigenständige Applikation als auch als Tab innerhalb des Home-Bereichs geöffnet werden kann.

 

Beispiel: Verschachtelte Applikationen

Angenommen, folgende Namensraum-Kette existiert:

agorum.home (application) → my.app (application) → my.sidebar (component)

Modus	Speicherort (package)	Offset
bucket(widget)	agorum.home	my.app.my.sidebar
bucket(widget, true)	my.app	my.sidebar

 

Im standalone-Modus werden die Einstellungen also direkt unter my.app abgelegt. Dadurch bleiben sie identisch, egal ob das Widget eigenständig oder eingebettet in einer anderen Applikation läuft.

 

Verwendungsbeispiel: standalone-Modus

/* global parameters */

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

let widget = aguila.create({
  properties: ['sidebarCollapsed'],
  type: 'agorum.border',
  height: 500,
  width: 800,
  docked: {
    center: {
      name: 'content',
      type: 'agorum.vbox',
    },
    east: {
      name: 'sidebar',
      type: 'agorum.vbox',
      width: 250,
      collapsible: true,
    },
  },
});

// Widget als eigenständige Applikation registrieren
userSettings.application(widget, 'my.app');

setImmediate(() => {
  // standalone: true → Einstellungen werden unter 'my.app' gespeichert,
  // auch wenn das Widget innerhalb einer anderen Applikation (z. B. Home) läuft
  let state = userSettings.bucket(widget, true);

  state.persist('sidebar.width', widget.down('sidebar'), 'width');
  state.persist('sidebar.collapsed', widget.down('sidebar'), 'collapsed');
});

widget;

 

persist 

Die Funktion persist bindet eine Property eines Widgets persistent an einen Bucket-Schlüssel. Beim Erzeugen des Buckets wird der gespeicherte Wert automatisch auf die Property geschrieben. Bei jeder Änderung der Property wird der neue Wert automatisch persistiert.

 

Syntax

state.persist(key, widget, propertyName);

 

Parameter

Parameter	Beschreibung	Pflicht	Standard
key	Schlüssel, unter dem die Einstellung im Bucket gespeichert wird.	ja	–
widget	Das Widget, dessen Property persistiert werden soll.	ja	–
propertyName	Name der Property am Widget, die persistiert werden soll. Die Property muss ein Changed-Event auslösen.	nein	key

 

Beispiel

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

// Expliziter Property-Name
state.persist('sidebar.width', widget.down('sidebar'), 'width');

// Property-Name entspricht dem Key → propertyName kann weggelassen werden
state.persist('width', widget);

 

get

Die Funktion get liest den gespeicherten Wert für einen Schlüssel aus dem Bucket.

 

Syntax

let value = state.get(key);

 

Parameter

Parameter	Beschreibung	Pflicht	Standard
key	Schlüssel der zu lesenden Einstellung.	ja	–

 

Rückgabe

Der gespeicherte Wert oder undefined, falls kein Wert vorhanden ist.

 

Beispiel

let state = userSettings.bucket(widget);
let currentWidth = state.get('sidebar.width');

 

set

Die Funktion set speichert einen Wert unter einem Schlüssel im Bucket. Die Schreiboperation erfolgt verzögert und gebündelt, um unnötige Schreibvorgänge zu vermeiden.

 

Syntax

state.set(key, value);

 

Parameter

Parameter	Beschreibung	Pflicht	Standard
key	Schlüssel der zu speichernden Einstellung.	ja	–
value	Der zu speichernde Wert. Mit undefined wird der Schlüssel gelöscht.	ja	–

 

Rückgabe

Ein Promise, das aufgelöst wird, sobald der Wert erfolgreich geschrieben wurde.

 

Beispiel

let state = userSettings.bucket(widget);
state.set('sidebar.width', 300);

 

clear

Die Funktion clear löscht gespeicherte Einstellungen aus dem Bucket.

 

Syntax

state.clear();
state.clear(subPrefix);

 

Parameter

Parameter	Beschreibung	Pflicht	Standard
subPrefix	Optionaler Präfix. Wenn angegeben, werden nur Schlüssel gelöscht, die mit diesem Präfix beginnen. Ohne Parameter werden alle Einstellungen des Buckets gelöscht.	nein	–

 

Beispiel

let state = userSettings.bucket(widget);

// Nur Einstellungen mit Präfix 'sidebar' löschen
state.clear('sidebar');

// Alle Einstellungen des Buckets löschen
state.clear();

 

Rückgabe

Beim Aufruf ohne Parameter gibt clear() ein Promise zurück, das aufgelöst wird, sobald alle Einstellungen gelöscht wurden. Beim Aufruf mit subPrefix werden die betroffenen Schlüssel über set entfernt (ebenfalls verzögert geschrieben).