3 * https://www.mediawiki.org/wiki/OOjs_UI
5 * Copyright 2011–2017 OOjs UI Team and other contributors.
6 * Released under the MIT license
7 * http://oojs.mit-license.org
9 * Date: 2017-07-11T22:12:33Z
16 * An ActionWidget is a {@link OO.ui.ButtonWidget button widget} that executes an action.
17 * Action widgets are used with OO.ui.ActionSet, which manages the behavior and availability
20 * Both actions and action sets are primarily used with {@link OO.ui.Dialog Dialogs}.
21 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information
24 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs#Action_sets
27 * @extends OO.ui.ButtonWidget
28 * @mixins OO.ui.mixin.PendingElement
31 * @param {Object} [config] Configuration options
32 * @cfg {string} [action] Symbolic name of the action (e.g., ‘continue’ or ‘cancel’).
33 * @cfg {string[]} [modes] Symbolic names of the modes (e.g., ‘edit’ or ‘read’) in which the action
34 * should be made available. See the action set's {@link OO.ui.ActionSet#setMode setMode} method
35 * for more information about setting modes.
36 * @cfg {boolean} [framed=false] Render the action button with a frame
38 OO
.ui
.ActionWidget
= function OoUiActionWidget( config
) {
39 // Configuration initialization
40 config
= $.extend( { framed
: false }, config
);
43 OO
.ui
.ActionWidget
.parent
.call( this, config
);
46 OO
.ui
.mixin
.PendingElement
.call( this, config
);
49 this.action
= config
.action
|| '';
50 this.modes
= config
.modes
|| [];
55 this.$element
.addClass( 'oo-ui-actionWidget' );
60 OO
.inheritClass( OO
.ui
.ActionWidget
, OO
.ui
.ButtonWidget
);
61 OO
.mixinClass( OO
.ui
.ActionWidget
, OO
.ui
.mixin
.PendingElement
);
66 * Check if the action is configured to be available in the specified `mode`.
68 * @param {string} mode Name of mode
69 * @return {boolean} The action is configured with the mode
71 OO
.ui
.ActionWidget
.prototype.hasMode = function ( mode
) {
72 return this.modes
.indexOf( mode
) !== -1;
76 * Get the symbolic name of the action (e.g., ‘continue’ or ‘cancel’).
80 OO
.ui
.ActionWidget
.prototype.getAction = function () {
85 * Get the symbolic name of the mode or modes for which the action is configured to be available.
87 * The current mode is set with the action set's {@link OO.ui.ActionSet#setMode setMode} method.
88 * Only actions that are configured to be avaiable in the current mode will be visible. All other actions
93 OO
.ui
.ActionWidget
.prototype.getModes = function () {
94 return this.modes
.slice();
97 /* eslint-disable no-unused-vars */
99 * ActionSets manage the behavior of the {@link OO.ui.ActionWidget action widgets} that comprise them.
100 * Actions can be made available for specific contexts (modes) and circumstances
101 * (abilities). Action sets are primarily used with {@link OO.ui.Dialog Dialogs}.
103 * ActionSets contain two types of actions:
105 * - Special: Special actions are the first visible actions with special flags, such as 'safe' and 'primary', the default special flags. Additional special flags can be configured in subclasses with the static #specialFlags property.
106 * - Other: Other actions include all non-special visible actions.
108 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
111 * // Example: An action set used in a process dialog
112 * function MyProcessDialog( config ) {
113 * MyProcessDialog.parent.call( this, config );
115 * OO.inheritClass( MyProcessDialog, OO.ui.ProcessDialog );
116 * MyProcessDialog.static.title = 'An action set in a process dialog';
117 * MyProcessDialog.static.name = 'myProcessDialog';
118 * // An action set that uses modes ('edit' and 'help' mode, in this example).
119 * MyProcessDialog.static.actions = [
120 * { action: 'continue', modes: 'edit', label: 'Continue', flags: [ 'primary', 'constructive' ] },
121 * { action: 'help', modes: 'edit', label: 'Help' },
122 * { modes: 'edit', label: 'Cancel', flags: 'safe' },
123 * { action: 'back', modes: 'help', label: 'Back', flags: 'safe' }
126 * MyProcessDialog.prototype.initialize = function () {
127 * MyProcessDialog.parent.prototype.initialize.apply( this, arguments );
128 * this.panel1 = new OO.ui.PanelLayout( { padded: true, expanded: false } );
129 * this.panel1.$element.append( '<p>This dialog uses an action set (continue, help, cancel, back) configured with modes. This is edit mode. Click \'help\' to see help mode.</p>' );
130 * this.panel2 = new OO.ui.PanelLayout( { padded: true, expanded: false } );
131 * this.panel2.$element.append( '<p>This is help mode. Only the \'back\' action widget is configured to be visible here. Click \'back\' to return to \'edit\' mode.</p>' );
132 * this.stackLayout = new OO.ui.StackLayout( {
133 * items: [ this.panel1, this.panel2 ]
135 * this.$body.append( this.stackLayout.$element );
137 * MyProcessDialog.prototype.getSetupProcess = function ( data ) {
138 * return MyProcessDialog.parent.prototype.getSetupProcess.call( this, data )
139 * .next( function () {
140 * this.actions.setMode( 'edit' );
143 * MyProcessDialog.prototype.getActionProcess = function ( action ) {
144 * if ( action === 'help' ) {
145 * this.actions.setMode( 'help' );
146 * this.stackLayout.setItem( this.panel2 );
147 * } else if ( action === 'back' ) {
148 * this.actions.setMode( 'edit' );
149 * this.stackLayout.setItem( this.panel1 );
150 * } else if ( action === 'continue' ) {
152 * return new OO.ui.Process( function () {
156 * return MyProcessDialog.parent.prototype.getActionProcess.call( this, action );
158 * MyProcessDialog.prototype.getBodyHeight = function () {
159 * return this.panel1.$element.outerHeight( true );
161 * var windowManager = new OO.ui.WindowManager();
162 * $( 'body' ).append( windowManager.$element );
163 * var dialog = new MyProcessDialog( {
166 * windowManager.addWindows( [ dialog ] );
167 * windowManager.openWindow( dialog );
169 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs#Action_sets
173 * @mixins OO.EventEmitter
176 * @param {Object} [config] Configuration options
178 OO
.ui
.ActionSet
= function OoUiActionSet( config
) {
179 // Configuration initialization
180 config
= config
|| {};
182 // Mixin constructors
183 OO
.EventEmitter
.call( this );
188 actions
: 'getAction',
192 this.categorized
= {};
195 this.organized
= false;
196 this.changing
= false;
197 this.changed
= false;
199 /* eslint-enable no-unused-vars */
203 OO
.mixinClass( OO
.ui
.ActionSet
, OO
.EventEmitter
);
205 /* Static Properties */
208 * Symbolic name of the flags used to identify special actions. Special actions are displayed in the
209 * header of a {@link OO.ui.ProcessDialog process dialog}.
210 * See the [OOjs UI documentation on MediaWiki][2] for more information and examples.
212 * [2]:https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs
219 OO
.ui
.ActionSet
.static.specialFlags
= [ 'safe', 'primary' ];
226 * A 'click' event is emitted when an action is clicked.
228 * @param {OO.ui.ActionWidget} action Action that was clicked
234 * An 'add' event is emitted when actions are {@link #method-add added} to the action set.
236 * @param {OO.ui.ActionWidget[]} added Actions added
242 * A 'remove' event is emitted when actions are {@link #method-remove removed}
243 * or {@link #clear cleared}.
245 * @param {OO.ui.ActionWidget[]} added Actions removed
251 * A 'change' event is emitted when actions are {@link #method-add added}, {@link #clear cleared},
252 * or {@link #method-remove removed} from the action set or when the {@link #setMode mode} is changed.
259 * Handle action change events.
264 OO
.ui
.ActionSet
.prototype.onActionChange = function () {
265 this.organized
= false;
266 if ( this.changing
) {
269 this.emit( 'change' );
274 * Check if an action is one of the special actions.
276 * @param {OO.ui.ActionWidget} action Action to check
277 * @return {boolean} Action is special
279 OO
.ui
.ActionSet
.prototype.isSpecial = function ( action
) {
282 for ( flag
in this.special
) {
283 if ( action
=== this.special
[ flag
] ) {
292 * Get action widgets based on the specified filter: ‘actions’, ‘flags’, ‘modes’, ‘visible’,
295 * @param {Object} [filters] Filters to use, omit to get all actions
296 * @param {string|string[]} [filters.actions] Actions that action widgets must have
297 * @param {string|string[]} [filters.flags] Flags that action widgets must have (e.g., 'safe')
298 * @param {string|string[]} [filters.modes] Modes that action widgets must have
299 * @param {boolean} [filters.visible] Action widgets must be visible
300 * @param {boolean} [filters.disabled] Action widgets must be disabled
301 * @return {OO.ui.ActionWidget[]} Action widgets matching all criteria
303 OO
.ui
.ActionSet
.prototype.get = function ( filters
) {
304 var i
, len
, list
, category
, actions
, index
, match
, matches
;
309 // Collect category candidates
311 for ( category
in this.categorized
) {
312 list
= filters
[ category
];
314 if ( !Array
.isArray( list
) ) {
317 for ( i
= 0, len
= list
.length
; i
< len
; i
++ ) {
318 actions
= this.categorized
[ category
][ list
[ i
] ];
319 if ( Array
.isArray( actions
) ) {
320 matches
.push
.apply( matches
, actions
);
325 // Remove by boolean filters
326 for ( i
= 0, len
= matches
.length
; i
< len
; i
++ ) {
327 match
= matches
[ i
];
329 ( filters
.visible
!== undefined && match
.isVisible() !== filters
.visible
) ||
330 ( filters
.disabled
!== undefined && match
.isDisabled() !== filters
.disabled
)
332 matches
.splice( i
, 1 );
338 for ( i
= 0, len
= matches
.length
; i
< len
; i
++ ) {
339 match
= matches
[ i
];
340 index
= matches
.lastIndexOf( match
);
341 while ( index
!== i
) {
342 matches
.splice( index
, 1 );
344 index
= matches
.lastIndexOf( match
);
349 return this.list
.slice();
353 * Get 'special' actions.
355 * Special actions are the first visible action widgets with special flags, such as 'safe' and 'primary'.
356 * Special flags can be configured in subclasses by changing the static #specialFlags property.
358 * @return {OO.ui.ActionWidget[]|null} 'Special' action widgets.
360 OO
.ui
.ActionSet
.prototype.getSpecial = function () {
362 return $.extend( {}, this.special
);
366 * Get 'other' actions.
368 * Other actions include all non-special visible action widgets.
370 * @return {OO.ui.ActionWidget[]} 'Other' action widgets
372 OO
.ui
.ActionSet
.prototype.getOthers = function () {
374 return this.others
.slice();
378 * Set the mode (e.g., ‘edit’ or ‘view’). Only {@link OO.ui.ActionWidget#modes actions} configured
379 * to be available in the specified mode will be made visible. All other actions will be hidden.
381 * @param {string} mode The mode. Only actions configured to be available in the specified
382 * mode will be made visible.
387 OO
.ui
.ActionSet
.prototype.setMode = function ( mode
) {
390 this.changing
= true;
391 for ( i
= 0, len
= this.list
.length
; i
< len
; i
++ ) {
392 action
= this.list
[ i
];
393 action
.toggle( action
.hasMode( mode
) );
396 this.organized
= false;
397 this.changing
= false;
398 this.emit( 'change' );
404 * Set the abilities of the specified actions.
406 * Action widgets that are configured with the specified actions will be enabled
407 * or disabled based on the boolean values specified in the `actions`
410 * @param {Object.<string,boolean>} actions A list keyed by action name with boolean
411 * values that indicate whether or not the action should be enabled.
414 OO
.ui
.ActionSet
.prototype.setAbilities = function ( actions
) {
415 var i
, len
, action
, item
;
417 for ( i
= 0, len
= this.list
.length
; i
< len
; i
++ ) {
418 item
= this.list
[ i
];
419 action
= item
.getAction();
420 if ( actions
[ action
] !== undefined ) {
421 item
.setDisabled( !actions
[ action
] );
429 * Executes a function once per action.
431 * When making changes to multiple actions, use this method instead of iterating over the actions
432 * manually to defer emitting a #change event until after all actions have been changed.
434 * @param {Object|null} filter Filters to use to determine which actions to iterate over; see #get
435 * @param {Function} callback Callback to run for each action; callback is invoked with three
436 * arguments: the action, the action's index, the list of actions being iterated over
439 OO
.ui
.ActionSet
.prototype.forEach = function ( filter
, callback
) {
440 this.changed
= false;
441 this.changing
= true;
442 this.get( filter
).forEach( callback
);
443 this.changing
= false;
444 if ( this.changed
) {
445 this.emit( 'change' );
452 * Add action widgets to the action set.
454 * @param {OO.ui.ActionWidget[]} actions Action widgets to add
459 OO
.ui
.ActionSet
.prototype.add = function ( actions
) {
462 this.changing
= true;
463 for ( i
= 0, len
= actions
.length
; i
< len
; i
++ ) {
464 action
= actions
[ i
];
465 action
.connect( this, {
466 click
: [ 'emit', 'click', action
],
467 toggle
: [ 'onActionChange' ]
469 this.list
.push( action
);
471 this.organized
= false;
472 this.emit( 'add', actions
);
473 this.changing
= false;
474 this.emit( 'change' );
480 * Remove action widgets from the set.
482 * To remove all actions, you may wish to use the #clear method instead.
484 * @param {OO.ui.ActionWidget[]} actions Action widgets to remove
489 OO
.ui
.ActionSet
.prototype.remove = function ( actions
) {
490 var i
, len
, index
, action
;
492 this.changing
= true;
493 for ( i
= 0, len
= actions
.length
; i
< len
; i
++ ) {
494 action
= actions
[ i
];
495 index
= this.list
.indexOf( action
);
496 if ( index
!== -1 ) {
497 action
.disconnect( this );
498 this.list
.splice( index
, 1 );
501 this.organized
= false;
502 this.emit( 'remove', actions
);
503 this.changing
= false;
504 this.emit( 'change' );
510 * Remove all action widets from the set.
512 * To remove only specified actions, use the {@link #method-remove remove} method instead.
518 OO
.ui
.ActionSet
.prototype.clear = function () {
520 removed
= this.list
.slice();
522 this.changing
= true;
523 for ( i
= 0, len
= this.list
.length
; i
< len
; i
++ ) {
524 action
= this.list
[ i
];
525 action
.disconnect( this );
530 this.organized
= false;
531 this.emit( 'remove', removed
);
532 this.changing
= false;
533 this.emit( 'change' );
541 * This is called whenever organized information is requested. It will only reorganize the actions
542 * if something has changed since the last time it ran.
547 OO
.ui
.ActionSet
.prototype.organize = function () {
548 var i
, iLen
, j
, jLen
, flag
, action
, category
, list
, item
, special
,
549 specialFlags
= this.constructor.static.specialFlags
;
551 if ( !this.organized
) {
552 this.categorized
= {};
555 for ( i
= 0, iLen
= this.list
.length
; i
< iLen
; i
++ ) {
556 action
= this.list
[ i
];
557 if ( action
.isVisible() ) {
558 // Populate categories
559 for ( category
in this.categories
) {
560 if ( !this.categorized
[ category
] ) {
561 this.categorized
[ category
] = {};
563 list
= action
[ this.categories
[ category
] ]();
564 if ( !Array
.isArray( list
) ) {
567 for ( j
= 0, jLen
= list
.length
; j
< jLen
; j
++ ) {
569 if ( !this.categorized
[ category
][ item
] ) {
570 this.categorized
[ category
][ item
] = [];
572 this.categorized
[ category
][ item
].push( action
);
575 // Populate special/others
577 for ( j
= 0, jLen
= specialFlags
.length
; j
< jLen
; j
++ ) {
578 flag
= specialFlags
[ j
];
579 if ( !this.special
[ flag
] && action
.hasFlag( flag
) ) {
580 this.special
[ flag
] = action
;
586 this.others
.push( action
);
590 this.organized
= true;
597 * Errors contain a required message (either a string or jQuery selection) that is used to describe what went wrong
598 * in a {@link OO.ui.Process process}. The error's #recoverable and #warning configurations are used to customize the
599 * appearance and functionality of the error interface.
601 * The basic error interface contains a formatted error message as well as two buttons: 'Dismiss' and 'Try again' (i.e., the error
602 * is 'recoverable' by default). If the error is not recoverable, the 'Try again' button will not be rendered and the widget
603 * that initiated the failed process will be disabled.
605 * If the error is a warning, the error interface will include a 'Dismiss' and a 'Continue' button, which will try the
608 * For an example of error interfaces, please see the [OOjs UI documentation on MediaWiki][1].
610 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs#Processes_and_errors
615 * @param {string|jQuery} message Description of error
616 * @param {Object} [config] Configuration options
617 * @cfg {boolean} [recoverable=true] Error is recoverable.
618 * By default, errors are recoverable, and users can try the process again.
619 * @cfg {boolean} [warning=false] Error is a warning.
620 * If the error is a warning, the error interface will include a
621 * 'Dismiss' and a 'Continue' button. It is the responsibility of the developer to ensure that the warning
622 * is not triggered a second time if the user chooses to continue.
624 OO
.ui
.Error
= function OoUiError( message
, config
) {
625 // Allow passing positional parameters inside the config object
626 if ( OO
.isPlainObject( message
) && config
=== undefined ) {
628 message
= config
.message
;
631 // Configuration initialization
632 config
= config
|| {};
635 this.message
= message
instanceof jQuery
? message
: String( message
);
636 this.recoverable
= config
.recoverable
=== undefined || !!config
.recoverable
;
637 this.warning
= !!config
.warning
;
642 OO
.initClass( OO
.ui
.Error
);
647 * Check if the error is recoverable.
649 * If the error is recoverable, users are able to try the process again.
651 * @return {boolean} Error is recoverable
653 OO
.ui
.Error
.prototype.isRecoverable = function () {
654 return this.recoverable
;
658 * Check if the error is a warning.
660 * If the error is a warning, the error interface will include a 'Dismiss' and a 'Continue' button.
662 * @return {boolean} Error is warning
664 OO
.ui
.Error
.prototype.isWarning = function () {
669 * Get error message as DOM nodes.
671 * @return {jQuery} Error message in DOM nodes
673 OO
.ui
.Error
.prototype.getMessage = function () {
674 return this.message
instanceof jQuery
?
675 this.message
.clone() :
676 $( '<div>' ).text( this.message
).contents();
680 * Get the error message text.
682 * @return {string} Error message
684 OO
.ui
.Error
.prototype.getMessageText = function () {
685 return this.message
instanceof jQuery
? this.message
.text() : this.message
;
689 * A Process is a list of steps that are called in sequence. The step can be a number, a jQuery promise,
692 * - **number**: the process will wait for the specified number of milliseconds before proceeding.
693 * - **promise**: the process will continue to the next step when the promise is successfully resolved
694 * or stop if the promise is rejected.
695 * - **function**: the process will execute the function. The process will stop if the function returns
696 * either a boolean `false` or a promise that is rejected; if the function returns a number, the process
697 * will wait for that number of milliseconds before proceeding.
699 * If the process fails, an {@link OO.ui.Error error} is generated. Depending on how the error is
700 * configured, users can dismiss the error and try the process again, or not. If a process is stopped,
701 * its remaining steps will not be performed.
706 * @param {number|jQuery.Promise|Function} step Number of miliseconds to wait before proceeding, promise
707 * that must be resolved before proceeding, or a function to execute. See #createStep for more information. see #createStep for more information
708 * @param {Object} [context=null] Execution context of the function. The context is ignored if the step is
709 * a number or promise.
711 OO
.ui
.Process = function ( step
, context
) {
716 if ( step
!== undefined ) {
717 this.next( step
, context
);
723 OO
.initClass( OO
.ui
.Process
);
730 * @return {jQuery.Promise} Promise that is resolved when all steps have successfully completed.
731 * If any of the steps return a promise that is rejected or a boolean false, this promise is rejected
732 * and any remaining steps are not performed.
734 OO
.ui
.Process
.prototype.execute = function () {
738 * Continue execution.
741 * @param {Array} step A function and the context it should be called in
742 * @return {Function} Function that continues the process
744 function proceed( step
) {
746 // Execute step in the correct context
748 result
= step
.callback
.call( step
.context
);
750 if ( result
=== false ) {
751 // Use rejected promise for boolean false results
752 return $.Deferred().reject( [] ).promise();
754 if ( typeof result
=== 'number' ) {
756 throw new Error( 'Cannot go back in time: flux capacitor is out of service' );
758 // Use a delayed promise for numbers, expecting them to be in milliseconds
759 deferred
= $.Deferred();
760 setTimeout( deferred
.resolve
, result
);
761 return deferred
.promise();
763 if ( result
instanceof OO
.ui
.Error
) {
764 // Use rejected promise for error
765 return $.Deferred().reject( [ result
] ).promise();
767 if ( Array
.isArray( result
) && result
.length
&& result
[ 0 ] instanceof OO
.ui
.Error
) {
768 // Use rejected promise for list of errors
769 return $.Deferred().reject( result
).promise();
771 // Duck-type the object to see if it can produce a promise
772 if ( result
&& $.isFunction( result
.promise
) ) {
773 // Use a promise generated from the result
774 return result
.promise();
776 // Use resolved promise for other results
777 return $.Deferred().resolve().promise();
781 if ( this.steps
.length
) {
782 // Generate a chain reaction of promises
783 promise
= proceed( this.steps
[ 0 ] )();
784 for ( i
= 1, len
= this.steps
.length
; i
< len
; i
++ ) {
785 promise
= promise
.then( proceed( this.steps
[ i
] ) );
788 promise
= $.Deferred().resolve().promise();
795 * Create a process step.
798 * @param {number|jQuery.Promise|Function} step
800 * - Number of milliseconds to wait before proceeding
801 * - Promise that must be resolved before proceeding
802 * - Function to execute
803 * - If the function returns a boolean false the process will stop
804 * - If the function returns a promise, the process will continue to the next
805 * step when the promise is resolved or stop if the promise is rejected
806 * - If the function returns a number, the process will wait for that number of
807 * milliseconds before proceeding
808 * @param {Object} [context=null] Execution context of the function. The context is
809 * ignored if the step is a number or promise.
810 * @return {Object} Step object, with `callback` and `context` properties
812 OO
.ui
.Process
.prototype.createStep = function ( step
, context
) {
813 if ( typeof step
=== 'number' || $.isFunction( step
.promise
) ) {
815 callback: function () {
821 if ( $.isFunction( step
) ) {
827 throw new Error( 'Cannot create process step: number, promise or function expected' );
831 * Add step to the beginning of the process.
833 * @inheritdoc #createStep
834 * @return {OO.ui.Process} this
837 OO
.ui
.Process
.prototype.first = function ( step
, context
) {
838 this.steps
.unshift( this.createStep( step
, context
) );
843 * Add step to the end of the process.
845 * @inheritdoc #createStep
846 * @return {OO.ui.Process} this
849 OO
.ui
.Process
.prototype.next = function ( step
, context
) {
850 this.steps
.push( this.createStep( step
, context
) );
855 * A window instance represents the life cycle for one single opening of a window
858 * While OO.ui.WindowManager will reuse OO.ui.Window objects, each time a window is
859 * opened, a new lifecycle starts.
861 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
863 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows
869 OO
.ui
.WindowInstance
= function OOuiWindowInstance() {
871 opening
: $.Deferred(),
872 opened
: $.Deferred(),
873 closing
: $.Deferred(),
881 this.deferreds
= deferreds
;
883 // Set these up as chained promises so that rejecting of
884 // an earlier stage automatically rejects the subsequent
885 // would-be stages as well.
888 * @property {jQuery.Promise}
890 this.opening
= deferreds
.opening
.promise();
892 * @property {jQuery.Promise}
894 this.opened
= this.opening
.then( function () {
895 return deferreds
.opened
;
898 * @property {jQuery.Promise}
900 this.closing
= this.opened
.then( function () {
901 return deferreds
.closing
;
904 * @property {jQuery.Promise}
906 this.closed
= this.closing
.then( function () {
907 return deferreds
.closed
;
913 OO
.initClass( OO
.ui
.WindowInstance
);
916 * Check if window is opening.
918 * @return {boolean} Window is opening
920 OO
.ui
.WindowInstance
.prototype.isOpening = function () {
921 return this.deferreds
.opened
.state() === 'pending';
925 * Check if window is opened.
927 * @return {boolean} Window is opened
929 OO
.ui
.WindowInstance
.prototype.isOpened = function () {
930 return this.deferreds
.opened
.state() === 'resolved' &&
931 this.deferreds
.closing
.state() === 'pending';
935 * Check if window is closing.
937 * @return {boolean} Window is closing
939 OO
.ui
.WindowInstance
.prototype.isClosing = function () {
940 return this.deferreds
.closing
.state() === 'resolved' &&
941 this.deferreds
.closed
.state() === 'pending';
945 * Check if window is closed.
947 * @return {boolean} Window is closed
949 OO
.ui
.WindowInstance
.prototype.isClosed = function () {
950 return this.deferreds
.closed
.state() === 'resolved';
954 * Window managers are used to open and close {@link OO.ui.Window windows} and control their presentation.
955 * Managed windows are mutually exclusive. If a new window is opened while a current window is opening
956 * or is opened, the current window will be closed and any ongoing {@link OO.ui.Process process} will be cancelled. Windows
957 * themselves are persistent and—rather than being torn down when closed—can be repopulated with the
958 * pertinent data and reused.
960 * Over the lifecycle of a window, the window manager makes available three promises: `opening`,
961 * `opened`, and `closing`, which represent the primary stages of the cycle:
963 * **Opening**: the opening stage begins when the window manager’s #openWindow or a window’s
964 * {@link OO.ui.Window#open open} method is used, and the window manager begins to open the window.
966 * - an `opening` event is emitted with an `opening` promise
967 * - the #getSetupDelay method is called and the returned value is used to time a pause in execution before the
968 * window’s {@link OO.ui.Window#method-setup setup} method is called which executes OO.ui.Window#getSetupProcess.
969 * - a `setup` progress notification is emitted from the `opening` promise
970 * - the #getReadyDelay method is called the returned value is used to time a pause in execution before the
971 * window’s {@link OO.ui.Window#method-ready ready} method is called which executes OO.ui.Window#getReadyProcess.
972 * - a `ready` progress notification is emitted from the `opening` promise
973 * - the `opening` promise is resolved with an `opened` promise
975 * **Opened**: the window is now open.
977 * **Closing**: the closing stage begins when the window manager's #closeWindow or the
978 * window's {@link OO.ui.Window#close close} methods is used, and the window manager begins
979 * to close the window.
981 * - the `opened` promise is resolved with `closing` promise and a `closing` event is emitted
982 * - the #getHoldDelay method is called and the returned value is used to time a pause in execution before
983 * the window's {@link OO.ui.Window#getHoldProcess getHoldProces} method is called on the
984 * window and its result executed
985 * - a `hold` progress notification is emitted from the `closing` promise
986 * - the #getTeardownDelay() method is called and the returned value is used to time a pause in execution before
987 * the window's {@link OO.ui.Window#getTeardownProcess getTeardownProcess} method is called on the
988 * window and its result executed
989 * - a `teardown` progress notification is emitted from the `closing` promise
990 * - the `closing` promise is resolved. The window is now closed
992 * See the [OOjs UI documentation on MediaWiki][1] for more information.
994 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Window_managers
997 * @extends OO.ui.Element
998 * @mixins OO.EventEmitter
1001 * @param {Object} [config] Configuration options
1002 * @cfg {OO.Factory} [factory] Window factory to use for automatic instantiation
1003 * Note that window classes that are instantiated with a factory must have
1004 * a {@link OO.ui.Dialog#static-name static name} property that specifies a symbolic name.
1005 * @cfg {boolean} [modal=true] Prevent interaction outside the dialog
1007 OO
.ui
.WindowManager
= function OoUiWindowManager( config
) {
1008 // Configuration initialization
1009 config
= config
|| {};
1011 // Parent constructor
1012 OO
.ui
.WindowManager
.parent
.call( this, config
);
1014 // Mixin constructors
1015 OO
.EventEmitter
.call( this );
1018 this.factory
= config
.factory
;
1019 this.modal
= config
.modal
=== undefined || !!config
.modal
;
1021 // Deprecated placeholder promise given to compatOpening in openWindow()
1022 // that is resolved in closeWindow().
1023 this.compatOpened
= null;
1024 this.preparingToOpen
= null;
1025 this.preparingToClose
= null;
1026 this.currentWindow
= null;
1027 this.globalEvents
= false;
1028 this.$returnFocusTo
= null;
1029 this.$ariaHidden
= null;
1030 this.onWindowResizeTimeout
= null;
1031 this.onWindowResizeHandler
= this.onWindowResize
.bind( this );
1032 this.afterWindowResizeHandler
= this.afterWindowResize
.bind( this );
1036 .addClass( 'oo-ui-windowManager' )
1037 .toggleClass( 'oo-ui-windowManager-modal', this.modal
);
1042 OO
.inheritClass( OO
.ui
.WindowManager
, OO
.ui
.Element
);
1043 OO
.mixinClass( OO
.ui
.WindowManager
, OO
.EventEmitter
);
1048 * An 'opening' event is emitted when the window begins to be opened.
1051 * @param {OO.ui.Window} win Window that's being opened
1052 * @param {jQuery.Promise} opened A promise resolved with a value when the window is opened successfully.
1053 * This promise also emits `setup` and `ready` notifications. When this promise is resolved, the first
1054 * argument of the value is an 'closed' promise, the second argument is the opening data.
1055 * @param {Object} data Window opening data
1059 * A 'closing' event is emitted when the window begins to be closed.
1062 * @param {OO.ui.Window} win Window that's being closed
1063 * @param {jQuery.Promise} closed A promise resolved with a value when the window is closed successfully.
1064 * This promise also emits `hold` and `teardown` notifications. When this promise is resolved, the first
1065 * argument of its value is the closing data.
1066 * @param {Object} data Window closing data
1070 * A 'resize' event is emitted when a window is resized.
1073 * @param {OO.ui.Window} win Window that was resized
1076 /* Static Properties */
1079 * Map of the symbolic name of each window size and its CSS properties.
1083 * @property {Object}
1085 OO
.ui
.WindowManager
.static.sizes
= {
1099 // These can be non-numeric because they are never used in calculations
1106 * Symbolic name of the default window size.
1108 * The default size is used if the window's requested size is not recognized.
1112 * @property {string}
1114 OO
.ui
.WindowManager
.static.defaultSize
= 'medium';
1119 * Handle window resize events.
1122 * @param {jQuery.Event} e Window resize event
1124 OO
.ui
.WindowManager
.prototype.onWindowResize = function () {
1125 clearTimeout( this.onWindowResizeTimeout
);
1126 this.onWindowResizeTimeout
= setTimeout( this.afterWindowResizeHandler
, 200 );
1130 * Handle window resize events.
1133 * @param {jQuery.Event} e Window resize event
1135 OO
.ui
.WindowManager
.prototype.afterWindowResize = function () {
1136 if ( this.currentWindow
) {
1137 this.updateWindowSize( this.currentWindow
);
1142 * Check if window is opening.
1144 * @param {OO.ui.Window} win Window to check
1145 * @return {boolean} Window is opening
1147 OO
.ui
.WindowManager
.prototype.isOpening = function ( win
) {
1148 return win
=== this.currentWindow
&& !!this.lifecycle
&&
1149 this.lifecycle
.isOpening();
1153 * Check if window is closing.
1155 * @param {OO.ui.Window} win Window to check
1156 * @return {boolean} Window is closing
1158 OO
.ui
.WindowManager
.prototype.isClosing = function ( win
) {
1159 return win
=== this.currentWindow
&& !!this.lifecycle
&&
1160 this.lifecycle
.isClosing();
1164 * Check if window is opened.
1166 * @param {OO.ui.Window} win Window to check
1167 * @return {boolean} Window is opened
1169 OO
.ui
.WindowManager
.prototype.isOpened = function ( win
) {
1170 return win
=== this.currentWindow
&& !!this.lifecycle
&&
1171 this.lifecycle
.isOpened();
1175 * Check if a window is being managed.
1177 * @param {OO.ui.Window} win Window to check
1178 * @return {boolean} Window is being managed
1180 OO
.ui
.WindowManager
.prototype.hasWindow = function ( win
) {
1183 for ( name
in this.windows
) {
1184 if ( this.windows
[ name
] === win
) {
1193 * Get the number of milliseconds to wait after opening begins before executing the ‘setup’ process.
1195 * @param {OO.ui.Window} win Window being opened
1196 * @param {Object} [data] Window opening data
1197 * @return {number} Milliseconds to wait
1199 OO
.ui
.WindowManager
.prototype.getSetupDelay = function () {
1204 * Get the number of milliseconds to wait after setup has finished before executing the ‘ready’ process.
1206 * @param {OO.ui.Window} win Window being opened
1207 * @param {Object} [data] Window opening data
1208 * @return {number} Milliseconds to wait
1210 OO
.ui
.WindowManager
.prototype.getReadyDelay = function () {
1215 * Get the number of milliseconds to wait after closing has begun before executing the 'hold' process.
1217 * @param {OO.ui.Window} win Window being closed
1218 * @param {Object} [data] Window closing data
1219 * @return {number} Milliseconds to wait
1221 OO
.ui
.WindowManager
.prototype.getHoldDelay = function () {
1226 * Get the number of milliseconds to wait after the ‘hold’ process has finished before
1227 * executing the ‘teardown’ process.
1229 * @param {OO.ui.Window} win Window being closed
1230 * @param {Object} [data] Window closing data
1231 * @return {number} Milliseconds to wait
1233 OO
.ui
.WindowManager
.prototype.getTeardownDelay = function () {
1234 return this.modal
? 250 : 0;
1238 * Get a window by its symbolic name.
1240 * If the window is not yet instantiated and its symbolic name is recognized by a factory, it will be
1241 * instantiated and added to the window manager automatically. Please see the [OOjs UI documentation on MediaWiki][3]
1242 * for more information about using factories.
1243 * [3]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Window_managers
1245 * @param {string} name Symbolic name of the window
1246 * @return {jQuery.Promise} Promise resolved with matching window, or rejected with an OO.ui.Error
1247 * @throws {Error} An error is thrown if the symbolic name is not recognized by the factory.
1248 * @throws {Error} An error is thrown if the named window is not recognized as a managed window.
1250 OO
.ui
.WindowManager
.prototype.getWindow = function ( name
) {
1251 var deferred
= $.Deferred(),
1252 win
= this.windows
[ name
];
1254 if ( !( win
instanceof OO
.ui
.Window
) ) {
1255 if ( this.factory
) {
1256 if ( !this.factory
.lookup( name
) ) {
1257 deferred
.reject( new OO
.ui
.Error(
1258 'Cannot auto-instantiate window: symbolic name is unrecognized by the factory'
1261 win
= this.factory
.create( name
);
1262 this.addWindows( [ win
] );
1263 deferred
.resolve( win
);
1266 deferred
.reject( new OO
.ui
.Error(
1267 'Cannot get unmanaged window: symbolic name unrecognized as a managed window'
1271 deferred
.resolve( win
);
1274 return deferred
.promise();
1278 * Get current window.
1280 * @return {OO.ui.Window|null} Currently opening/opened/closing window
1282 OO
.ui
.WindowManager
.prototype.getCurrentWindow = function () {
1283 return this.currentWindow
;
1289 * @param {OO.ui.Window|string} win Window object or symbolic name of window to open
1290 * @param {Object} [data] Window opening data
1291 * @param {jQuery|null} [data.$returnFocusTo] Element to which the window will return focus when closed.
1292 * Defaults the current activeElement. If set to null, focus isn't changed on close.
1293 * @return {OO.ui.WindowInstance|jQuery.Promise} A lifecycle object representing this particular
1294 * opening of the window. For backwards-compatibility, then object is also a Thenable that is resolved
1295 * when the window is done opening, with nested promise for when closing starts. This behaviour
1296 * is deprecated and is not compatible with jQuery 3 (T163510).
1299 OO
.ui
.WindowManager
.prototype.openWindow = function ( win
, data
, lifecycle
, compatOpening
) {
1304 // Internal parameter 'lifecycle' allows this method to always return
1305 // a lifecycle even if the window still needs to be created
1306 // asynchronously when 'win' is a string.
1307 lifecycle
= lifecycle
|| new OO
.ui
.WindowInstance();
1308 compatOpening
= compatOpening
|| $.Deferred();
1310 // Turn lifecycle into a Thenable for backwards-compatibility with
1311 // the deprecated nested-promise behaviour (T163510).
1312 [ 'state', 'always', 'catch', 'pipe', 'then', 'promise', 'progress', 'done', 'fail' ]
1313 .forEach( function ( method
) {
1314 lifecycle
[ method
] = function () {
1315 OO
.ui
.warnDeprecation(
1316 'Using the return value of openWindow as a promise is deprecated. ' +
1317 'Use .openWindow( ... ).opening.' + method
+ '( ... ) instead.'
1319 return compatOpening
[ method
].apply( this, arguments
);
1323 // Argument handling
1324 if ( typeof win
=== 'string' ) {
1325 this.getWindow( win
).then(
1327 manager
.openWindow( win
, data
, lifecycle
, compatOpening
);
1330 lifecycle
.deferreds
.opening
.reject( err
);
1337 if ( !this.hasWindow( win
) ) {
1338 error
= 'Cannot open window: window is not attached to manager';
1339 } else if ( this.lifecycle
&& this.lifecycle
.isOpened() ) {
1340 error
= 'Cannot open window: another window is open';
1341 } else if ( this.preparingToOpen
|| ( this.lifecycle
&& this.lifecycle
.isOpening() ) ) {
1342 error
= 'Cannot open window: another window is opening';
1346 compatOpening
.reject( new OO
.ui
.Error( error
) );
1347 lifecycle
.deferreds
.opening
.reject( new OO
.ui
.Error( error
) );
1351 // If a window is currently closing, wait for it to complete
1352 this.preparingToOpen
= $.when( this.lifecycle
&& this.lifecycle
.closed
);
1353 // Ensure handlers get called after preparingToOpen is set
1354 this.preparingToOpen
.done( function () {
1355 if ( manager
.modal
) {
1356 manager
.toggleGlobalEvents( true );
1357 manager
.toggleAriaIsolation( true );
1359 manager
.$returnFocusTo
= data
.$returnFocusTo
!== undefined ? data
.$returnFocusTo
: $( document
.activeElement
);
1360 manager
.currentWindow
= win
;
1361 manager
.lifecycle
= lifecycle
;
1362 manager
.preparingToOpen
= null;
1363 manager
.emit( 'opening', win
, compatOpening
, data
);
1364 lifecycle
.deferreds
.opening
.resolve( data
);
1365 setTimeout( function () {
1366 manager
.compatOpened
= $.Deferred();
1367 win
.setup( data
).then( function () {
1368 manager
.updateWindowSize( win
);
1369 compatOpening
.notify( { state
: 'setup' } );
1370 setTimeout( function () {
1371 win
.ready( data
).then( function () {
1372 compatOpening
.notify( { state
: 'ready' } );
1373 lifecycle
.deferreds
.opened
.resolve( data
);
1374 compatOpening
.resolve( manager
.compatOpened
.promise(), data
);
1376 lifecycle
.deferreds
.opened
.reject();
1377 compatOpening
.reject();
1378 manager
.closeWindow( win
);
1380 }, manager
.getReadyDelay() );
1382 lifecycle
.deferreds
.opened
.reject();
1383 compatOpening
.reject();
1384 manager
.closeWindow( win
);
1386 }, manager
.getSetupDelay() );
1395 * @param {OO.ui.Window|string} win Window object or symbolic name of window to close
1396 * @param {Object} [data] Window closing data
1397 * @return {OO.ui.WindowInstance|jQuery.Promise} A lifecycle object representing this particular
1398 * opening of the window. For backwards-compatibility, the object is also a Thenable that is resolved
1399 * when the window is done closing (T163510).
1402 OO
.ui
.WindowManager
.prototype.closeWindow = function ( win
, data
) {
1405 compatClosing
= $.Deferred(),
1406 lifecycle
= this.lifecycle
,
1409 // Argument handling
1410 if ( typeof win
=== 'string' ) {
1411 win
= this.windows
[ win
];
1412 } else if ( !this.hasWindow( win
) ) {
1418 error
= 'Cannot close window: no window is currently open';
1419 } else if ( !win
) {
1420 error
= 'Cannot close window: window is not attached to manager';
1421 } else if ( win
!== this.currentWindow
|| this.lifecycle
.isClosed() ) {
1422 error
= 'Cannot close window: window already closed with different data';
1423 } else if ( this.preparingToClose
|| this.lifecycle
.isClosing() ) {
1424 error
= 'Cannot close window: window already closing with different data';
1428 // This function was called for the wrong window and we don't want to mess with the current
1430 lifecycle
= new OO
.ui
.WindowInstance();
1431 // Pretend the window has been opened, so that we can pretend to fail to close it.
1432 lifecycle
.deferreds
.opening
.resolve( {} );
1433 lifecycle
.deferreds
.opened
.resolve( {} );
1436 // Turn lifecycle into a Thenable for backwards-compatibility with
1437 // the deprecated nested-promise behaviour (T163510).
1438 [ 'state', 'always', 'catch', 'pipe', 'then', 'promise', 'progress', 'done', 'fail' ]
1439 .forEach( function ( method
) {
1440 lifecycle
[ method
] = function () {
1441 OO
.ui
.warnDeprecation(
1442 'Using the return value of closeWindow as a promise is deprecated. ' +
1443 'Use .closeWindow( ... ).closed.' + method
+ '( ... ) instead.'
1445 return compatClosing
[ method
].apply( this, arguments
);
1450 compatClosing
.reject( new OO
.ui
.Error( error
) );
1451 lifecycle
.deferreds
.closing
.reject( new OO
.ui
.Error( error
) );
1455 // If the window is currently opening, close it when it's done
1456 this.preparingToClose
= $.when( this.lifecycle
.opened
);
1457 // Ensure handlers get called after preparingToClose is set
1458 this.preparingToClose
.always( function () {
1459 manager
.preparingToClose
= null;
1460 manager
.emit( 'closing', win
, compatClosing
, data
);
1461 lifecycle
.deferreds
.closing
.resolve( data
);
1462 compatOpened
= manager
.compatOpened
;
1463 manager
.compatOpened
= null;
1464 compatOpened
.resolve( compatClosing
.promise(), data
);
1465 setTimeout( function () {
1466 win
.hold( data
).then( function () {
1467 compatClosing
.notify( { state
: 'hold' } );
1468 setTimeout( function () {
1469 win
.teardown( data
).then( function () {
1470 compatClosing
.notify( { state
: 'teardown' } );
1471 if ( manager
.modal
) {
1472 manager
.toggleGlobalEvents( false );
1473 manager
.toggleAriaIsolation( false );
1475 if ( manager
.$returnFocusTo
&& manager
.$returnFocusTo
.length
) {
1476 manager
.$returnFocusTo
[ 0 ].focus();
1478 manager
.currentWindow
= null;
1479 manager
.lifecycle
= null;
1480 lifecycle
.deferreds
.closed
.resolve( data
);
1481 compatClosing
.resolve( data
);
1483 }, manager
.getTeardownDelay() );
1485 }, manager
.getHoldDelay() );
1492 * Add windows to the window manager.
1494 * Windows can be added by reference, symbolic name, or explicitly defined symbolic names.
1495 * See the [OOjs ui documentation on MediaWiki] [2] for examples.
1496 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Window_managers
1498 * This function can be called in two manners:
1500 * 1. `.addWindows( [ windowA, windowB, ... ] )` (where `windowA`, `windowB` are OO.ui.Window objects)
1502 * This syntax registers windows under the symbolic names defined in their `.static.name`
1503 * properties. For example, if `windowA.constructor.static.name` is `'nameA'`, calling
1504 * `.openWindow( 'nameA' )` afterwards will open the window `windowA`. This syntax requires the
1505 * static name to be set, otherwise an exception will be thrown.
1507 * This is the recommended way, as it allows for an easier switch to using a window factory.
1509 * 2. `.addWindows( { nameA: windowA, nameB: windowB, ... } )`
1511 * This syntax registers windows under the explicitly given symbolic names. In this example,
1512 * calling `.openWindow( 'nameA' )` afterwards will open the window `windowA`, regardless of what
1513 * its `.static.name` is set to. The static name is not required to be set.
1515 * This should only be used if you need to override the default symbolic names.
1519 * var windowManager = new OO.ui.WindowManager();
1520 * $( 'body' ).append( windowManager.$element );
1522 * // Add a window under the default name: see OO.ui.MessageDialog.static.name
1523 * windowManager.addWindows( [ new OO.ui.MessageDialog() ] );
1524 * // Add a window under an explicit name
1525 * windowManager.addWindows( { myMessageDialog: new OO.ui.MessageDialog() } );
1527 * // Open window by default name
1528 * windowManager.openWindow( 'message' );
1529 * // Open window by explicitly given name
1530 * windowManager.openWindow( 'myMessageDialog' );
1533 * @param {Object.<string,OO.ui.Window>|OO.ui.Window[]} windows An array of window objects specified
1534 * by reference, symbolic name, or explicitly defined symbolic names.
1535 * @throws {Error} An error is thrown if a window is added by symbolic name, but has neither an
1536 * explicit nor a statically configured symbolic name.
1538 OO
.ui
.WindowManager
.prototype.addWindows = function ( windows
) {
1539 var i
, len
, win
, name
, list
;
1541 if ( Array
.isArray( windows
) ) {
1542 // Convert to map of windows by looking up symbolic names from static configuration
1544 for ( i
= 0, len
= windows
.length
; i
< len
; i
++ ) {
1545 name
= windows
[ i
].constructor.static.name
;
1547 throw new Error( 'Windows must have a `name` static property defined.' );
1549 list
[ name
] = windows
[ i
];
1551 } else if ( OO
.isPlainObject( windows
) ) {
1556 for ( name
in list
) {
1558 this.windows
[ name
] = win
.toggle( false );
1559 this.$element
.append( win
.$element
);
1560 win
.setManager( this );
1565 * Remove the specified windows from the windows manager.
1567 * Windows will be closed before they are removed. If you wish to remove all windows, you may wish to use
1568 * the #clearWindows method instead. If you no longer need the window manager and want to ensure that it no
1569 * longer listens to events, use the #destroy method.
1571 * @param {string[]} names Symbolic names of windows to remove
1572 * @return {jQuery.Promise} Promise resolved when window is closed and removed
1573 * @throws {Error} An error is thrown if the named windows are not managed by the window manager.
1575 OO
.ui
.WindowManager
.prototype.removeWindows = function ( names
) {
1576 var i
, len
, win
, name
, cleanupWindow
,
1579 cleanup = function ( name
, win
) {
1580 delete manager
.windows
[ name
];
1581 win
.$element
.detach();
1584 for ( i
= 0, len
= names
.length
; i
< len
; i
++ ) {
1586 win
= this.windows
[ name
];
1588 throw new Error( 'Cannot remove window' );
1590 cleanupWindow
= cleanup
.bind( null, name
, win
);
1591 promises
.push( this.closeWindow( name
).closed
.then( cleanupWindow
, cleanupWindow
) );
1594 return $.when
.apply( $, promises
);
1598 * Remove all windows from the window manager.
1600 * Windows will be closed before they are removed. Note that the window manager, though not in use, will still
1601 * listen to events. If the window manager will not be used again, you may wish to use the #destroy method instead.
1602 * To remove just a subset of windows, use the #removeWindows method.
1604 * @return {jQuery.Promise} Promise resolved when all windows are closed and removed
1606 OO
.ui
.WindowManager
.prototype.clearWindows = function () {
1607 return this.removeWindows( Object
.keys( this.windows
) );
1611 * Set dialog size. In general, this method should not be called directly.
1613 * Fullscreen mode will be used if the dialog is too wide to fit in the screen.
1615 * @param {OO.ui.Window} win Window to update, should be the current window
1618 OO
.ui
.WindowManager
.prototype.updateWindowSize = function ( win
) {
1621 // Bypass for non-current, and thus invisible, windows
1622 if ( win
!== this.currentWindow
) {
1626 isFullscreen
= win
.getSize() === 'full';
1628 this.$element
.toggleClass( 'oo-ui-windowManager-fullscreen', isFullscreen
);
1629 this.$element
.toggleClass( 'oo-ui-windowManager-floating', !isFullscreen
);
1630 win
.setDimensions( win
.getSizeProperties() );
1632 this.emit( 'resize', win
);
1638 * Bind or unbind global events for scrolling.
1641 * @param {boolean} [on] Bind global events
1644 OO
.ui
.WindowManager
.prototype.toggleGlobalEvents = function ( on
) {
1645 var scrollWidth
, bodyMargin
,
1646 $body
= $( this.getElementDocument().body
),
1647 // We could have multiple window managers open so only modify
1648 // the body css at the bottom of the stack
1649 stackDepth
= $body
.data( 'windowManagerGlobalEvents' ) || 0;
1651 on
= on
=== undefined ? !!this.globalEvents
: !!on
;
1654 if ( !this.globalEvents
) {
1655 $( this.getElementWindow() ).on( {
1656 // Start listening for top-level window dimension changes
1657 'orientationchange resize': this.onWindowResizeHandler
1659 if ( stackDepth
=== 0 ) {
1660 scrollWidth
= window
.innerWidth
- document
.documentElement
.clientWidth
;
1661 bodyMargin
= parseFloat( $body
.css( 'margin-right' ) ) || 0;
1664 'margin-right': bodyMargin
+ scrollWidth
1668 this.globalEvents
= true;
1670 } else if ( this.globalEvents
) {
1671 $( this.getElementWindow() ).off( {
1672 // Stop listening for top-level window dimension changes
1673 'orientationchange resize': this.onWindowResizeHandler
1676 if ( stackDepth
=== 0 ) {
1682 this.globalEvents
= false;
1684 $body
.data( 'windowManagerGlobalEvents', stackDepth
);
1690 * Toggle screen reader visibility of content other than the window manager.
1693 * @param {boolean} [isolate] Make only the window manager visible to screen readers
1696 OO
.ui
.WindowManager
.prototype.toggleAriaIsolation = function ( isolate
) {
1697 isolate
= isolate
=== undefined ? !this.$ariaHidden
: !!isolate
;
1700 if ( !this.$ariaHidden
) {
1701 // Hide everything other than the window manager from screen readers
1702 this.$ariaHidden
= $( 'body' )
1704 .not( this.$element
.parentsUntil( 'body' ).last() )
1705 .attr( 'aria-hidden', '' );
1707 } else if ( this.$ariaHidden
) {
1708 // Restore screen reader visibility
1709 this.$ariaHidden
.removeAttr( 'aria-hidden' );
1710 this.$ariaHidden
= null;
1717 * Destroy the window manager.
1719 * Destroying the window manager ensures that it will no longer listen to events. If you would like to
1720 * continue using the window manager, but wish to remove all windows from it, use the #clearWindows method
1723 OO
.ui
.WindowManager
.prototype.destroy = function () {
1724 this.toggleGlobalEvents( false );
1725 this.toggleAriaIsolation( false );
1726 this.clearWindows();
1727 this.$element
.remove();
1731 * A window is a container for elements that are in a child frame. They are used with
1732 * a window manager (OO.ui.WindowManager), which is used to open and close the window and control
1733 * its presentation. The size of a window is specified using a symbolic name (e.g., ‘small’, ‘medium’,
1734 * ‘large’), which is interpreted by the window manager. If the requested size is not recognized,
1735 * the window manager will choose a sensible fallback.
1737 * The lifecycle of a window has three primary stages (opening, opened, and closing) in which
1738 * different processes are executed:
1740 * **opening**: The opening stage begins when the window manager's {@link OO.ui.WindowManager#openWindow
1741 * openWindow} or the window's {@link #open open} methods are used, and the window manager begins to open
1744 * - {@link #getSetupProcess} method is called and its result executed
1745 * - {@link #getReadyProcess} method is called and its result executed
1747 * **opened**: The window is now open
1749 * **closing**: The closing stage begins when the window manager's
1750 * {@link OO.ui.WindowManager#closeWindow closeWindow}
1751 * or the window's {@link #close} methods are used, and the window manager begins to close the window.
1753 * - {@link #getHoldProcess} method is called and its result executed
1754 * - {@link #getTeardownProcess} method is called and its result executed. The window is now closed
1756 * Each of the window's processes (setup, ready, hold, and teardown) can be extended in subclasses
1757 * by overriding the window's #getSetupProcess, #getReadyProcess, #getHoldProcess and #getTeardownProcess
1758 * methods. Note that each {@link OO.ui.Process process} is executed in series, so asynchronous
1759 * processing can complete. Always assume window processes are executed asynchronously.
1761 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
1763 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows
1767 * @extends OO.ui.Element
1768 * @mixins OO.EventEmitter
1771 * @param {Object} [config] Configuration options
1772 * @cfg {string} [size] Symbolic name of the dialog size: `small`, `medium`, `large`, `larger` or
1773 * `full`. If omitted, the value of the {@link #static-size static size} property will be used.
1775 OO
.ui
.Window
= function OoUiWindow( config
) {
1776 // Configuration initialization
1777 config
= config
|| {};
1779 // Parent constructor
1780 OO
.ui
.Window
.parent
.call( this, config
);
1782 // Mixin constructors
1783 OO
.EventEmitter
.call( this );
1786 this.manager
= null;
1787 this.size
= config
.size
|| this.constructor.static.size
;
1788 this.$frame
= $( '<div>' );
1790 * Overlay element to use for the `$overlay` configuration option of widgets that support it.
1791 * Things put inside of it are overlaid on top of the window and are not bound to its dimensions.
1792 * See <https://www.mediawiki.org/wiki/OOjs_UI/Concepts#Overlays>.
1794 * MyDialog.prototype.initialize = function () {
1796 * var popupButton = new OO.ui.PopupButtonWidget( {
1797 * $overlay: this.$overlay,
1798 * label: 'Popup button',
1800 * $content: $( '<p>Popup contents.</p><p>Popup contents.</p><p>Popup contents.</p>' ),
1807 * @property {jQuery}
1809 this.$overlay
= $( '<div>' );
1810 this.$content
= $( '<div>' );
1812 this.$focusTrapBefore
= $( '<div>' ).prop( 'tabIndex', 0 );
1813 this.$focusTrapAfter
= $( '<div>' ).prop( 'tabIndex', 0 );
1814 this.$focusTraps
= this.$focusTrapBefore
.add( this.$focusTrapAfter
);
1817 this.$overlay
.addClass( 'oo-ui-window-overlay' );
1819 .addClass( 'oo-ui-window-content' )
1820 .attr( 'tabindex', 0 );
1822 .addClass( 'oo-ui-window-frame' )
1823 .append( this.$focusTrapBefore
, this.$content
, this.$focusTrapAfter
);
1826 .addClass( 'oo-ui-window' )
1827 .append( this.$frame
, this.$overlay
);
1829 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
1830 // that reference properties not initialized at that time of parent class construction
1831 // TODO: Find a better way to handle post-constructor setup
1832 this.visible
= false;
1833 this.$element
.addClass( 'oo-ui-element-hidden' );
1838 OO
.inheritClass( OO
.ui
.Window
, OO
.ui
.Element
);
1839 OO
.mixinClass( OO
.ui
.Window
, OO
.EventEmitter
);
1841 /* Static Properties */
1844 * Symbolic name of the window size: `small`, `medium`, `large`, `larger` or `full`.
1846 * The static size is used if no #size is configured during construction.
1850 * @property {string}
1852 OO
.ui
.Window
.static.size
= 'medium';
1857 * Handle mouse down events.
1860 * @param {jQuery.Event} e Mouse down event
1862 OO
.ui
.Window
.prototype.onMouseDown = function ( e
) {
1863 // Prevent clicking on the click-block from stealing focus
1864 if ( e
.target
=== this.$element
[ 0 ] ) {
1870 * Check if the window has been initialized.
1872 * Initialization occurs when a window is added to a manager.
1874 * @return {boolean} Window has been initialized
1876 OO
.ui
.Window
.prototype.isInitialized = function () {
1877 return !!this.manager
;
1881 * Check if the window is visible.
1883 * @return {boolean} Window is visible
1885 OO
.ui
.Window
.prototype.isVisible = function () {
1886 return this.visible
;
1890 * Check if the window is opening.
1892 * This method is a wrapper around the window manager's {@link OO.ui.WindowManager#isOpening isOpening}
1895 * @return {boolean} Window is opening
1897 OO
.ui
.Window
.prototype.isOpening = function () {
1898 return this.manager
.isOpening( this );
1902 * Check if the window is closing.
1904 * This method is a wrapper around the window manager's {@link OO.ui.WindowManager#isClosing isClosing} method.
1906 * @return {boolean} Window is closing
1908 OO
.ui
.Window
.prototype.isClosing = function () {
1909 return this.manager
.isClosing( this );
1913 * Check if the window is opened.
1915 * This method is a wrapper around the window manager's {@link OO.ui.WindowManager#isOpened isOpened} method.
1917 * @return {boolean} Window is opened
1919 OO
.ui
.Window
.prototype.isOpened = function () {
1920 return this.manager
.isOpened( this );
1924 * Get the window manager.
1926 * All windows must be attached to a window manager, which is used to open
1927 * and close the window and control its presentation.
1929 * @return {OO.ui.WindowManager} Manager of window
1931 OO
.ui
.Window
.prototype.getManager = function () {
1932 return this.manager
;
1936 * Get the symbolic name of the window size (e.g., `small` or `medium`).
1938 * @return {string} Symbolic name of the size: `small`, `medium`, `large`, `larger`, `full`
1940 OO
.ui
.Window
.prototype.getSize = function () {
1941 var viewport
= OO
.ui
.Element
.static.getDimensions( this.getElementWindow() ),
1942 sizes
= this.manager
.constructor.static.sizes
,
1945 if ( !sizes
[ size
] ) {
1946 size
= this.manager
.constructor.static.defaultSize
;
1948 if ( size
!== 'full' && viewport
.rect
.right
- viewport
.rect
.left
< sizes
[ size
].width
) {
1956 * Get the size properties associated with the current window size
1958 * @return {Object} Size properties
1960 OO
.ui
.Window
.prototype.getSizeProperties = function () {
1961 return this.manager
.constructor.static.sizes
[ this.getSize() ];
1965 * Disable transitions on window's frame for the duration of the callback function, then enable them
1969 * @param {Function} callback Function to call while transitions are disabled
1971 OO
.ui
.Window
.prototype.withoutSizeTransitions = function ( callback
) {
1972 // Temporarily resize the frame so getBodyHeight() can use scrollHeight measurements.
1973 // Disable transitions first, otherwise we'll get values from when the window was animating.
1974 // We need to build the transition CSS properties using these specific properties since
1975 // Firefox doesn't return anything useful when asked just for 'transition'.
1976 var oldTransition
= this.$frame
.css( 'transition-property' ) + ' ' +
1977 this.$frame
.css( 'transition-duration' ) + ' ' +
1978 this.$frame
.css( 'transition-timing-function' ) + ' ' +
1979 this.$frame
.css( 'transition-delay' );
1981 this.$frame
.css( 'transition', 'none' );
1984 // Force reflow to make sure the style changes done inside callback
1985 // really are not transitioned
1986 this.$frame
.height();
1987 this.$frame
.css( 'transition', oldTransition
);
1991 * Get the height of the full window contents (i.e., the window head, body and foot together).
1993 * What consistitutes the head, body, and foot varies depending on the window type.
1994 * A {@link OO.ui.MessageDialog message dialog} displays a title and message in its body,
1995 * and any actions in the foot. A {@link OO.ui.ProcessDialog process dialog} displays a title
1996 * and special actions in the head, and dialog content in the body.
1998 * To get just the height of the dialog body, use the #getBodyHeight method.
2000 * @return {number} The height of the window contents (the dialog head, body and foot) in pixels
2002 OO
.ui
.Window
.prototype.getContentHeight = function () {
2005 bodyStyleObj
= this.$body
[ 0 ].style
,
2006 frameStyleObj
= this.$frame
[ 0 ].style
;
2008 // Temporarily resize the frame so getBodyHeight() can use scrollHeight measurements.
2009 // Disable transitions first, otherwise we'll get values from when the window was animating.
2010 this.withoutSizeTransitions( function () {
2011 var oldHeight
= frameStyleObj
.height
,
2012 oldPosition
= bodyStyleObj
.position
;
2013 frameStyleObj
.height
= '1px';
2014 // Force body to resize to new width
2015 bodyStyleObj
.position
= 'relative';
2016 bodyHeight
= win
.getBodyHeight();
2017 frameStyleObj
.height
= oldHeight
;
2018 bodyStyleObj
.position
= oldPosition
;
2022 // Add buffer for border
2023 ( this.$frame
.outerHeight() - this.$frame
.innerHeight() ) +
2024 // Use combined heights of children
2025 ( this.$head
.outerHeight( true ) + bodyHeight
+ this.$foot
.outerHeight( true ) )
2030 * Get the height of the window body.
2032 * To get the height of the full window contents (the window body, head, and foot together),
2033 * use #getContentHeight.
2035 * When this function is called, the window will temporarily have been resized
2036 * to height=1px, so .scrollHeight measurements can be taken accurately.
2038 * @return {number} Height of the window body in pixels
2040 OO
.ui
.Window
.prototype.getBodyHeight = function () {
2041 return this.$body
[ 0 ].scrollHeight
;
2045 * Get the directionality of the frame (right-to-left or left-to-right).
2047 * @return {string} Directionality: `'ltr'` or `'rtl'`
2049 OO
.ui
.Window
.prototype.getDir = function () {
2050 return OO
.ui
.Element
.static.getDir( this.$content
) || 'ltr';
2054 * Get the 'setup' process.
2056 * The setup process is used to set up a window for use in a particular context,
2057 * based on the `data` argument. This method is called during the opening phase of the window’s
2060 * Override this method to add additional steps to the ‘setup’ process the parent method provides
2061 * using the {@link OO.ui.Process#first first} and {@link OO.ui.Process#next next} methods
2064 * To add window content that persists between openings, you may wish to use the #initialize method
2067 * @param {Object} [data] Window opening data
2068 * @return {OO.ui.Process} Setup process
2070 OO
.ui
.Window
.prototype.getSetupProcess = function () {
2071 return new OO
.ui
.Process();
2075 * Get the ‘ready’ process.
2077 * The ready process is used to ready a window for use in a particular
2078 * context, based on the `data` argument. This method is called during the opening phase of
2079 * the window’s lifecycle, after the window has been {@link #getSetupProcess setup}.
2081 * Override this method to add additional steps to the ‘ready’ process the parent method
2082 * provides using the {@link OO.ui.Process#first first} and {@link OO.ui.Process#next next}
2083 * methods of OO.ui.Process.
2085 * @param {Object} [data] Window opening data
2086 * @return {OO.ui.Process} Ready process
2088 OO
.ui
.Window
.prototype.getReadyProcess = function () {
2089 return new OO
.ui
.Process();
2093 * Get the 'hold' process.
2095 * The hold process is used to keep a window from being used in a particular context,
2096 * based on the `data` argument. This method is called during the closing phase of the window’s
2099 * Override this method to add additional steps to the 'hold' process the parent method provides
2100 * using the {@link OO.ui.Process#first first} and {@link OO.ui.Process#next next} methods
2103 * @param {Object} [data] Window closing data
2104 * @return {OO.ui.Process} Hold process
2106 OO
.ui
.Window
.prototype.getHoldProcess = function () {
2107 return new OO
.ui
.Process();
2111 * Get the ‘teardown’ process.
2113 * The teardown process is used to teardown a window after use. During teardown,
2114 * user interactions within the window are conveyed and the window is closed, based on the `data`
2115 * argument. This method is called during the closing phase of the window’s lifecycle.
2117 * Override this method to add additional steps to the ‘teardown’ process the parent method provides
2118 * using the {@link OO.ui.Process#first first} and {@link OO.ui.Process#next next} methods
2121 * @param {Object} [data] Window closing data
2122 * @return {OO.ui.Process} Teardown process
2124 OO
.ui
.Window
.prototype.getTeardownProcess = function () {
2125 return new OO
.ui
.Process();
2129 * Set the window manager.
2131 * This will cause the window to initialize. Calling it more than once will cause an error.
2133 * @param {OO.ui.WindowManager} manager Manager for this window
2134 * @throws {Error} An error is thrown if the method is called more than once
2137 OO
.ui
.Window
.prototype.setManager = function ( manager
) {
2138 if ( this.manager
) {
2139 throw new Error( 'Cannot set window manager, window already has a manager' );
2142 this.manager
= manager
;
2149 * Set the window size by symbolic name (e.g., 'small' or 'medium')
2151 * @param {string} size Symbolic name of size: `small`, `medium`, `large`, `larger` or
2155 OO
.ui
.Window
.prototype.setSize = function ( size
) {
2162 * Update the window size.
2164 * @throws {Error} An error is thrown if the window is not attached to a window manager
2167 OO
.ui
.Window
.prototype.updateSize = function () {
2168 if ( !this.manager
) {
2169 throw new Error( 'Cannot update window size, must be attached to a manager' );
2172 this.manager
.updateWindowSize( this );
2178 * Set window dimensions. This method is called by the {@link OO.ui.WindowManager window manager}
2179 * when the window is opening. In general, setDimensions should not be called directly.
2181 * To set the size of the window, use the #setSize method.
2183 * @param {Object} dim CSS dimension properties
2184 * @param {string|number} [dim.width] Width
2185 * @param {string|number} [dim.minWidth] Minimum width
2186 * @param {string|number} [dim.maxWidth] Maximum width
2187 * @param {string|number} [dim.height] Height, omit to set based on height of contents
2188 * @param {string|number} [dim.minHeight] Minimum height
2189 * @param {string|number} [dim.maxHeight] Maximum height
2192 OO
.ui
.Window
.prototype.setDimensions = function ( dim
) {
2195 styleObj
= this.$frame
[ 0 ].style
;
2197 // Calculate the height we need to set using the correct width
2198 if ( dim
.height
=== undefined ) {
2199 this.withoutSizeTransitions( function () {
2200 var oldWidth
= styleObj
.width
;
2201 win
.$frame
.css( 'width', dim
.width
|| '' );
2202 height
= win
.getContentHeight();
2203 styleObj
.width
= oldWidth
;
2206 height
= dim
.height
;
2210 width
: dim
.width
|| '',
2211 minWidth
: dim
.minWidth
|| '',
2212 maxWidth
: dim
.maxWidth
|| '',
2213 height
: height
|| '',
2214 minHeight
: dim
.minHeight
|| '',
2215 maxHeight
: dim
.maxHeight
|| ''
2222 * Initialize window contents.
2224 * Before the window is opened for the first time, #initialize is called so that content that
2225 * persists between openings can be added to the window.
2227 * To set up a window with new content each time the window opens, use #getSetupProcess.
2229 * @throws {Error} An error is thrown if the window is not attached to a window manager
2232 OO
.ui
.Window
.prototype.initialize = function () {
2233 if ( !this.manager
) {
2234 throw new Error( 'Cannot initialize window, must be attached to a manager' );
2238 this.$head
= $( '<div>' );
2239 this.$body
= $( '<div>' );
2240 this.$foot
= $( '<div>' );
2241 this.$document
= $( this.getElementDocument() );
2244 this.$element
.on( 'mousedown', this.onMouseDown
.bind( this ) );
2247 this.$head
.addClass( 'oo-ui-window-head' );
2248 this.$body
.addClass( 'oo-ui-window-body' );
2249 this.$foot
.addClass( 'oo-ui-window-foot' );
2250 this.$content
.append( this.$head
, this.$body
, this.$foot
);
2256 * Called when someone tries to focus the hidden element at the end of the dialog.
2257 * Sends focus back to the start of the dialog.
2259 * @param {jQuery.Event} event Focus event
2261 OO
.ui
.Window
.prototype.onFocusTrapFocused = function ( event
) {
2262 var backwards
= this.$focusTrapBefore
.is( event
.target
),
2263 element
= OO
.ui
.findFocusable( this.$content
, backwards
);
2265 // There's a focusable element inside the content, at the front or
2266 // back depending on which focus trap we hit; select it.
2269 // There's nothing focusable inside the content. As a fallback,
2270 // this.$content is focusable, and focusing it will keep our focus
2271 // properly trapped. It's not a *meaningful* focus, since it's just
2272 // the content-div for the Window, but it's better than letting focus
2273 // escape into the page.
2274 this.$content
.focus();
2281 * This method is a wrapper around a call to the window manager’s {@link OO.ui.WindowManager#openWindow openWindow}
2282 * method, which returns a promise resolved when the window is done opening.
2284 * To customize the window each time it opens, use #getSetupProcess or #getReadyProcess.
2286 * @param {Object} [data] Window opening data
2287 * @return {jQuery.Promise} Promise resolved with a value when the window is opened, or rejected
2288 * if the window fails to open. When the promise is resolved successfully, the first argument of the
2289 * value is a new promise, which is resolved when the window begins closing.
2290 * @throws {Error} An error is thrown if the window is not attached to a window manager
2292 OO
.ui
.Window
.prototype.open = function ( data
) {
2293 if ( !this.manager
) {
2294 throw new Error( 'Cannot open window, must be attached to a manager' );
2297 return this.manager
.openWindow( this, data
);
2303 * This method is a wrapper around a call to the window
2304 * manager’s {@link OO.ui.WindowManager#closeWindow closeWindow} method,
2305 * which returns a closing promise resolved when the window is done closing.
2307 * The window's #getHoldProcess and #getTeardownProcess methods are called during the closing
2308 * phase of the window’s lifecycle and can be used to specify closing behavior each time
2309 * the window closes.
2311 * @param {Object} [data] Window closing data
2312 * @return {jQuery.Promise} Promise resolved when window is closed
2313 * @throws {Error} An error is thrown if the window is not attached to a window manager
2315 OO
.ui
.Window
.prototype.close = function ( data
) {
2316 if ( !this.manager
) {
2317 throw new Error( 'Cannot close window, must be attached to a manager' );
2320 return this.manager
.closeWindow( this, data
);
2326 * This is called by OO.ui.WindowManager during window opening, and should not be called directly
2329 * @param {Object} [data] Window opening data
2330 * @return {jQuery.Promise} Promise resolved when window is setup
2332 OO
.ui
.Window
.prototype.setup = function ( data
) {
2335 this.toggle( true );
2337 this.focusTrapHandler
= OO
.ui
.bind( this.onFocusTrapFocused
, this );
2338 this.$focusTraps
.on( 'focus', this.focusTrapHandler
);
2340 return this.getSetupProcess( data
).execute().then( function () {
2341 // Force redraw by asking the browser to measure the elements' widths
2342 win
.$element
.addClass( 'oo-ui-window-active oo-ui-window-setup' ).width();
2343 win
.$content
.addClass( 'oo-ui-window-content-setup' ).width();
2350 * This is called by OO.ui.WindowManager during window opening, and should not be called directly
2353 * @param {Object} [data] Window opening data
2354 * @return {jQuery.Promise} Promise resolved when window is ready
2356 OO
.ui
.Window
.prototype.ready = function ( data
) {
2359 this.$content
.focus();
2360 return this.getReadyProcess( data
).execute().then( function () {
2361 // Force redraw by asking the browser to measure the elements' widths
2362 win
.$element
.addClass( 'oo-ui-window-ready' ).width();
2363 win
.$content
.addClass( 'oo-ui-window-content-ready' ).width();
2370 * This is called by OO.ui.WindowManager during window closing, and should not be called directly
2373 * @param {Object} [data] Window closing data
2374 * @return {jQuery.Promise} Promise resolved when window is held
2376 OO
.ui
.Window
.prototype.hold = function ( data
) {
2379 return this.getHoldProcess( data
).execute().then( function () {
2380 // Get the focused element within the window's content
2381 var $focus
= win
.$content
.find( OO
.ui
.Element
.static.getDocument( win
.$content
).activeElement
);
2383 // Blur the focused element
2384 if ( $focus
.length
) {
2388 // Force redraw by asking the browser to measure the elements' widths
2389 win
.$element
.removeClass( 'oo-ui-window-ready' ).width();
2390 win
.$content
.removeClass( 'oo-ui-window-content-ready' ).width();
2397 * This is called by OO.ui.WindowManager during window closing, and should not be called directly
2400 * @param {Object} [data] Window closing data
2401 * @return {jQuery.Promise} Promise resolved when window is torn down
2403 OO
.ui
.Window
.prototype.teardown = function ( data
) {
2406 return this.getTeardownProcess( data
).execute().then( function () {
2407 // Force redraw by asking the browser to measure the elements' widths
2408 win
.$element
.removeClass( 'oo-ui-window-active oo-ui-window-setup' ).width();
2409 win
.$content
.removeClass( 'oo-ui-window-content-setup' ).width();
2410 win
.$focusTraps
.off( 'focus', win
.focusTrapHandler
);
2411 win
.toggle( false );
2416 * The Dialog class serves as the base class for the other types of dialogs.
2417 * Unless extended to include controls, the rendered dialog box is a simple window
2418 * that users can close by hitting the ‘Esc’ key. Dialog windows are used with OO.ui.WindowManager,
2419 * which opens, closes, and controls the presentation of the window. See the
2420 * [OOjs UI documentation on MediaWiki] [1] for more information.
2423 * // A simple dialog window.
2424 * function MyDialog( config ) {
2425 * MyDialog.parent.call( this, config );
2427 * OO.inheritClass( MyDialog, OO.ui.Dialog );
2428 * MyDialog.static.name = 'myDialog';
2429 * MyDialog.prototype.initialize = function () {
2430 * MyDialog.parent.prototype.initialize.call( this );
2431 * this.content = new OO.ui.PanelLayout( { padded: true, expanded: false } );
2432 * this.content.$element.append( '<p>A simple dialog window. Press \'Esc\' to close.</p>' );
2433 * this.$body.append( this.content.$element );
2435 * MyDialog.prototype.getBodyHeight = function () {
2436 * return this.content.$element.outerHeight( true );
2438 * var myDialog = new MyDialog( {
2441 * // Create and append a window manager, which opens and closes the window.
2442 * var windowManager = new OO.ui.WindowManager();
2443 * $( 'body' ).append( windowManager.$element );
2444 * windowManager.addWindows( [ myDialog ] );
2445 * // Open the window!
2446 * windowManager.openWindow( myDialog );
2448 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Dialogs
2452 * @extends OO.ui.Window
2453 * @mixins OO.ui.mixin.PendingElement
2456 * @param {Object} [config] Configuration options
2458 OO
.ui
.Dialog
= function OoUiDialog( config
) {
2459 // Parent constructor
2460 OO
.ui
.Dialog
.parent
.call( this, config
);
2462 // Mixin constructors
2463 OO
.ui
.mixin
.PendingElement
.call( this );
2466 this.actions
= new OO
.ui
.ActionSet();
2467 this.attachedActions
= [];
2468 this.currentAction
= null;
2469 this.onDialogKeyDownHandler
= this.onDialogKeyDown
.bind( this );
2472 this.actions
.connect( this, {
2473 click
: 'onActionClick',
2474 change
: 'onActionsChange'
2479 .addClass( 'oo-ui-dialog' )
2480 .attr( 'role', 'dialog' );
2485 OO
.inheritClass( OO
.ui
.Dialog
, OO
.ui
.Window
);
2486 OO
.mixinClass( OO
.ui
.Dialog
, OO
.ui
.mixin
.PendingElement
);
2488 /* Static Properties */
2491 * Symbolic name of dialog.
2493 * The dialog class must have a symbolic name in order to be registered with OO.Factory.
2494 * Please see the [OOjs UI documentation on MediaWiki] [3] for more information.
2496 * [3]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Window_managers
2501 * @property {string}
2503 OO
.ui
.Dialog
.static.name
= '';
2508 * The title can be specified as a plaintext string, a {@link OO.ui.mixin.LabelElement Label} node, or a function
2509 * that will produce a Label node or string. The title can also be specified with data passed to the
2510 * constructor (see #getSetupProcess). In this case, the static value will be overridden.
2515 * @property {jQuery|string|Function}
2517 OO
.ui
.Dialog
.static.title
= '';
2520 * An array of configured {@link OO.ui.ActionWidget action widgets}.
2522 * Actions can also be specified with data passed to the constructor (see #getSetupProcess). In this case, the static
2523 * value will be overridden.
2525 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs#Action_sets
2529 * @property {Object[]}
2531 OO
.ui
.Dialog
.static.actions
= [];
2534 * Close the dialog when the 'Esc' key is pressed.
2539 * @property {boolean}
2541 OO
.ui
.Dialog
.static.escapable
= true;
2546 * Handle frame document key down events.
2549 * @param {jQuery.Event} e Key down event
2551 OO
.ui
.Dialog
.prototype.onDialogKeyDown = function ( e
) {
2553 if ( e
.which
=== OO
.ui
.Keys
.ESCAPE
&& this.constructor.static.escapable
) {
2554 this.executeAction( '' );
2556 e
.stopPropagation();
2557 } else if ( e
.which
=== OO
.ui
.Keys
.ENTER
&& ( e
.ctrlKey
|| e
.metaKey
) ) {
2558 actions
= this.actions
.get( { flags
: 'primary', visible
: true, disabled
: false } );
2559 if ( actions
.length
> 0 ) {
2560 this.executeAction( actions
[ 0 ].getAction() );
2562 e
.stopPropagation();
2568 * Handle action click events.
2571 * @param {OO.ui.ActionWidget} action Action that was clicked
2573 OO
.ui
.Dialog
.prototype.onActionClick = function ( action
) {
2574 if ( !this.isPending() ) {
2575 this.executeAction( action
.getAction() );
2580 * Handle actions change event.
2584 OO
.ui
.Dialog
.prototype.onActionsChange = function () {
2585 this.detachActions();
2586 if ( !this.isClosing() ) {
2587 this.attachActions();
2592 * Get the set of actions used by the dialog.
2594 * @return {OO.ui.ActionSet}
2596 OO
.ui
.Dialog
.prototype.getActions = function () {
2597 return this.actions
;
2601 * Get a process for taking action.
2603 * When you override this method, you can create a new OO.ui.Process and return it, or add additional
2604 * accept steps to the process the parent method provides using the {@link OO.ui.Process#first 'first'}
2605 * and {@link OO.ui.Process#next 'next'} methods of OO.ui.Process.
2607 * @param {string} [action] Symbolic name of action
2608 * @return {OO.ui.Process} Action process
2610 OO
.ui
.Dialog
.prototype.getActionProcess = function ( action
) {
2611 return new OO
.ui
.Process()
2612 .next( function () {
2614 // An empty action always closes the dialog without data, which should always be
2615 // safe and make no changes
2624 * @param {Object} [data] Dialog opening data
2625 * @param {jQuery|string|Function|null} [data.title] Dialog title, omit to use
2626 * the {@link #static-title static title}
2627 * @param {Object[]} [data.actions] List of configuration options for each
2628 * {@link OO.ui.ActionWidget action widget}, omit to use {@link #static-actions static actions}.
2630 OO
.ui
.Dialog
.prototype.getSetupProcess = function ( data
) {
2634 return OO
.ui
.Dialog
.parent
.prototype.getSetupProcess
.call( this, data
)
2635 .next( function () {
2636 var config
= this.constructor.static,
2637 actions
= data
.actions
!== undefined ? data
.actions
: config
.actions
,
2638 title
= data
.title
!== undefined ? data
.title
: config
.title
;
2640 this.title
.setLabel( title
).setTitle( title
);
2641 this.actions
.add( this.getActionWidgets( actions
) );
2643 this.$element
.on( 'keydown', this.onDialogKeyDownHandler
);
2650 OO
.ui
.Dialog
.prototype.getTeardownProcess = function ( data
) {
2652 return OO
.ui
.Dialog
.parent
.prototype.getTeardownProcess
.call( this, data
)
2653 .first( function () {
2654 this.$element
.off( 'keydown', this.onDialogKeyDownHandler
);
2656 this.actions
.clear();
2657 this.currentAction
= null;
2664 OO
.ui
.Dialog
.prototype.initialize = function () {
2666 OO
.ui
.Dialog
.parent
.prototype.initialize
.call( this );
2669 this.title
= new OO
.ui
.LabelWidget();
2672 this.$content
.addClass( 'oo-ui-dialog-content' );
2673 this.$element
.attr( 'aria-labelledby', this.title
.getElementId() );
2674 this.setPendingElement( this.$head
);
2678 * Get action widgets from a list of configs
2680 * @param {Object[]} actions Action widget configs
2681 * @return {OO.ui.ActionWidget[]} Action widgets
2683 OO
.ui
.Dialog
.prototype.getActionWidgets = function ( actions
) {
2684 var i
, len
, widgets
= [];
2685 for ( i
= 0, len
= actions
.length
; i
< len
; i
++ ) {
2687 new OO
.ui
.ActionWidget( actions
[ i
] )
2694 * Attach action actions.
2698 OO
.ui
.Dialog
.prototype.attachActions = function () {
2699 // Remember the list of potentially attached actions
2700 this.attachedActions
= this.actions
.get();
2704 * Detach action actions.
2709 OO
.ui
.Dialog
.prototype.detachActions = function () {
2712 // Detach all actions that may have been previously attached
2713 for ( i
= 0, len
= this.attachedActions
.length
; i
< len
; i
++ ) {
2714 this.attachedActions
[ i
].$element
.detach();
2716 this.attachedActions
= [];
2720 * Execute an action.
2722 * @param {string} action Symbolic name of action to execute
2723 * @return {jQuery.Promise} Promise resolved when action completes, rejected if it fails
2725 OO
.ui
.Dialog
.prototype.executeAction = function ( action
) {
2727 this.currentAction
= action
;
2728 return this.getActionProcess( action
).execute()
2729 .always( this.popPending
.bind( this ) );
2733 * MessageDialogs display a confirmation or alert message. By default, the rendered dialog box
2734 * consists of a header that contains the dialog title, a body with the message, and a footer that
2735 * contains any {@link OO.ui.ActionWidget action widgets}. The MessageDialog class is the only type
2736 * of {@link OO.ui.Dialog dialog} that is usually instantiated directly.
2738 * There are two basic types of message dialogs, confirmation and alert:
2740 * - **confirmation**: the dialog title describes what a progressive action will do and the message provides
2741 * more details about the consequences.
2742 * - **alert**: the dialog title describes which event occurred and the message provides more information
2743 * about why the event occurred.
2745 * The MessageDialog class specifies two actions: ‘accept’, the primary
2746 * action (e.g., ‘ok’) and ‘reject,’ the safe action (e.g., ‘cancel’). Both will close the window,
2747 * passing along the selected action.
2749 * For more information and examples, please see the [OOjs UI documentation on MediaWiki][1].
2752 * // Example: Creating and opening a message dialog window.
2753 * var messageDialog = new OO.ui.MessageDialog();
2755 * // Create and append a window manager.
2756 * var windowManager = new OO.ui.WindowManager();
2757 * $( 'body' ).append( windowManager.$element );
2758 * windowManager.addWindows( [ messageDialog ] );
2759 * // Open the window.
2760 * windowManager.openWindow( messageDialog, {
2761 * title: 'Basic message dialog',
2762 * message: 'This is the message'
2765 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Message_Dialogs
2768 * @extends OO.ui.Dialog
2771 * @param {Object} [config] Configuration options
2773 OO
.ui
.MessageDialog
= function OoUiMessageDialog( config
) {
2774 // Parent constructor
2775 OO
.ui
.MessageDialog
.parent
.call( this, config
);
2778 this.verticalActionLayout
= null;
2781 this.$element
.addClass( 'oo-ui-messageDialog' );
2786 OO
.inheritClass( OO
.ui
.MessageDialog
, OO
.ui
.Dialog
);
2788 /* Static Properties */
2794 OO
.ui
.MessageDialog
.static.name
= 'message';
2800 OO
.ui
.MessageDialog
.static.size
= 'small';
2805 * The title of a confirmation dialog describes what a progressive action will do. The
2806 * title of an alert dialog describes which event occurred.
2810 * @property {jQuery|string|Function|null}
2812 OO
.ui
.MessageDialog
.static.title
= null;
2815 * The message displayed in the dialog body.
2817 * A confirmation message describes the consequences of a progressive action. An alert
2818 * message describes why an event occurred.
2822 * @property {jQuery|string|Function|null}
2824 OO
.ui
.MessageDialog
.static.message
= null;
2830 OO
.ui
.MessageDialog
.static.actions
= [
2831 // Note that OO.ui.alert() and OO.ui.confirm() rely on these.
2832 { action
: 'accept', label
: OO
.ui
.deferMsg( 'ooui-dialog-message-accept' ), flags
: 'primary' },
2833 { action
: 'reject', label
: OO
.ui
.deferMsg( 'ooui-dialog-message-reject' ), flags
: 'safe' }
2841 OO
.ui
.MessageDialog
.prototype.setManager = function ( manager
) {
2842 OO
.ui
.MessageDialog
.parent
.prototype.setManager
.call( this, manager
);
2845 this.manager
.connect( this, {
2853 * Handle window resized events.
2857 OO
.ui
.MessageDialog
.prototype.onResize = function () {
2859 dialog
.fitActions();
2860 // Wait for CSS transition to finish and do it again :(
2861 setTimeout( function () {
2862 dialog
.fitActions();
2867 * Toggle action layout between vertical and horizontal.
2870 * @param {boolean} [value] Layout actions vertically, omit to toggle
2873 OO
.ui
.MessageDialog
.prototype.toggleVerticalActionLayout = function ( value
) {
2874 value
= value
=== undefined ? !this.verticalActionLayout
: !!value
;
2876 if ( value
!== this.verticalActionLayout
) {
2877 this.verticalActionLayout
= value
;
2879 .toggleClass( 'oo-ui-messageDialog-actions-vertical', value
)
2880 .toggleClass( 'oo-ui-messageDialog-actions-horizontal', !value
);
2889 OO
.ui
.MessageDialog
.prototype.getActionProcess = function ( action
) {
2891 return new OO
.ui
.Process( function () {
2892 this.close( { action
: action
} );
2895 return OO
.ui
.MessageDialog
.parent
.prototype.getActionProcess
.call( this, action
);
2901 * @param {Object} [data] Dialog opening data
2902 * @param {jQuery|string|Function|null} [data.title] Description of the action being confirmed
2903 * @param {jQuery|string|Function|null} [data.message] Description of the action's consequence
2904 * @param {string} [data.size] Symbolic name of the dialog size, see OO.ui.Window
2905 * @param {Object[]} [data.actions] List of OO.ui.ActionOptionWidget configuration options for each
2908 OO
.ui
.MessageDialog
.prototype.getSetupProcess = function ( data
) {
2912 return OO
.ui
.MessageDialog
.parent
.prototype.getSetupProcess
.call( this, data
)
2913 .next( function () {
2914 this.title
.setLabel(
2915 data
.title
!== undefined ? data
.title
: this.constructor.static.title
2917 this.message
.setLabel(
2918 data
.message
!== undefined ? data
.message
: this.constructor.static.message
2920 this.size
= data
.size
!== undefined ? data
.size
: this.constructor.static.size
;
2927 OO
.ui
.MessageDialog
.prototype.getReadyProcess = function ( data
) {
2931 return OO
.ui
.MessageDialog
.parent
.prototype.getReadyProcess
.call( this, data
)
2932 .next( function () {
2933 // Focus the primary action button
2934 var actions
= this.actions
.get();
2935 actions
= actions
.filter( function ( action
) {
2936 return action
.getFlags().indexOf( 'primary' ) > -1;
2938 if ( actions
.length
> 0 ) {
2939 actions
[ 0 ].focus();
2947 OO
.ui
.MessageDialog
.prototype.getBodyHeight = function () {
2948 var bodyHeight
, oldOverflow
,
2949 $scrollable
= this.container
.$element
;
2951 oldOverflow
= $scrollable
[ 0 ].style
.overflow
;
2952 $scrollable
[ 0 ].style
.overflow
= 'hidden';
2954 OO
.ui
.Element
.static.reconsiderScrollbars( $scrollable
[ 0 ] );
2956 bodyHeight
= this.text
.$element
.outerHeight( true );
2957 $scrollable
[ 0 ].style
.overflow
= oldOverflow
;
2965 OO
.ui
.MessageDialog
.prototype.setDimensions = function ( dim
) {
2966 var $scrollable
= this.container
.$element
;
2967 OO
.ui
.MessageDialog
.parent
.prototype.setDimensions
.call( this, dim
);
2969 // Twiddle the overflow property, otherwise an unnecessary scrollbar will be produced.
2970 // Need to do it after transition completes (250ms), add 50ms just in case.
2971 setTimeout( function () {
2972 var oldOverflow
= $scrollable
[ 0 ].style
.overflow
,
2973 activeElement
= document
.activeElement
;
2975 $scrollable
[ 0 ].style
.overflow
= 'hidden';
2977 OO
.ui
.Element
.static.reconsiderScrollbars( $scrollable
[ 0 ] );
2979 // Check reconsiderScrollbars didn't destroy our focus, as we
2980 // are doing this after the ready process.
2981 if ( activeElement
&& activeElement
!== document
.activeElement
&& activeElement
.focus
) {
2982 activeElement
.focus();
2985 $scrollable
[ 0 ].style
.overflow
= oldOverflow
;
2994 OO
.ui
.MessageDialog
.prototype.initialize = function () {
2996 OO
.ui
.MessageDialog
.parent
.prototype.initialize
.call( this );
2999 this.$actions
= $( '<div>' );
3000 this.container
= new OO
.ui
.PanelLayout( {
3001 scrollable
: true, classes
: [ 'oo-ui-messageDialog-container' ]
3003 this.text
= new OO
.ui
.PanelLayout( {
3004 padded
: true, expanded
: false, classes
: [ 'oo-ui-messageDialog-text' ]
3006 this.message
= new OO
.ui
.LabelWidget( {
3007 classes
: [ 'oo-ui-messageDialog-message' ]
3011 this.title
.$element
.addClass( 'oo-ui-messageDialog-title' );
3012 this.$content
.addClass( 'oo-ui-messageDialog-content' );
3013 this.container
.$element
.append( this.text
.$element
);
3014 this.text
.$element
.append( this.title
.$element
, this.message
.$element
);
3015 this.$body
.append( this.container
.$element
);
3016 this.$actions
.addClass( 'oo-ui-messageDialog-actions' );
3017 this.$foot
.append( this.$actions
);
3023 OO
.ui
.MessageDialog
.prototype.attachActions = function () {
3024 var i
, len
, other
, special
, others
;
3027 OO
.ui
.MessageDialog
.parent
.prototype.attachActions
.call( this );
3029 special
= this.actions
.getSpecial();
3030 others
= this.actions
.getOthers();
3032 if ( special
.safe
) {
3033 this.$actions
.append( special
.safe
.$element
);
3034 special
.safe
.toggleFramed( false );
3036 if ( others
.length
) {
3037 for ( i
= 0, len
= others
.length
; i
< len
; i
++ ) {
3038 other
= others
[ i
];
3039 this.$actions
.append( other
.$element
);
3040 other
.toggleFramed( false );
3043 if ( special
.primary
) {
3044 this.$actions
.append( special
.primary
.$element
);
3045 special
.primary
.toggleFramed( false );
3048 if ( !this.isOpening() ) {
3049 // If the dialog is currently opening, this will be called automatically soon.
3050 // This also calls #fitActions.
3056 * Fit action actions into columns or rows.
3058 * Columns will be used if all labels can fit without overflow, otherwise rows will be used.
3062 OO
.ui
.MessageDialog
.prototype.fitActions = function () {
3064 previous
= this.verticalActionLayout
,
3065 actions
= this.actions
.get();
3068 this.toggleVerticalActionLayout( false );
3069 for ( i
= 0, len
= actions
.length
; i
< len
; i
++ ) {
3070 action
= actions
[ i
];
3071 if ( action
.$element
.innerWidth() < action
.$label
.outerWidth( true ) ) {
3072 this.toggleVerticalActionLayout( true );
3077 // Move the body out of the way of the foot
3078 this.$body
.css( 'bottom', this.$foot
.outerHeight( true ) );
3080 if ( this.verticalActionLayout
!== previous
) {
3081 // We changed the layout, window height might need to be updated.
3087 * ProcessDialog windows encapsulate a {@link OO.ui.Process process} and all of the code necessary
3088 * to complete it. If the process terminates with an error, a customizable {@link OO.ui.Error error
3089 * interface} alerts users to the trouble, permitting the user to dismiss the error and try again when
3090 * relevant. The ProcessDialog class is always extended and customized with the actions and content
3091 * required for each process.
3093 * The process dialog box consists of a header that visually represents the ‘working’ state of long
3094 * processes with an animation. The header contains the dialog title as well as
3095 * two {@link OO.ui.ActionWidget action widgets}: a ‘safe’ action on the left (e.g., ‘Cancel’) and
3096 * a ‘primary’ action on the right (e.g., ‘Done’).
3098 * Like other windows, the process dialog is managed by a {@link OO.ui.WindowManager window manager}.
3099 * Please see the [OOjs UI documentation on MediaWiki][1] for more information and examples.
3102 * // Example: Creating and opening a process dialog window.
3103 * function MyProcessDialog( config ) {
3104 * MyProcessDialog.parent.call( this, config );
3106 * OO.inheritClass( MyProcessDialog, OO.ui.ProcessDialog );
3108 * MyProcessDialog.static.name = 'myProcessDialog';
3109 * MyProcessDialog.static.title = 'Process dialog';
3110 * MyProcessDialog.static.actions = [
3111 * { action: 'save', label: 'Done', flags: 'primary' },
3112 * { label: 'Cancel', flags: 'safe' }
3115 * MyProcessDialog.prototype.initialize = function () {
3116 * MyProcessDialog.parent.prototype.initialize.apply( this, arguments );
3117 * this.content = new OO.ui.PanelLayout( { padded: true, expanded: false } );
3118 * this.content.$element.append( '<p>This is a process dialog window. The header contains the title and two buttons: \'Cancel\' (a safe action) on the left and \'Done\' (a primary action) on the right.</p>' );
3119 * this.$body.append( this.content.$element );
3121 * MyProcessDialog.prototype.getActionProcess = function ( action ) {
3122 * var dialog = this;
3124 * return new OO.ui.Process( function () {
3125 * dialog.close( { action: action } );
3128 * return MyProcessDialog.parent.prototype.getActionProcess.call( this, action );
3131 * var windowManager = new OO.ui.WindowManager();
3132 * $( 'body' ).append( windowManager.$element );
3134 * var dialog = new MyProcessDialog();
3135 * windowManager.addWindows( [ dialog ] );
3136 * windowManager.openWindow( dialog );
3138 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs
3142 * @extends OO.ui.Dialog
3145 * @param {Object} [config] Configuration options
3147 OO
.ui
.ProcessDialog
= function OoUiProcessDialog( config
) {
3148 // Parent constructor
3149 OO
.ui
.ProcessDialog
.parent
.call( this, config
);
3152 this.fitOnOpen
= false;
3155 this.$element
.addClass( 'oo-ui-processDialog' );
3160 OO
.inheritClass( OO
.ui
.ProcessDialog
, OO
.ui
.Dialog
);
3165 * Handle dismiss button click events.
3171 OO
.ui
.ProcessDialog
.prototype.onDismissErrorButtonClick = function () {
3176 * Handle retry button click events.
3178 * Hides errors and then tries again.
3182 OO
.ui
.ProcessDialog
.prototype.onRetryButtonClick = function () {
3184 this.executeAction( this.currentAction
);
3190 OO
.ui
.ProcessDialog
.prototype.initialize = function () {
3192 OO
.ui
.ProcessDialog
.parent
.prototype.initialize
.call( this );
3195 this.$navigation
= $( '<div>' );
3196 this.$location
= $( '<div>' );
3197 this.$safeActions
= $( '<div>' );
3198 this.$primaryActions
= $( '<div>' );
3199 this.$otherActions
= $( '<div>' );
3200 this.dismissButton
= new OO
.ui
.ButtonWidget( {
3201 label
: OO
.ui
.msg( 'ooui-dialog-process-dismiss' )
3203 this.retryButton
= new OO
.ui
.ButtonWidget();
3204 this.$errors
= $( '<div>' );
3205 this.$errorsTitle
= $( '<div>' );
3208 this.dismissButton
.connect( this, { click
: 'onDismissErrorButtonClick' } );
3209 this.retryButton
.connect( this, { click
: 'onRetryButtonClick' } );
3212 this.title
.$element
.addClass( 'oo-ui-processDialog-title' );
3214 .append( this.title
.$element
)
3215 .addClass( 'oo-ui-processDialog-location' );
3216 this.$safeActions
.addClass( 'oo-ui-processDialog-actions-safe' );
3217 this.$primaryActions
.addClass( 'oo-ui-processDialog-actions-primary' );
3218 this.$otherActions
.addClass( 'oo-ui-processDialog-actions-other' );
3220 .addClass( 'oo-ui-processDialog-errors-title' )
3221 .text( OO
.ui
.msg( 'ooui-dialog-process-error' ) );
3223 .addClass( 'oo-ui-processDialog-errors oo-ui-element-hidden' )
3224 .append( this.$errorsTitle
, this.dismissButton
.$element
, this.retryButton
.$element
);
3226 .addClass( 'oo-ui-processDialog-content' )
3227 .append( this.$errors
);
3229 .addClass( 'oo-ui-processDialog-navigation' )
3230 // Note: Order of appends below is important. These are in the order
3231 // we want tab to go through them. Display-order is handled entirely
3232 // by CSS absolute-positioning. As such, primary actions like "done"
3234 .append( this.$primaryActions
, this.$location
, this.$safeActions
);
3235 this.$head
.append( this.$navigation
);
3236 this.$foot
.append( this.$otherActions
);
3242 OO
.ui
.ProcessDialog
.prototype.getActionWidgets = function ( actions
) {
3244 isMobile
= OO
.ui
.isMobile(),
3247 for ( i
= 0, len
= actions
.length
; i
< len
; i
++ ) {
3248 config
= $.extend( { framed
: !OO
.ui
.isMobile() }, actions
[ i
] );
3250 ( config
.flags
=== 'back' || ( Array
.isArray( config
.flags
) && config
.flags
.indexOf( 'back' ) !== -1 ) )
3258 new OO
.ui
.ActionWidget( config
)
3267 OO
.ui
.ProcessDialog
.prototype.attachActions = function () {
3268 var i
, len
, other
, special
, others
;
3271 OO
.ui
.ProcessDialog
.parent
.prototype.attachActions
.call( this );
3273 special
= this.actions
.getSpecial();
3274 others
= this.actions
.getOthers();
3275 if ( special
.primary
) {
3276 this.$primaryActions
.append( special
.primary
.$element
);
3278 for ( i
= 0, len
= others
.length
; i
< len
; i
++ ) {
3279 other
= others
[ i
];
3280 this.$otherActions
.append( other
.$element
);
3282 if ( special
.safe
) {
3283 this.$safeActions
.append( special
.safe
.$element
);
3287 this.$body
.css( 'bottom', this.$foot
.outerHeight( true ) );
3293 OO
.ui
.ProcessDialog
.prototype.executeAction = function ( action
) {
3295 return OO
.ui
.ProcessDialog
.parent
.prototype.executeAction
.call( this, action
)
3296 .fail( function ( errors
) {
3297 process
.showErrors( errors
|| [] );
3304 OO
.ui
.ProcessDialog
.prototype.setDimensions = function () {
3306 OO
.ui
.ProcessDialog
.parent
.prototype.setDimensions
.apply( this, arguments
);
3312 * Fit label between actions.
3317 OO
.ui
.ProcessDialog
.prototype.fitLabel = function () {
3318 var safeWidth
, primaryWidth
, biggerWidth
, labelWidth
, navigationWidth
, leftWidth
, rightWidth
,
3319 size
= this.getSizeProperties();
3321 if ( typeof size
.width
!== 'number' ) {
3322 if ( this.isOpened() ) {
3323 navigationWidth
= this.$head
.width() - 20;
3324 } else if ( this.isOpening() ) {
3325 if ( !this.fitOnOpen
) {
3326 // Size is relative and the dialog isn't open yet, so wait.
3327 // FIXME: This should ideally be handled by setup somehow.
3328 this.manager
.lifecycle
.opened
.done( this.fitLabel
.bind( this ) );
3329 this.fitOnOpen
= true;
3336 navigationWidth
= size
.width
- 20;
3339 safeWidth
= this.$safeActions
.is( ':visible' ) ? this.$safeActions
.width() : 0;
3340 primaryWidth
= this.$primaryActions
.is( ':visible' ) ? this.$primaryActions
.width() : 0;
3341 biggerWidth
= Math
.max( safeWidth
, primaryWidth
);
3343 labelWidth
= this.title
.$element
.width();
3345 if ( 2 * biggerWidth
+ labelWidth
< navigationWidth
) {
3346 // We have enough space to center the label
3347 leftWidth
= rightWidth
= biggerWidth
;
3349 // Let's hope we at least have enough space not to overlap, because we can't wrap the label…
3350 if ( this.getDir() === 'ltr' ) {
3351 leftWidth
= safeWidth
;
3352 rightWidth
= primaryWidth
;
3354 leftWidth
= primaryWidth
;
3355 rightWidth
= safeWidth
;
3359 this.$location
.css( { paddingLeft
: leftWidth
, paddingRight
: rightWidth
} );
3365 * Handle errors that occurred during accept or reject processes.
3368 * @param {OO.ui.Error[]|OO.ui.Error} errors Errors to be handled
3370 OO
.ui
.ProcessDialog
.prototype.showErrors = function ( errors
) {
3371 var i
, len
, $item
, actions
,
3377 if ( errors
instanceof OO
.ui
.Error
) {
3378 errors
= [ errors
];
3381 for ( i
= 0, len
= errors
.length
; i
< len
; i
++ ) {
3382 if ( !errors
[ i
].isRecoverable() ) {
3383 recoverable
= false;
3385 if ( errors
[ i
].isWarning() ) {
3388 $item
= $( '<div>' )
3389 .addClass( 'oo-ui-processDialog-error' )
3390 .append( errors
[ i
].getMessage() );
3391 items
.push( $item
[ 0 ] );
3393 this.$errorItems
= $( items
);
3394 if ( recoverable
) {
3395 abilities
[ this.currentAction
] = true;
3396 // Copy the flags from the first matching action
3397 actions
= this.actions
.get( { actions
: this.currentAction
} );
3398 if ( actions
.length
) {
3399 this.retryButton
.clearFlags().setFlags( actions
[ 0 ].getFlags() );
3402 abilities
[ this.currentAction
] = false;
3403 this.actions
.setAbilities( abilities
);
3406 this.retryButton
.setLabel( OO
.ui
.msg( 'ooui-dialog-process-continue' ) );
3408 this.retryButton
.setLabel( OO
.ui
.msg( 'ooui-dialog-process-retry' ) );
3410 this.retryButton
.toggle( recoverable
);
3411 this.$errorsTitle
.after( this.$errorItems
);
3412 this.$errors
.removeClass( 'oo-ui-element-hidden' ).scrollTop( 0 );
3420 OO
.ui
.ProcessDialog
.prototype.hideErrors = function () {
3421 this.$errors
.addClass( 'oo-ui-element-hidden' );
3422 if ( this.$errorItems
) {
3423 this.$errorItems
.remove();
3424 this.$errorItems
= null;
3431 OO
.ui
.ProcessDialog
.prototype.getTeardownProcess = function ( data
) {
3433 return OO
.ui
.ProcessDialog
.parent
.prototype.getTeardownProcess
.call( this, data
)
3434 .first( function () {
3435 // Make sure to hide errors
3437 this.fitOnOpen
= false;
3446 * Lazy-initialize and return a global OO.ui.WindowManager instance, used by OO.ui.alert and
3450 * @return {OO.ui.WindowManager}
3452 OO
.ui
.getWindowManager = function () {
3453 if ( !OO
.ui
.windowManager
) {
3454 OO
.ui
.windowManager
= new OO
.ui
.WindowManager();
3455 $( 'body' ).append( OO
.ui
.windowManager
.$element
);
3456 OO
.ui
.windowManager
.addWindows( [ new OO
.ui
.MessageDialog() ] );
3458 return OO
.ui
.windowManager
;
3462 * Display a quick modal alert dialog, using a OO.ui.MessageDialog. While the dialog is open, the
3463 * rest of the page will be dimmed out and the user won't be able to interact with it. The dialog
3464 * has only one action button, labelled "OK", clicking it will simply close the dialog.
3466 * A window manager is created automatically when this function is called for the first time.
3469 * OO.ui.alert( 'Something happened!' ).done( function () {
3470 * console.log( 'User closed the dialog.' );
3473 * OO.ui.alert( 'Something larger happened!', { size: 'large' } );
3475 * @param {jQuery|string} text Message text to display
3476 * @param {Object} [options] Additional options, see OO.ui.MessageDialog#getSetupProcess
3477 * @return {jQuery.Promise} Promise resolved when the user closes the dialog
3479 OO
.ui
.alert = function ( text
, options
) {
3480 return OO
.ui
.getWindowManager().openWindow( 'message', $.extend( {
3482 actions
: [ OO
.ui
.MessageDialog
.static.actions
[ 0 ] ]
3483 }, options
) ).closed
.then( function () {
3489 * Display a quick modal confirmation dialog, using a OO.ui.MessageDialog. While the dialog is open,
3490 * the rest of the page will be dimmed out and the user won't be able to interact with it. The
3491 * dialog has two action buttons, one to confirm an operation (labelled "OK") and one to cancel it
3492 * (labelled "Cancel").
3494 * A window manager is created automatically when this function is called for the first time.
3497 * OO.ui.confirm( 'Are you sure?' ).done( function ( confirmed ) {
3498 * if ( confirmed ) {
3499 * console.log( 'User clicked "OK"!' );
3501 * console.log( 'User clicked "Cancel" or closed the dialog.' );
3505 * @param {jQuery|string} text Message text to display
3506 * @param {Object} [options] Additional options, see OO.ui.MessageDialog#getSetupProcess
3507 * @return {jQuery.Promise} Promise resolved when the user closes the dialog. If the user chose to
3508 * confirm, the promise will resolve to boolean `true`; otherwise, it will resolve to boolean
3511 OO
.ui
.confirm = function ( text
, options
) {
3512 return OO
.ui
.getWindowManager().openWindow( 'message', $.extend( {
3514 }, options
) ).closed
.then( function ( data
) {
3515 return !!( data
&& data
.action
=== 'accept' );
3520 * Display a quick modal prompt dialog, using a OO.ui.MessageDialog. While the dialog is open,
3521 * the rest of the page will be dimmed out and the user won't be able to interact with it. The
3522 * dialog has a text input widget and two action buttons, one to confirm an operation (labelled "OK")
3523 * and one to cancel it (labelled "Cancel").
3525 * A window manager is created automatically when this function is called for the first time.
3528 * OO.ui.prompt( 'Choose a line to go to', { textInput: { placeholder: 'Line number' } } ).done( function ( result ) {
3529 * if ( result !== null ) {
3530 * console.log( 'User typed "' + result + '" then clicked "OK".' );
3532 * console.log( 'User clicked "Cancel" or closed the dialog.' );
3536 * @param {jQuery|string} text Message text to display
3537 * @param {Object} [options] Additional options, see OO.ui.MessageDialog#getSetupProcess
3538 * @param {Object} [options.textInput] Additional options for text input widget, see OO.ui.TextInputWidget
3539 * @return {jQuery.Promise} Promise resolved when the user closes the dialog. If the user chose to
3540 * confirm, the promise will resolve with the value of the text input widget; otherwise, it will
3541 * resolve to `null`.
3543 OO
.ui
.prompt = function ( text
, options
) {
3545 manager
= OO
.ui
.getWindowManager(),
3546 textInput
= new OO
.ui
.TextInputWidget( ( options
&& options
.textInput
) || {} ),
3547 textField
= new OO
.ui
.FieldLayout( textInput
, {
3552 instance
= manager
.openWindow( 'message', $.extend( {
3553 message
: textField
.$element
3556 // TODO: This is a little hacky, and could be done by extending MessageDialog instead.
3557 instance
.opened
.then( function () {
3558 textInput
.on( 'enter', function () {
3559 manager
.getCurrentWindow().close( { action
: 'accept' } );
3564 return instance
.closed
.then( function ( data
) {
3565 return data
&& data
.action
=== 'accept' ? textInput
.getValue() : null;
3571 //# sourceMappingURL=oojs-ui-windows.js.map