Element: <oj-validation-group>

Oracle® JavaScript Extension Toolkit (JET)
5.2.0
E97691-01

QuickNav

Attributes

Methods

JET Custom Elements

JET components are implemented as custom HTML elements. In addition to the component attributes documented in this page, JET components also support standard HTML global attributes like id and aria-label.

The JET data binding syntax can be used to define both component and global attributes through the use of dynamically evaluated expressions. All attributes (component and global) support attribute-level binding by prefixing the attribute name with ":" (e.g. :id="[...]"). When using attribute-level binding, all expression values are treated as strings. Additionally, component attributes support property-level binding by using the attribute name directly with no ":" prefix. When using property-level binding, the expressions should evaluate to the types documented by the corresponding attributes. Property-level binding is strongly recommended over attribute-level binding for component attributes.

A detailed description of working with custom HTML elements can be found in: JET Custom Element Usage.


PREVIEW: This is a preview API. Preview APIs are production quality, but can be changed on a major version without a deprecation path.

Version:
  • 5.2.0
Since:
  • 4.2.0
Module:
  • ojvalidationgroup

JET ValidationGroup

The oj-validation-group element tracks the current validity state of its JET custom element descendents that contain the valid property.

The oj-validation-group element searches all its descendents. When it finds a component with a valid property, it adds it to the list of components it is tracking. For performance reasons it does not search the tracked component's children since the tracked component's valid state will be based on its children's valid state, if it has children with valid states. Once it finds all the components it needs to track, it calculates its own valid property value based on all the enabled (including hidden) components it tracks. Enabled means not disabled or readonly, so oj-validation-group's valid state ignores any disabled or readonly components.

The most 'invalid' component's valid property value will be oj-validation-group's valid property value. When any of the tracked component's valid value changes, oj-validation-group will be notified and will update its own valid value if it has changed.

This is an example of the oj-validation-group wrapping the JET form components. All the JET form components have the valid property. It is not shown in the HTML markup because it is readonly and cannot be set by the application developer. 


<oj-validation-group>
  <oj-form-layout>
    <oj-input-text required value="text" label-hint="input 1"></oj-input-text>
    <oj-text-area value='text' rows="6" label-hint="textarea"></oj-text-area>
    <oj-input-text value="text" label-hint="input 2"></oj-input-text>
    <oj-input-text value="text" label-hint="input 3 longer label"></oj-input-text>
  </oj-form-layout> 
</oj-validation-group>

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.

Attributes

(readonly) valid :string

The current validity state of the oj-validation-group element.

The oj-validation-group's valid property value is calculated from all the enabled components it tracks. The most 'invalid' component's valid property value will be oj-validation-group's valid property value. For example, if all the components are valid except one is "invalidShown", then oj-validation-group's valid value will be "invalidShown". If one is "invalidShown" and one is "invalidHidden", then oj-validation-group's valid value will be "invalidShown" since "invalidShown" is more invalid than "invalidHidden".

When any of the enabled tracked component's valid value changes, oj-validation-group will be notified and will update its own valid value if it has changed. There is no default value for the valid property since it is a read-only property that is calculated on initialization and kept updated if any of its tracked component's valid value changes.

The oj-validation-group does not filter out components that are hidden. Hidden components will be considered in oj-validation-group's valid calculation as long as they are enabled. A hidden enabled component's valid state is no different than a visible enabled component; if there is an error that isn't a deferred error, its valid value is "invalidShown". You can disable any components you do not want considered in oj-validation-group's valid value.

Note: New valid states may be added to the list of valid values in future releases. If so, we will keep the convention where if it is valid, it will start with "valid". If it is invalid, it will start with "invalid". If it is pending, it will start with "pending".

Supported Values:
Name Type Description
"invalidHidden" string The component has invalid messages hidden and no invalid messages showing. An invalid message is one with severity "error" or higher.
"invalidShown" string The component has invalid messages showing. An invalid message is one with severity "error" or higher.
"pending" string The component is waiting for the validation state to be determined. The "pending" state is never set in this release of JET. It will be set in a future release.
"valid" string The component is valid
Supports writeback:
  • true
Since:
  • 4.2
Names
Item Name
Property valid
Property change event validChanged
Property change listener attribute (must be of type function) on-valid-changed
Example

Get the valid property after initialization:

// getter
var valid = myValidationGroupElement.valid;

Methods

focusOn(key) → {void}

If the parameter passed in is "@firstInvalidShown", then it sets focus on the first enabled component with invalid messages showing, if any. If nothing is passed in, it will set focus to the first enabled component being tracked, if any. An enabled component is one that is not disabled or readonly.
Parameters:
Name Type Argument Description
key string <optional>
 "@firstInvalidShown" will focus on first invalidShown enabled component in DOM order, if any. When no parameter is passed in, the method will focus on first enabled component regardless of the valid state, if any. An enabled component is one that is not disabled or readonly.
Since:
  • 4.2.0
Returns:
Type
void
Examples

Focus on the first enabled component showing invalid messages.

validationGroupElem.focusOn("@firstInvalidShown");

Focus on the first enabled component.

validationGroupElem.focusOn();

getProperty(property) → {any}

Retrieves a value for a property or a single subproperty for complex properties.
Parameters:
Name Type Description
property string The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any
Example

Get a single subproperty of a complex property:

var subpropValue = myComponent.getProperty('complexProperty.subProperty1.subProperty2');

setProperties(properties) → {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties Object An object containing the property and value pairs to set.
Returns:
Type
void
Example

Set a batch of properties:

myComponent.setProperties({"prop1": "value1", "prop2.subprop": "value2", "prop3": "value3"});

setProperty(property, value) → {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a [property]Changed event.
Parameters:
Name Type Description
property string The property name to set. Supports dot notation for subproperty access.
value any The new value to set the property to.
Returns:
Type
void
Example

Set a single subproperty of a complex property:

myComponent.setProperty('complexProperty.subProperty1.subProperty2', "someValue");

showMessages() → {void}

Takes all deferred messages and shows them on each enabled component. An enabled component is one that is not disabled or readonly. As a result, the valid property may be updated; e.g., if the valid state was "invalidHidden" before showMessages(), the valid state will become "invalidShown" after showMessages().

If there were no deferred messages this method simply returns.

Since:
  • 4.2.0
Returns:
Type
void
Example

Display all messages including deferred ones.

validationGroupElem.showMessages();