Skip to the main content
View on Github

DateUtils

Create a formatted, locale-aware string representation of a datetime.

This module contains general purpose functions for localizing and displaying date-times by timezone, locale and preferred language.”

Most of the heavy lifting is done by the http://momentjs.com/ |’moments’ js library with the moment-with-locales and moment-timezones add-ons.

Example:

var context = {
   datetime: '2016-10-14 08:00:00+00:00',
   timezone: 'Pacific/Kiritimati',
   language: 'ar',
   format: DateUtils.dateFormats.shortDate
};
localized_date = DateUtils.localize(context);

DateUtils.localize(context)

Renders a localized date/time in a standard format.

Parameters

context: string, - datetime: The (UTC) datetime server-side string. - timezone: {string} (optional) the user set time zone preference, or ‘None’ if unset. This should be in a format like ‘Region/Locale’, e.g. ‘Atlantic/Azores’. Defaults to ‘UTC’. - language: {string} (optional), the user set language, an ISO 639-1 language string, defaults to ‘en’ - format: {object} (optional), a format constant. Defaults to DEFAULT_FORMAT.

Returns: string, A formatted, timezone-offset, internationalized date and time.

DateUtils.stringToMoment()

Converts a string to mutable ‘moment’ datetime object.

The input datetimeString can be just a date, a date and time, or a complex date/time string with TZ offset. This is fairly wide-open, as many strings will satisfy this requirement. (e.g. 01-01-16 and Jan 1, 2016, and 2016-01-01 01:00:00+00:00 will work)

The recommendation is to use a fully informed string, e.g. ‘2016-01-01 01:00:00+00:00’, to limit possible date, time, and timezone ambiguities.

Parameters

  • datetimeString.: string, A string representation of a datetime.

Returns: object, A moment.js UTC datetime object.

DateUtils.localizeTime(dateTimeObject, timezone)

Returns a new time that is offset by the requested timezone.

Parameters

dateTimeObject: Object, A moment.js datetime object.

timezone: string, A timezone representation, e.g. ‘America/New_York’.

Returns: object, A moment.js datetime object in a determined timezone.

DateUtils.getSysTimezone()

Helper function to determine system timezone, and fallback to UTC Determines timezone from argument, falling back to system/browser settings, then UTC.

Returns: string, Will attempt to return a determined timezone string, with a fallback to UTC.

DateUtils.getDisplayTime(localTime, language, format)

Generate a timezone-aware and language-aware string.

This includes a param for standard formatting constants.

Browser preferred language is currently overridden by platform-set language preference. If no preference is set, the function attempts to determine the locale settings (e.g. en-US) from the browser preferences.

This function will default to UTC/en-US display in default format in the case of an unresolvable language or timezone

preferred_language = ‘en’ yields Oct. 14, 2016 09:00 BST

preferred_language = ‘ru’ yields 14 окт 2016 г. 09:00 BST

Parameters

localTime: object, A moment.js datetime object offset to a determined timezone.

language: string, an ISO 639-1 language code (e.g. ‘en-US’, ‘fr’)

format: object, (optional) A desired date format, via the dateFormatEnum.

Returns: string, A language/timezone aware localized string

DateUtils.getDisplayLang(language)

Helper function to determine sys/browser language (if unpassed)

Parameters

language: string, (optional) an ISO 639-1 language code (e.g. ‘en-US’, ‘fr’)

Returns: string, an ISO 639-1 language code (e.g. ‘en-US’, ‘fr’)

DateUtils.getDisplayFormat(format)

Helper function to determine format constant.

Defaults to DEFAULT_FORMAT if malformed or unpassed.

Parameters

format: object, (optional) A format constant.

Returns: string, A format constant.

DateUtils.isValid(candidateVariable)

Helper function to determine variable/context validity.

Parameters

candidateVariable: string, to test

Returns: boolean