About Oracle JET Validators and Converters

Oracle JET provides converter classes that convert user input strings into the data type expected by the application and validator classes that enforce a validation rule on those input strings.

For example, you can use Oracle JET's oj.IntlDateTimeConverter to convert a user-entered date to a Date object for use by the application's ViewModel and then use oj.DateTimeRangeValidator to validate that input against a specified time range. You can also use converters to convert Date or Number objects to a string suitable for display or convert color object formats.

To retrieve the converter or validator factory for a registered type, Oracle JET provides the oj.Validation class which includes methods to register and retrieve converter and validator factories.

If the converters or validators included in Oracle JET are not sufficient for your application, you can create custom converters or validators. Optionally, you can provide a custom factory that implements the contract for a converter using oj.ConverterFactory or a validator using oj.ValidatorFactory and register the converter or validator with the oj.Validation class. The oj.Validation class enables you to access your custom converter or validator using the same mechanisms as you would use with the Oracle JET standard converters and validators.

Topics:

About Validators

All Oracle JET editable elements support a value attribute and provide UI elements that allow the user to enter or choose a value. These elements also support other attributes that page authors can set that instruct the element how it should validate its value.

An editable element may implicitly create a built-in converter and/or built-in validators for its normal functioning when certain attributes are set.

For example, editable elements that support a required property create the required validator implicitly when the property is set to true. Other elements like oj-input-date, oj-input-date-time, and oj-input-time create a datetime converter to implement its basic functionality.

Topics

Oracle JET Validators

The following table describes the Oracle JET validators and provides links to the API documentation:

Validator	Description	Link to API	Module
`oj.DateTimeRangeValidator`	Validates that the input date is between two dates, between two times, or within two date and time ranges	oj.DateTimeRangeValidator	`ojvalidation-datetime`
`oj.DateRestrictionValidator`	Validates that the input date is not a restricted date	oj.DateRestrictionValidator	`ojvalidation-datetime`
`oj.LengthValidator`	Validates that an input string is within a specified length	oj.LengthValidator	`ojvalidation-base`
`oj.NumberRangeValidator`	Validates that an input number is within a specified range	oj.NumberRangeValidator	`ojvalidation-number`
`oj.RegExpValidator`	Validates that the regular expression matches a specified pattern	oj.RegExpValidator	`ojvalidation-base`
`oj.RequiredValidator`	Validates that a required entry exists	oj.RequiredValidator	`ojvalidation-base`

Oracle JET Component Validation Attributes

The attributes that a component supports are part of its API, and the following validation specific attributes apply to most editable elements.

Element Attribute	Description
`async-validators`	When specified, the validators validate the user input on the server asynchronously.
`converter`	When specified, the `converter` instance is used over any internal converter the element might create. On elements such as `oj-input-text`, you may need to specify this attribute if the value must be processed to and from a number or a date value.
`countBy`	When specified on `oj.LengthValidator`, `countBy` enables you to change the validator’s default counting behavior. By default, this property is set to `codeUnit`, which uses JavaScript's String length property to count a UTF-16 surrogate pair as length === 2. Set this to `codePoint` to count surrogate pairs as length ===1.
`max`	When specified on an Oracle JET element like `oj-input-date` or `oj-input-number`, the element creates an implicit range validator.
`min`	When specified on an Oracle JET element like `oj-input-date` or `oj-input-number`, the component creates an implicit range validator.
`pattern`	When specified on an Oracle JET element like `oj-input-text`, `oj-input-password`, or `oj-text-area`, the component creates an implicit regExp validator using the pattern specified.
`placeholder`	When specified, it displays placeholder values in most elements.
`required`	When specified on an Oracle JET element, the element creates an implicit required validator.
`validators`	When specified, the element uses these validators along with the implicit validators to validate the UI value.

Some editable elements do not support specific validation attributes as they might be irrelevant to its intrinsic functioning. For example, oj-radioset and oj-checkboxset do not support a converter attribute since there is nothing for the converter to convert. For an exact list of attributes and how to use them, refer to the Attributes section in the element’s API documentation. For Oracle JET API documentation, see JavaScript API Reference for Oracle® JavaScript Extension Toolkit (JET). Select the component you're interested in viewing from the API list.

Oracle JET Component Validation Methods

Oracle JET editable elements support the following methods for validation purposes. For details on how to call this method, its parameters and return values, refer to the component’s API documentation.

Element Method	Description
`refresh()`	Use this method when the DOM the element relies on changes, such as the help attribute tooltip on an `oj-label` changing due to a change in locale.
`reset()`	Use this method to reset the element by clearing all messages and messages attributes - `messagesCustom` - and update the element’s display value using the attribute value. User entered values will be erased when this method is called.
`validate()`	Use this method to validate the component using the current display value.

For details on calling a element's method, parameters, and return values, See the Methods section of the element's API documentation in JavaScript API Reference for Oracle® JavaScript Extension Toolkit (JET). You can also find detail on how to register a callback for or bind to the event and for information about what triggers the events. Select the component you're interested in viewing from the API list.

About Converters

The Oracle JET converters include date-time, number, and color converters and are described in the following table.

Converter	Description	Link to API
`oj.ColorConverter`	Converts oj.Color object formats	oj.ColorConverter
`oj.IntlDateTimeConverter`	Converts a string to a `Date` or a `Date` to a string	oj.IntlDateTimeConverter
`oj.IntlNumberConverter`	Converts a string to a number or formats a number or `Number` object value to a string	oj.IntlNumberConverter

Oracle JET Component Converter Options

Oracle JET Converters use the options attribute to allow a range of formatting options for color, number, and date and time values.

Color Converters

Color converters support the following options.

Option Name	Description
`format`	Sets the format of the converted color specification. Allowed values are "rgb" (default), "hsl", "hsv" "hex", and "hex3" (3 digit hex code).

For an exact list of options and methods and how to use them, refer to API documentation of the ColorConverter class. See ColorConverter.

Number Converters

Number converters support a number of options that can be used to format decimal numbers, currency, percentages, or units. Some of the important options are:

Option Name	Description
`style`	Sets the style of number formatting. Allowed values are "decimal" (default), "currency", "percent" or "unit". For decimals, percentages, and units, the locale-appropriate symbols are used for decimal characters (point or comma) and grouping separators (if grouping is enabled).
`currency`	Mandatory when `style` is `"currency"`. Specifies the currency that will be used when formatting the number. The value should be a ISO 4217 alphabetic currency code (such as `USD` or `EUR`).
`currencyDisplay`	Allowed values are "code", "name", and "symbol" (default). When `style` is `currency`, this option specifies if the currency is displayed as its name (such as `Euro`) an ISO 4217 alphabetic currency code (such as `EUR`), or the commonly recognized symbol (such as `€`).
`unit`	Mandatory when `style` is `"unit"`. Allowed values are "byte" or "bit". This option is used for formatting only and cannot be used for parsing. Use this option to format digital units like `10Mb` for bit unit or `10MB` for byte unit. Note that scale is formatted automatically. For example, 1024 (with the `byte` unit set) is interpreted as 1 KB.
`minimumIntegerDigits`	Sets the minimum number of digits before the decimal place. The number is padded with leading zeros if it would not otherwise have enough digits. Allowed values are any integer from 1 to 21.
`minimumFractionDigits`	Sets the minimum number of digits after the decimal place. The number is padded with trailing zeros if it would not otherwise have enough digits. Allowed values are any integer from 0 to 20.
`maximumFractionDigits`	Sets the maximum number of digits after the decimal place. The number is rounded if it has more than the set maximum number of digits. Allowed values are any integer from 0 to 20.
`pattern`	Sets a pattern to use for the number, overriding other options. The pattern uses the symbols specified in the Unicode CLDR for numbers, percent, and currency formats. For the currency format, the `currency` option must be set. Use of the currency symbol (¤) indicates whether it will be displayed or not. For example, {pattern: '¤#,##0', currency: 'USD'}. For the percentage format, if the `style` option is set to 'percent', use of the percentage symbol (%) indicates whether it will be displayed or not. If the `style` option is not set to percent, the percentage symbol is required. For example, {style: 'percent', pattern: "#,##0"}. For the decimal or exponent patterns, the example is {pattern: "#,##0.00"} or {pattern: "0.##E+0"}.
`roundingMode`	Specifies the rounding behavior. Allowed values are `HALF_UP`, `HALF_DOWN`, and `HALF_EVEN`.
`roundDuringParse`	Specifies whether or not to round during parse. Defaults to false; the number converter rounds during format but not during parse.

For an exact list of options and methods and how to use them, refer to API documentation of the IntlNumberConverter class. See IntlNumberConverter.

For an example illustrating the use of Number Converter options, see Number Converter.

DateTime Converters

DateTime converters support a wide array of options that can be used to format date and time values in all common styles across locales. Some of the important options are:

Option Name	Description
`year`	Allowed values are the strings `"2–digit"` (00–99) and `"numeric"` (full year value, default).
`month`	Allowed values are the strings `"2–digit"` (01–12), `"numeric"` (variable digit value such as 1 or 11, default), `"narrow"` (narrow name such as J for January), `"short"` (abbreviated name such as Jan), and `"long"` (wide name such as January).
`day`	Allowed values are the strings `"2–digit"` (01–31) and `"numeric"` (variable digit value such as 1 or 18, default).
`formatType`	Determines the standard date and/or time format lengths to use. Allowed values are "date", "time", "datetime". When set, a value for `dateFormat` or `timeFormat` must be specified where appropriate.
`dateFormat`	Specifies the standard date format length to use when `formatType` is set to "date" or "datetime". Allowed values are "short" (default), "medium", "long", "full".
`timeFormat`	Specifies the standard time format length to use when `formatType` is set to "time" or "datetime". Allowed values are "short" (default), "medium", "long", "full".
`hour`	Allowed values are the strings `"2–digit"` (01–12 or 01–24) and `"numeric"` (variable digit value such as 1 or 23).
`minute`	Allowed values are the strings `"2–digit"` and `"numeric"`. This value is always displayed as 2 digits (00–59).
`second`	Allowed values are the strings `"2–digit"` and `"numeric"`. This value is always displayed as 2 digits (00–59).

For an exact list of options and methods and how to use them, refer to API documentation of the IntlDateTimeConverter class. See IntlDateTimeConverter.

For an example illustrating the use of DateTime Converter options, see DateTime Converter.