Understanding How Validation and Messaging Works in Oracle JET Editable Components

The actions performed on an Oracle JET component, the properties 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 properties to set on your components.

Normal Validation: During normal validation, the component clears all messages properties (messages-custom), parses the UI value, and performs validation. Validation errors are reported to the user immediately. If there are no validation errors, the value attribute 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 properties, 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 properties are cleared unless specified otherwise. If the value fails deferred validation, validation errors are not shown to the user immediately.

The editable component always runs deferred validation when:
- A component is created. None of the messages properties are cleared.
- The application calls the reset() method on the component.
- The application changes the value property on the component programmatically.
Note:

When the application changes certain properties 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 properties 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 property changes
- disabled property changes
- readOnly properties change
- required property changes
- validators property 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:

All messages-custom messages are cleared. An onMessagesCustomChanged event is triggered if applicable and if the change in value is obvious.
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.
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.
If all validations pass:
1. The parsed value is written to the component's value attribute, and an onValueChanged event is triggered for the value attribute.
2. The new value is formatted for display using the converter again and displayed on the component.
Note:

If the component's value property happens to be bound to a Knockout observable, then the value is written to the observable as well.
If one or more errors occurred in an earlier step:
1. The component's value attribute is not changed.
2. The component's messages-custom attribute is updated, and an onMessagesCustomChange event is triggered for the messages-custom attribute.
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 note window.
Note:

If the component's value attribute is bound to a Knockout observable, then the value is written to the observable array as well.
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 attribute if validation passes.

The method is only available on editable components where it makes sense, for example, oj-input-number. 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 property 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 property 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 element is created, as one of the last steps, it runs deferred validation on the component's initialized value.

The required validator is run, and a validation error raised if the value is empty or null.
If a validation error is raised, the component updates the messaging framework. 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 Property is Changed Programmatically

An Oracle JET editable element’s value property can change programmatically if:

The page has code that changes the element's value attribute, or
The page author refreshes the ViewModel observable with a new server value.

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

All messages properties are cleared on the editable element and onMessagesCustomChanged events triggered if applicable.
An onValueChanged event is triggered for the value attribute if applicable.
If a converter is set on the element, the value attribute 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 element.
Deferred validators are run on the new value. Any validation errors raised are communicated to the messaging framework, but the errors themselves are not shown to the user.
If there was a formatting error, the validation error message is processed and the component's messages-custom attribute 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.