agorum.composite.form.element - Grundlegende Eigenschaften

Eine form besteht aus Elementen. Dies sind die jeweiligen Eingabe-/ Ansichtselemente der Oberfläche. Verschiedene Typen existieren, etwa Text, Auswahlbox, Datum.

All diese Elemente haben gemeinsame Grundeigenschaften.

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',
      readOnly: null,
      value: 'Wert 1',
      placeholder: 'Bitte einen Text eingeben',
      error: 'Eine Fehlermeldung',
      validation: [
        {
          required: true
        }
      ]
    }    
  ]
});

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 des Elements, etwa agorum.composite.form.element.text.

Das System wählt automatisch das Text-Element, wenn Sie keinen type definieren.

name

Definiert den eindeutigen Namen des Elements.

Das System ermittelt den Typ anhand der Metadaten-Definition, wenn name ein bekanntes Metadatum ist.
Die jeweiligen Metadaten-Definitionen können Sie in der Element-Definition überschreiben.
Setzen Sie manualConfig=true, wenn Sie dieses Verhalten für dieses Element komplett deaktivieren möchten.

manualConfig

Verhindert, dass das System Form-Element-Definitionen aus der Metadaten-Definition übernimmt, wenn der Name eines Elements mit dem Namen eines definierten Metadatums übereinstimmt.

Setzen Sie dazu manualConfig=true (Standard: false).

labelType

Definiert den Typ des labels.

Sie können diesen Wert nachträglich ändern.
Ist dieser Wert auf form-Ebene definiert, wird dieser auf das Element vererbt.

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.

Hinweis: Auf einer umliegenden form darf keine labelType-Definition vorhanden sein, wenn Sie die labelType auf Element-Ebene direkt definieren möchten.

Beispiel

form.down('textField1').labelType = 'icon';

label

Definiert den Text / das Label vor dem Element.

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

Beispiel

form.down('textField1').label = 'Neues Label';

labelWidth

Definiert die Breite des Labels vor dem Element (Standard: 100).

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

Beispiel

form.down('textField1').labelWidth = 150;

labelIcon

Definiert das Icon des Labels.

Damit das Icon angezeigt wird, muss die Eigenschaft labelType auf icon gestellt sein.

Sie können diesen Wert nachträglich ändern.
Als Icon können Sie den Code eintragen, den Sie mit Icon erstellen erzeugen.

Beispiel

form.down('textField1').icon = 'agorum:agorum-logo;color=SlateGray';

labelPosition

Definiert die Position des Labels.

Sie können diesen Wert nachträglich ändern.
Ist dieser Wert auf form-Ebene definiert, wird dieser auf das Element vererbt.

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

Hinweis: Auf einer umliegenden form darf keine labelPosition-Definition vorhanden sein, wenn Sie die labelPosition auf Element-Ebene direkt definieren möchten.

Beispiel

form.down('textField1').labelPosition = 'top';

fieldBorder

Definiert den border-Parameter innerhalb eines Elements.

Sie können so etwa die border eines html-Elements innen deaktivieren, aber außen (border-Parameter) beibehalten.
Sie können diesen Wert nachträglich ändern.

Beispiel

form.down('textField1').fieldBorder = false;

readOnly

Wert	Beschreibung
false (Standard)	Das System steuert den Bearbeitungs- oder Ansichtsmodus über die umliegende form. Das Element befindet sich im Bearbeitungsmodus, wenn keine form existiert.
true	Das Element ist immer im Ansichtsmodus, unabhängig vom Zustand der umliegenden form.

Beispiel

form.down('textField1').readOnly = true;

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

value

Definiert den vorbelegten Wert des Elements.

Das System überschreibt den hier definierten Wert, wenn Sie einen Wert über die form setzen.
Sie können diesen Parameter über die umliegende form setzen (siehe Werte setzen und Werte lesen).
Sie können diesen Wert nachträglich ändern.

Beispiel

form.down('textField1').value = 'Neuer Wert';

placeholder

Definiert einen Platzhalter-Text, wenn das Element leer ist.

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

Beispiel

form.down('textField1').placeholder = 'Neuer placeholder';

error

Definiert eine Fehlermeldung auf dem Element.

Sie können eine solche Fehlermeldung etwa bei einer Prüfung über JavaScript, etwa bei valueChanged setzen, wenn die Standard-Validierungen nicht ausreichen.
Sie können diesen Parameter über die umliegende form setzen (siehe Werte setzen und Werte lesen).
Sie können diesen Wert nachträglich ändern.

Hinweise:

Das Setzen eines errors zeigt nicht sofort einen Fehler an. Der error verändert lediglich den Parameter valid.
Setzen Sie etwa showError = 'always', wenn der Fehler direkt erscheinen soll.

Beispiel

form.down('textField1').error = 'Neue Fehlermeldung';

showError

Steuert das Anzeigeverhalten von Fehlermeldungen des Elements.

Sie können diesen Parameter über die umliegende form setzen (siehe Werte setzen und Werte lesen).

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 Fehlermeldungen an.

validation

Definiert die Validierung für dieses Element.

Im Sonderfall von required hat die Definition auf dem Element selbst Vorrang gegenüber der validation-Definition auf der form (siehe agorum.composite.form - Validierung).
Sie können diesen Parameter über die umliegende form setzen (siehe Werte setzen und Werte lesen).
Sie können diesen Wert nachträglich ändern.

Beispiel

form.down('textField1').validation = [
  {
    required: false
  }
];

disabled

Wert	Beschreibung
true	Deaktiviert das Element. Das Element ist sichtbar, aber ausgegraut. Der Benutzer kann es nicht verwenden.
false (Standard)	Aktiviert das Element, sodass der Benutzer es verwenden kann.

Beispiel

form.down('textField1').disabled = true;

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

valid

Ermittelt, ob die eingestellten Validierungen auf dem Element korrekt sind.

Wenn das System innerhalb des Events valueChanged auf valid geprüft wird, so kann es sein, dass valid noch nicht korrekt ist, da intern die Validierung noch nicht erfolgt ist.
Verwenden Sie die Funktion setImmediate, um den Code am Ende der Verarbeitungskette auszuführen.
Sie können diesen Wert nachträglich ändern.

Beispiel

form.on('valueChanged', () => {
  console.log('Valid ggf. noch falsch: ' + form.valid);
  setImmediate(() => {
      console.log('Valid ist jetzt korrekt: ' + form.valid);
  });
});

hidden

Wert	Beschreibung
true	Das Element ist für den Benutzer unsichtbar.
false (Standard)	Das Element ist für den Benutzer sichtbar.

Beispiel

form.down('textField1').hidden = true;

Funktionen

set

Setzt Parameter und Werte direkt (siehe set).

Beispiel

// Beispiel einen Wert setzen
form.set('textField1.value', 'Ein Wert');

// Beispiel Feld disablen
form.set('textField1.disabled', true);

get

Liest Parameter und Werte direkt aus (siehe get).

Beispiel

// Beispiel einen Wert lesen
let value = form.get('textField1.value');

// Beispiel Feld disabled Status lesen
let disabled = form.get('textField1.disabled');

Events (on)

labelChanged

Ändert den Parameter label.

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

labelWidthChanged

Ändert den Parameter labelWidth.

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

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.

valueChanged

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

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

Tipp: Verwenden Sie das Event input, wenn Sie ausschließlich auf Änderungen von Benutzereingaben reagieren möchten.

readOnlyChanged

Ändert den Bearbeitungs-/Ansichtsmodus.

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

validationChanged

Ändert die validation-Definition.

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

showErrorChanged

Ändert den Parameter showError.

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

errorChanged

Ändert den Parameter error.

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

placeholderChanged

Ändert den Parameter placeholder.

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

input

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

Das Event ist einfacher zu verwenden als valueChanged.
Der Parameter data enthält folgende Informationen:

Wert	Beschreibung	Beispiel
path	Definiert den Pfad des Elements als Array, in der eine Änderung stattgefunden hat.	Inhalt von path bei einem Texfeld [ 'nameDesElements' ] (aus Sicht der form) Beispiel bei Listen [ 'nameDerListe', row, 'column' ], also zum Beispiel: [ 'listField1', 0, 'column1' ] Sie erhalten hier genaue Information darüber, wo die Eingabe des Benutzers stattgefunden hat. Allgemeines Beispiel form.on('input', data => { let path = data.path; let value = data.value; let oldValue = data.oldValue; let name = data.name; });

Wert

Beschreibung

Beispiel

path

Definiert den Pfad des Elements als Array, in der eine Änderung stattgefunden hat.

Inhalt von path bei einem Texfeld

[ 'nameDesElements' ] (aus Sicht der form)

Beispiel bei Listen

[ 'nameDerListe', row, 'column' ], also zum Beispiel: [ 'listField1', 0, 'column1' ]

Sie erhalten hier genaue Information darüber, wo die Eingabe des Benutzers stattgefunden hat.

Allgemeines Beispiel

form.on('input', data => {
  let path = data.path;
  let value = data.value;
  let oldValue = data.oldValue;
  let name = data.name;
});

Events (fire)

focus

Fokussiert das Element.

Beispiel

form.down('textField1').fire('focus');