Merge "Make updateCategoryCounts() have better lag checks"
[lhc/web/wiklou.git] / resources / src / mediawiki.widgets / mw.widgets.DateInputWidget.js
1 /*!
2 * MediaWiki Widgets – DateInputWidget class.
3 *
4 * @copyright 2011-2015 MediaWiki Widgets Team and others; see AUTHORS.txt
5 * @license The MIT License (MIT); see LICENSE.txt
6 */
7 /*global moment */
8 ( function ( $, mw ) {
9
10 /**
11 * Creates an mw.widgets.DateInputWidget object.
12 *
13 * @example
14 * // Date input widget showcase
15 * var fieldset = new OO.ui.FieldsetLayout( {
16 * items: [
17 * new OO.ui.FieldLayout(
18 * new mw.widgets.DateInputWidget(),
19 * {
20 * align: 'top',
21 * label: 'Select date'
22 * }
23 * ),
24 * new OO.ui.FieldLayout(
25 * new mw.widgets.DateInputWidget( { precision: 'month' } ),
26 * {
27 * align: 'top',
28 * label: 'Select month'
29 * }
30 * ),
31 * new OO.ui.FieldLayout(
32 * new mw.widgets.DateInputWidget( {
33 * inputFormat: 'DD.MM.YYYY',
34 * displayFormat: 'Do [of] MMMM [anno Domini] YYYY'
35 * } ),
36 * {
37 * align: 'top',
38 * label: 'Select date (custom formats)'
39 * }
40 * )
41 * ]
42 * } );
43 * $( 'body' ).append( fieldset.$element );
44 *
45 * The value is stored in 'YYYY-MM-DD' or 'YYYY-MM' format:
46 *
47 * @example
48 * // Accessing values in a date input widget
49 * var dateInput = new mw.widgets.DateInputWidget();
50 * var $label = $( '<p>' );
51 * $( 'body' ).append( $label, dateInput.$element );
52 * dateInput.on( 'change', function () {
53 * // The value will always be a valid date or empty string, malformed input is ignored
54 * var date = dateInput.getValue();
55 * $label.text( 'Selected date: ' + ( date || '(none)' ) );
56 * } );
57 *
58 * @class
59 * @extends OO.ui.InputWidget
60 * @mixins OO.ui.mixin.IndicatorElement
61 *
62 * @constructor
63 * @param {Object} [config] Configuration options
64 * @cfg {string} [precision='day'] Date precision to use, 'day' or 'month'
65 * @cfg {string} [value] Day or month date (depending on `precision`), in the format 'YYYY-MM-DD'
66 * or 'YYYY-MM'. If not given or empty string, no date is selected.
67 * @cfg {string} [inputFormat] Date format string to use for the textual input field. Displayed
68 * while the widget is active, and the user can type in a date in this format. Should be short
69 * and easy to type. When not given, defaults to 'YYYY-MM-DD' or 'YYYY-MM', depending on
70 * `precision`.
71 * @cfg {string} [displayFormat] Date format string to use for the clickable label. Displayed
72 * while the widget is inactive. Should be as unambiguous as possible (for example, prefer to
73 * spell out the month, rather than rely on the order), even if that makes it longer. When not
74 * given, the default is language-specific.
75 * @cfg {string} [placeholderLabel=No date selected] Placeholder text shown when the widget is not
76 * selected. Default text taken from message `mw-widgets-dateinput-no-date`.
77 * @cfg {string} [placeholderDateFormat] User-visible date format string displayed in the textual input
78 * field when it's empty. Should be the same as `inputFormat`, but translated to the user's
79 * language. When not given, defaults to a translated version of 'YYYY-MM-DD' or 'YYYY-MM',
80 * depending on `precision`.
81 * @cfg {boolean} [required=false] Mark the field as required. Implies `indicator: 'required'`.
82 * @cfg {string} [mustBeAfter] Validates the date to be after this. In the 'YYYY-MM-DD' format.
83 * @cfg {string} [mustBeBefore] Validates the date to be before this. In the 'YYYY-MM-DD' format.
84 * @cfg {jQuery} [$overlay] Render the calendar into a separate layer. This configuration is
85 * useful in cases where the expanded calendar is larger than its container. The specified
86 * overlay layer is usually on top of the container and has a larger area. By default, the
87 * calendar uses relative positioning.
88 */
89 mw.widgets.DateInputWidget = function MWWDateInputWidget( config ) {
90 // Config initialization
91 config = $.extend( {
92 precision: 'day',
93 required: false,
94 placeholderLabel: mw.msg( 'mw-widgets-dateinput-no-date' )
95 }, config );
96 if ( config.required ) {
97 if ( config.indicator === undefined ) {
98 config.indicator = 'required';
99 }
100 }
101
102 var placeholderDateFormat, mustBeAfter, mustBeBefore;
103 if ( config.placeholderDateFormat ) {
104 placeholderDateFormat = config.placeholderDateFormat;
105 } else if ( config.inputFormat ) {
106 // We have no way to display a translated placeholder for custom formats
107 placeholderDateFormat = '';
108 } else {
109 // Messages: mw-widgets-dateinput-placeholder-day, mw-widgets-dateinput-placeholder-month
110 placeholderDateFormat = mw.msg( 'mw-widgets-dateinput-placeholder-' + config.precision );
111 }
112
113 // Properties (must be set before parent constructor, which calls #setValue)
114 this.$handle = $( '<div>' );
115 this.label = new OO.ui.LabelWidget();
116 this.textInput = new OO.ui.TextInputWidget( {
117 required: config.required,
118 placeholder: placeholderDateFormat,
119 validate: this.validateDate.bind( this )
120 } );
121 this.calendar = new mw.widgets.CalendarWidget( {
122 lazyInitOnToggle: true,
123 // Can't pass `$floatableContainer: this.$element` here, the latter is not set yet.
124 // Instead we call setFloatableContainer() below.
125 precision: config.precision
126 } );
127 this.inCalendar = 0;
128 this.inTextInput = 0;
129 this.inputFormat = config.inputFormat;
130 this.displayFormat = config.displayFormat;
131 this.required = config.required;
132 this.placeholderLabel = config.placeholderLabel;
133
134 // Validate and set min and max dates as properties
135 if ( config.mustBeAfter !== undefined ) {
136 mustBeAfter = moment( config.mustBeAfter, 'YYYY-MM-DD' );
137 if ( mustBeAfter.isValid() ) {
138 this.mustBeAfter = mustBeAfter;
139 }
140 }
141 if ( config.mustBeBefore !== undefined ) {
142 mustBeBefore = moment( config.mustBeBefore, 'YYYY-MM-DD' );
143 if ( mustBeBefore.isValid() ) {
144 this.mustBeBefore = mustBeBefore;
145 }
146 }
147
148 // Parent constructor
149 mw.widgets.DateInputWidget.parent.call( this, config );
150
151 // Mixin constructors
152 OO.ui.mixin.IndicatorElement.call( this, config );
153
154 // Events
155 this.calendar.connect( this, {
156 change: 'onCalendarChange'
157 } );
158 this.textInput.connect( this, {
159 enter: 'onEnter',
160 change: 'onTextInputChange'
161 } );
162 this.$element.on( {
163 focusout: this.onBlur.bind( this )
164 } );
165 this.calendar.$element.on( {
166 click: this.onCalendarClick.bind( this ),
167 keypress: this.onCalendarKeyPress.bind( this )
168 } );
169 this.$handle.on( {
170 click: this.onClick.bind( this ),
171 keypress: this.onKeyPress.bind( this )
172 } );
173
174 // Initialization
175 // Move 'tabindex' from this.$input (which is invisible) to the visible handle
176 this.setTabIndexedElement( this.$handle );
177 this.$handle
178 .append( this.label.$element, this.$indicator )
179 .addClass( 'mw-widget-dateInputWidget-handle' );
180 this.calendar.$element
181 .addClass( 'mw-widget-dateInputWidget-calendar' );
182 this.$element
183 .addClass( 'mw-widget-dateInputWidget' )
184 .append( this.$handle, this.textInput.$element, this.calendar.$element );
185
186 if ( config.$overlay ) {
187 this.calendar.setFloatableContainer( this.$element );
188 config.$overlay.append( this.calendar.$element );
189
190 // The text input and calendar are not in DOM order, so fix up focus transitions.
191 this.textInput.$input.on( 'keydown', function ( e ) {
192 if ( e.which === OO.ui.Keys.TAB ) {
193 if ( e.shiftKey ) {
194 // Tabbing backward from text input: normal browser behavior
195 $.noop();
196 } else {
197 // Tabbing forward from text input: just focus the calendar
198 this.calendar.$element.focus();
199 return false;
200 }
201 }
202 }.bind( this ) );
203 this.calendar.$element.on( 'keydown', function ( e ) {
204 if ( e.which === OO.ui.Keys.TAB ) {
205 if ( e.shiftKey ) {
206 // Tabbing backward from calendar: just focus the text input
207 this.textInput.$input.focus();
208 return false;
209 } else {
210 // Tabbing forward from calendar: focus the text input, then allow normal browser
211 // behavior to move focus to next focusable after it
212 this.textInput.$input.focus();
213 }
214 }
215 }.bind( this ) );
216 }
217
218 // Set handle label and hide stuff
219 this.updateUI();
220 this.textInput.toggle( false );
221 this.calendar.toggle( false );
222 };
223
224 /* Inheritance */
225
226 OO.inheritClass( mw.widgets.DateInputWidget, OO.ui.InputWidget );
227 OO.mixinClass( mw.widgets.DateInputWidget, OO.ui.mixin.IndicatorElement );
228
229 /* Methods */
230
231 /**
232 * @inheritdoc
233 * @protected
234 */
235 mw.widgets.DateInputWidget.prototype.getInputElement = function () {
236 return $( '<input>' ).attr( 'type', 'hidden' );
237 };
238
239 /**
240 * Respond to calendar date change events.
241 *
242 * @private
243 */
244 mw.widgets.DateInputWidget.prototype.onCalendarChange = function () {
245 this.inCalendar++;
246 if ( !this.inTextInput ) {
247 // If this is caused by user typing in the input field, do not set anything.
248 // The value may be invalid (see #onTextInputChange), but displayable on the calendar.
249 this.setValue( this.calendar.getDate() );
250 }
251 this.inCalendar--;
252 };
253
254 /**
255 * Respond to text input value change events.
256 *
257 * @private
258 */
259 mw.widgets.DateInputWidget.prototype.onTextInputChange = function () {
260 var mom,
261 widget = this,
262 value = this.textInput.getValue(),
263 valid = this.isValidDate( value );
264 this.inTextInput++;
265
266 if ( value === '' ) {
267 // No date selected
268 widget.setValue( '' );
269 } else if ( valid ) {
270 // Well-formed date value, parse and set it
271 mom = moment( value, widget.getInputFormat() );
272 // Use English locale to avoid number formatting
273 widget.setValue( mom.locale( 'en' ).format( widget.getInternalFormat() ) );
274 } else {
275 // Not well-formed, but possibly partial? Try updating the calendar, but do not set the
276 // internal value. Generally this only makes sense when 'inputFormat' is little-endian (e.g.
277 // 'YYYY-MM-DD'), but that's hard to check for, and might be difficult to handle the parsing
278 // right for weird formats. So limit this trick to only when we're using the default
279 // 'inputFormat', which is the same as the internal format, 'YYYY-MM-DD'.
280 if ( widget.getInputFormat() === widget.getInternalFormat() ) {
281 widget.calendar.setDate( widget.textInput.getValue() );
282 }
283 }
284 widget.inTextInput--;
285
286 };
287
288 /**
289 * @inheritdoc
290 */
291 mw.widgets.DateInputWidget.prototype.setValue = function ( value ) {
292 var oldValue = this.value;
293
294 if ( !moment( value, this.getInternalFormat() ).isValid() ) {
295 value = '';
296 }
297
298 mw.widgets.DateInputWidget.parent.prototype.setValue.call( this, value );
299
300 if ( this.value !== oldValue ) {
301 this.updateUI();
302 this.setValidityFlag();
303 }
304
305 return this;
306 };
307
308 /**
309 * Handle text input and calendar blur events.
310 *
311 * @private
312 */
313 mw.widgets.DateInputWidget.prototype.onBlur = function () {
314 var widget = this;
315 setTimeout( function () {
316 var $focussed = $( ':focus' );
317 // Deactivate unless the focus moved to something else inside this widget
318 if (
319 !OO.ui.contains( widget.$element[ 0 ], $focussed[ 0 ], true ) &&
320 // Calendar might be in an $overlay
321 !OO.ui.contains( widget.calendar.$element[ 0 ], $focussed[ 0 ], true )
322 ) {
323 widget.deactivate();
324 }
325 }, 0 );
326 };
327
328 /**
329 * @inheritdoc
330 */
331 mw.widgets.DateInputWidget.prototype.focus = function () {
332 this.activate();
333 return this;
334 };
335
336 /**
337 * @inheritdoc
338 */
339 mw.widgets.DateInputWidget.prototype.blur = function () {
340 this.deactivate();
341 return this;
342 };
343
344 /**
345 * Update the contents of the label, text input and status of calendar to reflect selected value.
346 *
347 * @private
348 */
349 mw.widgets.DateInputWidget.prototype.updateUI = function () {
350 var moment;
351 if ( this.getValue() === '' ) {
352 this.textInput.setValue( '' );
353 this.calendar.setDate( null );
354 this.label.setLabel( this.placeholderLabel );
355 this.$element.addClass( 'mw-widget-dateInputWidget-empty' );
356 } else {
357 moment = this.getMoment();
358 if ( !this.inTextInput ) {
359 this.textInput.setValue( moment.format( this.getInputFormat() ) );
360 }
361 if ( !this.inCalendar ) {
362 this.calendar.setDate( this.getValue() );
363 }
364 this.label.setLabel( moment.format( this.getDisplayFormat() ) );
365 this.$element.removeClass( 'mw-widget-dateInputWidget-empty' );
366 }
367 };
368
369 /**
370 * Deactivate this input field for data entry. Closes the calendar and hides the text field.
371 *
372 * @private
373 */
374 mw.widgets.DateInputWidget.prototype.deactivate = function () {
375 this.$element.removeClass( 'mw-widget-dateInputWidget-active' );
376 this.$handle.show();
377 this.textInput.toggle( false );
378 this.calendar.toggle( false );
379 this.setValidityFlag();
380 };
381
382 /**
383 * Activate this input field for data entry. Opens the calendar and shows the text field.
384 *
385 * @private
386 */
387 mw.widgets.DateInputWidget.prototype.activate = function () {
388 this.calendar.resetUI();
389 this.$element.addClass( 'mw-widget-dateInputWidget-active' );
390 this.$handle.hide();
391 this.textInput.toggle( true );
392 this.calendar.toggle( true );
393
394 this.textInput.$input.focus();
395 };
396
397 /**
398 * Get the date format to be used for handle label when the input is inactive.
399 *
400 * @private
401 * @return {string} Format string
402 */
403 mw.widgets.DateInputWidget.prototype.getDisplayFormat = function () {
404 if ( this.displayFormat !== undefined ) {
405 return this.displayFormat;
406 }
407
408 if ( this.calendar.getPrecision() === 'month' ) {
409 return 'MMMM YYYY';
410 } else {
411 // The formats Moment.js provides:
412 // * ll: Month name, day of month, year
413 // * lll: Month name, day of month, year, time
414 // * llll: Month name, day of month, day of week, year, time
415 //
416 // The format we want:
417 // * ????: Month name, day of month, day of week, year
418 //
419 // We try to construct it as 'llll - (lll - ll)' and hope for the best.
420 // This seems to work well for many languages (maybe even all?).
421
422 var localeData = moment.localeData( moment.locale() ),
423 llll = localeData.longDateFormat( 'llll' ),
424 lll = localeData.longDateFormat( 'lll' ),
425 ll = localeData.longDateFormat( 'll' ),
426 format = llll.replace( lll.replace( ll, '' ), '' );
427
428 return format;
429 }
430 };
431
432 /**
433 * Get the date format to be used for the text field when the input is active.
434 *
435 * @private
436 * @return {string} Format string
437 */
438 mw.widgets.DateInputWidget.prototype.getInputFormat = function () {
439 if ( this.inputFormat !== undefined ) {
440 return this.inputFormat;
441 }
442
443 return {
444 day: 'YYYY-MM-DD',
445 month: 'YYYY-MM'
446 }[ this.calendar.getPrecision() ];
447 };
448
449 /**
450 * Get the date format to be used internally for the value. This is not configurable in any way,
451 * and always either 'YYYY-MM-DD' or 'YYYY-MM'.
452 *
453 * @private
454 * @return {string} Format string
455 */
456 mw.widgets.DateInputWidget.prototype.getInternalFormat = function () {
457 return {
458 day: 'YYYY-MM-DD',
459 month: 'YYYY-MM'
460 }[ this.calendar.getPrecision() ];
461 };
462
463 /**
464 * Get the Moment object for current value.
465 *
466 * @return {Object} Moment object
467 */
468 mw.widgets.DateInputWidget.prototype.getMoment = function () {
469 return moment( this.getValue(), this.getInternalFormat() );
470 };
471
472 /**
473 * Handle mouse click events.
474 *
475 * @private
476 * @param {jQuery.Event} e Mouse click event
477 */
478 mw.widgets.DateInputWidget.prototype.onClick = function ( e ) {
479 if ( !this.isDisabled() && e.which === 1 ) {
480 this.activate();
481 }
482 return false;
483 };
484
485 /**
486 * Handle key press events.
487 *
488 * @private
489 * @param {jQuery.Event} e Key press event
490 */
491 mw.widgets.DateInputWidget.prototype.onKeyPress = function ( e ) {
492 if ( !this.isDisabled() &&
493 ( e.which === OO.ui.Keys.SPACE || e.which === OO.ui.Keys.ENTER )
494 ) {
495 this.activate();
496 return false;
497 }
498 };
499
500 /**
501 * Handle calendar key press events.
502 *
503 * @private
504 * @param {jQuery.Event} e Key press event
505 */
506 mw.widgets.DateInputWidget.prototype.onCalendarKeyPress = function ( e ) {
507 if ( !this.isDisabled() && e.which === OO.ui.Keys.ENTER ) {
508 this.deactivate();
509 this.$handle.focus();
510 return false;
511 }
512 };
513
514 /**
515 * Handle calendar click events.
516 *
517 * @private
518 * @param {jQuery.Event} e Mouse click event
519 */
520 mw.widgets.DateInputWidget.prototype.onCalendarClick = function ( e ) {
521 if (
522 !this.isDisabled() &&
523 e.which === 1 &&
524 $( e.target ).hasClass( 'mw-widget-calendarWidget-day' )
525 ) {
526 this.deactivate();
527 this.$handle.focus();
528 return false;
529 }
530 };
531
532 /**
533 * Handle text input enter events.
534 *
535 * @private
536 */
537 mw.widgets.DateInputWidget.prototype.onEnter = function () {
538 this.deactivate();
539 this.$handle.focus();
540 };
541
542 /**
543 * @private
544 * @param {string} date Date string, to be valid, must be in 'YYYY-MM-DD' or 'YYYY-MM' format or
545 * (unless the field is required) empty
546 * @return {boolean}
547 */
548 mw.widgets.DateInputWidget.prototype.validateDate = function ( date ) {
549 var isValid;
550 if ( date === '' ) {
551 isValid = !this.required;
552 } else {
553 isValid = this.isValidDate( date ) && this.isInRange( date );
554 }
555 return isValid;
556 };
557
558 /**
559 * @private
560 * @param {string} date Date string, to be valid, must be in 'YYYY-MM-DD' or 'YYYY-MM' format
561 * @return {boolean}
562 */
563 mw.widgets.DateInputWidget.prototype.isValidDate = function ( date ) {
564 // "Half-strict mode": for example, for the format 'YYYY-MM-DD', 2015-1-3 instead of 2015-01-03
565 // is okay, but 2015-01 isn't, and neither is 2015-01-foo. Use Moment's "fuzzy" mode and check
566 // parsing flags for the details (stolen from implementation of moment#isValid).
567 var
568 mom = moment( date, this.getInputFormat() ),
569 flags = mom.parsingFlags();
570
571 return mom.isValid() && flags.charsLeftOver === 0 && flags.unusedTokens.length === 0;
572 };
573
574 /**
575 * Validates if the date is within the range configured with {@link #cfg-mustBeAfter}
576 * and {@link #cfg-mustBeBefore}.
577 *
578 * @private
579 * @param {string} date Date string, to be valid, must be empty (no date selected) or in
580 * 'YYYY-MM-DD' or 'YYYY-MM' format to be valid
581 * @return {boolean}
582 */
583 mw.widgets.DateInputWidget.prototype.isInRange = function ( date ) {
584 var momentDate, isAfter, isBefore;
585 if ( this.mustBeAfter === undefined && this.mustBeBefore === undefined ) {
586 return true;
587 }
588 momentDate = moment( date, 'YYYY-MM-DD' );
589 isAfter = ( this.mustBeAfter === undefined || momentDate.isAfter( this.mustBeAfter ) );
590 isBefore = ( this.mustBeBefore === undefined || momentDate.isBefore( this.mustBeBefore ) );
591 return isAfter && isBefore;
592 };
593
594 /**
595 * Get the validity of current value.
596 *
597 * This method returns a promise that resolves if the value is valid and rejects if
598 * it isn't. Uses {@link #validateDate}.
599 *
600 * @return {jQuery.Promise} A promise that resolves if the value is valid, rejects if not.
601 */
602 mw.widgets.DateInputWidget.prototype.getValidity = function () {
603 var isValid = this.validateDate( this.getValue() );
604
605 if ( isValid ) {
606 return $.Deferred().resolve().promise();
607 } else {
608 return $.Deferred().reject().promise();
609 }
610 };
611
612 /**
613 * Sets the 'invalid' flag appropriately.
614 *
615 * @param {boolean} [isValid] Optionally override validation result
616 */
617 mw.widgets.DateInputWidget.prototype.setValidityFlag = function ( isValid ) {
618 var widget = this,
619 setFlag = function ( valid ) {
620 if ( !valid ) {
621 widget.$input.attr( 'aria-invalid', 'true' );
622 } else {
623 widget.$input.removeAttr( 'aria-invalid' );
624 }
625 widget.setFlags( { invalid: !valid } );
626 };
627
628 if ( isValid !== undefined ) {
629 setFlag( isValid );
630 } else {
631 this.getValidity().then( function () {
632 setFlag( true );
633 }, function () {
634 setFlag( false );
635 } );
636 }
637 };
638
639 }( jQuery, mediaWiki ) );