4 * Provides various methods needed for formatting dates and times.
8 * @mixins OO.EventEmitter
11 * @param {Object} [config] Configuration options
12 * @cfg {string} [format='@default'] May be a key from the {@link #static-formats static formats},
13 * or a format specification as defined by {@link #method-parseFieldSpec parseFieldSpec}
14 * and {@link #method-getFieldForTag getFieldForTag}.
15 * @cfg {boolean} [local=false] Whether dates are local time or UTC
16 * @cfg {string[]} [fullZones] Time zone indicators. Array of 2 strings, for
18 * @cfg {string[]} [shortZones] Abbreviated time zone indicators. Array of 2
19 * strings, for UTC and local time.
20 * @cfg {Date} [defaultDate] Default date, for filling unspecified components.
21 * Defaults to the current date and time (with 0 milliseconds).
23 mw
.widgets
.datetime
.DateTimeFormatter
= function MwWidgetsDatetimeDateTimeFormatter( config
) {
24 var statick
= this.constructor[ 'static' ];
26 statick
.setupDefaults();
31 fullZones
: statick
.fullZones
,
32 shortZones
: statick
.shortZones
36 OO
.EventEmitter
.call( this );
39 if ( statick
.formats
[ config
.format
] ) {
40 this.format
= statick
.formats
[ config
.format
];
42 this.format
= config
.format
;
44 this.local
= !!config
.local
;
45 this.fullZones
= config
.fullZones
;
46 this.shortZones
= config
.shortZones
;
47 if ( config
.defaultDate
instanceof Date
) {
48 this.defaultDate
= config
.defaultDate
;
50 this.defaultDate
= new Date();
52 this.defaultDate
.setMilliseconds( 0 );
54 this.defaultDate
.setUTCMilliseconds( 0 );
61 OO
.initClass( mw
.widgets
.datetime
.DateTimeFormatter
);
62 OO
.mixinClass( mw
.widgets
.datetime
.DateTimeFormatter
, OO
.EventEmitter
);
67 * Default format specifications. See the {@link #format format} parameter.
73 mw
.widgets
.datetime
.DateTimeFormatter
[ 'static' ].formats
= {};
76 * Default time zone indicators
80 * @property {string[]}
82 mw
.widgets
.datetime
.DateTimeFormatter
[ 'static' ].fullZones
= null;
85 * Default abbreviated time zone indicators
89 * @property {string[]}
91 mw
.widgets
.datetime
.DateTimeFormatter
[ 'static' ].shortZones
= null;
93 mw
.widgets
.datetime
.DateTimeFormatter
[ 'static' ].setupDefaults = function () {
94 if ( !this.fullZones
) {
96 mw
.msg( 'timezone-utc' ),
97 mw
.msg( 'timezone-local' )
100 if ( !this.shortZones
) {
103 this.fullZones
[ 1 ].substr( 0, 1 ).toUpperCase()
105 if ( this.shortZones
[ 1 ] === 'Z' ) {
106 this.shortZones
[ 1 ] = 'L';
114 * A `local` event is emitted when the 'local' flag is changed.
122 * Whether dates are in local time or UTC
124 * @return {boolean} True if local time
126 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.getLocal = function () {
131 * Toggle whether dates are in local time or UTC
133 * @param {boolean} [flag] Set the flag instead of toggling it
137 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.toggleLocal = function ( flag
) {
138 if ( flag
=== undefined ) {
143 if ( this.local
!== flag
) {
145 this.emit( 'local', this.local
);
151 * Get the default date
155 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.getDefaultDate = function () {
156 return new Date( this.defaultDate
.getTime() );
160 * Fetch the field specification array for this object.
162 * See {@link #parseFieldSpec parseFieldSpec} for details on the return value structure.
166 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.getFieldSpec = function () {
167 return this.parseFieldSpec( this.format
);
171 * Parse a format string into a field specification
173 * The input is a string containing tags formatted as ${tag|param|param...}
174 * (for editable fields) and $!{tag|param|param...} (for non-editable fields).
175 * Most tags are defined by {@link #getFieldForTag getFieldForTag}, but a few
177 * - ${intercalary|X|text}: Text that is only displayed when the 'intercalary'
179 * - ${not-intercalary|X|text}: Text that is displayed unless the 'intercalary'
182 * Elements of the returned array are strings or objects. Strings are meant to
183 * be displayed as-is. Objects are as returned by {@link #getFieldForTag getFieldForTag}.
186 * @param {string} format
189 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.parseFieldSpec = function ( format
) {
190 var m
, last
, tag
, params
, spec
,
192 re
= /(.*?)(\$(!?)\{([^}]+)\})/g;
195 while ( ( m
= re
.exec( format
) ) !== null ) {
198 if ( m
[ 1 ] !== '' ) {
202 params
= m
[ 4 ].split( '|' );
203 tag
= params
.shift();
204 spec
= this.getFieldForTag( tag
, params
);
206 if ( m
[ 3 ] === '!' ) {
207 spec
.editable
= false;
214 if ( last
< format
.length
) {
215 ret
.push( format
.substr( last
) );
222 * Turn a tag into a field specification object
224 * Fields implemented here are:
225 * - ${intercalary|X|text}: Text that is only displayed when the 'intercalary'
227 * - ${not-intercalary|X|text}: Text that is displayed unless the 'intercalary'
229 * - ${zone|#}: Timezone offset, "+0000" format.
230 * - ${zone|:}: Timezone offset, "+00:00" format.
231 * - ${zone|short}: Timezone from 'shortZones' configuration setting.
232 * - ${zone|full}: Timezone from 'fullZones' configuration setting.
236 * @param {string} tag
237 * @param {string[]} params
238 * @return {Object|null} Field specification object, or null if the tag+params are unrecognized.
239 * @return {string|null} return.component Date component corresponding to this field, if any.
240 * @return {boolean} return.editable Whether this field is editable.
241 * @return {string} return.type What kind of field this is:
242 * - 'static': The field is a static string; component will be null.
243 * - 'number': The field is generally numeric.
244 * - 'string': The field is generally textual.
245 * - 'boolean': The field is a boolean.
246 * - 'toggleLocal': The field represents {@link #getLocal this.getLocal()}.
247 * Editing should directly call {@link #toggleLocal this.toggleLocal()}.
248 * @return {number} return.size Maximum number of characters in the field (when
249 * the 'intercalary' component is falsey). If 0, the field should be hidden entirely.
250 * @return {Object.<string,number>} return.intercalarySize Map from
251 * 'intercalary' component values to overridden sizes.
252 * @return {string} return.value For type='static', the string to display.
253 * @return {function(Mixed): string} return.formatValue A function to format a
254 * component value as a display string.
255 * @return {function(string): Mixed} return.parseValue A function to parse a
256 * display string into a component value. If parsing fails, returns undefined.
258 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.getFieldForTag = function ( tag
, params
) {
263 case 'not-intercalary':
264 if ( params
.length
< 2 || !params
[ 0 ] ) {
271 value
: params
.slice( 1 ).join( '|' ),
275 if ( tag
=== 'intercalary' ) {
276 spec
.intercalarySize
[ params
[ 0 ] ] = spec
.value
.length
;
278 spec
.size
= spec
.value
.length
;
279 spec
.intercalarySize
[ params
[ 0 ] ] = 0;
284 switch ( params
[ 0 ] ) {
287 c
= params
[ 0 ] === '#' ? '' : ':';
293 formatValue: function ( v
) {
296 o
= new Date().getTimezoneOffset();
297 r
= String( Math
.abs( o
) % 60 );
298 while ( r
.length
< 2 ) {
301 r
= String( Math
.floor( Math
.abs( o
) / 60 ) ) + c
+ r
;
302 while ( r
.length
< 4 + c
.length
) {
305 return ( o
<= 0 ? '+' : '−' ) + r
;
307 return '+00' + c
+ '00';
310 parseValue: function ( v
) {
312 v
= String( v
).trim();
313 if ( ( m
= /^([+-−])([0-9]{1,2}):?([0-9]{2})$/.test( v
) ) ) {
314 return ( m
[ 2 ] * 60 + m
[ 3 ] ) * ( m
[ 1 ] === '+' ? -1 : 1 );
327 values
: params
[ 0 ] === 'short' ? this.shortZones
: this.fullZones
,
328 formatValue
: this.formatSpecValue
,
329 parseValue
: this.parseSpecValue
331 spec
.size
= Math
.max
.apply(
332 null, $.map( spec
.values
, function ( v
) { return v
.length
; } )
344 * Format a value for a field specification
346 * 'this' must be the field specification object. The intention is that you
347 * could just assign this function as the 'formatValue' for each field spec.
349 * Besides the publicly-documented fields, uses the following:
350 * - values: Enumerated values for the field
351 * - zeropad: Whether to pad the number with zeros.
357 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.formatSpecValue = function ( v
) {
358 if ( v
=== undefined || v
=== null ) {
362 if ( typeof v
=== 'boolean' || this.type
=== 'toggleLocal' ) {
367 return this.values
[ v
];
371 if ( this.zeropad
) {
372 while ( v
.length
< this.size
) {
380 * Parse a value for a field specification
382 * 'this' must be the field specification object. The intention is that you
383 * could just assign this function as the 'parseValue' for each field spec.
385 * Besides the publicly-documented fields, uses the following:
386 * - values: Enumerated values for the field
390 * @return {number|string|null}
392 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.parseSpecValue = function ( v
) {
399 if ( !this.values
) {
401 if ( this.type
=== 'boolean' || this.type
=== 'toggleLocal' ) {
402 return isNaN( v
) ? undefined : !!v
;
404 return isNaN( v
) ? undefined : v
;
411 re
= new RegExp( '^\\s*' + v
.replace( /([\\{}()|.?*+\-\^$\[\]])/g, '\\$1' ), 'i' );
412 for ( k
in this.values
) {
414 if ( !isNaN( k
) && re
.test( this.values
[ k
] ) ) {
415 if ( this.type
=== 'boolean' || this.type
=== 'toggleLocal' ) {
426 * Get components from a Date object
428 * Most specific components are defined by the subclass. "Global" components
430 * - intercalary: {string} Non-falsey values are used to indicate intercalary days.
431 * - zone: {number} Timezone offset in minutes.
434 * @param {Date|null} date
435 * @return {Object} Components
437 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.getComponentsFromDate = function ( date
) {
438 // Should be overridden by subclass
440 zone
: this.local
? date
.getTimezoneOffset() : 0
445 * Get a Date object from components
447 * @param {Object} components Date components
450 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.getDateFromComponents = function ( /* components */ ) {
451 // Should be overridden by subclass
458 * @param {Date|null} date To be adjusted
459 * @param {string} component To adjust
460 * @param {number} delta Adjustment amount
461 * @param {string} mode Adjustment mode:
462 * - 'overflow': "Jan 32" => "Feb 1", "Jan 33" => "Feb 2", "Feb 0" => "Jan 31", etc.
463 * - 'wrap': "Jan 32" => "Jan 1", "Jan 33" => "Jan 2", "Jan 0" => "Jan 31", etc.
464 * - 'clip': "Jan 32" => "Jan 31", "Feb 32" => "Feb 28" (or 29), "Feb 0" => "Feb 1", etc.
465 * @return {Date} Adjusted date
467 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.adjustComponent = function ( date
/*, component, delta, mode */ ) {
468 // Should be overridden by subclass
473 * Get the column headings (weekday abbreviations) for a calendar grid
475 * Null-valued columns are hidden if getCalendarData() returns no "day" object
476 * for all days in that column.
479 * @return {Array} string or null
481 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.getCalendarHeadings = function () {
482 // Should be overridden by subclass
487 * Test whether two dates are in the same calendar grid
490 * @param {Date} date1
491 * @param {Date} date2
494 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.sameCalendarGrid = function ( date1
, date2
) {
495 // Should be overridden by subclass
496 return date1
.getTime() === date2
.getTime();
500 * Test whether the date parts of two Dates are equal
502 * @param {Date} date1
503 * @param {Date} date2
506 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.datePartIsEqual = function ( date1
, date2
) {
509 date1
.getFullYear() === date2
.getFullYear() &&
510 date1
.getMonth() === date2
.getMonth() &&
511 date1
.getDate() === date2
.getDate()
515 date1
.getUTCFullYear() === date2
.getUTCFullYear() &&
516 date1
.getUTCMonth() === date2
.getUTCMonth() &&
517 date1
.getUTCDate() === date2
.getUTCDate()
523 * Test whether the time parts of two Dates are equal
525 * @param {Date} date1
526 * @param {Date} date2
529 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.timePartIsEqual = function ( date1
, date2
) {
532 date1
.getHours() === date2
.getHours() &&
533 date1
.getMinutes() === date2
.getMinutes() &&
534 date1
.getSeconds() === date2
.getSeconds() &&
535 date1
.getMilliseconds() === date2
.getMilliseconds()
539 date1
.getUTCHours() === date2
.getUTCHours() &&
540 date1
.getUTCMinutes() === date2
.getUTCMinutes() &&
541 date1
.getUTCSeconds() === date2
.getUTCSeconds() &&
542 date1
.getUTCMilliseconds() === date2
.getUTCMilliseconds()
548 * Test whether toggleLocal() changes the date part
553 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.localChangesDatePart = function ( date
) {
555 date
.getUTCFullYear() !== date
.getFullYear() ||
556 date
.getUTCMonth() !== date
.getMonth() ||
557 date
.getUTCDate() !== date
.getDate()
562 * Create a new Date by merging the date part from one with the time part from
565 * @param {Date} datepart
566 * @param {Date} timepart
569 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.mergeDateAndTime = function ( datepart
, timepart
) {
570 var ret
= new Date( datepart
.getTime() );
575 timepart
.getMinutes(),
576 timepart
.getSeconds(),
577 timepart
.getMilliseconds()
581 timepart
.getUTCHours(),
582 timepart
.getUTCMinutes(),
583 timepart
.getUTCSeconds(),
584 timepart
.getUTCMilliseconds()
592 * Get data for a calendar grid
595 * - display: {string} Display text for the day.
596 * - date: {Date} Date to use when the day is selected.
597 * - extra: {string|null} 'prev' or 'next' on days used to fill out the weeks
598 * at the start and end of the month.
600 * In any one result object, 'extra' + 'display' will always be unique.
603 * @param {Date|null} current Current date
604 * @return {Object} Data
605 * @return {string} return.header String to display as the calendar header
606 * @return {string} return.monthComponent Component to adjust by ±1 to change months.
607 * @return {string} return.dayComponent Component to adjust by ±1 to change days.
608 * @return {string} [return.weekComponent] Component to adjust by ±1 to change
609 * weeks. If omitted, the dayComponent should be adjusted by ±the number of
610 * non-nullable columns returned by this.getCalendarHeadings() to change weeks.
611 * @return {Array} return.rows Array of arrays of "day" objects or null/undefined.
613 mw
.widgets
.datetime
.DateTimeFormatter
.prototype.getCalendarData = function ( /* components */ ) {
614 // Should be overridden by subclass
617 monthComponent
: 'month',
623 }( jQuery
, mediaWiki
) );