diff options
Diffstat (limited to 'www/wiki/resources/src/mediawiki.widgets.datetime/DateTimeFormatter.js')
| -rw-r--r-- | www/wiki/resources/src/mediawiki.widgets.datetime/DateTimeFormatter.js | 627 |
1 files changed, 627 insertions, 0 deletions
diff --git a/www/wiki/resources/src/mediawiki.widgets.datetime/DateTimeFormatter.js b/www/wiki/resources/src/mediawiki.widgets.datetime/DateTimeFormatter.js new file mode 100644 index 00000000..a7a3bd30 --- /dev/null +++ b/www/wiki/resources/src/mediawiki.widgets.datetime/DateTimeFormatter.js @@ -0,0 +1,627 @@ +( function ( $, mw ) { + + /** + * Provides various methods needed for formatting dates and times. + * + * @class + * @abstract + * @mixins OO.EventEmitter + * + * @constructor + * @param {Object} [config] Configuration options + * @cfg {string} [format='@default'] May be a key from the {@link #static-formats static formats}, + * or a format specification as defined by {@link #method-parseFieldSpec parseFieldSpec} + * and {@link #method-getFieldForTag getFieldForTag}. + * @cfg {boolean} [local=false] Whether dates are local time or UTC + * @cfg {string[]} [fullZones] Time zone indicators. Array of 2 strings, for + * UTC and local time. + * @cfg {string[]} [shortZones] Abbreviated time zone indicators. Array of 2 + * strings, for UTC and local time. + * @cfg {Date} [defaultDate] Default date, for filling unspecified components. + * Defaults to the current date and time (with 0 milliseconds). + */ + mw.widgets.datetime.DateTimeFormatter = function MwWidgetsDatetimeDateTimeFormatter( config ) { + this.constructor.static.setupDefaults(); + + config = $.extend( { + format: '@default', + local: false, + fullZones: this.constructor.static.fullZones, + shortZones: this.constructor.static.shortZones + }, config ); + + // Mixin constructors + OO.EventEmitter.call( this ); + + // Properties + if ( this.constructor.static.formats[ config.format ] ) { + this.format = this.constructor.static.formats[ config.format ]; + } else { + this.format = config.format; + } + this.local = !!config.local; + this.fullZones = config.fullZones; + this.shortZones = config.shortZones; + if ( config.defaultDate instanceof Date ) { + this.defaultDate = config.defaultDate; + } else { + this.defaultDate = new Date(); + if ( this.local ) { + this.defaultDate.setMilliseconds( 0 ); + } else { + this.defaultDate.setUTCMilliseconds( 0 ); + } + } + }; + + /* Setup */ + + OO.initClass( mw.widgets.datetime.DateTimeFormatter ); + OO.mixinClass( mw.widgets.datetime.DateTimeFormatter, OO.EventEmitter ); + + /* Static */ + + /** + * Default format specifications. See the {@link #format format} parameter. + * + * @static + * @inheritable + * @property {Object} + */ + mw.widgets.datetime.DateTimeFormatter.static.formats = {}; + + /** + * Default time zone indicators + * + * @static + * @inheritable + * @property {string[]} + */ + mw.widgets.datetime.DateTimeFormatter.static.fullZones = null; + + /** + * Default abbreviated time zone indicators + * + * @static + * @inheritable + * @property {string[]} + */ + mw.widgets.datetime.DateTimeFormatter.static.shortZones = null; + + mw.widgets.datetime.DateTimeFormatter.static.setupDefaults = function () { + if ( !this.fullZones ) { + this.fullZones = [ + mw.msg( 'timezone-utc' ), + mw.msg( 'timezone-local' ) + ]; + } + if ( !this.shortZones ) { + this.shortZones = [ + 'Z', + this.fullZones[ 1 ].substr( 0, 1 ).toUpperCase() + ]; + if ( this.shortZones[ 1 ] === 'Z' ) { + this.shortZones[ 1 ] = 'L'; + } + } + }; + + /* Events */ + + /** + * A `local` event is emitted when the 'local' flag is changed. + * + * @event local + */ + + /* Methods */ + + /** + * Whether dates are in local time or UTC + * + * @return {boolean} True if local time + */ + mw.widgets.datetime.DateTimeFormatter.prototype.getLocal = function () { + return this.local; + }; + + // eslint-disable-next-line valid-jsdoc + /** + * Toggle whether dates are in local time or UTC + * + * @param {boolean} [flag] Set the flag instead of toggling it + * @fires local + * @chainable + */ + mw.widgets.datetime.DateTimeFormatter.prototype.toggleLocal = function ( flag ) { + if ( flag === undefined ) { + flag = !this.local; + } else { + flag = !!flag; + } + if ( this.local !== flag ) { + this.local = flag; + this.emit( 'local', this.local ); + } + return this; + }; + + /** + * Get the default date + * + * @return {Date} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.getDefaultDate = function () { + return new Date( this.defaultDate.getTime() ); + }; + + /** + * Fetch the field specification array for this object. + * + * See {@link #parseFieldSpec parseFieldSpec} for details on the return value structure. + * + * @return {Array} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.getFieldSpec = function () { + return this.parseFieldSpec( this.format ); + }; + + /** + * 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 {@link #getFieldForTag 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 {@link #getFieldForTag getFieldForTag}. + * + * @protected + * @param {string} format + * @return {Array} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.parseFieldSpec = function ( format ) { + var m, last, tag, params, spec, + ret = [], + re = /(.*?)(\$(!?)\{([^}]+)\})/g; + + last = 0; + while ( ( m = re.exec( format ) ) !== null ) { + last = re.lastIndex; + + if ( m[ 1 ] !== '' ) { + ret.push( m[ 1 ] ); + } + + params = m[ 4 ].split( '|' ); + tag = params.shift(); + spec = this.getFieldForTag( tag, params ); + if ( spec ) { + if ( m[ 3 ] === '!' ) { + spec.editable = false; + } + ret.push( spec ); + } else { + ret.push( m[ 2 ] ); + } + } + if ( last < format.length ) { + ret.push( format.substr( last ) ); + } + + return ret; + }; + + /** + * 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. + * + * @protected + * @abstract + * @param {string} tag + * @param {string[]} params + * @return {Object|null} Field specification object, or null if the tag+params are unrecognized. + * @return {string|null} return.component Date component corresponding to this field, if any. + * @return {boolean} return.editable Whether this field is editable. + * @return {string} return.type 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 {@link #getLocal this.getLocal()}. + * Editing should directly call {@link #toggleLocal this.toggleLocal()}. + * @return {boolean} return.calendarComponent Whether this field is part of a calendar, e.g. + * part of the date instead of the time. + * @return {number} return.size Maximum number of characters in the field (when + * the 'intercalary' component is falsey). If 0, the field should be hidden entirely. + * @return {Object.<string,number>} return.intercalarySize Map from + * 'intercalary' component values to overridden sizes. + * @return {string} return.value For type='static', the string to display. + * @return {function(Mixed): string} return.formatValue A function to format a + * component value as a display string. + * @return {function(string): Mixed} return.parseValue A function to parse a + * display string into a component value. If parsing fails, returns undefined. + */ + mw.widgets.datetime.DateTimeFormatter.prototype.getFieldForTag = function ( tag, params ) { + var c, spec = null; + + switch ( tag ) { + case 'intercalary': + case 'not-intercalary': + if ( params.length < 2 || !params[ 0 ] ) { + return null; + } + spec = { + component: null, + calendarComponent: false, + editable: false, + type: 'static', + value: params.slice( 1 ).join( '|' ), + size: 0, + intercalarySize: {} + }; + if ( tag === 'intercalary' ) { + spec.intercalarySize[ params[ 0 ] ] = spec.value.length; + } else { + spec.size = spec.value.length; + spec.intercalarySize[ params[ 0 ] ] = 0; + } + return spec; + + case 'zone': + switch ( params[ 0 ] ) { + case '#': + case ':': + c = params[ 0 ] === '#' ? '' : ':'; + return { + component: 'zone', + calendarComponent: false, + editable: true, + type: 'toggleLocal', + size: 5 + c.length, + formatValue: function ( v ) { + var o, r; + if ( v ) { + o = new Date().getTimezoneOffset(); + r = String( Math.abs( o ) % 60 ); + while ( r.length < 2 ) { + r = '0' + r; + } + r = String( Math.floor( Math.abs( o ) / 60 ) ) + c + r; + while ( r.length < 4 + c.length ) { + r = '0' + r; + } + return ( o <= 0 ? '+' : '−' ) + r; + } else { + return '+00' + c + '00'; + } + }, + parseValue: function ( v ) { + var m; + v = String( v ).trim(); + if ( ( m = /^([+-−])([0-9]{1,2}):?([0-9]{2})$/.test( v ) ) ) { + return ( m[ 2 ] * 60 + m[ 3 ] ) * ( m[ 1 ] === '+' ? -1 : 1 ); + } else { + return undefined; + } + } + }; + + case 'short': + case 'full': + spec = { + component: 'zone', + calendarComponent: false, + editable: true, + type: 'toggleLocal', + values: params[ 0 ] === 'short' ? this.shortZones : this.fullZones, + formatValue: this.formatSpecValue, + parseValue: this.parseSpecValue + }; + spec.size = Math.max.apply( + null, $.map( spec.values, function ( v ) { return v.length; } ) + ); + return spec; + } + return null; + + default: + return null; + } + }; + + /** + * 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. + * + * @protected + * @param {Mixed} v + * @return {string} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.formatSpecValue = function ( v ) { + if ( v === undefined || v === null ) { + return ''; + } + + if ( typeof v === 'boolean' || this.type === 'toggleLocal' ) { + v = v ? 1 : 0; + } + + if ( this.values ) { + return this.values[ v ]; + } + + v = String( v ); + if ( this.zeropad ) { + while ( v.length < this.size ) { + v = '0' + v; + } + } + return v; + }; + + /** + * 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 + * + * @protected + * @param {string} v + * @return {number|string|null} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.parseSpecValue = function ( v ) { + var k, re; + + if ( v === '' ) { + return null; + } + + if ( !this.values ) { + v = +v; + if ( this.type === 'boolean' || this.type === 'toggleLocal' ) { + return isNaN( v ) ? undefined : !!v; + } else { + return isNaN( v ) ? undefined : v; + } + } + + if ( v.normalize ) { + v = v.normalize(); + } + re = new RegExp( '^\\s*' + v.replace( /([\\{}()|.?*+\-^$\[\]])/g, '\\$1' ), 'i' ); // eslint-disable-line no-useless-escape + for ( k in this.values ) { + k = +k; + if ( !isNaN( k ) && re.test( this.values[ k ] ) ) { + if ( this.type === 'boolean' || this.type === 'toggleLocal' ) { + return !!k; + } else { + return k; + } + } + } + return undefined; + }; + + /** + * 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. + * + * @abstract + * @param {Date|null} date + * @return {Object} Components + */ + mw.widgets.datetime.DateTimeFormatter.prototype.getComponentsFromDate = function ( date ) { + // Should be overridden by subclass + return { + zone: this.local ? date.getTimezoneOffset() : 0 + }; + }; + + /** + * Get a Date object from components + * + * @param {Object} components Date components + * @return {Date} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.getDateFromComponents = function ( /* components */ ) { + // Should be overridden by subclass + return new Date(); + }; + + /** + * Adjust a date + * + * @param {Date|null} date To be adjusted + * @param {string} component To adjust + * @param {number} delta Adjustment amount + * @param {string} mode 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. + * @return {Date} Adjusted date + */ + mw.widgets.datetime.DateTimeFormatter.prototype.adjustComponent = function ( date /* , component, delta, mode */ ) { + // Should be overridden by subclass + return date; + }; + + /** + * 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. + * + * @abstract + * @return {Array} string or null + */ + mw.widgets.datetime.DateTimeFormatter.prototype.getCalendarHeadings = function () { + // Should be overridden by subclass + return []; + }; + + /** + * Test whether two dates are in the same calendar grid + * + * @abstract + * @param {Date} date1 + * @param {Date} date2 + * @return {boolean} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.sameCalendarGrid = function ( date1, date2 ) { + // Should be overridden by subclass + return date1.getTime() === date2.getTime(); + }; + + /** + * Test whether the date parts of two Dates are equal + * + * @param {Date} date1 + * @param {Date} date2 + * @return {boolean} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.datePartIsEqual = function ( date1, date2 ) { + if ( this.local ) { + return ( + date1.getFullYear() === date2.getFullYear() && + date1.getMonth() === date2.getMonth() && + date1.getDate() === date2.getDate() + ); + } else { + return ( + date1.getUTCFullYear() === date2.getUTCFullYear() && + date1.getUTCMonth() === date2.getUTCMonth() && + date1.getUTCDate() === date2.getUTCDate() + ); + } + }; + + /** + * Test whether the time parts of two Dates are equal + * + * @param {Date} date1 + * @param {Date} date2 + * @return {boolean} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.timePartIsEqual = function ( date1, date2 ) { + if ( this.local ) { + return ( + date1.getHours() === date2.getHours() && + date1.getMinutes() === date2.getMinutes() && + date1.getSeconds() === date2.getSeconds() && + date1.getMilliseconds() === date2.getMilliseconds() + ); + } else { + return ( + date1.getUTCHours() === date2.getUTCHours() && + date1.getUTCMinutes() === date2.getUTCMinutes() && + date1.getUTCSeconds() === date2.getUTCSeconds() && + date1.getUTCMilliseconds() === date2.getUTCMilliseconds() + ); + } + }; + + /** + * Test whether toggleLocal() changes the date part + * + * @param {Date} date + * @return {boolean} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.localChangesDatePart = function ( date ) { + return ( + date.getUTCFullYear() !== date.getFullYear() || + date.getUTCMonth() !== date.getMonth() || + date.getUTCDate() !== date.getDate() + ); + }; + + /** + * Create a new Date by merging the date part from one with the time part from + * another. + * + * @param {Date} datepart + * @param {Date} timepart + * @return {Date} + */ + mw.widgets.datetime.DateTimeFormatter.prototype.mergeDateAndTime = function ( datepart, timepart ) { + var ret = new Date( datepart.getTime() ); + + if ( this.local ) { + ret.setHours( + timepart.getHours(), + timepart.getMinutes(), + timepart.getSeconds(), + timepart.getMilliseconds() + ); + } else { + ret.setUTCHours( + timepart.getUTCHours(), + timepart.getUTCMinutes(), + timepart.getUTCSeconds(), + timepart.getUTCMilliseconds() + ); + } + + return ret; + }; + + /** + * 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. + * + * @abstract + * @param {Date|null} current Current date + * @return {Object} Data + * @return {string} return.header String to display as the calendar header + * @return {string} return.monthComponent Component to adjust by ±1 to change months. + * @return {string} return.dayComponent Component to adjust by ±1 to change days. + * @return {string} [return.weekComponent] 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. + * @return {Array} return.rows Array of arrays of "day" objects or null/undefined. + */ + mw.widgets.datetime.DateTimeFormatter.prototype.getCalendarData = function ( /* components */ ) { + // Should be overridden by subclass + return { + header: '', + monthComponent: 'month', + dayComponent: 'day', + rows: [] + }; + }; + +}( jQuery, mediaWiki ) ); |