agorum.composite.form.basic

Dieses Widget bietet alle Basisfunktionen einer form:

• Bearbeitungsmaske
• Ansichtsmaske
• Eingabe/ Werte validieren
• Werte setzen /holen

Einfaches Beispiel

---

Das folgende Beispiel erstellt eine Maske mit zwei Eingabefeldern:

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

let form = aguila.create({
  width: 300,
  height: 300,
  type: 'agorum.composite.form.basic',
  name: 'basicForm',

  elements: [
    {
      type: 'agorum.composite.form.element.text',
      name: 'textField1',
      label: 'Text 1'
    },
    {
      type: 'agorum.composite.form.element.text',
      name: 'textField2',
      label: 'Text 2'
    }    
  ]
});

form;

Komplexes Beispiel

---

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

let form = aguila.create({
  width: 300,
  height: 300,
  type: 'agorum.composite.form.basic',
  name: 'basicForm',

  elements: [
    {
      type: 'agorum.composite.form.element.text',
      name: 'textField1',
      label: 'Text 1'
    },
    {
      type: 'agorum.composite.form.element.text',
      name: 'textField2',
      label: 'Text 2'
    }    
  ],
  readOnly: false,
  validation: [
    {
      required: true
    }
  ],
  value: {
    textField1: 'Wert 1',
    textField2: 'Wert 2'
  },
  showError: 'always',
  error: {
    textField1: 'Error darstellen für textField1'
  }
});

form;

Beispiel mit Icon als Label

---

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

let form = aguila.create({
  width: 300,
  height: 300,
  type: 'agorum.composite.form.basic',
  name: 'basicForm',
  labelPosition: 'left',
  labelType: 'icon',

  elements: [
    {
      type: 'agorum.composite.form.element.text',
      name: 'textField1',
      label: 'Text 1',
      labelIcon: 'ionicon:beer-outline;color=DimGray',
      readOnly: null,
      value: 'Wert 1',
      placeholder: 'Bitte einen Text eingeben',
      error: 'Eine Fehlermeldung',
      validation: [
        {
          required: true,
        },
      ],
    },

    {
      type: 'agorum.composite.form.element.text',
      name: 'textField2',
      label: 'Text 2',
      labelIcon: 'ionicon:stopwatch-outline;color=DimGray',
      value: 'Wert 2',
      placeholder: 'Bitte einen Text eingeben',
      error: 'Eine Fehlermeldung',
      validation: [
        {
          required: true,
        },
      ],
    },
  ],
});

form;

Parameter

---

type

Definiert den Typ und lautet immer agorum.composite.form.basic.

name

Definiert einen eindeutigen Namen für diese form.

manualConfig

Wert	Beschreibung
true	Übernimmt KEINE Form Element-Definitionen aus der Metadaten-Definition, wenn der Name eines Elements mit dem Namen eines definierten Metadatums übereinstimmt.
false (Standard)	Übernimmt Form Element-Definitionen aus der Metadaten-Definition, wenn der Name eines Elements mit dem Namen eines definierten Metadatums übereinstimmt.

Dieser Parameter können Sie auch auf Element-Ebene definieren.

labelWidth

Definiert optional die Breite der jeweiligen Labels der in dieser form enthaltenen elements.

Sie können diesen Parameter nachträglich ändern.

Beispiel

form.labelWidth = 150; // Standard: 100

labelPosition

Definiert die Position des Labels.

Sie können diesen Parameter nachträglich ändern.

Wert	Beschreibung
left (Standard)	Das Label ist links vom Feld.
top	Das Label ist über dem Feld.

Beispiel

form.labelPosition = 'top';

labelType

Definiert den Typ des Labels.

Sie können diesen Parameter nachträglich ändern.

Wert	Beschreibung
text (Standard)	Das Label erscheint als Text. Die Eigenschaft label wird als der Text angezeigt.
icon	Das Label erscheint als Icon. Die Eigenschaft labelIcon wird als Icon angezeigt und die Eigenschaft label als Tooltip.

Beispiel

form.labelType = 'icon';

elements

Definiert ein Array von Elementen, die das System in dieser form verwendet.

Beispiel

Ein Element kann auch nur aus dem Namen eines Metadatums bestehen. Dann ermittelt agorum.composite.form automatisch alle Parameter aus der Metadaten-Definition zur korrekten Darstellung des Felds:

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

let form = aguila.create({
  width: 300,
  height: 300,
  type: 'agorum.composite.form.basic',
  name: 'basicForm',

  elements: [
    {
      name: 'ag_tags'
    },
    {
      name: 'user_ag_tags'
    } 
  ]
});

form;

Sie können diesen Parameter nachträglich ändern.

form.elements = [
  {       
    name: 'ag_tags'
  }
];

readOnly

Wert	Beschreibung
true	Der Ansichtsmodus erscheint.
false (Standard)	Der Bearbeitungsmodus erscheint.

Beispiel

form.readOnly = true; // Ansichtsmodus einschalten

validation

Enthält ein Array von Validierungsdefinitionen für alle Elemente in dieser form.

• Die Validierung können Sie bei den einzelnen Elementen definieren.
• Sie können diesen Parameter nachträglich ändern.

Beispiel

form.validation = [
  {       
    required: true
  }
];

value

Definiert eine Map von Werten zum Setzen und Auslesen der Werte der einzelnen Elemente in der form.

Sie können diesen Parameter nachträglich ändern.

Beispiel

form.value = {       
  ag_tags: [ 'Tag 1', 'Tag 2' ]
};

showError

Steuert das Anzeigeverhalten von Fehlermeldungen bei den einzelnen Elementen.

Sie können diesen Parameter nachträglich ändern.

Wert	Beschreibung
deferred (Standard)	Zeigt die Fehlermeldung erst, wenn der Benutzer etwas ändert und die Validierung daraufhin fehlschlägt.
always	Zeigt die Fehlermeldung sofort an, wenn die Validierung fehlschlägt.
never	Zeigt keine Fehlermeldung an.

Beispiel

form.showError = 'always';

error

Setzt eigene Fehlermeldungen an die jeweiligen Elemente, etwa wenn ein Skript eine Validierung durchführt.

Beispiel

form.on('valueChanged', () => {
  if (form.value.textField1 && !form.value.textField1.startsWith('a')) {
    form.error = {
      textField1: 'Der Text muss mit einem a beginnen'
    };
  }
  else {
    form.error = {};
  }
});

Dieses Beispiel prüft bei Änderung der Werte in der form, ob das Feld textField1 mit einem a beginnt. Wenn nicht, setzt das System eine Fehlermeldung auf das Feld.

disabled

Deaktiviert alle Elemente dieser form.

• Die Elemente sind noch sichtbar, können aber nicht verwendet werden (ausgegraut).
• Sie können diesen Parameter nachträglich ändern.

Beispiel

form.disabled = true;

valid

Wert	Beschreibung
true	Alle Felder sind gültig.
false	Ein oder mehrere Felder sind ungültig.

Verwenden Sie diesen Parameter, um zu prüfen, ob alle Eingaben korrekt sind, bevor ein Benutzer Eingaben in einer Oberfläche speichert.

Events (on)

---

focused

Löst aus, wenn das System ein Element der form fokussiert.

• Das System übergibt als Parameter ein Objekt, das Informationen zum auslösenden Element enthält.
• Die übergebene Struktur (im Beispiel info) ist wie folgt aufgebaut:

{
  name: 'name des elements',
  path: [  'name-des-haupt-elements', 'weitere untergeordnete', 'name-des-elements' ]
}

Parameter	Beschreibung
name	Definiert den Namen des ursprünglich auslösenden Elements.
path	Definiert den gesamten Pfad zu dem auslösenden Element als Array aus Sicht der form.

Beispiel

form.on('focused', info => {
  console.log('focused', info);
});

Beispiel bei einem list-element mit der Spalte „col1“

Das list-element selbst trägt den Namen list1:

{
  name: 'col1',
  index: 0,
  path: [  'list1', 0, 'col1' ]
}

In der Liste list1 wurde die 1te Zeile (0) in der Spalte col1 fokussiert (selbige Struktur gilt auf für die nachfolgenden Events blurred und action).

blurred

Löst aus, wenn das System ein Element der form defokussiert. 

• Das System übergibt als Parameter ein Objekt, das Informationen zum auslösenden Element enthält.
• Struktur siehe Parameter focused

Beispiel

form.on('blurred', info => {
  console.log('blurred', info);
});

action

Löst aus, wenn ein Benutzer das Element button oder menuItem der form aklickt.

• Das System übergibt als Parameter ein Objekt, das Informationen zum auslösenden Element enthält.
• Struktur siehe Parameter focused
• Die action-Events folgender Standard-aguila-Widgets lösen ebenfalls das actionEvent auf form-Ebene aus, sofern diese sich unterhalb des Elemente befinden und einen Namen besitzen (agorum.button oder agorum.menuItem).

validChanged

Löst aus, wenn eine Eingabe erfolgt und sich dadurch der Status von valid ändert.

• Das System übergibt als Parameter den neuen Wert von valid.
• valid ist dann true, wenn alle in der form enthaltenen Elemente auch true sind und umgekehrt.

valueChanged

Löst aus, wenn sich ein oder mehrere Werte der form-Elemente ändern.

• Das System übergibt als Parameter den neuen Wert von value.
• value enthält eine map, die die Werte aller elements der form enthält.

input

Löst aus, wenn ein Benutzer einen Wert in einem Feld ändert. Dieses Event ist einfacher zu verwenden als valueChanged.

Das System übergibt als Parameter eine Struktur mit den Informationen, was sich geändert hat.

Beispiel

Als Parameter übergibt das System diese Struktur:

{
  value: 'current value',      // aktueller Wert des Felds
  oldValue: 'previous value',  // Wert vor der Änderung
  name: 'name-of-element',     // Name des auslösenden Elements
}

Der Inhalt dieser Struktur kann je nach verwendetem Element variieren. Etwa gibt das Element list hier noch weitere Informationen mit.

changed

Löst aus, wenn ein Benutzer einen Wert in einem Feld ändert und das Feld verlässt.

• Das Event löst erst aus, wenn der Benutzer mit seiner Eingabe fertig ist.
• Das Event löst je nach Feld-Typ aus: Bei Eingabefeldern, sobald das Feld verlassen wird, sowie bei Auswahlfeldern oder Checkboxen / Radio-Buttons, sobald der Wert geändert wird.
• Das System übergibt als Parameter eine Struktur mit den Informationen, was sich geändert hat.

Beispiel

Als Parameter übergibt das System diese Struktur:

{
  value: 'current value',      // aktueller Wert des Felds
  name: 'name-of-element',     // Name des auslösenden Elements
}

Der Inhalt dieser Struktur kann je nach verwendetem Element variieren. Etwa gibt das Element list hier noch weitere Informationen mit.

elementsChanged

Löst aus, wenn sich elements ändert.

Das System übergibt den neuen Wert von elements, also eine Liste der neuen elements.

readOnlyChanged

Löst aus, wenn eine Änderung im Bearbeitungs-/ oder Ansichtsmodus stattfindet.

Das System übergibt als Parameter den neuen Wert von readOnly.

labelWidthChanged

Löst aus, wenn sich der Parameter labelWidth ändert.

Das System übergibt als Parameter den neuen Wert von labelWidth.

validationChanged

Löst aus, wenn sich die validation-Definition ändert.

Das System übergibt als Parameter den neuen Wert von validation.

showErrorChanged

Löst aus, wenn sich der Parameter showError ändert.

Das System übergibt als Parameter den neuen Wert von showError.

errorChanged

Löst aus, wenn sich der Parameter error ändert.

Das System übergibt als Parameter den neuen Wert von error.

Events (fire)

---

focus

Fokussiert das angegebene Element.

Das System fokussiert das erste Element der form, wenn Sie kein Element angeben.

Beispiel

// erstes element
form.fire('focus');

// oder mit element
form.fire('focus', 'name-des-elements');

Funktionen

---

validate()

Führt eine Validierung aller darunterliegenden Elemente durch, gibt das Ergebnis true oder false zurück und stellt eventuell aufgetretene Fehler einmalig visuell dar, unabhängig von der aktuell gesetzten Einstellung showError.

dump()

Gibt den internen Zustand aller Elemente innerhalb dieser form zurück.

Sie debuggen damit, welche Felder innerhalb der form welchen Zustand besitzen, etwa wann welche Felder dazu führen, dass eine form nicht valide ist.

Beispiel

console.log(form.dump());

batch(fn)

Fasst mehrere set()-Aufrufe zusammen, um die Anzahl der dadurch ausgelösten Ereignisse zu minimieren und die Performance zu verbessern, etwa bei der Verwendung von list-Elementen, da dort die Änderungen an größeren Mengen von Unterelementen (etwa einer oder mehrerer Spalten einer langen Liste) häufiger ist als bei anderen Elementen.

Beispiel

form.batch(() => {
  // Wert eines einzelnen text-Elements aktualisieren
  form.set('textElement', 'someValue');

  // Werte einer gesamten list-Spalte aktualisieren
  let numRows = form.get('listElement.value').length;

  for (let i = 0; i < numRows; ++i) {
    form.set([ 'listElement', i, 'someColumn', 'value' ], 'someOtherValue');
  }
});