Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core für Entwickler > agorum.composite.form

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;

Screenshot zum Beispiel

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;

Screenshot zum Beispiel

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.

title

Legt einen Titel für das Element fest. Dadurch wird eine Titelleiste mit dem angegebenen Titel ergänzt. Zusätzlich können Sie ein Icon angeben, das zusätzlich vor dem Titel in der Titelleiste angezeigt wird.

Beispiel

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

let form = aguila.create({
  width: 500,
  height: 300,
  type: 'agorum.composite.form.basic',
  elements: [
    {
      type: 'agorum.composite.form.element.text',
      label: 'mylabel',
      title: 'mytitle',
    },
  ],
});
form;

Einfacher Titel

icon

Legt ein Icon für das Element fest. Dieses Icon wird zusätzlich zu einem Titel in der Titelleiste angezeigt.

Beispiel

let aguila = require('common/aguila');
let icons = require('/agorum/roi/customers/agorum.icons/js/icons');

let ICON = 'agorum:rounded-square-8;color=#0069b5;scale=.9|agorum:agorum-logo;color=white;scale=.9';

let form = aguila.create({
  width: 500,
  height: 300,
  type: 'agorum.composite.form.basic',
  elements: [
    {
      type: 'agorum.composite.form.element.text',
      label: 'mylabel',
      title: 'mytitle',
      icon: icons.cls(ICON),
    },
  ],
});
form;

Titelleiste mit Icon

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. Wichtig für die Entwicklung eigener Form-Elemente: Wenn ein Element innerhalb einer Form verwendet und die Form auf readOnly gesetzt wird, setzt die Form automatisch die Property viewMode=true auf dem Element. Bei der Entwicklung eines eigenen Form-Element-Widgets muss im Wrapper immer die Kombination von viewMode und readOnly geprüft werden. Dies gilt auch, wenn Sie ein Widget bauen, das einen Wrapper nutzt und vollständig in einer Form verwendet werden soll.

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.

Wichtig für die Entwicklung eigener Form-Elemente:

Wenn ein Element innerhalb einer Form verwendet und die Form auf readOnly gesetzt wird, setzt die Form automatisch die Property viewMode=true auf dem Element.
Bei der Entwicklung eines eigenen Form-Element-Widgets muss im Wrapper immer die Kombination von viewMode und readOnly geprüft werden.
Dies gilt auch, wenn Sie ein Widget bauen, das einen Wrapper nutzt und vollständig in einer Form verwendet werden soll.

Beispiel

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

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

viewMode

Die Properties readOnly und viewMode arbeiten zusammen und steuern den Ansichtsmodus (Nur-Lese-Modus) des Formulars. Wenn eines der beiden true ist, wird das gesamte Formular in den Ansichtsmodus versetzt. Die Property viewMode wird normalerweise automatisch gesetzt und muss nicht manuell gesetzt werden.

Wert	Beschreibung
false (Standard)	Das Element befindet sich im Bearbeitungsmodus.
true	Das Element befindet sich im Ansichtsmodus. Funktionsweise: viewMode wird automatisch auf true gesetzt, wenn ein Element innerhalb einer Form ist und die Form auf readOnly gesetzt wird. Die Form propagiert ihren readOnly-Zustand als viewMode an alle Kindelemente weiter. Wichtig für die Entwicklung eigener Form-Elemente: Bei der Entwicklung eines eigenen Form-Element-Widgets muss im Wrapper immer die Kombination von viewMode und readOnly geprüft werden. Auf Element-Ebene sollte readOnly verwendet werden, um ein Element dauerhaft in den Ansichtsmodus zu versetzen.

Wert

Beschreibung

false (Standard)

Das Element befindet sich im Bearbeitungsmodus.

true

Das Element befindet sich im Ansichtsmodus.

Funktionsweise:
viewMode wird automatisch auf true gesetzt, wenn ein Element innerhalb einer Form ist und die Form auf readOnly gesetzt wird. Die Form propagiert ihren readOnly-Zustand als viewMode an alle Kindelemente weiter.

Wichtig für die Entwicklung eigener Form-Elemente:

Bei der Entwicklung eines eigenen Form-Element-Widgets muss im Wrapper immer die Kombination von viewMode und readOnly geprüft werden.
Auf Element-Ebene sollte readOnly verwendet werden, um ein Element dauerhaft in den Ansichtsmodus zu versetzen.

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

Die Properties disabled und disabledMode arbeiten zusammen und steuern die Aktivierung des Elements.

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. Wichtig für die Entwicklung eigener Form-Elemente: Analog zu viewMode/readOnly existiert für disabled die Property disabledForm, die automatisch vom System gesetzt wird. Bei der Entwicklung eines eigenen Form-Element-Widgets muss im Wrapper immer die Kombination von disabledForm und disabled geprüft werden.

Beispiel

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

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

disabledForm

Die Properties disabled und disabledMode arbeiten zusammen und steuern die Aktivierung des Elements.

Wert	Beschreibung
false (Standard)	Das Element ist aktiviert (sofern disabled=false).
true	Das Element ist deaktiviert. Funktionsweise: disabledForm wird automatisch gesetzt, wenn ein Element innerhalb einer Form ist und die Form auf disabled=true gesetzt wird. Die Form propagiert ihren disabled-Zustand als disabledForm an alle Kindelemente weiter. Wichtig für die Entwicklung eigener Form-Elemente: Bei der Entwicklung eines eigenen Form-Elements muss immer die Kombination von disabledForm und disabled geprüft werden. Auf Element-Ebene sollte disabled verwendet werden, um ein Element zu deaktivieren.

Wert

Beschreibung

false (Standard)

Das Element ist aktiviert (sofern disabled=false).

true

Das Element ist deaktiviert.

Funktionsweise:
disabledForm wird automatisch gesetzt, wenn ein Element innerhalb einer Form ist und die Form auf disabled=true gesetzt wird. Die Form propagiert ihren disabled-Zustand als disabledForm an alle Kindelemente weiter.

Wichtig für die Entwicklung eigener Form-Elemente:

Bei der Entwicklung eines eigenen Form-Elements muss immer die Kombination von disabledForm und disabled geprüft werden.
Auf Element-Ebene sollte disabled verwendet werden, um ein Element zu deaktivieren.

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.

Hinweis: Bei der Entwicklung eigener Form-Elemente sollten Sie sowohl auf viewModeChanged als auch auf readOnlyChanged reagieren und beide Properties kombiniert prüfen. Siehe Form-Element mit readOnly und disabled Steuerung.

viewModeChanged

Ändert den Ansichtsmodus über die umliegende Form.

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

Hinweis: Dieses Event wird typischerweise ausgelöst, wenn die umliegende Form ihren readOnly-Zustand ändert. Bei der Entwicklung eigener Form-Elemente sollten Sie sowohl auf viewModeChanged als auch auf readOnlyChanged reagieren und beide Properties kombiniert prüfen. Siehe Form-Element mit readOnly und disabled Steuerung.

validationChanged

Ändert die validation-Definition.

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

disabledChanged

Löst aus, wenn die Property disabled auf dem Element geändert wird.

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

Hinweis: Bei der Entwicklung eigener Form-Elemente sollten Sie sowohl auf disabledForm als auch auf disabled reagieren und beide Properties kombiniert prüfen. Siehe Form-Element mit readOnly und disabled Steuerung.

disabledFormChanged

Löst aus, wenn die Property disabledForm durch die umliegende Form geändert wird.

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

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