Class: IntlDateTimeConverter

Oracle® JavaScript Extension Toolkit (JET)
2.0.0

E70325-01

QuickNav

oj. IntlDateTimeConverter extends oj.DateTimeConverter

Version:
  • 2.0.0
Since:
  • 0.6
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 {@li.nk oj.Config#getLocale}. Please note that timezone is currently not supported by the converter.

There are several ways to initialize the converter.
  • 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"
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

calculateWeek(value) → {number}

Returns the calculated week for the isoString value
Parameters:
Name Type Description
value string to return the calculated week of
Source:
Returns:
calculated week.
Type
number

format(value) → {string|Object}

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

Note: Application code that was previosuly passinga JavaScript Date object to this method, can now use the utility function oj.IntlConverterUtils.dateToLocalIso(), to get the proper isoString value.

Parameters:
Name Type Description
value string to be formatted for display which should be a local isoString
Source:
See:
Throws:
a ConverterError both when formatting fails, and if the options provided during initialization cannot be resolved correctly. Also if the iso string value contains time zone information, like the UTC designator (Z) or timezone offsets, an error is thrown.
Type
Error
Returns:
the localized and formatted value suitable for display
Type
string | Object
Example

To convert Javascript Date to an iso string before passing to format

var date = new Date();
var formatted = converter.format(oj.IntlConverterUtils.dateToLocalIso(date));

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

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

Note: Application code that was previosuly passing a JavaScript Date object to this method can now use the utility function oj.IntlConverterUtils.dateToLocalIso to get the proper isoString value.

Parameters:
Name Type 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 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:
See:
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
Example

To convert Javascript Date to an iso string before passing to formatRelative

var formatted = converter.formatRelative(oj.IntlConverterUtils.dateToLocalIso(new Date()));

getHint() → {String}

Retrieves a hint String describing the format the value is expected to be in. THe pattern used is provided through resolvedOptions, except when an actual pattern is set in the options. Otherwise hint is empty.
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) → {string|Object}

Parses the value using the options provided and returns the local 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 local time representation alone is returned.
For options that include both date and time, the iso date and local 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.

Parameters:
Name Type Description
value String | string to parse
Source:
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 | Object
Examples

Parse date, time and date & time values using parse method.

<!-- For date-time values  -->
var options = {pattern: 'MM/dd/yy hh:mm:ss a'};
var conv = oj.Validation.converterFactory('datetime').createConverter(options);
cnv.parse('09/11/14 03:02:01 PM'); // '2014-10-20T15:02:01'

<!-- For date values -->
var options = {pattern: 'MM/dd/yy'};
cnv.parse('09/11/14'); // '2014-10-20'

<!-- For time values -->
var options = {pattern: 'hh:mm:ss a'};
cnv.parse('03:02:01 PM'); // 'T15:02:01'

Convert from iso string to Javascript Date object

var isoString = '2014-10-20T15:02:01';
var date = oj.IntlConverterUtils.isoToLocalDate(converter.parse(isoString));

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