Werte durchreichen/ein Widget kapseln (agorum.composite.wrapper)

Dieses Widget dient dazu, ein- und ausgehende Werte eines anderen Widgets an ein inneres Widget weiterzugeben, oder umgekehrt, die Werte des inneren Widgets über das Wrapper-Widget nach außen weiterzugeben. Der Wrapper funktioniert im Prinzip wie ein Adapter.

Verwendung

Sie verwenden das Wrapper-Widget, um ein anderes aguila-Widget wie in diesem Beispiel für Form-Elemente nach innen zu legen und dadurch die Möglichkeit zu gewinnen, Werte von oder nach außen weiterzugeben.

let aguila = require('common/aguila');

/* widget: sample wrapper */

let widget = aguila.create({
  type: 'agorum.composite.wrapper',
  properties: ['value'],
  independent: true,
  wrap: {
    type: 'agorum.composite.form.basic',
    name: 'form',
    elements: [
      {
        type: 'agorum.composite.form.element.text',
        name: 'field1',
      },
      {
        type: 'agorum.composite.form.element.text',
        name: 'field2',
      },
    ],
  },
});

let form = widget.down('form');

widget
  .incoming('value', value => {
    // Verwenden des von außen kommenden Werts für die inneren Felder
    if (value) {
      let split = value.split(';');
      form.value = {
        field1: split[0],
        field2: split[1],
      };
    }
  })

  .outgoing('value', (/* value */) => {
    // Erstellen des Werts, der nach außen gegeben wird
    widget.value = form.get('field1.value') + ';' + form.get('field2.value');
  });

//widget.value = 'abc;def';

widget;

Auf Property-Änderungen reagieren

Sie können auf Änderungen der Wrapper-Properties reagieren, indem Sie Event-Listener registrieren und das innere Widget entsprechend aktualisieren.

let inner = widget.down('inner');

widget.on('readOnlyChanged', () => {
  inner.readOnly = widget.readOnly || widget.viewMode;
});

widget.on('disabledChanged', () => {
  inner.disabled = widget.disabled || widget.disabledForm;
});

Parameter

Parameter	Beschreibung	Mögliche Werte
independent	Macht das Wrapper-Widget unabhängig vom gekapselten Widget, indem die Properties, Incoming und Outgoing Werte gezielt angegeben werden müssen und nicht vom inneren Widget übernommen werden. Dadurch kann verhindert werden, dass alle Eigenschaften, etwa einer Form, verfügbar sind.	Boolescher Wert, Standardwert false
properties	Legt die Property-Werte des inneren Widgets fest, die an den Wrapper und nach außen durchgereicht werden sollen.	Typischerweise wird das Property value nach außen durchgereicht. let widget = aguila.create({ type: 'agorum.composite.wrapper', properties: [ 'value' ], wrap: { type: 'agorum.composite.form.basic' } }); Sie können auch wie folgt mehrere Properties gleichzeitig definieren, die das Verhalten des gekapselten Widgets steuern: properties: ['readOnly', 'viewMode', 'disabled', 'disabledForm']
target	Definiert optional ein vom inneren, gekapselten Widget abweichendes Widget, mit dem Properties synchronisiert werden sollen.	target: 'output',
wrap	Definiert das innere Widget. Pflichtfeld.	Widget-Definition des gekapselten Widgets. Für eine Liste der Widgets siehe agorum core aguila.
wrapper	Legt optional fest, welcher Typ von Container-Widget verwendet werden soll. Im Standard ist das agorum.vbox, aber je nach Situation kann ein anderer Container-Typ besser geeignet sein.	Ein beliebiger Container-Typ, wie agorum.single oder agorum.hbox.

Funktionen

down(name)

Ermöglicht den Zugriff auf das innere, gekapselte Widget anhand seines Namens.

name: Der Name des inneren Widgets, wie er in der wrap-Definition unter name angegeben wurde.

Rückgabewert: Das referenzierte innere Widget-Objekt, auf dem dann Properties gesetzt oder Methoden aufgerufen werden können.

Verwendung: Diese Methode ist notwendig, um vom Wrapper-Widget auf das gekapselte Widget zuzugreifen und dessen Properties oder Methoden zu manipulieren.

Beispiel:

let aguila = require('common/aguila');

let widget = aguila.create({
  type: 'agorum.composite.wrapper',
  wrap: {
    name: 'inner',
    type: 'agorum.textInput',
  },
});

// Zugriff auf das innere Widget
let inner = widget.down('inner');

// Jetzt können Properties des inneren Widgets gesetzt werden
inner.value = 'Ein Textwert';
inner.readOnly = true;

Beispiel mit Form:

let widget = aguila.create({
  type: 'agorum.composite.wrapper',
  wrap: {
    type: 'agorum.composite.form.basic',
    name: 'form',
    elements: [
      {
        type: 'agorum.composite.form.element.text',
        name: 'field1',
      },
    ],
  },
});

let form = widget.down('form');

// Werte der Form setzen
form.value = { field1: 'Hallo' };

Hinweis: Der in down() verwendete Name muss exakt mit dem name-Parameter in der wrap-Definition übereinstimmen. Ohne Namen-Angabe in der wrap-Definition kann das Widget nicht über down() referenziert werden.

Tipp: Speichern Sie das Ergebnis von down() in einer Variable, wenn Sie häufig auf das innere Widget zugreifen möchten. Dies verbessert die Lesbarkeit und Performance Ihres Codes.

incoming(property, handler)

Registriert für die angegebene Property einen Handler, der die Konvertierung von externen Werten (auf dem agorum.composite.wrapper-Widget) in interne Werte (auf dem gekapselten Widget) vornimmt. Hierdurch wird das bei der Form zuvor aktive 1:1-Durchreichen deaktiviert.

property: Angabe der Property, die durchgereicht werden soll.

handler: Funktion, welche die von außen kommenden Daten verarbeitet und an die inneren Elemente übergibt.

  .incoming('value', (value, form) => {
    form.value = value;
  })

outgoing(property, handler)

Registriert für die angegebene Property einen Handler, der die Konvertierung von internen Werten (auf dem eingepackten Widget) in externe Werte (auf dem agorum.composite.wrapper-Widget) vornimmt. Hierdurch wird das zuvor aktive 1:1-Durchreichen deaktiviert.

property: Hier ist die Property anzugeben, die durchgereicht werden soll.

handler: Funktion, welche die Werte des inneren Widgets sammelt und als Rückgabewert nach außen bereitstellt.

  .outgoing('value', (value, wrapper) => {
    wrapper.value = value;
  });

Beispiele

Anordnung des Inhalts einer Tabelle in einer Form

Dieses Beispiel zeigt auch die Verwendung allgemeiner Widget-Funktionen.

let aguila = require('common/aguila');

let widget = aguila.create({
  type: 'agorum.composite.form.basic',
  labelPosition: 'top',
  width: 400,
  elements: [
    {
      type: 'agorum.composite.form.element.text',
      name: 'input',
      label: 'Eingabefeld'
    },
    {
      type: 'agorum.composite.wrapper',
      name: 'grid',
      wrap: {
        type: 'agorum.basicGrid',
        border: true,
        height: 200,
        columns: [
          {
            name: 'col1',
            text: 'Spalte 1'
          },
          {
            name: 'col2',
            text: 'Spalte 2'
          }
        ]
      }
    }
  ]
});

let grid = widget.down('grid');

grid.incoming('value', (value, inner) => {
  // äußeren Wert auftrennen in Zeilen und Selektion
  inner.rows = value;
  inner.selection = value.reduce((sel, row, i) => row.selected ? sel.concat(i) : sel, []);
});

grid.outgoing('selection', (selection, outer) => {
  // geänderte Selektion zu äußerem Wert hinzufügen
  outer.value = outer.value.map((row, i) => Object.assign({}, row, { selected: selection.includes(i) }));
});

widget.on('valueChanged', value => console.log('value', value));

widget.value = {
  input: 'Test',
  grid: [
    {
      col1: 'Test 11',
      col2: 'Test 12'
    },
    {
      col1: 'Test 21',
      col2: 'Test 22',
      selected: true
    },
    {
      col1: 'Test 31',
      col2: 'Test 32',
      selected: true
    }
  ]
};

widget;

Oberfläche zum Tabellenbeispiel

Form-Element mit readOnly und disabled Steuerung

Dieses Beispiel zeigt, wie ein agorum.textInput Widget gekapselt wird, um readOnly- und disabled-Zustände aus übergeordneten Properties (readOnly, viewMode, disabled, disabledForm) zu verwalten. Dies ist nützlich, wenn ein einfaches Input-Widget in Form-Kontexten verwendet werden soll.

let aguila = require('common/aguila');

let widget = aguila.create({
  properties: ['readOnly', 'viewMode', 'disabled', 'disabledForm'],
  type: 'agorum.composite.wrapper',
  wrap: {
    name: 'inner',
    type: 'agorum.textInput',
  },
});

let inner = widget.down('inner');

let updateReadOnly = () => (inner.readOnly = widget.readOnly || widget.viewMode);
let updateDisabled = () => (inner.disabled = widget.disabled || widget.disabledForm);

widget.on('readOnlyChanged', updateReadOnly);
widget.on('viewModeChanged', updateReadOnly);
widget.on('disabledChanged', updateDisabled);
widget.on('disabledFormChanged', updateDisabled);

widget;