Validation¶

Validation in Granite UI is achieved by using jQuery Validator plugin.

jQuery Validator¶

jQuery.validator is a jQuery plugin that provides form validation, which is designed to replicate HTML Forms Constraint Validation API.

API¶

The plugin is exposed as jQuery.validator variable, exposing Validators interface (described as TypeScript):

interface Validators {
  /**
   * A flag to indicate that the validation process should continue to the next validator.
   */
  CONTINUE: number;

  /**
   * A flag to indicate that the validation process should stop. This is default behavior.
   */
  STOP: number;

  /**
   * Registers the given validator(s).
   *
   * Each validator will be iterated to check the validity of submittable elements, where the iteration stopped when the first matching validator says invalid.
   * The order of the registration is important, where the last one registered will be used first.
   *
   * @param validator One or more validator objects.
   */
  register(...validator: Validator[]): void;

  /**
   * Returns <code>true</code> if all submittable elements under the given root element have no validity problems; <code>false</code> otherwise.
   * Fires <code>invalid</code> or <code>valid</code> event at submittable element when it is invalid or valid respectively.
   *
   * @param root The root element
   *
   * @return The validity
   */
  isValid(root: JQuery): boolean;
}

interface Validator {
  /**
   * Only the element satisfying the selector will be validated using this validator. It will be passed to <code>jQuery.fn.is</code>.
   */
  selector: string;

  /**
   * Only the element satisfying the selector will be validated using this validator. It will be passed to <code>jQuery.fn.is</code>.
   */
  selector: (index: number, element: Element) => boolean;

  /**
   * The actual validation function. It must return a string of error message if the element fails.
   */
  validate: (element: JQuery) => string;

  /**
   * The function to show the error. The function can return {@link Validators.CONTINUE} or {@link Validators.STOP}.
   */
  show: (element: JQuery, message: string) => number;

  /**
   * The function to clear the error. The function can return {@link Validators.CONTINUE} or {@link Validators.STOP}.
   */
  clear: (element: JQuery) => number;
}

It also exposes the following plugin methods to jQuery object (jQuery.fn):

interface ValidatorMethods {
  /**
   * Returns <code>true</code> if the element will be validated when the form is submitted; <code>false</code> otherwise.
   *
   * @see {@link http://www.w3.org/TR/html5/forms.html#dom-cva-willvalidate}
   */
  willValidate: () => boolean;

  /**
   * Returns the error message that would be shown to the user if the element was to be checked for validity.
   *
   * @return The error message or an empty string
   * @see {@link http://www.w3.org/TR/html5/forms.html#dom-cva-validationmessage}
   */
  validationMessage: () => string;

  /**
   * Returns <code>true</code> if the element's value has no validity problems; <code>false</code> otherwise.
   * Fires <code>invalid</code> or <code>valid</code> event at the element when it is invalid or valid respectively.
   *
   * @return The validity
   * @see {@link http://www.w3.org/TR/html5/forms.html#dom-cva-checkvalidity}
   */
  checkValidity: () => boolean;

  /**
   * Sets a custom error, so that the element would fail to validate.
   * The given message is the message to be shown to the user when reporting the problem to the user.
   * If the argument is the empty string, clears the custom error.
   *
   * @param message The error message or empty string
   * @see {@link http://www.w3.org/TR/html5/forms.html#dom-cva-setcustomvalidity}
   */
  setCustomValidity: (message: string) => void;

  /**
   * Shows error UI if the element is invalid; hide the UI otherwise.
   */
  updateErrorUI: () => void;
}

Mechanism¶

Applicable Element¶

The plugin is only validating the element satisfying the following selectors:

input:not([readonly],[disabled],[type=hidden],[type=reset],[type=button])
select
textarea:not([readonly])
button[type=submit]
[role=checkbox]:not([aria-disabled=true])
[role=radio]:not([aria-disabled=true])
[role=combobox]:not([aria-disabled=true])
[role=listbox]:not([aria-disabled=true])
[role=radiogroup]:not([aria-disabled=true])
[role=tree]:not([aria-disabled=true])
[role=slider]:not([aria-disabled=true])
[role=spinbutton]:not([aria-disabled=true])
[role=textbox]:not([aria-disabled=true],[aria-readonly=true])

The selectors are specifically designed to enforce form semantic and accessibility (using WAI-ARIA).

Form Submission¶

It will capture the form submit event to cancel and stop propagating the event when the form is invalid. If there is novalidate attribute, the validation process is skipped.

During the event capturing of submit event, it will perform the following pseudo-code:

function validateForm(form, submitEvent) {
  var controls = getApplicableElements(form);
  var invalids = [];
  var unhandleds = [];

  controls.forEach(function(field) {
    if (!validateField(field)) {
      invalids.push(field);
    }
  });

  if (invalids.length === 0) { // The form is valid
    return;
  }

  invalids.forEach(function(field) {
    var e = createEvent("invalid");
    field.trigger(e);

    if (!e.isDefaultPrevented()) {
      unhandleds.push(field);
    }
  });

  if (unhandleds.length === 0) {
    return;
  }

  unhandleds.forEach(function(field) {
    showErrorUI(field);
  });

  submitEvent.stopPropagation();
  submitEvent.preventDefault();
}

Validator¶

The plugin itself is not performing the actual validation. Rather a validator can be registered using jQuery.validator.register. It doesn’t provide any pre-registered validator.

Example¶

We need a validator to check the max length of a textfield (e.g. <input type="type">, <textarea>), and we are using data-myapp-maxlength attribute to indicate this. Like so:

<input type="text" data-myapp-maxlength="10">

Then we need to register the validator like so:

jQuery.validator.register({
  selector: "[data-myapp-maxlength]",
  validate: function(el) {
    var maxlength = parseInt(el.attr("data-myapp-maxlength"), 10);

    if (isNaN(maxlength)) {
      return;
    }

    var length = el.val().length;

    if (length > maxlength) {
      return "The field needs to be maximum " + maxlength + " characters. It currently has a length of " + length + ".";
    }
  }
});

Since we want to leverage the default error UI, we don’t register handlers for show() and clear().

Error UI¶

Like the validator, the actual logic of error UI is delegated to other code, which can be registered using jQuery.validator.register. It doesn’t provide any pre-registered error UI.

Example¶

We need to show a custom tooltip when the field is contained in vertical form. Like so:

<form class="myapp-form-vertical">
  <input>
</form>

Then we need to register the validator like so:

jQuery.validator.register({
  selector: ".myapp-form-vertical input",
  show: function(el, message) {
    el.customTooltip(message);
  },
  clear: function(el) {
    el.customTooltip("destroy");
  }
});

Since we only want to show the error UI, we don’t register a handler for validate(). The validity is checked by validate() of other registered validators instead.

Validation in CoralUI¶

coralui2 clientlib provides a set of default validators and error UI for the widgets it provides. Namely it:

listens and cancels the native invalid event—which is triggered by the browser supporting native validation—to show its own UI instead
validates input and textarea during input and change event
validates coral-Autocomplete during its change:value event
validates coral-Autocomplete during input and change event of its .js-coral-Autocomplete-textfield

It registers the following validators:

Default Error UI¶

The default catch all error UI.

selector: *

coral-Form Error UI¶

The error UI for coral-Form that uses .coral-Form-fielderror.

selector: .coral-Form-fieldwrapper .coral-Form-field, .coral-Form-fieldwrapper .coral-Form-field.coral-Autocomplete .js-coral-Autocomplete-textfield, .coral-Form-fieldwrapper .coral-Form-field.coral-InputGroup .coral-InputGroup-input, .coral-Form-fieldwrapper .coral-Form-field.coral-DecoratedTextfield .coral-DecoratedTextfield-input

Required for Input and Textarea¶

Checks required and aria-required attributes of input and textarea elements.

selector: input, textarea

Required for [role=listbox]¶

Checks aria-required attributes of [role=listbox] elements.

selector: [role=listbox]

Required for coral-Autocomplete¶

Checks aria-required attributes of coral-Autocomplete.

selector: .coral-Autocomplete

Validation in Granite UI’s Foundation¶

granite.ui.foundation clientlib provides a set of default validators and error UI for the vocabulary it provides. Namely it:

validates .foundation-collection[role=listbox] during foundation-selections-change event
performs .foundation-validation-bind

It registers the following validators:

[data-foundation-validation-ui]¶

Performs [data-foundation-validation-ui].

selector: [data-foundation-validation-ui]

foundation.jcr.name¶

Checks against valid JCR name. If the value is empty, this validator is voting abstain. This is a JavaScript counterpart of com.day.cq.commons.jcr.JcrUtil#isValidName(String).

selector: [data-validation='foundation.jcr.name']

.foundation-layout-actionfield¶

Provides error UI for .foundation-layout-actionfield under coral-Form.

selector: .coral-Form-fieldwrapper .coral-Form-field.foundation-layout-actionfield .foundation-layout-actionfield-field

Validation¶

jQuery Validator¶

API¶

Mechanism¶

Applicable Element¶

Form Submission¶

Validator¶

Example¶

Error UI¶

Example¶

Validation in CoralUI¶

Default Error UI¶

coral-Form Error UI¶

Required for Input and Textarea¶

Required for [role=listbox]¶

Required for coral-Autocomplete¶

Validation in Granite UI’s Foundation¶

[data-foundation-validation-ui]¶

foundation.jcr.name¶

.foundation-layout-actionfield¶

Table of Contents

Previous topic

Next topic

This Page