Using Oracle JET Messaging

Use the Oracle JET messaging framework to notify an Oracle JET application of a component's messages and validity as well as notify an Oracle JET component of a business validation failure.

Topics:

Tracking Validity of a Group of Editable Components Using Knockout

You can track the validity of a group of editable components by using the invalidComponentTracker binding attribute. This attribute is automatically available on all editable components.

In the markup below, username and password components bind to the same Knockout observable, tracker, allowing for validation to be tracked as a group.

<div id="example">
  <input id="username" type="text" autocomplete="off" name="username" required
    data-bind="ojComponent: {component: 'ojInputText', value: userName,
      validators: [{type: 'regExp', options: {pattern: '[a-zA-Z0-9]{3,}',
        'messageDetail': 'You must enter at least 3 letters or numbers'}}],
      invalidComponentTracker: tracker}">

  <input id="password" type="password" name="password" required
    data-bind="ojComponent: {component: 'ojInputPassword', value: password,
      validators: [{type: 'regExp', options : {pattern: '(?=.*\\d)(?=.*[a-z])(?=.*[A-Z]).{6,}',
        label: 'Password',
        messageSummary : '\'{label}\' too Weak',
        messageDetail: 'You must enter a password that meets our security requirements.'}}],
      invalidComponentTracker: tracker}"/>

  <button data-bind="ojComponent: {component: 'ojButton', label: 'Create',
    disabled: shouldDisableCreate()}></button>
</div>

The example also uses a Create button whose disabled option is bound to the shouldDisableCreate() method so that it is disabled on a validation error.

The code that defines the MemberViewModel(), which includes the definition for the tracker observable, is shown below.

function MemberViewModel()
{
  var self = this;
  self.tracker = ko.observable();

  // USERNAME
  self.userName = ko.observable();
  self.password = ko.observable();

  self.shouldDisableCreate = function()
  {
    // see below
  };
}
ko.applybindings(new MemberViewModel(), document.getElementById("example");

The shouldDisableCreate() function uses the invalidShown property, exposed on the tracker object, to enable the button conditionally on the page.

/**
 * Determines when the Create button will be enabled.
 * - if there are invalid components, currently showing messages, return true.
 * - if we have invalid components, that deferred showing messages, end-user doesn't know
 *   these have errors so return false.
 * - if there are no invalid components return false.
 */
 self.shouldDisableCreate = function()
 {
   var trackerObj = ko.utils.unwrapObservable(self.tracker),
   hasInvalidComponents = ko.utils.unwrapObservable(trackerObj["invalidShown"]);
   return  hasInvalidComponents;
 };

Note:

The invalidComponentTracker 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.

For an example showing the invalidComponentTracker used for cross-field validation, see Cross-Field Validation. For information about using invalidComponentTracker for form validation, see Applying Form Validation Best Practices.

Notifying an Oracle JET Application of a Component's Messages and Validity

You can notify your Oracle JET application of an Oracle JET component's messages and validity using an event listener or the invalidComponentTracker binding attribute.

Topics:

Using the optionChange Event

When there are errors during conversion or validation, the component updates the messagesShown or messagesHidden messages option and triggers an optionChange event. You can register an event listener or callback to be notified of a component's validity.

The following code sample shows how you could add a callback to an ojInputText component for the optionChange event. The callback will log a message to the console showing the previous and current values for the messagesShown and messagesHidden options.

<input id="username"
  data-bind="ojComponent: {component: 'ojInputText', 'value': 'abc',
    'optionChange' : function(event, ui) {usernameMessagesChange( event, ui);}}"/>

<script>
  usernameMessagesChange = function(event, ui)
  {
    if (ui.option && (ui.option === "messagesShown" || ui.option === "messagesHidden"))
      window.console.log("option '"+ ui.option +"' changed from "+ ui.previousValue +" to "+ ui.value);
  };
</script>

Using a Component's invalidComponentTracker Binding Attribute

When this attribute is set on the component, the Oracle JET binding framework registers a custom listener for the optionChange event. This enables the oj.InvalidComponentTracker object to update its state for the components it tracks when their messages options change.

Page authors can use the properties exposed on the tracker object to be notified of changes. For details, see Tracking Validity of a Group of Editable Components Using Knockout.

Notifying an Oracle JET Editable Component of Business Validation Errors

You can notify Oracle JET editable components of business validation errors using the messagesCustom option and the showMessages() method.

Topics:

Using the messagesCustom Option

Your application can use this option to notify the Oracle JET framework components to show new or updated custom messages. These could be a result of business validation that originates in the viewModel layer or on the server. When this option is set the messagesShown option is also updated and the message shows to the user immediately. The messagesCustom option takes an oj.Message object with detail, summary, and severity fields.

In this example, the severity type button is toggled and a message of the selected severity type is pushed onto the messagesCustom array. The messagesCustom option is set on every form control in this example. When the messagesCustom option is changed, it is shown immediately. In this example, the user selected the Error severity type, and the associated messages are shown for the various text input and selection components.

In this example an observable, appMessages, is declared and is bound to the messagesCustom option for various components. The following code describes how you can associate the observable with the messagesCustom option for ojSwitch component .

<input id="switch" data-bind="ojComponent: {
                                 component: 'ojSwitch',
                                 required: true,
                                 value: switchValue,
                                 messagesCustom: appMessages}">

In the corresponding JavaScript file, set the severity type and pass it to the observable, appMessages, to display associated messages.

if (summary && detail)
{
 msgs.push({summary: summary, detail: detail, severity: type});
}
self.appMessages(msgs);

In the example below, an instance of a cross-field custom validator is associated with the emailAddress observable, ensuring that its value is non-empty when the user chooses Email as their contact preference.

In the corresponding JavaScript file you must set the messagesCustom option as emailAddressMessages.

   <input id="emailId"
    data-bind="ojComponent: { 
    component: 'ojInputText',
    invalidComponentTracker: tracker,
    messagesCustom: emailAddressMessages}"/>

For the complete example and code used to create the custom validator, see Cross-Field Validation. The demo uses a custom validator to validate an observable value against another. If validation fails the custom validator updates the messagesCustom option.

Using the showMessages() Method on Editable Components

Use this method to instruct the component to show its deferred messages. When this method is called, the Oracle JET editable component automatically moves all deferred messages in the messagesHidden option to the messagesShown option. This causes the component to display the deferred messages to the user.

The oj.InvalidComponentTracker object uses this method to show deferred messages. For an example, see App Level Validation.