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-10-04T01:20:41Z
16 * Namespace for all classes, static methods and static properties.
48 * Constants for MouseEvent.which
52 OO
.ui
.MouseButtons
= {
65 * Generate a unique ID for element
69 OO
.ui
.generateElementId = function () {
71 return 'oojsui-' + OO
.ui
.elementId
;
75 * Check if an element is focusable.
76 * Inspired by :focusable in jQueryUI v1.11.4 - 2015-04-14
78 * @param {jQuery} $element Element to test
79 * @return {boolean} Element is focusable
81 OO
.ui
.isFocusableElement = function ( $element
) {
83 element
= $element
[ 0 ];
85 // Anything disabled is not focusable
86 if ( element
.disabled
) {
90 // Check if the element is visible
92 // This is quicker than calling $element.is( ':visible' )
93 $.expr
.pseudos
.visible( element
) &&
94 // Check that all parents are visible
95 !$element
.parents().addBack().filter( function () {
96 return $.css( this, 'visibility' ) === 'hidden';
102 // Check if the element is ContentEditable, which is the string 'true'
103 if ( element
.contentEditable
=== 'true' ) {
107 // Anything with a non-negative numeric tabIndex is focusable.
108 // Use .prop to avoid browser bugs
109 if ( $element
.prop( 'tabIndex' ) >= 0 ) {
113 // Some element types are naturally focusable
114 // (indexOf is much faster than regex in Chrome and about the
115 // same in FF: https://jsperf.com/regex-vs-indexof-array2)
116 nodeName
= element
.nodeName
.toLowerCase();
117 if ( [ 'input', 'select', 'textarea', 'button', 'object' ].indexOf( nodeName
) !== -1 ) {
121 // Links and areas are focusable if they have an href
122 if ( ( nodeName
=== 'a' || nodeName
=== 'area' ) && $element
.attr( 'href' ) !== undefined ) {
130 * Find a focusable child
132 * @param {jQuery} $container Container to search in
133 * @param {boolean} [backwards] Search backwards
134 * @return {jQuery} Focusable child, or an empty jQuery object if none found
136 OO
.ui
.findFocusable = function ( $container
, backwards
) {
137 var $focusable
= $( [] ),
138 // $focusableCandidates is a superset of things that
139 // could get matched by isFocusableElement
140 $focusableCandidates
= $container
141 .find( 'input, select, textarea, button, object, a, area, [contenteditable], [tabindex]' );
144 $focusableCandidates
= Array
.prototype.reverse
.call( $focusableCandidates
);
147 $focusableCandidates
.each( function () {
148 var $this = $( this );
149 if ( OO
.ui
.isFocusableElement( $this ) ) {
158 * Get the user's language and any fallback languages.
160 * These language codes are used to localize user interface elements in the user's language.
162 * In environments that provide a localization system, this function should be overridden to
163 * return the user's language(s). The default implementation returns English (en) only.
165 * @return {string[]} Language codes, in descending order of priority
167 OO
.ui
.getUserLanguages = function () {
172 * Get a value in an object keyed by language code.
174 * @param {Object.<string,Mixed>} obj Object keyed by language code
175 * @param {string|null} [lang] Language code, if omitted or null defaults to any user language
176 * @param {string} [fallback] Fallback code, used if no matching language can be found
177 * @return {Mixed} Local value
179 OO
.ui
.getLocalValue = function ( obj
, lang
, fallback
) {
182 // Requested language
186 // Known user language
187 langs
= OO
.ui
.getUserLanguages();
188 for ( i
= 0, len
= langs
.length
; i
< len
; i
++ ) {
195 if ( obj
[ fallback
] ) {
196 return obj
[ fallback
];
198 // First existing language
199 for ( lang
in obj
) {
207 * Check if a node is contained within another node
209 * Similar to jQuery#contains except a list of containers can be supplied
210 * and a boolean argument allows you to include the container in the match list
212 * @param {HTMLElement|HTMLElement[]} containers Container node(s) to search in
213 * @param {HTMLElement} contained Node to find
214 * @param {boolean} [matchContainers] Include the container(s) in the list of nodes to match, otherwise only match descendants
215 * @return {boolean} The node is in the list of target nodes
217 OO
.ui
.contains = function ( containers
, contained
, matchContainers
) {
219 if ( !Array
.isArray( containers
) ) {
220 containers
= [ containers
];
222 for ( i
= containers
.length
- 1; i
>= 0; i
-- ) {
223 if ( ( matchContainers
&& contained
=== containers
[ i
] ) || $.contains( containers
[ i
], contained
) ) {
231 * Return a function, that, as long as it continues to be invoked, will not
232 * be triggered. The function will be called after it stops being called for
233 * N milliseconds. If `immediate` is passed, trigger the function on the
234 * leading edge, instead of the trailing.
236 * Ported from: http://underscorejs.org/underscore.js
238 * @param {Function} func Function to debounce
239 * @param {number} [wait=0] Wait period in milliseconds
240 * @param {boolean} [immediate] Trigger on leading edge
241 * @return {Function} Debounced function
243 OO
.ui
.debounce = function ( func
, wait
, immediate
) {
248 later = function () {
251 func
.apply( context
, args
);
254 if ( immediate
&& !timeout
) {
255 func
.apply( context
, args
);
257 if ( !timeout
|| wait
) {
258 clearTimeout( timeout
);
259 timeout
= setTimeout( later
, wait
);
265 * Puts a console warning with provided message.
267 * @param {string} message Message
269 OO
.ui
.warnDeprecation = function ( message
) {
270 if ( OO
.getProp( window
, 'console', 'warn' ) !== undefined ) {
271 // eslint-disable-next-line no-console
272 console
.warn( message
);
277 * Returns a function, that, when invoked, will only be triggered at most once
278 * during a given window of time. If called again during that window, it will
279 * wait until the window ends and then trigger itself again.
281 * As it's not knowable to the caller whether the function will actually run
282 * when the wrapper is called, return values from the function are entirely
285 * @param {Function} func Function to throttle
286 * @param {number} wait Throttle window length, in milliseconds
287 * @return {Function} Throttled function
289 OO
.ui
.throttle = function ( func
, wait
) {
290 var context
, args
, timeout
,
294 previous
= OO
.ui
.now();
295 func
.apply( context
, args
);
298 // Check how long it's been since the last time the function was
299 // called, and whether it's more or less than the requested throttle
300 // period. If it's less, run the function immediately. If it's more,
301 // set a timeout for the remaining time -- but don't replace an
302 // existing timeout, since that'd indefinitely prolong the wait.
303 var remaining
= wait
- ( OO
.ui
.now() - previous
);
306 if ( remaining
<= 0 ) {
307 // Note: unless wait was ridiculously large, this means we'll
308 // automatically run the first time the function was called in a
309 // given period. (If you provide a wait period larger than the
310 // current Unix timestamp, you *deserve* unexpected behavior.)
311 clearTimeout( timeout
);
313 } else if ( !timeout
) {
314 timeout
= setTimeout( run
, remaining
);
320 * A (possibly faster) way to get the current timestamp as an integer
322 * @return {number} Current timestamp, in milliseconds since the Unix epoch
324 OO
.ui
.now
= Date
.now
|| function () {
325 return new Date().getTime();
329 * Reconstitute a JavaScript object corresponding to a widget created by
330 * the PHP implementation.
332 * This is an alias for `OO.ui.Element.static.infuse()`.
334 * @param {string|HTMLElement|jQuery} idOrNode
335 * A DOM id (if a string) or node for the widget to infuse.
336 * @return {OO.ui.Element}
337 * The `OO.ui.Element` corresponding to this (infusable) document node.
339 OO
.ui
.infuse = function ( idOrNode
) {
340 return OO
.ui
.Element
.static.infuse( idOrNode
);
345 * Message store for the default implementation of OO.ui.msg
347 * Environments that provide a localization system should not use this, but should override
348 * OO.ui.msg altogether.
353 // Tool tip for a button that moves items in a list down one place
354 'ooui-outline-control-move-down': 'Move item down',
355 // Tool tip for a button that moves items in a list up one place
356 'ooui-outline-control-move-up': 'Move item up',
357 // Tool tip for a button that removes items from a list
358 'ooui-outline-control-remove': 'Remove item',
359 // Label for the toolbar group that contains a list of all other available tools
360 'ooui-toolbar-more': 'More',
361 // Label for the fake tool that expands the full list of tools in a toolbar group
362 'ooui-toolgroup-expand': 'More',
363 // Label for the fake tool that collapses the full list of tools in a toolbar group
364 'ooui-toolgroup-collapse': 'Fewer',
365 // Default label for the tooltip for the button that removes a tag item
366 'ooui-item-remove': 'Remove',
367 // Default label for the accept button of a confirmation dialog
368 'ooui-dialog-message-accept': 'OK',
369 // Default label for the reject button of a confirmation dialog
370 'ooui-dialog-message-reject': 'Cancel',
371 // Title for process dialog error description
372 'ooui-dialog-process-error': 'Something went wrong',
373 // Label for process dialog dismiss error button, visible when describing errors
374 'ooui-dialog-process-dismiss': 'Dismiss',
375 // Label for process dialog retry action button, visible when describing only recoverable errors
376 'ooui-dialog-process-retry': 'Try again',
377 // Label for process dialog retry action button, visible when describing only warnings
378 'ooui-dialog-process-continue': 'Continue',
379 // Label for the file selection widget's select file button
380 'ooui-selectfile-button-select': 'Select a file',
381 // Label for the file selection widget if file selection is not supported
382 'ooui-selectfile-not-supported': 'File selection is not supported',
383 // Label for the file selection widget when no file is currently selected
384 'ooui-selectfile-placeholder': 'No file is selected',
385 // Label for the file selection widget's drop target
386 'ooui-selectfile-dragdrop-placeholder': 'Drop file here'
390 * Get a localized message.
392 * After the message key, message parameters may optionally be passed. In the default implementation,
393 * any occurrences of $1 are replaced with the first parameter, $2 with the second parameter, etc.
394 * Alternative implementations of OO.ui.msg may use any substitution system they like, as long as
395 * they support unnamed, ordered message parameters.
397 * In environments that provide a localization system, this function should be overridden to
398 * return the message translated in the user's language. The default implementation always returns
399 * English messages. An example of doing this with [jQuery.i18n](https://github.com/wikimedia/jquery.i18n)
403 * var i, iLen, button,
404 * messagePath = 'oojs-ui/dist/i18n/',
405 * languages = [ $.i18n().locale, 'ur', 'en' ],
408 * for ( i = 0, iLen = languages.length; i < iLen; i++ ) {
409 * languageMap[ languages[ i ] ] = messagePath + languages[ i ].toLowerCase() + '.json';
412 * $.i18n().load( languageMap ).done( function() {
413 * // Replace the built-in `msg` only once we've loaded the internationalization.
414 * // OOjs UI uses `OO.ui.deferMsg` for all initially-loaded messages. So long as
415 * // you put off creating any widgets until this promise is complete, no English
416 * // will be displayed.
417 * OO.ui.msg = $.i18n;
419 * // A button displaying "OK" in the default locale
420 * button = new OO.ui.ButtonWidget( {
421 * label: OO.ui.msg( 'ooui-dialog-message-accept' ),
424 * $( 'body' ).append( button.$element );
426 * // A button displaying "OK" in Urdu
427 * $.i18n().locale = 'ur';
428 * button = new OO.ui.ButtonWidget( {
429 * label: OO.ui.msg( 'ooui-dialog-message-accept' ),
432 * $( 'body' ).append( button.$element );
435 * @param {string} key Message key
436 * @param {...Mixed} [params] Message parameters
437 * @return {string} Translated message with parameters substituted
439 OO
.ui
.msg = function ( key
) {
440 var message
= messages
[ key
],
441 params
= Array
.prototype.slice
.call( arguments
, 1 );
442 if ( typeof message
=== 'string' ) {
443 // Perform $1 substitution
444 message
= message
.replace( /\$(\d+)/g, function ( unused
, n
) {
445 var i
= parseInt( n
, 10 );
446 return params
[ i
- 1 ] !== undefined ? params
[ i
- 1 ] : '$' + n
;
449 // Return placeholder if message not found
450 message
= '[' + key
+ ']';
457 * Package a message and arguments for deferred resolution.
459 * Use this when you are statically specifying a message and the message may not yet be present.
461 * @param {string} key Message key
462 * @param {...Mixed} [params] Message parameters
463 * @return {Function} Function that returns the resolved message when executed
465 OO
.ui
.deferMsg = function () {
466 var args
= arguments
;
468 return OO
.ui
.msg
.apply( OO
.ui
, args
);
475 * If the message is a function it will be executed, otherwise it will pass through directly.
477 * @param {Function|string} msg Deferred message, or message text
478 * @return {string} Resolved message
480 OO
.ui
.resolveMsg = function ( msg
) {
481 if ( $.isFunction( msg
) ) {
488 * @param {string} url
491 OO
.ui
.isSafeUrl = function ( url
) {
492 // Keep this function in sync with php/Tag.php
493 var i
, protocolWhitelist
;
495 function stringStartsWith( haystack
, needle
) {
496 return haystack
.substr( 0, needle
.length
) === needle
;
499 protocolWhitelist
= [
500 'bitcoin', 'ftp', 'ftps', 'geo', 'git', 'gopher', 'http', 'https', 'irc', 'ircs',
501 'magnet', 'mailto', 'mms', 'news', 'nntp', 'redis', 'sftp', 'sip', 'sips', 'sms', 'ssh',
502 'svn', 'tel', 'telnet', 'urn', 'worldwind', 'xmpp'
509 for ( i
= 0; i
< protocolWhitelist
.length
; i
++ ) {
510 if ( stringStartsWith( url
, protocolWhitelist
[ i
] + ':' ) ) {
515 // This matches '//' too
516 if ( stringStartsWith( url
, '/' ) || stringStartsWith( url
, './' ) ) {
519 if ( stringStartsWith( url
, '?' ) || stringStartsWith( url
, '#' ) ) {
527 * Check if the user has a 'mobile' device.
529 * For our purposes this means the user is primarily using an
530 * on-screen keyboard, touch input instead of a mouse and may
531 * have a physically small display.
533 * It is left up to implementors to decide how to compute this
534 * so the default implementation always returns false.
536 * @return {boolean} Use is on a mobile device
538 OO
.ui
.isMobile = function () {
547 * Namespace for OOjs UI mixins.
549 * Mixins are named according to the type of object they are intended to
550 * be mixed in to. For example, OO.ui.mixin.GroupElement is intended to be
551 * mixed in to an instance of OO.ui.Element, and OO.ui.mixin.GroupWidget
552 * is intended to be mixed in to an instance of OO.ui.Widget.
560 * Each Element represents a rendering in the DOM—a button or an icon, for example, or anything
561 * that is visible to a user. Unlike {@link OO.ui.Widget widgets}, plain elements usually do not have events
562 * connected to them and can't be interacted with.
568 * @param {Object} [config] Configuration options
569 * @cfg {string[]} [classes] The names of the CSS classes to apply to the element. CSS styles are added
570 * to the top level (e.g., the outermost div) of the element. See the [OOjs UI documentation on MediaWiki][2]
572 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#cssExample
573 * @cfg {string} [id] The HTML id attribute used in the rendered tag.
574 * @cfg {string} [text] Text to insert
575 * @cfg {Array} [content] An array of content elements to append (after #text).
576 * Strings will be html-escaped; use an OO.ui.HtmlSnippet to append raw HTML.
577 * Instances of OO.ui.Element will have their $element appended.
578 * @cfg {jQuery} [$content] Content elements to append (after #text).
579 * @cfg {jQuery} [$element] Wrapper element. Defaults to a new element with #getTagName.
580 * @cfg {Mixed} [data] Custom data of any type or combination of types (e.g., string, number, array, object).
581 * Data can also be specified with the #setData method.
583 OO
.ui
.Element
= function OoUiElement( config
) {
584 this.initialConfig
= config
;
585 // Configuration initialization
586 config
= config
|| {};
590 this.elementId
= null;
592 this.data
= config
.data
;
593 this.$element
= config
.$element
||
594 $( document
.createElement( this.getTagName() ) );
595 this.elementGroup
= null;
598 if ( Array
.isArray( config
.classes
) ) {
599 this.$element
.addClass( config
.classes
.join( ' ' ) );
602 this.setElementId( config
.id
);
605 this.$element
.text( config
.text
);
607 if ( config
.content
) {
608 // The `content` property treats plain strings as text; use an
609 // HtmlSnippet to append HTML content. `OO.ui.Element`s get their
610 // appropriate $element appended.
611 this.$element
.append( config
.content
.map( function ( v
) {
612 if ( typeof v
=== 'string' ) {
613 // Escape string so it is properly represented in HTML.
614 return document
.createTextNode( v
);
615 } else if ( v
instanceof OO
.ui
.HtmlSnippet
) {
618 } else if ( v
instanceof OO
.ui
.Element
) {
624 if ( config
.$content
) {
625 // The `$content` property treats plain strings as HTML.
626 this.$element
.append( config
.$content
);
632 OO
.initClass( OO
.ui
.Element
);
634 /* Static Properties */
637 * The name of the HTML tag used by the element.
639 * The static value may be ignored if the #getTagName method is overridden.
645 OO
.ui
.Element
.static.tagName
= 'div';
650 * Reconstitute a JavaScript object corresponding to a widget created
651 * by the PHP implementation.
653 * @param {string|HTMLElement|jQuery} idOrNode
654 * A DOM id (if a string) or node for the widget to infuse.
655 * @return {OO.ui.Element}
656 * The `OO.ui.Element` corresponding to this (infusable) document node.
657 * For `Tag` objects emitted on the HTML side (used occasionally for content)
658 * the value returned is a newly-created Element wrapping around the existing
661 OO
.ui
.Element
.static.infuse = function ( idOrNode
) {
662 var obj
= OO
.ui
.Element
.static.unsafeInfuse( idOrNode
, false );
663 // Verify that the type matches up.
664 // FIXME: uncomment after T89721 is fixed, see T90929.
666 if ( !( obj instanceof this['class'] ) ) {
667 throw new Error( 'Infusion type mismatch!' );
674 * Implementation helper for `infuse`; skips the type check and has an
675 * extra property so that only the top-level invocation touches the DOM.
678 * @param {string|HTMLElement|jQuery} idOrNode
679 * @param {jQuery.Promise|boolean} domPromise A promise that will be resolved
680 * when the top-level widget of this infusion is inserted into DOM,
681 * replacing the original node; or false for top-level invocation.
682 * @return {OO.ui.Element}
684 OO
.ui
.Element
.static.unsafeInfuse = function ( idOrNode
, domPromise
) {
685 // look for a cached result of a previous infusion.
686 var id
, $elem
, error
, data
, cls
, parts
, parent
, obj
, top
, state
, infusedChildren
;
687 if ( typeof idOrNode
=== 'string' ) {
689 $elem
= $( document
.getElementById( id
) );
691 $elem
= $( idOrNode
);
692 id
= $elem
.attr( 'id' );
694 if ( !$elem
.length
) {
695 if ( typeof idOrNode
=== 'string' ) {
696 error
= 'Widget not found: ' + idOrNode
;
697 } else if ( idOrNode
&& idOrNode
.selector
) {
698 error
= 'Widget not found: ' + idOrNode
.selector
;
700 error
= 'Widget not found';
702 throw new Error( error
);
704 if ( $elem
[ 0 ].oouiInfused
) {
705 $elem
= $elem
[ 0 ].oouiInfused
;
707 data
= $elem
.data( 'ooui-infused' );
710 if ( data
=== true ) {
711 throw new Error( 'Circular dependency! ' + id
);
714 // pick up dynamic state, like focus, value of form inputs, scroll position, etc.
715 state
= data
.constructor.static.gatherPreInfuseState( $elem
, data
);
716 // restore dynamic state after the new element is re-inserted into DOM under infused parent
717 domPromise
.done( data
.restorePreInfuseState
.bind( data
, state
) );
718 infusedChildren
= $elem
.data( 'ooui-infused-children' );
719 if ( infusedChildren
&& infusedChildren
.length
) {
720 infusedChildren
.forEach( function ( data
) {
721 var state
= data
.constructor.static.gatherPreInfuseState( $elem
, data
);
722 domPromise
.done( data
.restorePreInfuseState
.bind( data
, state
) );
728 data
= $elem
.attr( 'data-ooui' );
730 throw new Error( 'No infusion data found: ' + id
);
733 data
= JSON
.parse( data
);
737 if ( !( data
&& data
._
) ) {
738 throw new Error( 'No valid infusion data found: ' + id
);
740 if ( data
._
=== 'Tag' ) {
741 // Special case: this is a raw Tag; wrap existing node, don't rebuild.
742 return new OO
.ui
.Element( { $element
: $elem
} );
744 parts
= data
._
.split( '.' );
745 cls
= OO
.getProp
.apply( OO
, [ window
].concat( parts
) );
746 if ( cls
=== undefined ) {
747 throw new Error( 'Unknown widget type: id: ' + id
+ ', class: ' + data
._
);
750 // Verify that we're creating an OO.ui.Element instance
753 while ( parent
!== undefined ) {
754 if ( parent
=== OO
.ui
.Element
) {
759 parent
= parent
.parent
;
762 if ( parent
!== OO
.ui
.Element
) {
763 throw new Error( 'Unknown widget type: id: ' + id
+ ', class: ' + data
._
);
766 if ( domPromise
=== false ) {
768 domPromise
= top
.promise();
770 $elem
.data( 'ooui-infused', true ); // prevent loops
771 data
.id
= id
; // implicit
772 infusedChildren
= [];
773 data
= OO
.copy( data
, null, function deserialize( value
) {
775 if ( OO
.isPlainObject( value
) ) {
777 infused
= OO
.ui
.Element
.static.unsafeInfuse( value
.tag
, domPromise
);
778 infusedChildren
.push( infused
);
779 // Flatten the structure
780 infusedChildren
.push
.apply( infusedChildren
, infused
.$element
.data( 'ooui-infused-children' ) || [] );
781 infused
.$element
.removeData( 'ooui-infused-children' );
784 if ( value
.html
!== undefined ) {
785 return new OO
.ui
.HtmlSnippet( value
.html
);
789 // allow widgets to reuse parts of the DOM
790 data
= cls
.static.reusePreInfuseDOM( $elem
[ 0 ], data
);
791 // pick up dynamic state, like focus, value of form inputs, scroll position, etc.
792 state
= cls
.static.gatherPreInfuseState( $elem
[ 0 ], data
);
794 // eslint-disable-next-line new-cap
795 obj
= new cls( data
);
796 // now replace old DOM with this new DOM.
798 // An efficient constructor might be able to reuse the entire DOM tree of the original element,
799 // so only mutate the DOM if we need to.
800 if ( $elem
[ 0 ] !== obj
.$element
[ 0 ] ) {
801 $elem
.replaceWith( obj
.$element
);
802 // This element is now gone from the DOM, but if anyone is holding a reference to it,
803 // let's allow them to OO.ui.infuse() it and do what they expect, see T105828.
804 // Do not use jQuery.data(), as using it on detached nodes leaks memory in 1.x line by design.
805 $elem
[ 0 ].oouiInfused
= obj
.$element
;
809 obj
.$element
.data( 'ooui-infused', obj
);
810 obj
.$element
.data( 'ooui-infused-children', infusedChildren
);
811 // set the 'data-ooui' attribute so we can identify infused widgets
812 obj
.$element
.attr( 'data-ooui', '' );
813 // restore dynamic state after the new element is inserted into DOM
814 domPromise
.done( obj
.restorePreInfuseState
.bind( obj
, state
) );
819 * Pick out parts of `node`'s DOM to be reused when infusing a widget.
821 * This method **must not** make any changes to the DOM, only find interesting pieces and add them
822 * to `config` (which should then be returned). Actual DOM juggling should then be done by the
823 * constructor, which will be given the enhanced config.
826 * @param {HTMLElement} node
827 * @param {Object} config
830 OO
.ui
.Element
.static.reusePreInfuseDOM = function ( node
, config
) {
835 * Gather the dynamic state (focus, value of form inputs, scroll position, etc.) of an HTML DOM node
836 * (and its children) that represent an Element of the same class and the given configuration,
837 * generated by the PHP implementation.
839 * This method is called just before `node` is detached from the DOM. The return value of this
840 * function will be passed to #restorePreInfuseState after the newly created widget's #$element
841 * is inserted into DOM to replace `node`.
844 * @param {HTMLElement} node
845 * @param {Object} config
848 OO
.ui
.Element
.static.gatherPreInfuseState = function () {
853 * Get a jQuery function within a specific document.
856 * @param {jQuery|HTMLElement|HTMLDocument|Window} context Context to bind the function to
857 * @param {jQuery} [$iframe] HTML iframe element that contains the document, omit if document is
859 * @return {Function} Bound jQuery function
861 OO
.ui
.Element
.static.getJQuery = function ( context
, $iframe
) {
862 function wrapper( selector
) {
863 return $( selector
, wrapper
.context
);
866 wrapper
.context
= this.getDocument( context
);
869 wrapper
.$iframe
= $iframe
;
876 * Get the document of an element.
879 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Object to get the document for
880 * @return {HTMLDocument|null} Document object
882 OO
.ui
.Element
.static.getDocument = function ( obj
) {
883 // jQuery - selections created "offscreen" won't have a context, so .context isn't reliable
884 return ( obj
[ 0 ] && obj
[ 0 ].ownerDocument
) ||
885 // Empty jQuery selections might have a context
892 ( obj
.nodeType
=== Node
.DOCUMENT_NODE
&& obj
) ||
897 * Get the window of an element or document.
900 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the window for
901 * @return {Window} Window object
903 OO
.ui
.Element
.static.getWindow = function ( obj
) {
904 var doc
= this.getDocument( obj
);
905 return doc
.defaultView
;
909 * Get the direction of an element or document.
912 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the direction for
913 * @return {string} Text direction, either 'ltr' or 'rtl'
915 OO
.ui
.Element
.static.getDir = function ( obj
) {
918 if ( obj
instanceof jQuery
) {
921 isDoc
= obj
.nodeType
=== Node
.DOCUMENT_NODE
;
922 isWin
= obj
.document
!== undefined;
923 if ( isDoc
|| isWin
) {
929 return $( obj
).css( 'direction' );
933 * Get the offset between two frames.
935 * TODO: Make this function not use recursion.
938 * @param {Window} from Window of the child frame
939 * @param {Window} [to=window] Window of the parent frame
940 * @param {Object} [offset] Offset to start with, used internally
941 * @return {Object} Offset object, containing left and top properties
943 OO
.ui
.Element
.static.getFrameOffset = function ( from, to
, offset
) {
944 var i
, len
, frames
, frame
, rect
;
950 offset
= { top
: 0, left
: 0 };
952 if ( from.parent
=== from ) {
956 // Get iframe element
957 frames
= from.parent
.document
.getElementsByTagName( 'iframe' );
958 for ( i
= 0, len
= frames
.length
; i
< len
; i
++ ) {
959 if ( frames
[ i
].contentWindow
=== from ) {
965 // Recursively accumulate offset values
967 rect
= frame
.getBoundingClientRect();
968 offset
.left
+= rect
.left
;
969 offset
.top
+= rect
.top
;
971 this.getFrameOffset( from.parent
, offset
);
978 * Get the offset between two elements.
980 * The two elements may be in a different frame, but in that case the frame $element is in must
981 * be contained in the frame $anchor is in.
984 * @param {jQuery} $element Element whose position to get
985 * @param {jQuery} $anchor Element to get $element's position relative to
986 * @return {Object} Translated position coordinates, containing top and left properties
988 OO
.ui
.Element
.static.getRelativePosition = function ( $element
, $anchor
) {
989 var iframe
, iframePos
,
990 pos
= $element
.offset(),
991 anchorPos
= $anchor
.offset(),
992 elementDocument
= this.getDocument( $element
),
993 anchorDocument
= this.getDocument( $anchor
);
995 // If $element isn't in the same document as $anchor, traverse up
996 while ( elementDocument
!== anchorDocument
) {
997 iframe
= elementDocument
.defaultView
.frameElement
;
999 throw new Error( '$element frame is not contained in $anchor frame' );
1001 iframePos
= $( iframe
).offset();
1002 pos
.left
+= iframePos
.left
;
1003 pos
.top
+= iframePos
.top
;
1004 elementDocument
= iframe
.ownerDocument
;
1006 pos
.left
-= anchorPos
.left
;
1007 pos
.top
-= anchorPos
.top
;
1012 * Get element border sizes.
1015 * @param {HTMLElement} el Element to measure
1016 * @return {Object} Dimensions object with `top`, `left`, `bottom` and `right` properties
1018 OO
.ui
.Element
.static.getBorders = function ( el
) {
1019 var doc
= el
.ownerDocument
,
1020 win
= doc
.defaultView
,
1021 style
= win
.getComputedStyle( el
, null ),
1023 top
= parseFloat( style
? style
.borderTopWidth
: $el
.css( 'borderTopWidth' ) ) || 0,
1024 left
= parseFloat( style
? style
.borderLeftWidth
: $el
.css( 'borderLeftWidth' ) ) || 0,
1025 bottom
= parseFloat( style
? style
.borderBottomWidth
: $el
.css( 'borderBottomWidth' ) ) || 0,
1026 right
= parseFloat( style
? style
.borderRightWidth
: $el
.css( 'borderRightWidth' ) ) || 0;
1037 * Get dimensions of an element or window.
1040 * @param {HTMLElement|Window} el Element to measure
1041 * @return {Object} Dimensions object with `borders`, `scroll`, `scrollbar` and `rect` properties
1043 OO
.ui
.Element
.static.getDimensions = function ( el
) {
1045 doc
= el
.ownerDocument
|| el
.document
,
1046 win
= doc
.defaultView
;
1048 if ( win
=== el
|| el
=== doc
.documentElement
) {
1051 borders
: { top
: 0, left
: 0, bottom
: 0, right
: 0 },
1053 top
: $win
.scrollTop(),
1054 left
: $win
.scrollLeft()
1056 scrollbar
: { right
: 0, bottom
: 0 },
1060 bottom
: $win
.innerHeight(),
1061 right
: $win
.innerWidth()
1067 borders
: this.getBorders( el
),
1069 top
: $el
.scrollTop(),
1070 left
: $el
.scrollLeft()
1073 right
: $el
.innerWidth() - el
.clientWidth
,
1074 bottom
: $el
.innerHeight() - el
.clientHeight
1076 rect
: el
.getBoundingClientRect()
1082 * Get the number of pixels that an element's content is scrolled to the left.
1084 * Adapted from <https://github.com/othree/jquery.rtl-scroll-type>.
1085 * Original code copyright 2012 Wei-Ko Kao, licensed under the MIT License.
1087 * This function smooths out browser inconsistencies (nicely described in the README at
1088 * <https://github.com/othree/jquery.rtl-scroll-type>) and produces a result consistent
1089 * with Firefox's 'scrollLeft', which seems the sanest.
1093 * @param {HTMLElement|Window} el Element to measure
1094 * @return {number} Scroll position from the left.
1095 * If the element's direction is LTR, this is a positive number between `0` (initial scroll position)
1096 * and `el.scrollWidth - el.clientWidth` (furthest possible scroll position).
1097 * If the element's direction is RTL, this is a negative number between `0` (initial scroll position)
1098 * and `-el.scrollWidth + el.clientWidth` (furthest possible scroll position).
1100 OO
.ui
.Element
.static.getScrollLeft
= ( function () {
1101 var rtlScrollType
= null;
1104 var $definer
= $( '<div dir="rtl" style="font-size: 14px; width: 1px; height: 1px; position: absolute; top: -1000px; overflow: scroll">A</div>' ),
1105 definer
= $definer
[ 0 ];
1107 $definer
.appendTo( 'body' );
1108 if ( definer
.scrollLeft
> 0 ) {
1110 rtlScrollType
= 'default';
1112 definer
.scrollLeft
= 1;
1113 if ( definer
.scrollLeft
=== 0 ) {
1114 // Firefox, old Opera
1115 rtlScrollType
= 'negative';
1117 // Internet Explorer, Edge
1118 rtlScrollType
= 'reverse';
1124 return function getScrollLeft( el
) {
1125 var isRoot
= el
.window
=== el
||
1126 el
=== el
.ownerDocument
.body
||
1127 el
=== el
.ownerDocument
.documentElement
,
1128 scrollLeft
= isRoot
? $( window
).scrollLeft() : el
.scrollLeft
,
1129 // All browsers use the correct scroll type ('negative') on the root, so don't
1130 // do any fixups when looking at the root element
1131 direction
= isRoot
? 'ltr' : $( el
).css( 'direction' );
1133 if ( direction
=== 'rtl' ) {
1134 if ( rtlScrollType
=== null ) {
1137 if ( rtlScrollType
=== 'reverse' ) {
1138 scrollLeft
= -scrollLeft
;
1139 } else if ( rtlScrollType
=== 'default' ) {
1140 scrollLeft
= scrollLeft
- el
.scrollWidth
+ el
.clientWidth
;
1149 * Get the root scrollable element of given element's document.
1151 * On Blink-based browsers (Chrome etc.), `document.documentElement` can't be used to get or set
1152 * the scrollTop property; instead we have to use `document.body`. Changing and testing the value
1153 * lets us use 'body' or 'documentElement' based on what is working.
1155 * https://code.google.com/p/chromium/issues/detail?id=303131
1158 * @param {HTMLElement} el Element to find root scrollable parent for
1159 * @return {HTMLElement} Scrollable parent, `document.body` or `document.documentElement`
1160 * depending on browser
1162 OO
.ui
.Element
.static.getRootScrollableElement = function ( el
) {
1163 var scrollTop
, body
;
1165 if ( OO
.ui
.scrollableElement
=== undefined ) {
1166 body
= el
.ownerDocument
.body
;
1167 scrollTop
= body
.scrollTop
;
1170 // In some browsers (observed in Chrome 56 on Linux Mint 18.1),
1171 // body.scrollTop doesn't become exactly 1, but a fractional value like 0.76
1172 if ( Math
.round( body
.scrollTop
) === 1 ) {
1173 body
.scrollTop
= scrollTop
;
1174 OO
.ui
.scrollableElement
= 'body';
1176 OO
.ui
.scrollableElement
= 'documentElement';
1180 return el
.ownerDocument
[ OO
.ui
.scrollableElement
];
1184 * Get closest scrollable container.
1186 * Traverses up until either a scrollable element or the root is reached, in which case the root
1187 * scrollable element will be returned (see #getRootScrollableElement).
1190 * @param {HTMLElement} el Element to find scrollable container for
1191 * @param {string} [dimension] Dimension of scrolling to look for; `x`, `y` or omit for either
1192 * @return {HTMLElement} Closest scrollable container
1194 OO
.ui
.Element
.static.getClosestScrollableContainer = function ( el
, dimension
) {
1196 // Browsers do not correctly return the computed value of 'overflow' when 'overflow-x' and
1197 // 'overflow-y' have different values, so we need to check the separate properties.
1198 props
= [ 'overflow-x', 'overflow-y' ],
1199 $parent
= $( el
).parent();
1201 if ( dimension
=== 'x' || dimension
=== 'y' ) {
1202 props
= [ 'overflow-' + dimension
];
1205 // Special case for the document root (which doesn't really have any scrollable container, since
1206 // it is the ultimate scrollable container, but this is probably saner than null or exception)
1207 if ( $( el
).is( 'html, body' ) ) {
1208 return this.getRootScrollableElement( el
);
1211 while ( $parent
.length
) {
1212 if ( $parent
[ 0 ] === this.getRootScrollableElement( el
) ) {
1213 return $parent
[ 0 ];
1217 val
= $parent
.css( props
[ i
] );
1218 // We assume that elements with 'overflow' (in any direction) set to 'hidden' will never be
1219 // scrolled in that direction, but they can actually be scrolled programatically. The user can
1220 // unintentionally perform a scroll in such case even if the application doesn't scroll
1221 // programatically, e.g. when jumping to an anchor, or when using built-in find functionality.
1222 // This could cause funny issues...
1223 if ( val
=== 'auto' || val
=== 'scroll' ) {
1224 return $parent
[ 0 ];
1227 $parent
= $parent
.parent();
1229 // The element is unattached... return something mostly sane
1230 return this.getRootScrollableElement( el
);
1234 * Scroll element into view.
1237 * @param {HTMLElement} el Element to scroll into view
1238 * @param {Object} [config] Configuration options
1239 * @param {string} [config.duration='fast'] jQuery animation duration value
1240 * @param {string} [config.direction] Scroll in only one direction, e.g. 'x' or 'y', omit
1241 * to scroll in both directions
1242 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1244 OO
.ui
.Element
.static.scrollIntoView = function ( el
, config
) {
1245 var position
, animations
, container
, $container
, elementDimensions
, containerDimensions
, $window
,
1246 deferred
= $.Deferred();
1248 // Configuration initialization
1249 config
= config
|| {};
1252 container
= this.getClosestScrollableContainer( el
, config
.direction
);
1253 $container
= $( container
);
1254 elementDimensions
= this.getDimensions( el
);
1255 containerDimensions
= this.getDimensions( container
);
1256 $window
= $( this.getWindow( el
) );
1258 // Compute the element's position relative to the container
1259 if ( $container
.is( 'html, body' ) ) {
1260 // If the scrollable container is the root, this is easy
1262 top
: elementDimensions
.rect
.top
,
1263 bottom
: $window
.innerHeight() - elementDimensions
.rect
.bottom
,
1264 left
: elementDimensions
.rect
.left
,
1265 right
: $window
.innerWidth() - elementDimensions
.rect
.right
1268 // Otherwise, we have to subtract el's coordinates from container's coordinates
1270 top
: elementDimensions
.rect
.top
- ( containerDimensions
.rect
.top
+ containerDimensions
.borders
.top
),
1271 bottom
: containerDimensions
.rect
.bottom
- containerDimensions
.borders
.bottom
- containerDimensions
.scrollbar
.bottom
- elementDimensions
.rect
.bottom
,
1272 left
: elementDimensions
.rect
.left
- ( containerDimensions
.rect
.left
+ containerDimensions
.borders
.left
),
1273 right
: containerDimensions
.rect
.right
- containerDimensions
.borders
.right
- containerDimensions
.scrollbar
.right
- elementDimensions
.rect
.right
1277 if ( !config
.direction
|| config
.direction
=== 'y' ) {
1278 if ( position
.top
< 0 ) {
1279 animations
.scrollTop
= containerDimensions
.scroll
.top
+ position
.top
;
1280 } else if ( position
.top
> 0 && position
.bottom
< 0 ) {
1281 animations
.scrollTop
= containerDimensions
.scroll
.top
+ Math
.min( position
.top
, -position
.bottom
);
1284 if ( !config
.direction
|| config
.direction
=== 'x' ) {
1285 if ( position
.left
< 0 ) {
1286 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ position
.left
;
1287 } else if ( position
.left
> 0 && position
.right
< 0 ) {
1288 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ Math
.min( position
.left
, -position
.right
);
1291 if ( !$.isEmptyObject( animations
) ) {
1292 $container
.stop( true ).animate( animations
, config
.duration
=== undefined ? 'fast' : config
.duration
);
1293 $container
.queue( function ( next
) {
1300 return deferred
.promise();
1304 * Force the browser to reconsider whether it really needs to render scrollbars inside the element
1305 * and reserve space for them, because it probably doesn't.
1307 * Workaround primarily for <https://code.google.com/p/chromium/issues/detail?id=387290>, but also
1308 * similar bugs in other browsers. "Just" forcing a reflow is not sufficient in all cases, we need
1309 * to first actually detach (or hide, but detaching is simpler) all children, *then* force a reflow,
1310 * and then reattach (or show) them back.
1313 * @param {HTMLElement} el Element to reconsider the scrollbars on
1315 OO
.ui
.Element
.static.reconsiderScrollbars = function ( el
) {
1316 var i
, len
, scrollLeft
, scrollTop
, nodes
= [];
1317 // Save scroll position
1318 scrollLeft
= el
.scrollLeft
;
1319 scrollTop
= el
.scrollTop
;
1320 // Detach all children
1321 while ( el
.firstChild
) {
1322 nodes
.push( el
.firstChild
);
1323 el
.removeChild( el
.firstChild
);
1326 void el
.offsetHeight
;
1327 // Reattach all children
1328 for ( i
= 0, len
= nodes
.length
; i
< len
; i
++ ) {
1329 el
.appendChild( nodes
[ i
] );
1331 // Restore scroll position (no-op if scrollbars disappeared)
1332 el
.scrollLeft
= scrollLeft
;
1333 el
.scrollTop
= scrollTop
;
1339 * Toggle visibility of an element.
1341 * @param {boolean} [show] Make element visible, omit to toggle visibility
1345 OO
.ui
.Element
.prototype.toggle = function ( show
) {
1346 show
= show
=== undefined ? !this.visible
: !!show
;
1348 if ( show
!== this.isVisible() ) {
1349 this.visible
= show
;
1350 this.$element
.toggleClass( 'oo-ui-element-hidden', !this.visible
);
1351 this.emit( 'toggle', show
);
1358 * Check if element is visible.
1360 * @return {boolean} element is visible
1362 OO
.ui
.Element
.prototype.isVisible = function () {
1363 return this.visible
;
1369 * @return {Mixed} Element data
1371 OO
.ui
.Element
.prototype.getData = function () {
1378 * @param {Mixed} data Element data
1381 OO
.ui
.Element
.prototype.setData = function ( data
) {
1387 * Set the element has an 'id' attribute.
1389 * @param {string} id
1392 OO
.ui
.Element
.prototype.setElementId = function ( id
) {
1393 this.elementId
= id
;
1394 this.$element
.attr( 'id', id
);
1399 * Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing,
1400 * and return its value.
1404 OO
.ui
.Element
.prototype.getElementId = function () {
1405 if ( this.elementId
=== null ) {
1406 this.setElementId( OO
.ui
.generateElementId() );
1408 return this.elementId
;
1412 * Check if element supports one or more methods.
1414 * @param {string|string[]} methods Method or list of methods to check
1415 * @return {boolean} All methods are supported
1417 OO
.ui
.Element
.prototype.supports = function ( methods
) {
1421 methods
= Array
.isArray( methods
) ? methods
: [ methods
];
1422 for ( i
= 0, len
= methods
.length
; i
< len
; i
++ ) {
1423 if ( $.isFunction( this[ methods
[ i
] ] ) ) {
1428 return methods
.length
=== support
;
1432 * Update the theme-provided classes.
1434 * @localdoc This is called in element mixins and widget classes any time state changes.
1435 * Updating is debounced, minimizing overhead of changing multiple attributes and
1436 * guaranteeing that theme updates do not occur within an element's constructor
1438 OO
.ui
.Element
.prototype.updateThemeClasses = function () {
1439 OO
.ui
.theme
.queueUpdateElementClasses( this );
1443 * Get the HTML tag name.
1445 * Override this method to base the result on instance information.
1447 * @return {string} HTML tag name
1449 OO
.ui
.Element
.prototype.getTagName = function () {
1450 return this.constructor.static.tagName
;
1454 * Check if the element is attached to the DOM
1456 * @return {boolean} The element is attached to the DOM
1458 OO
.ui
.Element
.prototype.isElementAttached = function () {
1459 return $.contains( this.getElementDocument(), this.$element
[ 0 ] );
1463 * Get the DOM document.
1465 * @return {HTMLDocument} Document object
1467 OO
.ui
.Element
.prototype.getElementDocument = function () {
1468 // Don't cache this in other ways either because subclasses could can change this.$element
1469 return OO
.ui
.Element
.static.getDocument( this.$element
);
1473 * Get the DOM window.
1475 * @return {Window} Window object
1477 OO
.ui
.Element
.prototype.getElementWindow = function () {
1478 return OO
.ui
.Element
.static.getWindow( this.$element
);
1482 * Get closest scrollable container.
1484 * @return {HTMLElement} Closest scrollable container
1486 OO
.ui
.Element
.prototype.getClosestScrollableElementContainer = function () {
1487 return OO
.ui
.Element
.static.getClosestScrollableContainer( this.$element
[ 0 ] );
1491 * Get group element is in.
1493 * @return {OO.ui.mixin.GroupElement|null} Group element, null if none
1495 OO
.ui
.Element
.prototype.getElementGroup = function () {
1496 return this.elementGroup
;
1500 * Set group element is in.
1502 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
1505 OO
.ui
.Element
.prototype.setElementGroup = function ( group
) {
1506 this.elementGroup
= group
;
1511 * Scroll element into view.
1513 * @param {Object} [config] Configuration options
1514 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1516 OO
.ui
.Element
.prototype.scrollElementIntoView = function ( config
) {
1518 !this.isElementAttached() ||
1519 !this.isVisible() ||
1520 ( this.getElementGroup() && !this.getElementGroup().isVisible() )
1522 return $.Deferred().resolve();
1524 return OO
.ui
.Element
.static.scrollIntoView( this.$element
[ 0 ], config
);
1528 * Restore the pre-infusion dynamic state for this widget.
1530 * This method is called after #$element has been inserted into DOM. The parameter is the return
1531 * value of #gatherPreInfuseState.
1534 * @param {Object} state
1536 OO
.ui
.Element
.prototype.restorePreInfuseState = function () {
1540 * Wraps an HTML snippet for use with configuration values which default
1541 * to strings. This bypasses the default html-escaping done to string
1547 * @param {string} [content] HTML content
1549 OO
.ui
.HtmlSnippet
= function OoUiHtmlSnippet( content
) {
1551 this.content
= content
;
1556 OO
.initClass( OO
.ui
.HtmlSnippet
);
1563 * @return {string} Unchanged HTML snippet.
1565 OO
.ui
.HtmlSnippet
.prototype.toString = function () {
1566 return this.content
;
1570 * Layouts are containers for elements and are used to arrange other widgets of arbitrary type in a way
1571 * that is centrally controlled and can be updated dynamically. Layouts can be, and usually are, combined.
1572 * See {@link OO.ui.FieldsetLayout FieldsetLayout}, {@link OO.ui.FieldLayout FieldLayout}, {@link OO.ui.FormLayout FormLayout},
1573 * {@link OO.ui.PanelLayout PanelLayout}, {@link OO.ui.StackLayout StackLayout}, {@link OO.ui.PageLayout PageLayout},
1574 * {@link OO.ui.HorizontalLayout HorizontalLayout}, and {@link OO.ui.BookletLayout BookletLayout} for more information and examples.
1578 * @extends OO.ui.Element
1579 * @mixins OO.EventEmitter
1582 * @param {Object} [config] Configuration options
1584 OO
.ui
.Layout
= function OoUiLayout( config
) {
1585 // Configuration initialization
1586 config
= config
|| {};
1588 // Parent constructor
1589 OO
.ui
.Layout
.parent
.call( this, config
);
1591 // Mixin constructors
1592 OO
.EventEmitter
.call( this );
1595 this.$element
.addClass( 'oo-ui-layout' );
1600 OO
.inheritClass( OO
.ui
.Layout
, OO
.ui
.Element
);
1601 OO
.mixinClass( OO
.ui
.Layout
, OO
.EventEmitter
);
1604 * Widgets are compositions of one or more OOjs UI elements that users can both view
1605 * and interact with. All widgets can be configured and modified via a standard API,
1606 * and their state can change dynamically according to a model.
1610 * @extends OO.ui.Element
1611 * @mixins OO.EventEmitter
1614 * @param {Object} [config] Configuration options
1615 * @cfg {boolean} [disabled=false] Disable the widget. Disabled widgets cannot be used and their
1616 * appearance reflects this state.
1618 OO
.ui
.Widget
= function OoUiWidget( config
) {
1619 // Initialize config
1620 config
= $.extend( { disabled
: false }, config
);
1622 // Parent constructor
1623 OO
.ui
.Widget
.parent
.call( this, config
);
1625 // Mixin constructors
1626 OO
.EventEmitter
.call( this );
1629 this.disabled
= null;
1630 this.wasDisabled
= null;
1633 this.$element
.addClass( 'oo-ui-widget' );
1634 this.setDisabled( !!config
.disabled
);
1639 OO
.inheritClass( OO
.ui
.Widget
, OO
.ui
.Element
);
1640 OO
.mixinClass( OO
.ui
.Widget
, OO
.EventEmitter
);
1647 * A 'disable' event is emitted when the disabled state of the widget changes
1648 * (i.e. on disable **and** enable).
1650 * @param {boolean} disabled Widget is disabled
1656 * A 'toggle' event is emitted when the visibility of the widget changes.
1658 * @param {boolean} visible Widget is visible
1664 * Check if the widget is disabled.
1666 * @return {boolean} Widget is disabled
1668 OO
.ui
.Widget
.prototype.isDisabled = function () {
1669 return this.disabled
;
1673 * Set the 'disabled' state of the widget.
1675 * When a widget is disabled, it cannot be used and its appearance is updated to reflect this state.
1677 * @param {boolean} disabled Disable widget
1680 OO
.ui
.Widget
.prototype.setDisabled = function ( disabled
) {
1683 this.disabled
= !!disabled
;
1684 isDisabled
= this.isDisabled();
1685 if ( isDisabled
!== this.wasDisabled
) {
1686 this.$element
.toggleClass( 'oo-ui-widget-disabled', isDisabled
);
1687 this.$element
.toggleClass( 'oo-ui-widget-enabled', !isDisabled
);
1688 this.$element
.attr( 'aria-disabled', isDisabled
.toString() );
1689 this.emit( 'disable', isDisabled
);
1690 this.updateThemeClasses();
1692 this.wasDisabled
= isDisabled
;
1698 * Update the disabled state, in case of changes in parent widget.
1702 OO
.ui
.Widget
.prototype.updateDisabled = function () {
1703 this.setDisabled( this.disabled
);
1708 * Get an ID of a labelable node which is part of this widget, if any, to be used for `<label for>`
1711 * If this function returns null, the widget should have a meaningful #simulateLabelClick method
1714 * @return {string|null} The ID of the labelable element
1716 OO
.ui
.Widget
.prototype.getInputId = function () {
1721 * Simulate the behavior of clicking on a label (a HTML `<label>` element) bound to this input.
1722 * HTML only allows `<label>` to act on specific "labelable" elements; complex widgets might need to
1723 * override this method to provide intuitive, accessible behavior.
1725 * By default, this does nothing. OO.ui.mixin.TabIndexedElement overrides it for focusable widgets.
1726 * Individual widgets may override it too.
1728 * This method is called by OO.ui.LabelWidget and OO.ui.FieldLayout. It should not be called
1731 OO
.ui
.Widget
.prototype.simulateLabelClick = function () {
1742 OO
.ui
.Theme
= function OoUiTheme() {
1743 this.elementClassesQueue
= [];
1744 this.debouncedUpdateQueuedElementClasses
= OO
.ui
.debounce( this.updateQueuedElementClasses
);
1749 OO
.initClass( OO
.ui
.Theme
);
1754 * Get a list of classes to be applied to a widget.
1756 * The 'on' and 'off' lists combined MUST contain keys for all classes the theme adds or removes,
1757 * otherwise state transitions will not work properly.
1759 * @param {OO.ui.Element} element Element for which to get classes
1760 * @return {Object.<string,string[]>} Categorized class names with `on` and `off` lists
1762 OO
.ui
.Theme
.prototype.getElementClasses = function () {
1763 return { on
: [], off
: [] };
1767 * Update CSS classes provided by the theme.
1769 * For elements with theme logic hooks, this should be called any time there's a state change.
1771 * @param {OO.ui.Element} element Element for which to update classes
1773 OO
.ui
.Theme
.prototype.updateElementClasses = function ( element
) {
1774 var $elements
= $( [] ),
1775 classes
= this.getElementClasses( element
);
1777 if ( element
.$icon
) {
1778 $elements
= $elements
.add( element
.$icon
);
1780 if ( element
.$indicator
) {
1781 $elements
= $elements
.add( element
.$indicator
);
1785 .removeClass( classes
.off
.join( ' ' ) )
1786 .addClass( classes
.on
.join( ' ' ) );
1792 OO
.ui
.Theme
.prototype.updateQueuedElementClasses = function () {
1794 for ( i
= 0; i
< this.elementClassesQueue
.length
; i
++ ) {
1795 this.updateElementClasses( this.elementClassesQueue
[ i
] );
1798 this.elementClassesQueue
= [];
1802 * Queue #updateElementClasses to be called for this element.
1804 * @localdoc QUnit tests override this method to directly call #queueUpdateElementClasses,
1805 * to make them synchronous.
1807 * @param {OO.ui.Element} element Element for which to update classes
1809 OO
.ui
.Theme
.prototype.queueUpdateElementClasses = function ( element
) {
1810 // Keep items in the queue unique. Use lastIndexOf to start checking from the end because that's
1811 // the most common case (this method is often called repeatedly for the same element).
1812 if ( this.elementClassesQueue
.lastIndexOf( element
) !== -1 ) {
1815 this.elementClassesQueue
.push( element
);
1816 this.debouncedUpdateQueuedElementClasses();
1820 * Get the transition duration in milliseconds for dialogs opening/closing
1822 * The dialog should be fully rendered this many milliseconds after the
1823 * ready process has executed.
1825 * @return {number} Transition duration in milliseconds
1827 OO
.ui
.Theme
.prototype.getDialogTransitionDuration = function () {
1832 * The TabIndexedElement class is an attribute mixin used to add additional functionality to an
1833 * element created by another class. The mixin provides a ‘tabIndex’ property, which specifies the
1834 * order in which users will navigate through the focusable elements via the "tab" key.
1837 * // TabIndexedElement is mixed into the ButtonWidget class
1838 * // to provide a tabIndex property.
1839 * var button1 = new OO.ui.ButtonWidget( {
1843 * var button2 = new OO.ui.ButtonWidget( {
1847 * var button3 = new OO.ui.ButtonWidget( {
1851 * var button4 = new OO.ui.ButtonWidget( {
1855 * $( 'body' ).append( button1.$element, button2.$element, button3.$element, button4.$element );
1861 * @param {Object} [config] Configuration options
1862 * @cfg {jQuery} [$tabIndexed] The element that should use the tabindex functionality. By default,
1863 * the functionality is applied to the element created by the class ($element). If a different element is specified, the tabindex
1864 * functionality will be applied to it instead.
1865 * @cfg {string|number|null} [tabIndex=0] Number that specifies the element’s position in the tab-navigation
1866 * order (e.g., 1 for the first focusable element). Use 0 to use the default navigation order; use -1
1867 * to remove the element from the tab-navigation flow.
1869 OO
.ui
.mixin
.TabIndexedElement
= function OoUiMixinTabIndexedElement( config
) {
1870 // Configuration initialization
1871 config
= $.extend( { tabIndex
: 0 }, config
);
1874 this.$tabIndexed
= null;
1875 this.tabIndex
= null;
1878 this.connect( this, { disable
: 'onTabIndexedElementDisable' } );
1881 this.setTabIndex( config
.tabIndex
);
1882 this.setTabIndexedElement( config
.$tabIndexed
|| this.$element
);
1887 OO
.initClass( OO
.ui
.mixin
.TabIndexedElement
);
1892 * Set the element that should use the tabindex functionality.
1894 * This method is used to retarget a tabindex mixin so that its functionality applies
1895 * to the specified element. If an element is currently using the functionality, the mixin’s
1896 * effect on that element is removed before the new element is set up.
1898 * @param {jQuery} $tabIndexed Element that should use the tabindex functionality
1901 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndexedElement = function ( $tabIndexed
) {
1902 var tabIndex
= this.tabIndex
;
1903 // Remove attributes from old $tabIndexed
1904 this.setTabIndex( null );
1905 // Force update of new $tabIndexed
1906 this.$tabIndexed
= $tabIndexed
;
1907 this.tabIndex
= tabIndex
;
1908 return this.updateTabIndex();
1912 * Set the value of the tabindex.
1914 * @param {string|number|null} tabIndex Tabindex value, or `null` for no tabindex
1917 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndex = function ( tabIndex
) {
1918 tabIndex
= /^-?\d+$/.test( tabIndex
) ? Number( tabIndex
) : null;
1920 if ( this.tabIndex
!== tabIndex
) {
1921 this.tabIndex
= tabIndex
;
1922 this.updateTabIndex();
1929 * Update the `tabindex` attribute, in case of changes to tab index or
1935 OO
.ui
.mixin
.TabIndexedElement
.prototype.updateTabIndex = function () {
1936 if ( this.$tabIndexed
) {
1937 if ( this.tabIndex
!== null ) {
1938 // Do not index over disabled elements
1939 this.$tabIndexed
.attr( {
1940 tabindex
: this.isDisabled() ? -1 : this.tabIndex
,
1941 // Support: ChromeVox and NVDA
1942 // These do not seem to inherit aria-disabled from parent elements
1943 'aria-disabled': this.isDisabled().toString()
1946 this.$tabIndexed
.removeAttr( 'tabindex aria-disabled' );
1953 * Handle disable events.
1956 * @param {boolean} disabled Element is disabled
1958 OO
.ui
.mixin
.TabIndexedElement
.prototype.onTabIndexedElementDisable = function () {
1959 this.updateTabIndex();
1963 * Get the value of the tabindex.
1965 * @return {number|null} Tabindex value
1967 OO
.ui
.mixin
.TabIndexedElement
.prototype.getTabIndex = function () {
1968 return this.tabIndex
;
1972 * Get an ID of a focusable element of this widget, if any, to be used for `<label for>` value.
1974 * If the element already has an ID then that is returned, otherwise unique ID is
1975 * generated, set on the element, and returned.
1977 * @return {string|null} The ID of the focusable element
1979 OO
.ui
.mixin
.TabIndexedElement
.prototype.getInputId = function () {
1982 if ( !this.$tabIndexed
) {
1985 if ( !this.isLabelableNode( this.$tabIndexed
) ) {
1989 id
= this.$tabIndexed
.attr( 'id' );
1990 if ( id
=== undefined ) {
1991 id
= OO
.ui
.generateElementId();
1992 this.$tabIndexed
.attr( 'id', id
);
1999 * Whether the node is 'labelable' according to the HTML spec
2000 * (i.e., whether it can be interacted with through a `<label for="…">`).
2001 * See: <https://html.spec.whatwg.org/multipage/forms.html#category-label>.
2004 * @param {jQuery} $node
2007 OO
.ui
.mixin
.TabIndexedElement
.prototype.isLabelableNode = function ( $node
) {
2009 labelableTags
= [ 'button', 'meter', 'output', 'progress', 'select', 'textarea' ],
2010 tagName
= $node
.prop( 'tagName' ).toLowerCase();
2012 if ( tagName
=== 'input' && $node
.attr( 'type' ) !== 'hidden' ) {
2015 if ( labelableTags
.indexOf( tagName
) !== -1 ) {
2022 * Focus this element.
2026 OO
.ui
.mixin
.TabIndexedElement
.prototype.focus = function () {
2027 if ( !this.isDisabled() ) {
2028 this.$tabIndexed
.focus();
2034 * Blur this element.
2038 OO
.ui
.mixin
.TabIndexedElement
.prototype.blur = function () {
2039 this.$tabIndexed
.blur();
2044 * @inheritdoc OO.ui.Widget
2046 OO
.ui
.mixin
.TabIndexedElement
.prototype.simulateLabelClick = function () {
2051 * ButtonElement is often mixed into other classes to generate a button, which is a clickable
2052 * interface element that can be configured with access keys for accessibility.
2053 * See the [OOjs UI documentation on MediaWiki] [1] for examples.
2055 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#Buttons
2061 * @param {Object} [config] Configuration options
2062 * @cfg {jQuery} [$button] The button element created by the class.
2063 * If this configuration is omitted, the button element will use a generated `<a>`.
2064 * @cfg {boolean} [framed=true] Render the button with a frame
2066 OO
.ui
.mixin
.ButtonElement
= function OoUiMixinButtonElement( config
) {
2067 // Configuration initialization
2068 config
= config
|| {};
2071 this.$button
= null;
2073 this.active
= config
.active
!== undefined && config
.active
;
2074 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
2075 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
2076 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
2077 this.onKeyUpHandler
= this.onKeyUp
.bind( this );
2078 this.onClickHandler
= this.onClick
.bind( this );
2079 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
2082 this.$element
.addClass( 'oo-ui-buttonElement' );
2083 this.toggleFramed( config
.framed
=== undefined || config
.framed
);
2084 this.setButtonElement( config
.$button
|| $( '<a>' ) );
2089 OO
.initClass( OO
.ui
.mixin
.ButtonElement
);
2091 /* Static Properties */
2094 * Cancel mouse down events.
2096 * This property is usually set to `true` to prevent the focus from changing when the button is clicked.
2097 * Classes such as {@link OO.ui.mixin.DraggableElement DraggableElement} and {@link OO.ui.ButtonOptionWidget ButtonOptionWidget}
2098 * use a value of `false` so that dragging behavior is possible and mousedown events can be handled by a
2103 * @property {boolean}
2105 OO
.ui
.mixin
.ButtonElement
.static.cancelButtonMouseDownEvents
= true;
2110 * A 'click' event is emitted when the button element is clicked.
2118 * Set the button element.
2120 * This method is used to retarget a button mixin so that its functionality applies to
2121 * the specified button element instead of the one created by the class. If a button element
2122 * is already set, the method will remove the mixin’s effect on that element.
2124 * @param {jQuery} $button Element to use as button
2126 OO
.ui
.mixin
.ButtonElement
.prototype.setButtonElement = function ( $button
) {
2127 if ( this.$button
) {
2129 .removeClass( 'oo-ui-buttonElement-button' )
2130 .removeAttr( 'role accesskey' )
2132 mousedown
: this.onMouseDownHandler
,
2133 keydown
: this.onKeyDownHandler
,
2134 click
: this.onClickHandler
,
2135 keypress
: this.onKeyPressHandler
2139 this.$button
= $button
2140 .addClass( 'oo-ui-buttonElement-button' )
2142 mousedown
: this.onMouseDownHandler
,
2143 keydown
: this.onKeyDownHandler
,
2144 click
: this.onClickHandler
,
2145 keypress
: this.onKeyPressHandler
2148 // Add `role="button"` on `<a>` elements, where it's needed
2149 // `toUppercase()` is added for XHTML documents
2150 if ( this.$button
.prop( 'tagName' ).toUpperCase() === 'A' ) {
2151 this.$button
.attr( 'role', 'button' );
2156 * Handles mouse down events.
2159 * @param {jQuery.Event} e Mouse down event
2161 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseDown = function ( e
) {
2162 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
2165 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
2166 // Run the mouseup handler no matter where the mouse is when the button is let go, so we can
2167 // reliably remove the pressed class
2168 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
2169 // Prevent change of focus unless specifically configured otherwise
2170 if ( this.constructor.static.cancelButtonMouseDownEvents
) {
2176 * Handles mouse up events.
2179 * @param {MouseEvent} e Mouse up event
2181 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseUp = function ( e
) {
2182 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
2185 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
2186 // Stop listening for mouseup, since we only needed this once
2187 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
2191 * Handles mouse click events.
2194 * @param {jQuery.Event} e Mouse click event
2197 OO
.ui
.mixin
.ButtonElement
.prototype.onClick = function ( e
) {
2198 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
2199 if ( this.emit( 'click' ) ) {
2206 * Handles key down events.
2209 * @param {jQuery.Event} e Key down event
2211 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyDown = function ( e
) {
2212 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
2215 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
2216 // Run the keyup handler no matter where the key is when the button is let go, so we can
2217 // reliably remove the pressed class
2218 this.getElementDocument().addEventListener( 'keyup', this.onKeyUpHandler
, true );
2222 * Handles key up events.
2225 * @param {KeyboardEvent} e Key up event
2227 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyUp = function ( e
) {
2228 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
2231 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
2232 // Stop listening for keyup, since we only needed this once
2233 this.getElementDocument().removeEventListener( 'keyup', this.onKeyUpHandler
, true );
2237 * Handles key press events.
2240 * @param {jQuery.Event} e Key press event
2243 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyPress = function ( e
) {
2244 if ( !this.isDisabled() && ( e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
) ) {
2245 if ( this.emit( 'click' ) ) {
2252 * Check if button has a frame.
2254 * @return {boolean} Button is framed
2256 OO
.ui
.mixin
.ButtonElement
.prototype.isFramed = function () {
2261 * Render the button with or without a frame. Omit the `framed` parameter to toggle the button frame on and off.
2263 * @param {boolean} [framed] Make button framed, omit to toggle
2266 OO
.ui
.mixin
.ButtonElement
.prototype.toggleFramed = function ( framed
) {
2267 framed
= framed
=== undefined ? !this.framed
: !!framed
;
2268 if ( framed
!== this.framed
) {
2269 this.framed
= framed
;
2271 .toggleClass( 'oo-ui-buttonElement-frameless', !framed
)
2272 .toggleClass( 'oo-ui-buttonElement-framed', framed
);
2273 this.updateThemeClasses();
2280 * Set the button's active state.
2282 * The active state can be set on:
2284 * - {@link OO.ui.ButtonOptionWidget ButtonOptionWidget} when it is selected
2285 * - {@link OO.ui.ToggleButtonWidget ToggleButtonWidget} when it is toggle on
2286 * - {@link OO.ui.ButtonWidget ButtonWidget} when clicking the button would only refresh the page
2289 * @param {boolean} value Make button active
2292 OO
.ui
.mixin
.ButtonElement
.prototype.setActive = function ( value
) {
2293 this.active
= !!value
;
2294 this.$element
.toggleClass( 'oo-ui-buttonElement-active', this.active
);
2295 this.updateThemeClasses();
2300 * Check if the button is active
2303 * @return {boolean} The button is active
2305 OO
.ui
.mixin
.ButtonElement
.prototype.isActive = function () {
2310 * Any OOjs UI widget that contains other widgets (such as {@link OO.ui.ButtonWidget buttons} or
2311 * {@link OO.ui.OptionWidget options}) mixes in GroupElement. Adding, removing, and clearing
2312 * items from the group is done through the interface the class provides.
2313 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
2315 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Groups
2318 * @mixins OO.EmitterList
2322 * @param {Object} [config] Configuration options
2323 * @cfg {jQuery} [$group] The container element created by the class. If this configuration
2324 * is omitted, the group element will use a generated `<div>`.
2326 OO
.ui
.mixin
.GroupElement
= function OoUiMixinGroupElement( config
) {
2327 // Configuration initialization
2328 config
= config
|| {};
2330 // Mixin constructors
2331 OO
.EmitterList
.call( this, config
);
2337 this.setGroupElement( config
.$group
|| $( '<div>' ) );
2342 OO
.mixinClass( OO
.ui
.mixin
.GroupElement
, OO
.EmitterList
);
2349 * A change event is emitted when the set of selected items changes.
2351 * @param {OO.ui.Element[]} items Items currently in the group
2357 * Set the group element.
2359 * If an element is already set, items will be moved to the new element.
2361 * @param {jQuery} $group Element to use as group
2363 OO
.ui
.mixin
.GroupElement
.prototype.setGroupElement = function ( $group
) {
2366 this.$group
= $group
;
2367 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2368 this.$group
.append( this.items
[ i
].$element
);
2373 * Get an item by its data.
2375 * Only the first item with matching data will be returned. To return all matching items,
2376 * use the #getItemsFromData method.
2378 * @param {Object} data Item data to search for
2379 * @return {OO.ui.Element|null} Item with equivalent data, `null` if none exists
2381 OO
.ui
.mixin
.GroupElement
.prototype.getItemFromData = function ( data
) {
2383 hash
= OO
.getHash( data
);
2385 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2386 item
= this.items
[ i
];
2387 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2396 * Get items by their data.
2398 * All items with matching data will be returned. To return only the first match, use the #getItemFromData method instead.
2400 * @param {Object} data Item data to search for
2401 * @return {OO.ui.Element[]} Items with equivalent data
2403 OO
.ui
.mixin
.GroupElement
.prototype.getItemsFromData = function ( data
) {
2405 hash
= OO
.getHash( data
),
2408 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2409 item
= this.items
[ i
];
2410 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2419 * Add items to the group.
2421 * Items will be added to the end of the group array unless the optional `index` parameter specifies
2422 * a different insertion point. Adding an existing item will move it to the end of the array or the point specified by the `index`.
2424 * @param {OO.ui.Element[]} items An array of items to add to the group
2425 * @param {number} [index] Index of the insertion point
2428 OO
.ui
.mixin
.GroupElement
.prototype.addItems = function ( items
, index
) {
2430 OO
.EmitterList
.prototype.addItems
.call( this, items
, index
);
2432 this.emit( 'change', this.getItems() );
2439 OO
.ui
.mixin
.GroupElement
.prototype.moveItem = function ( items
, newIndex
) {
2440 // insertItemElements expects this.items to not have been modified yet, so call before the mixin
2441 this.insertItemElements( items
, newIndex
);
2444 newIndex
= OO
.EmitterList
.prototype.moveItem
.call( this, items
, newIndex
);
2452 OO
.ui
.mixin
.GroupElement
.prototype.insertItem = function ( item
, index
) {
2453 item
.setElementGroup( this );
2454 this.insertItemElements( item
, index
);
2457 index
= OO
.EmitterList
.prototype.insertItem
.call( this, item
, index
);
2463 * Insert elements into the group
2466 * @param {OO.ui.Element} itemWidget Item to insert
2467 * @param {number} index Insertion index
2469 OO
.ui
.mixin
.GroupElement
.prototype.insertItemElements = function ( itemWidget
, index
) {
2470 if ( index
=== undefined || index
< 0 || index
>= this.items
.length
) {
2471 this.$group
.append( itemWidget
.$element
);
2472 } else if ( index
=== 0 ) {
2473 this.$group
.prepend( itemWidget
.$element
);
2475 this.items
[ index
].$element
.before( itemWidget
.$element
);
2480 * Remove the specified items from a group.
2482 * Removed items are detached (not removed) from the DOM so that they may be reused.
2483 * To remove all items from a group, you may wish to use the #clearItems method instead.
2485 * @param {OO.ui.Element[]} items An array of items to remove
2488 OO
.ui
.mixin
.GroupElement
.prototype.removeItems = function ( items
) {
2489 var i
, len
, item
, index
;
2491 // Remove specific items elements
2492 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
2494 index
= this.items
.indexOf( item
);
2495 if ( index
!== -1 ) {
2496 item
.setElementGroup( null );
2497 item
.$element
.detach();
2502 OO
.EmitterList
.prototype.removeItems
.call( this, items
);
2504 this.emit( 'change', this.getItems() );
2509 * Clear all items from the group.
2511 * Cleared items are detached from the DOM, not removed, so that they may be reused.
2512 * To remove only a subset of items from a group, use the #removeItems method.
2516 OO
.ui
.mixin
.GroupElement
.prototype.clearItems = function () {
2519 // Remove all item elements
2520 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2521 this.items
[ i
].setElementGroup( null );
2522 this.items
[ i
].$element
.detach();
2526 OO
.EmitterList
.prototype.clearItems
.call( this );
2528 this.emit( 'change', this.getItems() );
2533 * IconElement is often mixed into other classes to generate an icon.
2534 * Icons are graphics, about the size of normal text. They are used to aid the user
2535 * in locating a control or to convey information in a space-efficient way. See the
2536 * [OOjs UI documentation on MediaWiki] [1] for a list of icons
2537 * included in the library.
2539 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2545 * @param {Object} [config] Configuration options
2546 * @cfg {jQuery} [$icon] The icon element created by the class. If this configuration is omitted,
2547 * the icon element will use a generated `<span>`. To use a different HTML tag, or to specify that
2548 * the icon element be set to an existing icon instead of the one generated by this class, set a
2549 * value using a jQuery selection. For example:
2551 * // Use a <div> tag instead of a <span>
2553 * // Use an existing icon element instead of the one generated by the class
2554 * $icon: this.$element
2555 * // Use an icon element from a child widget
2556 * $icon: this.childwidget.$element
2557 * @cfg {Object|string} [icon=''] The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of
2558 * symbolic names. A map is used for i18n purposes and contains a `default` icon
2559 * name and additional names keyed by language code. The `default` name is used when no icon is keyed
2560 * by the user's language.
2562 * Example of an i18n map:
2564 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2565 * See the [OOjs UI documentation on MediaWiki] [2] for a list of icons included in the library.
2566 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2567 * @cfg {string|Function} [iconTitle] A text string used as the icon title, or a function that returns title
2568 * text. The icon title is displayed when users move the mouse over the icon.
2570 OO
.ui
.mixin
.IconElement
= function OoUiMixinIconElement( config
) {
2571 // Configuration initialization
2572 config
= config
|| {};
2577 this.iconTitle
= null;
2580 this.setIcon( config
.icon
|| this.constructor.static.icon
);
2581 this.setIconTitle( config
.iconTitle
|| this.constructor.static.iconTitle
);
2582 this.setIconElement( config
.$icon
|| $( '<span>' ) );
2587 OO
.initClass( OO
.ui
.mixin
.IconElement
);
2589 /* Static Properties */
2592 * The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of symbolic names. A map is used
2593 * for i18n purposes and contains a `default` icon name and additional names keyed by
2594 * language code. The `default` name is used when no icon is keyed by the user's language.
2596 * Example of an i18n map:
2598 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2600 * Note: the static property will be overridden if the #icon configuration is used.
2604 * @property {Object|string}
2606 OO
.ui
.mixin
.IconElement
.static.icon
= null;
2609 * The icon title, displayed when users move the mouse over the icon. The value can be text, a
2610 * function that returns title text, or `null` for no title.
2612 * The static property will be overridden if the #iconTitle configuration is used.
2616 * @property {string|Function|null}
2618 OO
.ui
.mixin
.IconElement
.static.iconTitle
= null;
2623 * Set the icon element. This method is used to retarget an icon mixin so that its functionality
2624 * applies to the specified icon element instead of the one created by the class. If an icon
2625 * element is already set, the mixin’s effect on that element is removed. Generated CSS classes
2626 * and mixin methods will no longer affect the element.
2628 * @param {jQuery} $icon Element to use as icon
2630 OO
.ui
.mixin
.IconElement
.prototype.setIconElement = function ( $icon
) {
2633 .removeClass( 'oo-ui-iconElement-icon oo-ui-icon-' + this.icon
)
2634 .removeAttr( 'title' );
2638 .addClass( 'oo-ui-iconElement-icon' )
2639 .toggleClass( 'oo-ui-icon-' + this.icon
, !!this.icon
);
2640 if ( this.iconTitle
!== null ) {
2641 this.$icon
.attr( 'title', this.iconTitle
);
2644 this.updateThemeClasses();
2648 * Set icon by symbolic name (e.g., ‘remove’ or ‘menu’). Use `null` to remove an icon.
2649 * The icon parameter can also be set to a map of icon names. See the #icon config setting
2652 * @param {Object|string|null} icon A symbolic icon name, a {@link #icon map of icon names} keyed
2653 * by language code, or `null` to remove the icon.
2656 OO
.ui
.mixin
.IconElement
.prototype.setIcon = function ( icon
) {
2657 icon
= OO
.isPlainObject( icon
) ? OO
.ui
.getLocalValue( icon
, null, 'default' ) : icon
;
2658 icon
= typeof icon
=== 'string' && icon
.trim().length
? icon
.trim() : null;
2660 if ( this.icon
!== icon
) {
2662 if ( this.icon
!== null ) {
2663 this.$icon
.removeClass( 'oo-ui-icon-' + this.icon
);
2665 if ( icon
!== null ) {
2666 this.$icon
.addClass( 'oo-ui-icon-' + icon
);
2672 this.$element
.toggleClass( 'oo-ui-iconElement', !!this.icon
);
2673 this.updateThemeClasses();
2679 * Set the icon title. Use `null` to remove the title.
2681 * @param {string|Function|null} iconTitle A text string used as the icon title,
2682 * a function that returns title text, or `null` for no title.
2685 OO
.ui
.mixin
.IconElement
.prototype.setIconTitle = function ( iconTitle
) {
2687 ( typeof iconTitle
=== 'function' || ( typeof iconTitle
=== 'string' && iconTitle
.length
) ) ?
2688 OO
.ui
.resolveMsg( iconTitle
) : null;
2690 if ( this.iconTitle
!== iconTitle
) {
2691 this.iconTitle
= iconTitle
;
2693 if ( this.iconTitle
!== null ) {
2694 this.$icon
.attr( 'title', iconTitle
);
2696 this.$icon
.removeAttr( 'title' );
2705 * Get the symbolic name of the icon.
2707 * @return {string} Icon name
2709 OO
.ui
.mixin
.IconElement
.prototype.getIcon = function () {
2714 * Get the icon title. The title text is displayed when a user moves the mouse over the icon.
2716 * @return {string} Icon title text
2718 OO
.ui
.mixin
.IconElement
.prototype.getIconTitle = function () {
2719 return this.iconTitle
;
2723 * IndicatorElement is often mixed into other classes to generate an indicator.
2724 * Indicators are small graphics that are generally used in two ways:
2726 * - To draw attention to the status of an item. For example, an indicator might be
2727 * used to show that an item in a list has errors that need to be resolved.
2728 * - To clarify the function of a control that acts in an exceptional way (a button
2729 * that opens a menu instead of performing an action directly, for example).
2731 * For a list of indicators included in the library, please see the
2732 * [OOjs UI documentation on MediaWiki] [1].
2734 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2740 * @param {Object} [config] Configuration options
2741 * @cfg {jQuery} [$indicator] The indicator element created by the class. If this
2742 * configuration is omitted, the indicator element will use a generated `<span>`.
2743 * @cfg {string} [indicator] Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2744 * See the [OOjs UI documentation on MediaWiki][2] for a list of indicators included
2746 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2747 * @cfg {string|Function} [indicatorTitle] A text string used as the indicator title,
2748 * or a function that returns title text. The indicator title is displayed when users move
2749 * the mouse over the indicator.
2751 OO
.ui
.mixin
.IndicatorElement
= function OoUiMixinIndicatorElement( config
) {
2752 // Configuration initialization
2753 config
= config
|| {};
2756 this.$indicator
= null;
2757 this.indicator
= null;
2758 this.indicatorTitle
= null;
2761 this.setIndicator( config
.indicator
|| this.constructor.static.indicator
);
2762 this.setIndicatorTitle( config
.indicatorTitle
|| this.constructor.static.indicatorTitle
);
2763 this.setIndicatorElement( config
.$indicator
|| $( '<span>' ) );
2768 OO
.initClass( OO
.ui
.mixin
.IndicatorElement
);
2770 /* Static Properties */
2773 * Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2774 * The static property will be overridden if the #indicator configuration is used.
2778 * @property {string|null}
2780 OO
.ui
.mixin
.IndicatorElement
.static.indicator
= null;
2783 * A text string used as the indicator title, a function that returns title text, or `null`
2784 * for no title. The static property will be overridden if the #indicatorTitle configuration is used.
2788 * @property {string|Function|null}
2790 OO
.ui
.mixin
.IndicatorElement
.static.indicatorTitle
= null;
2795 * Set the indicator element.
2797 * If an element is already set, it will be cleaned up before setting up the new element.
2799 * @param {jQuery} $indicator Element to use as indicator
2801 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorElement = function ( $indicator
) {
2802 if ( this.$indicator
) {
2804 .removeClass( 'oo-ui-indicatorElement-indicator oo-ui-indicator-' + this.indicator
)
2805 .removeAttr( 'title' );
2808 this.$indicator
= $indicator
2809 .addClass( 'oo-ui-indicatorElement-indicator' )
2810 .toggleClass( 'oo-ui-indicator-' + this.indicator
, !!this.indicator
);
2811 if ( this.indicatorTitle
!== null ) {
2812 this.$indicator
.attr( 'title', this.indicatorTitle
);
2815 this.updateThemeClasses();
2819 * Set the indicator by its symbolic name: ‘alert’, ‘down’, ‘next’, ‘previous’, ‘required’, ‘up’. Use `null` to remove the indicator.
2821 * @param {string|null} indicator Symbolic name of indicator, or `null` for no indicator
2824 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicator = function ( indicator
) {
2825 indicator
= typeof indicator
=== 'string' && indicator
.length
? indicator
.trim() : null;
2827 if ( this.indicator
!== indicator
) {
2828 if ( this.$indicator
) {
2829 if ( this.indicator
!== null ) {
2830 this.$indicator
.removeClass( 'oo-ui-indicator-' + this.indicator
);
2832 if ( indicator
!== null ) {
2833 this.$indicator
.addClass( 'oo-ui-indicator-' + indicator
);
2836 this.indicator
= indicator
;
2839 this.$element
.toggleClass( 'oo-ui-indicatorElement', !!this.indicator
);
2840 this.updateThemeClasses();
2846 * Set the indicator title.
2848 * The title is displayed when a user moves the mouse over the indicator.
2850 * @param {string|Function|null} indicatorTitle Indicator title text, a function that returns text, or
2851 * `null` for no indicator title
2854 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorTitle = function ( indicatorTitle
) {
2856 ( typeof indicatorTitle
=== 'function' || ( typeof indicatorTitle
=== 'string' && indicatorTitle
.length
) ) ?
2857 OO
.ui
.resolveMsg( indicatorTitle
) : null;
2859 if ( this.indicatorTitle
!== indicatorTitle
) {
2860 this.indicatorTitle
= indicatorTitle
;
2861 if ( this.$indicator
) {
2862 if ( this.indicatorTitle
!== null ) {
2863 this.$indicator
.attr( 'title', indicatorTitle
);
2865 this.$indicator
.removeAttr( 'title' );
2874 * Get the symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2876 * @return {string} Symbolic name of indicator
2878 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicator = function () {
2879 return this.indicator
;
2883 * Get the indicator title.
2885 * The title is displayed when a user moves the mouse over the indicator.
2887 * @return {string} Indicator title text
2889 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicatorTitle = function () {
2890 return this.indicatorTitle
;
2894 * LabelElement is often mixed into other classes to generate a label, which
2895 * helps identify the function of an interface element.
2896 * See the [OOjs UI documentation on MediaWiki] [1] for more information.
2898 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2904 * @param {Object} [config] Configuration options
2905 * @cfg {jQuery} [$label] The label element created by the class. If this
2906 * configuration is omitted, the label element will use a generated `<span>`.
2907 * @cfg {jQuery|string|Function|OO.ui.HtmlSnippet} [label] The label text. The label can be specified
2908 * as a plaintext string, a jQuery selection of elements, or a function that will produce a string
2909 * in the future. See the [OOjs UI documentation on MediaWiki] [2] for examples.
2910 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2912 OO
.ui
.mixin
.LabelElement
= function OoUiMixinLabelElement( config
) {
2913 // Configuration initialization
2914 config
= config
|| {};
2921 this.setLabel( config
.label
|| this.constructor.static.label
);
2922 this.setLabelElement( config
.$label
|| $( '<span>' ) );
2927 OO
.initClass( OO
.ui
.mixin
.LabelElement
);
2932 * @event labelChange
2933 * @param {string} value
2936 /* Static Properties */
2939 * The label text. The label can be specified as a plaintext string, a function that will
2940 * produce a string in the future, or `null` for no label. The static value will
2941 * be overridden if a label is specified with the #label config option.
2945 * @property {string|Function|null}
2947 OO
.ui
.mixin
.LabelElement
.static.label
= null;
2949 /* Static methods */
2952 * Highlight the first occurrence of the query in the given text
2954 * @param {string} text Text
2955 * @param {string} query Query to find
2956 * @param {Function} [compare] Optional string comparator, e.g. Intl.Collator().compare
2957 * @return {jQuery} Text with the first match of the query
2958 * sub-string wrapped in highlighted span
2960 OO
.ui
.mixin
.LabelElement
.static.highlightQuery = function ( text
, query
, compare
) {
2963 $result
= $( '<span>' );
2967 qLen
= query
.length
;
2968 for ( i
= 0; offset
=== -1 && i
<= tLen
- qLen
; i
++ ) {
2969 if ( compare( query
, text
.slice( i
, i
+ qLen
) ) === 0 ) {
2974 offset
= text
.toLowerCase().indexOf( query
.toLowerCase() );
2977 if ( !query
.length
|| offset
=== -1 ) {
2978 $result
.text( text
);
2981 document
.createTextNode( text
.slice( 0, offset
) ),
2983 .addClass( 'oo-ui-labelElement-label-highlight' )
2984 .text( text
.slice( offset
, offset
+ query
.length
) ),
2985 document
.createTextNode( text
.slice( offset
+ query
.length
) )
2988 return $result
.contents();
2994 * Set the label element.
2996 * If an element is already set, it will be cleaned up before setting up the new element.
2998 * @param {jQuery} $label Element to use as label
3000 OO
.ui
.mixin
.LabelElement
.prototype.setLabelElement = function ( $label
) {
3001 if ( this.$label
) {
3002 this.$label
.removeClass( 'oo-ui-labelElement-label' ).empty();
3005 this.$label
= $label
.addClass( 'oo-ui-labelElement-label' );
3006 this.setLabelContent( this.label
);
3012 * An empty string will result in the label being hidden. A string containing only whitespace will
3013 * be converted to a single ` `.
3015 * @param {jQuery|string|OO.ui.HtmlSnippet|Function|null} label Label nodes; text; a function that returns nodes or
3016 * text; or null for no label
3019 OO
.ui
.mixin
.LabelElement
.prototype.setLabel = function ( label
) {
3020 label
= typeof label
=== 'function' ? OO
.ui
.resolveMsg( label
) : label
;
3021 label
= ( ( typeof label
=== 'string' || label
instanceof jQuery
) && label
.length
) || ( label
instanceof OO
.ui
.HtmlSnippet
&& label
.toString().length
) ? label
: null;
3023 if ( this.label
!== label
) {
3024 if ( this.$label
) {
3025 this.setLabelContent( label
);
3028 this.emit( 'labelChange' );
3031 this.$element
.toggleClass( 'oo-ui-labelElement', !!this.label
);
3037 * Set the label as plain text with a highlighted query
3039 * @param {string} text Text label to set
3040 * @param {string} query Substring of text to highlight
3041 * @param {Function} [compare] Optional string comparator, e.g. Intl.Collator().compare
3044 OO
.ui
.mixin
.LabelElement
.prototype.setHighlightedQuery = function ( text
, query
, compare
) {
3045 return this.setLabel( this.constructor.static.highlightQuery( text
, query
, compare
) );
3051 * @return {jQuery|string|Function|null} Label nodes; text; a function that returns nodes or
3052 * text; or null for no label
3054 OO
.ui
.mixin
.LabelElement
.prototype.getLabel = function () {
3059 * Set the content of the label.
3061 * Do not call this method until after the label element has been set by #setLabelElement.
3064 * @param {jQuery|string|Function|null} label Label nodes; text; a function that returns nodes or
3065 * text; or null for no label
3067 OO
.ui
.mixin
.LabelElement
.prototype.setLabelContent = function ( label
) {
3068 if ( typeof label
=== 'string' ) {
3069 if ( label
.match( /^\s*$/ ) ) {
3070 // Convert whitespace only string to a single non-breaking space
3071 this.$label
.html( ' ' );
3073 this.$label
.text( label
);
3075 } else if ( label
instanceof OO
.ui
.HtmlSnippet
) {
3076 this.$label
.html( label
.toString() );
3077 } else if ( label
instanceof jQuery
) {
3078 this.$label
.empty().append( label
);
3080 this.$label
.empty();
3085 * The FlaggedElement class is an attribute mixin, meaning that it is used to add
3086 * additional functionality to an element created by another class. The class provides
3087 * a ‘flags’ property assigned the name (or an array of names) of styling flags,
3088 * which are used to customize the look and feel of a widget to better describe its
3089 * importance and functionality.
3091 * The library currently contains the following styling flags for general use:
3093 * - **progressive**: Progressive styling is applied to convey that the widget will move the user forward in a process.
3094 * - **destructive**: Destructive styling is applied to convey that the widget will remove something.
3095 * - **constructive**: Constructive styling is deprecated since v0.23.2 and equivalent to progressive.
3097 * The flags affect the appearance of the buttons:
3100 * // FlaggedElement is mixed into ButtonWidget to provide styling flags
3101 * var button1 = new OO.ui.ButtonWidget( {
3102 * label: 'Progressive',
3103 * flags: 'progressive'
3105 * var button2 = new OO.ui.ButtonWidget( {
3106 * label: 'Destructive',
3107 * flags: 'destructive'
3109 * $( 'body' ).append( button1.$element, button2.$element );
3111 * {@link OO.ui.ActionWidget ActionWidgets}, which are a special kind of button that execute an action, use these flags: **primary** and **safe**.
3112 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
3114 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
3120 * @param {Object} [config] Configuration options
3121 * @cfg {string|string[]} [flags] The name or names of the flags (e.g., 'progressive' or 'primary') to apply.
3122 * Please see the [OOjs UI documentation on MediaWiki] [2] for more information about available flags.
3123 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
3124 * @cfg {jQuery} [$flagged] The flagged element. By default,
3125 * the flagged functionality is applied to the element created by the class ($element).
3126 * If a different element is specified, the flagged functionality will be applied to it instead.
3128 OO
.ui
.mixin
.FlaggedElement
= function OoUiMixinFlaggedElement( config
) {
3129 // Configuration initialization
3130 config
= config
|| {};
3134 this.$flagged
= null;
3137 this.setFlags( config
.flags
);
3138 this.setFlaggedElement( config
.$flagged
|| this.$element
);
3145 * A flag event is emitted when the #clearFlags or #setFlags methods are used. The `changes`
3146 * parameter contains the name of each modified flag and indicates whether it was
3149 * @param {Object.<string,boolean>} changes Object keyed by flag name. A Boolean `true` indicates
3150 * that the flag was added, `false` that the flag was removed.
3156 * Set the flagged element.
3158 * This method is used to retarget a flagged mixin so that its functionality applies to the specified element.
3159 * If an element is already set, the method will remove the mixin’s effect on that element.
3161 * @param {jQuery} $flagged Element that should be flagged
3163 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlaggedElement = function ( $flagged
) {
3164 var classNames
= Object
.keys( this.flags
).map( function ( flag
) {
3165 return 'oo-ui-flaggedElement-' + flag
;
3168 if ( this.$flagged
) {
3169 this.$flagged
.removeClass( classNames
);
3172 this.$flagged
= $flagged
.addClass( classNames
);
3176 * Check if the specified flag is set.
3178 * @param {string} flag Name of flag
3179 * @return {boolean} The flag is set
3181 OO
.ui
.mixin
.FlaggedElement
.prototype.hasFlag = function ( flag
) {
3182 // This may be called before the constructor, thus before this.flags is set
3183 return this.flags
&& ( flag
in this.flags
);
3187 * Get the names of all flags set.
3189 * @return {string[]} Flag names
3191 OO
.ui
.mixin
.FlaggedElement
.prototype.getFlags = function () {
3192 // This may be called before the constructor, thus before this.flags is set
3193 return Object
.keys( this.flags
|| {} );
3202 OO
.ui
.mixin
.FlaggedElement
.prototype.clearFlags = function () {
3203 var flag
, className
,
3206 classPrefix
= 'oo-ui-flaggedElement-';
3208 for ( flag
in this.flags
) {
3209 className
= classPrefix
+ flag
;
3210 changes
[ flag
] = false;
3211 delete this.flags
[ flag
];
3212 remove
.push( className
);
3215 if ( this.$flagged
) {
3216 this.$flagged
.removeClass( remove
.join( ' ' ) );
3219 this.updateThemeClasses();
3220 this.emit( 'flag', changes
);
3226 * Add one or more flags.
3228 * @param {string|string[]|Object.<string, boolean>} flags A flag name, an array of flag names,
3229 * or an object keyed by flag name with a boolean value that indicates whether the flag should
3230 * be added (`true`) or removed (`false`).
3234 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlags = function ( flags
) {
3235 var i
, len
, flag
, className
,
3239 classPrefix
= 'oo-ui-flaggedElement-';
3241 if ( typeof flags
=== 'string' ) {
3242 className
= classPrefix
+ flags
;
3244 if ( !this.flags
[ flags
] ) {
3245 this.flags
[ flags
] = true;
3246 add
.push( className
);
3248 } else if ( Array
.isArray( flags
) ) {
3249 for ( i
= 0, len
= flags
.length
; i
< len
; i
++ ) {
3251 className
= classPrefix
+ flag
;
3253 if ( !this.flags
[ flag
] ) {
3254 changes
[ flag
] = true;
3255 this.flags
[ flag
] = true;
3256 add
.push( className
);
3259 } else if ( OO
.isPlainObject( flags
) ) {
3260 for ( flag
in flags
) {
3261 className
= classPrefix
+ flag
;
3262 if ( flags
[ flag
] ) {
3264 if ( !this.flags
[ flag
] ) {
3265 changes
[ flag
] = true;
3266 this.flags
[ flag
] = true;
3267 add
.push( className
);
3271 if ( this.flags
[ flag
] ) {
3272 changes
[ flag
] = false;
3273 delete this.flags
[ flag
];
3274 remove
.push( className
);
3280 if ( this.$flagged
) {
3282 .addClass( add
.join( ' ' ) )
3283 .removeClass( remove
.join( ' ' ) );
3286 this.updateThemeClasses();
3287 this.emit( 'flag', changes
);
3293 * TitledElement is mixed into other classes to provide a `title` attribute.
3294 * Titles are rendered by the browser and are made visible when the user moves
3295 * the mouse over the element. Titles are not visible on touch devices.
3298 * // TitledElement provides a 'title' attribute to the
3299 * // ButtonWidget class
3300 * var button = new OO.ui.ButtonWidget( {
3301 * label: 'Button with Title',
3302 * title: 'I am a button'
3304 * $( 'body' ).append( button.$element );
3310 * @param {Object} [config] Configuration options
3311 * @cfg {jQuery} [$titled] The element to which the `title` attribute is applied.
3312 * If this config is omitted, the title functionality is applied to $element, the
3313 * element created by the class.
3314 * @cfg {string|Function} [title] The title text or a function that returns text. If
3315 * this config is omitted, the value of the {@link #static-title static title} property is used.
3317 OO
.ui
.mixin
.TitledElement
= function OoUiMixinTitledElement( config
) {
3318 // Configuration initialization
3319 config
= config
|| {};
3322 this.$titled
= null;
3326 this.setTitle( config
.title
!== undefined ? config
.title
: this.constructor.static.title
);
3327 this.setTitledElement( config
.$titled
|| this.$element
);
3332 OO
.initClass( OO
.ui
.mixin
.TitledElement
);
3334 /* Static Properties */
3337 * The title text, a function that returns text, or `null` for no title. The value of the static property
3338 * is overridden if the #title config option is used.
3342 * @property {string|Function|null}
3344 OO
.ui
.mixin
.TitledElement
.static.title
= null;
3349 * Set the titled element.
3351 * This method is used to retarget a titledElement mixin so that its functionality applies to the specified element.
3352 * If an element is already set, the mixin’s effect on that element is removed before the new element is set up.
3354 * @param {jQuery} $titled Element that should use the 'titled' functionality
3356 OO
.ui
.mixin
.TitledElement
.prototype.setTitledElement = function ( $titled
) {
3357 if ( this.$titled
) {
3358 this.$titled
.removeAttr( 'title' );
3361 this.$titled
= $titled
;
3370 * @param {string|Function|null} title Title text, a function that returns text, or `null` for no title
3373 OO
.ui
.mixin
.TitledElement
.prototype.setTitle = function ( title
) {
3374 title
= typeof title
=== 'function' ? OO
.ui
.resolveMsg( title
) : title
;
3375 title
= ( typeof title
=== 'string' && title
.length
) ? title
: null;
3377 if ( this.title
!== title
) {
3386 * Update the title attribute, in case of changes to title or accessKey.
3391 OO
.ui
.mixin
.TitledElement
.prototype.updateTitle = function () {
3392 var title
= this.getTitle();
3393 if ( this.$titled
) {
3394 if ( title
!== null ) {
3395 // Only if this is an AccessKeyedElement
3396 if ( this.formatTitleWithAccessKey
) {
3397 title
= this.formatTitleWithAccessKey( title
);
3399 this.$titled
.attr( 'title', title
);
3401 this.$titled
.removeAttr( 'title' );
3410 * @return {string} Title string
3412 OO
.ui
.mixin
.TitledElement
.prototype.getTitle = function () {
3417 * AccessKeyedElement is mixed into other classes to provide an `accesskey` attribute.
3418 * Accesskeys allow an user to go to a specific element by using
3419 * a shortcut combination of a browser specific keys + the key
3423 * // AccessKeyedElement provides an 'accesskey' attribute to the
3424 * // ButtonWidget class
3425 * var button = new OO.ui.ButtonWidget( {
3426 * label: 'Button with Accesskey',
3429 * $( 'body' ).append( button.$element );
3435 * @param {Object} [config] Configuration options
3436 * @cfg {jQuery} [$accessKeyed] The element to which the `accesskey` attribute is applied.
3437 * If this config is omitted, the accesskey functionality is applied to $element, the
3438 * element created by the class.
3439 * @cfg {string|Function} [accessKey] The key or a function that returns the key. If
3440 * this config is omitted, no accesskey will be added.
3442 OO
.ui
.mixin
.AccessKeyedElement
= function OoUiMixinAccessKeyedElement( config
) {
3443 // Configuration initialization
3444 config
= config
|| {};
3447 this.$accessKeyed
= null;
3448 this.accessKey
= null;
3451 this.setAccessKey( config
.accessKey
|| null );
3452 this.setAccessKeyedElement( config
.$accessKeyed
|| this.$element
);
3454 // If this is also a TitledElement and it initialized before we did, we may have
3455 // to update the title with the access key
3456 if ( this.updateTitle
) {
3463 OO
.initClass( OO
.ui
.mixin
.AccessKeyedElement
);
3465 /* Static Properties */
3468 * The access key, a function that returns a key, or `null` for no accesskey.
3472 * @property {string|Function|null}
3474 OO
.ui
.mixin
.AccessKeyedElement
.static.accessKey
= null;
3479 * Set the accesskeyed element.
3481 * This method is used to retarget a AccessKeyedElement mixin so that its functionality applies to the specified element.
3482 * If an element is already set, the mixin's effect on that element is removed before the new element is set up.
3484 * @param {jQuery} $accessKeyed Element that should use the 'accesskeyes' functionality
3486 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKeyedElement = function ( $accessKeyed
) {
3487 if ( this.$accessKeyed
) {
3488 this.$accessKeyed
.removeAttr( 'accesskey' );
3491 this.$accessKeyed
= $accessKeyed
;
3492 if ( this.accessKey
) {
3493 this.$accessKeyed
.attr( 'accesskey', this.accessKey
);
3500 * @param {string|Function|null} accessKey Key, a function that returns a key, or `null` for no accesskey
3503 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKey = function ( accessKey
) {
3504 accessKey
= typeof accessKey
=== 'string' ? OO
.ui
.resolveMsg( accessKey
) : null;
3506 if ( this.accessKey
!== accessKey
) {
3507 if ( this.$accessKeyed
) {
3508 if ( accessKey
!== null ) {
3509 this.$accessKeyed
.attr( 'accesskey', accessKey
);
3511 this.$accessKeyed
.removeAttr( 'accesskey' );
3514 this.accessKey
= accessKey
;
3516 // Only if this is a TitledElement
3517 if ( this.updateTitle
) {
3528 * @return {string} accessKey string
3530 OO
.ui
.mixin
.AccessKeyedElement
.prototype.getAccessKey = function () {
3531 return this.accessKey
;
3535 * Add information about the access key to the element's tooltip label.
3536 * (This is only public for hacky usage in FieldLayout.)
3538 * @param {string} title Tooltip label for `title` attribute
3541 OO
.ui
.mixin
.AccessKeyedElement
.prototype.formatTitleWithAccessKey = function ( title
) {
3544 if ( !this.$accessKeyed
) {
3545 // Not initialized yet; the constructor will call updateTitle() which will rerun this function
3548 // Use jquery.accessKeyLabel if available to show modifiers, otherwise just display the single key
3549 if ( $.fn
.updateTooltipAccessKeys
&& $.fn
.updateTooltipAccessKeys
.getAccessKeyLabel
) {
3550 accessKey
= $.fn
.updateTooltipAccessKeys
.getAccessKeyLabel( this.$accessKeyed
[ 0 ] );
3552 accessKey
= this.getAccessKey();
3555 title
+= ' [' + accessKey
+ ']';
3561 * ButtonWidget is a generic widget for buttons. A wide variety of looks,
3562 * feels, and functionality can be customized via the class’s configuration options
3563 * and methods. Please see the [OOjs UI documentation on MediaWiki] [1] for more information
3566 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches
3569 * // A button widget
3570 * var button = new OO.ui.ButtonWidget( {
3571 * label: 'Button with Icon',
3573 * iconTitle: 'Remove'
3575 * $( 'body' ).append( button.$element );
3577 * NOTE: HTML form buttons should use the OO.ui.ButtonInputWidget class.
3580 * @extends OO.ui.Widget
3581 * @mixins OO.ui.mixin.ButtonElement
3582 * @mixins OO.ui.mixin.IconElement
3583 * @mixins OO.ui.mixin.IndicatorElement
3584 * @mixins OO.ui.mixin.LabelElement
3585 * @mixins OO.ui.mixin.TitledElement
3586 * @mixins OO.ui.mixin.FlaggedElement
3587 * @mixins OO.ui.mixin.TabIndexedElement
3588 * @mixins OO.ui.mixin.AccessKeyedElement
3591 * @param {Object} [config] Configuration options
3592 * @cfg {boolean} [active=false] Whether button should be shown as active
3593 * @cfg {string} [href] Hyperlink to visit when the button is clicked.
3594 * @cfg {string} [target] The frame or window in which to open the hyperlink.
3595 * @cfg {boolean} [noFollow] Search engine traversal hint (default: true)
3597 OO
.ui
.ButtonWidget
= function OoUiButtonWidget( config
) {
3598 // Configuration initialization
3599 config
= config
|| {};
3601 // Parent constructor
3602 OO
.ui
.ButtonWidget
.parent
.call( this, config
);
3604 // Mixin constructors
3605 OO
.ui
.mixin
.ButtonElement
.call( this, config
);
3606 OO
.ui
.mixin
.IconElement
.call( this, config
);
3607 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
3608 OO
.ui
.mixin
.LabelElement
.call( this, config
);
3609 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$button
} ) );
3610 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
3611 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$button
} ) );
3612 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$button
} ) );
3617 this.noFollow
= false;
3620 this.connect( this, { disable
: 'onDisable' } );
3623 this.$button
.append( this.$icon
, this.$label
, this.$indicator
);
3625 .addClass( 'oo-ui-buttonWidget' )
3626 .append( this.$button
);
3627 this.setActive( config
.active
);
3628 this.setHref( config
.href
);
3629 this.setTarget( config
.target
);
3630 this.setNoFollow( config
.noFollow
);
3635 OO
.inheritClass( OO
.ui
.ButtonWidget
, OO
.ui
.Widget
);
3636 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.ButtonElement
);
3637 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IconElement
);
3638 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IndicatorElement
);
3639 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.LabelElement
);
3640 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TitledElement
);
3641 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.FlaggedElement
);
3642 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TabIndexedElement
);
3643 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
3645 /* Static Properties */
3651 OO
.ui
.ButtonWidget
.static.cancelButtonMouseDownEvents
= false;
3657 OO
.ui
.ButtonWidget
.static.tagName
= 'span';
3662 * Get hyperlink location.
3664 * @return {string} Hyperlink location
3666 OO
.ui
.ButtonWidget
.prototype.getHref = function () {
3671 * Get hyperlink target.
3673 * @return {string} Hyperlink target
3675 OO
.ui
.ButtonWidget
.prototype.getTarget = function () {
3680 * Get search engine traversal hint.
3682 * @return {boolean} Whether search engines should avoid traversing this hyperlink
3684 OO
.ui
.ButtonWidget
.prototype.getNoFollow = function () {
3685 return this.noFollow
;
3689 * Set hyperlink location.
3691 * @param {string|null} href Hyperlink location, null to remove
3693 OO
.ui
.ButtonWidget
.prototype.setHref = function ( href
) {
3694 href
= typeof href
=== 'string' ? href
: null;
3695 if ( href
!== null && !OO
.ui
.isSafeUrl( href
) ) {
3699 if ( href
!== this.href
) {
3708 * Update the `href` attribute, in case of changes to href or
3714 OO
.ui
.ButtonWidget
.prototype.updateHref = function () {
3715 if ( this.href
!== null && !this.isDisabled() ) {
3716 this.$button
.attr( 'href', this.href
);
3718 this.$button
.removeAttr( 'href' );
3725 * Handle disable events.
3728 * @param {boolean} disabled Element is disabled
3730 OO
.ui
.ButtonWidget
.prototype.onDisable = function () {
3735 * Set hyperlink target.
3737 * @param {string|null} target Hyperlink target, null to remove
3739 OO
.ui
.ButtonWidget
.prototype.setTarget = function ( target
) {
3740 target
= typeof target
=== 'string' ? target
: null;
3742 if ( target
!== this.target
) {
3743 this.target
= target
;
3744 if ( target
!== null ) {
3745 this.$button
.attr( 'target', target
);
3747 this.$button
.removeAttr( 'target' );
3755 * Set search engine traversal hint.
3757 * @param {boolean} noFollow True if search engines should avoid traversing this hyperlink
3759 OO
.ui
.ButtonWidget
.prototype.setNoFollow = function ( noFollow
) {
3760 noFollow
= typeof noFollow
=== 'boolean' ? noFollow
: true;
3762 if ( noFollow
!== this.noFollow
) {
3763 this.noFollow
= noFollow
;
3765 this.$button
.attr( 'rel', 'nofollow' );
3767 this.$button
.removeAttr( 'rel' );
3774 // Override method visibility hints from ButtonElement
3785 * A ButtonGroupWidget groups related buttons and is used together with OO.ui.ButtonWidget and
3786 * its subclasses. Each button in a group is addressed by a unique reference. Buttons can be added,
3787 * removed, and cleared from the group.
3790 * // Example: A ButtonGroupWidget with two buttons
3791 * var button1 = new OO.ui.PopupButtonWidget( {
3792 * label: 'Select a category',
3795 * $content: $( '<p>List of categories...</p>' ),
3800 * var button2 = new OO.ui.ButtonWidget( {
3803 * var buttonGroup = new OO.ui.ButtonGroupWidget( {
3804 * items: [button1, button2]
3806 * $( 'body' ).append( buttonGroup.$element );
3809 * @extends OO.ui.Widget
3810 * @mixins OO.ui.mixin.GroupElement
3813 * @param {Object} [config] Configuration options
3814 * @cfg {OO.ui.ButtonWidget[]} [items] Buttons to add
3816 OO
.ui
.ButtonGroupWidget
= function OoUiButtonGroupWidget( config
) {
3817 // Configuration initialization
3818 config
= config
|| {};
3820 // Parent constructor
3821 OO
.ui
.ButtonGroupWidget
.parent
.call( this, config
);
3823 // Mixin constructors
3824 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
3827 this.$element
.addClass( 'oo-ui-buttonGroupWidget' );
3828 if ( Array
.isArray( config
.items
) ) {
3829 this.addItems( config
.items
);
3835 OO
.inheritClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.Widget
);
3836 OO
.mixinClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.mixin
.GroupElement
);
3838 /* Static Properties */
3844 OO
.ui
.ButtonGroupWidget
.static.tagName
= 'span';
3853 OO
.ui
.ButtonGroupWidget
.prototype.focus = function () {
3854 if ( !this.isDisabled() ) {
3855 if ( this.items
[ 0 ] ) {
3856 this.items
[ 0 ].focus();
3865 OO
.ui
.ButtonGroupWidget
.prototype.simulateLabelClick = function () {
3870 * IconWidget is a generic widget for {@link OO.ui.mixin.IconElement icons}. In general, IconWidgets should be used with OO.ui.LabelWidget,
3871 * which creates a label that identifies the icon’s function. See the [OOjs UI documentation on MediaWiki] [1]
3872 * for a list of icons included in the library.
3875 * // An icon widget with a label
3876 * var myIcon = new OO.ui.IconWidget( {
3880 * // Create a label.
3881 * var iconLabel = new OO.ui.LabelWidget( {
3884 * $( 'body' ).append( myIcon.$element, iconLabel.$element );
3886 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
3889 * @extends OO.ui.Widget
3890 * @mixins OO.ui.mixin.IconElement
3891 * @mixins OO.ui.mixin.TitledElement
3892 * @mixins OO.ui.mixin.FlaggedElement
3895 * @param {Object} [config] Configuration options
3897 OO
.ui
.IconWidget
= function OoUiIconWidget( config
) {
3898 // Configuration initialization
3899 config
= config
|| {};
3901 // Parent constructor
3902 OO
.ui
.IconWidget
.parent
.call( this, config
);
3904 // Mixin constructors
3905 OO
.ui
.mixin
.IconElement
.call( this, $.extend( {}, config
, { $icon
: this.$element
} ) );
3906 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3907 OO
.ui
.mixin
.FlaggedElement
.call( this, $.extend( {}, config
, { $flagged
: this.$element
} ) );
3910 this.$element
.addClass( 'oo-ui-iconWidget' );
3915 OO
.inheritClass( OO
.ui
.IconWidget
, OO
.ui
.Widget
);
3916 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.IconElement
);
3917 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.TitledElement
);
3918 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.FlaggedElement
);
3920 /* Static Properties */
3926 OO
.ui
.IconWidget
.static.tagName
= 'span';
3929 * IndicatorWidgets create indicators, which are small graphics that are generally used to draw
3930 * attention to the status of an item or to clarify the function of a control. For a list of
3931 * indicators included in the library, please see the [OOjs UI documentation on MediaWiki][1].
3934 * // Example of an indicator widget
3935 * var indicator1 = new OO.ui.IndicatorWidget( {
3936 * indicator: 'alert'
3939 * // Create a fieldset layout to add a label
3940 * var fieldset = new OO.ui.FieldsetLayout();
3941 * fieldset.addItems( [
3942 * new OO.ui.FieldLayout( indicator1, { label: 'An alert indicator:' } )
3944 * $( 'body' ).append( fieldset.$element );
3946 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
3949 * @extends OO.ui.Widget
3950 * @mixins OO.ui.mixin.IndicatorElement
3951 * @mixins OO.ui.mixin.TitledElement
3954 * @param {Object} [config] Configuration options
3956 OO
.ui
.IndicatorWidget
= function OoUiIndicatorWidget( config
) {
3957 // Configuration initialization
3958 config
= config
|| {};
3960 // Parent constructor
3961 OO
.ui
.IndicatorWidget
.parent
.call( this, config
);
3963 // Mixin constructors
3964 OO
.ui
.mixin
.IndicatorElement
.call( this, $.extend( {}, config
, { $indicator
: this.$element
} ) );
3965 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3968 this.$element
.addClass( 'oo-ui-indicatorWidget' );
3973 OO
.inheritClass( OO
.ui
.IndicatorWidget
, OO
.ui
.Widget
);
3974 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.IndicatorElement
);
3975 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.TitledElement
);
3977 /* Static Properties */
3983 OO
.ui
.IndicatorWidget
.static.tagName
= 'span';
3986 * LabelWidgets help identify the function of interface elements. Each LabelWidget can
3987 * be configured with a `label` option that is set to a string, a label node, or a function:
3989 * - String: a plaintext string
3990 * - jQuery selection: a jQuery selection, used for anything other than a plaintext label, e.g., a
3991 * label that includes a link or special styling, such as a gray color or additional graphical elements.
3992 * - Function: a function that will produce a string in the future. Functions are used
3993 * in cases where the value of the label is not currently defined.
3995 * In addition, the LabelWidget can be associated with an {@link OO.ui.InputWidget input widget}, which
3996 * will come into focus when the label is clicked.
3999 * // Examples of LabelWidgets
4000 * var label1 = new OO.ui.LabelWidget( {
4001 * label: 'plaintext label'
4003 * var label2 = new OO.ui.LabelWidget( {
4004 * label: $( '<a href="default.html">jQuery label</a>' )
4006 * // Create a fieldset layout with fields for each example
4007 * var fieldset = new OO.ui.FieldsetLayout();
4008 * fieldset.addItems( [
4009 * new OO.ui.FieldLayout( label1 ),
4010 * new OO.ui.FieldLayout( label2 )
4012 * $( 'body' ).append( fieldset.$element );
4015 * @extends OO.ui.Widget
4016 * @mixins OO.ui.mixin.LabelElement
4017 * @mixins OO.ui.mixin.TitledElement
4020 * @param {Object} [config] Configuration options
4021 * @cfg {OO.ui.InputWidget} [input] {@link OO.ui.InputWidget Input widget} that uses the label.
4022 * Clicking the label will focus the specified input field.
4024 OO
.ui
.LabelWidget
= function OoUiLabelWidget( config
) {
4025 // Configuration initialization
4026 config
= config
|| {};
4028 // Parent constructor
4029 OO
.ui
.LabelWidget
.parent
.call( this, config
);
4031 // Mixin constructors
4032 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, { $label
: this.$element
} ) );
4033 OO
.ui
.mixin
.TitledElement
.call( this, config
);
4036 this.input
= config
.input
;
4040 if ( this.input
.getInputId() ) {
4041 this.$element
.attr( 'for', this.input
.getInputId() );
4043 this.$label
.on( 'click', function () {
4044 this.input
.simulateLabelClick();
4049 this.$element
.addClass( 'oo-ui-labelWidget' );
4054 OO
.inheritClass( OO
.ui
.LabelWidget
, OO
.ui
.Widget
);
4055 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.LabelElement
);
4056 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.TitledElement
);
4058 /* Static Properties */
4064 OO
.ui
.LabelWidget
.static.tagName
= 'label';
4067 * PendingElement is a mixin that is used to create elements that notify users that something is happening
4068 * and that they should wait before proceeding. The pending state is visually represented with a pending
4069 * texture that appears in the head of a pending {@link OO.ui.ProcessDialog process dialog} or in the input
4070 * field of a {@link OO.ui.TextInputWidget text input widget}.
4072 * Currently, {@link OO.ui.ActionWidget Action widgets}, which mix in this class, can also be marked as pending, but only when
4073 * used in {@link OO.ui.MessageDialog message dialogs}. The behavior is not currently supported for action widgets used
4074 * in process dialogs.
4077 * function MessageDialog( config ) {
4078 * MessageDialog.parent.call( this, config );
4080 * OO.inheritClass( MessageDialog, OO.ui.MessageDialog );
4082 * MessageDialog.static.name = 'myMessageDialog';
4083 * MessageDialog.static.actions = [
4084 * { action: 'save', label: 'Done', flags: 'primary' },
4085 * { label: 'Cancel', flags: 'safe' }
4088 * MessageDialog.prototype.initialize = function () {
4089 * MessageDialog.parent.prototype.initialize.apply( this, arguments );
4090 * this.content = new OO.ui.PanelLayout( { $: this.$, padded: true } );
4091 * this.content.$element.append( '<p>Click the \'Done\' action widget to see its pending state. Note that action widgets can be marked pending in message dialogs but not process dialogs.</p>' );
4092 * this.$body.append( this.content.$element );
4094 * MessageDialog.prototype.getBodyHeight = function () {
4097 * MessageDialog.prototype.getActionProcess = function ( action ) {
4098 * var dialog = this;
4099 * if ( action === 'save' ) {
4100 * dialog.getActions().get({actions: 'save'})[0].pushPending();
4101 * return new OO.ui.Process()
4103 * .next( function () {
4104 * dialog.getActions().get({actions: 'save'})[0].popPending();
4107 * return MessageDialog.parent.prototype.getActionProcess.call( this, action );
4110 * var windowManager = new OO.ui.WindowManager();
4111 * $( 'body' ).append( windowManager.$element );
4113 * var dialog = new MessageDialog();
4114 * windowManager.addWindows( [ dialog ] );
4115 * windowManager.openWindow( dialog );
4121 * @param {Object} [config] Configuration options
4122 * @cfg {jQuery} [$pending] Element to mark as pending, defaults to this.$element
4124 OO
.ui
.mixin
.PendingElement
= function OoUiMixinPendingElement( config
) {
4125 // Configuration initialization
4126 config
= config
|| {};
4130 this.$pending
= null;
4133 this.setPendingElement( config
.$pending
|| this.$element
);
4138 OO
.initClass( OO
.ui
.mixin
.PendingElement
);
4143 * Set the pending element (and clean up any existing one).
4145 * @param {jQuery} $pending The element to set to pending.
4147 OO
.ui
.mixin
.PendingElement
.prototype.setPendingElement = function ( $pending
) {
4148 if ( this.$pending
) {
4149 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
4152 this.$pending
= $pending
;
4153 if ( this.pending
> 0 ) {
4154 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
4159 * Check if an element is pending.
4161 * @return {boolean} Element is pending
4163 OO
.ui
.mixin
.PendingElement
.prototype.isPending = function () {
4164 return !!this.pending
;
4168 * Increase the pending counter. The pending state will remain active until the counter is zero
4169 * (i.e., the number of calls to #pushPending and #popPending is the same).
4173 OO
.ui
.mixin
.PendingElement
.prototype.pushPending = function () {
4174 if ( this.pending
=== 0 ) {
4175 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
4176 this.updateThemeClasses();
4184 * Decrease the pending counter. The pending state will remain active until the counter is zero
4185 * (i.e., the number of calls to #pushPending and #popPending is the same).
4189 OO
.ui
.mixin
.PendingElement
.prototype.popPending = function () {
4190 if ( this.pending
=== 1 ) {
4191 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
4192 this.updateThemeClasses();
4194 this.pending
= Math
.max( 0, this.pending
- 1 );
4200 * Element that will stick adjacent to a specified container, even when it is inserted elsewhere
4201 * in the document (for example, in an OO.ui.Window's $overlay).
4203 * The elements's position is automatically calculated and maintained when window is resized or the
4204 * page is scrolled. If you reposition the container manually, you have to call #position to make
4205 * sure the element is still placed correctly.
4207 * As positioning is only possible when both the element and the container are attached to the DOM
4208 * and visible, it's only done after you call #togglePositioning. You might want to do this inside
4209 * the #toggle method to display a floating popup, for example.
4215 * @param {Object} [config] Configuration options
4216 * @cfg {jQuery} [$floatable] Node to position, assigned to #$floatable, omit to use #$element
4217 * @cfg {jQuery} [$floatableContainer] Node to position adjacent to
4218 * @cfg {string} [verticalPosition='below'] Where to position $floatable vertically:
4219 * 'below': Directly below $floatableContainer, aligning f's top edge with fC's bottom edge
4220 * 'above': Directly above $floatableContainer, aligning f's bottom edge with fC's top edge
4221 * 'top': Align the top edge with $floatableContainer's top edge
4222 * 'bottom': Align the bottom edge with $floatableContainer's bottom edge
4223 * 'center': Vertically align the center with $floatableContainer's center
4224 * @cfg {string} [horizontalPosition='start'] Where to position $floatable horizontally:
4225 * 'before': Directly before $floatableContainer, aligning f's end edge with fC's start edge
4226 * 'after': Directly after $floatableContainer, algining f's start edge with fC's end edge
4227 * 'start': Align the start (left in LTR, right in RTL) edge with $floatableContainer's start edge
4228 * 'end': Align the end (right in LTR, left in RTL) edge with $floatableContainer's end edge
4229 * 'center': Horizontally align the center with $floatableContainer's center
4230 * @cfg {boolean} [hideWhenOutOfView=true] Whether to hide the floatable element if the container
4233 OO
.ui
.mixin
.FloatableElement
= function OoUiMixinFloatableElement( config
) {
4234 // Configuration initialization
4235 config
= config
|| {};
4238 this.$floatable
= null;
4239 this.$floatableContainer
= null;
4240 this.$floatableWindow
= null;
4241 this.$floatableClosestScrollable
= null;
4242 this.onFloatableScrollHandler
= this.position
.bind( this );
4243 this.onFloatableWindowResizeHandler
= this.position
.bind( this );
4246 this.setFloatableContainer( config
.$floatableContainer
);
4247 this.setFloatableElement( config
.$floatable
|| this.$element
);
4248 this.setVerticalPosition( config
.verticalPosition
|| 'below' );
4249 this.setHorizontalPosition( config
.horizontalPosition
|| 'start' );
4250 this.hideWhenOutOfView
= config
.hideWhenOutOfView
=== undefined ? true : !!config
.hideWhenOutOfView
;
4256 * Set floatable element.
4258 * If an element is already set, it will be cleaned up before setting up the new element.
4260 * @param {jQuery} $floatable Element to make floatable
4262 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableElement = function ( $floatable
) {
4263 if ( this.$floatable
) {
4264 this.$floatable
.removeClass( 'oo-ui-floatableElement-floatable' );
4265 this.$floatable
.css( { left
: '', top
: '' } );
4268 this.$floatable
= $floatable
.addClass( 'oo-ui-floatableElement-floatable' );
4273 * Set floatable container.
4275 * The element will be positioned relative to the specified container.
4277 * @param {jQuery|null} $floatableContainer Container to keep visible, or null to unset
4279 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableContainer = function ( $floatableContainer
) {
4280 this.$floatableContainer
= $floatableContainer
;
4281 if ( this.$floatable
) {
4287 * Change how the element is positioned vertically.
4289 * @param {string} position 'below', 'above', 'top', 'bottom' or 'center'
4291 OO
.ui
.mixin
.FloatableElement
.prototype.setVerticalPosition = function ( position
) {
4292 if ( [ 'below', 'above', 'top', 'bottom', 'center' ].indexOf( position
) === -1 ) {
4293 throw new Error( 'Invalid value for vertical position: ' + position
);
4295 if ( this.verticalPosition
!== position
) {
4296 this.verticalPosition
= position
;
4297 if ( this.$floatable
) {
4304 * Change how the element is positioned horizontally.
4306 * @param {string} position 'before', 'after', 'start', 'end' or 'center'
4308 OO
.ui
.mixin
.FloatableElement
.prototype.setHorizontalPosition = function ( position
) {
4309 if ( [ 'before', 'after', 'start', 'end', 'center' ].indexOf( position
) === -1 ) {
4310 throw new Error( 'Invalid value for horizontal position: ' + position
);
4312 if ( this.horizontalPosition
!== position
) {
4313 this.horizontalPosition
= position
;
4314 if ( this.$floatable
) {
4321 * Toggle positioning.
4323 * Do not turn positioning on until after the element is attached to the DOM and visible.
4325 * @param {boolean} [positioning] Enable positioning, omit to toggle
4328 OO
.ui
.mixin
.FloatableElement
.prototype.togglePositioning = function ( positioning
) {
4329 var closestScrollableOfContainer
;
4331 if ( !this.$floatable
|| !this.$floatableContainer
) {
4335 positioning
= positioning
=== undefined ? !this.positioning
: !!positioning
;
4337 if ( positioning
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
4338 OO
.ui
.warnDeprecation( 'FloatableElement#togglePositioning: Before calling this method, the element must be attached to the DOM.' );
4339 this.warnedUnattached
= true;
4342 if ( this.positioning
!== positioning
) {
4343 this.positioning
= positioning
;
4345 this.needsCustomPosition
=
4346 this.verticalPostion
!== 'below' ||
4347 this.horizontalPosition
!== 'start' ||
4348 !OO
.ui
.contains( this.$floatableContainer
[ 0 ], this.$floatable
[ 0 ] );
4350 closestScrollableOfContainer
= OO
.ui
.Element
.static.getClosestScrollableContainer( this.$floatableContainer
[ 0 ] );
4351 // If the scrollable is the root, we have to listen to scroll events
4352 // on the window because of browser inconsistencies.
4353 if ( $( closestScrollableOfContainer
).is( 'html, body' ) ) {
4354 closestScrollableOfContainer
= OO
.ui
.Element
.static.getWindow( closestScrollableOfContainer
);
4357 if ( positioning
) {
4358 this.$floatableWindow
= $( this.getElementWindow() );
4359 this.$floatableWindow
.on( 'resize', this.onFloatableWindowResizeHandler
);
4361 this.$floatableClosestScrollable
= $( closestScrollableOfContainer
);
4362 this.$floatableClosestScrollable
.on( 'scroll', this.onFloatableScrollHandler
);
4364 // Initial position after visible
4367 if ( this.$floatableWindow
) {
4368 this.$floatableWindow
.off( 'resize', this.onFloatableWindowResizeHandler
);
4369 this.$floatableWindow
= null;
4372 if ( this.$floatableClosestScrollable
) {
4373 this.$floatableClosestScrollable
.off( 'scroll', this.onFloatableScrollHandler
);
4374 this.$floatableClosestScrollable
= null;
4377 this.$floatable
.css( { left
: '', right
: '', top
: '' } );
4385 * Check whether the bottom edge of the given element is within the viewport of the given container.
4388 * @param {jQuery} $element
4389 * @param {jQuery} $container
4392 OO
.ui
.mixin
.FloatableElement
.prototype.isElementInViewport = function ( $element
, $container
) {
4393 var elemRect
, contRect
, topEdgeInBounds
, bottomEdgeInBounds
, leftEdgeInBounds
, rightEdgeInBounds
,
4394 startEdgeInBounds
, endEdgeInBounds
,
4395 direction
= $element
.css( 'direction' );
4397 elemRect
= $element
[ 0 ].getBoundingClientRect();
4398 if ( $container
[ 0 ] === window
) {
4402 right
: document
.documentElement
.clientWidth
,
4403 bottom
: document
.documentElement
.clientHeight
4406 contRect
= $container
[ 0 ].getBoundingClientRect();
4409 topEdgeInBounds
= elemRect
.top
>= contRect
.top
&& elemRect
.top
<= contRect
.bottom
;
4410 bottomEdgeInBounds
= elemRect
.bottom
>= contRect
.top
&& elemRect
.bottom
<= contRect
.bottom
;
4411 leftEdgeInBounds
= elemRect
.left
>= contRect
.left
&& elemRect
.left
<= contRect
.right
;
4412 rightEdgeInBounds
= elemRect
.right
>= contRect
.left
&& elemRect
.right
<= contRect
.right
;
4413 if ( direction
=== 'rtl' ) {
4414 startEdgeInBounds
= rightEdgeInBounds
;
4415 endEdgeInBounds
= leftEdgeInBounds
;
4417 startEdgeInBounds
= leftEdgeInBounds
;
4418 endEdgeInBounds
= rightEdgeInBounds
;
4421 if ( this.verticalPosition
=== 'below' && !bottomEdgeInBounds
) {
4424 if ( this.verticalPosition
=== 'above' && !topEdgeInBounds
) {
4427 if ( this.horizontalPosition
=== 'before' && !startEdgeInBounds
) {
4430 if ( this.horizontalPosition
=== 'after' && !endEdgeInBounds
) {
4434 // The other positioning values are all about being inside the container,
4435 // so in those cases all we care about is that any part of the container is visible.
4436 return elemRect
.top
<= contRect
.bottom
&& elemRect
.bottom
>= contRect
.top
&&
4437 elemRect
.left
<= contRect
.right
&& elemRect
.right
>= contRect
.left
;
4441 * Position the floatable below its container.
4443 * This should only be done when both of them are attached to the DOM and visible.
4447 OO
.ui
.mixin
.FloatableElement
.prototype.position = function () {
4448 if ( !this.positioning
) {
4453 // To continue, some things need to be true:
4454 // The element must actually be in the DOM
4455 this.isElementAttached() && (
4456 // The closest scrollable is the current window
4457 this.$floatableClosestScrollable
[ 0 ] === this.getElementWindow() ||
4458 // OR is an element in the element's DOM
4459 $.contains( this.getElementDocument(), this.$floatableClosestScrollable
[ 0 ] )
4462 // Abort early if important parts of the widget are no longer attached to the DOM
4466 if ( this.hideWhenOutOfView
&& !this.isElementInViewport( this.$floatableContainer
, this.$floatableClosestScrollable
) ) {
4467 this.$floatable
.addClass( 'oo-ui-element-hidden' );
4470 this.$floatable
.removeClass( 'oo-ui-element-hidden' );
4473 if ( !this.needsCustomPosition
) {
4477 this.$floatable
.css( this.computePosition() );
4479 // We updated the position, so re-evaluate the clipping state.
4480 // (ClippableElement does not listen to 'scroll' events on $floatableContainer's parent, and so
4481 // will not notice the need to update itself.)
4482 // TODO: This is terrible, we shouldn't need to know about ClippableElement at all here. Why does
4483 // it not listen to the right events in the right places?
4492 * Compute how #$floatable should be positioned based on the position of #$floatableContainer
4493 * and the positioning settings. This is a helper for #position that shouldn't be called directly,
4494 * but may be overridden by subclasses if they want to change or add to the positioning logic.
4496 * @return {Object} New position to apply with .css(). Keys are 'top', 'left', 'bottom' and 'right'.
4498 OO
.ui
.mixin
.FloatableElement
.prototype.computePosition = function () {
4499 var isBody
, scrollableX
, scrollableY
, containerPos
,
4500 horizScrollbarHeight
, vertScrollbarWidth
, scrollTop
, scrollLeft
,
4501 newPos
= { top
: '', left
: '', bottom
: '', right
: '' },
4502 direction
= this.$floatableContainer
.css( 'direction' ),
4503 $offsetParent
= this.$floatable
.offsetParent();
4505 if ( $offsetParent
.is( 'html' ) ) {
4506 // The innerHeight/Width and clientHeight/Width calculations don't work well on the
4507 // <html> element, but they do work on the <body>
4508 $offsetParent
= $( $offsetParent
[ 0 ].ownerDocument
.body
);
4510 isBody
= $offsetParent
.is( 'body' );
4511 scrollableX
= $offsetParent
.css( 'overflow-x' ) === 'scroll' || $offsetParent
.css( 'overflow-x' ) === 'auto';
4512 scrollableY
= $offsetParent
.css( 'overflow-y' ) === 'scroll' || $offsetParent
.css( 'overflow-y' ) === 'auto';
4514 vertScrollbarWidth
= $offsetParent
.innerWidth() - $offsetParent
.prop( 'clientWidth' );
4515 horizScrollbarHeight
= $offsetParent
.innerHeight() - $offsetParent
.prop( 'clientHeight' );
4516 // We don't need to compute and add scrollTop and scrollLeft if the scrollable container is the body,
4517 // or if it isn't scrollable
4518 scrollTop
= scrollableY
&& !isBody
? $offsetParent
.scrollTop() : 0;
4519 scrollLeft
= scrollableX
&& !isBody
? OO
.ui
.Element
.static.getScrollLeft( $offsetParent
[ 0 ] ) : 0;
4521 // Avoid passing the <body> to getRelativePosition(), because it won't return what we expect
4522 // if the <body> has a margin
4523 containerPos
= isBody
?
4524 this.$floatableContainer
.offset() :
4525 OO
.ui
.Element
.static.getRelativePosition( this.$floatableContainer
, $offsetParent
);
4526 containerPos
.bottom
= containerPos
.top
+ this.$floatableContainer
.outerHeight();
4527 containerPos
.right
= containerPos
.left
+ this.$floatableContainer
.outerWidth();
4528 containerPos
.start
= direction
=== 'rtl' ? containerPos
.right
: containerPos
.left
;
4529 containerPos
.end
= direction
=== 'rtl' ? containerPos
.left
: containerPos
.right
;
4531 if ( this.verticalPosition
=== 'below' ) {
4532 newPos
.top
= containerPos
.bottom
;
4533 } else if ( this.verticalPosition
=== 'above' ) {
4534 newPos
.bottom
= $offsetParent
.outerHeight() - containerPos
.top
;
4535 } else if ( this.verticalPosition
=== 'top' ) {
4536 newPos
.top
= containerPos
.top
;
4537 } else if ( this.verticalPosition
=== 'bottom' ) {
4538 newPos
.bottom
= $offsetParent
.outerHeight() - containerPos
.bottom
;
4539 } else if ( this.verticalPosition
=== 'center' ) {
4540 newPos
.top
= containerPos
.top
+
4541 ( this.$floatableContainer
.height() - this.$floatable
.height() ) / 2;
4544 if ( this.horizontalPosition
=== 'before' ) {
4545 newPos
.end
= containerPos
.start
;
4546 } else if ( this.horizontalPosition
=== 'after' ) {
4547 newPos
.start
= containerPos
.end
;
4548 } else if ( this.horizontalPosition
=== 'start' ) {
4549 newPos
.start
= containerPos
.start
;
4550 } else if ( this.horizontalPosition
=== 'end' ) {
4551 newPos
.end
= containerPos
.end
;
4552 } else if ( this.horizontalPosition
=== 'center' ) {
4553 newPos
.left
= containerPos
.left
+
4554 ( this.$floatableContainer
.width() - this.$floatable
.width() ) / 2;
4557 if ( newPos
.start
!== undefined ) {
4558 if ( direction
=== 'rtl' ) {
4559 newPos
.right
= ( isBody
? $( $offsetParent
[ 0 ].ownerDocument
.documentElement
) : $offsetParent
).outerWidth() - newPos
.start
;
4561 newPos
.left
= newPos
.start
;
4563 delete newPos
.start
;
4565 if ( newPos
.end
!== undefined ) {
4566 if ( direction
=== 'rtl' ) {
4567 newPos
.left
= newPos
.end
;
4569 newPos
.right
= ( isBody
? $( $offsetParent
[ 0 ].ownerDocument
.documentElement
) : $offsetParent
).outerWidth() - newPos
.end
;
4574 // Account for scroll position
4575 if ( newPos
.top
!== '' ) {
4576 newPos
.top
+= scrollTop
;
4578 if ( newPos
.bottom
!== '' ) {
4579 newPos
.bottom
-= scrollTop
;
4581 if ( newPos
.left
!== '' ) {
4582 newPos
.left
+= scrollLeft
;
4584 if ( newPos
.right
!== '' ) {
4585 newPos
.right
-= scrollLeft
;
4588 // Account for scrollbar gutter
4589 if ( newPos
.bottom
!== '' ) {
4590 newPos
.bottom
-= horizScrollbarHeight
;
4592 if ( direction
=== 'rtl' ) {
4593 if ( newPos
.left
!== '' ) {
4594 newPos
.left
-= vertScrollbarWidth
;
4597 if ( newPos
.right
!== '' ) {
4598 newPos
.right
-= vertScrollbarWidth
;
4606 * Element that can be automatically clipped to visible boundaries.
4608 * Whenever the element's natural height changes, you have to call
4609 * {@link OO.ui.mixin.ClippableElement#clip} to make sure it's still
4610 * clipping correctly.
4612 * The dimensions of #$clippableContainer will be compared to the boundaries of the
4613 * nearest scrollable container. If #$clippableContainer is too tall and/or too wide,
4614 * then #$clippable will be given a fixed reduced height and/or width and will be made
4615 * scrollable. By default, #$clippable and #$clippableContainer are the same element,
4616 * but you can build a static footer by setting #$clippableContainer to an element that contains
4617 * #$clippable and the footer.
4623 * @param {Object} [config] Configuration options
4624 * @cfg {jQuery} [$clippable] Node to clip, assigned to #$clippable, omit to use #$element
4625 * @cfg {jQuery} [$clippableContainer] Node to keep visible, assigned to #$clippableContainer,
4626 * omit to use #$clippable
4628 OO
.ui
.mixin
.ClippableElement
= function OoUiMixinClippableElement( config
) {
4629 // Configuration initialization
4630 config
= config
|| {};
4633 this.$clippable
= null;
4634 this.$clippableContainer
= null;
4635 this.clipping
= false;
4636 this.clippedHorizontally
= false;
4637 this.clippedVertically
= false;
4638 this.$clippableScrollableContainer
= null;
4639 this.$clippableScroller
= null;
4640 this.$clippableWindow
= null;
4641 this.idealWidth
= null;
4642 this.idealHeight
= null;
4643 this.onClippableScrollHandler
= this.clip
.bind( this );
4644 this.onClippableWindowResizeHandler
= this.clip
.bind( this );
4647 if ( config
.$clippableContainer
) {
4648 this.setClippableContainer( config
.$clippableContainer
);
4650 this.setClippableElement( config
.$clippable
|| this.$element
);
4656 * Set clippable element.
4658 * If an element is already set, it will be cleaned up before setting up the new element.
4660 * @param {jQuery} $clippable Element to make clippable
4662 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableElement = function ( $clippable
) {
4663 if ( this.$clippable
) {
4664 this.$clippable
.removeClass( 'oo-ui-clippableElement-clippable' );
4665 this.$clippable
.css( { width
: '', height
: '', overflowX
: '', overflowY
: '' } );
4666 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4669 this.$clippable
= $clippable
.addClass( 'oo-ui-clippableElement-clippable' );
4674 * Set clippable container.
4676 * This is the container that will be measured when deciding whether to clip. When clipping,
4677 * #$clippable will be resized in order to keep the clippable container fully visible.
4679 * If the clippable container is unset, #$clippable will be used.
4681 * @param {jQuery|null} $clippableContainer Container to keep visible, or null to unset
4683 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableContainer = function ( $clippableContainer
) {
4684 this.$clippableContainer
= $clippableContainer
;
4685 if ( this.$clippable
) {
4693 * Do not turn clipping on until after the element is attached to the DOM and visible.
4695 * @param {boolean} [clipping] Enable clipping, omit to toggle
4698 OO
.ui
.mixin
.ClippableElement
.prototype.toggleClipping = function ( clipping
) {
4699 clipping
= clipping
=== undefined ? !this.clipping
: !!clipping
;
4701 if ( clipping
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
4702 OO
.ui
.warnDeprecation( 'ClippableElement#toggleClipping: Before calling this method, the element must be attached to the DOM.' );
4703 this.warnedUnattached
= true;
4706 if ( this.clipping
!== clipping
) {
4707 this.clipping
= clipping
;
4709 this.$clippableScrollableContainer
= $( this.getClosestScrollableElementContainer() );
4710 // If the clippable container is the root, we have to listen to scroll events and check
4711 // jQuery.scrollTop on the window because of browser inconsistencies
4712 this.$clippableScroller
= this.$clippableScrollableContainer
.is( 'html, body' ) ?
4713 $( OO
.ui
.Element
.static.getWindow( this.$clippableScrollableContainer
) ) :
4714 this.$clippableScrollableContainer
;
4715 this.$clippableScroller
.on( 'scroll', this.onClippableScrollHandler
);
4716 this.$clippableWindow
= $( this.getElementWindow() )
4717 .on( 'resize', this.onClippableWindowResizeHandler
);
4718 // Initial clip after visible
4721 this.$clippable
.css( {
4729 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4731 this.$clippableScrollableContainer
= null;
4732 this.$clippableScroller
.off( 'scroll', this.onClippableScrollHandler
);
4733 this.$clippableScroller
= null;
4734 this.$clippableWindow
.off( 'resize', this.onClippableWindowResizeHandler
);
4735 this.$clippableWindow
= null;
4743 * Check if the element will be clipped to fit the visible area of the nearest scrollable container.
4745 * @return {boolean} Element will be clipped to the visible area
4747 OO
.ui
.mixin
.ClippableElement
.prototype.isClipping = function () {
4748 return this.clipping
;
4752 * Check if the bottom or right of the element is being clipped by the nearest scrollable container.
4754 * @return {boolean} Part of the element is being clipped
4756 OO
.ui
.mixin
.ClippableElement
.prototype.isClipped = function () {
4757 return this.clippedHorizontally
|| this.clippedVertically
;
4761 * Check if the right of the element is being clipped by the nearest scrollable container.
4763 * @return {boolean} Part of the element is being clipped
4765 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedHorizontally = function () {
4766 return this.clippedHorizontally
;
4770 * Check if the bottom of the element is being clipped by the nearest scrollable container.
4772 * @return {boolean} Part of the element is being clipped
4774 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedVertically = function () {
4775 return this.clippedVertically
;
4779 * Set the ideal size. These are the dimensions #$clippable will have when it's not being clipped.
4781 * @param {number|string} [width] Width as a number of pixels or CSS string with unit suffix
4782 * @param {number|string} [height] Height as a number of pixels or CSS string with unit suffix
4784 OO
.ui
.mixin
.ClippableElement
.prototype.setIdealSize = function ( width
, height
) {
4785 this.idealWidth
= width
;
4786 this.idealHeight
= height
;
4788 if ( !this.clipping
) {
4789 // Update dimensions
4790 this.$clippable
.css( { width
: width
, height
: height
} );
4792 // While clipping, idealWidth and idealHeight are not considered
4796 * Clip element to visible boundaries and allow scrolling when needed. You should call this method
4797 * when the element's natural height changes.
4799 * Element will be clipped the bottom or right of the element is within 10px of the edge of, or
4800 * overlapped by, the visible area of the nearest scrollable container.
4802 * Because calling clip() when the natural height changes isn't always possible, we also set
4803 * max-height when the element isn't being clipped. This means that if the element tries to grow
4804 * beyond the edge, something reasonable will happen before clip() is called.
4808 OO
.ui
.mixin
.ClippableElement
.prototype.clip = function () {
4809 var $container
, extraHeight
, extraWidth
, ccOffset
,
4810 $scrollableContainer
, scOffset
, scHeight
, scWidth
,
4811 ccWidth
, scrollerIsWindow
, scrollTop
, scrollLeft
,
4812 desiredWidth
, desiredHeight
, allotedWidth
, allotedHeight
,
4813 naturalWidth
, naturalHeight
, clipWidth
, clipHeight
,
4814 buffer
= 7; // Chosen by fair dice roll
4816 if ( !this.clipping
) {
4817 // this.$clippableScrollableContainer and this.$clippableWindow are null, so the below will fail
4821 $container
= this.$clippableContainer
|| this.$clippable
;
4822 extraHeight
= $container
.outerHeight() - this.$clippable
.outerHeight();
4823 extraWidth
= $container
.outerWidth() - this.$clippable
.outerWidth();
4824 ccOffset
= $container
.offset();
4825 if ( this.$clippableScrollableContainer
.is( 'html, body' ) ) {
4826 $scrollableContainer
= this.$clippableWindow
;
4827 scOffset
= { top
: 0, left
: 0 };
4829 $scrollableContainer
= this.$clippableScrollableContainer
;
4830 scOffset
= $scrollableContainer
.offset();
4832 scHeight
= $scrollableContainer
.innerHeight() - buffer
;
4833 scWidth
= $scrollableContainer
.innerWidth() - buffer
;
4834 ccWidth
= $container
.outerWidth() + buffer
;
4835 scrollerIsWindow
= this.$clippableScroller
[ 0 ] === this.$clippableWindow
[ 0 ];
4836 scrollTop
= scrollerIsWindow
? this.$clippableScroller
.scrollTop() : 0;
4837 scrollLeft
= scrollerIsWindow
? this.$clippableScroller
.scrollLeft() : 0;
4838 desiredWidth
= ccOffset
.left
< 0 ?
4839 ccWidth
+ ccOffset
.left
:
4840 ( scOffset
.left
+ scrollLeft
+ scWidth
) - ccOffset
.left
;
4841 desiredHeight
= ( scOffset
.top
+ scrollTop
+ scHeight
) - ccOffset
.top
;
4842 // It should never be desirable to exceed the dimensions of the browser viewport... right?
4843 desiredWidth
= Math
.min( desiredWidth
, document
.documentElement
.clientWidth
);
4844 desiredHeight
= Math
.min( desiredHeight
, document
.documentElement
.clientHeight
);
4845 allotedWidth
= Math
.ceil( desiredWidth
- extraWidth
);
4846 allotedHeight
= Math
.ceil( desiredHeight
- extraHeight
);
4847 naturalWidth
= this.$clippable
.prop( 'scrollWidth' );
4848 naturalHeight
= this.$clippable
.prop( 'scrollHeight' );
4849 clipWidth
= allotedWidth
< naturalWidth
;
4850 clipHeight
= allotedHeight
< naturalHeight
;
4853 // The order matters here. If overflow is not set first, Chrome displays bogus scrollbars. See T157672.
4854 // Forcing a reflow is a smaller workaround than calling reconsiderScrollbars() for this case.
4855 this.$clippable
.css( 'overflowX', 'scroll' );
4856 void this.$clippable
[ 0 ].offsetHeight
; // Force reflow
4857 this.$clippable
.css( {
4858 width
: Math
.max( 0, allotedWidth
),
4862 this.$clippable
.css( {
4864 width
: this.idealWidth
|| '',
4865 maxWidth
: Math
.max( 0, allotedWidth
)
4869 // The order matters here. If overflow is not set first, Chrome displays bogus scrollbars. See T157672.
4870 // Forcing a reflow is a smaller workaround than calling reconsiderScrollbars() for this case.
4871 this.$clippable
.css( 'overflowY', 'scroll' );
4872 void this.$clippable
[ 0 ].offsetHeight
; // Force reflow
4873 this.$clippable
.css( {
4874 height
: Math
.max( 0, allotedHeight
),
4878 this.$clippable
.css( {
4880 height
: this.idealHeight
|| '',
4881 maxHeight
: Math
.max( 0, allotedHeight
)
4885 // If we stopped clipping in at least one of the dimensions
4886 if ( ( this.clippedHorizontally
&& !clipWidth
) || ( this.clippedVertically
&& !clipHeight
) ) {
4887 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4890 this.clippedHorizontally
= clipWidth
;
4891 this.clippedVertically
= clipHeight
;
4897 * PopupWidget is a container for content. The popup is overlaid and positioned absolutely.
4898 * By default, each popup has an anchor that points toward its origin.
4899 * Please see the [OOjs UI documentation on Mediawiki] [1] for more information and examples.
4901 * Unlike most widgets, PopupWidget is initially hidden and must be shown by calling #toggle.
4904 * // A popup widget.
4905 * var popup = new OO.ui.PopupWidget( {
4906 * $content: $( '<p>Hi there!</p>' ),
4911 * $( 'body' ).append( popup.$element );
4912 * // To display the popup, toggle the visibility to 'true'.
4913 * popup.toggle( true );
4915 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups
4918 * @extends OO.ui.Widget
4919 * @mixins OO.ui.mixin.LabelElement
4920 * @mixins OO.ui.mixin.ClippableElement
4921 * @mixins OO.ui.mixin.FloatableElement
4924 * @param {Object} [config] Configuration options
4925 * @cfg {number} [width=320] Width of popup in pixels
4926 * @cfg {number} [height] Height of popup in pixels. Omit to use the automatic height.
4927 * @cfg {boolean} [anchor=true] Show anchor pointing to origin of popup
4928 * @cfg {string} [position='below'] Where to position the popup relative to $floatableContainer
4929 * 'above': Put popup above $floatableContainer; anchor points down to the horizontal center
4930 * of $floatableContainer
4931 * 'below': Put popup below $floatableContainer; anchor points up to the horizontal center
4932 * of $floatableContainer
4933 * 'before': Put popup to the left (LTR) / right (RTL) of $floatableContainer; anchor points
4934 * endwards (right/left) to the vertical center of $floatableContainer
4935 * 'after': Put popup to the right (LTR) / left (RTL) of $floatableContainer; anchor points
4936 * startwards (left/right) to the vertical center of $floatableContainer
4937 * @cfg {string} [align='center'] How to align the popup to $floatableContainer
4938 * 'forwards': If position is above/below, move the popup as far endwards (right in LTR, left in RTL)
4939 * as possible while still keeping the anchor within the popup;
4940 * if position is before/after, move the popup as far downwards as possible.
4941 * 'backwards': If position is above/below, move the popup as far startwards (left in LTR, right in RTL)
4942 * as possible while still keeping the anchor within the popup;
4943 * if position in before/after, move the popup as far upwards as possible.
4944 * 'center': Horizontally (if position is above/below) or vertically (before/after) align the center
4945 * of the popup with the center of $floatableContainer.
4946 * 'force-left': Alias for 'forwards' in LTR and 'backwards' in RTL
4947 * 'force-right': Alias for 'backwards' in RTL and 'forwards' in LTR
4948 * @cfg {jQuery} [$container] Constrain the popup to the boundaries of the specified container.
4949 * See the [OOjs UI docs on MediaWiki][3] for an example.
4950 * [3]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#containerExample
4951 * @cfg {number} [containerPadding=10] Padding between the popup and its container, specified as a number of pixels.
4952 * @cfg {jQuery} [$content] Content to append to the popup's body
4953 * @cfg {jQuery} [$footer] Content to append to the popup's footer
4954 * @cfg {boolean} [autoClose=false] Automatically close the popup when it loses focus.
4955 * @cfg {jQuery} [$autoCloseIgnore] Elements that will not close the popup when clicked.
4956 * This config option is only relevant if #autoClose is set to `true`. See the [OOjs UI docs on MediaWiki][2]
4958 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#autocloseExample
4959 * @cfg {boolean} [head=false] Show a popup header that contains a #label (if specified) and close
4961 * @cfg {boolean} [padded=false] Add padding to the popup's body
4963 OO
.ui
.PopupWidget
= function OoUiPopupWidget( config
) {
4964 // Configuration initialization
4965 config
= config
|| {};
4967 // Parent constructor
4968 OO
.ui
.PopupWidget
.parent
.call( this, config
);
4970 // Properties (must be set before ClippableElement constructor call)
4971 this.$body
= $( '<div>' );
4972 this.$popup
= $( '<div>' );
4974 // Mixin constructors
4975 OO
.ui
.mixin
.LabelElement
.call( this, config
);
4976 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, {
4977 $clippable
: this.$body
,
4978 $clippableContainer
: this.$popup
4980 OO
.ui
.mixin
.FloatableElement
.call( this, config
);
4983 this.$anchor
= $( '<div>' );
4984 // If undefined, will be computed lazily in computePosition()
4985 this.$container
= config
.$container
;
4986 this.containerPadding
= config
.containerPadding
!== undefined ? config
.containerPadding
: 10;
4987 this.autoClose
= !!config
.autoClose
;
4988 this.$autoCloseIgnore
= config
.$autoCloseIgnore
;
4989 this.transitionTimeout
= null;
4990 this.anchored
= false;
4991 this.width
= config
.width
!== undefined ? config
.width
: 320;
4992 this.height
= config
.height
!== undefined ? config
.height
: null;
4993 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
4994 this.onDocumentKeyDownHandler
= this.onDocumentKeyDown
.bind( this );
4997 this.toggleAnchor( config
.anchor
=== undefined || config
.anchor
);
4998 this.setAlignment( config
.align
|| 'center' );
4999 this.setPosition( config
.position
|| 'below' );
5000 this.$body
.addClass( 'oo-ui-popupWidget-body' );
5001 this.$anchor
.addClass( 'oo-ui-popupWidget-anchor' );
5003 .addClass( 'oo-ui-popupWidget-popup' )
5004 .append( this.$body
);
5006 .addClass( 'oo-ui-popupWidget' )
5007 .append( this.$popup
, this.$anchor
);
5008 // Move content, which was added to #$element by OO.ui.Widget, to the body
5009 // FIXME This is gross, we should use '$body' or something for the config
5010 if ( config
.$content
instanceof jQuery
) {
5011 this.$body
.append( config
.$content
);
5014 if ( config
.padded
) {
5015 this.$body
.addClass( 'oo-ui-popupWidget-body-padded' );
5018 if ( config
.head
) {
5019 this.closeButton
= new OO
.ui
.ButtonWidget( { framed
: false, icon
: 'close' } );
5020 this.closeButton
.connect( this, { click
: 'onCloseButtonClick' } );
5021 this.$head
= $( '<div>' )
5022 .addClass( 'oo-ui-popupWidget-head' )
5023 .append( this.$label
, this.closeButton
.$element
);
5024 this.$popup
.prepend( this.$head
);
5027 if ( config
.$footer
) {
5028 this.$footer
= $( '<div>' )
5029 .addClass( 'oo-ui-popupWidget-footer' )
5030 .append( config
.$footer
);
5031 this.$popup
.append( this.$footer
);
5034 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
5035 // that reference properties not initialized at that time of parent class construction
5036 // TODO: Find a better way to handle post-constructor setup
5037 this.visible
= false;
5038 this.$element
.addClass( 'oo-ui-element-hidden' );
5043 OO
.inheritClass( OO
.ui
.PopupWidget
, OO
.ui
.Widget
);
5044 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.LabelElement
);
5045 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.ClippableElement
);
5046 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.FloatableElement
);
5053 * The popup is ready: it is visible and has been positioned and clipped.
5059 * Handles mouse down events.
5062 * @param {MouseEvent} e Mouse down event
5064 OO
.ui
.PopupWidget
.prototype.onMouseDown = function ( e
) {
5067 !OO
.ui
.contains( this.$element
.add( this.$autoCloseIgnore
).get(), e
.target
, true )
5069 this.toggle( false );
5074 * Bind mouse down listener.
5078 OO
.ui
.PopupWidget
.prototype.bindMouseDownListener = function () {
5079 // Capture clicks outside popup
5080 this.getElementWindow().addEventListener( 'mousedown', this.onMouseDownHandler
, true );
5084 * Handles close button click events.
5088 OO
.ui
.PopupWidget
.prototype.onCloseButtonClick = function () {
5089 if ( this.isVisible() ) {
5090 this.toggle( false );
5095 * Unbind mouse down listener.
5099 OO
.ui
.PopupWidget
.prototype.unbindMouseDownListener = function () {
5100 this.getElementWindow().removeEventListener( 'mousedown', this.onMouseDownHandler
, true );
5104 * Handles key down events.
5107 * @param {KeyboardEvent} e Key down event
5109 OO
.ui
.PopupWidget
.prototype.onDocumentKeyDown = function ( e
) {
5111 e
.which
=== OO
.ui
.Keys
.ESCAPE
&&
5114 this.toggle( false );
5116 e
.stopPropagation();
5121 * Bind key down listener.
5125 OO
.ui
.PopupWidget
.prototype.bindKeyDownListener = function () {
5126 this.getElementWindow().addEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
5130 * Unbind key down listener.
5134 OO
.ui
.PopupWidget
.prototype.unbindKeyDownListener = function () {
5135 this.getElementWindow().removeEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
5139 * Show, hide, or toggle the visibility of the anchor.
5141 * @param {boolean} [show] Show anchor, omit to toggle
5143 OO
.ui
.PopupWidget
.prototype.toggleAnchor = function ( show
) {
5144 show
= show
=== undefined ? !this.anchored
: !!show
;
5146 if ( this.anchored
!== show
) {
5148 this.$element
.addClass( 'oo-ui-popupWidget-anchored' );
5149 this.$element
.addClass( 'oo-ui-popupWidget-anchored-' + this.anchorEdge
);
5151 this.$element
.removeClass( 'oo-ui-popupWidget-anchored' );
5152 this.$element
.removeClass( 'oo-ui-popupWidget-anchored-' + this.anchorEdge
);
5154 this.anchored
= show
;
5158 * Change which edge the anchor appears on.
5160 * @param {string} edge 'top', 'bottom', 'start' or 'end'
5162 OO
.ui
.PopupWidget
.prototype.setAnchorEdge = function ( edge
) {
5163 if ( [ 'top', 'bottom', 'start', 'end' ].indexOf( edge
) === -1 ) {
5164 throw new Error( 'Invalid value for edge: ' + edge
);
5166 if ( this.anchorEdge
!== null ) {
5167 this.$element
.removeClass( 'oo-ui-popupWidget-anchored-' + this.anchorEdge
);
5169 this.anchorEdge
= edge
;
5170 if ( this.anchored
) {
5171 this.$element
.addClass( 'oo-ui-popupWidget-anchored-' + edge
);
5176 * Check if the anchor is visible.
5178 * @return {boolean} Anchor is visible
5180 OO
.ui
.PopupWidget
.prototype.hasAnchor = function () {
5181 return this.anchored
;
5185 * Toggle visibility of the popup. The popup is initially hidden and must be shown by calling
5186 * `.toggle( true )` after its #$element is attached to the DOM.
5188 * Do not show the popup while it is not attached to the DOM. The calculations required to display
5189 * it in the right place and with the right dimensions only work correctly while it is attached.
5190 * Side-effects may include broken interface and exceptions being thrown. This wasn't always
5191 * strictly enforced, so currently it only generates a warning in the browser console.
5196 OO
.ui
.PopupWidget
.prototype.toggle = function ( show
) {
5198 show
= show
=== undefined ? !this.isVisible() : !!show
;
5200 change
= show
!== this.isVisible();
5202 if ( show
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
5203 OO
.ui
.warnDeprecation( 'PopupWidget#toggle: Before calling this method, the popup must be attached to the DOM.' );
5204 this.warnedUnattached
= true;
5206 if ( show
&& !this.$floatableContainer
&& this.isElementAttached() ) {
5207 // Fall back to the parent node if the floatableContainer is not set
5208 this.setFloatableContainer( this.$element
.parent() );
5212 OO
.ui
.PopupWidget
.parent
.prototype.toggle
.call( this, show
);
5215 this.togglePositioning( show
&& !!this.$floatableContainer
);
5218 if ( this.autoClose
) {
5219 this.bindMouseDownListener();
5220 this.bindKeyDownListener();
5222 this.updateDimensions();
5223 this.toggleClipping( true );
5224 this.emit( 'ready' );
5226 this.toggleClipping( false );
5227 if ( this.autoClose
) {
5228 this.unbindMouseDownListener();
5229 this.unbindKeyDownListener();
5238 * Set the size of the popup.
5240 * Changing the size may also change the popup's position depending on the alignment.
5242 * @param {number} width Width in pixels
5243 * @param {number} height Height in pixels
5244 * @param {boolean} [transition=false] Use a smooth transition
5247 OO
.ui
.PopupWidget
.prototype.setSize = function ( width
, height
, transition
) {
5249 this.height
= height
!== undefined ? height
: null;
5250 if ( this.isVisible() ) {
5251 this.updateDimensions( transition
);
5256 * Update the size and position.
5258 * Only use this to keep the popup properly anchored. Use #setSize to change the size, and this will
5259 * be called automatically.
5261 * @param {boolean} [transition=false] Use a smooth transition
5264 OO
.ui
.PopupWidget
.prototype.updateDimensions = function ( transition
) {
5267 // Prevent transition from being interrupted
5268 clearTimeout( this.transitionTimeout
);
5270 // Enable transition
5271 this.$element
.addClass( 'oo-ui-popupWidget-transitioning' );
5277 // Prevent transitioning after transition is complete
5278 this.transitionTimeout
= setTimeout( function () {
5279 widget
.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
5282 // Prevent transitioning immediately
5283 this.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
5290 OO
.ui
.PopupWidget
.prototype.computePosition = function () {
5291 var direction
, align
, vertical
, start
, end
, near
, far
, sizeProp
, popupSize
, anchorSize
, anchorPos
,
5292 anchorOffset
, anchorMargin
, parentPosition
, positionProp
, positionAdjustment
, floatablePos
,
5293 offsetParentPos
, containerPos
,
5295 anchorCss
= { left
: '', right
: '', top
: '', bottom
: '' },
5298 'force-left': 'backwards',
5299 'force-right': 'forwards'
5302 'force-left': 'forwards',
5303 'force-right': 'backwards'
5315 backwards
: this.anchored
? 'before' : 'end'
5323 if ( !this.$container
) {
5324 // Lazy-initialize $container if not specified in constructor
5325 this.$container
= $( this.getClosestScrollableElementContainer() );
5327 direction
= this.$container
.css( 'direction' );
5329 // Set height and width before we do anything else, since it might cause our measurements
5330 // to change (e.g. due to scrollbars appearing or disappearing), and it also affects centering
5333 height
: this.height
!== null ? this.height
: 'auto'
5336 align
= alignMap
[ direction
][ this.align
] || this.align
;
5337 // If the popup is positioned before or after, then the anchor positioning is vertical, otherwise horizontal
5338 vertical
= this.popupPosition
=== 'before' || this.popupPosition
=== 'after';
5339 start
= vertical
? 'top' : ( direction
=== 'rtl' ? 'right' : 'left' );
5340 end
= vertical
? 'bottom' : ( direction
=== 'rtl' ? 'left' : 'right' );
5341 near
= vertical
? 'top' : 'left';
5342 far
= vertical
? 'bottom' : 'right';
5343 sizeProp
= vertical
? 'Height' : 'Width';
5344 popupSize
= vertical
? ( this.height
|| this.$popup
.height() ) : this.width
;
5346 this.setAnchorEdge( anchorEdgeMap
[ this.popupPosition
] );
5347 this.horizontalPosition
= vertical
? this.popupPosition
: hPosMap
[ align
];
5348 this.verticalPosition
= vertical
? vPosMap
[ align
] : this.popupPosition
;
5351 parentPosition
= OO
.ui
.mixin
.FloatableElement
.prototype.computePosition
.call( this );
5352 // Find out which property FloatableElement used for positioning, and adjust that value
5353 positionProp
= vertical
?
5354 ( parentPosition
.top
!== '' ? 'top' : 'bottom' ) :
5355 ( parentPosition
.left
!== '' ? 'left' : 'right' );
5357 // Figure out where the near and far edges of the popup and $floatableContainer are
5358 floatablePos
= this.$floatableContainer
.offset();
5359 floatablePos
[ far
] = floatablePos
[ near
] + this.$floatableContainer
[ 'outer' + sizeProp
]();
5360 // Measure where the offsetParent is and compute our position based on that and parentPosition
5361 offsetParentPos
= this.$element
.offsetParent().offset();
5363 if ( positionProp
=== near
) {
5364 popupPos
[ near
] = offsetParentPos
[ near
] + parentPosition
[ near
];
5365 popupPos
[ far
] = popupPos
[ near
] + popupSize
;
5367 popupPos
[ far
] = offsetParentPos
[ near
] +
5368 this.$element
.offsetParent()[ 'inner' + sizeProp
]() - parentPosition
[ far
];
5369 popupPos
[ near
] = popupPos
[ far
] - popupSize
;
5372 if ( this.anchored
) {
5373 // Position the anchor (which is positioned relative to the popup) to point to $floatableContainer
5374 anchorPos
= ( floatablePos
[ start
] + floatablePos
[ end
] ) / 2;
5375 anchorOffset
= ( start
=== far
? -1 : 1 ) * ( anchorPos
- popupPos
[ start
] );
5377 // If the anchor is less than 2*anchorSize from either edge, move the popup to make more space
5378 // this.$anchor.width()/height() returns 0 because of the CSS trickery we use, so use scrollWidth/Height
5379 anchorSize
= this.$anchor
[ 0 ][ 'scroll' + sizeProp
];
5380 anchorMargin
= parseFloat( this.$anchor
.css( 'margin-' + start
) );
5381 if ( anchorOffset
+ anchorMargin
< 2 * anchorSize
) {
5382 // Not enough space for the anchor on the start side; pull the popup startwards
5383 positionAdjustment
= ( positionProp
=== start
? -1 : 1 ) *
5384 ( 2 * anchorSize
- ( anchorOffset
+ anchorMargin
) );
5385 } else if ( anchorOffset
+ anchorMargin
> popupSize
- 2 * anchorSize
) {
5386 // Not enough space for the anchor on the end side; pull the popup endwards
5387 positionAdjustment
= ( positionProp
=== end
? -1 : 1 ) *
5388 ( anchorOffset
+ anchorMargin
- ( popupSize
- 2 * anchorSize
) );
5390 positionAdjustment
= 0;
5393 positionAdjustment
= 0;
5396 // Check if the popup will go beyond the edge of this.$container
5397 containerPos
= this.$container
.offset();
5398 containerPos
[ far
] = containerPos
[ near
] + this.$container
[ 'inner' + sizeProp
]();
5399 // Take into account how much the popup will move because of the adjustments we're going to make
5400 popupPos
[ near
] += ( positionProp
=== near
? 1 : -1 ) * positionAdjustment
;
5401 popupPos
[ far
] += ( positionProp
=== near
? 1 : -1 ) * positionAdjustment
;
5402 if ( containerPos
[ near
] + this.containerPadding
> popupPos
[ near
] ) {
5403 // Popup goes beyond the near (left/top) edge, move it to the right/bottom
5404 positionAdjustment
+= ( positionProp
=== near
? 1 : -1 ) *
5405 ( containerPos
[ near
] + this.containerPadding
- popupPos
[ near
] );
5406 } else if ( containerPos
[ far
] - this.containerPadding
< popupPos
[ far
] ) {
5407 // Popup goes beyond the far (right/bottom) edge, move it to the left/top
5408 positionAdjustment
+= ( positionProp
=== far
? 1 : -1 ) *
5409 ( popupPos
[ far
] - ( containerPos
[ far
] - this.containerPadding
) );
5412 if ( this.anchored
) {
5413 // Adjust anchorOffset for positionAdjustment
5414 anchorOffset
+= ( positionProp
=== start
? -1 : 1 ) * positionAdjustment
;
5416 // Position the anchor
5417 anchorCss
[ start
] = anchorOffset
;
5418 this.$anchor
.css( anchorCss
);
5421 // Move the popup if needed
5422 parentPosition
[ positionProp
] += positionAdjustment
;
5424 return parentPosition
;
5428 * Set popup alignment
5430 * @param {string} [align=center] Alignment of the popup, `center`, `force-left`, `force-right`,
5431 * `backwards` or `forwards`.
5433 OO
.ui
.PopupWidget
.prototype.setAlignment = function ( align
) {
5434 // Validate alignment
5435 if ( [ 'force-left', 'force-right', 'backwards', 'forwards', 'center' ].indexOf( align
) > -1 ) {
5438 this.align
= 'center';
5444 * Get popup alignment
5446 * @return {string} Alignment of the popup, `center`, `force-left`, `force-right`,
5447 * `backwards` or `forwards`.
5449 OO
.ui
.PopupWidget
.prototype.getAlignment = function () {
5454 * Change the positioning of the popup.
5456 * @param {string} position 'above', 'below', 'before' or 'after'
5458 OO
.ui
.PopupWidget
.prototype.setPosition = function ( position
) {
5459 if ( [ 'above', 'below', 'before', 'after' ].indexOf( position
) === -1 ) {
5462 this.popupPosition
= position
;
5467 * Get popup positioning.
5469 * @return {string} 'above', 'below', 'before' or 'after'
5471 OO
.ui
.PopupWidget
.prototype.getPosition = function () {
5472 return this.popupPosition
;
5476 * Get an ID of the body element, this can be used as the
5477 * `aria-describedby` attribute for an input field.
5479 * @return {string} The ID of the body element
5481 OO
.ui
.PopupWidget
.prototype.getBodyId = function () {
5482 var id
= this.$body
.attr( 'id' );
5483 if ( id
=== undefined ) {
5484 id
= OO
.ui
.generateElementId();
5485 this.$body
.attr( 'id', id
);
5491 * PopupElement is mixed into other classes to generate a {@link OO.ui.PopupWidget popup widget}.
5492 * A popup is a container for content. It is overlaid and positioned absolutely. By default, each
5493 * popup has an anchor, which is an arrow-like protrusion that points toward the popup’s origin.
5494 * See {@link OO.ui.PopupWidget PopupWidget} for an example.
5500 * @param {Object} [config] Configuration options
5501 * @cfg {Object} [popup] Configuration to pass to popup
5502 * @cfg {boolean} [popup.autoClose=true] Popup auto-closes when it loses focus
5504 OO
.ui
.mixin
.PopupElement
= function OoUiMixinPopupElement( config
) {
5505 // Configuration initialization
5506 config
= config
|| {};
5509 this.popup
= new OO
.ui
.PopupWidget( $.extend(
5512 $floatableContainer
: this.$element
5516 $autoCloseIgnore
: this.$element
.add( config
.popup
&& config
.popup
.$autoCloseIgnore
)
5526 * @return {OO.ui.PopupWidget} Popup widget
5528 OO
.ui
.mixin
.PopupElement
.prototype.getPopup = function () {
5533 * PopupButtonWidgets toggle the visibility of a contained {@link OO.ui.PopupWidget PopupWidget},
5534 * which is used to display additional information or options.
5537 * // Example of a popup button.
5538 * var popupButton = new OO.ui.PopupButtonWidget( {
5539 * label: 'Popup button with options',
5542 * $content: $( '<p>Additional options here.</p>' ),
5544 * align: 'force-left'
5547 * // Append the button to the DOM.
5548 * $( 'body' ).append( popupButton.$element );
5551 * @extends OO.ui.ButtonWidget
5552 * @mixins OO.ui.mixin.PopupElement
5555 * @param {Object} [config] Configuration options
5556 * @cfg {jQuery} [$overlay] Render the popup into a separate layer. This configuration is useful in cases where
5557 * the expanded popup is larger than its containing `<div>`. The specified overlay layer is usually on top of the
5558 * containing `<div>` and has a larger area. By default, the popup uses relative positioning.
5559 * See <https://www.mediawiki.org/wiki/OOjs_UI/Concepts#Overlays>.
5561 OO
.ui
.PopupButtonWidget
= function OoUiPopupButtonWidget( config
) {
5562 // Configuration initialization
5563 config
= config
|| {};
5565 // Parent constructor
5566 OO
.ui
.PopupButtonWidget
.parent
.call( this, config
);
5568 // Mixin constructors
5569 OO
.ui
.mixin
.PopupElement
.call( this, config
);
5572 this.$overlay
= config
.$overlay
|| this.$element
;
5575 this.connect( this, { click
: 'onAction' } );
5579 .addClass( 'oo-ui-popupButtonWidget' )
5580 .attr( 'aria-haspopup', 'true' );
5582 .addClass( 'oo-ui-popupButtonWidget-popup' )
5583 .toggleClass( 'oo-ui-popupButtonWidget-framed-popup', this.isFramed() )
5584 .toggleClass( 'oo-ui-popupButtonWidget-frameless-popup', !this.isFramed() );
5585 this.$overlay
.append( this.popup
.$element
);
5590 OO
.inheritClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.ButtonWidget
);
5591 OO
.mixinClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.mixin
.PopupElement
);
5596 * Handle the button action being triggered.
5600 OO
.ui
.PopupButtonWidget
.prototype.onAction = function () {
5601 this.popup
.toggle();
5605 * Mixin for OO.ui.Widget subclasses to provide OO.ui.mixin.GroupElement.
5607 * Use together with OO.ui.mixin.ItemWidget to make disabled state inheritable.
5612 * @mixins OO.ui.mixin.GroupElement
5615 * @param {Object} [config] Configuration options
5617 OO
.ui
.mixin
.GroupWidget
= function OoUiMixinGroupWidget( config
) {
5618 // Mixin constructors
5619 OO
.ui
.mixin
.GroupElement
.call( this, config
);
5624 OO
.mixinClass( OO
.ui
.mixin
.GroupWidget
, OO
.ui
.mixin
.GroupElement
);
5629 * Set the disabled state of the widget.
5631 * This will also update the disabled state of child widgets.
5633 * @param {boolean} disabled Disable widget
5636 OO
.ui
.mixin
.GroupWidget
.prototype.setDisabled = function ( disabled
) {
5640 // Note: Calling #setDisabled this way assumes this is mixed into an OO.ui.Widget
5641 OO
.ui
.Widget
.prototype.setDisabled
.call( this, disabled
);
5643 // During construction, #setDisabled is called before the OO.ui.mixin.GroupElement constructor
5645 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5646 this.items
[ i
].updateDisabled();
5654 * Mixin for widgets used as items in widgets that mix in OO.ui.mixin.GroupWidget.
5656 * Item widgets have a reference to a OO.ui.mixin.GroupWidget while they are attached to the group. This
5657 * allows bidirectional communication.
5659 * Use together with OO.ui.mixin.GroupWidget to make disabled state inheritable.
5667 OO
.ui
.mixin
.ItemWidget
= function OoUiMixinItemWidget() {
5674 * Check if widget is disabled.
5676 * Checks parent if present, making disabled state inheritable.
5678 * @return {boolean} Widget is disabled
5680 OO
.ui
.mixin
.ItemWidget
.prototype.isDisabled = function () {
5681 return this.disabled
||
5682 ( this.elementGroup
instanceof OO
.ui
.Widget
&& this.elementGroup
.isDisabled() );
5686 * Set group element is in.
5688 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
5691 OO
.ui
.mixin
.ItemWidget
.prototype.setElementGroup = function ( group
) {
5693 // Note: Calling #setElementGroup this way assumes this is mixed into an OO.ui.Element
5694 OO
.ui
.Element
.prototype.setElementGroup
.call( this, group
);
5696 // Initialize item disabled states
5697 this.updateDisabled();
5703 * OptionWidgets are special elements that can be selected and configured with data. The
5704 * data is often unique for each option, but it does not have to be. OptionWidgets are used
5705 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
5706 * and examples, please see the [OOjs UI documentation on MediaWiki][1].
5708 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5711 * @extends OO.ui.Widget
5712 * @mixins OO.ui.mixin.ItemWidget
5713 * @mixins OO.ui.mixin.LabelElement
5714 * @mixins OO.ui.mixin.FlaggedElement
5715 * @mixins OO.ui.mixin.AccessKeyedElement
5718 * @param {Object} [config] Configuration options
5720 OO
.ui
.OptionWidget
= function OoUiOptionWidget( config
) {
5721 // Configuration initialization
5722 config
= config
|| {};
5724 // Parent constructor
5725 OO
.ui
.OptionWidget
.parent
.call( this, config
);
5727 // Mixin constructors
5728 OO
.ui
.mixin
.ItemWidget
.call( this );
5729 OO
.ui
.mixin
.LabelElement
.call( this, config
);
5730 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
5731 OO
.ui
.mixin
.AccessKeyedElement
.call( this, config
);
5734 this.selected
= false;
5735 this.highlighted
= false;
5736 this.pressed
= false;
5740 .data( 'oo-ui-optionWidget', this )
5741 // Allow programmatic focussing (and by accesskey), but not tabbing
5742 .attr( 'tabindex', '-1' )
5743 .attr( 'role', 'option' )
5744 .attr( 'aria-selected', 'false' )
5745 .addClass( 'oo-ui-optionWidget' )
5746 .append( this.$label
);
5751 OO
.inheritClass( OO
.ui
.OptionWidget
, OO
.ui
.Widget
);
5752 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.ItemWidget
);
5753 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.LabelElement
);
5754 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.FlaggedElement
);
5755 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
5757 /* Static Properties */
5760 * Whether this option can be selected. See #setSelected.
5764 * @property {boolean}
5766 OO
.ui
.OptionWidget
.static.selectable
= true;
5769 * Whether this option can be highlighted. See #setHighlighted.
5773 * @property {boolean}
5775 OO
.ui
.OptionWidget
.static.highlightable
= true;
5778 * Whether this option can be pressed. See #setPressed.
5782 * @property {boolean}
5784 OO
.ui
.OptionWidget
.static.pressable
= true;
5787 * Whether this option will be scrolled into view when it is selected.
5791 * @property {boolean}
5793 OO
.ui
.OptionWidget
.static.scrollIntoViewOnSelect
= false;
5798 * Check if the option can be selected.
5800 * @return {boolean} Item is selectable
5802 OO
.ui
.OptionWidget
.prototype.isSelectable = function () {
5803 return this.constructor.static.selectable
&& !this.isDisabled() && this.isVisible();
5807 * Check if the option can be highlighted. A highlight indicates that the option
5808 * may be selected when a user presses enter or clicks. Disabled items cannot
5811 * @return {boolean} Item is highlightable
5813 OO
.ui
.OptionWidget
.prototype.isHighlightable = function () {
5814 return this.constructor.static.highlightable
&& !this.isDisabled() && this.isVisible();
5818 * Check if the option can be pressed. The pressed state occurs when a user mouses
5819 * down on an item, but has not yet let go of the mouse.
5821 * @return {boolean} Item is pressable
5823 OO
.ui
.OptionWidget
.prototype.isPressable = function () {
5824 return this.constructor.static.pressable
&& !this.isDisabled() && this.isVisible();
5828 * Check if the option is selected.
5830 * @return {boolean} Item is selected
5832 OO
.ui
.OptionWidget
.prototype.isSelected = function () {
5833 return this.selected
;
5837 * Check if the option is highlighted. A highlight indicates that the
5838 * item may be selected when a user presses enter or clicks.
5840 * @return {boolean} Item is highlighted
5842 OO
.ui
.OptionWidget
.prototype.isHighlighted = function () {
5843 return this.highlighted
;
5847 * Check if the option is pressed. The pressed state occurs when a user mouses
5848 * down on an item, but has not yet let go of the mouse. The item may appear
5849 * selected, but it will not be selected until the user releases the mouse.
5851 * @return {boolean} Item is pressed
5853 OO
.ui
.OptionWidget
.prototype.isPressed = function () {
5854 return this.pressed
;
5858 * Set the option’s selected state. In general, all modifications to the selection
5859 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
5860 * method instead of this method.
5862 * @param {boolean} [state=false] Select option
5865 OO
.ui
.OptionWidget
.prototype.setSelected = function ( state
) {
5866 if ( this.constructor.static.selectable
) {
5867 this.selected
= !!state
;
5869 .toggleClass( 'oo-ui-optionWidget-selected', state
)
5870 .attr( 'aria-selected', state
.toString() );
5871 if ( state
&& this.constructor.static.scrollIntoViewOnSelect
) {
5872 this.scrollElementIntoView();
5874 this.updateThemeClasses();
5880 * Set the option’s highlighted state. In general, all programmatic
5881 * modifications to the highlight should be handled by the
5882 * SelectWidget’s {@link OO.ui.SelectWidget#highlightItem highlightItem( [item] )}
5883 * method instead of this method.
5885 * @param {boolean} [state=false] Highlight option
5888 OO
.ui
.OptionWidget
.prototype.setHighlighted = function ( state
) {
5889 if ( this.constructor.static.highlightable
) {
5890 this.highlighted
= !!state
;
5891 this.$element
.toggleClass( 'oo-ui-optionWidget-highlighted', state
);
5892 this.updateThemeClasses();
5898 * Set the option’s pressed state. In general, all
5899 * programmatic modifications to the pressed state should be handled by the
5900 * SelectWidget’s {@link OO.ui.SelectWidget#pressItem pressItem( [item] )}
5901 * method instead of this method.
5903 * @param {boolean} [state=false] Press option
5906 OO
.ui
.OptionWidget
.prototype.setPressed = function ( state
) {
5907 if ( this.constructor.static.pressable
) {
5908 this.pressed
= !!state
;
5909 this.$element
.toggleClass( 'oo-ui-optionWidget-pressed', state
);
5910 this.updateThemeClasses();
5916 * Get text to match search strings against.
5918 * The default implementation returns the label text, but subclasses
5919 * can override this to provide more complex behavior.
5921 * @return {string|boolean} String to match search string against
5923 OO
.ui
.OptionWidget
.prototype.getMatchText = function () {
5924 var label
= this.getLabel();
5925 return typeof label
=== 'string' ? label
: this.$label
.text();
5929 * A SelectWidget is of a generic selection of options. The OOjs UI library contains several types of
5930 * select widgets, including {@link OO.ui.ButtonSelectWidget button selects},
5931 * {@link OO.ui.RadioSelectWidget radio selects}, and {@link OO.ui.MenuSelectWidget
5934 * This class should be used together with OO.ui.OptionWidget or OO.ui.DecoratedOptionWidget. For more
5935 * information, please see the [OOjs UI documentation on MediaWiki][1].
5938 * // Example of a select widget with three options
5939 * var select = new OO.ui.SelectWidget( {
5941 * new OO.ui.OptionWidget( {
5943 * label: 'Option One',
5945 * new OO.ui.OptionWidget( {
5947 * label: 'Option Two',
5949 * new OO.ui.OptionWidget( {
5951 * label: 'Option Three',
5955 * $( 'body' ).append( select.$element );
5957 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5961 * @extends OO.ui.Widget
5962 * @mixins OO.ui.mixin.GroupWidget
5965 * @param {Object} [config] Configuration options
5966 * @cfg {OO.ui.OptionWidget[]} [items] An array of options to add to the select.
5967 * Options are created with {@link OO.ui.OptionWidget OptionWidget} classes. See
5968 * the [OOjs UI documentation on MediaWiki] [2] for examples.
5969 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5971 OO
.ui
.SelectWidget
= function OoUiSelectWidget( config
) {
5972 // Configuration initialization
5973 config
= config
|| {};
5975 // Parent constructor
5976 OO
.ui
.SelectWidget
.parent
.call( this, config
);
5978 // Mixin constructors
5979 OO
.ui
.mixin
.GroupWidget
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
5982 this.pressed
= false;
5983 this.selecting
= null;
5984 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
5985 this.onMouseMoveHandler
= this.onMouseMove
.bind( this );
5986 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
5987 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
5988 this.keyPressBuffer
= '';
5989 this.keyPressBufferTimer
= null;
5990 this.blockMouseOverEvents
= 0;
5993 this.connect( this, {
5997 focusin
: this.onFocus
.bind( this ),
5998 mousedown
: this.onMouseDown
.bind( this ),
5999 mouseover
: this.onMouseOver
.bind( this ),
6000 mouseleave
: this.onMouseLeave
.bind( this )
6005 .addClass( 'oo-ui-selectWidget oo-ui-selectWidget-depressed' )
6006 .attr( 'role', 'listbox' );
6007 this.setFocusOwner( this.$element
);
6008 if ( Array
.isArray( config
.items
) ) {
6009 this.addItems( config
.items
);
6015 OO
.inheritClass( OO
.ui
.SelectWidget
, OO
.ui
.Widget
);
6016 OO
.mixinClass( OO
.ui
.SelectWidget
, OO
.ui
.mixin
.GroupWidget
);
6023 * A `highlight` event is emitted when the highlight is changed with the #highlightItem method.
6025 * @param {OO.ui.OptionWidget|null} item Highlighted item
6031 * A `press` event is emitted when the #pressItem method is used to programmatically modify the
6032 * pressed state of an option.
6034 * @param {OO.ui.OptionWidget|null} item Pressed item
6040 * A `select` event is emitted when the selection is modified programmatically with the #selectItem method.
6042 * @param {OO.ui.OptionWidget|null} item Selected item
6047 * A `choose` event is emitted when an item is chosen with the #chooseItem method.
6048 * @param {OO.ui.OptionWidget} item Chosen item
6054 * An `add` event is emitted when options are added to the select with the #addItems method.
6056 * @param {OO.ui.OptionWidget[]} items Added items
6057 * @param {number} index Index of insertion point
6063 * A `remove` event is emitted when options are removed from the select with the #clearItems
6064 * or #removeItems methods.
6066 * @param {OO.ui.OptionWidget[]} items Removed items
6072 * Handle focus events
6075 * @param {jQuery.Event} event
6077 OO
.ui
.SelectWidget
.prototype.onFocus = function ( event
) {
6079 if ( event
.target
=== this.$element
[ 0 ] ) {
6080 // This widget was focussed, e.g. by the user tabbing to it.
6081 // The styles for focus state depend on one of the items being selected.
6082 if ( !this.getSelectedItem() ) {
6083 item
= this.findFirstSelectableItem();
6086 if ( event
.target
.tabIndex
=== -1 ) {
6087 // One of the options got focussed (and the event bubbled up here).
6088 // They can't be tabbed to, but they can be activated using accesskeys.
6089 // OptionWidgets and focusable UI elements inside them have tabindex="-1" set.
6090 item
= this.findTargetItem( event
);
6092 // There is something actually user-focusable in one of the labels of the options, and the
6093 // user focussed it (e.g. by tabbing to it). Do nothing (especially, don't change the focus).
6099 if ( item
.constructor.static.highlightable
) {
6100 this.highlightItem( item
);
6102 this.selectItem( item
);
6106 if ( event
.target
!== this.$element
[ 0 ] ) {
6107 this.$focusOwner
.focus();
6112 * Handle mouse down events.
6115 * @param {jQuery.Event} e Mouse down event
6117 OO
.ui
.SelectWidget
.prototype.onMouseDown = function ( e
) {
6120 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
6121 this.togglePressed( true );
6122 item
= this.findTargetItem( e
);
6123 if ( item
&& item
.isSelectable() ) {
6124 this.pressItem( item
);
6125 this.selecting
= item
;
6126 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
6127 this.getElementDocument().addEventListener( 'mousemove', this.onMouseMoveHandler
, true );
6134 * Handle mouse up events.
6137 * @param {MouseEvent} e Mouse up event
6139 OO
.ui
.SelectWidget
.prototype.onMouseUp = function ( e
) {
6142 this.togglePressed( false );
6143 if ( !this.selecting
) {
6144 item
= this.findTargetItem( e
);
6145 if ( item
&& item
.isSelectable() ) {
6146 this.selecting
= item
;
6149 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
&& this.selecting
) {
6150 this.pressItem( null );
6151 this.chooseItem( this.selecting
);
6152 this.selecting
= null;
6155 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
6156 this.getElementDocument().removeEventListener( 'mousemove', this.onMouseMoveHandler
, true );
6162 * Handle mouse move events.
6165 * @param {MouseEvent} e Mouse move event
6167 OO
.ui
.SelectWidget
.prototype.onMouseMove = function ( e
) {
6170 if ( !this.isDisabled() && this.pressed
) {
6171 item
= this.findTargetItem( e
);
6172 if ( item
&& item
!== this.selecting
&& item
.isSelectable() ) {
6173 this.pressItem( item
);
6174 this.selecting
= item
;
6180 * Handle mouse over events.
6183 * @param {jQuery.Event} e Mouse over event
6185 OO
.ui
.SelectWidget
.prototype.onMouseOver = function ( e
) {
6187 if ( this.blockMouseOverEvents
) {
6190 if ( !this.isDisabled() ) {
6191 item
= this.findTargetItem( e
);
6192 this.highlightItem( item
&& item
.isHighlightable() ? item
: null );
6198 * Handle mouse leave events.
6201 * @param {jQuery.Event} e Mouse over event
6203 OO
.ui
.SelectWidget
.prototype.onMouseLeave = function () {
6204 if ( !this.isDisabled() ) {
6205 this.highlightItem( null );
6211 * Handle key down events.
6214 * @param {KeyboardEvent} e Key down event
6216 OO
.ui
.SelectWidget
.prototype.onKeyDown = function ( e
) {
6219 currentItem
= this.findHighlightedItem() || this.getSelectedItem();
6221 if ( !this.isDisabled() && this.isVisible() ) {
6222 switch ( e
.keyCode
) {
6223 case OO
.ui
.Keys
.ENTER
:
6224 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
6225 // Was only highlighted, now let's select it. No-op if already selected.
6226 this.chooseItem( currentItem
);
6231 case OO
.ui
.Keys
.LEFT
:
6232 this.clearKeyPressBuffer();
6233 nextItem
= this.findRelativeSelectableItem( currentItem
, -1 );
6236 case OO
.ui
.Keys
.DOWN
:
6237 case OO
.ui
.Keys
.RIGHT
:
6238 this.clearKeyPressBuffer();
6239 nextItem
= this.findRelativeSelectableItem( currentItem
, 1 );
6242 case OO
.ui
.Keys
.ESCAPE
:
6243 case OO
.ui
.Keys
.TAB
:
6244 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
6245 currentItem
.setHighlighted( false );
6247 this.unbindKeyDownListener();
6248 this.unbindKeyPressListener();
6249 // Don't prevent tabbing away / defocusing
6255 if ( nextItem
.constructor.static.highlightable
) {
6256 this.highlightItem( nextItem
);
6258 this.chooseItem( nextItem
);
6260 this.scrollItemIntoView( nextItem
);
6265 e
.stopPropagation();
6271 * Bind key down listener.
6275 OO
.ui
.SelectWidget
.prototype.bindKeyDownListener = function () {
6276 this.getElementWindow().addEventListener( 'keydown', this.onKeyDownHandler
, true );
6280 * Unbind key down listener.
6284 OO
.ui
.SelectWidget
.prototype.unbindKeyDownListener = function () {
6285 this.getElementWindow().removeEventListener( 'keydown', this.onKeyDownHandler
, true );
6289 * Scroll item into view, preventing spurious mouse highlight actions from happening.
6291 * @param {OO.ui.OptionWidget} item Item to scroll into view
6293 OO
.ui
.SelectWidget
.prototype.scrollItemIntoView = function ( item
) {
6295 // Chromium's Blink engine will generate spurious 'mouseover' events during programmatic scrolling
6296 // and around 100-150 ms after it is finished.
6297 this.blockMouseOverEvents
++;
6298 item
.scrollElementIntoView().done( function () {
6299 setTimeout( function () {
6300 widget
.blockMouseOverEvents
--;
6306 * Clear the key-press buffer
6310 OO
.ui
.SelectWidget
.prototype.clearKeyPressBuffer = function () {
6311 if ( this.keyPressBufferTimer
) {
6312 clearTimeout( this.keyPressBufferTimer
);
6313 this.keyPressBufferTimer
= null;
6315 this.keyPressBuffer
= '';
6319 * Handle key press events.
6322 * @param {KeyboardEvent} e Key press event
6324 OO
.ui
.SelectWidget
.prototype.onKeyPress = function ( e
) {
6325 var c
, filter
, item
;
6327 if ( !e
.charCode
) {
6328 if ( e
.keyCode
=== OO
.ui
.Keys
.BACKSPACE
&& this.keyPressBuffer
!== '' ) {
6329 this.keyPressBuffer
= this.keyPressBuffer
.substr( 0, this.keyPressBuffer
.length
- 1 );
6334 if ( String
.fromCodePoint
) {
6335 c
= String
.fromCodePoint( e
.charCode
);
6337 c
= String
.fromCharCode( e
.charCode
);
6340 if ( this.keyPressBufferTimer
) {
6341 clearTimeout( this.keyPressBufferTimer
);
6343 this.keyPressBufferTimer
= setTimeout( this.clearKeyPressBuffer
.bind( this ), 1500 );
6345 item
= this.findHighlightedItem() || this.getSelectedItem();
6347 if ( this.keyPressBuffer
=== c
) {
6348 // Common (if weird) special case: typing "xxxx" will cycle through all
6349 // the items beginning with "x".
6351 item
= this.findRelativeSelectableItem( item
, 1 );
6354 this.keyPressBuffer
+= c
;
6357 filter
= this.getItemMatcher( this.keyPressBuffer
, false );
6358 if ( !item
|| !filter( item
) ) {
6359 item
= this.findRelativeSelectableItem( item
, 1, filter
);
6362 if ( this.isVisible() && item
.constructor.static.highlightable
) {
6363 this.highlightItem( item
);
6365 this.chooseItem( item
);
6367 this.scrollItemIntoView( item
);
6371 e
.stopPropagation();
6375 * Get a matcher for the specific string
6378 * @param {string} s String to match against items
6379 * @param {boolean} [exact=false] Only accept exact matches
6380 * @return {Function} function ( OO.ui.OptionWidget ) => boolean
6382 OO
.ui
.SelectWidget
.prototype.getItemMatcher = function ( s
, exact
) {
6385 if ( s
.normalize
) {
6388 s
= exact
? s
.trim() : s
.replace( /^\s+/, '' );
6389 re
= '^\\s*' + s
.replace( /([\\{}()|.?*+\-^$[\]])/g, '\\$1' ).replace( /\s+/g, '\\s+' );
6393 re
= new RegExp( re
, 'i' );
6394 return function ( item
) {
6395 var matchText
= item
.getMatchText();
6396 if ( matchText
.normalize
) {
6397 matchText
= matchText
.normalize();
6399 return re
.test( matchText
);
6404 * Bind key press listener.
6408 OO
.ui
.SelectWidget
.prototype.bindKeyPressListener = function () {
6409 this.getElementWindow().addEventListener( 'keypress', this.onKeyPressHandler
, true );
6413 * Unbind key down listener.
6415 * If you override this, be sure to call this.clearKeyPressBuffer() from your
6420 OO
.ui
.SelectWidget
.prototype.unbindKeyPressListener = function () {
6421 this.getElementWindow().removeEventListener( 'keypress', this.onKeyPressHandler
, true );
6422 this.clearKeyPressBuffer();
6426 * Visibility change handler
6429 * @param {boolean} visible
6431 OO
.ui
.SelectWidget
.prototype.onToggle = function ( visible
) {
6433 this.clearKeyPressBuffer();
6438 * Get the closest item to a jQuery.Event.
6441 * @param {jQuery.Event} e
6442 * @return {OO.ui.OptionWidget|null} Outline item widget, `null` if none was found
6444 OO
.ui
.SelectWidget
.prototype.findTargetItem = function ( e
) {
6445 var $option
= $( e
.target
).closest( '.oo-ui-optionWidget' );
6446 if ( !$option
.closest( '.oo-ui-selectWidget' ).is( this.$element
) ) {
6449 return $option
.data( 'oo-ui-optionWidget' ) || null;
6453 * Get selected item.
6455 * @return {OO.ui.OptionWidget|null} Selected item, `null` if no item is selected
6457 OO
.ui
.SelectWidget
.prototype.getSelectedItem = function () {
6460 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6461 if ( this.items
[ i
].isSelected() ) {
6462 return this.items
[ i
];
6469 * Find highlighted item.
6471 * @return {OO.ui.OptionWidget|null} Highlighted item, `null` if no item is highlighted
6473 OO
.ui
.SelectWidget
.prototype.findHighlightedItem = function () {
6476 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6477 if ( this.items
[ i
].isHighlighted() ) {
6478 return this.items
[ i
];
6485 * Get highlighted item.
6487 * @deprecated 0.23.1 Use {@link #findHighlightedItem} instead.
6488 * @return {OO.ui.OptionWidget|null} Highlighted item, `null` if no item is highlighted
6490 OO
.ui
.SelectWidget
.prototype.getHighlightedItem = function () {
6491 OO
.ui
.warnDeprecation( 'SelectWidget#getHighlightedItem: Deprecated function. Use findHighlightedItem instead. See T76630.' );
6492 return this.findHighlightedItem();
6496 * Toggle pressed state.
6498 * Press is a state that occurs when a user mouses down on an item, but
6499 * has not yet let go of the mouse. The item may appear selected, but it will not be selected
6500 * until the user releases the mouse.
6502 * @param {boolean} pressed An option is being pressed
6504 OO
.ui
.SelectWidget
.prototype.togglePressed = function ( pressed
) {
6505 if ( pressed
=== undefined ) {
6506 pressed
= !this.pressed
;
6508 if ( pressed
!== this.pressed
) {
6510 .toggleClass( 'oo-ui-selectWidget-pressed', pressed
)
6511 .toggleClass( 'oo-ui-selectWidget-depressed', !pressed
);
6512 this.pressed
= pressed
;
6517 * Highlight an option. If the `item` param is omitted, no options will be highlighted
6518 * and any existing highlight will be removed. The highlight is mutually exclusive.
6520 * @param {OO.ui.OptionWidget} [item] Item to highlight, omit for no highlight
6524 OO
.ui
.SelectWidget
.prototype.highlightItem = function ( item
) {
6525 var i
, len
, highlighted
,
6528 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6529 highlighted
= this.items
[ i
] === item
;
6530 if ( this.items
[ i
].isHighlighted() !== highlighted
) {
6531 this.items
[ i
].setHighlighted( highlighted
);
6537 this.$focusOwner
.attr( 'aria-activedescendant', item
.getElementId() );
6539 this.$focusOwner
.removeAttr( 'aria-activedescendant' );
6541 this.emit( 'highlight', item
);
6548 * Fetch an item by its label.
6550 * @param {string} label Label of the item to select.
6551 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
6552 * @return {OO.ui.Element|null} Item with equivalent label, `null` if none exists
6554 OO
.ui
.SelectWidget
.prototype.getItemFromLabel = function ( label
, prefix
) {
6556 len
= this.items
.length
,
6557 filter
= this.getItemMatcher( label
, true );
6559 for ( i
= 0; i
< len
; i
++ ) {
6560 item
= this.items
[ i
];
6561 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
6568 filter
= this.getItemMatcher( label
, false );
6569 for ( i
= 0; i
< len
; i
++ ) {
6570 item
= this.items
[ i
];
6571 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
6587 * Programmatically select an option by its label. If the item does not exist,
6588 * all options will be deselected.
6590 * @param {string} [label] Label of the item to select.
6591 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
6595 OO
.ui
.SelectWidget
.prototype.selectItemByLabel = function ( label
, prefix
) {
6596 var itemFromLabel
= this.getItemFromLabel( label
, !!prefix
);
6597 if ( label
=== undefined || !itemFromLabel
) {
6598 return this.selectItem();
6600 return this.selectItem( itemFromLabel
);
6604 * Programmatically select an option by its data. If the `data` parameter is omitted,
6605 * or if the item does not exist, all options will be deselected.
6607 * @param {Object|string} [data] Value of the item to select, omit to deselect all
6611 OO
.ui
.SelectWidget
.prototype.selectItemByData = function ( data
) {
6612 var itemFromData
= this.getItemFromData( data
);
6613 if ( data
=== undefined || !itemFromData
) {
6614 return this.selectItem();
6616 return this.selectItem( itemFromData
);
6620 * Programmatically select an option by its reference. If the `item` parameter is omitted,
6621 * all options will be deselected.
6623 * @param {OO.ui.OptionWidget} [item] Item to select, omit to deselect all
6627 OO
.ui
.SelectWidget
.prototype.selectItem = function ( item
) {
6628 var i
, len
, selected
,
6631 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6632 selected
= this.items
[ i
] === item
;
6633 if ( this.items
[ i
].isSelected() !== selected
) {
6634 this.items
[ i
].setSelected( selected
);
6639 if ( item
&& !item
.constructor.static.highlightable
) {
6641 this.$focusOwner
.attr( 'aria-activedescendant', item
.getElementId() );
6643 this.$focusOwner
.removeAttr( 'aria-activedescendant' );
6646 this.emit( 'select', item
);
6655 * Press is a state that occurs when a user mouses down on an item, but has not
6656 * yet let go of the mouse. The item may appear selected, but it will not be selected until the user
6657 * releases the mouse.
6659 * @param {OO.ui.OptionWidget} [item] Item to press, omit to depress all
6663 OO
.ui
.SelectWidget
.prototype.pressItem = function ( item
) {
6664 var i
, len
, pressed
,
6667 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6668 pressed
= this.items
[ i
] === item
;
6669 if ( this.items
[ i
].isPressed() !== pressed
) {
6670 this.items
[ i
].setPressed( pressed
);
6675 this.emit( 'press', item
);
6684 * Note that ‘choose’ should never be modified programmatically. A user can choose
6685 * an option with the keyboard or mouse and it becomes selected. To select an item programmatically,
6686 * use the #selectItem method.
6688 * This method is identical to #selectItem, but may vary in subclasses that take additional action
6689 * when users choose an item with the keyboard or mouse.
6691 * @param {OO.ui.OptionWidget} item Item to choose
6695 OO
.ui
.SelectWidget
.prototype.chooseItem = function ( item
) {
6697 this.selectItem( item
);
6698 this.emit( 'choose', item
);
6705 * Find an option by its position relative to the specified item (or to the start of the option array,
6706 * if item is `null`). The direction in which to search through the option array is specified with a
6707 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
6708 * `null` if there are no options in the array.
6710 * @param {OO.ui.OptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
6711 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
6712 * @param {Function} [filter] Only consider items for which this function returns
6713 * true. Function takes an OO.ui.OptionWidget and returns a boolean.
6714 * @return {OO.ui.OptionWidget|null} Item at position, `null` if there are no items in the select
6716 OO
.ui
.SelectWidget
.prototype.findRelativeSelectableItem = function ( item
, direction
, filter
) {
6717 var currentIndex
, nextIndex
, i
,
6718 increase
= direction
> 0 ? 1 : -1,
6719 len
= this.items
.length
;
6721 if ( item
instanceof OO
.ui
.OptionWidget
) {
6722 currentIndex
= this.items
.indexOf( item
);
6723 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
6725 // If no item is selected and moving forward, start at the beginning.
6726 // If moving backward, start at the end.
6727 nextIndex
= direction
> 0 ? 0 : len
- 1;
6730 for ( i
= 0; i
< len
; i
++ ) {
6731 item
= this.items
[ nextIndex
];
6733 item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() &&
6734 ( !filter
|| filter( item
) )
6738 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
6744 * Get an option by its position relative to the specified item (or to the start of the option array,
6745 * if item is `null`). The direction in which to search through the option array is specified with a
6746 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
6747 * `null` if there are no options in the array.
6749 * @deprecated 0.23.1 Use {@link #findRelativeSelectableItem} instead
6750 * @param {OO.ui.OptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
6751 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
6752 * @param {Function} [filter] Only consider items for which this function returns
6753 * true. Function takes an OO.ui.OptionWidget and returns a boolean.
6754 * @return {OO.ui.OptionWidget|null} Item at position, `null` if there are no items in the select
6756 OO
.ui
.SelectWidget
.prototype.getRelativeSelectableItem = function ( item
, direction
, filter
) {
6757 OO
.ui
.warnDeprecation( 'SelectWidget#getRelativeSelectableItem: Deprecated function. Use findRelativeSelectableItem instead. See T76630.' );
6758 return this.findRelativeSelectableItem( item
, direction
, filter
);
6762 * Find the next selectable item or `null` if there are no selectable items.
6763 * Disabled options and menu-section markers and breaks are not selectable.
6765 * @return {OO.ui.OptionWidget|null} Item, `null` if there aren't any selectable items
6767 OO
.ui
.SelectWidget
.prototype.findFirstSelectableItem = function () {
6768 return this.findRelativeSelectableItem( null, 1 );
6772 * Get the next selectable item or `null` if there are no selectable items.
6773 * Disabled options and menu-section markers and breaks are not selectable.
6775 * @deprecated 0.23.1 Use {@link OO.ui.SelectWidget#findFirstSelectableItem} instead.
6776 * @return {OO.ui.OptionWidget|null} Item, `null` if there aren't any selectable items
6778 OO
.ui
.SelectWidget
.prototype.getFirstSelectableItem = function () {
6779 OO
.ui
.warnDeprecation( 'SelectWidget#getFirstSelectableItem: Deprecated function. Use findFirstSelectableItem instead. See T76630.' );
6780 return this.findFirstSelectableItem();
6784 * Add an array of options to the select. Optionally, an index number can be used to
6785 * specify an insertion point.
6787 * @param {OO.ui.OptionWidget[]} items Items to add
6788 * @param {number} [index] Index to insert items after
6792 OO
.ui
.SelectWidget
.prototype.addItems = function ( items
, index
) {
6794 OO
.ui
.mixin
.GroupWidget
.prototype.addItems
.call( this, items
, index
);
6796 // Always provide an index, even if it was omitted
6797 this.emit( 'add', items
, index
=== undefined ? this.items
.length
- items
.length
- 1 : index
);
6803 * Remove the specified array of options from the select. Options will be detached
6804 * from the DOM, not removed, so they can be reused later. To remove all options from
6805 * the select, you may wish to use the #clearItems method instead.
6807 * @param {OO.ui.OptionWidget[]} items Items to remove
6811 OO
.ui
.SelectWidget
.prototype.removeItems = function ( items
) {
6814 // Deselect items being removed
6815 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
6817 if ( item
.isSelected() ) {
6818 this.selectItem( null );
6823 OO
.ui
.mixin
.GroupWidget
.prototype.removeItems
.call( this, items
);
6825 this.emit( 'remove', items
);
6831 * Clear all options from the select. Options will be detached from the DOM, not removed,
6832 * so that they can be reused later. To remove a subset of options from the select, use
6833 * the #removeItems method.
6838 OO
.ui
.SelectWidget
.prototype.clearItems = function () {
6839 var items
= this.items
.slice();
6842 OO
.ui
.mixin
.GroupWidget
.prototype.clearItems
.call( this );
6845 this.selectItem( null );
6847 this.emit( 'remove', items
);
6853 * Set the DOM element which has focus while the user is interacting with this SelectWidget.
6855 * Currently this is just used to set `aria-activedescendant` on it.
6858 * @param {jQuery} $focusOwner
6860 OO
.ui
.SelectWidget
.prototype.setFocusOwner = function ( $focusOwner
) {
6861 this.$focusOwner
= $focusOwner
;
6865 * DecoratedOptionWidgets are {@link OO.ui.OptionWidget options} that can be configured
6866 * with an {@link OO.ui.mixin.IconElement icon} and/or {@link OO.ui.mixin.IndicatorElement indicator}.
6867 * This class is used with OO.ui.SelectWidget to create a selection of mutually exclusive
6868 * options. For more information about options and selects, please see the
6869 * [OOjs UI documentation on MediaWiki][1].
6872 * // Decorated options in a select widget
6873 * var select = new OO.ui.SelectWidget( {
6875 * new OO.ui.DecoratedOptionWidget( {
6877 * label: 'Option with icon',
6880 * new OO.ui.DecoratedOptionWidget( {
6882 * label: 'Option with indicator',
6887 * $( 'body' ).append( select.$element );
6889 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6892 * @extends OO.ui.OptionWidget
6893 * @mixins OO.ui.mixin.IconElement
6894 * @mixins OO.ui.mixin.IndicatorElement
6897 * @param {Object} [config] Configuration options
6899 OO
.ui
.DecoratedOptionWidget
= function OoUiDecoratedOptionWidget( config
) {
6900 // Parent constructor
6901 OO
.ui
.DecoratedOptionWidget
.parent
.call( this, config
);
6903 // Mixin constructors
6904 OO
.ui
.mixin
.IconElement
.call( this, config
);
6905 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
6909 .addClass( 'oo-ui-decoratedOptionWidget' )
6910 .prepend( this.$icon
)
6911 .append( this.$indicator
);
6916 OO
.inheritClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.OptionWidget
);
6917 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IconElement
);
6918 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IndicatorElement
);
6921 * MenuOptionWidget is an option widget that looks like a menu item. The class is used with
6922 * OO.ui.MenuSelectWidget to create a menu of mutually exclusive options. Please see
6923 * the [OOjs UI documentation on MediaWiki] [1] for more information.
6925 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
6928 * @extends OO.ui.DecoratedOptionWidget
6931 * @param {Object} [config] Configuration options
6933 OO
.ui
.MenuOptionWidget
= function OoUiMenuOptionWidget( config
) {
6934 // Parent constructor
6935 OO
.ui
.MenuOptionWidget
.parent
.call( this, config
);
6938 this.$element
.addClass( 'oo-ui-menuOptionWidget' );
6943 OO
.inheritClass( OO
.ui
.MenuOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
6945 /* Static Properties */
6951 OO
.ui
.MenuOptionWidget
.static.scrollIntoViewOnSelect
= true;
6954 * MenuSectionOptionWidgets are used inside {@link OO.ui.MenuSelectWidget menu select widgets} to group one or more related
6955 * {@link OO.ui.MenuOptionWidget menu options}. MenuSectionOptionWidgets cannot be highlighted or selected.
6958 * var myDropdown = new OO.ui.DropdownWidget( {
6961 * new OO.ui.MenuSectionOptionWidget( {
6964 * new OO.ui.MenuOptionWidget( {
6966 * label: 'Welsh Corgi'
6968 * new OO.ui.MenuOptionWidget( {
6970 * label: 'Standard Poodle'
6972 * new OO.ui.MenuSectionOptionWidget( {
6975 * new OO.ui.MenuOptionWidget( {
6982 * $( 'body' ).append( myDropdown.$element );
6985 * @extends OO.ui.DecoratedOptionWidget
6988 * @param {Object} [config] Configuration options
6990 OO
.ui
.MenuSectionOptionWidget
= function OoUiMenuSectionOptionWidget( config
) {
6991 // Parent constructor
6992 OO
.ui
.MenuSectionOptionWidget
.parent
.call( this, config
);
6995 this.$element
.addClass( 'oo-ui-menuSectionOptionWidget' )
6996 .removeAttr( 'role aria-selected' );
7001 OO
.inheritClass( OO
.ui
.MenuSectionOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
7003 /* Static Properties */
7009 OO
.ui
.MenuSectionOptionWidget
.static.selectable
= false;
7015 OO
.ui
.MenuSectionOptionWidget
.static.highlightable
= false;
7018 * MenuSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains options and
7019 * is used together with OO.ui.MenuOptionWidget. It is designed be used as part of another widget.
7020 * See {@link OO.ui.DropdownWidget DropdownWidget}, {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget},
7021 * and {@link OO.ui.mixin.LookupElement LookupElement} for examples of widgets that contain menus.
7022 * MenuSelectWidgets themselves are not instantiated directly, rather subclassed
7023 * and customized to be opened, closed, and displayed as needed.
7025 * By default, menus are clipped to the visible viewport and are not visible when a user presses the
7026 * mouse outside the menu.
7028 * Menus also have support for keyboard interaction:
7030 * - Enter/Return key: choose and select a menu option
7031 * - Up-arrow key: highlight the previous menu option
7032 * - Down-arrow key: highlight the next menu option
7033 * - Esc key: hide the menu
7035 * Unlike most widgets, MenuSelectWidget is initially hidden and must be shown by calling #toggle.
7037 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
7038 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
7041 * @extends OO.ui.SelectWidget
7042 * @mixins OO.ui.mixin.ClippableElement
7043 * @mixins OO.ui.mixin.FloatableElement
7046 * @param {Object} [config] Configuration options
7047 * @cfg {OO.ui.TextInputWidget} [input] Text input used to implement option highlighting for menu items that match
7048 * the text the user types. This config is used by {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget}
7049 * and {@link OO.ui.mixin.LookupElement LookupElement}
7050 * @cfg {jQuery} [$input] Text input used to implement option highlighting for menu items that match
7051 * the text the user types. This config is used by {@link OO.ui.CapsuleMultiselectWidget CapsuleMultiselectWidget}
7052 * @cfg {OO.ui.Widget} [widget] Widget associated with the menu's active state. If the user clicks the mouse
7053 * anywhere on the page outside of this widget, the menu is hidden. For example, if there is a button
7054 * that toggles the menu's visibility on click, the menu will be hidden then re-shown when the user clicks
7055 * that button, unless the button (or its parent widget) is passed in here.
7056 * @cfg {boolean} [autoHide=true] Hide the menu when the mouse is pressed outside the menu.
7057 * @cfg {jQuery} [$autoCloseIgnore] If these elements are clicked, don't auto-hide the menu.
7058 * @cfg {boolean} [hideOnChoose=true] Hide the menu when the user chooses an option.
7059 * @cfg {boolean} [filterFromInput=false] Filter the displayed options from the input
7060 * @cfg {boolean} [highlightOnFilter] Highlight the first result when filtering
7061 * @cfg {number} [width] Width of the menu
7063 OO
.ui
.MenuSelectWidget
= function OoUiMenuSelectWidget( config
) {
7064 // Configuration initialization
7065 config
= config
|| {};
7067 // Parent constructor
7068 OO
.ui
.MenuSelectWidget
.parent
.call( this, config
);
7070 // Mixin constructors
7071 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, { $clippable
: this.$group
} ) );
7072 OO
.ui
.mixin
.FloatableElement
.call( this, config
);
7075 this.autoHide
= config
.autoHide
=== undefined || !!config
.autoHide
;
7076 this.hideOnChoose
= config
.hideOnChoose
=== undefined || !!config
.hideOnChoose
;
7077 this.filterFromInput
= !!config
.filterFromInput
;
7078 this.$input
= config
.$input
? config
.$input
: config
.input
? config
.input
.$input
: null;
7079 this.$widget
= config
.widget
? config
.widget
.$element
: null;
7080 this.$autoCloseIgnore
= config
.$autoCloseIgnore
|| $( [] );
7081 this.onDocumentMouseDownHandler
= this.onDocumentMouseDown
.bind( this );
7082 this.onInputEditHandler
= OO
.ui
.debounce( this.updateItemVisibility
.bind( this ), 100 );
7083 this.highlightOnFilter
= !!config
.highlightOnFilter
;
7084 this.width
= config
.width
;
7087 this.$element
.addClass( 'oo-ui-menuSelectWidget' );
7088 if ( config
.widget
) {
7089 this.setFocusOwner( config
.widget
.$tabIndexed
);
7092 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
7093 // that reference properties not initialized at that time of parent class construction
7094 // TODO: Find a better way to handle post-constructor setup
7095 this.visible
= false;
7096 this.$element
.addClass( 'oo-ui-element-hidden' );
7101 OO
.inheritClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.SelectWidget
);
7102 OO
.mixinClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.mixin
.ClippableElement
);
7103 OO
.mixinClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.mixin
.FloatableElement
);
7110 * The menu is ready: it is visible and has been positioned and clipped.
7116 * Handles document mouse down events.
7119 * @param {MouseEvent} e Mouse down event
7121 OO
.ui
.MenuSelectWidget
.prototype.onDocumentMouseDown = function ( e
) {
7125 this.$element
.add( this.$widget
).add( this.$autoCloseIgnore
).get(),
7130 this.toggle( false );
7137 OO
.ui
.MenuSelectWidget
.prototype.onKeyDown = function ( e
) {
7138 var currentItem
= this.findHighlightedItem() || this.getSelectedItem();
7140 if ( !this.isDisabled() && this.isVisible() ) {
7141 switch ( e
.keyCode
) {
7142 case OO
.ui
.Keys
.LEFT
:
7143 case OO
.ui
.Keys
.RIGHT
:
7144 // Do nothing if a text field is associated, arrow keys will be handled natively
7145 if ( !this.$input
) {
7146 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
7149 case OO
.ui
.Keys
.ESCAPE
:
7150 case OO
.ui
.Keys
.TAB
:
7151 if ( currentItem
) {
7152 currentItem
.setHighlighted( false );
7154 this.toggle( false );
7155 // Don't prevent tabbing away, prevent defocusing
7156 if ( e
.keyCode
=== OO
.ui
.Keys
.ESCAPE
) {
7158 e
.stopPropagation();
7162 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
7169 * Update menu item visibility and clipping after input changes (if filterFromInput is enabled)
7170 * or after items were added/removed (always).
7174 OO
.ui
.MenuSelectWidget
.prototype.updateItemVisibility = function () {
7175 var i
, item
, visible
, section
, sectionEmpty
, filter
, exactFilter
,
7176 firstItemFound
= false,
7178 len
= this.items
.length
,
7179 showAll
= !this.isVisible(),
7182 if ( this.$input
&& this.filterFromInput
) {
7183 filter
= showAll
? null : this.getItemMatcher( this.$input
.val() );
7184 exactFilter
= this.getItemMatcher( this.$input
.val(), true );
7186 // Hide non-matching options, and also hide section headers if all options
7187 // in their section are hidden.
7188 for ( i
= 0; i
< len
; i
++ ) {
7189 item
= this.items
[ i
];
7190 if ( item
instanceof OO
.ui
.MenuSectionOptionWidget
) {
7192 // If the previous section was empty, hide its header
7193 section
.toggle( showAll
|| !sectionEmpty
);
7196 sectionEmpty
= true;
7197 } else if ( item
instanceof OO
.ui
.OptionWidget
) {
7198 visible
= showAll
|| filter( item
);
7199 exactMatch
= exactMatch
|| exactFilter( item
);
7200 anyVisible
= anyVisible
|| visible
;
7201 sectionEmpty
= sectionEmpty
&& !visible
;
7202 item
.toggle( visible
);
7203 if ( this.highlightOnFilter
&& visible
&& !firstItemFound
) {
7204 // Highlight the first item in the list
7205 this.highlightItem( item
);
7206 firstItemFound
= true;
7210 // Process the final section
7212 section
.toggle( showAll
|| !sectionEmpty
);
7215 if ( anyVisible
&& this.items
.length
&& !exactMatch
) {
7216 this.scrollItemIntoView( this.items
[ 0 ] );
7219 this.$element
.toggleClass( 'oo-ui-menuSelectWidget-invisible', !anyVisible
);
7222 // Reevaluate clipping
7229 OO
.ui
.MenuSelectWidget
.prototype.bindKeyDownListener = function () {
7230 if ( this.$input
) {
7231 this.$input
.on( 'keydown', this.onKeyDownHandler
);
7233 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyDownListener
.call( this );
7240 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyDownListener = function () {
7241 if ( this.$input
) {
7242 this.$input
.off( 'keydown', this.onKeyDownHandler
);
7244 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyDownListener
.call( this );
7251 OO
.ui
.MenuSelectWidget
.prototype.bindKeyPressListener = function () {
7252 if ( this.$input
) {
7253 if ( this.filterFromInput
) {
7254 this.$input
.on( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
7255 this.updateItemVisibility();
7258 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyPressListener
.call( this );
7265 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyPressListener = function () {
7266 if ( this.$input
) {
7267 if ( this.filterFromInput
) {
7268 this.$input
.off( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
7269 this.updateItemVisibility();
7272 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyPressListener
.call( this );
7279 * When a user chooses an item, the menu is closed, unless the hideOnChoose config option is set to false.
7281 * Note that ‘choose’ should never be modified programmatically. A user can choose an option with the keyboard
7282 * or mouse and it becomes selected. To select an item programmatically, use the #selectItem method.
7284 * @param {OO.ui.OptionWidget} item Item to choose
7287 OO
.ui
.MenuSelectWidget
.prototype.chooseItem = function ( item
) {
7288 OO
.ui
.MenuSelectWidget
.parent
.prototype.chooseItem
.call( this, item
);
7289 if ( this.hideOnChoose
) {
7290 this.toggle( false );
7298 OO
.ui
.MenuSelectWidget
.prototype.addItems = function ( items
, index
) {
7300 OO
.ui
.MenuSelectWidget
.parent
.prototype.addItems
.call( this, items
, index
);
7302 this.updateItemVisibility();
7310 OO
.ui
.MenuSelectWidget
.prototype.removeItems = function ( items
) {
7312 OO
.ui
.MenuSelectWidget
.parent
.prototype.removeItems
.call( this, items
);
7314 this.updateItemVisibility();
7322 OO
.ui
.MenuSelectWidget
.prototype.clearItems = function () {
7324 OO
.ui
.MenuSelectWidget
.parent
.prototype.clearItems
.call( this );
7326 this.updateItemVisibility();
7332 * Toggle visibility of the menu. The menu is initially hidden and must be shown by calling
7333 * `.toggle( true )` after its #$element is attached to the DOM.
7335 * Do not show the menu while it is not attached to the DOM. The calculations required to display
7336 * it in the right place and with the right dimensions only work correctly while it is attached.
7337 * Side-effects may include broken interface and exceptions being thrown. This wasn't always
7338 * strictly enforced, so currently it only generates a warning in the browser console.
7343 OO
.ui
.MenuSelectWidget
.prototype.toggle = function ( visible
) {
7346 visible
= ( visible
=== undefined ? !this.visible
: !!visible
) && !!this.items
.length
;
7347 change
= visible
!== this.isVisible();
7349 if ( visible
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
7350 OO
.ui
.warnDeprecation( 'MenuSelectWidget#toggle: Before calling this method, the menu must be attached to the DOM.' );
7351 this.warnedUnattached
= true;
7354 if ( change
&& visible
&& ( this.width
|| this.$floatableContainer
) ) {
7355 this.setIdealSize( this.width
|| this.$floatableContainer
.width() );
7359 OO
.ui
.MenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
7363 this.bindKeyDownListener();
7364 this.bindKeyPressListener();
7366 this.togglePositioning( !!this.$floatableContainer
);
7367 this.toggleClipping( true );
7369 this.$focusOwner
.attr( 'aria-expanded', 'true' );
7371 if ( this.getSelectedItem() ) {
7372 this.$focusOwner
.attr( 'aria-activedescendant', this.getSelectedItem().getElementId() );
7373 this.getSelectedItem().scrollElementIntoView( { duration
: 0 } );
7377 if ( this.autoHide
) {
7378 this.getElementDocument().addEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
7381 this.emit( 'ready' );
7383 this.$focusOwner
.removeAttr( 'aria-activedescendant' );
7384 this.unbindKeyDownListener();
7385 this.unbindKeyPressListener();
7386 this.$focusOwner
.attr( 'aria-expanded', 'false' );
7387 this.getElementDocument().removeEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
7388 this.togglePositioning( false );
7389 this.toggleClipping( false );
7397 * DropdownWidgets are not menus themselves, rather they contain a menu of options created with
7398 * OO.ui.MenuOptionWidget. The DropdownWidget takes care of opening and displaying the menu so that
7399 * users can interact with it.
7401 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
7402 * OO.ui.DropdownInputWidget instead.
7405 * // Example: A DropdownWidget with a menu that contains three options
7406 * var dropDown = new OO.ui.DropdownWidget( {
7407 * label: 'Dropdown menu: Select a menu option',
7410 * new OO.ui.MenuOptionWidget( {
7414 * new OO.ui.MenuOptionWidget( {
7418 * new OO.ui.MenuOptionWidget( {
7426 * $( 'body' ).append( dropDown.$element );
7428 * dropDown.getMenu().selectItemByData( 'b' );
7430 * dropDown.getMenu().getSelectedItem().getData(); // returns 'b'
7432 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
7434 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
7437 * @extends OO.ui.Widget
7438 * @mixins OO.ui.mixin.IconElement
7439 * @mixins OO.ui.mixin.IndicatorElement
7440 * @mixins OO.ui.mixin.LabelElement
7441 * @mixins OO.ui.mixin.TitledElement
7442 * @mixins OO.ui.mixin.TabIndexedElement
7445 * @param {Object} [config] Configuration options
7446 * @cfg {Object} [menu] Configuration options to pass to {@link OO.ui.MenuSelectWidget menu select widget}
7447 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
7448 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
7449 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
7450 * See <https://www.mediawiki.org/wiki/OOjs_UI/Concepts#Overlays>.
7452 OO
.ui
.DropdownWidget
= function OoUiDropdownWidget( config
) {
7453 // Configuration initialization
7454 config
= $.extend( { indicator
: 'down' }, config
);
7456 // Parent constructor
7457 OO
.ui
.DropdownWidget
.parent
.call( this, config
);
7459 // Properties (must be set before TabIndexedElement constructor call)
7460 this.$handle
= this.$( '<span>' );
7461 this.$overlay
= config
.$overlay
|| this.$element
;
7463 // Mixin constructors
7464 OO
.ui
.mixin
.IconElement
.call( this, config
);
7465 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
7466 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7467 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
7468 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$handle
} ) );
7471 this.menu
= new OO
.ui
.MenuSelectWidget( $.extend( {
7473 $floatableContainer
: this.$element
7478 click
: this.onClick
.bind( this ),
7479 keydown
: this.onKeyDown
.bind( this ),
7480 // Hack? Handle type-to-search when menu is not expanded and not handling its own events
7481 keypress
: this.menu
.onKeyPressHandler
,
7482 blur
: this.menu
.clearKeyPressBuffer
.bind( this.menu
)
7484 this.menu
.connect( this, {
7485 select
: 'onMenuSelect',
7486 toggle
: 'onMenuToggle'
7491 .addClass( 'oo-ui-dropdownWidget-handle' )
7494 'aria-owns': this.menu
.getElementId(),
7495 'aria-autocomplete': 'list'
7497 .append( this.$icon
, this.$label
, this.$indicator
);
7499 .addClass( 'oo-ui-dropdownWidget' )
7500 .append( this.$handle
);
7501 this.$overlay
.append( this.menu
.$element
);
7506 OO
.inheritClass( OO
.ui
.DropdownWidget
, OO
.ui
.Widget
);
7507 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IconElement
);
7508 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IndicatorElement
);
7509 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.LabelElement
);
7510 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TitledElement
);
7511 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TabIndexedElement
);
7518 * @return {OO.ui.MenuSelectWidget} Menu of widget
7520 OO
.ui
.DropdownWidget
.prototype.getMenu = function () {
7525 * Handles menu select events.
7528 * @param {OO.ui.MenuOptionWidget} item Selected menu item
7530 OO
.ui
.DropdownWidget
.prototype.onMenuSelect = function ( item
) {
7534 this.setLabel( null );
7538 selectedLabel
= item
.getLabel();
7540 // If the label is a DOM element, clone it, because setLabel will append() it
7541 if ( selectedLabel
instanceof jQuery
) {
7542 selectedLabel
= selectedLabel
.clone();
7545 this.setLabel( selectedLabel
);
7549 * Handle menu toggle events.
7552 * @param {boolean} isVisible Menu toggle event
7554 OO
.ui
.DropdownWidget
.prototype.onMenuToggle = function ( isVisible
) {
7555 this.$element
.toggleClass( 'oo-ui-dropdownWidget-open', isVisible
);
7558 this.$element
.hasClass( 'oo-ui-dropdownWidget-open' ).toString()
7563 * Handle mouse click events.
7566 * @param {jQuery.Event} e Mouse click event
7568 OO
.ui
.DropdownWidget
.prototype.onClick = function ( e
) {
7569 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
7576 * Handle key down events.
7579 * @param {jQuery.Event} e Key down event
7581 OO
.ui
.DropdownWidget
.prototype.onKeyDown = function ( e
) {
7583 !this.isDisabled() &&
7585 e
.which
=== OO
.ui
.Keys
.ENTER
||
7587 !this.menu
.isVisible() &&
7589 e
.which
=== OO
.ui
.Keys
.SPACE
||
7590 e
.which
=== OO
.ui
.Keys
.UP
||
7591 e
.which
=== OO
.ui
.Keys
.DOWN
7602 * RadioOptionWidget is an option widget that looks like a radio button.
7603 * The class is used with OO.ui.RadioSelectWidget to create a selection of radio options.
7604 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
7606 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option
7609 * @extends OO.ui.OptionWidget
7612 * @param {Object} [config] Configuration options
7614 OO
.ui
.RadioOptionWidget
= function OoUiRadioOptionWidget( config
) {
7615 // Configuration initialization
7616 config
= config
|| {};
7618 // Properties (must be done before parent constructor which calls #setDisabled)
7619 this.radio
= new OO
.ui
.RadioInputWidget( { value
: config
.data
, tabIndex
: -1 } );
7621 // Parent constructor
7622 OO
.ui
.RadioOptionWidget
.parent
.call( this, config
);
7625 // Remove implicit role, we're handling it ourselves
7626 this.radio
.$input
.attr( 'role', 'presentation' );
7628 .addClass( 'oo-ui-radioOptionWidget' )
7629 .attr( 'role', 'radio' )
7630 .attr( 'aria-checked', 'false' )
7631 .removeAttr( 'aria-selected' )
7632 .prepend( this.radio
.$element
);
7637 OO
.inheritClass( OO
.ui
.RadioOptionWidget
, OO
.ui
.OptionWidget
);
7639 /* Static Properties */
7645 OO
.ui
.RadioOptionWidget
.static.highlightable
= false;
7651 OO
.ui
.RadioOptionWidget
.static.scrollIntoViewOnSelect
= true;
7657 OO
.ui
.RadioOptionWidget
.static.pressable
= false;
7663 OO
.ui
.RadioOptionWidget
.static.tagName
= 'label';
7670 OO
.ui
.RadioOptionWidget
.prototype.setSelected = function ( state
) {
7671 OO
.ui
.RadioOptionWidget
.parent
.prototype.setSelected
.call( this, state
);
7673 this.radio
.setSelected( state
);
7675 .attr( 'aria-checked', state
.toString() )
7676 .removeAttr( 'aria-selected' );
7684 OO
.ui
.RadioOptionWidget
.prototype.setDisabled = function ( disabled
) {
7685 OO
.ui
.RadioOptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
7687 this.radio
.setDisabled( this.isDisabled() );
7693 * RadioSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains radio
7694 * options and is used together with OO.ui.RadioOptionWidget. The RadioSelectWidget provides
7695 * an interface for adding, removing and selecting options.
7696 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
7698 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
7699 * OO.ui.RadioSelectInputWidget instead.
7702 * // A RadioSelectWidget with RadioOptions.
7703 * var option1 = new OO.ui.RadioOptionWidget( {
7705 * label: 'Selected radio option'
7708 * var option2 = new OO.ui.RadioOptionWidget( {
7710 * label: 'Unselected radio option'
7713 * var radioSelect=new OO.ui.RadioSelectWidget( {
7714 * items: [ option1, option2 ]
7717 * // Select 'option 1' using the RadioSelectWidget's selectItem() method.
7718 * radioSelect.selectItem( option1 );
7720 * $( 'body' ).append( radioSelect.$element );
7722 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
7726 * @extends OO.ui.SelectWidget
7727 * @mixins OO.ui.mixin.TabIndexedElement
7730 * @param {Object} [config] Configuration options
7732 OO
.ui
.RadioSelectWidget
= function OoUiRadioSelectWidget( config
) {
7733 // Parent constructor
7734 OO
.ui
.RadioSelectWidget
.parent
.call( this, config
);
7736 // Mixin constructors
7737 OO
.ui
.mixin
.TabIndexedElement
.call( this, config
);
7741 focus
: this.bindKeyDownListener
.bind( this ),
7742 blur
: this.unbindKeyDownListener
.bind( this )
7747 .addClass( 'oo-ui-radioSelectWidget' )
7748 .attr( 'role', 'radiogroup' );
7753 OO
.inheritClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.SelectWidget
);
7754 OO
.mixinClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.mixin
.TabIndexedElement
);
7757 * MultioptionWidgets are special elements that can be selected and configured with data. The
7758 * data is often unique for each option, but it does not have to be. MultioptionWidgets are used
7759 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
7760 * and examples, please see the [OOjs UI documentation on MediaWiki][1].
7762 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Multioptions
7765 * @extends OO.ui.Widget
7766 * @mixins OO.ui.mixin.ItemWidget
7767 * @mixins OO.ui.mixin.LabelElement
7770 * @param {Object} [config] Configuration options
7771 * @cfg {boolean} [selected=false] Whether the option is initially selected
7773 OO
.ui
.MultioptionWidget
= function OoUiMultioptionWidget( config
) {
7774 // Configuration initialization
7775 config
= config
|| {};
7777 // Parent constructor
7778 OO
.ui
.MultioptionWidget
.parent
.call( this, config
);
7780 // Mixin constructors
7781 OO
.ui
.mixin
.ItemWidget
.call( this );
7782 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7785 this.selected
= null;
7789 .addClass( 'oo-ui-multioptionWidget' )
7790 .append( this.$label
);
7791 this.setSelected( config
.selected
);
7796 OO
.inheritClass( OO
.ui
.MultioptionWidget
, OO
.ui
.Widget
);
7797 OO
.mixinClass( OO
.ui
.MultioptionWidget
, OO
.ui
.mixin
.ItemWidget
);
7798 OO
.mixinClass( OO
.ui
.MultioptionWidget
, OO
.ui
.mixin
.LabelElement
);
7805 * A change event is emitted when the selected state of the option changes.
7807 * @param {boolean} selected Whether the option is now selected
7813 * Check if the option is selected.
7815 * @return {boolean} Item is selected
7817 OO
.ui
.MultioptionWidget
.prototype.isSelected = function () {
7818 return this.selected
;
7822 * Set the option’s selected state. In general, all modifications to the selection
7823 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
7824 * method instead of this method.
7826 * @param {boolean} [state=false] Select option
7829 OO
.ui
.MultioptionWidget
.prototype.setSelected = function ( state
) {
7831 if ( this.selected
!== state
) {
7832 this.selected
= state
;
7833 this.emit( 'change', state
);
7834 this.$element
.toggleClass( 'oo-ui-multioptionWidget-selected', state
);
7840 * MultiselectWidget allows selecting multiple options from a list.
7842 * For more information about menus and options, please see the [OOjs UI documentation on MediaWiki][1].
7844 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
7848 * @extends OO.ui.Widget
7849 * @mixins OO.ui.mixin.GroupWidget
7852 * @param {Object} [config] Configuration options
7853 * @cfg {OO.ui.MultioptionWidget[]} [items] An array of options to add to the multiselect.
7855 OO
.ui
.MultiselectWidget
= function OoUiMultiselectWidget( config
) {
7856 // Parent constructor
7857 OO
.ui
.MultiselectWidget
.parent
.call( this, config
);
7859 // Configuration initialization
7860 config
= config
|| {};
7862 // Mixin constructors
7863 OO
.ui
.mixin
.GroupWidget
.call( this, config
);
7866 this.aggregate( { change
: 'select' } );
7867 // This is mostly for compatibility with CapsuleMultiselectWidget... normally, 'change' is emitted
7868 // by GroupElement only when items are added/removed
7869 this.connect( this, { select
: [ 'emit', 'change' ] } );
7872 if ( config
.items
) {
7873 this.addItems( config
.items
);
7875 this.$group
.addClass( 'oo-ui-multiselectWidget-group' );
7876 this.$element
.addClass( 'oo-ui-multiselectWidget' )
7877 .append( this.$group
);
7882 OO
.inheritClass( OO
.ui
.MultiselectWidget
, OO
.ui
.Widget
);
7883 OO
.mixinClass( OO
.ui
.MultiselectWidget
, OO
.ui
.mixin
.GroupWidget
);
7890 * A change event is emitted when the set of items changes, or an item is selected or deselected.
7896 * A select event is emitted when an item is selected or deselected.
7902 * Get options that are selected.
7904 * @return {OO.ui.MultioptionWidget[]} Selected options
7906 OO
.ui
.MultiselectWidget
.prototype.getSelectedItems = function () {
7907 return this.items
.filter( function ( item
) {
7908 return item
.isSelected();
7913 * Get the data of options that are selected.
7915 * @return {Object[]|string[]} Values of selected options
7917 OO
.ui
.MultiselectWidget
.prototype.getSelectedItemsData = function () {
7918 return this.getSelectedItems().map( function ( item
) {
7924 * Select options by reference. Options not mentioned in the `items` array will be deselected.
7926 * @param {OO.ui.MultioptionWidget[]} items Items to select
7929 OO
.ui
.MultiselectWidget
.prototype.selectItems = function ( items
) {
7930 this.items
.forEach( function ( item
) {
7931 var selected
= items
.indexOf( item
) !== -1;
7932 item
.setSelected( selected
);
7938 * Select items by their data. Options not mentioned in the `datas` array will be deselected.
7940 * @param {Object[]|string[]} datas Values of items to select
7943 OO
.ui
.MultiselectWidget
.prototype.selectItemsByData = function ( datas
) {
7946 items
= datas
.map( function ( data
) {
7947 return widget
.getItemFromData( data
);
7949 this.selectItems( items
);
7954 * CheckboxMultioptionWidget is an option widget that looks like a checkbox.
7955 * The class is used with OO.ui.CheckboxMultiselectWidget to create a selection of checkbox options.
7956 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
7958 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option
7961 * @extends OO.ui.MultioptionWidget
7964 * @param {Object} [config] Configuration options
7966 OO
.ui
.CheckboxMultioptionWidget
= function OoUiCheckboxMultioptionWidget( config
) {
7967 // Configuration initialization
7968 config
= config
|| {};
7970 // Properties (must be done before parent constructor which calls #setDisabled)
7971 this.checkbox
= new OO
.ui
.CheckboxInputWidget();
7973 // Parent constructor
7974 OO
.ui
.CheckboxMultioptionWidget
.parent
.call( this, config
);
7977 this.checkbox
.on( 'change', this.onCheckboxChange
.bind( this ) );
7978 this.$element
.on( 'keydown', this.onKeyDown
.bind( this ) );
7982 .addClass( 'oo-ui-checkboxMultioptionWidget' )
7983 .prepend( this.checkbox
.$element
);
7988 OO
.inheritClass( OO
.ui
.CheckboxMultioptionWidget
, OO
.ui
.MultioptionWidget
);
7990 /* Static Properties */
7996 OO
.ui
.CheckboxMultioptionWidget
.static.tagName
= 'label';
8001 * Handle checkbox selected state change.
8005 OO
.ui
.CheckboxMultioptionWidget
.prototype.onCheckboxChange = function () {
8006 this.setSelected( this.checkbox
.isSelected() );
8012 OO
.ui
.CheckboxMultioptionWidget
.prototype.setSelected = function ( state
) {
8013 OO
.ui
.CheckboxMultioptionWidget
.parent
.prototype.setSelected
.call( this, state
);
8014 this.checkbox
.setSelected( state
);
8021 OO
.ui
.CheckboxMultioptionWidget
.prototype.setDisabled = function ( disabled
) {
8022 OO
.ui
.CheckboxMultioptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
8023 this.checkbox
.setDisabled( this.isDisabled() );
8030 OO
.ui
.CheckboxMultioptionWidget
.prototype.focus = function () {
8031 this.checkbox
.focus();
8035 * Handle key down events.
8038 * @param {jQuery.Event} e
8040 OO
.ui
.CheckboxMultioptionWidget
.prototype.onKeyDown = function ( e
) {
8042 element
= this.getElementGroup(),
8045 if ( e
.keyCode
=== OO
.ui
.Keys
.LEFT
|| e
.keyCode
=== OO
.ui
.Keys
.UP
) {
8046 nextItem
= element
.getRelativeFocusableItem( this, -1 );
8047 } else if ( e
.keyCode
=== OO
.ui
.Keys
.RIGHT
|| e
.keyCode
=== OO
.ui
.Keys
.DOWN
) {
8048 nextItem
= element
.getRelativeFocusableItem( this, 1 );
8058 * CheckboxMultiselectWidget is a {@link OO.ui.MultiselectWidget multiselect widget} that contains
8059 * checkboxes and is used together with OO.ui.CheckboxMultioptionWidget. The
8060 * CheckboxMultiselectWidget provides an interface for adding, removing and selecting options.
8061 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
8063 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
8064 * OO.ui.CheckboxMultiselectInputWidget instead.
8067 * // A CheckboxMultiselectWidget with CheckboxMultioptions.
8068 * var option1 = new OO.ui.CheckboxMultioptionWidget( {
8071 * label: 'Selected checkbox'
8074 * var option2 = new OO.ui.CheckboxMultioptionWidget( {
8076 * label: 'Unselected checkbox'
8079 * var multiselect=new OO.ui.CheckboxMultiselectWidget( {
8080 * items: [ option1, option2 ]
8083 * $( 'body' ).append( multiselect.$element );
8085 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
8088 * @extends OO.ui.MultiselectWidget
8091 * @param {Object} [config] Configuration options
8093 OO
.ui
.CheckboxMultiselectWidget
= function OoUiCheckboxMultiselectWidget( config
) {
8094 // Parent constructor
8095 OO
.ui
.CheckboxMultiselectWidget
.parent
.call( this, config
);
8098 this.$lastClicked
= null;
8101 this.$group
.on( 'click', this.onClick
.bind( this ) );
8105 .addClass( 'oo-ui-checkboxMultiselectWidget' );
8110 OO
.inheritClass( OO
.ui
.CheckboxMultiselectWidget
, OO
.ui
.MultiselectWidget
);
8115 * Get an option by its position relative to the specified item (or to the start of the option array,
8116 * if item is `null`). The direction in which to search through the option array is specified with a
8117 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
8118 * `null` if there are no options in the array.
8120 * @param {OO.ui.CheckboxMultioptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
8121 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
8122 * @return {OO.ui.CheckboxMultioptionWidget|null} Item at position, `null` if there are no items in the select
8124 OO
.ui
.CheckboxMultiselectWidget
.prototype.getRelativeFocusableItem = function ( item
, direction
) {
8125 var currentIndex
, nextIndex
, i
,
8126 increase
= direction
> 0 ? 1 : -1,
8127 len
= this.items
.length
;
8130 currentIndex
= this.items
.indexOf( item
);
8131 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
8133 // If no item is selected and moving forward, start at the beginning.
8134 // If moving backward, start at the end.
8135 nextIndex
= direction
> 0 ? 0 : len
- 1;
8138 for ( i
= 0; i
< len
; i
++ ) {
8139 item
= this.items
[ nextIndex
];
8140 if ( item
&& !item
.isDisabled() ) {
8143 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
8149 * Handle click events on checkboxes.
8151 * @param {jQuery.Event} e
8153 OO
.ui
.CheckboxMultiselectWidget
.prototype.onClick = function ( e
) {
8154 var $options
, lastClickedIndex
, nowClickedIndex
, i
, direction
, wasSelected
, items
,
8155 $lastClicked
= this.$lastClicked
,
8156 $nowClicked
= $( e
.target
).closest( '.oo-ui-checkboxMultioptionWidget' )
8157 .not( '.oo-ui-widget-disabled' );
8159 // Allow selecting multiple options at once by Shift-clicking them
8160 if ( $lastClicked
&& $nowClicked
.length
&& e
.shiftKey
) {
8161 $options
= this.$group
.find( '.oo-ui-checkboxMultioptionWidget' );
8162 lastClickedIndex
= $options
.index( $lastClicked
);
8163 nowClickedIndex
= $options
.index( $nowClicked
);
8164 // If it's the same item, either the user is being silly, or it's a fake event generated by the
8165 // browser. In either case we don't need custom handling.
8166 if ( nowClickedIndex
!== lastClickedIndex
) {
8168 wasSelected
= items
[ nowClickedIndex
].isSelected();
8169 direction
= nowClickedIndex
> lastClickedIndex
? 1 : -1;
8171 // This depends on the DOM order of the items and the order of the .items array being the same.
8172 for ( i
= lastClickedIndex
; i
!== nowClickedIndex
; i
+= direction
) {
8173 if ( !items
[ i
].isDisabled() ) {
8174 items
[ i
].setSelected( !wasSelected
);
8177 // For the now-clicked element, use immediate timeout to allow the browser to do its own
8178 // handling first, then set our value. The order in which events happen is different for
8179 // clicks on the <input> and on the <label> and there are additional fake clicks fired for
8180 // non-click actions that change the checkboxes.
8182 setTimeout( function () {
8183 if ( !items
[ nowClickedIndex
].isDisabled() ) {
8184 items
[ nowClickedIndex
].setSelected( !wasSelected
);
8190 if ( $nowClicked
.length
) {
8191 this.$lastClicked
= $nowClicked
;
8200 OO
.ui
.CheckboxMultiselectWidget
.prototype.focus = function () {
8202 if ( !this.isDisabled() ) {
8203 item
= this.getRelativeFocusableItem( null, 1 );
8214 OO
.ui
.CheckboxMultiselectWidget
.prototype.simulateLabelClick = function () {
8219 * Progress bars visually display the status of an operation, such as a download,
8220 * and can be either determinate or indeterminate:
8222 * - **determinate** process bars show the percent of an operation that is complete.
8224 * - **indeterminate** process bars use a visual display of motion to indicate that an operation
8225 * is taking place. Because the extent of an indeterminate operation is unknown, the bar does
8226 * not use percentages.
8228 * The value of the `progress` configuration determines whether the bar is determinate or indeterminate.
8231 * // Examples of determinate and indeterminate progress bars.
8232 * var progressBar1 = new OO.ui.ProgressBarWidget( {
8235 * var progressBar2 = new OO.ui.ProgressBarWidget();
8237 * // Create a FieldsetLayout to layout progress bars
8238 * var fieldset = new OO.ui.FieldsetLayout;
8239 * fieldset.addItems( [
8240 * new OO.ui.FieldLayout( progressBar1, {label: 'Determinate', align: 'top'}),
8241 * new OO.ui.FieldLayout( progressBar2, {label: 'Indeterminate', align: 'top'})
8243 * $( 'body' ).append( fieldset.$element );
8246 * @extends OO.ui.Widget
8249 * @param {Object} [config] Configuration options
8250 * @cfg {number|boolean} [progress=false] The type of progress bar (determinate or indeterminate).
8251 * To create a determinate progress bar, specify a number that reflects the initial percent complete.
8252 * By default, the progress bar is indeterminate.
8254 OO
.ui
.ProgressBarWidget
= function OoUiProgressBarWidget( config
) {
8255 // Configuration initialization
8256 config
= config
|| {};
8258 // Parent constructor
8259 OO
.ui
.ProgressBarWidget
.parent
.call( this, config
);
8262 this.$bar
= $( '<div>' );
8263 this.progress
= null;
8266 this.setProgress( config
.progress
!== undefined ? config
.progress
: false );
8267 this.$bar
.addClass( 'oo-ui-progressBarWidget-bar' );
8270 role
: 'progressbar',
8272 'aria-valuemax': 100
8274 .addClass( 'oo-ui-progressBarWidget' )
8275 .append( this.$bar
);
8280 OO
.inheritClass( OO
.ui
.ProgressBarWidget
, OO
.ui
.Widget
);
8282 /* Static Properties */
8288 OO
.ui
.ProgressBarWidget
.static.tagName
= 'div';
8293 * Get the percent of the progress that has been completed. Indeterminate progresses will return `false`.
8295 * @return {number|boolean} Progress percent
8297 OO
.ui
.ProgressBarWidget
.prototype.getProgress = function () {
8298 return this.progress
;
8302 * Set the percent of the process completed or `false` for an indeterminate process.
8304 * @param {number|boolean} progress Progress percent or `false` for indeterminate
8306 OO
.ui
.ProgressBarWidget
.prototype.setProgress = function ( progress
) {
8307 this.progress
= progress
;
8309 if ( progress
!== false ) {
8310 this.$bar
.css( 'width', this.progress
+ '%' );
8311 this.$element
.attr( 'aria-valuenow', this.progress
);
8313 this.$bar
.css( 'width', '' );
8314 this.$element
.removeAttr( 'aria-valuenow' );
8316 this.$element
.toggleClass( 'oo-ui-progressBarWidget-indeterminate', progress
=== false );
8320 * InputWidget is the base class for all input widgets, which
8321 * include {@link OO.ui.TextInputWidget text inputs}, {@link OO.ui.CheckboxInputWidget checkbox inputs},
8322 * {@link OO.ui.RadioInputWidget radio inputs}, and {@link OO.ui.ButtonInputWidget button inputs}.
8323 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
8325 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8329 * @extends OO.ui.Widget
8330 * @mixins OO.ui.mixin.FlaggedElement
8331 * @mixins OO.ui.mixin.TabIndexedElement
8332 * @mixins OO.ui.mixin.TitledElement
8333 * @mixins OO.ui.mixin.AccessKeyedElement
8336 * @param {Object} [config] Configuration options
8337 * @cfg {string} [name=''] The value of the input’s HTML `name` attribute.
8338 * @cfg {string} [value=''] The value of the input.
8339 * @cfg {string} [dir] The directionality of the input (ltr/rtl).
8340 * @cfg {string} [inputId] The value of the input’s HTML `id` attribute.
8341 * @cfg {Function} [inputFilter] The name of an input filter function. Input filters modify the value of an input
8342 * before it is accepted.
8344 OO
.ui
.InputWidget
= function OoUiInputWidget( config
) {
8345 // Configuration initialization
8346 config
= config
|| {};
8348 // Parent constructor
8349 OO
.ui
.InputWidget
.parent
.call( this, config
);
8352 // See #reusePreInfuseDOM about config.$input
8353 this.$input
= config
.$input
|| this.getInputElement( config
);
8355 this.inputFilter
= config
.inputFilter
;
8357 // Mixin constructors
8358 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
8359 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$input
} ) );
8360 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
8361 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$input
} ) );
8364 this.$input
.on( 'keydown mouseup cut paste change input select', this.onEdit
.bind( this ) );
8368 .addClass( 'oo-ui-inputWidget-input' )
8369 .attr( 'name', config
.name
)
8370 .prop( 'disabled', this.isDisabled() );
8372 .addClass( 'oo-ui-inputWidget' )
8373 .append( this.$input
);
8374 this.setValue( config
.value
);
8376 this.setDir( config
.dir
);
8378 if ( config
.inputId
!== undefined ) {
8379 this.setInputId( config
.inputId
);
8385 OO
.inheritClass( OO
.ui
.InputWidget
, OO
.ui
.Widget
);
8386 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.FlaggedElement
);
8387 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TabIndexedElement
);
8388 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TitledElement
);
8389 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
8391 /* Static Methods */
8396 OO
.ui
.InputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
8397 config
= OO
.ui
.InputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
8398 // Reusing `$input` lets browsers preserve inputted values across page reloads, see T114134.
8399 config
.$input
= $( node
).find( '.oo-ui-inputWidget-input' );
8406 OO
.ui
.InputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8407 var state
= OO
.ui
.InputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8408 if ( config
.$input
&& config
.$input
.length
) {
8409 state
.value
= config
.$input
.val();
8410 // Might be better in TabIndexedElement, but it's awkward to do there because mixins are awkward
8411 state
.focus
= config
.$input
.is( ':focus' );
8421 * A change event is emitted when the value of the input changes.
8423 * @param {string} value
8429 * Get input element.
8431 * Subclasses of OO.ui.InputWidget use the `config` parameter to produce different elements in
8432 * different circumstances. The element must have a `value` property (like form elements).
8435 * @param {Object} config Configuration options
8436 * @return {jQuery} Input element
8438 OO
.ui
.InputWidget
.prototype.getInputElement = function () {
8439 return $( '<input>' );
8443 * Handle potentially value-changing events.
8446 * @param {jQuery.Event} e Key down, mouse up, cut, paste, change, input, or select event
8448 OO
.ui
.InputWidget
.prototype.onEdit = function () {
8450 if ( !this.isDisabled() ) {
8451 // Allow the stack to clear so the value will be updated
8452 setTimeout( function () {
8453 widget
.setValue( widget
.$input
.val() );
8459 * Get the value of the input.
8461 * @return {string} Input value
8463 OO
.ui
.InputWidget
.prototype.getValue = function () {
8464 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
8465 // it, and we won't know unless they're kind enough to trigger a 'change' event.
8466 var value
= this.$input
.val();
8467 if ( this.value
!== value
) {
8468 this.setValue( value
);
8474 * Set the directionality of the input.
8476 * @param {string} dir Text directionality: 'ltr', 'rtl' or 'auto'
8479 OO
.ui
.InputWidget
.prototype.setDir = function ( dir
) {
8480 this.$input
.prop( 'dir', dir
);
8485 * Set the value of the input.
8487 * @param {string} value New value
8491 OO
.ui
.InputWidget
.prototype.setValue = function ( value
) {
8492 value
= this.cleanUpValue( value
);
8493 // Update the DOM if it has changed. Note that with cleanUpValue, it
8494 // is possible for the DOM value to change without this.value changing.
8495 if ( this.$input
.val() !== value
) {
8496 this.$input
.val( value
);
8498 if ( this.value
!== value
) {
8500 this.emit( 'change', this.value
);
8506 * Clean up incoming value.
8508 * Ensures value is a string, and converts undefined and null to empty string.
8511 * @param {string} value Original value
8512 * @return {string} Cleaned up value
8514 OO
.ui
.InputWidget
.prototype.cleanUpValue = function ( value
) {
8515 if ( value
=== undefined || value
=== null ) {
8517 } else if ( this.inputFilter
) {
8518 return this.inputFilter( String( value
) );
8520 return String( value
);
8527 OO
.ui
.InputWidget
.prototype.setDisabled = function ( state
) {
8528 OO
.ui
.InputWidget
.parent
.prototype.setDisabled
.call( this, state
);
8529 if ( this.$input
) {
8530 this.$input
.prop( 'disabled', this.isDisabled() );
8536 * Set the 'id' attribute of the `<input>` element.
8538 * @param {string} id
8541 OO
.ui
.InputWidget
.prototype.setInputId = function ( id
) {
8542 this.$input
.attr( 'id', id
);
8549 OO
.ui
.InputWidget
.prototype.restorePreInfuseState = function ( state
) {
8550 OO
.ui
.InputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8551 if ( state
.value
!== undefined && state
.value
!== this.getValue() ) {
8552 this.setValue( state
.value
);
8554 if ( state
.focus
) {
8560 * Data widget intended for creating 'hidden'-type inputs.
8563 * @extends OO.ui.Widget
8566 * @param {Object} [config] Configuration options
8567 * @cfg {string} [value=''] The value of the input.
8568 * @cfg {string} [name=''] The value of the input’s HTML `name` attribute.
8570 OO
.ui
.HiddenInputWidget
= function OoUiHiddenInputWidget( config
) {
8571 // Configuration initialization
8572 config
= $.extend( { value
: '', name
: '' }, config
);
8574 // Parent constructor
8575 OO
.ui
.HiddenInputWidget
.parent
.call( this, config
);
8578 this.$element
.attr( {
8580 value
: config
.value
,
8583 this.$element
.removeAttr( 'aria-disabled' );
8588 OO
.inheritClass( OO
.ui
.HiddenInputWidget
, OO
.ui
.Widget
);
8590 /* Static Properties */
8596 OO
.ui
.HiddenInputWidget
.static.tagName
= 'input';
8599 * ButtonInputWidget is used to submit HTML forms and is intended to be used within
8600 * a OO.ui.FormLayout. If you do not need the button to work with HTML forms, you probably
8601 * want to use OO.ui.ButtonWidget instead. Button input widgets can be rendered as either an
8602 * HTML `<button>` (the default) or an HTML `<input>` tags. See the
8603 * [OOjs UI documentation on MediaWiki] [1] for more information.
8606 * // A ButtonInputWidget rendered as an HTML button, the default.
8607 * var button = new OO.ui.ButtonInputWidget( {
8608 * label: 'Input button',
8612 * $( 'body' ).append( button.$element );
8614 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs#Button_inputs
8617 * @extends OO.ui.InputWidget
8618 * @mixins OO.ui.mixin.ButtonElement
8619 * @mixins OO.ui.mixin.IconElement
8620 * @mixins OO.ui.mixin.IndicatorElement
8621 * @mixins OO.ui.mixin.LabelElement
8622 * @mixins OO.ui.mixin.TitledElement
8625 * @param {Object} [config] Configuration options
8626 * @cfg {string} [type='button'] The value of the HTML `'type'` attribute: 'button', 'submit' or 'reset'.
8627 * @cfg {boolean} [useInputTag=false] Use an `<input>` tag instead of a `<button>` tag, the default.
8628 * Widgets configured to be an `<input>` do not support {@link #icon icons} and {@link #indicator indicators},
8629 * non-plaintext {@link #label labels}, or {@link #value values}. In general, useInputTag should only
8630 * be set to `true` when there’s need to support IE 6 in a form with multiple buttons.
8632 OO
.ui
.ButtonInputWidget
= function OoUiButtonInputWidget( config
) {
8633 // Configuration initialization
8634 config
= $.extend( { type
: 'button', useInputTag
: false }, config
);
8636 // See InputWidget#reusePreInfuseDOM about config.$input
8637 if ( config
.$input
) {
8638 config
.$input
.empty();
8641 // Properties (must be set before parent constructor, which calls #setValue)
8642 this.useInputTag
= config
.useInputTag
;
8644 // Parent constructor
8645 OO
.ui
.ButtonInputWidget
.parent
.call( this, config
);
8647 // Mixin constructors
8648 OO
.ui
.mixin
.ButtonElement
.call( this, $.extend( {}, config
, { $button
: this.$input
} ) );
8649 OO
.ui
.mixin
.IconElement
.call( this, config
);
8650 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
8651 OO
.ui
.mixin
.LabelElement
.call( this, config
);
8652 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
8655 if ( !config
.useInputTag
) {
8656 this.$input
.append( this.$icon
, this.$label
, this.$indicator
);
8658 this.$element
.addClass( 'oo-ui-buttonInputWidget' );
8663 OO
.inheritClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.InputWidget
);
8664 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.ButtonElement
);
8665 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IconElement
);
8666 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
8667 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.LabelElement
);
8668 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.TitledElement
);
8670 /* Static Properties */
8676 OO
.ui
.ButtonInputWidget
.static.tagName
= 'span';
8684 OO
.ui
.ButtonInputWidget
.prototype.getInputElement = function ( config
) {
8686 type
= [ 'button', 'submit', 'reset' ].indexOf( config
.type
) !== -1 ? config
.type
: 'button';
8687 return $( '<' + ( config
.useInputTag
? 'input' : 'button' ) + ' type="' + type
+ '">' );
8693 * If #useInputTag is `true`, the label is set as the `value` of the `<input>` tag.
8695 * @param {jQuery|string|Function|null} label Label nodes, text, a function that returns nodes or
8696 * text, or `null` for no label
8699 OO
.ui
.ButtonInputWidget
.prototype.setLabel = function ( label
) {
8700 if ( typeof label
=== 'function' ) {
8701 label
= OO
.ui
.resolveMsg( label
);
8704 if ( this.useInputTag
) {
8705 // Discard non-plaintext labels
8706 if ( typeof label
!== 'string' ) {
8710 this.$input
.val( label
);
8713 return OO
.ui
.mixin
.LabelElement
.prototype.setLabel
.call( this, label
);
8717 * Set the value of the input.
8719 * This method is disabled for button inputs configured as {@link #useInputTag <input> tags}, as
8720 * they do not support {@link #value values}.
8722 * @param {string} value New value
8725 OO
.ui
.ButtonInputWidget
.prototype.setValue = function ( value
) {
8726 if ( !this.useInputTag
) {
8727 OO
.ui
.ButtonInputWidget
.parent
.prototype.setValue
.call( this, value
);
8735 OO
.ui
.ButtonInputWidget
.prototype.getInputId = function () {
8736 // Disable generating `<label>` elements for buttons. One would very rarely need additional label
8737 // for a button, and it's already a big clickable target, and it causes unexpected rendering.
8742 * CheckboxInputWidgets, like HTML checkboxes, can be selected and/or configured with a value.
8743 * Note that these {@link OO.ui.InputWidget input widgets} are best laid out
8744 * in {@link OO.ui.FieldLayout field layouts} that use the {@link OO.ui.FieldLayout#align inline}
8745 * alignment. For more information, please see the [OOjs UI documentation on MediaWiki][1].
8747 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
8750 * // An example of selected, unselected, and disabled checkbox inputs
8751 * var checkbox1=new OO.ui.CheckboxInputWidget( {
8755 * var checkbox2=new OO.ui.CheckboxInputWidget( {
8758 * var checkbox3=new OO.ui.CheckboxInputWidget( {
8762 * // Create a fieldset layout with fields for each checkbox.
8763 * var fieldset = new OO.ui.FieldsetLayout( {
8764 * label: 'Checkboxes'
8766 * fieldset.addItems( [
8767 * new OO.ui.FieldLayout( checkbox1, { label: 'Selected checkbox', align: 'inline' } ),
8768 * new OO.ui.FieldLayout( checkbox2, { label: 'Unselected checkbox', align: 'inline' } ),
8769 * new OO.ui.FieldLayout( checkbox3, { label: 'Disabled checkbox', align: 'inline' } ),
8771 * $( 'body' ).append( fieldset.$element );
8773 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8776 * @extends OO.ui.InputWidget
8779 * @param {Object} [config] Configuration options
8780 * @cfg {boolean} [selected=false] Select the checkbox initially. By default, the checkbox is not selected.
8782 OO
.ui
.CheckboxInputWidget
= function OoUiCheckboxInputWidget( config
) {
8783 // Configuration initialization
8784 config
= config
|| {};
8786 // Parent constructor
8787 OO
.ui
.CheckboxInputWidget
.parent
.call( this, config
);
8791 .addClass( 'oo-ui-checkboxInputWidget' )
8792 // Required for pretty styling in WikimediaUI theme
8793 .append( $( '<span>' ) );
8794 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
8799 OO
.inheritClass( OO
.ui
.CheckboxInputWidget
, OO
.ui
.InputWidget
);
8801 /* Static Properties */
8807 OO
.ui
.CheckboxInputWidget
.static.tagName
= 'span';
8809 /* Static Methods */
8814 OO
.ui
.CheckboxInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8815 var state
= OO
.ui
.CheckboxInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8816 state
.checked
= config
.$input
.prop( 'checked' );
8826 OO
.ui
.CheckboxInputWidget
.prototype.getInputElement = function () {
8827 return $( '<input>' ).attr( 'type', 'checkbox' );
8833 OO
.ui
.CheckboxInputWidget
.prototype.onEdit = function () {
8835 if ( !this.isDisabled() ) {
8836 // Allow the stack to clear so the value will be updated
8837 setTimeout( function () {
8838 widget
.setSelected( widget
.$input
.prop( 'checked' ) );
8844 * Set selection state of this checkbox.
8846 * @param {boolean} state `true` for selected
8849 OO
.ui
.CheckboxInputWidget
.prototype.setSelected = function ( state
) {
8851 if ( this.selected
!== state
) {
8852 this.selected
= state
;
8853 this.$input
.prop( 'checked', this.selected
);
8854 this.emit( 'change', this.selected
);
8860 * Check if this checkbox is selected.
8862 * @return {boolean} Checkbox is selected
8864 OO
.ui
.CheckboxInputWidget
.prototype.isSelected = function () {
8865 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
8866 // it, and we won't know unless they're kind enough to trigger a 'change' event.
8867 var selected
= this.$input
.prop( 'checked' );
8868 if ( this.selected
!== selected
) {
8869 this.setSelected( selected
);
8871 return this.selected
;
8877 OO
.ui
.CheckboxInputWidget
.prototype.simulateLabelClick = function () {
8878 if ( !this.isDisabled() ) {
8879 this.$input
.click();
8887 OO
.ui
.CheckboxInputWidget
.prototype.restorePreInfuseState = function ( state
) {
8888 OO
.ui
.CheckboxInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8889 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
8890 this.setSelected( state
.checked
);
8895 * DropdownInputWidget is a {@link OO.ui.DropdownWidget DropdownWidget} intended to be used
8896 * within an HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
8897 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
8898 * more information about input widgets.
8900 * A DropdownInputWidget always has a value (one of the options is always selected), unless there
8901 * are no options. If no `value` configuration option is provided, the first option is selected.
8902 * If you need a state representing no value (no option being selected), use a DropdownWidget.
8904 * This and OO.ui.RadioSelectInputWidget support the same configuration options.
8907 * // Example: A DropdownInputWidget with three options
8908 * var dropdownInput = new OO.ui.DropdownInputWidget( {
8910 * { data: 'a', label: 'First' },
8911 * { data: 'b', label: 'Second'},
8912 * { data: 'c', label: 'Third' }
8915 * $( 'body' ).append( dropdownInput.$element );
8917 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8920 * @extends OO.ui.InputWidget
8921 * @mixins OO.ui.mixin.TitledElement
8924 * @param {Object} [config] Configuration options
8925 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
8926 * @cfg {Object} [dropdown] Configuration options for {@link OO.ui.DropdownWidget DropdownWidget}
8928 OO
.ui
.DropdownInputWidget
= function OoUiDropdownInputWidget( config
) {
8929 // Configuration initialization
8930 config
= config
|| {};
8932 // See InputWidget#reusePreInfuseDOM about config.$input
8933 if ( config
.$input
) {
8934 config
.$input
.addClass( 'oo-ui-element-hidden' );
8937 // Properties (must be done before parent constructor which calls #setDisabled)
8938 this.dropdownWidget
= new OO
.ui
.DropdownWidget( config
.dropdown
);
8940 // Parent constructor
8941 OO
.ui
.DropdownInputWidget
.parent
.call( this, config
);
8943 // Mixin constructors
8944 OO
.ui
.mixin
.TitledElement
.call( this, config
);
8947 this.dropdownWidget
.getMenu().connect( this, { select
: 'onMenuSelect' } );
8950 this.setOptions( config
.options
|| [] );
8951 // Set the value again, after we did setOptions(). The call from parent doesn't work because the
8952 // widget has no valid options when it happens.
8953 this.setValue( config
.value
);
8955 .addClass( 'oo-ui-dropdownInputWidget' )
8956 .append( this.dropdownWidget
.$element
);
8957 this.setTabIndexedElement( null );
8962 OO
.inheritClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.InputWidget
);
8963 OO
.mixinClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.mixin
.TitledElement
);
8971 OO
.ui
.DropdownInputWidget
.prototype.getInputElement = function () {
8972 return $( '<input>' ).attr( 'type', 'hidden' );
8976 * Handles menu select events.
8979 * @param {OO.ui.MenuOptionWidget|null} item Selected menu item
8981 OO
.ui
.DropdownInputWidget
.prototype.onMenuSelect = function ( item
) {
8982 this.setValue( item
? item
.getData() : '' );
8988 OO
.ui
.DropdownInputWidget
.prototype.setValue = function ( value
) {
8990 value
= this.cleanUpValue( value
);
8991 // Only allow setting values that are actually present in the dropdown
8992 selected
= this.dropdownWidget
.getMenu().getItemFromData( value
) ||
8993 this.dropdownWidget
.getMenu().findFirstSelectableItem();
8994 this.dropdownWidget
.getMenu().selectItem( selected
);
8995 value
= selected
? selected
.getData() : '';
8996 OO
.ui
.DropdownInputWidget
.parent
.prototype.setValue
.call( this, value
);
9003 OO
.ui
.DropdownInputWidget
.prototype.setDisabled = function ( state
) {
9004 this.dropdownWidget
.setDisabled( state
);
9005 OO
.ui
.DropdownInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
9010 * Set the options available for this input.
9012 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
9015 OO
.ui
.DropdownInputWidget
.prototype.setOptions = function ( options
) {
9017 value
= this.getValue(),
9020 // Rebuild the dropdown menu
9021 this.dropdownWidget
.getMenu()
9023 .addItems( options
.map( function ( opt
) {
9024 var optValue
= widget
.cleanUpValue( opt
.data
);
9026 if ( opt
.optgroup
=== undefined ) {
9027 return new OO
.ui
.MenuOptionWidget( {
9029 label
: opt
.label
!== undefined ? opt
.label
: optValue
9032 return new OO
.ui
.MenuSectionOptionWidget( {
9038 // Restore the previous value, or reset to something sensible
9039 if ( this.dropdownWidget
.getMenu().getItemFromData( value
) ) {
9040 // Previous value is still available, ensure consistency with the dropdown
9041 this.setValue( value
);
9043 // No longer valid, reset
9044 if ( options
.length
) {
9045 this.setValue( options
[ 0 ].data
);
9055 OO
.ui
.DropdownInputWidget
.prototype.focus = function () {
9056 this.dropdownWidget
.focus();
9063 OO
.ui
.DropdownInputWidget
.prototype.blur = function () {
9064 this.dropdownWidget
.blur();
9069 * RadioInputWidget creates a single radio button. Because radio buttons are usually used as a set,
9070 * in most cases you will want to use a {@link OO.ui.RadioSelectWidget radio select}
9071 * with {@link OO.ui.RadioOptionWidget radio options} instead of this class. For more information,
9072 * please see the [OOjs UI documentation on MediaWiki][1].
9074 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
9077 * // An example of selected, unselected, and disabled radio inputs
9078 * var radio1 = new OO.ui.RadioInputWidget( {
9082 * var radio2 = new OO.ui.RadioInputWidget( {
9085 * var radio3 = new OO.ui.RadioInputWidget( {
9089 * // Create a fieldset layout with fields for each radio button.
9090 * var fieldset = new OO.ui.FieldsetLayout( {
9091 * label: 'Radio inputs'
9093 * fieldset.addItems( [
9094 * new OO.ui.FieldLayout( radio1, { label: 'Selected', align: 'inline' } ),
9095 * new OO.ui.FieldLayout( radio2, { label: 'Unselected', align: 'inline' } ),
9096 * new OO.ui.FieldLayout( radio3, { label: 'Disabled', align: 'inline' } ),
9098 * $( 'body' ).append( fieldset.$element );
9100 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
9103 * @extends OO.ui.InputWidget
9106 * @param {Object} [config] Configuration options
9107 * @cfg {boolean} [selected=false] Select the radio button initially. By default, the radio button is not selected.
9109 OO
.ui
.RadioInputWidget
= function OoUiRadioInputWidget( config
) {
9110 // Configuration initialization
9111 config
= config
|| {};
9113 // Parent constructor
9114 OO
.ui
.RadioInputWidget
.parent
.call( this, config
);
9118 .addClass( 'oo-ui-radioInputWidget' )
9119 // Required for pretty styling in WikimediaUI theme
9120 .append( $( '<span>' ) );
9121 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
9126 OO
.inheritClass( OO
.ui
.RadioInputWidget
, OO
.ui
.InputWidget
);
9128 /* Static Properties */
9134 OO
.ui
.RadioInputWidget
.static.tagName
= 'span';
9136 /* Static Methods */
9141 OO
.ui
.RadioInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
9142 var state
= OO
.ui
.RadioInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
9143 state
.checked
= config
.$input
.prop( 'checked' );
9153 OO
.ui
.RadioInputWidget
.prototype.getInputElement = function () {
9154 return $( '<input>' ).attr( 'type', 'radio' );
9160 OO
.ui
.RadioInputWidget
.prototype.onEdit = function () {
9161 // RadioInputWidget doesn't track its state.
9165 * Set selection state of this radio button.
9167 * @param {boolean} state `true` for selected
9170 OO
.ui
.RadioInputWidget
.prototype.setSelected = function ( state
) {
9171 // RadioInputWidget doesn't track its state.
9172 this.$input
.prop( 'checked', state
);
9177 * Check if this radio button is selected.
9179 * @return {boolean} Radio is selected
9181 OO
.ui
.RadioInputWidget
.prototype.isSelected = function () {
9182 return this.$input
.prop( 'checked' );
9188 OO
.ui
.RadioInputWidget
.prototype.simulateLabelClick = function () {
9189 if ( !this.isDisabled() ) {
9190 this.$input
.click();
9198 OO
.ui
.RadioInputWidget
.prototype.restorePreInfuseState = function ( state
) {
9199 OO
.ui
.RadioInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
9200 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
9201 this.setSelected( state
.checked
);
9206 * RadioSelectInputWidget is a {@link OO.ui.RadioSelectWidget RadioSelectWidget} intended to be used
9207 * within an HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
9208 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
9209 * more information about input widgets.
9211 * This and OO.ui.DropdownInputWidget support the same configuration options.
9214 * // Example: A RadioSelectInputWidget with three options
9215 * var radioSelectInput = new OO.ui.RadioSelectInputWidget( {
9217 * { data: 'a', label: 'First' },
9218 * { data: 'b', label: 'Second'},
9219 * { data: 'c', label: 'Third' }
9222 * $( 'body' ).append( radioSelectInput.$element );
9224 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
9227 * @extends OO.ui.InputWidget
9230 * @param {Object} [config] Configuration options
9231 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
9233 OO
.ui
.RadioSelectInputWidget
= function OoUiRadioSelectInputWidget( config
) {
9234 // Configuration initialization
9235 config
= config
|| {};
9237 // Properties (must be done before parent constructor which calls #setDisabled)
9238 this.radioSelectWidget
= new OO
.ui
.RadioSelectWidget();
9240 // Parent constructor
9241 OO
.ui
.RadioSelectInputWidget
.parent
.call( this, config
);
9244 this.radioSelectWidget
.connect( this, { select
: 'onMenuSelect' } );
9247 this.setOptions( config
.options
|| [] );
9249 .addClass( 'oo-ui-radioSelectInputWidget' )
9250 .append( this.radioSelectWidget
.$element
);
9251 this.setTabIndexedElement( null );
9256 OO
.inheritClass( OO
.ui
.RadioSelectInputWidget
, OO
.ui
.InputWidget
);
9258 /* Static Methods */
9263 OO
.ui
.RadioSelectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
9264 var state
= OO
.ui
.RadioSelectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
9265 state
.value
= $( node
).find( '.oo-ui-radioInputWidget .oo-ui-inputWidget-input:checked' ).val();
9272 OO
.ui
.RadioSelectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
9273 config
= OO
.ui
.RadioSelectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
9274 // Cannot reuse the `<input type=radio>` set
9275 delete config
.$input
;
9285 OO
.ui
.RadioSelectInputWidget
.prototype.getInputElement = function () {
9286 return $( '<input>' ).attr( 'type', 'hidden' );
9290 * Handles menu select events.
9293 * @param {OO.ui.RadioOptionWidget} item Selected menu item
9295 OO
.ui
.RadioSelectInputWidget
.prototype.onMenuSelect = function ( item
) {
9296 this.setValue( item
.getData() );
9302 OO
.ui
.RadioSelectInputWidget
.prototype.setValue = function ( value
) {
9303 value
= this.cleanUpValue( value
);
9304 this.radioSelectWidget
.selectItemByData( value
);
9305 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setValue
.call( this, value
);
9312 OO
.ui
.RadioSelectInputWidget
.prototype.setDisabled = function ( state
) {
9313 this.radioSelectWidget
.setDisabled( state
);
9314 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
9319 * Set the options available for this input.
9321 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
9324 OO
.ui
.RadioSelectInputWidget
.prototype.setOptions = function ( options
) {
9326 value
= this.getValue(),
9329 // Rebuild the radioSelect menu
9330 this.radioSelectWidget
9332 .addItems( options
.map( function ( opt
) {
9333 var optValue
= widget
.cleanUpValue( opt
.data
);
9334 return new OO
.ui
.RadioOptionWidget( {
9336 label
: opt
.label
!== undefined ? opt
.label
: optValue
9340 // Restore the previous value, or reset to something sensible
9341 if ( this.radioSelectWidget
.getItemFromData( value
) ) {
9342 // Previous value is still available, ensure consistency with the radioSelect
9343 this.setValue( value
);
9345 // No longer valid, reset
9346 if ( options
.length
) {
9347 this.setValue( options
[ 0 ].data
);
9357 OO
.ui
.RadioSelectInputWidget
.prototype.focus = function () {
9358 this.radioSelectWidget
.focus();
9365 OO
.ui
.RadioSelectInputWidget
.prototype.blur = function () {
9366 this.radioSelectWidget
.blur();
9371 * CheckboxMultiselectInputWidget is a
9372 * {@link OO.ui.CheckboxMultiselectWidget CheckboxMultiselectWidget} intended to be used within a
9373 * HTML form, such as a OO.ui.FormLayout. The selected values are synchronized with the value of
9374 * HTML `<input type=checkbox>` tags. Please see the [OOjs UI documentation on MediaWiki][1] for
9375 * more information about input widgets.
9378 * // Example: A CheckboxMultiselectInputWidget with three options
9379 * var multiselectInput = new OO.ui.CheckboxMultiselectInputWidget( {
9381 * { data: 'a', label: 'First' },
9382 * { data: 'b', label: 'Second'},
9383 * { data: 'c', label: 'Third' }
9386 * $( 'body' ).append( multiselectInput.$element );
9388 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
9391 * @extends OO.ui.InputWidget
9394 * @param {Object} [config] Configuration options
9395 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: …, disabled: … }`
9397 OO
.ui
.CheckboxMultiselectInputWidget
= function OoUiCheckboxMultiselectInputWidget( config
) {
9398 // Configuration initialization
9399 config
= config
|| {};
9401 // Properties (must be done before parent constructor which calls #setDisabled)
9402 this.checkboxMultiselectWidget
= new OO
.ui
.CheckboxMultiselectWidget();
9404 // Parent constructor
9405 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.call( this, config
);
9408 this.inputName
= config
.name
;
9412 .addClass( 'oo-ui-checkboxMultiselectInputWidget' )
9413 .append( this.checkboxMultiselectWidget
.$element
);
9414 // We don't use this.$input, but rather the CheckboxInputWidgets inside each option
9415 this.$input
.detach();
9416 this.setOptions( config
.options
|| [] );
9417 // Have to repeat this from parent, as we need options to be set up for this to make sense
9418 this.setValue( config
.value
);
9420 // setValue when checkboxMultiselectWidget changes
9421 this.checkboxMultiselectWidget
.on( 'change', function () {
9422 this.setValue( this.checkboxMultiselectWidget
.getSelectedItemsData() );
9428 OO
.inheritClass( OO
.ui
.CheckboxMultiselectInputWidget
, OO
.ui
.InputWidget
);
9430 /* Static Methods */
9435 OO
.ui
.CheckboxMultiselectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
9436 var state
= OO
.ui
.CheckboxMultiselectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
9437 state
.value
= $( node
).find( '.oo-ui-checkboxInputWidget .oo-ui-inputWidget-input:checked' )
9438 .toArray().map( function ( el
) { return el
.value
; } );
9445 OO
.ui
.CheckboxMultiselectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
9446 config
= OO
.ui
.CheckboxMultiselectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
9447 // Cannot reuse the `<input type=checkbox>` set
9448 delete config
.$input
;
9458 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.getInputElement = function () {
9460 return $( '<unused>' );
9466 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.getValue = function () {
9467 var value
= this.$element
.find( '.oo-ui-checkboxInputWidget .oo-ui-inputWidget-input:checked' )
9468 .toArray().map( function ( el
) { return el
.value
; } );
9469 if ( this.value
!== value
) {
9470 this.setValue( value
);
9478 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setValue = function ( value
) {
9479 value
= this.cleanUpValue( value
);
9480 this.checkboxMultiselectWidget
.selectItemsByData( value
);
9481 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.setValue
.call( this, value
);
9486 * Clean up incoming value.
9488 * @param {string[]} value Original value
9489 * @return {string[]} Cleaned up value
9491 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.cleanUpValue = function ( value
) {
9494 if ( !Array
.isArray( value
) ) {
9497 for ( i
= 0; i
< value
.length
; i
++ ) {
9499 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.cleanUpValue
.call( this, value
[ i
] );
9500 // Remove options that we don't have here
9501 if ( !this.checkboxMultiselectWidget
.getItemFromData( singleValue
) ) {
9504 cleanValue
.push( singleValue
);
9512 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setDisabled = function ( state
) {
9513 this.checkboxMultiselectWidget
.setDisabled( state
);
9514 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
9519 * Set the options available for this input.
9521 * @param {Object[]} options Array of menu options in the format `{ data: …, label: …, disabled: … }`
9524 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setOptions = function ( options
) {
9527 // Rebuild the checkboxMultiselectWidget menu
9528 this.checkboxMultiselectWidget
9530 .addItems( options
.map( function ( opt
) {
9531 var optValue
, item
, optDisabled
;
9533 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.cleanUpValue
.call( widget
, opt
.data
);
9534 optDisabled
= opt
.disabled
!== undefined ? opt
.disabled
: false;
9535 item
= new OO
.ui
.CheckboxMultioptionWidget( {
9537 label
: opt
.label
!== undefined ? opt
.label
: optValue
,
9538 disabled
: optDisabled
9540 // Set the 'name' and 'value' for form submission
9541 item
.checkbox
.$input
.attr( 'name', widget
.inputName
);
9542 item
.checkbox
.setValue( optValue
);
9546 // Re-set the value, checking the checkboxes as needed.
9547 // This will also get rid of any stale options that we just removed.
9548 this.setValue( this.getValue() );
9556 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.focus = function () {
9557 this.checkboxMultiselectWidget
.focus();
9562 * TextInputWidgets, like HTML text inputs, can be configured with options that customize the
9563 * size of the field as well as its presentation. In addition, these widgets can be configured
9564 * with {@link OO.ui.mixin.IconElement icons}, {@link OO.ui.mixin.IndicatorElement indicators}, an optional
9565 * validation-pattern (used to determine if an input value is valid or not) and an input filter,
9566 * which modifies incoming values rather than validating them.
9567 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
9569 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
9572 * // Example of a text input widget
9573 * var textInput = new OO.ui.TextInputWidget( {
9574 * value: 'Text input'
9576 * $( 'body' ).append( textInput.$element );
9578 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
9581 * @extends OO.ui.InputWidget
9582 * @mixins OO.ui.mixin.IconElement
9583 * @mixins OO.ui.mixin.IndicatorElement
9584 * @mixins OO.ui.mixin.PendingElement
9585 * @mixins OO.ui.mixin.LabelElement
9588 * @param {Object} [config] Configuration options
9589 * @cfg {string} [type='text'] The value of the HTML `type` attribute: 'text', 'password'
9590 * 'email', 'url' or 'number'.
9591 * @cfg {string} [placeholder] Placeholder text
9592 * @cfg {boolean} [autofocus=false] Use an HTML `autofocus` attribute to
9593 * instruct the browser to focus this widget.
9594 * @cfg {boolean} [readOnly=false] Prevent changes to the value of the text input.
9595 * @cfg {number} [maxLength] Maximum number of characters allowed in the input.
9596 * @cfg {string} [labelPosition='after'] The position of the inline label relative to that of
9597 * the value or placeholder text: `'before'` or `'after'`
9598 * @cfg {boolean} [required=false] Mark the field as required. Implies `indicator: 'required'`.
9599 * @cfg {boolean} [autocomplete=true] Should the browser support autocomplete for this field
9600 * @cfg {RegExp|Function|string} [validate] Validation pattern: when string, a symbolic name of a
9601 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer'
9602 * (the value must contain only numbers); when RegExp, a regular expression that must match the
9603 * value for it to be considered valid; when Function, a function receiving the value as parameter
9604 * that must return true, or promise resolving to true, for it to be considered valid.
9606 OO
.ui
.TextInputWidget
= function OoUiTextInputWidget( config
) {
9607 // Configuration initialization
9608 config
= $.extend( {
9610 labelPosition
: 'after'
9613 if ( config
.multiline
) {
9614 OO
.ui
.warnDeprecation( 'TextInputWidget: config.multiline is deprecated. Use the MultilineTextInputWidget instead. See T130434.' );
9615 return new OO
.ui
.MultilineTextInputWidget( config
);
9618 // Parent constructor
9619 OO
.ui
.TextInputWidget
.parent
.call( this, config
);
9621 // Mixin constructors
9622 OO
.ui
.mixin
.IconElement
.call( this, config
);
9623 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
9624 OO
.ui
.mixin
.PendingElement
.call( this, $.extend( {}, config
, { $pending
: this.$input
} ) );
9625 OO
.ui
.mixin
.LabelElement
.call( this, config
);
9628 this.type
= this.getSaneType( config
);
9629 this.readOnly
= false;
9630 this.required
= false;
9631 this.validate
= null;
9632 this.styleHeight
= null;
9633 this.scrollWidth
= null;
9635 this.setValidation( config
.validate
);
9636 this.setLabelPosition( config
.labelPosition
);
9640 keypress
: this.onKeyPress
.bind( this ),
9641 blur
: this.onBlur
.bind( this ),
9642 focus
: this.onFocus
.bind( this )
9644 this.$icon
.on( 'mousedown', this.onIconMouseDown
.bind( this ) );
9645 this.$indicator
.on( 'mousedown', this.onIndicatorMouseDown
.bind( this ) );
9646 this.on( 'labelChange', this.updatePosition
.bind( this ) );
9647 this.on( 'change', OO
.ui
.debounce( this.onDebouncedChange
.bind( this ), 250 ) );
9651 .addClass( 'oo-ui-textInputWidget oo-ui-textInputWidget-type-' + this.type
)
9652 .append( this.$icon
, this.$indicator
);
9653 this.setReadOnly( !!config
.readOnly
);
9654 this.setRequired( !!config
.required
);
9655 if ( config
.placeholder
!== undefined ) {
9656 this.$input
.attr( 'placeholder', config
.placeholder
);
9658 if ( config
.maxLength
!== undefined ) {
9659 this.$input
.attr( 'maxlength', config
.maxLength
);
9661 if ( config
.autofocus
) {
9662 this.$input
.attr( 'autofocus', 'autofocus' );
9664 if ( config
.autocomplete
=== false ) {
9665 this.$input
.attr( 'autocomplete', 'off' );
9666 // Turning off autocompletion also disables "form caching" when the user navigates to a
9667 // different page and then clicks "Back". Re-enable it when leaving. Borrowed from jQuery UI.
9669 beforeunload: function () {
9670 this.$input
.removeAttr( 'autocomplete' );
9672 pageshow: function () {
9673 // Browsers don't seem to actually fire this event on "Back", they instead just reload the
9674 // whole page... it shouldn't hurt, though.
9675 this.$input
.attr( 'autocomplete', 'off' );
9680 this.isWaitingToBeAttached
= true;
9681 this.installParentChangeDetector();
9687 OO
.inheritClass( OO
.ui
.TextInputWidget
, OO
.ui
.InputWidget
);
9688 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IconElement
);
9689 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
9690 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.PendingElement
);
9691 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.LabelElement
);
9693 /* Static Properties */
9695 OO
.ui
.TextInputWidget
.static.validationPatterns
= {
9700 /* Static Methods */
9705 OO
.ui
.TextInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
9706 var state
= OO
.ui
.TextInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
9713 * An `enter` event is emitted when the user presses 'enter' inside the text box.
9721 * Handle icon mouse down events.
9724 * @param {jQuery.Event} e Mouse down event
9726 OO
.ui
.TextInputWidget
.prototype.onIconMouseDown = function ( e
) {
9727 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
9734 * Handle indicator mouse down events.
9737 * @param {jQuery.Event} e Mouse down event
9739 OO
.ui
.TextInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
9740 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
9747 * Handle key press events.
9750 * @param {jQuery.Event} e Key press event
9751 * @fires enter If enter key is pressed
9753 OO
.ui
.TextInputWidget
.prototype.onKeyPress = function ( e
) {
9754 if ( e
.which
=== OO
.ui
.Keys
.ENTER
) {
9755 this.emit( 'enter', e
);
9760 * Handle blur events.
9763 * @param {jQuery.Event} e Blur event
9765 OO
.ui
.TextInputWidget
.prototype.onBlur = function () {
9766 this.setValidityFlag();
9770 * Handle focus events.
9773 * @param {jQuery.Event} e Focus event
9775 OO
.ui
.TextInputWidget
.prototype.onFocus = function () {
9776 if ( this.isWaitingToBeAttached
) {
9777 // If we've received focus, then we must be attached to the document, and if
9778 // isWaitingToBeAttached is still true, that means the handler never fired. Fire it now.
9779 this.onElementAttach();
9781 this.setValidityFlag( true );
9785 * Handle element attach events.
9788 * @param {jQuery.Event} e Element attach event
9790 OO
.ui
.TextInputWidget
.prototype.onElementAttach = function () {
9791 this.isWaitingToBeAttached
= false;
9792 // Any previously calculated size is now probably invalid if we reattached elsewhere
9793 this.valCache
= null;
9794 this.positionLabel();
9798 * Handle debounced change events.
9800 * @param {string} value
9803 OO
.ui
.TextInputWidget
.prototype.onDebouncedChange = function () {
9804 this.setValidityFlag();
9808 * Check if the input is {@link #readOnly read-only}.
9812 OO
.ui
.TextInputWidget
.prototype.isReadOnly = function () {
9813 return this.readOnly
;
9817 * Set the {@link #readOnly read-only} state of the input.
9819 * @param {boolean} state Make input read-only
9822 OO
.ui
.TextInputWidget
.prototype.setReadOnly = function ( state
) {
9823 this.readOnly
= !!state
;
9824 this.$input
.prop( 'readOnly', this.readOnly
);
9829 * Check if the input is {@link #required required}.
9833 OO
.ui
.TextInputWidget
.prototype.isRequired = function () {
9834 return this.required
;
9838 * Set the {@link #required required} state of the input.
9840 * @param {boolean} state Make input required
9843 OO
.ui
.TextInputWidget
.prototype.setRequired = function ( state
) {
9844 this.required
= !!state
;
9845 if ( this.required
) {
9847 .prop( 'required', true )
9848 .attr( 'aria-required', 'true' );
9849 if ( this.getIndicator() === null ) {
9850 this.setIndicator( 'required' );
9854 .prop( 'required', false )
9855 .removeAttr( 'aria-required' );
9856 if ( this.getIndicator() === 'required' ) {
9857 this.setIndicator( null );
9864 * Support function for making #onElementAttach work across browsers.
9866 * This whole function could be replaced with one line of code using the DOMNodeInsertedIntoDocument
9867 * event, but it's not supported by Firefox and allegedly deprecated, so we only use it as fallback.
9869 * Due to MutationObserver performance woes, #onElementAttach is only somewhat reliably called the
9870 * first time that the element gets attached to the documented.
9872 OO
.ui
.TextInputWidget
.prototype.installParentChangeDetector = function () {
9873 var mutationObserver
, onRemove
, topmostNode
, fakeParentNode
,
9874 MutationObserver
= window
.MutationObserver
|| window
.WebKitMutationObserver
|| window
.MozMutationObserver
,
9877 if ( MutationObserver
) {
9878 // The new way. If only it wasn't so ugly.
9880 if ( this.isElementAttached() ) {
9881 // Widget is attached already, do nothing. This breaks the functionality of this function when
9882 // the widget is detached and reattached. Alas, doing this correctly with MutationObserver
9883 // would require observation of the whole document, which would hurt performance of other,
9884 // more important code.
9888 // Find topmost node in the tree
9889 topmostNode
= this.$element
[ 0 ];
9890 while ( topmostNode
.parentNode
) {
9891 topmostNode
= topmostNode
.parentNode
;
9894 // We have no way to detect the $element being attached somewhere without observing the entire
9895 // DOM with subtree modifications, which would hurt performance. So we cheat: we hook to the
9896 // parent node of $element, and instead detect when $element is removed from it (and thus
9897 // probably attached somewhere else). If there is no parent, we create a "fake" one. If it
9898 // doesn't get attached, we end up back here and create the parent.
9900 mutationObserver
= new MutationObserver( function ( mutations
) {
9901 var i
, j
, removedNodes
;
9902 for ( i
= 0; i
< mutations
.length
; i
++ ) {
9903 removedNodes
= mutations
[ i
].removedNodes
;
9904 for ( j
= 0; j
< removedNodes
.length
; j
++ ) {
9905 if ( removedNodes
[ j
] === topmostNode
) {
9906 setTimeout( onRemove
, 0 );
9913 onRemove = function () {
9914 // If the node was attached somewhere else, report it
9915 if ( widget
.isElementAttached() ) {
9916 widget
.onElementAttach();
9918 mutationObserver
.disconnect();
9919 widget
.installParentChangeDetector();
9922 // Create a fake parent and observe it
9923 fakeParentNode
= $( '<div>' ).append( topmostNode
)[ 0 ];
9924 mutationObserver
.observe( fakeParentNode
, { childList
: true } );
9926 // Using the DOMNodeInsertedIntoDocument event is much nicer and less magical, and works for
9927 // detachment and reattachment, but it's not supported by Firefox and allegedly deprecated.
9928 this.$element
.on( 'DOMNodeInsertedIntoDocument', this.onElementAttach
.bind( this ) );
9936 OO
.ui
.TextInputWidget
.prototype.getInputElement = function ( config
) {
9937 if ( this.getSaneType( config
) === 'number' ) {
9938 return $( '<input>' )
9939 .attr( 'step', 'any' )
9940 .attr( 'type', 'number' );
9942 return $( '<input>' ).attr( 'type', this.getSaneType( config
) );
9947 * Get sanitized value for 'type' for given config.
9949 * @param {Object} config Configuration options
9950 * @return {string|null}
9953 OO
.ui
.TextInputWidget
.prototype.getSaneType = function ( config
) {
9954 var allowedTypes
= [
9961 return allowedTypes
.indexOf( config
.type
) !== -1 ? config
.type
: 'text';
9965 * Focus the input and select a specified range within the text.
9967 * @param {number} from Select from offset
9968 * @param {number} [to] Select to offset, defaults to from
9971 OO
.ui
.TextInputWidget
.prototype.selectRange = function ( from, to
) {
9972 var isBackwards
, start
, end
,
9973 input
= this.$input
[ 0 ];
9977 isBackwards
= to
< from;
9978 start
= isBackwards
? to
: from;
9979 end
= isBackwards
? from : to
;
9984 input
.setSelectionRange( start
, end
, isBackwards
? 'backward' : 'forward' );
9986 // IE throws an exception if you call setSelectionRange on a unattached DOM node.
9987 // Rather than expensively check if the input is attached every time, just check
9988 // if it was the cause of an error being thrown. If not, rethrow the error.
9989 if ( this.getElementDocument().body
.contains( input
) ) {
9997 * Get an object describing the current selection range in a directional manner
9999 * @return {Object} Object containing 'from' and 'to' offsets
10001 OO
.ui
.TextInputWidget
.prototype.getRange = function () {
10002 var input
= this.$input
[ 0 ],
10003 start
= input
.selectionStart
,
10004 end
= input
.selectionEnd
,
10005 isBackwards
= input
.selectionDirection
=== 'backward';
10008 from: isBackwards
? end
: start
,
10009 to
: isBackwards
? start
: end
10014 * Get the length of the text input value.
10016 * This could differ from the length of #getValue if the
10017 * value gets filtered
10019 * @return {number} Input length
10021 OO
.ui
.TextInputWidget
.prototype.getInputLength = function () {
10022 return this.$input
[ 0 ].value
.length
;
10026 * Focus the input and select the entire text.
10030 OO
.ui
.TextInputWidget
.prototype.select = function () {
10031 return this.selectRange( 0, this.getInputLength() );
10035 * Focus the input and move the cursor to the start.
10039 OO
.ui
.TextInputWidget
.prototype.moveCursorToStart = function () {
10040 return this.selectRange( 0 );
10044 * Focus the input and move the cursor to the end.
10048 OO
.ui
.TextInputWidget
.prototype.moveCursorToEnd = function () {
10049 return this.selectRange( this.getInputLength() );
10053 * Insert new content into the input.
10055 * @param {string} content Content to be inserted
10058 OO
.ui
.TextInputWidget
.prototype.insertContent = function ( content
) {
10060 range
= this.getRange(),
10061 value
= this.getValue();
10063 start
= Math
.min( range
.from, range
.to
);
10064 end
= Math
.max( range
.from, range
.to
);
10066 this.setValue( value
.slice( 0, start
) + content
+ value
.slice( end
) );
10067 this.selectRange( start
+ content
.length
);
10072 * Insert new content either side of a selection.
10074 * @param {string} pre Content to be inserted before the selection
10075 * @param {string} post Content to be inserted after the selection
10078 OO
.ui
.TextInputWidget
.prototype.encapsulateContent = function ( pre
, post
) {
10080 range
= this.getRange(),
10081 offset
= pre
.length
;
10083 start
= Math
.min( range
.from, range
.to
);
10084 end
= Math
.max( range
.from, range
.to
);
10086 this.selectRange( start
).insertContent( pre
);
10087 this.selectRange( offset
+ end
).insertContent( post
);
10089 this.selectRange( offset
+ start
, offset
+ end
);
10094 * Set the validation pattern.
10096 * The validation pattern is either a regular expression, a function, or the symbolic name of a
10097 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer' (the
10098 * value must contain only numbers).
10100 * @param {RegExp|Function|string|null} validate Regular expression, function, or the symbolic name
10101 * of a pattern (either ‘integer’ or ‘non-empty’) defined by the class.
10103 OO
.ui
.TextInputWidget
.prototype.setValidation = function ( validate
) {
10104 if ( validate
instanceof RegExp
|| validate
instanceof Function
) {
10105 this.validate
= validate
;
10107 this.validate
= this.constructor.static.validationPatterns
[ validate
] || /.*/;
10112 * Sets the 'invalid' flag appropriately.
10114 * @param {boolean} [isValid] Optionally override validation result
10116 OO
.ui
.TextInputWidget
.prototype.setValidityFlag = function ( isValid
) {
10118 setFlag = function ( valid
) {
10120 widget
.$input
.attr( 'aria-invalid', 'true' );
10122 widget
.$input
.removeAttr( 'aria-invalid' );
10124 widget
.setFlags( { invalid
: !valid
} );
10127 if ( isValid
!== undefined ) {
10128 setFlag( isValid
);
10130 this.getValidity().then( function () {
10139 * Get the validity of current value.
10141 * This method returns a promise that resolves if the value is valid and rejects if
10142 * it isn't. Uses the {@link #validate validation pattern} to check for validity.
10144 * @return {jQuery.Promise} A promise that resolves if the value is valid, rejects if not.
10146 OO
.ui
.TextInputWidget
.prototype.getValidity = function () {
10149 function rejectOrResolve( valid
) {
10151 return $.Deferred().resolve().promise();
10153 return $.Deferred().reject().promise();
10157 // Check browser validity and reject if it is invalid
10159 this.$input
[ 0 ].checkValidity
!== undefined &&
10160 this.$input
[ 0 ].checkValidity() === false
10162 return rejectOrResolve( false );
10165 // Run our checks if the browser thinks the field is valid
10166 if ( this.validate
instanceof Function
) {
10167 result
= this.validate( this.getValue() );
10168 if ( result
&& $.isFunction( result
.promise
) ) {
10169 return result
.promise().then( function ( valid
) {
10170 return rejectOrResolve( valid
);
10173 return rejectOrResolve( result
);
10176 return rejectOrResolve( this.getValue().match( this.validate
) );
10181 * Set the position of the inline label relative to that of the value: `‘before’` or `‘after’`.
10183 * @param {string} labelPosition Label position, 'before' or 'after'
10186 OO
.ui
.TextInputWidget
.prototype.setLabelPosition = function ( labelPosition
) {
10187 this.labelPosition
= labelPosition
;
10188 if ( this.label
) {
10189 // If there is no label and we only change the position, #updatePosition is a no-op,
10190 // but it takes really a lot of work to do nothing.
10191 this.updatePosition();
10197 * Update the position of the inline label.
10199 * This method is called by #setLabelPosition, and can also be called on its own if
10200 * something causes the label to be mispositioned.
10204 OO
.ui
.TextInputWidget
.prototype.updatePosition = function () {
10205 var after
= this.labelPosition
=== 'after';
10208 .toggleClass( 'oo-ui-textInputWidget-labelPosition-after', !!this.label
&& after
)
10209 .toggleClass( 'oo-ui-textInputWidget-labelPosition-before', !!this.label
&& !after
);
10211 this.valCache
= null;
10212 this.scrollWidth
= null;
10213 this.positionLabel();
10219 * Position the label by setting the correct padding on the input.
10224 OO
.ui
.TextInputWidget
.prototype.positionLabel = function () {
10225 var after
, rtl
, property
, newCss
;
10227 if ( this.isWaitingToBeAttached
) {
10228 // #onElementAttach will be called soon, which calls this method
10233 'padding-right': '',
10237 if ( this.label
) {
10238 this.$element
.append( this.$label
);
10240 this.$label
.detach();
10241 // Clear old values if present
10242 this.$input
.css( newCss
);
10246 after
= this.labelPosition
=== 'after';
10247 rtl
= this.$element
.css( 'direction' ) === 'rtl';
10248 property
= after
=== rtl
? 'padding-left' : 'padding-right';
10250 newCss
[ property
] = this.$label
.outerWidth( true ) + ( after
? this.scrollWidth
: 0 );
10251 // We have to clear the padding on the other side, in case the element direction changed
10252 this.$input
.css( newCss
);
10260 OO
.ui
.TextInputWidget
.prototype.restorePreInfuseState = function ( state
) {
10261 OO
.ui
.TextInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
10262 if ( state
.scrollTop
!== undefined ) {
10263 this.$input
.scrollTop( state
.scrollTop
);
10269 * @extends OO.ui.TextInputWidget
10272 * @param {Object} [config] Configuration options
10274 OO
.ui
.SearchInputWidget
= function OoUiSearchInputWidget( config
) {
10275 config
= $.extend( {
10279 // Set type to text so that TextInputWidget doesn't
10280 // get stuck in an infinite loop.
10281 config
.type
= 'text';
10283 // Parent constructor
10284 OO
.ui
.SearchInputWidget
.parent
.call( this, config
);
10287 this.connect( this, {
10292 this.$element
.addClass( 'oo-ui-textInputWidget-type-search' );
10293 this.updateSearchIndicator();
10294 this.connect( this, {
10295 disable
: 'onDisable'
10301 OO
.inheritClass( OO
.ui
.SearchInputWidget
, OO
.ui
.TextInputWidget
);
10309 OO
.ui
.SearchInputWidget
.prototype.getInputElement = function () {
10310 return $( '<input>' ).attr( 'type', 'search' );
10316 OO
.ui
.SearchInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
10317 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
10318 // Clear the text field
10319 this.setValue( '' );
10326 * Update the 'clear' indicator displayed on type: 'search' text
10327 * fields, hiding it when the field is already empty or when it's not
10330 OO
.ui
.SearchInputWidget
.prototype.updateSearchIndicator = function () {
10331 if ( this.getValue() === '' || this.isDisabled() || this.isReadOnly() ) {
10332 this.setIndicator( null );
10334 this.setIndicator( 'clear' );
10339 * Handle change events.
10343 OO
.ui
.SearchInputWidget
.prototype.onChange = function () {
10344 this.updateSearchIndicator();
10348 * Handle disable events.
10350 * @param {boolean} disabled Element is disabled
10353 OO
.ui
.SearchInputWidget
.prototype.onDisable = function () {
10354 this.updateSearchIndicator();
10360 OO
.ui
.SearchInputWidget
.prototype.setReadOnly = function ( state
) {
10361 OO
.ui
.SearchInputWidget
.parent
.prototype.setReadOnly
.call( this, state
);
10362 this.updateSearchIndicator();
10368 * @extends OO.ui.TextInputWidget
10371 * @param {Object} [config] Configuration options
10372 * @cfg {number} [rows] Number of visible lines in textarea. If used with `autosize`,
10373 * specifies minimum number of rows to display.
10374 * @cfg {string} [labelPosition='after'] The position of the inline label relative to that of
10375 * @cfg {boolean} [autosize=false] Automatically resize the text input to fit its content.
10376 * Use the #maxRows config to specify a maximum number of displayed rows.
10377 * @cfg {boolean} [maxRows] Maximum number of rows to display when #autosize is set to true.
10378 * Defaults to the maximum of `10` and `2 * rows`, or `10` if `rows` isn't provided.
10380 OO
.ui
.MultilineTextInputWidget
= function OoUiMultilineTextInputWidget( config
) {
10381 config
= $.extend( {
10384 config
.multiline
= false;
10385 // Parent constructor
10386 OO
.ui
.MultilineTextInputWidget
.parent
.call( this, config
);
10389 this.multiline
= true;
10390 this.autosize
= !!config
.autosize
;
10391 this.minRows
= config
.rows
!== undefined ? config
.rows
: '';
10392 this.maxRows
= config
.maxRows
|| Math
.max( 2 * ( this.minRows
|| 0 ), 10 );
10394 // Clone for resizing
10395 if ( this.autosize
) {
10396 this.$clone
= this.$input
10398 .insertAfter( this.$input
)
10399 .attr( 'aria-hidden', 'true' )
10400 .addClass( 'oo-ui-element-hidden' );
10404 this.connect( this, {
10409 if ( this.multiline
&& config
.rows
) {
10410 this.$input
.attr( 'rows', config
.rows
);
10412 if ( this.autosize
) {
10413 this.isWaitingToBeAttached
= true;
10414 this.installParentChangeDetector();
10420 OO
.inheritClass( OO
.ui
.MultilineTextInputWidget
, OO
.ui
.TextInputWidget
);
10422 /* Static Methods */
10427 OO
.ui
.MultilineTextInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
10428 var state
= OO
.ui
.MultilineTextInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
10429 state
.scrollTop
= config
.$input
.scrollTop();
10438 OO
.ui
.MultilineTextInputWidget
.prototype.onElementAttach = function () {
10439 OO
.ui
.MultilineTextInputWidget
.parent
.prototype.onElementAttach
.call( this );
10444 * Handle change events.
10448 OO
.ui
.MultilineTextInputWidget
.prototype.onChange = function () {
10455 OO
.ui
.MultilineTextInputWidget
.prototype.updatePosition = function () {
10456 OO
.ui
.MultilineTextInputWidget
.parent
.prototype.updatePosition
.call( this );
10461 * Override TextInputWidget so it doesn't emit the 'enter' event.
10464 * @param {jQuery.Event} e Key press event
10466 OO
.ui
.MultilineTextInputWidget
.prototype.onKeyPress = function () {
10471 * Automatically adjust the size of the text input.
10473 * This only affects multiline inputs that are {@link #autosize autosized}.
10478 OO
.ui
.MultilineTextInputWidget
.prototype.adjustSize = function () {
10479 var scrollHeight
, innerHeight
, outerHeight
, maxInnerHeight
, measurementError
,
10480 idealHeight
, newHeight
, scrollWidth
, property
;
10482 if ( this.$input
.val() !== this.valCache
) {
10483 if ( this.autosize
) {
10485 .val( this.$input
.val() )
10486 .attr( 'rows', this.minRows
)
10487 // Set inline height property to 0 to measure scroll height
10488 .css( 'height', 0 );
10490 this.$clone
.removeClass( 'oo-ui-element-hidden' );
10492 this.valCache
= this.$input
.val();
10494 scrollHeight
= this.$clone
[ 0 ].scrollHeight
;
10496 // Remove inline height property to measure natural heights
10497 this.$clone
.css( 'height', '' );
10498 innerHeight
= this.$clone
.innerHeight();
10499 outerHeight
= this.$clone
.outerHeight();
10501 // Measure max rows height
10503 .attr( 'rows', this.maxRows
)
10504 .css( 'height', 'auto' )
10506 maxInnerHeight
= this.$clone
.innerHeight();
10508 // Difference between reported innerHeight and scrollHeight with no scrollbars present.
10509 // This is sometimes non-zero on Blink-based browsers, depending on zoom level.
10510 measurementError
= maxInnerHeight
- this.$clone
[ 0 ].scrollHeight
;
10511 idealHeight
= Math
.min( maxInnerHeight
, scrollHeight
+ measurementError
);
10513 this.$clone
.addClass( 'oo-ui-element-hidden' );
10515 // Only apply inline height when expansion beyond natural height is needed
10516 // Use the difference between the inner and outer height as a buffer
10517 newHeight
= idealHeight
> innerHeight
? idealHeight
+ ( outerHeight
- innerHeight
) : '';
10518 if ( newHeight
!== this.styleHeight
) {
10519 this.$input
.css( 'height', newHeight
);
10520 this.styleHeight
= newHeight
;
10521 this.emit( 'resize' );
10524 scrollWidth
= this.$input
[ 0 ].offsetWidth
- this.$input
[ 0 ].clientWidth
;
10525 if ( scrollWidth
!== this.scrollWidth
) {
10526 property
= this.$element
.css( 'direction' ) === 'rtl' ? 'left' : 'right';
10528 this.$label
.css( { right
: '', left
: '' } );
10529 this.$indicator
.css( { right
: '', left
: '' } );
10531 if ( scrollWidth
) {
10532 this.$indicator
.css( property
, scrollWidth
);
10533 if ( this.labelPosition
=== 'after' ) {
10534 this.$label
.css( property
, scrollWidth
);
10538 this.scrollWidth
= scrollWidth
;
10539 this.positionLabel();
10549 OO
.ui
.MultilineTextInputWidget
.prototype.getInputElement = function () {
10550 return $( '<textarea>' );
10554 * Check if the input supports multiple lines.
10556 * @return {boolean}
10558 OO
.ui
.MultilineTextInputWidget
.prototype.isMultiline = function () {
10559 return !!this.multiline
;
10563 * Check if the input automatically adjusts its size.
10565 * @return {boolean}
10567 OO
.ui
.MultilineTextInputWidget
.prototype.isAutosizing = function () {
10568 return !!this.autosize
;
10572 * ComboBoxInputWidgets combine a {@link OO.ui.TextInputWidget text input} (where a value
10573 * can be entered manually) and a {@link OO.ui.MenuSelectWidget menu of options} (from which
10574 * a value can be chosen instead). Users can choose options from the combo box in one of two ways:
10576 * - by typing a value in the text input field. If the value exactly matches the value of a menu
10577 * option, that option will appear to be selected.
10578 * - by choosing a value from the menu. The value of the chosen option will then appear in the text
10581 * After the user chooses an option, its `data` will be used as a new value for the widget.
10582 * A `label` also can be specified for each option: if given, it will be shown instead of the
10583 * `data` in the dropdown menu.
10585 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
10587 * For more information about menus and options, please see the [OOjs UI documentation on MediaWiki][1].
10590 * // Example: A ComboBoxInputWidget.
10591 * var comboBox = new OO.ui.ComboBoxInputWidget( {
10592 * value: 'Option 1',
10594 * { data: 'Option 1' },
10595 * { data: 'Option 2' },
10596 * { data: 'Option 3' }
10599 * $( 'body' ).append( comboBox.$element );
10602 * // Example: A ComboBoxInputWidget with additional option labels.
10603 * var comboBox = new OO.ui.ComboBoxInputWidget( {
10604 * value: 'Option 1',
10607 * data: 'Option 1',
10608 * label: 'Option One'
10611 * data: 'Option 2',
10612 * label: 'Option Two'
10615 * data: 'Option 3',
10616 * label: 'Option Three'
10620 * $( 'body' ).append( comboBox.$element );
10622 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
10625 * @extends OO.ui.TextInputWidget
10628 * @param {Object} [config] Configuration options
10629 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
10630 * @cfg {Object} [menu] Configuration options to pass to the {@link OO.ui.MenuSelectWidget menu select widget}.
10631 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
10632 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
10633 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
10634 * See <https://www.mediawiki.org/wiki/OOjs_UI/Concepts#Overlays>.
10636 OO
.ui
.ComboBoxInputWidget
= function OoUiComboBoxInputWidget( config
) {
10637 // Configuration initialization
10638 config
= $.extend( {
10639 autocomplete
: false
10642 // ComboBoxInputWidget shouldn't support `multiline`
10643 config
.multiline
= false;
10645 // See InputWidget#reusePreInfuseDOM about `config.$input`
10646 if ( config
.$input
) {
10647 config
.$input
.removeAttr( 'list' );
10650 // Parent constructor
10651 OO
.ui
.ComboBoxInputWidget
.parent
.call( this, config
);
10654 this.$overlay
= config
.$overlay
|| this.$element
;
10655 this.dropdownButton
= new OO
.ui
.ButtonWidget( {
10656 classes
: [ 'oo-ui-comboBoxInputWidget-dropdownButton' ],
10658 disabled
: this.disabled
10660 this.menu
= new OO
.ui
.MenuSelectWidget( $.extend(
10664 $floatableContainer
: this.$element
,
10665 disabled
: this.isDisabled()
10671 this.connect( this, {
10672 change
: 'onInputChange',
10673 enter
: 'onInputEnter'
10675 this.dropdownButton
.connect( this, {
10676 click
: 'onDropdownButtonClick'
10678 this.menu
.connect( this, {
10679 choose
: 'onMenuChoose',
10680 add
: 'onMenuItemsChange',
10681 remove
: 'onMenuItemsChange'
10685 this.$input
.attr( {
10687 'aria-owns': this.menu
.getElementId(),
10688 'aria-autocomplete': 'list'
10690 // Do not override options set via config.menu.items
10691 if ( config
.options
!== undefined ) {
10692 this.setOptions( config
.options
);
10694 this.$field
= $( '<div>' )
10695 .addClass( 'oo-ui-comboBoxInputWidget-field' )
10696 .append( this.$input
, this.dropdownButton
.$element
);
10698 .addClass( 'oo-ui-comboBoxInputWidget' )
10699 .append( this.$field
);
10700 this.$overlay
.append( this.menu
.$element
);
10701 this.onMenuItemsChange();
10706 OO
.inheritClass( OO
.ui
.ComboBoxInputWidget
, OO
.ui
.TextInputWidget
);
10711 * Get the combobox's menu.
10713 * @return {OO.ui.MenuSelectWidget} Menu widget
10715 OO
.ui
.ComboBoxInputWidget
.prototype.getMenu = function () {
10720 * Get the combobox's text input widget.
10722 * @return {OO.ui.TextInputWidget} Text input widget
10724 OO
.ui
.ComboBoxInputWidget
.prototype.getInput = function () {
10729 * Handle input change events.
10732 * @param {string} value New value
10734 OO
.ui
.ComboBoxInputWidget
.prototype.onInputChange = function ( value
) {
10735 var match
= this.menu
.getItemFromData( value
);
10737 this.menu
.selectItem( match
);
10738 if ( this.menu
.findHighlightedItem() ) {
10739 this.menu
.highlightItem( match
);
10742 if ( !this.isDisabled() ) {
10743 this.menu
.toggle( true );
10748 * Handle input enter events.
10752 OO
.ui
.ComboBoxInputWidget
.prototype.onInputEnter = function () {
10753 if ( !this.isDisabled() ) {
10754 this.menu
.toggle( false );
10759 * Handle button click events.
10763 OO
.ui
.ComboBoxInputWidget
.prototype.onDropdownButtonClick = function () {
10764 this.menu
.toggle();
10769 * Handle menu choose events.
10772 * @param {OO.ui.OptionWidget} item Chosen item
10774 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuChoose = function ( item
) {
10775 this.setValue( item
.getData() );
10779 * Handle menu item change events.
10783 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuItemsChange = function () {
10784 var match
= this.menu
.getItemFromData( this.getValue() );
10785 this.menu
.selectItem( match
);
10786 if ( this.menu
.findHighlightedItem() ) {
10787 this.menu
.highlightItem( match
);
10789 this.$element
.toggleClass( 'oo-ui-comboBoxInputWidget-empty', this.menu
.isEmpty() );
10795 OO
.ui
.ComboBoxInputWidget
.prototype.setDisabled = function ( disabled
) {
10797 OO
.ui
.ComboBoxInputWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
10799 if ( this.dropdownButton
) {
10800 this.dropdownButton
.setDisabled( this.isDisabled() );
10803 this.menu
.setDisabled( this.isDisabled() );
10810 * Set the options available for this input.
10812 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
10815 OO
.ui
.ComboBoxInputWidget
.prototype.setOptions = function ( options
) {
10818 .addItems( options
.map( function ( opt
) {
10819 return new OO
.ui
.MenuOptionWidget( {
10821 label
: opt
.label
!== undefined ? opt
.label
: opt
.data
10829 * FieldLayouts are used with OO.ui.FieldsetLayout. Each FieldLayout requires a field-widget,
10830 * which is a widget that is specified by reference before any optional configuration settings.
10832 * Field layouts can be configured with help text and/or labels. Labels are aligned in one of four ways:
10834 * - **left**: The label is placed before the field-widget and aligned with the left margin.
10835 * A left-alignment is used for forms with many fields.
10836 * - **right**: The label is placed before the field-widget and aligned to the right margin.
10837 * A right-alignment is used for long but familiar forms which users tab through,
10838 * verifying the current field with a quick glance at the label.
10839 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
10840 * that users fill out from top to bottom.
10841 * - **inline**: The label is placed after the field-widget and aligned to the left.
10842 * An inline-alignment is best used with checkboxes or radio buttons.
10844 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout.
10845 * Please see the [OOjs UI documentation on MediaWiki] [1] for examples and more information.
10847 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
10850 * @extends OO.ui.Layout
10851 * @mixins OO.ui.mixin.LabelElement
10852 * @mixins OO.ui.mixin.TitledElement
10855 * @param {OO.ui.Widget} fieldWidget Field widget
10856 * @param {Object} [config] Configuration options
10857 * @cfg {string} [align='left'] Alignment of the label: 'left', 'right', 'top' or 'inline'
10858 * @cfg {Array} [errors] Error messages about the widget, which will be displayed below the widget.
10859 * The array may contain strings or OO.ui.HtmlSnippet instances.
10860 * @cfg {Array} [notices] Notices about the widget, which will be displayed below the widget.
10861 * The array may contain strings or OO.ui.HtmlSnippet instances.
10862 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified, a "help" icon will appear
10863 * in the upper-right corner of the rendered field; clicking it will display the text in a popup.
10864 * For important messages, you are advised to use `notices`, as they are always shown.
10865 * @cfg {jQuery} [$overlay] Passed to OO.ui.PopupButtonWidget for help popup, if `help` is given.
10866 * See <https://www.mediawiki.org/wiki/OOjs_UI/Concepts#Overlays>.
10868 * @throws {Error} An error is thrown if no widget is specified
10870 OO
.ui
.FieldLayout
= function OoUiFieldLayout( fieldWidget
, config
) {
10871 // Allow passing positional parameters inside the config object
10872 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
10873 config
= fieldWidget
;
10874 fieldWidget
= config
.fieldWidget
;
10877 // Make sure we have required constructor arguments
10878 if ( fieldWidget
=== undefined ) {
10879 throw new Error( 'Widget not found' );
10882 // Configuration initialization
10883 config
= $.extend( { align
: 'left' }, config
);
10885 // Parent constructor
10886 OO
.ui
.FieldLayout
.parent
.call( this, config
);
10888 // Mixin constructors
10889 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, {
10890 $label
: $( '<label>' )
10892 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
10895 this.fieldWidget
= fieldWidget
;
10898 this.$field
= this.isFieldInline() ? $( '<span>' ) : $( '<div>' );
10899 this.$messages
= $( '<ul>' );
10900 this.$header
= $( '<span>' );
10901 this.$body
= $( '<div>' );
10903 if ( config
.help
) {
10904 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
10905 $overlay
: config
.$overlay
,
10909 classes
: [ 'oo-ui-fieldLayout-help' ],
10913 if ( config
.help
instanceof OO
.ui
.HtmlSnippet
) {
10914 this.popupButtonWidget
.getPopup().$body
.html( config
.help
.toString() );
10916 this.popupButtonWidget
.getPopup().$body
.text( config
.help
);
10918 this.$help
= this.popupButtonWidget
.$element
;
10920 this.$help
= $( [] );
10924 this.fieldWidget
.connect( this, { disable
: 'onFieldDisable' } );
10927 if ( config
.help
) {
10928 // Set the 'aria-describedby' attribute on the fieldWidget
10929 // Preference given to an input or a button
10931 this.fieldWidget
.$input
||
10932 this.fieldWidget
.$button
||
10933 this.fieldWidget
.$element
10935 'aria-describedby',
10936 this.popupButtonWidget
.getPopup().getBodyId()
10939 if ( this.fieldWidget
.getInputId() ) {
10940 this.$label
.attr( 'for', this.fieldWidget
.getInputId() );
10942 this.$label
.on( 'click', function () {
10943 this.fieldWidget
.simulateLabelClick();
10948 .addClass( 'oo-ui-fieldLayout' )
10949 .toggleClass( 'oo-ui-fieldLayout-disabled', this.fieldWidget
.isDisabled() )
10950 .append( this.$body
);
10951 this.$body
.addClass( 'oo-ui-fieldLayout-body' );
10952 this.$header
.addClass( 'oo-ui-fieldLayout-header' );
10953 this.$messages
.addClass( 'oo-ui-fieldLayout-messages' );
10955 .addClass( 'oo-ui-fieldLayout-field' )
10956 .append( this.fieldWidget
.$element
);
10958 this.setErrors( config
.errors
|| [] );
10959 this.setNotices( config
.notices
|| [] );
10960 this.setAlignment( config
.align
);
10961 // Call this again to take into account the widget's accessKey
10962 this.updateTitle();
10967 OO
.inheritClass( OO
.ui
.FieldLayout
, OO
.ui
.Layout
);
10968 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.LabelElement
);
10969 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.TitledElement
);
10974 * Handle field disable events.
10977 * @param {boolean} value Field is disabled
10979 OO
.ui
.FieldLayout
.prototype.onFieldDisable = function ( value
) {
10980 this.$element
.toggleClass( 'oo-ui-fieldLayout-disabled', value
);
10984 * Get the widget contained by the field.
10986 * @return {OO.ui.Widget} Field widget
10988 OO
.ui
.FieldLayout
.prototype.getField = function () {
10989 return this.fieldWidget
;
10993 * Return `true` if the given field widget can be used with `'inline'` alignment (see
10994 * #setAlignment). Return `false` if it can't or if this can't be determined.
10996 * @return {boolean}
10998 OO
.ui
.FieldLayout
.prototype.isFieldInline = function () {
10999 // This is very simplistic, but should be good enough.
11000 return this.getField().$element
.prop( 'tagName' ).toLowerCase() === 'span';
11005 * @param {string} kind 'error' or 'notice'
11006 * @param {string|OO.ui.HtmlSnippet} text
11009 OO
.ui
.FieldLayout
.prototype.makeMessage = function ( kind
, text
) {
11010 var $listItem
, $icon
, message
;
11011 $listItem
= $( '<li>' );
11012 if ( kind
=== 'error' ) {
11013 $icon
= new OO
.ui
.IconWidget( { icon
: 'alert', flags
: [ 'warning' ] } ).$element
;
11014 $listItem
.attr( 'role', 'alert' );
11015 } else if ( kind
=== 'notice' ) {
11016 $icon
= new OO
.ui
.IconWidget( { icon
: 'info' } ).$element
;
11020 message
= new OO
.ui
.LabelWidget( { label
: text
} );
11022 .append( $icon
, message
.$element
)
11023 .addClass( 'oo-ui-fieldLayout-messages-' + kind
);
11028 * Set the field alignment mode.
11031 * @param {string} value Alignment mode, either 'left', 'right', 'top' or 'inline'
11034 OO
.ui
.FieldLayout
.prototype.setAlignment = function ( value
) {
11035 if ( value
!== this.align
) {
11036 // Default to 'left'
11037 if ( [ 'left', 'right', 'top', 'inline' ].indexOf( value
) === -1 ) {
11041 if ( value
=== 'inline' && !this.isFieldInline() ) {
11044 // Reorder elements
11045 if ( value
=== 'top' ) {
11046 this.$header
.append( this.$label
, this.$help
);
11047 this.$body
.append( this.$header
, this.$field
);
11048 } else if ( value
=== 'inline' ) {
11049 this.$header
.append( this.$label
, this.$help
);
11050 this.$body
.append( this.$field
, this.$header
);
11052 this.$header
.append( this.$label
);
11053 this.$body
.append( this.$header
, this.$help
, this.$field
);
11055 // Set classes. The following classes can be used here:
11056 // * oo-ui-fieldLayout-align-left
11057 // * oo-ui-fieldLayout-align-right
11058 // * oo-ui-fieldLayout-align-top
11059 // * oo-ui-fieldLayout-align-inline
11060 if ( this.align
) {
11061 this.$element
.removeClass( 'oo-ui-fieldLayout-align-' + this.align
);
11063 this.$element
.addClass( 'oo-ui-fieldLayout-align-' + value
);
11064 this.align
= value
;
11071 * Set the list of error messages.
11073 * @param {Array} errors Error messages about the widget, which will be displayed below the widget.
11074 * The array may contain strings or OO.ui.HtmlSnippet instances.
11077 OO
.ui
.FieldLayout
.prototype.setErrors = function ( errors
) {
11078 this.errors
= errors
.slice();
11079 this.updateMessages();
11084 * Set the list of notice messages.
11086 * @param {Array} notices Notices about the widget, which will be displayed below the widget.
11087 * The array may contain strings or OO.ui.HtmlSnippet instances.
11090 OO
.ui
.FieldLayout
.prototype.setNotices = function ( notices
) {
11091 this.notices
= notices
.slice();
11092 this.updateMessages();
11097 * Update the rendering of error and notice messages.
11101 OO
.ui
.FieldLayout
.prototype.updateMessages = function () {
11103 this.$messages
.empty();
11105 if ( this.errors
.length
|| this.notices
.length
) {
11106 this.$body
.after( this.$messages
);
11108 this.$messages
.remove();
11112 for ( i
= 0; i
< this.notices
.length
; i
++ ) {
11113 this.$messages
.append( this.makeMessage( 'notice', this.notices
[ i
] ) );
11115 for ( i
= 0; i
< this.errors
.length
; i
++ ) {
11116 this.$messages
.append( this.makeMessage( 'error', this.errors
[ i
] ) );
11121 * Include information about the widget's accessKey in our title. TitledElement calls this method.
11122 * (This is a bit of a hack.)
11125 * @param {string} title Tooltip label for 'title' attribute
11128 OO
.ui
.FieldLayout
.prototype.formatTitleWithAccessKey = function ( title
) {
11129 if ( this.fieldWidget
&& this.fieldWidget
.formatTitleWithAccessKey
) {
11130 return this.fieldWidget
.formatTitleWithAccessKey( title
);
11136 * ActionFieldLayouts are used with OO.ui.FieldsetLayout. The layout consists of a field-widget, a button,
11137 * and an optional label and/or help text. The field-widget (e.g., a {@link OO.ui.TextInputWidget TextInputWidget}),
11138 * is required and is specified before any optional configuration settings.
11140 * Labels can be aligned in one of four ways:
11142 * - **left**: The label is placed before the field-widget and aligned with the left margin.
11143 * A left-alignment is used for forms with many fields.
11144 * - **right**: The label is placed before the field-widget and aligned to the right margin.
11145 * A right-alignment is used for long but familiar forms which users tab through,
11146 * verifying the current field with a quick glance at the label.
11147 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
11148 * that users fill out from top to bottom.
11149 * - **inline**: The label is placed after the field-widget and aligned to the left.
11150 * An inline-alignment is best used with checkboxes or radio buttons.
11152 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout when help
11153 * text is specified.
11156 * // Example of an ActionFieldLayout
11157 * var actionFieldLayout = new OO.ui.ActionFieldLayout(
11158 * new OO.ui.TextInputWidget( {
11159 * placeholder: 'Field widget'
11161 * new OO.ui.ButtonWidget( {
11165 * label: 'An ActionFieldLayout. This label is aligned top',
11167 * help: 'This is help text'
11171 * $( 'body' ).append( actionFieldLayout.$element );
11174 * @extends OO.ui.FieldLayout
11177 * @param {OO.ui.Widget} fieldWidget Field widget
11178 * @param {OO.ui.ButtonWidget} buttonWidget Button widget
11179 * @param {Object} config
11181 OO
.ui
.ActionFieldLayout
= function OoUiActionFieldLayout( fieldWidget
, buttonWidget
, config
) {
11182 // Allow passing positional parameters inside the config object
11183 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
11184 config
= fieldWidget
;
11185 fieldWidget
= config
.fieldWidget
;
11186 buttonWidget
= config
.buttonWidget
;
11189 // Parent constructor
11190 OO
.ui
.ActionFieldLayout
.parent
.call( this, fieldWidget
, config
);
11193 this.buttonWidget
= buttonWidget
;
11194 this.$button
= $( '<span>' );
11195 this.$input
= this.isFieldInline() ? $( '<span>' ) : $( '<div>' );
11199 .addClass( 'oo-ui-actionFieldLayout' );
11201 .addClass( 'oo-ui-actionFieldLayout-button' )
11202 .append( this.buttonWidget
.$element
);
11204 .addClass( 'oo-ui-actionFieldLayout-input' )
11205 .append( this.fieldWidget
.$element
);
11207 .append( this.$input
, this.$button
);
11212 OO
.inheritClass( OO
.ui
.ActionFieldLayout
, OO
.ui
.FieldLayout
);
11215 * FieldsetLayouts are composed of one or more {@link OO.ui.FieldLayout FieldLayouts},
11216 * which each contain an individual widget and, optionally, a label. Each Fieldset can be
11217 * configured with a label as well. For more information and examples,
11218 * please see the [OOjs UI documentation on MediaWiki][1].
11221 * // Example of a fieldset layout
11222 * var input1 = new OO.ui.TextInputWidget( {
11223 * placeholder: 'A text input field'
11226 * var input2 = new OO.ui.TextInputWidget( {
11227 * placeholder: 'A text input field'
11230 * var fieldset = new OO.ui.FieldsetLayout( {
11231 * label: 'Example of a fieldset layout'
11234 * fieldset.addItems( [
11235 * new OO.ui.FieldLayout( input1, {
11236 * label: 'Field One'
11238 * new OO.ui.FieldLayout( input2, {
11239 * label: 'Field Two'
11242 * $( 'body' ).append( fieldset.$element );
11244 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
11247 * @extends OO.ui.Layout
11248 * @mixins OO.ui.mixin.IconElement
11249 * @mixins OO.ui.mixin.LabelElement
11250 * @mixins OO.ui.mixin.GroupElement
11253 * @param {Object} [config] Configuration options
11254 * @cfg {OO.ui.FieldLayout[]} [items] An array of fields to add to the fieldset. See OO.ui.FieldLayout for more information about fields.
11255 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified, a "help" icon will appear
11256 * in the upper-right corner of the rendered field; clicking it will display the text in a popup.
11257 * For important messages, you are advised to use `notices`, as they are always shown.
11258 * @cfg {jQuery} [$overlay] Passed to OO.ui.PopupButtonWidget for help popup, if `help` is given.
11259 * See <https://www.mediawiki.org/wiki/OOjs_UI/Concepts#Overlays>.
11261 OO
.ui
.FieldsetLayout
= function OoUiFieldsetLayout( config
) {
11262 // Configuration initialization
11263 config
= config
|| {};
11265 // Parent constructor
11266 OO
.ui
.FieldsetLayout
.parent
.call( this, config
);
11268 // Mixin constructors
11269 OO
.ui
.mixin
.IconElement
.call( this, config
);
11270 OO
.ui
.mixin
.LabelElement
.call( this, config
);
11271 OO
.ui
.mixin
.GroupElement
.call( this, config
);
11274 this.$header
= $( '<legend>' );
11275 if ( config
.help
) {
11276 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
11277 $overlay
: config
.$overlay
,
11281 classes
: [ 'oo-ui-fieldsetLayout-help' ],
11285 if ( config
.help
instanceof OO
.ui
.HtmlSnippet
) {
11286 this.popupButtonWidget
.getPopup().$body
.html( config
.help
.toString() );
11288 this.popupButtonWidget
.getPopup().$body
.text( config
.help
);
11290 this.$help
= this.popupButtonWidget
.$element
;
11292 this.$help
= $( [] );
11297 .addClass( 'oo-ui-fieldsetLayout-header' )
11298 .append( this.$icon
, this.$label
, this.$help
);
11299 this.$group
.addClass( 'oo-ui-fieldsetLayout-group' );
11301 .addClass( 'oo-ui-fieldsetLayout' )
11302 .prepend( this.$header
, this.$group
);
11303 if ( Array
.isArray( config
.items
) ) {
11304 this.addItems( config
.items
);
11310 OO
.inheritClass( OO
.ui
.FieldsetLayout
, OO
.ui
.Layout
);
11311 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.IconElement
);
11312 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.LabelElement
);
11313 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.GroupElement
);
11315 /* Static Properties */
11321 OO
.ui
.FieldsetLayout
.static.tagName
= 'fieldset';
11324 * FormLayouts are used to wrap {@link OO.ui.FieldsetLayout FieldsetLayouts} when you intend to use browser-based
11325 * form submission for the fields instead of handling them in JavaScript. Form layouts can be configured with an
11326 * HTML form action, an encoding type, and a method using the #action, #enctype, and #method configs, respectively.
11327 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
11329 * Only widgets from the {@link OO.ui.InputWidget InputWidget} family support form submission. It
11330 * includes standard form elements like {@link OO.ui.CheckboxInputWidget checkboxes}, {@link
11331 * OO.ui.RadioInputWidget radio buttons} and {@link OO.ui.TextInputWidget text fields}, as well as
11332 * some fancier controls. Some controls have both regular and InputWidget variants, for example
11333 * OO.ui.DropdownWidget and OO.ui.DropdownInputWidget – only the latter support form submission and
11334 * often have simplified APIs to match the capabilities of HTML forms.
11335 * See the [OOjs UI Inputs documentation on MediaWiki] [2] for more information about InputWidgets.
11337 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Forms
11338 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
11341 * // Example of a form layout that wraps a fieldset layout
11342 * var input1 = new OO.ui.TextInputWidget( {
11343 * placeholder: 'Username'
11345 * var input2 = new OO.ui.TextInputWidget( {
11346 * placeholder: 'Password',
11349 * var submit = new OO.ui.ButtonInputWidget( {
11353 * var fieldset = new OO.ui.FieldsetLayout( {
11354 * label: 'A form layout'
11356 * fieldset.addItems( [
11357 * new OO.ui.FieldLayout( input1, {
11358 * label: 'Username',
11361 * new OO.ui.FieldLayout( input2, {
11362 * label: 'Password',
11365 * new OO.ui.FieldLayout( submit )
11367 * var form = new OO.ui.FormLayout( {
11368 * items: [ fieldset ],
11369 * action: '/api/formhandler',
11372 * $( 'body' ).append( form.$element );
11375 * @extends OO.ui.Layout
11376 * @mixins OO.ui.mixin.GroupElement
11379 * @param {Object} [config] Configuration options
11380 * @cfg {string} [method] HTML form `method` attribute
11381 * @cfg {string} [action] HTML form `action` attribute
11382 * @cfg {string} [enctype] HTML form `enctype` attribute
11383 * @cfg {OO.ui.FieldsetLayout[]} [items] Fieldset layouts to add to the form layout.
11385 OO
.ui
.FormLayout
= function OoUiFormLayout( config
) {
11388 // Configuration initialization
11389 config
= config
|| {};
11391 // Parent constructor
11392 OO
.ui
.FormLayout
.parent
.call( this, config
);
11394 // Mixin constructors
11395 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
11398 this.$element
.on( 'submit', this.onFormSubmit
.bind( this ) );
11400 // Make sure the action is safe
11401 action
= config
.action
;
11402 if ( action
!== undefined && !OO
.ui
.isSafeUrl( action
) ) {
11403 action
= './' + action
;
11408 .addClass( 'oo-ui-formLayout' )
11410 method
: config
.method
,
11412 enctype
: config
.enctype
11414 if ( Array
.isArray( config
.items
) ) {
11415 this.addItems( config
.items
);
11421 OO
.inheritClass( OO
.ui
.FormLayout
, OO
.ui
.Layout
);
11422 OO
.mixinClass( OO
.ui
.FormLayout
, OO
.ui
.mixin
.GroupElement
);
11427 * A 'submit' event is emitted when the form is submitted.
11432 /* Static Properties */
11438 OO
.ui
.FormLayout
.static.tagName
= 'form';
11443 * Handle form submit events.
11446 * @param {jQuery.Event} e Submit event
11449 OO
.ui
.FormLayout
.prototype.onFormSubmit = function () {
11450 if ( this.emit( 'submit' ) ) {
11456 * PanelLayouts expand to cover the entire area of their parent. They can be configured with scrolling, padding,
11457 * and a frame, and are often used together with {@link OO.ui.StackLayout StackLayouts}.
11460 * // Example of a panel layout
11461 * var panel = new OO.ui.PanelLayout( {
11465 * $content: $( '<p>A panel layout with padding and a frame.</p>' )
11467 * $( 'body' ).append( panel.$element );
11470 * @extends OO.ui.Layout
11473 * @param {Object} [config] Configuration options
11474 * @cfg {boolean} [scrollable=false] Allow vertical scrolling
11475 * @cfg {boolean} [padded=false] Add padding between the content and the edges of the panel.
11476 * @cfg {boolean} [expanded=true] Expand the panel to fill the entire parent element.
11477 * @cfg {boolean} [framed=false] Render the panel with a frame to visually separate it from outside content.
11479 OO
.ui
.PanelLayout
= function OoUiPanelLayout( config
) {
11480 // Configuration initialization
11481 config
= $.extend( {
11488 // Parent constructor
11489 OO
.ui
.PanelLayout
.parent
.call( this, config
);
11492 this.$element
.addClass( 'oo-ui-panelLayout' );
11493 if ( config
.scrollable
) {
11494 this.$element
.addClass( 'oo-ui-panelLayout-scrollable' );
11496 if ( config
.padded
) {
11497 this.$element
.addClass( 'oo-ui-panelLayout-padded' );
11499 if ( config
.expanded
) {
11500 this.$element
.addClass( 'oo-ui-panelLayout-expanded' );
11502 if ( config
.framed
) {
11503 this.$element
.addClass( 'oo-ui-panelLayout-framed' );
11509 OO
.inheritClass( OO
.ui
.PanelLayout
, OO
.ui
.Layout
);
11514 * Focus the panel layout
11516 * The default implementation just focuses the first focusable element in the panel
11518 OO
.ui
.PanelLayout
.prototype.focus = function () {
11519 OO
.ui
.findFocusable( this.$element
).focus();
11523 * HorizontalLayout arranges its contents in a single line (using `display: inline-block` for its
11524 * items), with small margins between them. Convenient when you need to put a number of block-level
11525 * widgets on a single line next to each other.
11527 * Note that inline elements, such as OO.ui.ButtonWidgets, do not need this wrapper.
11530 * // HorizontalLayout with a text input and a label
11531 * var layout = new OO.ui.HorizontalLayout( {
11533 * new OO.ui.LabelWidget( { label: 'Label' } ),
11534 * new OO.ui.TextInputWidget( { value: 'Text' } )
11537 * $( 'body' ).append( layout.$element );
11540 * @extends OO.ui.Layout
11541 * @mixins OO.ui.mixin.GroupElement
11544 * @param {Object} [config] Configuration options
11545 * @cfg {OO.ui.Widget[]|OO.ui.Layout[]} [items] Widgets or other layouts to add to the layout.
11547 OO
.ui
.HorizontalLayout
= function OoUiHorizontalLayout( config
) {
11548 // Configuration initialization
11549 config
= config
|| {};
11551 // Parent constructor
11552 OO
.ui
.HorizontalLayout
.parent
.call( this, config
);
11554 // Mixin constructors
11555 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
11558 this.$element
.addClass( 'oo-ui-horizontalLayout' );
11559 if ( Array
.isArray( config
.items
) ) {
11560 this.addItems( config
.items
);
11566 OO
.inheritClass( OO
.ui
.HorizontalLayout
, OO
.ui
.Layout
);
11567 OO
.mixinClass( OO
.ui
.HorizontalLayout
, OO
.ui
.mixin
.GroupElement
);
11571 //# sourceMappingURL=oojs-ui-core.js.map