Final Class: IntlDateTimeConverter

Oracle® JavaScript Extension Toolkit (JET)
17.1.0
G12196-01

Since:
  • 0.6.0
Module:
  • ojconverter-datetime

QuickNav

Methods

Type Definitions

Description

Constructs an immutable instance and initializes it with the options provided.

The converter instance uses locale symbols for the locale set on the page (returned by oj.Config.getLocale).

There are several ways to initialize the converter. However, the recommended method involves utilizing the formatType, dateFormat, and timeFormat options. This approach ensures automatic formatting of the date and/or time in a locale-specific manner.

The following initialization methods are available:

  • Using the standard date, datetime and time format lengths such as 'short', 'medium', etc., as defined by Unicode CLDR. For example: formatType: 'date', dateFormat: 'short'.
  • Using options defined by the ECMA 402 Specification, which are year, month, day, hour, minute, second, weekday, era, timeZoneName, hour12. This method is suitable when a specific format is desired irrespective of the locale. However, it's not recommended as it lacks locale sensitivity.
  • Using a custom date and/or time format pattern using the pattern property. This way is deprecated and discouraged since it is not locale sensitive. Applications should not use pattern.

The options when specified take precedence in the following order:

  1. pattern (deprecated). If pattern is set, the ECMA options and formatType/dateFormat/timeFormat are ignored.
  2. ECMA options (not locale sensitive). If pattern is not set, and ECMA options are set, ECMA options are used, and formatType/dateFormat/timeFormat are ignored.
  3. formatType/dateFormat/timeFormat (recommended).

If no options are provided, they default to day:"numeric", month:"numeric", year:"numeric". As this formatting remains consistent across locales and is not sensitive to locale variations, it is not recommended. The recommended approach is to create the converter using the options formatType: "date", dateFormat: "short" to ensure locale sensitivity.

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 day 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 day 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

Lenient parse can be disabled by setting the property lenientParse to "none". In which case the user input must be an exact match of the expected pattern and all the leniency described above will be disabled.


Usage

Signature:

final class IntlDateTimeConverter

Typescript Import Format
//To import this class, use the format below.
import {IntlDateTimeConverter} from "ojs/ojconverter-datetime";

For additional information visit:


Final classes in JET

Classes in JET are generally final and do not support subclassing. At the moment, final is not enforced. However, this will likely change in an upcoming JET release.


Constructor

new IntlDateTimeConverter(options)

Parameters:
Name Type Argument Description
options oj.IntlDateTimeConverter.ConverterOptions <optional>
 an object literal used to provide an optional information to initialize the converter.

Methods

calculateWeek(value) : {number}

Returns the calculated week for the isoString value
Parameters:
Name Type Description
value string to return the calculated week of
Deprecated:
Since Description
11.0.0 This is used internally by the oj-date-picker component, and should not be called by application code.
Returns:

calculated week.

Type
number

compareISODates(isoStr, isoStr2) : {number}

Compares 2 ISO 8601 strings, returning the time difference between the two
Parameters:
Name Type Description
isoStr string first iso string
isoStr2 string second iso string
Returns:

the time difference between isoStr and isoStr2

Type
number

format(value) : {string|null}

Formats the isoString value using the options provided and returns a string value.

The isoStr value could be zulu, offset, or local. And if the value is zulu or offset, then the timezone the converter uses will be the system's timezone if no timeZone option is specified.

Parameters:
Name Type Description
value string to be formatted for display which should be an isoString
See:
Throws:
a ConverterError both when formatting fails, and if the options provided during initialization cannot be resolved correctly.
Type
Error
Returns:

the formatted value suitable for display

Type
string | null

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

Formats an ISOString as a relative date time, using the relativeOptions.

Parameters:
Name Type Argument Description
value string value to be formatted. This value is compared with the current date on the client to arrive at the relative formatted value.
relativeOptions Object <optional>
 an Object literal containing the following properties. The default options are ignored during relative formatting -
Properties
Name Type Argument Description
formatUsing string <optional>
 Specifies the relative formatting convention to. Allowed values are "displayName" and "calendar". Setting value to 'displayName' uses the relative display name for the instance of the dateField, and one or two past and future instances. When omitted we use the implicit rules.
dateField string <optional>
 To be used in conjunction of 'displayName' value of formatUsing attribute. Allowed values are: "day", "week", "month", "year", "hour", "minute", "second".
relativeTime string <optional>
 Allowed values are: "fromNow", "toNow". "fromNow" means the system's current date is the reference and "toNow" means the value attribute is the reference. Default "fromNow".
dateOnly boolean <optional>
 A boolean value that can be used in conjunction with "calendar" of formatUsing attribute. When set to true date only format is used. Example: "Sunday" instead of "Sunday at 2:30 PM". Default value is false.
timeZone string <optional>
 The timeZone attribute can be used to specify the time zone of the value parameter. The system’s time zone is used for the current time. If timeZone attribute is not specified, we use the system’s time zone for both. The value parameter, which is an iso string, can be Z or contain and offset, in this case the timeZone attribute is overwritten.
Deprecated:
Since Description
11.0.0 Use Intl.RelativeTimeFormat
See:
Throws:
an instance of ConverterError
Type
Object
Returns:

relative date. null if the value falls out side the supported relative range.

Type
string | null

getAvailableTimeZones : {Array}

Gets the supported timezones for the converter. The returned value is an array of objects. Each object represents a timezone and contains 2 properties:

Property Description
id IANA timezone ID
displayName
    It is the concatenation of 3 string:
  • UTC timezone offset
  • City name
  • Generic time zone name

Deprecated:
Since Description
11.0.0 Use TimeZoneUtils.getAvailableTimeZones instead.
Since:
  • 11.0.0
Returns:

supported timezones

Type
Array

getHint : {null}

It returns null for the placeholder hint. There is no default placeholder hint when using IntlDateTimeConverter.
Returns:

hint for the converter.

Type
null

getOptions : {oj.IntlDateTimeConverter.ConverterOptions}

Returns the options called with converter initialization.
Deprecated:
Since Description
11.0.0 Use resolvedOptions.
Returns:

an object of options.

Type
oj.IntlDateTimeConverter.ConverterOptions

isDayNameSet : {boolean}

Returns true if the day name is shown in the date portion; false otherwise.
Deprecated:
Since Description
11.0.0 Use resolvedOptions()["weekday"] !== undefined
Returns:
Type
boolean

isDaySet : {boolean}

Returns true if day is shown in the date portion; false otherwise.
Deprecated:
Since Description
11.0.0 Use resolvedOptions()["day"] !== undefined
Returns:
Type
boolean

isHourInAMPMSet : {boolean}

Returns true if 12-hour is set; false otherwise.
Deprecated:
Since Description
11.0.0 Use !!(resolvedOptions()["hour"] && resolvedOptions()["hour12"])
Returns:
Type
boolean

isHourInDaySet : {boolean}

Returns true if a 24-hour format is set; false otherwise.
Deprecated:
Since Description
11.0.0 Use !!(resolvedOptions()["hour"] && !resolvedOptions()["hour12"])
Returns:
Type
boolean

isMilliSecondSet : {boolean}

Returns true if milliseconds are shown in the time portion; false otherwise.
Deprecated:
Since Description
11.0.0 Use resolvedOptions()["millisecond"] !== undefined
Returns:
Type
boolean

isMinuteSet : {boolean}

Returns true if minutes are shown in the time portion; false otherwise.
Deprecated:
Since Description
11.0.0 Use resolvedOptions()["minute"] !== undefined
Returns:
Type
boolean

isMonthSet : {boolean}

Returns true if month is shown in the date portion; false otherwise.
Deprecated:
Since Description
11.0.0 Use resolvedOptions()["month"] !== undefined
Returns:
Type
boolean

isSecondSet : {boolean}

Returns true if seconds are shown in the time portion; false otherwise.
Deprecated:
Since Description
11.0.0 Use resolvedOptions()["second"] !== undefined
Returns:
Type
boolean

isYearSet : {boolean}

Returns true if year is shown in the date portion; false otherwise.
Deprecated:
Since Description
11.0.0 Use resolvedOptions()["year"] !== undefined
Returns:
Type
boolean

parse(value) : {string|null}

Parses the value using the options provided and returns the date and time as a string expressed using the ISO-8601 format (http://en.wikipedia.org/wiki/ISO_8601).

For converter options specific to a date, the iso date representation alone is returned.
For time only options, the iso time representation alone is returned.
For options that include both date and time, the iso date and time representation is returned.

For convenience, if one wishes to retrieve a JavaScript Date object from the local isoString, a utility function oj.IntlConverterUtils.isoToLocalDate is provided. Or oj.IntlConverterUtils.isoToDate if one wish to utilize the timezone of the isoString.

Parameters:
Name Type Description
value string to parse
See:
Throws:
a ConverterError both when parsing fails, and if the options provided during initialization cannot be resolved correctly. Parsing can also fail when the value includes a time zone.
Type
Error
Returns:

the parsed value as an ISOString.

Type
string | null

resolvedOptions : {oj.IntlDateTimeConverter.ConverterOptions}

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.
Throws:
a 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.

Type
oj.IntlDateTimeConverter.ConverterOptions

Type Definitions

ConverterOptions

Properties:
Name Type Argument Description
dateFormat 'short' | 'medium' | 'long' | 'full' <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".

Option Example
short 9/20/15
medium Sep 20, 2015
long September 20, 2015
full Sunday, September 20, 2015

day '2-digit' | 'numeric' <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.

Option Description Example
2-digit 2 digit representation of the day in month, padded: 01-31. 1 => 01, 27 => 27
numeric variable digit representation of the day in month depending on the value. 1, 31

era 'narrow' | 'short' | 'long' <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". Although allowed values are narrow, short, long, we only display era in abbreviated format: BC, AD.
formatType 'date' | 'time' | 'datetime' <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.

Option Description Example
datetime date and time portions are displayed. "September 20, 2015 12:04 PM", "September 20, 2015 12:05:35 PM Pacific Daylight Time"
date date portion only is displayed. "September 20, 2015"
time time portion only is displayed. “12:05:35�?

hour '2-digit' | 'numeric' <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.

Option Description Example
2-digit 2 digit representation of the hour, padded: 01-24 depending on the locale. 1 => 01, 24 => 24
numeric variable digit representation of the day in month depending on the value. 1, 24

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.

Option Example
true T13:10 is formatted as "1:10 PM"
false T13:10 is formatted as "13:10"

hourCycle 'h11' | 'h12' | 'h23' | 'h24' <optional>
 The hour cycle to use. Possible values are "h11", "h12", "h23", or "h24". hour12 option takes precedence in case both options have been specified.

Option Example
h11 T00:00:00 is formatted as "00:00:00 AM"
h12 T00:00:00 is formatted as "12:00:00 AM"
h23 T00:00:00 is formatted as "00:00:00"
h24 T00:00:00 is formatted as "24:00:00"

isoStrFormat 'offset' | 'zulu' | 'local' | 'auto' <optional>
 specifies the time zone offset of the ISO string that is returned from the parse method. isoStrFormat only applies to the parse method. The possible values of isoStrFormat are: "offset", "zulu", "local". The default is offset. local applies to time-only and date-only ISO strings. If the returned ISO string is date-time, local is ignored and the date-time ISO string is returned with offset. This is necessary for the result to be a valid RFC-3339 date-time so that it may be transferred over REST. Note: auto is deprecated and ignored since the default is now offset.

Option Description Example
offset time zone offset from UTC. 2016-01-05T11:30:00-08:00
T11:30:00-06:00
zulu zulu time or UTC time. 2016-01-05T19:30:00Z
local local date or time, does not contain time zone offset. T19:30:00
2016-01-05

lenientParse 'full' | 'none' <optional>
 The lenientParse property can be used to enable or disable lenient parsing. Allowed values: "full" (default), "none".

By default the lenient parse is enabled and the leniency rules described above will be used. When lenientParse is set to "none" the lenient parse is disabled and the user input must match the expected input otherwise an exception will be thrown.
millisecond 'numeric' <optional>
 specifies how the minute is formatted. Allowed value is "numeric". millisecond is always displayed as 3-digits except the case where only millisecond is present (hour and minute not specified) in which case we display it as no-padded number, example: .5
minute '2-digit' | 'numeric' <optional>
 specifies how the minute is formatted. Allowed values are "2-digit", "numeric". Although allowed values for minute are numeric and 2-digit, minute is always displayed as 2 digits: 00-59.
month '2-digit' | 'numeric' | 'narrow' | 'short' | 'long' <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.

Option Description Example
2-digit 2 digit representation of the month, padded: 01-12. 1 => 01, 12 => 12
numeric variable digit representation of the month depending on the value. 1, 11
narrow narrow name of the month. J
short abbreviated name of the month. Jan
long wide name of the month. January

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. NOTE: The supported tokens for timezone are of 'Z', 'VV', and 'X'.

Letter Date or Time Component Examples
G, GG, GGG Era designator AD
y numeric representation of year 1, 2014
yy 2-digit representation of year 01, 14
yyyy 4-digit representation of year 0001, 2014
M Numeric representation of month in year: (1-12) 1, 12
MM 2-digit representation of month in year: (01-12) 01, 12
MMM Formatted name of the month, abbreviated Jan
MMMM Formatted name of the month, wide January
MMMMM Formatted name of the month, narrow J
LLL Stand-alone name of the month, abbreviated Jan
LLLL Stand-alone name of the month, wide January
LLLLL Stand-alone name of the month, narrow J
d Numeric representation of day in month (1-31) 1, 21
dd 2-digit representation of day in month (01-31) 01, 21
E, EE, EEE Formatted name of day in week, abbreviated Tue
EEEE Formatted name of day in week, wide Tuesday
EEEEE Formatted name of day in week, narrow T
c, cc, ccc Stand-alone name of day in week, abbreviated Tue
cccc Stand-alone name of day in week, wide Tuesday
ccccc Stand-alone name of day in week, narrow T
a am/pm marker PM
H Numeric hour in day (0-23) 1, 23
HH 2-digit hour in day (00-23) 01, 23
h Numeric hour in am/pm (1-12) 1, 12
hh 2-digit hour in day (01-12) 01, 12
k Numeric hour in day (1-24) 1, 24
kk 2-digit hour in day (1-24) 01, 24
K Numeric hour in am/pm (0-11) 1, 11
KK 2-digit hour in am/pm (0-11) 01, 11
m, mm 2-digit minute in hour (00-59) 05, 59
s, ss 2-digit second in minute (00-59) 01, 59
S Numeric Millisecond (0-999) 1, 999
SS 2-digit Millisecond (00-999) 01, 999
SSS 3-digit Millisecond (000-999) 001, 999
z, zz, zzz Abbreviated time zone name PDT, PST
zzzz Full time zone name Pacific Standard Time, Pacific Daylight Time
Z, ZZ, ZZZ Sign hours minutes -0800
X Sign hours -08
XX Sign hours minutes -0800
XXX Sign hours:minutes -08:00
VV Time zone ID America/Los_Angeles
Deprecated:
Since Description
11.0.0 Applications should not use pattern because it is not locale sensitive. Use other options instead like formatType, dateFormat and timeFormat, and if needed, set the locale to be the preferred locale.
second '2-digit' | 'numeric' <optional>
 specifies whether the second should be displayed as "2-digit" or "numeric". Although allowed values for second are numeric and 2-digit, second is always displayed as 2 digits: 00-59.
timeFormat 'short' | 'medium' | 'long' | 'full' <optional>
 specifies the standard time format length to use when 'formatType' is set to "time" or "datetime". Allowed values: "short" (default), "medium", "long", "full".

Option Example
short 12:11 PM
medium 12:11:23 PM
long 12:12:19 PM PDT
full 12:12:37 PM Pacific Daylight Time

timeZone string <optional>
 The possible values of the timeZone property are valid IANA timezone IDs. If the users want to pass an offset, they can use one of the Etc/GMT timezone IDs.

Option Example
IANA ID America/Los_Angeles, Europe/Paris
Offset Etc/GMT-8. The offset is positive if the local time zone is behind UTC and negative if it is ahead. The offset range is between Etc/GMT-14 and Etc/GMT+12 (UTC-12 and UTC+14). Which means that Etc/GMT-8 is equivalent to UTC+08.

timeZoneName 'short' | 'long' <optional>
 allowed values are "short", "long".

Option Description Example
short short name of the time zone. short: short name of the time zone: PDT, PST, EST, EDT. Note: Not all locales have translations for short time zone names, in this case we display the English short name
long short name of the time zone. Pacific Standard Time, Pacific Daylight Time.

two-digit-year-start number <optional>
 the 100-year period 2-digit year. During parsing, two digit years will be placed in the range two-digit-year-start to two-digit-year-start + 100 years. The default is 1950.

Example: if two-digit-year-start is 1950, 10 is parsed as 2010

Example: if two-digit-year-start is 1900, 10 is parsed as 1910

weekday 'narrow' | 'short' | 'long' <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.

Option Description Example
narrow narrow name of the day of week. M
short abbreviated name of the day of week. Mon
long wide name of the day of week. Monday

year '2-digit' | 'numeric' <optional>
 allowed values are "2-digit", "numeric". When no options are set the default value of "numeric" is used.

Option Description Example
2-digit 2 digit representation of the year, padded: 00-99. 2001 => 01, 2016 => 16
numeric variable digit representation of the year depending on the value. 2010, 199