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.

Hinweis: Wenn Sie labelPosition auf Element-Ebene definieren möchten, dürfen Sie auf form-Ebene kein labelPosition setzen, weil das System labelPosition auf Element-Ebene mit der Einstellung der form überschreibt.

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.

Hinweis: Wenn Sie readOnly auf Element-Ebene definieren möchten, dürfen Sie auf form-Ebene kein readOnly setzen, weil das System readOnly sonst auf Element-Ebene mit der Einstellung der form überschreibt.

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.

Hinweis: das Setzen eines errors zeigt nicht sofort einen Fehler an. Dieser verändert lediglich den Parameter valid. Soll direkt der Fehler erscheinen, setzen Sie showError etwa auf always.

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