abstract mw.widgets.datetime.DateTimeFormatter

Provides various methods needed for formatting dates and times.

Constructor

new mw.widgets.datetime.DateTimeFormatter(config)abstract #

Create an instance of mw.widgets.datetime.DateTimeFormatter.

Parameters:

Name Type Attributes Description
config Object optional

Configuration options

Properties:
Name Type Attributes Default Description
format string optional
 '@default'

May be a key from the mw.widgets.datetime.DateTimeFormatter.formats, or a format specification as defined by mw.widgets.datetime.DateTimeFormatter#parseFieldSpec and mw.widgets.datetime.DateTimeFormatter#getFieldForTag.
local boolean optional
 false

Whether dates are local time or UTC
fullZones Array.<string> optional

Time zone indicators. Array of 2 strings, for UTC and local time.
shortZones Array.<string> optional

Abbreviated time zone indicators. Array of 2 strings, for UTC and local time.
defaultDate Date optional

Default date, for filling unspecified components. Defaults to the current date and time (with 0 milliseconds).
Mixes in:
Source:

Properties

formats :Objectstatic #

Default format specifications. See the format parameter.

Type:

Source:
Default format specifications.

fullZones :Array.<string>static #

Default time zone indicators.

Type:

Source:
Default time zone indicators.

shortZones :Array.<string>static #

Default abbreviated time zone indicators.

Type:

Source:
Default abbreviated time zone indicators.

Methods

adjustComponent(date, component, delta, mode) → {Date} #

Adjust a date.

Parameters:

Name Type Description
date Date | null

To be adjusted
component string

To adjust
delta number

Adjustment amount
mode string

Adjustment mode:

  • 'overflow': "Jan 32" => "Feb 1", "Jan 33" => "Feb 2", "Feb 0" => "Jan 31", etc.
  • 'wrap': "Jan 32" => "Jan 1", "Jan 33" => "Jan 2", "Jan 0" => "Jan 31", etc.
  • 'clip': "Jan 32" => "Jan 31", "Feb 32" => "Feb 28" (or 29), "Feb 0" => "Feb 1", etc.
Source:

Returns:

Adjusted date

Type
Date
Adjust a date.

datePartIsEqual(date1, date2) → {boolean} #

Test whether the date parts of two Dates are equal.

Parameters:

Name Type Description
date1 Date
date2 Date
Source:

Returns:

Type
boolean
Test whether the date parts of two Dates are equal.

formatSpecValue(v) → {string}protected #

Format a value for a field specification.

'this' must be the field specification object. The intention is that you could just assign this function as the 'formatValue' for each field spec.

Besides the publicly-documented fields, uses the following:

  • values: Enumerated values for the field
  • zeropad: Whether to pad the number with zeros.

Parameters:

Name Type Description
v any
Source:

Returns:

Type
string
Format a value for a field specification.

getCalendarData(current) → {CalendarGridData}abstract #

Get data for a calendar grid.

A "day" object is:

  • display: {string} Display text for the day.
  • date: {Date} Date to use when the day is selected.
  • extra: {string|null} 'prev' or 'next' on days used to fill out the weeks at the start and end of the month.

In any one result object, 'extra' + 'display' will always be unique.

Parameters:

Name Type Description
current Date | null

Current date
Source:

Returns:

Data

Type
CalendarGridData
Get data for a calendar grid.

getCalendarHeadings() → {Array}abstract #

Get the column headings (weekday abbreviations) for a calendar grid.

Null-valued columns are hidden if getCalendarData() returns no "day" object for all days in that column.

Source:

Returns:

string or null

Type
Array
Get the column headings (weekday abbreviations) for a calendar grid.

getComponentsFromDate(date) → {Object}abstract #

Get components from a Date object.

Most specific components are defined by the subclass. "Global" components are:

  • intercalary: {string} Non-falsey values are used to indicate intercalary days.
  • zone: {number} Timezone offset in minutes.

Parameters:

Name Type Description
date Date | null
Source:

Returns:

Components

Type
Object
Get components from a Date object.

getDateFromComponents(components) → {Date} #

Get a Date object from components.

Parameters:

Name Type Description
components Object

Date components
Source:

Returns:

Type
Date
Get a Date object from components.

getDefaultDate() → {Date} #

Get the default date.

Source:

Returns:

Type
Date
Get the default date.

getFieldForTag(tag, params) → {FieldSpecificationObject}abstractprotected #

Turn a tag into a field specification object.

Fields implemented here are:

  • ${intercalary|X|text}: Text that is only displayed when the 'intercalary' component is X.
  • ${not-intercalary|X|text}: Text that is displayed unless the 'intercalary' component is X.
  • ${zone|#}: Timezone offset, "+0000" format.
  • ${zone|:}: Timezone offset, "+00:00" format.
  • ${zone|short}: Timezone from 'shortZones' configuration setting.
  • ${zone|full}: Timezone from 'fullZones' configuration setting.

Parameters:

Name Type Description
tag string
params Array.<string>
Source:

Returns:

Field specification object, or null if the tag+params are unrecognized.

Type
FieldSpecificationObject
Turn a tag into a field specification object.

getFieldSpec() → {Array} #

Fetch the field specification array for this object.

See parseFieldSpec for details on the return value structure.

Source:

Returns:

Type
Array
Fetch the field specification array for this object.

getLocal() → {boolean} #

Whether dates are in local time or UTC.

Source:

Returns:

True if local time

Type
boolean
Whether dates are in local time or UTC.

localChangesDatePart(date) → {boolean} #

Test whether toggleLocal() changes the date part.

Parameters:

Name Type Description
date Date
Source:

Returns:

Type
boolean
Test whether toggleLocal() changes the date part.

mergeDateAndTime(datepart, timepart) → {Date} #

Create a new Date by merging the date part from one with the time part from another.

Parameters:

Name Type Description
datepart Date
timepart Date
Source:

Returns:

Type
Date

Create a new Date by merging the date part from one with the time part from another.

parseFieldSpec(format) → {Array}protected #

Parse a format string into a field specification.

The input is a string containing tags formatted as ${tag|param|param...} (for editable fields) and $!{tag|param|param...} (for non-editable fields). Most tags are defined by getFieldForTag, but a few are defined here:

  • ${intercalary|X|text}: Text that is only displayed when the 'intercalary' component is X.
  • ${not-intercalary|X|text}: Text that is displayed unless the 'intercalary' component is X.

Elements of the returned array are strings or objects. Strings are meant to be displayed as-is. Objects are as returned by getFieldForTag.

Parameters:

Name Type Description
format string
Source:

Returns:

Type
Array
Parse a format string into a field specification.

parseSpecValue(v) → {number|string|null}protected #

Parse a value for a field specification.

'this' must be the field specification object. The intention is that you could just assign this function as the 'parseValue' for each field spec.

Besides the publicly-documented fields, uses the following:

  • values: Enumerated values for the field

Parameters:

Name Type Description
v string
Source:

Returns:

Type
number | string | null
Parse a value for a field specification.

sameCalendarGrid(date1, date2) → {boolean}abstract #

Test whether two dates are in the same calendar grid.

Parameters:

Name Type Description
date1 Date
date2 Date
Source:

Returns:

Type
boolean
Test whether two dates are in the same calendar grid.

timePartIsEqual(date1, date2) → {boolean} #

Test whether the time parts of two Dates are equal.

Parameters:

Name Type Description
date1 Date
date2 Date
Source:

Returns:

Type
boolean
Test whether the time parts of two Dates are equal.

toggleLocal(flag) → {mw.widgets.datetime.DateTimeFormatter} #

Toggle whether dates are in local time or UTC.

Parameters:

Name Type Attributes Description
flag boolean optional

Set the flag instead of toggling it
Source:

Fires:

Returns:

Type
mw.widgets.datetime.DateTimeFormatter
Toggle whether dates are in local time or UTC.

Type Definitions

CalendarGridData #

Type:

Properties:

Name Type Attributes Description
header string

String to display as the calendar header
monthComponent string

Component to adjust by ±1 to change months.
dayComponent string

Component to adjust by ±1 to change days.
weekComponent string optional

Component to adjust by ±1 to change weeks. If omitted, the dayComponent should be adjusted by ±the number of non-nullable columns returned by this.getCalendarHeadings() to change weeks.
rows Array

Array of arrays of "day" objects or null/undefined.
Source:

FieldSpecificationObject #

Type:

Properties:

Name Type Description
component string | null

Date component corresponding to this field, if any.
editable boolean

Whether this field is editable.
type string

What kind of field this is:

  • 'static': The field is a static string; component will be null.
  • 'number': The field is generally numeric.
  • 'string': The field is generally textual.
  • 'boolean': The field is a boolean.
  • 'toggleLocal': The field represents this.getLocal(). Editing should directly call this.toggleLocal().
calendarComponent boolean

Whether this field is part of a calendar, e.g. part of the date instead of the time.
size number

Maximum number of characters in the field (when the 'intercalary' component is falsey). If 0, the field should be hidden entirely.
intercalarySize Object.<string, number>

Map from 'intercalary' component values to overridden sizes.
value string

For type='static', the string to display.
formatValue function

A function to format a component value as a display string.
parseValue function

A function to parse a display string into a component value. If parsing fails, returns undefined.
Source:

Events

local(local) #

A local event is emitted when the 'local' flag is changed.

Parameters:

Name Type Description
local boolean

Whether dates are local time
Source:
A local event is emitted when the 'local' flag is changed.