Durchsuchbare Dokumentation aufrufen

Zurück zur Dokumentationsübersicht

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.

Validierungsdefinition

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

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.

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.


Beispiel

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

minLength

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


Beispiel

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

regex

Erwartet einen regulären Ausdruck in Form eines Strings.


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.

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

  1. Öffnen Sie links in der Seitenleiste Explorer.
  2. Öffnen Sie Ihr Konfigurationsprojekt und legen Sie diese Unterordner an: 
    Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/js/form/validation
  3. Legen Sie eine JavaScript-Datei an, etwa: 
    validate-script.js
  4. Klicken Sie mit der rechten Maustaste auf die JavaScript-Datei.
  5. 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:

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


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