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: {
      // 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 connect and persist properties
setImmediate(() => {
  let state = userSettings.bucket(widget);

  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. 

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.

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