Class: IntlDateTimeConverter

Oracle® Fusion Middleware Oracle JavaScript Extension Toolkit (JET)
12c (12.1.4)

E54107-01

QuickNav

oj. IntlDateTimeConverter extends oj.DateTimeConverter

Constructs an immutable instance and initializes it with the options provided. There are several ways to initialize the converter. The converters by default uses the locale symbols for the current page locale (returned by oj.Config#getLocale.
  • Using options defined by the ECMA 402 Specification, these would be the properties year, month, day, hour, minute, second, weekday, era, timeZoneName, hour12
  • Using a custom date and/or time format pattern using the 'pattern' property
  • Using the standard date, datetime and time format lengths defined by Unicode CLDR, these would include the properties formaType, dateFormat, timeFormat.

The options when specified take precendence in the following order:
1. pattern.
2. ECMA options.
3. formatType/dateFormat/timeFormat.

The converter provides great leniency when parsing a user input value to a date in the following ways:

  • Allows use of any character for separators irrespective of the separator specified in the associated pattern. E.g., if pattern is set to 'y-M-d', the following values are all valid - 2013-11-16, 2013/11-16 and 2013aaa11xxx16.
  • Allows specifying 4 digit year in any position in relation to day and month. E.g., 11-2013-16 or 16-11-2013
  • Supports auto-correction of value, when month and day positions are swapped as long as the date is > 12 when working with the Gregorian calendar. E.g., if the pattern is 'y-M-d', 2013-16-11 will be auto-corrected to 2013-11-16. However if both date and month are less or equal to 12, no assumptions are made about the day or month and the value parsed against the exact pattern.
  • Supports auto-correction of value, for the short and long types of weekday and month names. So they can are used anywhere in the value. E.g., if the expected pattern is E, MMM, d, y, all these values are acceptable - Tue, Nov 26 2013 or Nov, Tue 2013 26 or 2013 Tue 26 Nov.
    NOTE: Lenient parsing of narrow era, weekday or month name is not supported because of ambiguity in choosing the right value. So we expect for narrow era, weekday or month option that values be provided either in their short or long forms. E.g., Sat, March 02, 2013.
  • Specifying the weekday is optional. E.g., if the expected pattern is E, MMM, d, y; then entering Nov 26, 2013, is automatically turned to Tuesday Nov 26, 2013. But entering an invalid weekday, i.e., if the weekday does not match the date, an exception is thrown.
  • Leniency rules apply equally no matter which option is used - pattern, ECMA options or formatType

Constructor

new IntlDateTimeConverter()

Properties:
Name Type Argument Description
options Object <optional>
an object literal used to provide an optional information to initialize the converter.

Properties
Name Type Argument Description
year string <optional>
allowed values are "2-digit", "numeric". When no options are set the default value of "numeric" is used.
month string <optional>
specifies how the month is formatted. Allowed values are "2-digit", "numeric", "narrow", "short", "long". The last 3 values behave in the same way as for weekday, indicating the length of the string used. When no options are set the default value of "numeric" is used.
day string <optional>
specifies how the day is formatted. Allowed values are "2-digit", "numeric". When no options are set the default value of "numeric" is used.
hour string <optional>
specifies how the hour is formatted. Allowed values are "2-digit" or "numeric". The hour is displayed using the 12 or 24 hour clock, depending on the locale. See 'hour12' for details.
minute string <optional>
specifies how the minute is formatted. Allowed values are "2-digit", "numeric".
second string <optional>
specifies whether the second should be displayed as "2-digit" or "numeric".
weekday string <optional>
specifies how the day of the week is formatted. If absent, it is not included in the date formatting. Allowed values are "narrow", "short", "long" indicating the length of the string used.
era string <optional>
specifies how the era is included in the formatted date. If absent, it is not included in the date formatting. Allowed values are "narrow", "short", "long".
timeZoneName string <optional>
allowed values are "short", "long".
hour12 boolean <optional>
specifies what time notation is used for formatting the time. A true value uses the 12-hour clock and false uses the 24-hour clock (often called military time in the US). This property is undefined if the hour property is not used when formatting the date.
pattern string <optional>
a localized string pattern, where the the characters used in pattern conform to Unicode CLDR for date time formats. This will override all other options when present.
NOTE: 'pattern' is provided for backwards compatibility with existing apps that may want the convenience of specifying an explicit format mask. Setting a 'pattern' will override the default locale specific format.
formatType string <optional>
determines the 'standard' date and/or time format lengths to use. Allowed values: "date", "time", "datetime". See 'dateFormat' and 'timeFormat' options. When set a value must be specified.
dateFormat string <optional>
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 string <optional>
specifies the standard time format length to use when 'formatType' is set to "time" or "datetime". Allowed values: "short" (default), "medium", "long", "full".
Source:
Examples

Create a date time converter using no options. This uses the default value for year, month, day properties

var converterFactory = oj.Validation.converterFactory("datetime");
converter = converterFactory.createConverter();
var resolved = converter.resolvedOpions();
// logs "day=numeric, month=numeric, year=numeric"
window.console.log("day=" + resolved.day + ", month=" + resolved.month + ", year=" + resolved.year);

Create a date time converter using the ECMA options to represent date

var options = { year:'2-digit', month: '2-digit', day: '2-digit'};
var converterFactory = oj.Validation.converterFactory("datetime");
converter = converterFactory.createConverter(options);

Create a date time converter using the 'pattern' option

var options = {pattern: 'MM-dd-yyyy'}; 
var converterFactory = oj.Validation.converterFactory("datetime");
converter = converterFactory.createConverter(options);

Create a date time converter using the standard format length

var options = {formatType: 'date', dateFormat: 'medium'}; 
var converterFactory = oj.Validation.converterFactory("datetime");
converter = converterFactory.createConverter(options);

Methods

format(value) → {string}

Formats the Date value using the resolved options and returns a String value.
Parameters:
Name Type Description
value Date to be formatted for display
Source:
Throws:
a ConverterError both when formatting fails, and if the options provided during initialization cannot be resolved correctly.
Type
Error
Returns:
the localized and formatted value suitable for display
Type
string

formatRelative(value, relativeOptions) → {string|null}

Formats a Date object as a relative date, using the relativeOptions.
Parameters:
Name Type Description
value Date Date object to be formatted. This value is compared with the current date on the client to arrive at the relative formatted value.
relativeOptions Object an Object literal containing the following properties. The default options are ignored during relative formatting -
  • formatUsing: Specifies the relative formatting convention to use for (calendar or) the date field type. allowed values: "displayName".
    Setting value to 'displayName' uses the relative display name for the instance of the dateField, and one or two past and future instances.
  • dateField: allowed values are: "day", "week", "month", "year"
Source:
Throws:
an instance of oj.ConverterError
Type
Object
Returns:
relative date. null if the value falls out side the supported relative range.
Type
string | null

getHint() → {String}

Retrieves a hint String describing the format the value is expected to be in.
Source:
Returns:
a hint describing the format the value is expected to be in.
Type
String

getOptions() → {Object}

Returns the options called with converter initialization.
Source:
Returns:
an object of options.
Type
Object

Init(options)

Initializes the date time converter instance with the set options.
Parameters:
Name Type Argument Description
options Object <optional>
an object literal used to provide an optional information to initialize the converter.

Source:

isDayNameSet()

Returns true if the day name is shown in the date portion; false otherwise.
Source:

isDaySet()

Returns true if day is shown in the date portion; false otherwise.
Source:

isHourInAMPMSet()

Returns true if 12-hour is set; false otherwise.
Source:

isHourInDaySet()

Returns true if a 24-hour format is set; false otherwise.
Source:

isMilliSecondSet()

Returns true if milliseconds are shown in the time portion; false otherwise.
Source:

isMinuteSet()

Returns true if minutes are shown in the time portion; false otherwise.
Source:

isMonthSet()

Returns true if month is shown in the date portion; false otherwise.
Source:

isSecondSet()

Returns true if seconds are shown in the time portion; false otherwise.
Source:

isYearSet()

Returns true if year is shown in the date portion; false otherwise.
Source:

parse(value) → {Date}

Parses the value using the resolved options provided and returns a Date value.
Parameters:
Name Type Description
value String | string to parse
Source:
Throws:
a ConverterError both when parsing fails, and if the options provided during initialization cannot be resolved correctly.
Type
Error
Returns:
the parsed value as a Date object.
Type
Date

resolvedOptions() → {Object}

Returns an object literal with locale and formatting options computed during initialization of the object. If options was not provided at the time of initialization, the properties will be derived from the locale defaults.
Source:
Throws:
a oj.ConverterError when the options that the converter was initialized with are invalid.
Returns:
an object of resolved options. Properties whose corresponding internal properties are not present are not assigned. More properties may be included as needed.
  • locale - a String value with the language tag of the locale whose localization is used for formatting.
  • numberingSystem: a String value of the numbering system used. E.g. latn
  • era: a String value. One of allowed values - "narrow", "short", "long"
  • year: a String value. One of allowed values - "2-digit", "numeric"
  • month: a String value. One of allowed values - "2-digit", "numeric", "narrow", "short" , "long"
  • weekday: a String value. One of the allowed values - "narrow", "short", "long"
  • day: a String value. One of allowed values - "2-digit", "numeric"
  • hour: String value. One of allowed values - "2-digit", "numeric"
  • minute: a String value. One of allowed values - "2-digit", "numeric"
  • second: a String value. One of allowed values - "2-digit", "numeric"
  • hour12: a Boolean value indicating whether 12-hour format (true) or 24-hour format (false) should be used. It is only relevant when hour is also present.
  • timeZoneName: String value. One of allowed values - "short", "long".
Type
Object