Understanding Oracle JET's Messaging APIs on Editable Components

The Oracle JET framework provides a messaging API to support messaging on Oracle JET editable components.

Editable components include the following:

  • ojCheckboxSet

  • ojColorPalette

  • ojColorSpectrum

  • ojCombobox

  • ojInputDate

  • ojInputDateTime

  • ojInputNumber

  • ojInputPassword

  • ojInputSearch

  • ojInputText

  • ojInputTime

  • ojRadioSet

  • ojSelect

  • ojSlider

  • ojSwitch

  • ojTextArea

Topics:

The Oracle JET Cookbook also includes descriptions and examples for working with each component at: Form Controls.

Oracle JET Editable Component Messaging Options

The following options impact messaging on editable components.

Component Option HTML5 Attribute Description

converter

 

Default converter hint displayed as placeholder text when a placeholder option or HTML5 attribute is not already set.

displayOptions

 

JSON object literal that specifies the location where the component should display auxiliary content such as messages, converterHint, validatorHint, and title in relation to itself. Refer to the component's API documentation for details.

help

 

Help message displayed on the input label when the user hovers over the label or the Help icon. No formatted text is available for the message.

The help definition attribute's value appears when you hover with a mouse, and the attribute's value is read by a screen reader. It does not appear when you set focus, so it is not touch or keyboard accessible. Therefore, do not set the help definition text to something that is required to be able to use the page. The default value is null.

messagesCustom

 

List of messages that the application provides when it encounters business validation errors or messages of other severity type.

messagesHidden

 

List of messages currently hidden on component. These are added by the component when it runs deferred validation. This option is read-only, and you cannot set or change it directly.

messagesShown

 

List of messages currently shown on the component. These include messages generated both by the component and ones provided by the application using the messagesCustom option. This option is read-only, and you cannot set or change it directly.

placeholder

placeholder

The placeholder text to set on the element.

title

title

Displays text in a note window that displays when the user sets focus on the input field. You can format the text string using standard HTML formatting tags.

translations

 

Object containing all translated resources relevant to the component and all its superclasses. Use sub-options to modify the component's translated resources.

validators

 

List of validators used by component when performing validation. Validator hints are displayed in a note window by default.

See the Options section of the component's API documentation in JavaScript API Reference for Oracle® JavaScript Extension Toolkit (JET) for additional details about its messaging options. Select the component you're interested in viewing from the API list.

Note:

When the Oracle JET component is initialized on a component that also has HTML5 validation attributes, then these often drive the initial value of the corresponding option on the component if the value is not already set.

Oracle JET Component Messaging Methods

Editable value components support the following method for messaging purposes.

Component Event Description

showMessages

Moves all deferred messages that are in the messagesHidden option to the messagesShown option. When the user sets focus on the component, the deferred messages will display in the note window.

See the Methods section of the component's API documentation in the JavaScript API Reference for Oracle® JavaScript Extension Toolkit (JET) for details on how to call the method, its parameters, and return value. Select the component you're interested in viewing from the list.

Oracle JET Component Messaging Binding Attributes

Editable value components support the following binding attribute for messaging purposes.

Binding Attribute Description

invalidComponentTracker

Tracks the validity of the Oracle JET component. This attribute is available on all Oracle JET editable component when you use the oj.Component binding. When you bind this option to a Knockout observable, an instance of an oj.InvalidComponentTracker object is set on the observable.

For additional detail about the oj.InvalidComponentTracker object, see oj.InvalidComponentTracker.

Note:

The invalidComponentTracker binding attribute depends upon the ojs/ojknockout-validation module, and you must add the module to your RequireJS bootstrap file. For additional information about the ojs/ojknockout-validation module, see Oracle JET Module Organization. For details about using RequireJS in your application, see Using RequireJS in an Oracle JET Application.

See the Binding Attributes section of the component's API documentation in the JavaScript API Reference for Oracle® JavaScript Extension Toolkit (JET). Select the component you're interested in viewing from the API list.

oj.InvalidComponentTracker

oj.InvalidComponentTracker is a helper object that tracks the validity of a group of components and provides useful properties and methods that allow a page author to enforce validation best practices in Oracle JET applications.

Applications can use this object to:

  • Determine whether there are invalid components in the group that are currently showing messages using the invalidShown property.

  • Determine whether there are invalid components that have deferred messages, such as messages that are currently hidden in the group, using the invalidHidden property.

  • Set focus on the first invalid component showing in the group using the focusOnFirstInvalid() method.

  • Show deferred messages on all tracked components using the showMessages() method.

oj.InvalidComponentTracker updates its state every time one of the editable components it tracks triggers an optionChange event for messagesHidden or messagesShown options. When the messagesCustom option is updated, the messagesShown option is automatically updated to reflect the change, and an optionChange event is also triggered for the messagesShown option.

For details about the oj.InvalidComponentTracker object's fields and methods, see oj.InvalidComponentTracker. For information about using oj.InvalidComponentTracker in your Oracle JET application, see Using a Component's invalidComponentTracker Binding Attribute.