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