Understanding How Validation and Messaging Works in Oracle JET Editable Components

The actions performed on an Oracle JET component, the options set on it, and the methods called on it, all instruct the component on how it should validate the value and what content it should show as part of its messaging.

Editable components always perform either normal or deferred validation in some situations. In other situations, the editable component decides to perform either normal or deferred validation based on the component's state. Understanding the normal and deferred validation process may be helpful for determining what message options to set on your components.

  • Normal Validation: During normal validation, the component clears all messages options (messagesCustom, messagesShown, and messagesHidden), parses the UI value, and performs validation. Validation errors are reported to the user immediately. If there are no validation errors, the value option is updated, and the value is formatted and pushed to the display.

    The editable component always runs normal validation when:

    • The user interacts with an editable component and changes its value in the UI.

    • The application calls validate() on the component.

    Note:

    When the application changes certain options, the component might decide to run normal validation depending on its current state. See Mixed Validation below for additional details.

  • Deferred Validation: Uses the required validator to validate the component's value. The required validator is the only validator that participates in deferred validation. During deferred validation all messages options are cleared unless specified otherwise. If the value fails deferred validation, validation errors are pushed to the messagesHidden option and not shown to the user immediately.

    The editable component always runs deferred validation when:

    • A component is created. None of the messages options are cleared.

    • The application calls the reset() method on the component.

    • The application changes the value option on the component programmatically.

    Note:

    When the application changes certain options programmatically, the component might decide to run deferred validation depending on its current state. See Mixed Validation below for additional details.

  • Mixed Validation: Runs when the following options are changed or methods are called by the application. Either deferred or normal validation is run based on the component's current state, and any validation errors are either hidden or shown to the user. Mixed validation runs when:

    • converter option changes

    • disabled option changes

    • readOnly options change

    • required option changes

    • validators option changes

    • refresh() method is called

Topics:

The Oracle JET Cookbook includes additional examples that show normal and deferred validation at Validators (Component). For additional information about the validators and converters included with Oracle JET, see Validating and Converting Input.

Understanding How an Oracle JET Editable Component Performs Normal Validation

An Oracle JET editable component runs normal validation when the user changes the value in the UI or when the application calls the component's validate() method. In both cases, error messages are displayed immediately.

Topics:

Normal Validation Process When User Changes Value of an Editable Component

When a user changes an editable value:

  1. All messagesCustom, messagesHidden, and messagesShown messages are cleared. An optionChange event is triggered if applicable and if the change in value is obvious.

  2. If a converter is set on the component, the UI value is parsed. If there is a parse error, then processing jumps to step 5.

  3. If one or more validators are set on the component:

    1. The parsed (converted) value is validated in sequence using the specified validators, with the implicit required validator being the first to run if present. The value that is passed to the implicit required validator is trimmed of white space.

    2. If the validator throws an error, the error is remembered, and the next validator runs if it exists.

      After all validators complete, if there are one or more errors, processing jumps to step 5.

  4. If all validations pass:

    1. The parsed value is written to the component's value option, and an optionChange event is triggered for the value option.

    2. The new value is formatted for display using the converter again and displayed on the component.

    Note:

    If the component's value option happens to be bound to a Knockout observable, then the value is written to the observable as well.

  5. If one or more errors occurred in an earlier step:

    1. The component's value option is not changed.

    2. The component's messagesShown option is updated, and an optionChange event is triggered for the messagesShown option.

    3. Errors are displayed on the component. The user can also view the details of the error by setting focus on the component. By default, this will open a notewindow.

    Note:

    If the component's value option is bound to a Knockout observable, then the value is written to the observable array as well. In addition, if the page author has set the invalidComponentTracker binding attribute, then the array associated to this attribute is updated.

  6. When the user fixes the error, the validation process begins again.

Normal Validation Process When Validate() is Called on Editable Component

The validate() method validates the component's current display value using the converter and all validators registered on the component and updates the value option if validation passes.

For details about the validate() method, see validate().

Understanding How an Oracle JET Editable Component Performs Deferred Validation

An Oracle JET editable component runs deferred validation when the component is created, when its value or required option is changed programmatically, or when the component's reset() method is called. This section provides additional detail about the deferred validation process when an Oracle JET editable component is created and when the value option is changed programmatically.

Topics:

You can also find additional detail in the JavaScript API Reference for Oracle® JavaScript Extension Toolkit (JET). Select the component you’re interested in from the navigation list.

Deferred Validation Process When an Oracle JET Editable Component is Created

When a editable component is created, as one of the last steps, it runs deferred validation on the component's initialized value.

  1. The required validator is run, and a validation error raised if the value is empty or null.

  2. If a validation error is raised, the component updates the messagesHidden option which triggers the optionChange event.

    • isValid() method returns false.

    • No messaging themes are applied on the component nor does it show the error message in the note window because the validation error message is deferred.

Note:

Page authors can call showMessages() at any time to reveal deferred messages.

Deferred Validation Process When value Option is Changed Programmatically

An Oracle JET editable component's value option can change programmatically if:

  • The page has code that changes the component's value using the component's option() method, or

  • The page author refreshes the ViewModel observable with a new server value.

In both cases, the component will update itself to show the new value as follows:

  1. All messages options are cleared on the editable component and optionChange events triggered if applicable.

  2. An optionChange event is triggered for the value option if applicable.

  3. If a converter option is set on the component, the value option is retrieved and formatted before it's displayed. If there is a format error, then processing jumps to step 5. Otherwise the formatted value is displayed on the component.

  4. Deferred validators are run on the new value. Any validation errors raised are communicated to the messaging framework, and the messagesHidden option updated, but the errors themselves are not shown to the user.

  5. If there was a formatting error, the validation error message is processed and the component's messagesShown option updated. Formatting errors are shown right away.

Note:

Page authors should ensure that the value you set is the expected type as defined by the component's API and that the value can be formatted without any errors for display.