Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum.composite.form

agorum.composite.form – Validierung

Mit einer Validierung können Sie Benutzereingaben anhand von Vorgaben einschränken und einen Benutzer darauf hinweisen, was er einzugeben hat. Eine Validierung können Sie entweder an ein Element oder auf eine ganze form setzen.

Setzen Sie eine Validierungsdefinition (validation) auf die form, mischt das System deren Definitionen mit den validation-Definitionen der Elemente. Das System verhält sich dann so, als wenn die Validierung bei jedem Element gesetzt werden würde.
Das System zeigt einen errorText beim jeweiligen Element an und verdeutlicht die fehlerhafte Eingabe durch eine rote Markierung.

Validierungsdefinition

Sie setzen die Validierungsdefinition (validation) per Parameter auf das Element oder die form.
Die Validierung definiert, wann der eingegebene Wert eines Elements gültig ist und erlaubt so die Prüfung auf Korrektheit des eingegebenen Werts.
Sie können mehrere Arten der Validierung übergeben.

Das System prüft bei jeder Werteänderung des Elements oder beim Ändern der Validerungsdefinitionen auf diese Validierung. Schlägt sie fehl, dann:

setzt das System den Parameter valid auf false
markiert das System das Element rot (abhängig von showError)
zeigt das System per Mouse-Over den jeweiligen Fehlertext an (abhängig von showError)

Die Validierung ist ein Array mit mehreren möglichen Definitionen. Das System kann mehrere Verhalten nacheinander prüfen, und Sie können im Hinweistext genau differenzieren. So können Sie statt einer komplexen RegEx, die alles abprüft, zwei einzelne formulieren. Dadurch ist zum einen die Formulierung der regulären Ausdrücke einfacher, zum anderen zeigt das System so zu jeder RegEx einen speziellen Hinweis an.

Jede Definition enthält einen Fehlertext (errorText) und einen Parameter (etwa regex).
Definieren Sie den optionalen errorText nicht, erzeugt das System eine Standard-Fehlermeldung.

Beispiel einer Oberfläche

Beispiel

Skript zur Oberfläche

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

let form = aguila.create({
  type: 'agorum.composite.form.basic',
  elements: [
    {
      type: 'agorum.composite.form.element.text',
      name: 'textField1',
      label: 'e-Mail',
      validation: [
        {
          regex: '/.*@.*\\..*/i', // Achtung, stark vereinfacht!
          errorText: 'Keine gültige E-Mail'                
        },
        {
          required: true
        }
      ]
    }
  ]
});

form;

Parameter

required

Wert	Beschreibung
true	Prüft, ob der Benutzer einen Wert gesetzt oder eingegeben hat. Verhindert etwa, dass der Benutzer das Feld vergisst und nichts eingibt.
false	Prüft NICHT, ob der Benutzer einen Wert gesetzt oder eingegeben hat.

Beispiel

{
  required: true
}

errorText

Definiert eine Fehlermeldung.

Definieren Sie keine Fehlermeldung, lautet die Fehlermeldung Feld darf nicht leer sein.

Beispiel

{
  errorText: 'Keine gültige E-Mail'
}

maxLength

Beschränkt die Menge der einzugebenden Zeichen.

Sie können maxLength und minLength entweder gemeinsam oder jeweils einzeln verwenden.
Verwenden Sie den Parameter errorText, um eine Fehlermeldung auszugeben, wenn ein Benutzer diese Menge überschreitet.

Beispiel

// maximal 10 Zeichen
{
  maxLength: 10,
  errorText: 'Zu viele Zeichen'
}

minLength

Verlangt eine Mindestmenge von Zeichen, die ein Benutzer eingeben muss.

Sie können minLength und maxLength entweder gemeinsam oder jeweils einzeln verwenden.
Verwenden Sie den Parameter errorText, um eine Fehlermeldung auszugeben, wenn ein Benutzer diese Menge unterschreitet.

Beispiel

// mindestens 3 Zeichen
{
  minLength: 3,
  errorText: 'Zu wenige Zeichen'
}

regex

Erwartet einen regulären Ausdruck in Form eines Strings.

Das System prüft diesen Ausdruck bei Eingabe des Benutzers oder bei Änderung von value, etwa ('/(w*)[0-9]+/').
Sie können einen Parameter übergeben, wenn Sie den regulären Ausdruck in Schrägstriche hüllen (ein führender und endender Schrägstrich (/)) etwa regex: '/(w*)[0-9]+/ig'. Dadurch erstellt das System den regulären Ausdruck mit den Parametern i und g.
Sie können eine Schreibweise ohne Schrägstriche verwenden, etwa regex: '(w*)[0-9]+'.
Verwenden Sie den Parameter errorText, um eine Fehlermeldung auszugeben, wenn der reguläre Ausdruck nicht stimmt.

Beispiel

{
  regex: '/^([A-Z])\\w+/',
  errorText: 'Bitte mit Großbuchstaben beginnen.'                
}

Dieser reguläre Ausdruck erwartet ein Wort, das mit mindestens einem Großbuchstaben beginnt.

Übergeben Sie den regulären Ausdruck als String.
Escapen Sie \ mit \\.
Das System prüft reguläre Ausdrücke nur, wenn das Feld auch einen Wert besitzt.
Das System führt keine Prüfung durch, wenn der Parameter required auf false steht, weil definiert ist, dass das Feld nicht belegt sein muss.

script (JavaScript)

Sie können über ein Skript eine Validierung für das jeweilige Feld durchführen. Dazu erzeugen und registrieren Sie das Skript.

Das Skript muss die Funktion validate enthalten.

Wichtig: Das System ruft diese Funktion jedes Mal synchron auf:

für jedes Element, wenn sich das jeweilige Element ändert
für jedes Element einer Form, wenn Sie die Funktion auf form-Ebene definiert haben

Führen Sie keine langlaufenden Operationen durch, weil sonst die Oberfläche langsamer arbeitet.

Das Skript in der MetaDB registrieren

Öffnen Sie links in der Seitenleiste Explorer.

Öffnen Sie Ihr Konfigurationsprojekt und legen Sie diese Unterordner an:

Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/js/form/validation

Legen Sie eine JavaScript-Datei an, etwa:
```
validate-script.js
```
Klicken Sie mit der rechten Maustaste auf die JavaScript-Datei.
Wählen Sie im Kontextmenü agorum core template manager > Register form validation.

Ergebnis: Sie haben das Validierungsskript registriert. Es erhält im obigen Beispiel den Namen tstforms.testValidation.

Inhalt des Validierungsskripts

Möglichkeit 1: Das Skript gibt true / false zurück

Diese Funktion erhält als Parameter das Element (widget) und den Wert (value).

Die Funktion:

gibt true bei einem gültigen Wert zurück
gibt false bei einem ungültigen Wert zurück

Beispiel für einen Zahlenwert, der zwischen 10 und 20 liegen muss:

/**
 * validate if given value is between 10 and 20
 */
function validate(element, value) {
  if (value && value >= 10 && value <= 20) {
    return true;
  }
  
  return false;
}

// export function
module.exports = {
  validate: validate
};

Geben Sie in der Definition des Elements das Skript sowie den Parameter errorText, den der Benutzer sehen soll, wenn die Validierung fehlschlägt, so an:

{
  script: 'tstforms.testValidation',
  errorText: 'Der angegebene Wert muss zwischen 10 und 20 liegen.'
}

Möglichkeit 2: Das Skript gibt eine Fehlermeldung zurück

Diese Möglichkeit ist ähnlich der Möglichkeit 1, mit dem Unterschied, dass das Skript selbst Fehlermeldungen produzieren kann, die der Benutzer dann je nach Fall sieht.

Beispiel

/**
 * validate if given value is between 10 and 20
 */
function validate(element, value) {  
  if (!value) {
    return 'Der Wert des Felds "' + element.name + '" muss belegt sein.';
  }

  if (!(value >= 10 && value <= 20)) {
    return 'Der Wert des Felds "' + element.name + '" muss zwischen 10 und 20 liegen.';
  }

  return true;
}

// export function
module.exports = {
  validate: validate
};

Sie müssen den Parameter errorText in der Definition nicht definieren, da der Text bereits aus dem Skript kommt.
Ist eine Skript-Validierung aktiv, ignoriert das System den Parameter required, sodass das Skript die Möglichkeit hat, sich darum kümmern zu können.

Parameter an das Validierungsskript übergeben

Sie können optional Parameter übergeben, um das Skript von außen zu steuern.

Beispiel

/**
 * validate if given value is between parameters.from and parameters.to
 */
function validate(element, value, parameters) {  
  parameters = parameters || {};
  
  if (!parameters.from || !parameters.to) {
    throw new Error('Fehlende Parameter: from und to müssen belegt sein.');
  }
  
  if (!value) {
    return 'Hier muss was rein: ' + element.name;
  }

  if (value && !(value >= parameters.from && value <= parameters.to)) {
    return 'Der Wert muss zwischen ' + parameters.from + ' und ' + parameters.to + ' liegen: ' + element.name;
  }

  return true;
}

// export function
module.exports = {
  validate: validate
};

Element definieren

validation: [
  {
    script: 'tstforms.testValidation',
    parameters: {
      from: 1,
      to: 100
    }
  }
]

Validierung außerhalb des Elements

Sie können die Validierung auf form-Ebene, d. h. außerhalb des jeweiligen Elements, durchführen. Dies kann etwa erfolgen, wenn sich der Wert auf form-Ebene geändert hat. So beachtet das System auch mehrere Elemente bei einer Validierung.

Beispiel 1

form.on('valueChanged', () => {
  //Prüfen, ob textField1 mit einem "a" beginnt
  if (form.value.textField1 && !form.value.textField1.startsWith('a')) {
    //Wenn textField1 nicht mit einem a beginnt, belege textField1 mit einer Fehlermeldung
    form.error = {
      textField1: 'Der Text muss mit einem a beginnen.'
    };
  }
  else {
  // Um die Fehlermeldung wieder zu entfernen, setze form.error zurück
    form.error = {};
  }
});

Beispiel 2 mit agorum.composite.form.element.list

.
.

    {
      type: 'agorum.composite.form.element.list',
      name: 'listField',
      maxItems: 5,
      label: 'Test',
      showAppend: true,
      showRowDelete: true,
      template: [
        {
          type: 'agorum.composite.form.element.text',
          name: 'locale',
          label: 'Sprache[_<Land>[_<Variante>]]',
          flexible: true,
          validation: [
            {
              required: true
            }
          ]
        },
        {
          type: 'agorum.composite.form.element.text',
          name: 'text',
          label: '_agorum.messages.manager.js.messagemanager.filekey.label',
          flexible: true,
          validation: [
            {
              required: true
            }
          ]
        }        
      ]
    },

.
.
.
.




form.on('input', input => {
  if (input.name === 'locale') {
    // Prüfen, ob Eingabe okay
    let lookupData = localeHandler.read(input.value, {lookup:true});
    if (lookupData && lookupData[0]) {
      // Wenn okay, dann errorText wieder zurücksetzen
      form.set(['listField', input.index, 'locale', 'error' ], null);
    }
    else {
      // errorText setzen und durch form.validate anzeigen lassen
      form.set(['listField', input.index, 'locale', 'error' ], 'Fehlerhafte Eingabe ...');
      form.validate();
    }
  }
});

Open Source DokumentenmanagementDokumentation

agorum.composite.form – Validierung

Validierungsdefinition

Beispiel einer Oberfläche

Skript zur Oberfläche

Parameter

required

errorText

maxLength

minLength

regex

script (JavaScript)

Validierung außerhalb des Elements

Beispiel 1

Beispiel 2 mit agorum.composite.form.element.list

Open Source Dokumentenmanagement
Dokumentation