Oracle JET elements that accept user input, such as oj-input-date, already include an implicit converter that is used when parsing user input. However, you can also specify an explicit converter on the element that will be used instead when converting data from the model for display on the page, and vice versa. An explicit converter is required if you want to include timezone data.

For example, the following code sample shows a portion of a form containing an oj-input-date component that uses the default converter supplied by the component implicitly. The highlighted code shows the oj-input-date component.

<oj-form-layout id="datetime-converter-example">
  <oj-input-date id="date1" value="{{date}}"
                 label-hint="input date with no converter"
                 help.instruction="enter a date in your preferred format and we 
                                   will attempt to figure it out">
  </oj-input-date>
</oj-form-layout>

The script to create the view model for this example is shown below.

import * as ko from 'knockout';
import 'ojs/ojformlayout';
import 'ojs/ojdatetimepicker';
import { IntlConverterUtils } from 'ojs/ojconverterutils-i18n';

class DemoViewModel {

  date: ko.Observable<string>;

  constructor() {

    this.date = ko.observable
        (IntlConverterUtils.dateToLocalIsoDateString(new Date()));
    
  }
}

export = IncidentsViewModel;

define(['knockout', 'ojs/ojconverterutils-i18n', 'ojs/ojknockout', 
  'ojs/ojdatetimepicker', 'ojs/ojformlayout'],

  function (ko, ConverterUtilsI18n) {

    function DemoViewModel() {

        const date = new Date();
        this.value = ko.observable
                (ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(date));
     }
 
  return DemoViewModel;
  }
);

When the user runs the page, the oj-input-date element displays an input field with the expected date format. In this example, the element also displays a hint when the user hovers over the input field, and it displays a calendar when the user clicks in the input field. If the user inputs data that is not in the expected format, the built-in converter displays an error message with the expected format.

Description of the illustration input_converter_default.png

<div class="oj-flex">
  <div class="oj-flex-item">
    <oj-label for="date2">input date</oj-label>
  </div>
  <div class="oj-flex-item">
    <oj-input-date
      id="date2"
      value="{{date}}"
      help.instruction="enter a date in your preferred format and we will attempt 
                        to figure it out"
      converter='{ "type":"datetime",
                    "options": {"year": "numeric", "month": "long", 
                    "day": "numeric"}}'>
    </oj-input-date>
  </div>
</div>

You can create custom converters in Oracle JET by extending Converter or by duck typing it. You can also create a custom converter factory to register the converter with Oracle JET and make it easier to instantiate the converter.

Custom converters can be used with Oracle JET components, provided they don't violate the integrity of the component. As with the built-in Oracle JET converters, you can also use them directly on the page.

The following image shows an implementation of a custom converter that converts the current date to a relative term. The Schedule For column uses a RelativeDateTimeConverter to convert the date that the page is run in the en-US locale to display Today, Tomorrow, and the date in two days.

Description of the illustration input_convert_custom.png

To create and use a custom converter in Oracle JET:

1. Define the custom converter.

   The Oracle JET Cookbook’s Custom Converter sample uses RelativeDateTimeConverter to wrap the Oracle JET IntlDateTimeConverter by providing a specialized format() method that turns dates close to the current date into relative terms for display. For example, in the en-US locale, the relative terms display Today, Yesterday, and Tomorrow. If a relative notation for the date value does not exist, then the date is formatted using the regular Oracle JET format() method supported by the Oracle JET IntlDateTimeConverter.

   The custom converter relies on the IntlDateTimeConverter converter's formatRelative() method. For additional details about the IntlDateTimeConverter converter's supported methods, see the IntlDateTimeConverter API documentation.

2. Add code to your app that uses the custom converter, as in the following example.

   The code sample below shows how you could add code to your script to use the custom converter.

   let rdConverter = new RelativeDateTimeConverter(relativeDayOptions);

3. Add the Oracle JET element or elements that will use the custom converter to your page.

   The Oracle JET Cookbook includes implementations of the options discussed here. See Converters (Custom).

If you want to use a converter without binding it to an Oracle JET component, create the converter using the constructor for the converter of your choice.

The Oracle JET Cookbook includes a demo that shows how to use the number and date time converters directly in your pages without binding them to an Oracle JET component. In the demo image, the salary is a number formatted as currency, and the start date is an ISO string formatted as a date.

Description of the illustration input_builtin_convert.png

The viewModel defines a salaryConverter method to format a number as currency and a dateConverter that formats the start date using the date format style and medium date format while the view HTML binds to the returned values, as shown in the following snippet for Amy Flanagan’s salary and start date.

. . .
<p>Product Manager</p>
 <span style="white-space:nowrap;"><b>Salary</b>:
<span>
  <oj-bind-text value="[[amySalary]]"></oj-bind-text>
</span>
 </span>
 <br />
 <span style="white-space:nowrap;"><b>Joined</b>:
<span>
  <oj-bind-text value="[[amyStartDate]]"></oj-bind-text>
</span>
. . . 

The Oracle JET Cookbook includes implementations of the options discussed here. See Converters Factory.

Oracle JET editable elements, such as oj-input-text and oj-input-date, set up validators both implicitly, based on certain attributes they support such as required, min, max, and so on, and explicitly by providing a means to set up one or more validators using the component's validators attribute. As with the Oracle JET converters, the validators attribute can be specified either using JSON array notation or can be an array of actual validator instances.

For example, the following code sample shows a portion of a form containing an oj-input-date element that uses the default validator supplied by the component implicitly. The highlighted code shows the HTML5 attribute set on the oj-input-date element. When the oj-input-date reads the min attribute, it creates the implicit DateTimeRangeValidator.

<oj-form-layout id="validator-example">
  <oj-input-date
    id="dateTimeRange1"
    value="{{dateValue1}}"
    min="2000-01-01T08:00:00.000"
    help.instruction="enter a date that falls in the current 
                  millenium and not greater than today's date."
    max="[[todayIsoDate]]"
    label-hint="'min' attribute and 'max' option">
  </oj-input-date>
</oj-form-layout>

The script to create the view model for this example is shown below.

import * as ko from "knockout";
import * as ConverterUtilsI18n from "ojs/ojconverterutils-i18n";
import "ojs/ojknockout";
import "ojs/ojformlayout";
import "ojs/ojdatetimepicker";

class DemoViewModel {
 
  dateValue1: ko.Observable<string>;
  dateValue2: ko.Observable<string>;
  todayIsoDate: ko.Observable<string>;
  milleniumStartIsoDate: ko.Observable<string>;

constructor() {

  this.dateValue1 = ko.observable("");
  this.dateValue2 = ko.observable("");
  this.todayIsoDate = ko.observable(
    ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date())
  );
  this.milleniumStartIsoDate = ko.observable(
    ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date(2000, 0, 1))
    );
  } 
}

export = DemoViewModel;

define([
  "knockout",
  "ojs/ojconverterutils-i18n",
  "ojs/ojknockout",
  "ojs/ojdatetimepicker",
  "ojs/ojformlayout",
], function (
  ko,
  ConverterUtilsI18n
) {
  function DemoViewModel() {

  this.dateValue1 = ko.observable();
  this.dateValue2 = ko.observable();
  this.todayIsoDate = ko.observable(
   ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date())
  );
  this.milleniumStartIsoDate = ko.observable(
   ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date(2000, 0, 1))
  );
 }
  return DemoViewModel;
});

When the user runs the page, the oj-input-date element displays an input field with a calendar icon. The help.instruction attribute set on the element displays below the input field when you click on the input field. If you input data that is not within the expected range, the built-in validator displays an error message with the expected range.

Description of the illustration input_validator_message.png

The error thrown by the Oracle JET validator when validation fails is represented by the ValidatorError object, and the error message is represented by an object of type Message. The messages and hints that Oracle JET validators use when they throw an error are resources that are defined in the translation bundle included with Oracle JET. For more information about messaging in Oracle JET, see Work with User Assistance.

<oj-form-layout id="validator-example">
 <oj-input-date
  id="dateTimeRange2"
  value="{{dateValue2}}"
  validators="[[validators]]"
  help.instruction="enter a date that falls in the current millenium and
                    not greater than today's date."
  label-hint="'dateTimeRange' type in 'validators' option">
 </oj-input-date>
</oj-form-layout>

import * as ko from "knockout";
import * as ConverterUtilsI18n from "ojs/ojconverterutils-i18n";
import AsyncDateTimeRangeValidator 
                = require("ojs/ojasyncvalidator-datetimerange");
import * as DateTimeConverter from "ojs/ojconverter-datetime";
import "ojs/ojknockout";
import "ojs/ojformlayout";
import "ojs/ojdatetimepicker";

class DemoViewModel {
  dateValue1: ko.Observable<string>;
  dateValue2: ko.Observable<string>;
  todayIsoDate: ko.Observable<string>;
  milleniumStartIsoDate: ko.Observable<string>;
  validators: ko.Computed<AsyncDateTimeRangeValidator<string>[]>;

  constructor() {
    this.dateValue1 = ko.observable("");
    this.dateValue2 = ko.observable("");
    this.todayIsoDate = ko.observable(
      ConverterUtilsI18n.IntlConverterUtils.dateToLocalIso(new Date())
    );
    this.milleniumStartIsoDate = ko.observable(
    ConverterUtilsI18n.IntlConverterUtils.
                   dateToLocalIso(new Date(2000, 0, 1))
    );

    this.validators = ko.computed(() => {
      return [
        new AsyncDateTimeRangeValidator({
          max: this.todayIsoDate(),
          min: this.milleniumStartIsoDate(),
          hint: {
            inRange: "Enter a date that falls in the 
                      current millennium.",
          },
          converter: new DateTimeConverter.IntlDateTimeConverter({
            day: "2-digit",
            month: "2-digit",
            year: "2-digit",
          }),
        }),
      ];
    });
  } 
}

export = DemoViewModel;

define([
  "knockout",
  "ojs/ojconverterutils-i18n",
  "ojs/ojasyncvalidator-datetimerange",
  "ojs/ojconverter-datetime",
  "ojs/ojknockout",
  "ojs/ojdatetimepicker",
  "ojs/ojformlayout",
], function (
  ko,
  ConverterUtilsI18n,
  AsyncDateTimeRangeValidator,
  DateTimeConverter
) {
  function DemoViewModel() {
    
    this.dateValue1 = ko.observable();
    this.dateValue2 = ko.observable();
    this.todayIsoDate = ko.observable(
      ConverterUtilsI18n.IntlConverterUtils.
                      dateToLocalIso(new Date())
    );
    this.milleniumStartIsoDate = ko.observable(
      ConverterUtilsI18n.IntlConverterUtils.
             dateToLocalIso(new Date(2000, 0, 1))
    );

    this.validators = ko.computed(
      function () {
        return [
          new AsyncDateTimeRangeValidator({
            max: this.todayIsoDate(),
            min: this.milleniumStartIsoDate(),
            hint: {
              inRange: "Enter a date that falls 
                        in the current millennium.",
            },
            converter: new DateTimeConverter.
                              IntlDateTimeConverter({
              day: "2-digit",
              month: "2-digit",
              year: "2-digit",
            }),
          }),
        ];
      }.bind(this)
    );
  }

  return DemoViewModel;
});

You can create custom validators in Oracle JET by extending Validator or by duck typing it.

Custom validators can be used with Oracle JET components, provided they don't violate the integrity of the component. As with the built-in Oracle JET validators, you can also use them directly on the page. For information about messaging in Oracle JET, see Use the messages-custom Attribute. The following image shows a custom validator that displays an error message if the user’s password doesn’t match.

Description of the illustration input_validator_custom.png

To create and use a custom validator in Oracle JET:

1. Define the custom validator.

   The Oracle JET Cookbook sample defines an equalToPassword custom validator of type Validator. Because the custom validator provides the methods expected of a Validator instance, Oracle JET accepts it.

2. Add code to your app that uses the custom validator.

   The code sample below shows how you could add code to your view page to use the custom validator. In this example, both input fields are defined as oj-c-input-password elements. The first instance validates that the user entered a password that meets the app's password requirements. The second instance uses the equalToPassword validator to verify that the password in the second field is equal to the password entered in the first field.

   <oj-form-layout id="custom-validator-example">
     <oj-c-input-password
       id="password"
       required
       value="{{password}}"
       validators="[[validators]]"
       label-hint="Password"
       mask-icon="visible"></oj-c-input-password>
     <oj-c-input-password
       id="cpassword"
       value="{{passwordRepeat}}"
       validators="[[[equalToPassword]]]"
       label-hint="Confirm Password"
       mask-icon="visible"></oj-c-input-password>
   </oj-form-layout>

   The Oracle JET Cookbook contains the complete code sample discussed in this section. See Validators (Custom).