Field validators

Validators ensure that field input is entered in the correct format and length. For example, you can validate that an email address adheres to a syntax such as first.last@company.com. You can add multiple validators to a field. The validators are executed in a chain, one after the other.

This field validator definition is part of the Magnolia 6 UI framework. The fully qualified class name is info.magnolia.ui.field.FieldValidatorDefinition.

If you work with the Magnolia 5 UI framework, see Field validators for Magnolia 5 UI instead.

Example definition

email:
  label: Email
  $type: textField
  required: true
  validators:
    email:
      $type: emailValidator
      errorMessage: Enter a valid email address

Validator properties

Property Description

validators

required

List of field validator definition items. Any value must be a subtype of info.magnolia.ui.field.FieldValidatorDefinition.

     <validator name>

required

Arbitrary validator name. Use a name that describes the validator type.

         class

required (unless $type is used)

Validator definition class. Use the fully qualified class name. See Validator types for possible values.

You can also create your own validator definition class.

         $type

You can use this as a shortcut for class if the definition class is annotated with info.magnolia.ui.field.ValidatorType. The proper value is defined by the annotation.

Example class annotation
@ValidatorType("emailValidator")
public class EmailValidatorDefinition extends ConfiguredFieldValidatorDefinition {
...
}

To use the $type property in YAML, see Example definition.

         mode

required (used only in node name validation), default is EDIT

Validation mode when using nodeNameValidator. Validates names for:

  • Siblings of the currently selected node when editing an existing node (mode=EDIT).

  • Children of the currently selected node when adding a new node (mode=ADD).

         pattern

required (used only in node name and regex validation), default is .+ for nodeNameValidator

Regular expression pattern to validate against when using nodeNameValidator and regexpValidator.

Do not use pattern to validate empty values. Instead, make sure that required is set to true.

         factoryClass

optional

Fully qualified name of the Java class that creates the validator. The class must implement info.magnolia.ui.field.FieldValidatorFactory. Validator definitions specify a default factory class. This means that unless you want to use a custom implementation, you do not need to configure a factory class.

         errorMessage

optional

Error message displayed on invalid input. The value can be literal or retrieved from the message bundle with a key. Use alphanumeric characters in literal values.

Global validators

Validators can be defined globally for certain types of fields. You can view and edit the default configuration file config.yaml in the Resource Files app under the ui-framework-core node.

In the YAML below, the default field validators for UploadFieldDefinition would also apply to its extended class DamUploadFieldDefinition (and any other extended classes).

defaultFieldValidators:
  info.magnolia.ui.field.UploadFieldDefinition: # applies to its extended classes as well (e.g. DamUploadFieldDefinition)
    svgValidator:
      class: info.magnolia.ui.field.SvgUploadValidatorDefinition

The default field validator SafeHtmlValidatorDefinition is also configured for RichTextFieldDefinition and its extended classes. This validator allows html tags, attributes and protocols in the value of rich text field.

The global SafeHtmlValidatorDefinition configuration is also used by the 5 UI rich text field.

However, this validator cannot be reconfigured per field in the Magnolia 5 UI framework.

 
defaultFieldValidators:
  info.magnolia.ui.field.RichTextFieldDefinition:
    safeHtml: (1)
      class: info.magnolia.ui.field.SafeHtmlValidatorDefinition (1)
      allowedTags:
        a: a
        div: div
        ...
      allowedAttributes:
        a:
          tag: a
          attributes: [ href ]
        ...
      allowedProtocols:
        a:
          tag: a
          attribute: href
          protocols: [ ftp, http, https, mailto ]
        ...
1 The safeHtml section contains the SafeHtmlValidatorDefinition class which allows you to specify the allowed tags, attributes, and protocols.
Property Description

allowedTags

List of html tags that are allowed in rich text field.

globallyAllowedAttributes

List of attributes that are allowed in all tags, defined in allowedTags.

The tag should be configured to make all globally allowed attributes work.
Example
  allowedTags:
    a: a
    b: b

  globallyAllowedAttributes: [style, class] (1)
1 Style and class attributes are allowed in the <a> and <b> tags.

<a style="some-styleA" class="some-classA"></a>

<b style="some-styleB" class="some-classA"></b>

allowedAttributes

List of attributes that are allowed in a tag, defined in allowedTags.

The tag should be configured to make all allowed attributes work.
Example
  allowedTags:
    a: a
  allowedAttributes:
    abbr:
      tag: a
      attributes: [ title ] (1)
1 Only <a title="the title"></a> is allowed in this example.

allowedProtocols

List of protocols that are allowed in attribute value of a tag.

The attribute and tag should be configured to make the allowed protocols work.
Example
  allowedTags:
    a: a
  allowedAttributes:
    a:
      tag: a
      attributes: [ href ]
  allowedProtocols:
    a:
      tag: a
      attribute: href
      protocols: [ https, mailto ] (1)
1 In this case, <a href="https://foo.bar">foo</a> and <a href="mailto:info@mail.com">foo</a> are allowed because of https and mailto protocols.
Global validators do not apply to apps using the Magnolia 5 UI framework. An exception is the SafeHtmlValidator, which loads this configuration explicitly.

Custom validators

To write your own validator definition class:

  1. Create a validator class that performs the actual validation.

  2. Create a validator factory class that extends info.magnolia.ui.field.AbstractFieldValidatorFactory. Implement the createValidator method.

  3. Create a validator definition class that extends info.magnolia.ui.field.ConfiguredFieldValidatorDefinition. In the definition class, set the factory class.

Validator types

$type class/description

emailValidator

info.magnolia.ui.field.EmailValidatorDefinition

Validates an email address. Delegates to Vaadin EmailValidator.

nodeNameValidator

info.magnolia.ui.editor.validator.NodeNameValidatorDefinition

Validates JCR node names as defined in the mode and pattern properties.

regexpValidator

info.magnolia.ui.field.RegexpValidatorDefinition

Validates text input as defined in the pattern property.

n/a

info.magnolia.ui.field.SvgUploadValidatorDefinition

Validates SVG file uploads against malicious content.

n/a

info.magnolia.ui.field.SafeHtmlValidatorDefinition

Validates text against malicious HTML.
Feedback