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-04-18T23:32:49Z
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 accept button of a confirmation dialog
366 'ooui-dialog-message-accept': 'OK',
367 // Default label for the reject button of a confirmation dialog
368 'ooui-dialog-message-reject': 'Cancel',
369 // Title for process dialog error description
370 'ooui-dialog-process-error': 'Something went wrong',
371 // Label for process dialog dismiss error button, visible when describing errors
372 'ooui-dialog-process-dismiss': 'Dismiss',
373 // Label for process dialog retry action button, visible when describing only recoverable errors
374 'ooui-dialog-process-retry': 'Try again',
375 // Label for process dialog retry action button, visible when describing only warnings
376 'ooui-dialog-process-continue': 'Continue',
377 // Label for the file selection widget's select file button
378 'ooui-selectfile-button-select': 'Select a file',
379 // Label for the file selection widget if file selection is not supported
380 'ooui-selectfile-not-supported': 'File selection is not supported',
381 // Label for the file selection widget when no file is currently selected
382 'ooui-selectfile-placeholder': 'No file is selected',
383 // Label for the file selection widget's drop target
384 'ooui-selectfile-dragdrop-placeholder': 'Drop file here'
388 * Get a localized message.
390 * After the message key, message parameters may optionally be passed. In the default implementation,
391 * any occurrences of $1 are replaced with the first parameter, $2 with the second parameter, etc.
392 * Alternative implementations of OO.ui.msg may use any substitution system they like, as long as
393 * they support unnamed, ordered message parameters.
395 * In environments that provide a localization system, this function should be overridden to
396 * return the message translated in the user's language. The default implementation always returns
397 * English messages. An example of doing this with [jQuery.i18n](https://github.com/wikimedia/jquery.i18n)
401 * var i, iLen, button,
402 * messagePath = 'oojs-ui/dist/i18n/',
403 * languages = [ $.i18n().locale, 'ur', 'en' ],
406 * for ( i = 0, iLen = languages.length; i < iLen; i++ ) {
407 * languageMap[ languages[ i ] ] = messagePath + languages[ i ].toLowerCase() + '.json';
410 * $.i18n().load( languageMap ).done( function() {
411 * // Replace the built-in `msg` only once we've loaded the internationalization.
412 * // OOjs UI uses `OO.ui.deferMsg` for all initially-loaded messages. So long as
413 * // you put off creating any widgets until this promise is complete, no English
414 * // will be displayed.
415 * OO.ui.msg = $.i18n;
417 * // A button displaying "OK" in the default locale
418 * button = new OO.ui.ButtonWidget( {
419 * label: OO.ui.msg( 'ooui-dialog-message-accept' ),
422 * $( 'body' ).append( button.$element );
424 * // A button displaying "OK" in Urdu
425 * $.i18n().locale = 'ur';
426 * button = new OO.ui.ButtonWidget( {
427 * label: OO.ui.msg( 'ooui-dialog-message-accept' ),
430 * $( 'body' ).append( button.$element );
433 * @param {string} key Message key
434 * @param {...Mixed} [params] Message parameters
435 * @return {string} Translated message with parameters substituted
437 OO
.ui
.msg = function ( key
) {
438 var message
= messages
[ key
],
439 params
= Array
.prototype.slice
.call( arguments
, 1 );
440 if ( typeof message
=== 'string' ) {
441 // Perform $1 substitution
442 message
= message
.replace( /\$(\d+)/g, function ( unused
, n
) {
443 var i
= parseInt( n
, 10 );
444 return params
[ i
- 1 ] !== undefined ? params
[ i
- 1 ] : '$' + n
;
447 // Return placeholder if message not found
448 message
= '[' + key
+ ']';
455 * Package a message and arguments for deferred resolution.
457 * Use this when you are statically specifying a message and the message may not yet be present.
459 * @param {string} key Message key
460 * @param {...Mixed} [params] Message parameters
461 * @return {Function} Function that returns the resolved message when executed
463 OO
.ui
.deferMsg = function () {
464 var args
= arguments
;
466 return OO
.ui
.msg
.apply( OO
.ui
, args
);
473 * If the message is a function it will be executed, otherwise it will pass through directly.
475 * @param {Function|string} msg Deferred message, or message text
476 * @return {string} Resolved message
478 OO
.ui
.resolveMsg = function ( msg
) {
479 if ( $.isFunction( msg
) ) {
486 * @param {string} url
489 OO
.ui
.isSafeUrl = function ( url
) {
490 // Keep this function in sync with php/Tag.php
491 var i
, protocolWhitelist
;
493 function stringStartsWith( haystack
, needle
) {
494 return haystack
.substr( 0, needle
.length
) === needle
;
497 protocolWhitelist
= [
498 'bitcoin', 'ftp', 'ftps', 'geo', 'git', 'gopher', 'http', 'https', 'irc', 'ircs',
499 'magnet', 'mailto', 'mms', 'news', 'nntp', 'redis', 'sftp', 'sip', 'sips', 'sms', 'ssh',
500 'svn', 'tel', 'telnet', 'urn', 'worldwind', 'xmpp'
507 for ( i
= 0; i
< protocolWhitelist
.length
; i
++ ) {
508 if ( stringStartsWith( url
, protocolWhitelist
[ i
] + ':' ) ) {
513 // This matches '//' too
514 if ( stringStartsWith( url
, '/' ) || stringStartsWith( url
, './' ) ) {
517 if ( stringStartsWith( url
, '?' ) || stringStartsWith( url
, '#' ) ) {
525 * Check if the user has a 'mobile' device.
527 * For our purposes this means the user is primarily using an
528 * on-screen keyboard, touch input instead of a mouse and may
529 * have a physically small display.
531 * It is left up to implementors to decide how to compute this
532 * so the default implementation always returns false.
534 * @return {boolean} Use is on a mobile device
536 OO
.ui
.isMobile = function () {
545 * Namespace for OOjs UI mixins.
547 * Mixins are named according to the type of object they are intended to
548 * be mixed in to. For example, OO.ui.mixin.GroupElement is intended to be
549 * mixed in to an instance of OO.ui.Element, and OO.ui.mixin.GroupWidget
550 * is intended to be mixed in to an instance of OO.ui.Widget.
558 * Each Element represents a rendering in the DOM—a button or an icon, for example, or anything
559 * that is visible to a user. Unlike {@link OO.ui.Widget widgets}, plain elements usually do not have events
560 * connected to them and can't be interacted with.
566 * @param {Object} [config] Configuration options
567 * @cfg {string[]} [classes] The names of the CSS classes to apply to the element. CSS styles are added
568 * to the top level (e.g., the outermost div) of the element. See the [OOjs UI documentation on MediaWiki][2]
570 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#cssExample
571 * @cfg {string} [id] The HTML id attribute used in the rendered tag.
572 * @cfg {string} [text] Text to insert
573 * @cfg {Array} [content] An array of content elements to append (after #text).
574 * Strings will be html-escaped; use an OO.ui.HtmlSnippet to append raw HTML.
575 * Instances of OO.ui.Element will have their $element appended.
576 * @cfg {jQuery} [$content] Content elements to append (after #text).
577 * @cfg {jQuery} [$element] Wrapper element. Defaults to a new element with #getTagName.
578 * @cfg {Mixed} [data] Custom data of any type or combination of types (e.g., string, number, array, object).
579 * Data can also be specified with the #setData method.
581 OO
.ui
.Element
= function OoUiElement( config
) {
582 // Configuration initialization
583 config
= config
|| {};
588 this.data
= config
.data
;
589 this.$element
= config
.$element
||
590 $( document
.createElement( this.getTagName() ) );
591 this.elementGroup
= null;
594 if ( Array
.isArray( config
.classes
) ) {
595 this.$element
.addClass( config
.classes
.join( ' ' ) );
598 this.$element
.attr( 'id', config
.id
);
601 this.$element
.text( config
.text
);
603 if ( config
.content
) {
604 // The `content` property treats plain strings as text; use an
605 // HtmlSnippet to append HTML content. `OO.ui.Element`s get their
606 // appropriate $element appended.
607 this.$element
.append( config
.content
.map( function ( v
) {
608 if ( typeof v
=== 'string' ) {
609 // Escape string so it is properly represented in HTML.
610 return document
.createTextNode( v
);
611 } else if ( v
instanceof OO
.ui
.HtmlSnippet
) {
614 } else if ( v
instanceof OO
.ui
.Element
) {
620 if ( config
.$content
) {
621 // The `$content` property treats plain strings as HTML.
622 this.$element
.append( config
.$content
);
628 OO
.initClass( OO
.ui
.Element
);
630 /* Static Properties */
633 * The name of the HTML tag used by the element.
635 * The static value may be ignored if the #getTagName method is overridden.
641 OO
.ui
.Element
.static.tagName
= 'div';
646 * Reconstitute a JavaScript object corresponding to a widget created
647 * by the PHP implementation.
649 * @param {string|HTMLElement|jQuery} idOrNode
650 * A DOM id (if a string) or node for the widget to infuse.
651 * @return {OO.ui.Element}
652 * The `OO.ui.Element` corresponding to this (infusable) document node.
653 * For `Tag` objects emitted on the HTML side (used occasionally for content)
654 * the value returned is a newly-created Element wrapping around the existing
657 OO
.ui
.Element
.static.infuse = function ( idOrNode
) {
658 var obj
= OO
.ui
.Element
.static.unsafeInfuse( idOrNode
, false );
659 // Verify that the type matches up.
660 // FIXME: uncomment after T89721 is fixed (see T90929)
662 if ( !( obj instanceof this['class'] ) ) {
663 throw new Error( 'Infusion type mismatch!' );
670 * Implementation helper for `infuse`; skips the type check and has an
671 * extra property so that only the top-level invocation touches the DOM.
674 * @param {string|HTMLElement|jQuery} idOrNode
675 * @param {jQuery.Promise|boolean} domPromise A promise that will be resolved
676 * when the top-level widget of this infusion is inserted into DOM,
677 * replacing the original node; or false for top-level invocation.
678 * @return {OO.ui.Element}
680 OO
.ui
.Element
.static.unsafeInfuse = function ( idOrNode
, domPromise
) {
681 // look for a cached result of a previous infusion.
682 var id
, $elem
, data
, cls
, parts
, parent
, obj
, top
, state
, infusedChildren
;
683 if ( typeof idOrNode
=== 'string' ) {
685 $elem
= $( document
.getElementById( id
) );
687 $elem
= $( idOrNode
);
688 id
= $elem
.attr( 'id' );
690 if ( !$elem
.length
) {
691 throw new Error( 'Widget not found: ' + id
);
693 if ( $elem
[ 0 ].oouiInfused
) {
694 $elem
= $elem
[ 0 ].oouiInfused
;
696 data
= $elem
.data( 'ooui-infused' );
699 if ( data
=== true ) {
700 throw new Error( 'Circular dependency! ' + id
);
703 // pick up dynamic state, like focus, value of form inputs, scroll position, etc.
704 state
= data
.constructor.static.gatherPreInfuseState( $elem
, data
);
705 // restore dynamic state after the new element is re-inserted into DOM under infused parent
706 domPromise
.done( data
.restorePreInfuseState
.bind( data
, state
) );
707 infusedChildren
= $elem
.data( 'ooui-infused-children' );
708 if ( infusedChildren
&& infusedChildren
.length
) {
709 infusedChildren
.forEach( function ( data
) {
710 var state
= data
.constructor.static.gatherPreInfuseState( $elem
, data
);
711 domPromise
.done( data
.restorePreInfuseState
.bind( data
, state
) );
717 data
= $elem
.attr( 'data-ooui' );
719 throw new Error( 'No infusion data found: ' + id
);
722 data
= JSON
.parse( data
);
726 if ( !( data
&& data
._
) ) {
727 throw new Error( 'No valid infusion data found: ' + id
);
729 if ( data
._
=== 'Tag' ) {
730 // Special case: this is a raw Tag; wrap existing node, don't rebuild.
731 return new OO
.ui
.Element( { $element
: $elem
} );
733 parts
= data
._
.split( '.' );
734 cls
= OO
.getProp
.apply( OO
, [ window
].concat( parts
) );
735 if ( cls
=== undefined ) {
736 // The PHP output might be old and not including the "OO.ui" prefix
737 // TODO: Remove this back-compat after next major release
738 cls
= OO
.getProp
.apply( OO
, [ OO
.ui
].concat( parts
) );
739 if ( cls
=== undefined ) {
740 throw new Error( 'Unknown widget type: id: ' + id
+ ', class: ' + data
._
);
744 // Verify that we're creating an OO.ui.Element instance
747 while ( parent
!== undefined ) {
748 if ( parent
=== OO
.ui
.Element
) {
753 parent
= parent
.parent
;
756 if ( parent
!== OO
.ui
.Element
) {
757 throw new Error( 'Unknown widget type: id: ' + id
+ ', class: ' + data
._
);
760 if ( domPromise
=== false ) {
762 domPromise
= top
.promise();
764 $elem
.data( 'ooui-infused', true ); // prevent loops
765 data
.id
= id
; // implicit
766 infusedChildren
= [];
767 data
= OO
.copy( data
, null, function deserialize( value
) {
769 if ( OO
.isPlainObject( value
) ) {
771 infused
= OO
.ui
.Element
.static.unsafeInfuse( value
.tag
, domPromise
);
772 infusedChildren
.push( infused
);
773 // Flatten the structure
774 infusedChildren
.push
.apply( infusedChildren
, infused
.$element
.data( 'ooui-infused-children' ) || [] );
775 infused
.$element
.removeData( 'ooui-infused-children' );
778 if ( value
.html
!== undefined ) {
779 return new OO
.ui
.HtmlSnippet( value
.html
);
783 // allow widgets to reuse parts of the DOM
784 data
= cls
.static.reusePreInfuseDOM( $elem
[ 0 ], data
);
785 // pick up dynamic state, like focus, value of form inputs, scroll position, etc.
786 state
= cls
.static.gatherPreInfuseState( $elem
[ 0 ], data
);
788 // eslint-disable-next-line new-cap
789 obj
= new cls( data
);
790 // now replace old DOM with this new DOM.
792 // An efficient constructor might be able to reuse the entire DOM tree of the original element,
793 // so only mutate the DOM if we need to.
794 if ( $elem
[ 0 ] !== obj
.$element
[ 0 ] ) {
795 $elem
.replaceWith( obj
.$element
);
796 // This element is now gone from the DOM, but if anyone is holding a reference to it,
797 // let's allow them to OO.ui.infuse() it and do what they expect (T105828).
798 // Do not use jQuery.data(), as using it on detached nodes leaks memory in 1.x line by design.
799 $elem
[ 0 ].oouiInfused
= obj
.$element
;
803 obj
.$element
.data( 'ooui-infused', obj
);
804 obj
.$element
.data( 'ooui-infused-children', infusedChildren
);
805 // set the 'data-ooui' attribute so we can identify infused widgets
806 obj
.$element
.attr( 'data-ooui', '' );
807 // restore dynamic state after the new element is inserted into DOM
808 domPromise
.done( obj
.restorePreInfuseState
.bind( obj
, state
) );
813 * Pick out parts of `node`'s DOM to be reused when infusing a widget.
815 * This method **must not** make any changes to the DOM, only find interesting pieces and add them
816 * to `config` (which should then be returned). Actual DOM juggling should then be done by the
817 * constructor, which will be given the enhanced config.
820 * @param {HTMLElement} node
821 * @param {Object} config
824 OO
.ui
.Element
.static.reusePreInfuseDOM = function ( node
, config
) {
829 * Gather the dynamic state (focus, value of form inputs, scroll position, etc.) of an HTML DOM node
830 * (and its children) that represent an Element of the same class and the given configuration,
831 * generated by the PHP implementation.
833 * This method is called just before `node` is detached from the DOM. The return value of this
834 * function will be passed to #restorePreInfuseState after the newly created widget's #$element
835 * is inserted into DOM to replace `node`.
838 * @param {HTMLElement} node
839 * @param {Object} config
842 OO
.ui
.Element
.static.gatherPreInfuseState = function () {
847 * Get a jQuery function within a specific document.
850 * @param {jQuery|HTMLElement|HTMLDocument|Window} context Context to bind the function to
851 * @param {jQuery} [$iframe] HTML iframe element that contains the document, omit if document is
853 * @return {Function} Bound jQuery function
855 OO
.ui
.Element
.static.getJQuery = function ( context
, $iframe
) {
856 function wrapper( selector
) {
857 return $( selector
, wrapper
.context
);
860 wrapper
.context
= this.getDocument( context
);
863 wrapper
.$iframe
= $iframe
;
870 * Get the document of an element.
873 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Object to get the document for
874 * @return {HTMLDocument|null} Document object
876 OO
.ui
.Element
.static.getDocument = function ( obj
) {
877 // jQuery - selections created "offscreen" won't have a context, so .context isn't reliable
878 return ( obj
[ 0 ] && obj
[ 0 ].ownerDocument
) ||
879 // Empty jQuery selections might have a context
886 ( obj
.nodeType
=== Node
.DOCUMENT_NODE
&& obj
) ||
891 * Get the window of an element or document.
894 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the window for
895 * @return {Window} Window object
897 OO
.ui
.Element
.static.getWindow = function ( obj
) {
898 var doc
= this.getDocument( obj
);
899 return doc
.defaultView
;
903 * Get the direction of an element or document.
906 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the direction for
907 * @return {string} Text direction, either 'ltr' or 'rtl'
909 OO
.ui
.Element
.static.getDir = function ( obj
) {
912 if ( obj
instanceof jQuery
) {
915 isDoc
= obj
.nodeType
=== Node
.DOCUMENT_NODE
;
916 isWin
= obj
.document
!== undefined;
917 if ( isDoc
|| isWin
) {
923 return $( obj
).css( 'direction' );
927 * Get the offset between two frames.
929 * TODO: Make this function not use recursion.
932 * @param {Window} from Window of the child frame
933 * @param {Window} [to=window] Window of the parent frame
934 * @param {Object} [offset] Offset to start with, used internally
935 * @return {Object} Offset object, containing left and top properties
937 OO
.ui
.Element
.static.getFrameOffset = function ( from, to
, offset
) {
938 var i
, len
, frames
, frame
, rect
;
944 offset
= { top
: 0, left
: 0 };
946 if ( from.parent
=== from ) {
950 // Get iframe element
951 frames
= from.parent
.document
.getElementsByTagName( 'iframe' );
952 for ( i
= 0, len
= frames
.length
; i
< len
; i
++ ) {
953 if ( frames
[ i
].contentWindow
=== from ) {
959 // Recursively accumulate offset values
961 rect
= frame
.getBoundingClientRect();
962 offset
.left
+= rect
.left
;
963 offset
.top
+= rect
.top
;
965 this.getFrameOffset( from.parent
, offset
);
972 * Get the offset between two elements.
974 * The two elements may be in a different frame, but in that case the frame $element is in must
975 * be contained in the frame $anchor is in.
978 * @param {jQuery} $element Element whose position to get
979 * @param {jQuery} $anchor Element to get $element's position relative to
980 * @return {Object} Translated position coordinates, containing top and left properties
982 OO
.ui
.Element
.static.getRelativePosition = function ( $element
, $anchor
) {
983 var iframe
, iframePos
,
984 pos
= $element
.offset(),
985 anchorPos
= $anchor
.offset(),
986 elementDocument
= this.getDocument( $element
),
987 anchorDocument
= this.getDocument( $anchor
);
989 // If $element isn't in the same document as $anchor, traverse up
990 while ( elementDocument
!== anchorDocument
) {
991 iframe
= elementDocument
.defaultView
.frameElement
;
993 throw new Error( '$element frame is not contained in $anchor frame' );
995 iframePos
= $( iframe
).offset();
996 pos
.left
+= iframePos
.left
;
997 pos
.top
+= iframePos
.top
;
998 elementDocument
= iframe
.ownerDocument
;
1000 pos
.left
-= anchorPos
.left
;
1001 pos
.top
-= anchorPos
.top
;
1006 * Get element border sizes.
1009 * @param {HTMLElement} el Element to measure
1010 * @return {Object} Dimensions object with `top`, `left`, `bottom` and `right` properties
1012 OO
.ui
.Element
.static.getBorders = function ( el
) {
1013 var doc
= el
.ownerDocument
,
1014 win
= doc
.defaultView
,
1015 style
= win
.getComputedStyle( el
, null ),
1017 top
= parseFloat( style
? style
.borderTopWidth
: $el
.css( 'borderTopWidth' ) ) || 0,
1018 left
= parseFloat( style
? style
.borderLeftWidth
: $el
.css( 'borderLeftWidth' ) ) || 0,
1019 bottom
= parseFloat( style
? style
.borderBottomWidth
: $el
.css( 'borderBottomWidth' ) ) || 0,
1020 right
= parseFloat( style
? style
.borderRightWidth
: $el
.css( 'borderRightWidth' ) ) || 0;
1031 * Get dimensions of an element or window.
1034 * @param {HTMLElement|Window} el Element to measure
1035 * @return {Object} Dimensions object with `borders`, `scroll`, `scrollbar` and `rect` properties
1037 OO
.ui
.Element
.static.getDimensions = function ( el
) {
1039 doc
= el
.ownerDocument
|| el
.document
,
1040 win
= doc
.defaultView
;
1042 if ( win
=== el
|| el
=== doc
.documentElement
) {
1045 borders
: { top
: 0, left
: 0, bottom
: 0, right
: 0 },
1047 top
: $win
.scrollTop(),
1048 left
: $win
.scrollLeft()
1050 scrollbar
: { right
: 0, bottom
: 0 },
1054 bottom
: $win
.innerHeight(),
1055 right
: $win
.innerWidth()
1061 borders
: this.getBorders( el
),
1063 top
: $el
.scrollTop(),
1064 left
: $el
.scrollLeft()
1067 right
: $el
.innerWidth() - el
.clientWidth
,
1068 bottom
: $el
.innerHeight() - el
.clientHeight
1070 rect
: el
.getBoundingClientRect()
1076 * Get the number of pixels that an element's content is scrolled to the left.
1078 * Adapted from <https://github.com/othree/jquery.rtl-scroll-type>.
1079 * Original code copyright 2012 Wei-Ko Kao, licensed under the MIT License.
1081 * This function smooths out browser inconsistencies (nicely described in the README at
1082 * <https://github.com/othree/jquery.rtl-scroll-type>) and produces a result consistent
1083 * with Firefox's 'scrollLeft', which seems the sanest.
1087 * @param {HTMLElement|Window} el Element to measure
1088 * @return {number} Scroll position from the left.
1089 * If the element's direction is LTR, this is a positive number between `0` (initial scroll position)
1090 * and `el.scrollWidth - el.clientWidth` (furthest possible scroll position).
1091 * If the element's direction is RTL, this is a negative number between `0` (initial scroll position)
1092 * and `-el.scrollWidth + el.clientWidth` (furthest possible scroll position).
1094 OO
.ui
.Element
.static.getScrollLeft
= ( function () {
1095 var rtlScrollType
= null;
1098 var $definer
= $( '<div dir="rtl" style="font-size: 14px; width: 1px; height: 1px; position: absolute; top: -1000px; overflow: scroll">A</div>' ),
1099 definer
= $definer
[ 0 ];
1101 $definer
.appendTo( 'body' );
1102 if ( definer
.scrollLeft
> 0 ) {
1104 rtlScrollType
= 'default';
1106 definer
.scrollLeft
= 1;
1107 if ( definer
.scrollLeft
=== 0 ) {
1108 // Firefox, old Opera
1109 rtlScrollType
= 'negative';
1111 // Internet Explorer, Edge
1112 rtlScrollType
= 'reverse';
1118 return function getScrollLeft( el
) {
1119 var isRoot
= el
.window
=== el
||
1120 el
=== el
.ownerDocument
.body
||
1121 el
=== el
.ownerDocument
.documentElement
,
1122 scrollLeft
= isRoot
? $( window
).scrollLeft() : el
.scrollLeft
,
1123 // All browsers use the correct scroll type ('negative') on the root, so don't
1124 // do any fixups when looking at the root element
1125 direction
= isRoot
? 'ltr' : $( el
).css( 'direction' );
1127 if ( direction
=== 'rtl' ) {
1128 if ( rtlScrollType
=== null ) {
1131 if ( rtlScrollType
=== 'reverse' ) {
1132 scrollLeft
= -scrollLeft
;
1133 } else if ( rtlScrollType
=== 'default' ) {
1134 scrollLeft
= scrollLeft
- el
.scrollWidth
+ el
.clientWidth
;
1143 * Get the root scrollable element of given element's document.
1145 * On Blink-based browsers (Chrome etc.), `document.documentElement` can't be used to get or set
1146 * the scrollTop property; instead we have to use `document.body`. Changing and testing the value
1147 * lets us use 'body' or 'documentElement' based on what is working.
1149 * https://code.google.com/p/chromium/issues/detail?id=303131
1152 * @param {HTMLElement} el Element to find root scrollable parent for
1153 * @return {HTMLElement} Scrollable parent, `document.body` or `document.documentElement`
1154 * depending on browser
1156 OO
.ui
.Element
.static.getRootScrollableElement = function ( el
) {
1157 var scrollTop
, body
;
1159 if ( OO
.ui
.scrollableElement
=== undefined ) {
1160 body
= el
.ownerDocument
.body
;
1161 scrollTop
= body
.scrollTop
;
1164 if ( body
.scrollTop
=== 1 ) {
1165 body
.scrollTop
= scrollTop
;
1166 OO
.ui
.scrollableElement
= 'body';
1168 OO
.ui
.scrollableElement
= 'documentElement';
1172 return el
.ownerDocument
[ OO
.ui
.scrollableElement
];
1176 * Get closest scrollable container.
1178 * Traverses up until either a scrollable element or the root is reached, in which case the root
1179 * scrollable element will be returned (see #getRootScrollableElement).
1182 * @param {HTMLElement} el Element to find scrollable container for
1183 * @param {string} [dimension] Dimension of scrolling to look for; `x`, `y` or omit for either
1184 * @return {HTMLElement} Closest scrollable container
1186 OO
.ui
.Element
.static.getClosestScrollableContainer = function ( el
, dimension
) {
1188 // Browsers do not correctly return the computed value of 'overflow' when 'overflow-x' and
1189 // 'overflow-y' have different values, so we need to check the separate properties.
1190 props
= [ 'overflow-x', 'overflow-y' ],
1191 $parent
= $( el
).parent();
1193 if ( dimension
=== 'x' || dimension
=== 'y' ) {
1194 props
= [ 'overflow-' + dimension
];
1197 // Special case for the document root (which doesn't really have any scrollable container, since
1198 // it is the ultimate scrollable container, but this is probably saner than null or exception)
1199 if ( $( el
).is( 'html, body' ) ) {
1200 return this.getRootScrollableElement( el
);
1203 while ( $parent
.length
) {
1204 if ( $parent
[ 0 ] === this.getRootScrollableElement( el
) ) {
1205 return $parent
[ 0 ];
1209 val
= $parent
.css( props
[ i
] );
1210 // We assume that elements with 'overflow' (in any direction) set to 'hidden' will never be
1211 // scrolled in that direction, but they can actually be scrolled programatically. The user can
1212 // unintentionally perform a scroll in such case even if the application doesn't scroll
1213 // programatically, e.g. when jumping to an anchor, or when using built-in find functionality.
1214 // This could cause funny issues...
1215 if ( val
=== 'auto' || val
=== 'scroll' ) {
1216 return $parent
[ 0 ];
1219 $parent
= $parent
.parent();
1221 // The element is unattached... return something mostly sane
1222 return this.getRootScrollableElement( el
);
1226 * Scroll element into view.
1229 * @param {HTMLElement} el Element to scroll into view
1230 * @param {Object} [config] Configuration options
1231 * @param {string} [config.duration='fast'] jQuery animation duration value
1232 * @param {string} [config.direction] Scroll in only one direction, e.g. 'x' or 'y', omit
1233 * to scroll in both directions
1234 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1236 OO
.ui
.Element
.static.scrollIntoView = function ( el
, config
) {
1237 var position
, animations
, container
, $container
, elementDimensions
, containerDimensions
, $window
,
1238 deferred
= $.Deferred();
1240 // Configuration initialization
1241 config
= config
|| {};
1244 container
= this.getClosestScrollableContainer( el
, config
.direction
);
1245 $container
= $( container
);
1246 elementDimensions
= this.getDimensions( el
);
1247 containerDimensions
= this.getDimensions( container
);
1248 $window
= $( this.getWindow( el
) );
1250 // Compute the element's position relative to the container
1251 if ( $container
.is( 'html, body' ) ) {
1252 // If the scrollable container is the root, this is easy
1254 top
: elementDimensions
.rect
.top
,
1255 bottom
: $window
.innerHeight() - elementDimensions
.rect
.bottom
,
1256 left
: elementDimensions
.rect
.left
,
1257 right
: $window
.innerWidth() - elementDimensions
.rect
.right
1260 // Otherwise, we have to subtract el's coordinates from container's coordinates
1262 top
: elementDimensions
.rect
.top
- ( containerDimensions
.rect
.top
+ containerDimensions
.borders
.top
),
1263 bottom
: containerDimensions
.rect
.bottom
- containerDimensions
.borders
.bottom
- containerDimensions
.scrollbar
.bottom
- elementDimensions
.rect
.bottom
,
1264 left
: elementDimensions
.rect
.left
- ( containerDimensions
.rect
.left
+ containerDimensions
.borders
.left
),
1265 right
: containerDimensions
.rect
.right
- containerDimensions
.borders
.right
- containerDimensions
.scrollbar
.right
- elementDimensions
.rect
.right
1269 if ( !config
.direction
|| config
.direction
=== 'y' ) {
1270 if ( position
.top
< 0 ) {
1271 animations
.scrollTop
= containerDimensions
.scroll
.top
+ position
.top
;
1272 } else if ( position
.top
> 0 && position
.bottom
< 0 ) {
1273 animations
.scrollTop
= containerDimensions
.scroll
.top
+ Math
.min( position
.top
, -position
.bottom
);
1276 if ( !config
.direction
|| config
.direction
=== 'x' ) {
1277 if ( position
.left
< 0 ) {
1278 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ position
.left
;
1279 } else if ( position
.left
> 0 && position
.right
< 0 ) {
1280 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ Math
.min( position
.left
, -position
.right
);
1283 if ( !$.isEmptyObject( animations
) ) {
1284 $container
.stop( true ).animate( animations
, config
.duration
=== undefined ? 'fast' : config
.duration
);
1285 $container
.queue( function ( next
) {
1292 return deferred
.promise();
1296 * Force the browser to reconsider whether it really needs to render scrollbars inside the element
1297 * and reserve space for them, because it probably doesn't.
1299 * Workaround primarily for <https://code.google.com/p/chromium/issues/detail?id=387290>, but also
1300 * similar bugs in other browsers. "Just" forcing a reflow is not sufficient in all cases, we need
1301 * to first actually detach (or hide, but detaching is simpler) all children, *then* force a reflow,
1302 * and then reattach (or show) them back.
1305 * @param {HTMLElement} el Element to reconsider the scrollbars on
1307 OO
.ui
.Element
.static.reconsiderScrollbars = function ( el
) {
1308 var i
, len
, scrollLeft
, scrollTop
, nodes
= [];
1309 // Save scroll position
1310 scrollLeft
= el
.scrollLeft
;
1311 scrollTop
= el
.scrollTop
;
1312 // Detach all children
1313 while ( el
.firstChild
) {
1314 nodes
.push( el
.firstChild
);
1315 el
.removeChild( el
.firstChild
);
1318 void el
.offsetHeight
;
1319 // Reattach all children
1320 for ( i
= 0, len
= nodes
.length
; i
< len
; i
++ ) {
1321 el
.appendChild( nodes
[ i
] );
1323 // Restore scroll position (no-op if scrollbars disappeared)
1324 el
.scrollLeft
= scrollLeft
;
1325 el
.scrollTop
= scrollTop
;
1331 * Toggle visibility of an element.
1333 * @param {boolean} [show] Make element visible, omit to toggle visibility
1337 OO
.ui
.Element
.prototype.toggle = function ( show
) {
1338 show
= show
=== undefined ? !this.visible
: !!show
;
1340 if ( show
!== this.isVisible() ) {
1341 this.visible
= show
;
1342 this.$element
.toggleClass( 'oo-ui-element-hidden', !this.visible
);
1343 this.emit( 'toggle', show
);
1350 * Check if element is visible.
1352 * @return {boolean} element is visible
1354 OO
.ui
.Element
.prototype.isVisible = function () {
1355 return this.visible
;
1361 * @return {Mixed} Element data
1363 OO
.ui
.Element
.prototype.getData = function () {
1370 * @param {Mixed} data Element data
1373 OO
.ui
.Element
.prototype.setData = function ( data
) {
1379 * Check if element supports one or more methods.
1381 * @param {string|string[]} methods Method or list of methods to check
1382 * @return {boolean} All methods are supported
1384 OO
.ui
.Element
.prototype.supports = function ( methods
) {
1388 methods
= Array
.isArray( methods
) ? methods
: [ methods
];
1389 for ( i
= 0, len
= methods
.length
; i
< len
; i
++ ) {
1390 if ( $.isFunction( this[ methods
[ i
] ] ) ) {
1395 return methods
.length
=== support
;
1399 * Update the theme-provided classes.
1401 * @localdoc This is called in element mixins and widget classes any time state changes.
1402 * Updating is debounced, minimizing overhead of changing multiple attributes and
1403 * guaranteeing that theme updates do not occur within an element's constructor
1405 OO
.ui
.Element
.prototype.updateThemeClasses = function () {
1406 OO
.ui
.theme
.queueUpdateElementClasses( this );
1410 * Get the HTML tag name.
1412 * Override this method to base the result on instance information.
1414 * @return {string} HTML tag name
1416 OO
.ui
.Element
.prototype.getTagName = function () {
1417 return this.constructor.static.tagName
;
1421 * Check if the element is attached to the DOM
1423 * @return {boolean} The element is attached to the DOM
1425 OO
.ui
.Element
.prototype.isElementAttached = function () {
1426 return $.contains( this.getElementDocument(), this.$element
[ 0 ] );
1430 * Get the DOM document.
1432 * @return {HTMLDocument} Document object
1434 OO
.ui
.Element
.prototype.getElementDocument = function () {
1435 // Don't cache this in other ways either because subclasses could can change this.$element
1436 return OO
.ui
.Element
.static.getDocument( this.$element
);
1440 * Get the DOM window.
1442 * @return {Window} Window object
1444 OO
.ui
.Element
.prototype.getElementWindow = function () {
1445 return OO
.ui
.Element
.static.getWindow( this.$element
);
1449 * Get closest scrollable container.
1451 * @return {HTMLElement} Closest scrollable container
1453 OO
.ui
.Element
.prototype.getClosestScrollableElementContainer = function () {
1454 return OO
.ui
.Element
.static.getClosestScrollableContainer( this.$element
[ 0 ] );
1458 * Get group element is in.
1460 * @return {OO.ui.mixin.GroupElement|null} Group element, null if none
1462 OO
.ui
.Element
.prototype.getElementGroup = function () {
1463 return this.elementGroup
;
1467 * Set group element is in.
1469 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
1472 OO
.ui
.Element
.prototype.setElementGroup = function ( group
) {
1473 this.elementGroup
= group
;
1478 * Scroll element into view.
1480 * @param {Object} [config] Configuration options
1481 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1483 OO
.ui
.Element
.prototype.scrollElementIntoView = function ( config
) {
1485 !this.isElementAttached() ||
1486 !this.isVisible() ||
1487 ( this.getElementGroup() && !this.getElementGroup().isVisible() )
1489 return $.Deferred().resolve();
1491 return OO
.ui
.Element
.static.scrollIntoView( this.$element
[ 0 ], config
);
1495 * Restore the pre-infusion dynamic state for this widget.
1497 * This method is called after #$element has been inserted into DOM. The parameter is the return
1498 * value of #gatherPreInfuseState.
1501 * @param {Object} state
1503 OO
.ui
.Element
.prototype.restorePreInfuseState = function () {
1507 * Wraps an HTML snippet for use with configuration values which default
1508 * to strings. This bypasses the default html-escaping done to string
1514 * @param {string} [content] HTML content
1516 OO
.ui
.HtmlSnippet
= function OoUiHtmlSnippet( content
) {
1518 this.content
= content
;
1523 OO
.initClass( OO
.ui
.HtmlSnippet
);
1530 * @return {string} Unchanged HTML snippet.
1532 OO
.ui
.HtmlSnippet
.prototype.toString = function () {
1533 return this.content
;
1537 * Layouts are containers for elements and are used to arrange other widgets of arbitrary type in a way
1538 * that is centrally controlled and can be updated dynamically. Layouts can be, and usually are, combined.
1539 * See {@link OO.ui.FieldsetLayout FieldsetLayout}, {@link OO.ui.FieldLayout FieldLayout}, {@link OO.ui.FormLayout FormLayout},
1540 * {@link OO.ui.PanelLayout PanelLayout}, {@link OO.ui.StackLayout StackLayout}, {@link OO.ui.PageLayout PageLayout},
1541 * {@link OO.ui.HorizontalLayout HorizontalLayout}, and {@link OO.ui.BookletLayout BookletLayout} for more information and examples.
1545 * @extends OO.ui.Element
1546 * @mixins OO.EventEmitter
1549 * @param {Object} [config] Configuration options
1551 OO
.ui
.Layout
= function OoUiLayout( config
) {
1552 // Configuration initialization
1553 config
= config
|| {};
1555 // Parent constructor
1556 OO
.ui
.Layout
.parent
.call( this, config
);
1558 // Mixin constructors
1559 OO
.EventEmitter
.call( this );
1562 this.$element
.addClass( 'oo-ui-layout' );
1567 OO
.inheritClass( OO
.ui
.Layout
, OO
.ui
.Element
);
1568 OO
.mixinClass( OO
.ui
.Layout
, OO
.EventEmitter
);
1571 * Widgets are compositions of one or more OOjs UI elements that users can both view
1572 * and interact with. All widgets can be configured and modified via a standard API,
1573 * and their state can change dynamically according to a model.
1577 * @extends OO.ui.Element
1578 * @mixins OO.EventEmitter
1581 * @param {Object} [config] Configuration options
1582 * @cfg {boolean} [disabled=false] Disable the widget. Disabled widgets cannot be used and their
1583 * appearance reflects this state.
1585 OO
.ui
.Widget
= function OoUiWidget( config
) {
1586 // Initialize config
1587 config
= $.extend( { disabled
: false }, config
);
1589 // Parent constructor
1590 OO
.ui
.Widget
.parent
.call( this, config
);
1592 // Mixin constructors
1593 OO
.EventEmitter
.call( this );
1596 this.disabled
= null;
1597 this.wasDisabled
= null;
1600 this.$element
.addClass( 'oo-ui-widget' );
1601 this.setDisabled( !!config
.disabled
);
1606 OO
.inheritClass( OO
.ui
.Widget
, OO
.ui
.Element
);
1607 OO
.mixinClass( OO
.ui
.Widget
, OO
.EventEmitter
);
1609 /* Static Properties */
1612 * Whether this widget will behave reasonably when wrapped in an HTML `<label>`. If this is true,
1613 * wrappers such as OO.ui.FieldLayout may use a `<label>` instead of implementing own label click
1618 * @property {boolean}
1620 OO
.ui
.Widget
.static.supportsSimpleLabel
= false;
1627 * A 'disable' event is emitted when the disabled state of the widget changes
1628 * (i.e. on disable **and** enable).
1630 * @param {boolean} disabled Widget is disabled
1636 * A 'toggle' event is emitted when the visibility of the widget changes.
1638 * @param {boolean} visible Widget is visible
1644 * Check if the widget is disabled.
1646 * @return {boolean} Widget is disabled
1648 OO
.ui
.Widget
.prototype.isDisabled = function () {
1649 return this.disabled
;
1653 * Set the 'disabled' state of the widget.
1655 * When a widget is disabled, it cannot be used and its appearance is updated to reflect this state.
1657 * @param {boolean} disabled Disable widget
1660 OO
.ui
.Widget
.prototype.setDisabled = function ( disabled
) {
1663 this.disabled
= !!disabled
;
1664 isDisabled
= this.isDisabled();
1665 if ( isDisabled
!== this.wasDisabled
) {
1666 this.$element
.toggleClass( 'oo-ui-widget-disabled', isDisabled
);
1667 this.$element
.toggleClass( 'oo-ui-widget-enabled', !isDisabled
);
1668 this.$element
.attr( 'aria-disabled', isDisabled
.toString() );
1669 this.emit( 'disable', isDisabled
);
1670 this.updateThemeClasses();
1672 this.wasDisabled
= isDisabled
;
1678 * Update the disabled state, in case of changes in parent widget.
1682 OO
.ui
.Widget
.prototype.updateDisabled = function () {
1683 this.setDisabled( this.disabled
);
1695 OO
.ui
.Theme
= function OoUiTheme() {
1696 this.elementClassesQueue
= [];
1697 this.debouncedUpdateQueuedElementClasses
= OO
.ui
.debounce( this.updateQueuedElementClasses
);
1702 OO
.initClass( OO
.ui
.Theme
);
1707 * Get a list of classes to be applied to a widget.
1709 * The 'on' and 'off' lists combined MUST contain keys for all classes the theme adds or removes,
1710 * otherwise state transitions will not work properly.
1712 * @param {OO.ui.Element} element Element for which to get classes
1713 * @return {Object.<string,string[]>} Categorized class names with `on` and `off` lists
1715 OO
.ui
.Theme
.prototype.getElementClasses = function () {
1716 return { on
: [], off
: [] };
1720 * Update CSS classes provided by the theme.
1722 * For elements with theme logic hooks, this should be called any time there's a state change.
1724 * @param {OO.ui.Element} element Element for which to update classes
1726 OO
.ui
.Theme
.prototype.updateElementClasses = function ( element
) {
1727 var $elements
= $( [] ),
1728 classes
= this.getElementClasses( element
);
1730 if ( element
.$icon
) {
1731 $elements
= $elements
.add( element
.$icon
);
1733 if ( element
.$indicator
) {
1734 $elements
= $elements
.add( element
.$indicator
);
1738 .removeClass( classes
.off
.join( ' ' ) )
1739 .addClass( classes
.on
.join( ' ' ) );
1745 OO
.ui
.Theme
.prototype.updateQueuedElementClasses = function () {
1747 for ( i
= 0; i
< this.elementClassesQueue
.length
; i
++ ) {
1748 this.updateElementClasses( this.elementClassesQueue
[ i
] );
1751 this.elementClassesQueue
= [];
1755 * Queue #updateElementClasses to be called for this element.
1757 * @localdoc QUnit tests override this method to directly call #queueUpdateElementClasses,
1758 * to make them synchronous.
1760 * @param {OO.ui.Element} element Element for which to update classes
1762 OO
.ui
.Theme
.prototype.queueUpdateElementClasses = function ( element
) {
1763 // Keep items in the queue unique. Use lastIndexOf to start checking from the end because that's
1764 // the most common case (this method is often called repeatedly for the same element).
1765 if ( this.elementClassesQueue
.lastIndexOf( element
) !== -1 ) {
1768 this.elementClassesQueue
.push( element
);
1769 this.debouncedUpdateQueuedElementClasses();
1773 * Get the transition duration in milliseconds for dialogs opening/closing
1775 * The dialog should be fully rendered this many milliseconds after the
1776 * ready process has executed.
1778 * @return {number} Transition duration in milliseconds
1780 OO
.ui
.Theme
.prototype.getDialogTransitionDuration = function () {
1785 * The TabIndexedElement class is an attribute mixin used to add additional functionality to an
1786 * element created by another class. The mixin provides a ‘tabIndex’ property, which specifies the
1787 * order in which users will navigate through the focusable elements via the "tab" key.
1790 * // TabIndexedElement is mixed into the ButtonWidget class
1791 * // to provide a tabIndex property.
1792 * var button1 = new OO.ui.ButtonWidget( {
1796 * var button2 = new OO.ui.ButtonWidget( {
1800 * var button3 = new OO.ui.ButtonWidget( {
1804 * var button4 = new OO.ui.ButtonWidget( {
1808 * $( 'body' ).append( button1.$element, button2.$element, button3.$element, button4.$element );
1814 * @param {Object} [config] Configuration options
1815 * @cfg {jQuery} [$tabIndexed] The element that should use the tabindex functionality. By default,
1816 * the functionality is applied to the element created by the class ($element). If a different element is specified, the tabindex
1817 * functionality will be applied to it instead.
1818 * @cfg {number|null} [tabIndex=0] Number that specifies the element’s position in the tab-navigation
1819 * order (e.g., 1 for the first focusable element). Use 0 to use the default navigation order; use -1
1820 * to remove the element from the tab-navigation flow.
1822 OO
.ui
.mixin
.TabIndexedElement
= function OoUiMixinTabIndexedElement( config
) {
1823 // Configuration initialization
1824 config
= $.extend( { tabIndex
: 0 }, config
);
1827 this.$tabIndexed
= null;
1828 this.tabIndex
= null;
1831 this.connect( this, { disable
: 'onTabIndexedElementDisable' } );
1834 this.setTabIndex( config
.tabIndex
);
1835 this.setTabIndexedElement( config
.$tabIndexed
|| this.$element
);
1840 OO
.initClass( OO
.ui
.mixin
.TabIndexedElement
);
1845 * Set the element that should use the tabindex functionality.
1847 * This method is used to retarget a tabindex mixin so that its functionality applies
1848 * to the specified element. If an element is currently using the functionality, the mixin’s
1849 * effect on that element is removed before the new element is set up.
1851 * @param {jQuery} $tabIndexed Element that should use the tabindex functionality
1854 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndexedElement = function ( $tabIndexed
) {
1855 var tabIndex
= this.tabIndex
;
1856 // Remove attributes from old $tabIndexed
1857 this.setTabIndex( null );
1858 // Force update of new $tabIndexed
1859 this.$tabIndexed
= $tabIndexed
;
1860 this.tabIndex
= tabIndex
;
1861 return this.updateTabIndex();
1865 * Set the value of the tabindex.
1867 * @param {number|null} tabIndex Tabindex value, or `null` for no tabindex
1870 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndex = function ( tabIndex
) {
1871 tabIndex
= typeof tabIndex
=== 'number' ? tabIndex
: null;
1873 if ( this.tabIndex
!== tabIndex
) {
1874 this.tabIndex
= tabIndex
;
1875 this.updateTabIndex();
1882 * Update the `tabindex` attribute, in case of changes to tab index or
1888 OO
.ui
.mixin
.TabIndexedElement
.prototype.updateTabIndex = function () {
1889 if ( this.$tabIndexed
) {
1890 if ( this.tabIndex
!== null ) {
1891 // Do not index over disabled elements
1892 this.$tabIndexed
.attr( {
1893 tabindex
: this.isDisabled() ? -1 : this.tabIndex
,
1894 // Support: ChromeVox and NVDA
1895 // These do not seem to inherit aria-disabled from parent elements
1896 'aria-disabled': this.isDisabled().toString()
1899 this.$tabIndexed
.removeAttr( 'tabindex aria-disabled' );
1906 * Handle disable events.
1909 * @param {boolean} disabled Element is disabled
1911 OO
.ui
.mixin
.TabIndexedElement
.prototype.onTabIndexedElementDisable = function () {
1912 this.updateTabIndex();
1916 * Get the value of the tabindex.
1918 * @return {number|null} Tabindex value
1920 OO
.ui
.mixin
.TabIndexedElement
.prototype.getTabIndex = function () {
1921 return this.tabIndex
;
1925 * ButtonElement is often mixed into other classes to generate a button, which is a clickable
1926 * interface element that can be configured with access keys for accessibility.
1927 * See the [OOjs UI documentation on MediaWiki] [1] for examples.
1929 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#Buttons
1935 * @param {Object} [config] Configuration options
1936 * @cfg {jQuery} [$button] The button element created by the class.
1937 * If this configuration is omitted, the button element will use a generated `<a>`.
1938 * @cfg {boolean} [framed=true] Render the button with a frame
1940 OO
.ui
.mixin
.ButtonElement
= function OoUiMixinButtonElement( config
) {
1941 // Configuration initialization
1942 config
= config
|| {};
1945 this.$button
= null;
1947 this.active
= config
.active
!== undefined && config
.active
;
1948 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
1949 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
1950 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
1951 this.onKeyUpHandler
= this.onKeyUp
.bind( this );
1952 this.onClickHandler
= this.onClick
.bind( this );
1953 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
1956 this.$element
.addClass( 'oo-ui-buttonElement' );
1957 this.toggleFramed( config
.framed
=== undefined || config
.framed
);
1958 this.setButtonElement( config
.$button
|| $( '<a>' ) );
1963 OO
.initClass( OO
.ui
.mixin
.ButtonElement
);
1965 /* Static Properties */
1968 * Cancel mouse down events.
1970 * This property is usually set to `true` to prevent the focus from changing when the button is clicked.
1971 * Classes such as {@link OO.ui.mixin.DraggableElement DraggableElement} and {@link OO.ui.ButtonOptionWidget ButtonOptionWidget}
1972 * use a value of `false` so that dragging behavior is possible and mousedown events can be handled by a
1977 * @property {boolean}
1979 OO
.ui
.mixin
.ButtonElement
.static.cancelButtonMouseDownEvents
= true;
1984 * A 'click' event is emitted when the button element is clicked.
1992 * Set the button element.
1994 * This method is used to retarget a button mixin so that its functionality applies to
1995 * the specified button element instead of the one created by the class. If a button element
1996 * is already set, the method will remove the mixin’s effect on that element.
1998 * @param {jQuery} $button Element to use as button
2000 OO
.ui
.mixin
.ButtonElement
.prototype.setButtonElement = function ( $button
) {
2001 if ( this.$button
) {
2003 .removeClass( 'oo-ui-buttonElement-button' )
2004 .removeAttr( 'role accesskey' )
2006 mousedown
: this.onMouseDownHandler
,
2007 keydown
: this.onKeyDownHandler
,
2008 click
: this.onClickHandler
,
2009 keypress
: this.onKeyPressHandler
2013 this.$button
= $button
2014 .addClass( 'oo-ui-buttonElement-button' )
2016 mousedown
: this.onMouseDownHandler
,
2017 keydown
: this.onKeyDownHandler
,
2018 click
: this.onClickHandler
,
2019 keypress
: this.onKeyPressHandler
2022 // Add `role="button"` on `<a>` elements, where it's needed
2023 // `toUppercase()` is added for XHTML documents
2024 if ( this.$button
.prop( 'tagName' ).toUpperCase() === 'A' ) {
2025 this.$button
.attr( 'role', 'button' );
2030 * Handles mouse down events.
2033 * @param {jQuery.Event} e Mouse down event
2035 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseDown = function ( e
) {
2036 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
2039 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
2040 // Run the mouseup handler no matter where the mouse is when the button is let go, so we can
2041 // reliably remove the pressed class
2042 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
2043 // Prevent change of focus unless specifically configured otherwise
2044 if ( this.constructor.static.cancelButtonMouseDownEvents
) {
2050 * Handles mouse up events.
2053 * @param {MouseEvent} e Mouse up event
2055 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseUp = function ( e
) {
2056 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
2059 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
2060 // Stop listening for mouseup, since we only needed this once
2061 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
2065 * Handles mouse click events.
2068 * @param {jQuery.Event} e Mouse click event
2071 OO
.ui
.mixin
.ButtonElement
.prototype.onClick = function ( e
) {
2072 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
2073 if ( this.emit( 'click' ) ) {
2080 * Handles key down events.
2083 * @param {jQuery.Event} e Key down event
2085 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyDown = function ( e
) {
2086 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
2089 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
2090 // Run the keyup handler no matter where the key is when the button is let go, so we can
2091 // reliably remove the pressed class
2092 this.getElementDocument().addEventListener( 'keyup', this.onKeyUpHandler
, true );
2096 * Handles key up events.
2099 * @param {KeyboardEvent} e Key up event
2101 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyUp = function ( e
) {
2102 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
2105 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
2106 // Stop listening for keyup, since we only needed this once
2107 this.getElementDocument().removeEventListener( 'keyup', this.onKeyUpHandler
, true );
2111 * Handles key press events.
2114 * @param {jQuery.Event} e Key press event
2117 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyPress = function ( e
) {
2118 if ( !this.isDisabled() && ( e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
) ) {
2119 if ( this.emit( 'click' ) ) {
2126 * Check if button has a frame.
2128 * @return {boolean} Button is framed
2130 OO
.ui
.mixin
.ButtonElement
.prototype.isFramed = function () {
2135 * Render the button with or without a frame. Omit the `framed` parameter to toggle the button frame on and off.
2137 * @param {boolean} [framed] Make button framed, omit to toggle
2140 OO
.ui
.mixin
.ButtonElement
.prototype.toggleFramed = function ( framed
) {
2141 framed
= framed
=== undefined ? !this.framed
: !!framed
;
2142 if ( framed
!== this.framed
) {
2143 this.framed
= framed
;
2145 .toggleClass( 'oo-ui-buttonElement-frameless', !framed
)
2146 .toggleClass( 'oo-ui-buttonElement-framed', framed
);
2147 this.updateThemeClasses();
2154 * Set the button's active state.
2156 * The active state can be set on:
2158 * - {@link OO.ui.ButtonOptionWidget ButtonOptionWidget} when it is selected
2159 * - {@link OO.ui.ToggleButtonWidget ToggleButtonWidget} when it is toggle on
2160 * - {@link OO.ui.ButtonWidget ButtonWidget} when clicking the button would only refresh the page
2163 * @param {boolean} value Make button active
2166 OO
.ui
.mixin
.ButtonElement
.prototype.setActive = function ( value
) {
2167 this.active
= !!value
;
2168 this.$element
.toggleClass( 'oo-ui-buttonElement-active', this.active
);
2169 this.updateThemeClasses();
2174 * Check if the button is active
2177 * @return {boolean} The button is active
2179 OO
.ui
.mixin
.ButtonElement
.prototype.isActive = function () {
2184 * Any OOjs UI widget that contains other widgets (such as {@link OO.ui.ButtonWidget buttons} or
2185 * {@link OO.ui.OptionWidget options}) mixes in GroupElement. Adding, removing, and clearing
2186 * items from the group is done through the interface the class provides.
2187 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
2189 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Groups
2192 * @mixins OO.EmitterList
2196 * @param {Object} [config] Configuration options
2197 * @cfg {jQuery} [$group] The container element created by the class. If this configuration
2198 * is omitted, the group element will use a generated `<div>`.
2200 OO
.ui
.mixin
.GroupElement
= function OoUiMixinGroupElement( config
) {
2201 // Configuration initialization
2202 config
= config
|| {};
2204 // Mixin constructors
2205 OO
.EmitterList
.call( this, config
);
2211 this.setGroupElement( config
.$group
|| $( '<div>' ) );
2216 OO
.mixinClass( OO
.ui
.mixin
.GroupElement
, OO
.EmitterList
);
2223 * A change event is emitted when the set of selected items changes.
2225 * @param {OO.ui.Element[]} items Items currently in the group
2231 * Set the group element.
2233 * If an element is already set, items will be moved to the new element.
2235 * @param {jQuery} $group Element to use as group
2237 OO
.ui
.mixin
.GroupElement
.prototype.setGroupElement = function ( $group
) {
2240 this.$group
= $group
;
2241 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2242 this.$group
.append( this.items
[ i
].$element
);
2247 * Get an item by its data.
2249 * Only the first item with matching data will be returned. To return all matching items,
2250 * use the #getItemsFromData method.
2252 * @param {Object} data Item data to search for
2253 * @return {OO.ui.Element|null} Item with equivalent data, `null` if none exists
2255 OO
.ui
.mixin
.GroupElement
.prototype.getItemFromData = function ( data
) {
2257 hash
= OO
.getHash( data
);
2259 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2260 item
= this.items
[ i
];
2261 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2270 * Get items by their data.
2272 * All items with matching data will be returned. To return only the first match, use the #getItemFromData method instead.
2274 * @param {Object} data Item data to search for
2275 * @return {OO.ui.Element[]} Items with equivalent data
2277 OO
.ui
.mixin
.GroupElement
.prototype.getItemsFromData = function ( data
) {
2279 hash
= OO
.getHash( data
),
2282 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2283 item
= this.items
[ i
];
2284 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2293 * Add items to the group.
2295 * Items will be added to the end of the group array unless the optional `index` parameter specifies
2296 * a different insertion point. Adding an existing item will move it to the end of the array or the point specified by the `index`.
2298 * @param {OO.ui.Element[]} items An array of items to add to the group
2299 * @param {number} [index] Index of the insertion point
2302 OO
.ui
.mixin
.GroupElement
.prototype.addItems = function ( items
, index
) {
2304 OO
.EmitterList
.prototype.addItems
.call( this, items
, index
);
2306 this.emit( 'change', this.getItems() );
2313 OO
.ui
.mixin
.GroupElement
.prototype.moveItem = function ( items
, newIndex
) {
2314 // insertItemElements expects this.items to not have been modified yet, so call before the mixin
2315 this.insertItemElements( items
, newIndex
);
2318 newIndex
= OO
.EmitterList
.prototype.moveItem
.call( this, items
, newIndex
);
2326 OO
.ui
.mixin
.GroupElement
.prototype.insertItem = function ( item
, index
) {
2327 item
.setElementGroup( this );
2328 this.insertItemElements( item
, index
);
2331 index
= OO
.EmitterList
.prototype.insertItem
.call( this, item
, index
);
2337 * Insert elements into the group
2340 * @param {OO.ui.Element} itemWidget Item to insert
2341 * @param {number} index Insertion index
2343 OO
.ui
.mixin
.GroupElement
.prototype.insertItemElements = function ( itemWidget
, index
) {
2344 if ( index
=== undefined || index
< 0 || index
>= this.items
.length
) {
2345 this.$group
.append( itemWidget
.$element
);
2346 } else if ( index
=== 0 ) {
2347 this.$group
.prepend( itemWidget
.$element
);
2349 this.items
[ index
].$element
.before( itemWidget
.$element
);
2354 * Remove the specified items from a group.
2356 * Removed items are detached (not removed) from the DOM so that they may be reused.
2357 * To remove all items from a group, you may wish to use the #clearItems method instead.
2359 * @param {OO.ui.Element[]} items An array of items to remove
2362 OO
.ui
.mixin
.GroupElement
.prototype.removeItems = function ( items
) {
2363 var i
, len
, item
, index
;
2365 // Remove specific items elements
2366 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
2368 index
= this.items
.indexOf( item
);
2369 if ( index
!== -1 ) {
2370 item
.setElementGroup( null );
2371 item
.$element
.detach();
2376 OO
.EmitterList
.prototype.removeItems
.call( this, items
);
2378 this.emit( 'change', this.getItems() );
2383 * Clear all items from the group.
2385 * Cleared items are detached from the DOM, not removed, so that they may be reused.
2386 * To remove only a subset of items from a group, use the #removeItems method.
2390 OO
.ui
.mixin
.GroupElement
.prototype.clearItems = function () {
2393 // Remove all item elements
2394 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2395 this.items
[ i
].setElementGroup( null );
2396 this.items
[ i
].$element
.detach();
2400 OO
.EmitterList
.prototype.clearItems
.call( this );
2402 this.emit( 'change', this.getItems() );
2407 * IconElement is often mixed into other classes to generate an icon.
2408 * Icons are graphics, about the size of normal text. They are used to aid the user
2409 * in locating a control or to convey information in a space-efficient way. See the
2410 * [OOjs UI documentation on MediaWiki] [1] for a list of icons
2411 * included in the library.
2413 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2419 * @param {Object} [config] Configuration options
2420 * @cfg {jQuery} [$icon] The icon element created by the class. If this configuration is omitted,
2421 * the icon element will use a generated `<span>`. To use a different HTML tag, or to specify that
2422 * the icon element be set to an existing icon instead of the one generated by this class, set a
2423 * value using a jQuery selection. For example:
2425 * // Use a <div> tag instead of a <span>
2427 * // Use an existing icon element instead of the one generated by the class
2428 * $icon: this.$element
2429 * // Use an icon element from a child widget
2430 * $icon: this.childwidget.$element
2431 * @cfg {Object|string} [icon=''] The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of
2432 * symbolic names. A map is used for i18n purposes and contains a `default` icon
2433 * name and additional names keyed by language code. The `default` name is used when no icon is keyed
2434 * by the user's language.
2436 * Example of an i18n map:
2438 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2439 * See the [OOjs UI documentation on MediaWiki] [2] for a list of icons included in the library.
2440 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2441 * @cfg {string|Function} [iconTitle] A text string used as the icon title, or a function that returns title
2442 * text. The icon title is displayed when users move the mouse over the icon.
2444 OO
.ui
.mixin
.IconElement
= function OoUiMixinIconElement( config
) {
2445 // Configuration initialization
2446 config
= config
|| {};
2451 this.iconTitle
= null;
2454 this.setIcon( config
.icon
|| this.constructor.static.icon
);
2455 this.setIconTitle( config
.iconTitle
|| this.constructor.static.iconTitle
);
2456 this.setIconElement( config
.$icon
|| $( '<span>' ) );
2461 OO
.initClass( OO
.ui
.mixin
.IconElement
);
2463 /* Static Properties */
2466 * The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of symbolic names. A map is used
2467 * for i18n purposes and contains a `default` icon name and additional names keyed by
2468 * language code. The `default` name is used when no icon is keyed by the user's language.
2470 * Example of an i18n map:
2472 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2474 * Note: the static property will be overridden if the #icon configuration is used.
2478 * @property {Object|string}
2480 OO
.ui
.mixin
.IconElement
.static.icon
= null;
2483 * The icon title, displayed when users move the mouse over the icon. The value can be text, a
2484 * function that returns title text, or `null` for no title.
2486 * The static property will be overridden if the #iconTitle configuration is used.
2490 * @property {string|Function|null}
2492 OO
.ui
.mixin
.IconElement
.static.iconTitle
= null;
2497 * Set the icon element. This method is used to retarget an icon mixin so that its functionality
2498 * applies to the specified icon element instead of the one created by the class. If an icon
2499 * element is already set, the mixin’s effect on that element is removed. Generated CSS classes
2500 * and mixin methods will no longer affect the element.
2502 * @param {jQuery} $icon Element to use as icon
2504 OO
.ui
.mixin
.IconElement
.prototype.setIconElement = function ( $icon
) {
2507 .removeClass( 'oo-ui-iconElement-icon oo-ui-icon-' + this.icon
)
2508 .removeAttr( 'title' );
2512 .addClass( 'oo-ui-iconElement-icon' )
2513 .toggleClass( 'oo-ui-icon-' + this.icon
, !!this.icon
);
2514 if ( this.iconTitle
!== null ) {
2515 this.$icon
.attr( 'title', this.iconTitle
);
2518 this.updateThemeClasses();
2522 * Set icon by symbolic name (e.g., ‘remove’ or ‘menu’). Use `null` to remove an icon.
2523 * The icon parameter can also be set to a map of icon names. See the #icon config setting
2526 * @param {Object|string|null} icon A symbolic icon name, a {@link #icon map of icon names} keyed
2527 * by language code, or `null` to remove the icon.
2530 OO
.ui
.mixin
.IconElement
.prototype.setIcon = function ( icon
) {
2531 icon
= OO
.isPlainObject( icon
) ? OO
.ui
.getLocalValue( icon
, null, 'default' ) : icon
;
2532 icon
= typeof icon
=== 'string' && icon
.trim().length
? icon
.trim() : null;
2534 if ( this.icon
!== icon
) {
2536 if ( this.icon
!== null ) {
2537 this.$icon
.removeClass( 'oo-ui-icon-' + this.icon
);
2539 if ( icon
!== null ) {
2540 this.$icon
.addClass( 'oo-ui-icon-' + icon
);
2546 this.$element
.toggleClass( 'oo-ui-iconElement', !!this.icon
);
2547 this.updateThemeClasses();
2553 * Set the icon title. Use `null` to remove the title.
2555 * @param {string|Function|null} iconTitle A text string used as the icon title,
2556 * a function that returns title text, or `null` for no title.
2559 OO
.ui
.mixin
.IconElement
.prototype.setIconTitle = function ( iconTitle
) {
2560 iconTitle
= typeof iconTitle
=== 'function' ||
2561 ( typeof iconTitle
=== 'string' && iconTitle
.length
) ?
2562 OO
.ui
.resolveMsg( iconTitle
) : null;
2564 if ( this.iconTitle
!== iconTitle
) {
2565 this.iconTitle
= iconTitle
;
2567 if ( this.iconTitle
!== null ) {
2568 this.$icon
.attr( 'title', iconTitle
);
2570 this.$icon
.removeAttr( 'title' );
2579 * Get the symbolic name of the icon.
2581 * @return {string} Icon name
2583 OO
.ui
.mixin
.IconElement
.prototype.getIcon = function () {
2588 * Get the icon title. The title text is displayed when a user moves the mouse over the icon.
2590 * @return {string} Icon title text
2592 OO
.ui
.mixin
.IconElement
.prototype.getIconTitle = function () {
2593 return this.iconTitle
;
2597 * IndicatorElement is often mixed into other classes to generate an indicator.
2598 * Indicators are small graphics that are generally used in two ways:
2600 * - To draw attention to the status of an item. For example, an indicator might be
2601 * used to show that an item in a list has errors that need to be resolved.
2602 * - To clarify the function of a control that acts in an exceptional way (a button
2603 * that opens a menu instead of performing an action directly, for example).
2605 * For a list of indicators included in the library, please see the
2606 * [OOjs UI documentation on MediaWiki] [1].
2608 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2614 * @param {Object} [config] Configuration options
2615 * @cfg {jQuery} [$indicator] The indicator element created by the class. If this
2616 * configuration is omitted, the indicator element will use a generated `<span>`.
2617 * @cfg {string} [indicator] Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2618 * See the [OOjs UI documentation on MediaWiki][2] for a list of indicators included
2620 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2621 * @cfg {string|Function} [indicatorTitle] A text string used as the indicator title,
2622 * or a function that returns title text. The indicator title is displayed when users move
2623 * the mouse over the indicator.
2625 OO
.ui
.mixin
.IndicatorElement
= function OoUiMixinIndicatorElement( config
) {
2626 // Configuration initialization
2627 config
= config
|| {};
2630 this.$indicator
= null;
2631 this.indicator
= null;
2632 this.indicatorTitle
= null;
2635 this.setIndicator( config
.indicator
|| this.constructor.static.indicator
);
2636 this.setIndicatorTitle( config
.indicatorTitle
|| this.constructor.static.indicatorTitle
);
2637 this.setIndicatorElement( config
.$indicator
|| $( '<span>' ) );
2642 OO
.initClass( OO
.ui
.mixin
.IndicatorElement
);
2644 /* Static Properties */
2647 * Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2648 * The static property will be overridden if the #indicator configuration is used.
2652 * @property {string|null}
2654 OO
.ui
.mixin
.IndicatorElement
.static.indicator
= null;
2657 * A text string used as the indicator title, a function that returns title text, or `null`
2658 * for no title. The static property will be overridden if the #indicatorTitle configuration is used.
2662 * @property {string|Function|null}
2664 OO
.ui
.mixin
.IndicatorElement
.static.indicatorTitle
= null;
2669 * Set the indicator element.
2671 * If an element is already set, it will be cleaned up before setting up the new element.
2673 * @param {jQuery} $indicator Element to use as indicator
2675 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorElement = function ( $indicator
) {
2676 if ( this.$indicator
) {
2678 .removeClass( 'oo-ui-indicatorElement-indicator oo-ui-indicator-' + this.indicator
)
2679 .removeAttr( 'title' );
2682 this.$indicator
= $indicator
2683 .addClass( 'oo-ui-indicatorElement-indicator' )
2684 .toggleClass( 'oo-ui-indicator-' + this.indicator
, !!this.indicator
);
2685 if ( this.indicatorTitle
!== null ) {
2686 this.$indicator
.attr( 'title', this.indicatorTitle
);
2689 this.updateThemeClasses();
2693 * Set the indicator by its symbolic name: ‘alert’, ‘down’, ‘next’, ‘previous’, ‘required’, ‘up’. Use `null` to remove the indicator.
2695 * @param {string|null} indicator Symbolic name of indicator, or `null` for no indicator
2698 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicator = function ( indicator
) {
2699 indicator
= typeof indicator
=== 'string' && indicator
.length
? indicator
.trim() : null;
2701 if ( this.indicator
!== indicator
) {
2702 if ( this.$indicator
) {
2703 if ( this.indicator
!== null ) {
2704 this.$indicator
.removeClass( 'oo-ui-indicator-' + this.indicator
);
2706 if ( indicator
!== null ) {
2707 this.$indicator
.addClass( 'oo-ui-indicator-' + indicator
);
2710 this.indicator
= indicator
;
2713 this.$element
.toggleClass( 'oo-ui-indicatorElement', !!this.indicator
);
2714 this.updateThemeClasses();
2720 * Set the indicator title.
2722 * The title is displayed when a user moves the mouse over the indicator.
2724 * @param {string|Function|null} indicatorTitle Indicator title text, a function that returns text, or
2725 * `null` for no indicator title
2728 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorTitle = function ( indicatorTitle
) {
2729 indicatorTitle
= typeof indicatorTitle
=== 'function' ||
2730 ( typeof indicatorTitle
=== 'string' && indicatorTitle
.length
) ?
2731 OO
.ui
.resolveMsg( indicatorTitle
) : null;
2733 if ( this.indicatorTitle
!== indicatorTitle
) {
2734 this.indicatorTitle
= indicatorTitle
;
2735 if ( this.$indicator
) {
2736 if ( this.indicatorTitle
!== null ) {
2737 this.$indicator
.attr( 'title', indicatorTitle
);
2739 this.$indicator
.removeAttr( 'title' );
2748 * Get the symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2750 * @return {string} Symbolic name of indicator
2752 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicator = function () {
2753 return this.indicator
;
2757 * Get the indicator title.
2759 * The title is displayed when a user moves the mouse over the indicator.
2761 * @return {string} Indicator title text
2763 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicatorTitle = function () {
2764 return this.indicatorTitle
;
2768 * LabelElement is often mixed into other classes to generate a label, which
2769 * helps identify the function of an interface element.
2770 * See the [OOjs UI documentation on MediaWiki] [1] for more information.
2772 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2778 * @param {Object} [config] Configuration options
2779 * @cfg {jQuery} [$label] The label element created by the class. If this
2780 * configuration is omitted, the label element will use a generated `<span>`.
2781 * @cfg {jQuery|string|Function|OO.ui.HtmlSnippet} [label] The label text. The label can be specified
2782 * as a plaintext string, a jQuery selection of elements, or a function that will produce a string
2783 * in the future. See the [OOjs UI documentation on MediaWiki] [2] for examples.
2784 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2786 OO
.ui
.mixin
.LabelElement
= function OoUiMixinLabelElement( config
) {
2787 // Configuration initialization
2788 config
= config
|| {};
2795 this.setLabel( config
.label
|| this.constructor.static.label
);
2796 this.setLabelElement( config
.$label
|| $( '<span>' ) );
2801 OO
.initClass( OO
.ui
.mixin
.LabelElement
);
2806 * @event labelChange
2807 * @param {string} value
2810 /* Static Properties */
2813 * The label text. The label can be specified as a plaintext string, a function that will
2814 * produce a string in the future, or `null` for no label. The static value will
2815 * be overridden if a label is specified with the #label config option.
2819 * @property {string|Function|null}
2821 OO
.ui
.mixin
.LabelElement
.static.label
= null;
2823 /* Static methods */
2826 * Highlight the first occurrence of the query in the given text
2828 * @param {string} text Text
2829 * @param {string} query Query to find
2830 * @return {jQuery} Text with the first match of the query
2831 * sub-string wrapped in highlighted span
2833 OO
.ui
.mixin
.LabelElement
.static.highlightQuery = function ( text
, query
) {
2834 var $result
= $( '<span>' ),
2835 offset
= text
.toLowerCase().indexOf( query
.toLowerCase() );
2837 if ( !query
.length
|| offset
=== -1 ) {
2838 return $result
.text( text
);
2841 document
.createTextNode( text
.slice( 0, offset
) ),
2843 .addClass( 'oo-ui-labelElement-label-highlight' )
2844 .text( text
.slice( offset
, offset
+ query
.length
) ),
2845 document
.createTextNode( text
.slice( offset
+ query
.length
) )
2847 return $result
.contents();
2853 * Set the label element.
2855 * If an element is already set, it will be cleaned up before setting up the new element.
2857 * @param {jQuery} $label Element to use as label
2859 OO
.ui
.mixin
.LabelElement
.prototype.setLabelElement = function ( $label
) {
2860 if ( this.$label
) {
2861 this.$label
.removeClass( 'oo-ui-labelElement-label' ).empty();
2864 this.$label
= $label
.addClass( 'oo-ui-labelElement-label' );
2865 this.setLabelContent( this.label
);
2871 * An empty string will result in the label being hidden. A string containing only whitespace will
2872 * be converted to a single ` `.
2874 * @param {jQuery|string|OO.ui.HtmlSnippet|Function|null} label Label nodes; text; a function that returns nodes or
2875 * text; or null for no label
2878 OO
.ui
.mixin
.LabelElement
.prototype.setLabel = function ( label
) {
2879 label
= typeof label
=== 'function' ? OO
.ui
.resolveMsg( label
) : label
;
2880 label
= ( ( typeof label
=== 'string' || label
instanceof jQuery
) && label
.length
) || ( label
instanceof OO
.ui
.HtmlSnippet
&& label
.toString().length
) ? label
: null;
2882 if ( this.label
!== label
) {
2883 if ( this.$label
) {
2884 this.setLabelContent( label
);
2887 this.emit( 'labelChange' );
2890 this.$element
.toggleClass( 'oo-ui-labelElement', !!this.label
);
2896 * Set the label as plain text with a highlighted query
2898 * @param {string} text Text label to set
2899 * @param {string} query Substring of text to highlight
2902 OO
.ui
.mixin
.LabelElement
.prototype.setHighlightedQuery = function ( text
, query
) {
2903 return this.setLabel( this.constructor.static.highlightQuery( text
, query
) );
2909 * @return {jQuery|string|Function|null} Label nodes; text; a function that returns nodes or
2910 * text; or null for no label
2912 OO
.ui
.mixin
.LabelElement
.prototype.getLabel = function () {
2917 * Set the content of the label.
2919 * Do not call this method until after the label element has been set by #setLabelElement.
2922 * @param {jQuery|string|Function|null} label Label nodes; text; a function that returns nodes or
2923 * text; or null for no label
2925 OO
.ui
.mixin
.LabelElement
.prototype.setLabelContent = function ( label
) {
2926 if ( typeof label
=== 'string' ) {
2927 if ( label
.match( /^\s*$/ ) ) {
2928 // Convert whitespace only string to a single non-breaking space
2929 this.$label
.html( ' ' );
2931 this.$label
.text( label
);
2933 } else if ( label
instanceof OO
.ui
.HtmlSnippet
) {
2934 this.$label
.html( label
.toString() );
2935 } else if ( label
instanceof jQuery
) {
2936 this.$label
.empty().append( label
);
2938 this.$label
.empty();
2943 * The FlaggedElement class is an attribute mixin, meaning that it is used to add
2944 * additional functionality to an element created by another class. The class provides
2945 * a ‘flags’ property assigned the name (or an array of names) of styling flags,
2946 * which are used to customize the look and feel of a widget to better describe its
2947 * importance and functionality.
2949 * The library currently contains the following styling flags for general use:
2951 * - **progressive**: Progressive styling is applied to convey that the widget will move the user forward in a process.
2952 * - **destructive**: Destructive styling is applied to convey that the widget will remove something.
2953 * - **constructive**: Constructive styling is applied to convey that the widget will create something.
2955 * The flags affect the appearance of the buttons:
2958 * // FlaggedElement is mixed into ButtonWidget to provide styling flags
2959 * var button1 = new OO.ui.ButtonWidget( {
2960 * label: 'Constructive',
2961 * flags: 'constructive'
2963 * var button2 = new OO.ui.ButtonWidget( {
2964 * label: 'Destructive',
2965 * flags: 'destructive'
2967 * var button3 = new OO.ui.ButtonWidget( {
2968 * label: 'Progressive',
2969 * flags: 'progressive'
2971 * $( 'body' ).append( button1.$element, button2.$element, button3.$element );
2973 * {@link OO.ui.ActionWidget ActionWidgets}, which are a special kind of button that execute an action, use these flags: **primary** and **safe**.
2974 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
2976 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
2982 * @param {Object} [config] Configuration options
2983 * @cfg {string|string[]} [flags] The name or names of the flags (e.g., 'constructive' or 'primary') to apply.
2984 * Please see the [OOjs UI documentation on MediaWiki] [2] for more information about available flags.
2985 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
2986 * @cfg {jQuery} [$flagged] The flagged element. By default,
2987 * the flagged functionality is applied to the element created by the class ($element).
2988 * If a different element is specified, the flagged functionality will be applied to it instead.
2990 OO
.ui
.mixin
.FlaggedElement
= function OoUiMixinFlaggedElement( config
) {
2991 // Configuration initialization
2992 config
= config
|| {};
2996 this.$flagged
= null;
2999 this.setFlags( config
.flags
);
3000 this.setFlaggedElement( config
.$flagged
|| this.$element
);
3007 * A flag event is emitted when the #clearFlags or #setFlags methods are used. The `changes`
3008 * parameter contains the name of each modified flag and indicates whether it was
3011 * @param {Object.<string,boolean>} changes Object keyed by flag name. A Boolean `true` indicates
3012 * that the flag was added, `false` that the flag was removed.
3018 * Set the flagged element.
3020 * This method is used to retarget a flagged mixin so that its functionality applies to the specified element.
3021 * If an element is already set, the method will remove the mixin’s effect on that element.
3023 * @param {jQuery} $flagged Element that should be flagged
3025 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlaggedElement = function ( $flagged
) {
3026 var classNames
= Object
.keys( this.flags
).map( function ( flag
) {
3027 return 'oo-ui-flaggedElement-' + flag
;
3030 if ( this.$flagged
) {
3031 this.$flagged
.removeClass( classNames
);
3034 this.$flagged
= $flagged
.addClass( classNames
);
3038 * Check if the specified flag is set.
3040 * @param {string} flag Name of flag
3041 * @return {boolean} The flag is set
3043 OO
.ui
.mixin
.FlaggedElement
.prototype.hasFlag = function ( flag
) {
3044 // This may be called before the constructor, thus before this.flags is set
3045 return this.flags
&& ( flag
in this.flags
);
3049 * Get the names of all flags set.
3051 * @return {string[]} Flag names
3053 OO
.ui
.mixin
.FlaggedElement
.prototype.getFlags = function () {
3054 // This may be called before the constructor, thus before this.flags is set
3055 return Object
.keys( this.flags
|| {} );
3064 OO
.ui
.mixin
.FlaggedElement
.prototype.clearFlags = function () {
3065 var flag
, className
,
3068 classPrefix
= 'oo-ui-flaggedElement-';
3070 for ( flag
in this.flags
) {
3071 className
= classPrefix
+ flag
;
3072 changes
[ flag
] = false;
3073 delete this.flags
[ flag
];
3074 remove
.push( className
);
3077 if ( this.$flagged
) {
3078 this.$flagged
.removeClass( remove
.join( ' ' ) );
3081 this.updateThemeClasses();
3082 this.emit( 'flag', changes
);
3088 * Add one or more flags.
3090 * @param {string|string[]|Object.<string, boolean>} flags A flag name, an array of flag names,
3091 * or an object keyed by flag name with a boolean value that indicates whether the flag should
3092 * be added (`true`) or removed (`false`).
3096 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlags = function ( flags
) {
3097 var i
, len
, flag
, className
,
3101 classPrefix
= 'oo-ui-flaggedElement-';
3103 if ( typeof flags
=== 'string' ) {
3104 className
= classPrefix
+ flags
;
3106 if ( !this.flags
[ flags
] ) {
3107 this.flags
[ flags
] = true;
3108 add
.push( className
);
3110 } else if ( Array
.isArray( flags
) ) {
3111 for ( i
= 0, len
= flags
.length
; i
< len
; i
++ ) {
3113 className
= classPrefix
+ flag
;
3115 if ( !this.flags
[ flag
] ) {
3116 changes
[ flag
] = true;
3117 this.flags
[ flag
] = true;
3118 add
.push( className
);
3121 } else if ( OO
.isPlainObject( flags
) ) {
3122 for ( flag
in flags
) {
3123 className
= classPrefix
+ flag
;
3124 if ( flags
[ flag
] ) {
3126 if ( !this.flags
[ flag
] ) {
3127 changes
[ flag
] = true;
3128 this.flags
[ flag
] = true;
3129 add
.push( className
);
3133 if ( this.flags
[ flag
] ) {
3134 changes
[ flag
] = false;
3135 delete this.flags
[ flag
];
3136 remove
.push( className
);
3142 if ( this.$flagged
) {
3144 .addClass( add
.join( ' ' ) )
3145 .removeClass( remove
.join( ' ' ) );
3148 this.updateThemeClasses();
3149 this.emit( 'flag', changes
);
3155 * TitledElement is mixed into other classes to provide a `title` attribute.
3156 * Titles are rendered by the browser and are made visible when the user moves
3157 * the mouse over the element. Titles are not visible on touch devices.
3160 * // TitledElement provides a 'title' attribute to the
3161 * // ButtonWidget class
3162 * var button = new OO.ui.ButtonWidget( {
3163 * label: 'Button with Title',
3164 * title: 'I am a button'
3166 * $( 'body' ).append( button.$element );
3172 * @param {Object} [config] Configuration options
3173 * @cfg {jQuery} [$titled] The element to which the `title` attribute is applied.
3174 * If this config is omitted, the title functionality is applied to $element, the
3175 * element created by the class.
3176 * @cfg {string|Function} [title] The title text or a function that returns text. If
3177 * this config is omitted, the value of the {@link #static-title static title} property is used.
3179 OO
.ui
.mixin
.TitledElement
= function OoUiMixinTitledElement( config
) {
3180 // Configuration initialization
3181 config
= config
|| {};
3184 this.$titled
= null;
3188 this.setTitle( config
.title
!== undefined ? config
.title
: this.constructor.static.title
);
3189 this.setTitledElement( config
.$titled
|| this.$element
);
3194 OO
.initClass( OO
.ui
.mixin
.TitledElement
);
3196 /* Static Properties */
3199 * The title text, a function that returns text, or `null` for no title. The value of the static property
3200 * is overridden if the #title config option is used.
3204 * @property {string|Function|null}
3206 OO
.ui
.mixin
.TitledElement
.static.title
= null;
3211 * Set the titled element.
3213 * This method is used to retarget a titledElement mixin so that its functionality applies to the specified element.
3214 * If an element is already set, the mixin’s effect on that element is removed before the new element is set up.
3216 * @param {jQuery} $titled Element that should use the 'titled' functionality
3218 OO
.ui
.mixin
.TitledElement
.prototype.setTitledElement = function ( $titled
) {
3219 if ( this.$titled
) {
3220 this.$titled
.removeAttr( 'title' );
3223 this.$titled
= $titled
;
3225 this.$titled
.attr( 'title', this.title
);
3232 * @param {string|Function|null} title Title text, a function that returns text, or `null` for no title
3235 OO
.ui
.mixin
.TitledElement
.prototype.setTitle = function ( title
) {
3236 title
= typeof title
=== 'function' ? OO
.ui
.resolveMsg( title
) : title
;
3237 title
= ( typeof title
=== 'string' && title
.length
) ? title
: null;
3239 if ( this.title
!== title
) {
3240 if ( this.$titled
) {
3241 if ( title
!== null ) {
3242 this.$titled
.attr( 'title', title
);
3244 this.$titled
.removeAttr( 'title' );
3256 * @return {string} Title string
3258 OO
.ui
.mixin
.TitledElement
.prototype.getTitle = function () {
3263 * AccessKeyedElement is mixed into other classes to provide an `accesskey` attribute.
3264 * Accesskeys allow an user to go to a specific element by using
3265 * a shortcut combination of a browser specific keys + the key
3269 * // AccessKeyedElement provides an 'accesskey' attribute to the
3270 * // ButtonWidget class
3271 * var button = new OO.ui.ButtonWidget( {
3272 * label: 'Button with Accesskey',
3275 * $( 'body' ).append( button.$element );
3281 * @param {Object} [config] Configuration options
3282 * @cfg {jQuery} [$accessKeyed] The element to which the `accesskey` attribute is applied.
3283 * If this config is omitted, the accesskey functionality is applied to $element, the
3284 * element created by the class.
3285 * @cfg {string|Function} [accessKey] The key or a function that returns the key. If
3286 * this config is omitted, no accesskey will be added.
3288 OO
.ui
.mixin
.AccessKeyedElement
= function OoUiMixinAccessKeyedElement( config
) {
3289 // Configuration initialization
3290 config
= config
|| {};
3293 this.$accessKeyed
= null;
3294 this.accessKey
= null;
3297 this.setAccessKey( config
.accessKey
|| null );
3298 this.setAccessKeyedElement( config
.$accessKeyed
|| this.$element
);
3303 OO
.initClass( OO
.ui
.mixin
.AccessKeyedElement
);
3305 /* Static Properties */
3308 * The access key, a function that returns a key, or `null` for no accesskey.
3312 * @property {string|Function|null}
3314 OO
.ui
.mixin
.AccessKeyedElement
.static.accessKey
= null;
3319 * Set the accesskeyed element.
3321 * This method is used to retarget a AccessKeyedElement mixin so that its functionality applies to the specified element.
3322 * If an element is already set, the mixin's effect on that element is removed before the new element is set up.
3324 * @param {jQuery} $accessKeyed Element that should use the 'accesskeyes' functionality
3326 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKeyedElement = function ( $accessKeyed
) {
3327 if ( this.$accessKeyed
) {
3328 this.$accessKeyed
.removeAttr( 'accesskey' );
3331 this.$accessKeyed
= $accessKeyed
;
3332 if ( this.accessKey
) {
3333 this.$accessKeyed
.attr( 'accesskey', this.accessKey
);
3340 * @param {string|Function|null} accessKey Key, a function that returns a key, or `null` for no accesskey
3343 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKey = function ( accessKey
) {
3344 accessKey
= typeof accessKey
=== 'string' ? OO
.ui
.resolveMsg( accessKey
) : null;
3346 if ( this.accessKey
!== accessKey
) {
3347 if ( this.$accessKeyed
) {
3348 if ( accessKey
!== null ) {
3349 this.$accessKeyed
.attr( 'accesskey', accessKey
);
3351 this.$accessKeyed
.removeAttr( 'accesskey' );
3354 this.accessKey
= accessKey
;
3363 * @return {string} accessKey string
3365 OO
.ui
.mixin
.AccessKeyedElement
.prototype.getAccessKey = function () {
3366 return this.accessKey
;
3370 * ButtonWidget is a generic widget for buttons. A wide variety of looks,
3371 * feels, and functionality can be customized via the class’s configuration options
3372 * and methods. Please see the [OOjs UI documentation on MediaWiki] [1] for more information
3375 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches
3378 * // A button widget
3379 * var button = new OO.ui.ButtonWidget( {
3380 * label: 'Button with Icon',
3382 * iconTitle: 'Remove'
3384 * $( 'body' ).append( button.$element );
3386 * NOTE: HTML form buttons should use the OO.ui.ButtonInputWidget class.
3389 * @extends OO.ui.Widget
3390 * @mixins OO.ui.mixin.ButtonElement
3391 * @mixins OO.ui.mixin.IconElement
3392 * @mixins OO.ui.mixin.IndicatorElement
3393 * @mixins OO.ui.mixin.LabelElement
3394 * @mixins OO.ui.mixin.TitledElement
3395 * @mixins OO.ui.mixin.FlaggedElement
3396 * @mixins OO.ui.mixin.TabIndexedElement
3397 * @mixins OO.ui.mixin.AccessKeyedElement
3400 * @param {Object} [config] Configuration options
3401 * @cfg {boolean} [active=false] Whether button should be shown as active
3402 * @cfg {string} [href] Hyperlink to visit when the button is clicked.
3403 * @cfg {string} [target] The frame or window in which to open the hyperlink.
3404 * @cfg {boolean} [noFollow] Search engine traversal hint (default: true)
3406 OO
.ui
.ButtonWidget
= function OoUiButtonWidget( config
) {
3407 // Configuration initialization
3408 config
= config
|| {};
3410 // Parent constructor
3411 OO
.ui
.ButtonWidget
.parent
.call( this, config
);
3413 // Mixin constructors
3414 OO
.ui
.mixin
.ButtonElement
.call( this, config
);
3415 OO
.ui
.mixin
.IconElement
.call( this, config
);
3416 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
3417 OO
.ui
.mixin
.LabelElement
.call( this, config
);
3418 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$button
} ) );
3419 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
3420 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$button
} ) );
3421 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$button
} ) );
3426 this.noFollow
= false;
3429 this.connect( this, { disable
: 'onDisable' } );
3432 this.$button
.append( this.$icon
, this.$label
, this.$indicator
);
3434 .addClass( 'oo-ui-buttonWidget' )
3435 .append( this.$button
);
3436 this.setActive( config
.active
);
3437 this.setHref( config
.href
);
3438 this.setTarget( config
.target
);
3439 this.setNoFollow( config
.noFollow
);
3444 OO
.inheritClass( OO
.ui
.ButtonWidget
, OO
.ui
.Widget
);
3445 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.ButtonElement
);
3446 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IconElement
);
3447 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IndicatorElement
);
3448 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.LabelElement
);
3449 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TitledElement
);
3450 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.FlaggedElement
);
3451 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TabIndexedElement
);
3452 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
3454 /* Static Properties */
3460 OO
.ui
.ButtonWidget
.static.cancelButtonMouseDownEvents
= false;
3466 OO
.ui
.ButtonWidget
.static.tagName
= 'span';
3471 * Get hyperlink location.
3473 * @return {string} Hyperlink location
3475 OO
.ui
.ButtonWidget
.prototype.getHref = function () {
3480 * Get hyperlink target.
3482 * @return {string} Hyperlink target
3484 OO
.ui
.ButtonWidget
.prototype.getTarget = function () {
3489 * Get search engine traversal hint.
3491 * @return {boolean} Whether search engines should avoid traversing this hyperlink
3493 OO
.ui
.ButtonWidget
.prototype.getNoFollow = function () {
3494 return this.noFollow
;
3498 * Set hyperlink location.
3500 * @param {string|null} href Hyperlink location, null to remove
3502 OO
.ui
.ButtonWidget
.prototype.setHref = function ( href
) {
3503 href
= typeof href
=== 'string' ? href
: null;
3504 if ( href
!== null && !OO
.ui
.isSafeUrl( href
) ) {
3508 if ( href
!== this.href
) {
3517 * Update the `href` attribute, in case of changes to href or
3523 OO
.ui
.ButtonWidget
.prototype.updateHref = function () {
3524 if ( this.href
!== null && !this.isDisabled() ) {
3525 this.$button
.attr( 'href', this.href
);
3527 this.$button
.removeAttr( 'href' );
3534 * Handle disable events.
3537 * @param {boolean} disabled Element is disabled
3539 OO
.ui
.ButtonWidget
.prototype.onDisable = function () {
3544 * Set hyperlink target.
3546 * @param {string|null} target Hyperlink target, null to remove
3548 OO
.ui
.ButtonWidget
.prototype.setTarget = function ( target
) {
3549 target
= typeof target
=== 'string' ? target
: null;
3551 if ( target
!== this.target
) {
3552 this.target
= target
;
3553 if ( target
!== null ) {
3554 this.$button
.attr( 'target', target
);
3556 this.$button
.removeAttr( 'target' );
3564 * Set search engine traversal hint.
3566 * @param {boolean} noFollow True if search engines should avoid traversing this hyperlink
3568 OO
.ui
.ButtonWidget
.prototype.setNoFollow = function ( noFollow
) {
3569 noFollow
= typeof noFollow
=== 'boolean' ? noFollow
: true;
3571 if ( noFollow
!== this.noFollow
) {
3572 this.noFollow
= noFollow
;
3574 this.$button
.attr( 'rel', 'nofollow' );
3576 this.$button
.removeAttr( 'rel' );
3583 // Override method visibility hints from ButtonElement
3594 * A ButtonGroupWidget groups related buttons and is used together with OO.ui.ButtonWidget and
3595 * its subclasses. Each button in a group is addressed by a unique reference. Buttons can be added,
3596 * removed, and cleared from the group.
3599 * // Example: A ButtonGroupWidget with two buttons
3600 * var button1 = new OO.ui.PopupButtonWidget( {
3601 * label: 'Select a category',
3604 * $content: $( '<p>List of categories...</p>' ),
3609 * var button2 = new OO.ui.ButtonWidget( {
3612 * var buttonGroup = new OO.ui.ButtonGroupWidget( {
3613 * items: [button1, button2]
3615 * $( 'body' ).append( buttonGroup.$element );
3618 * @extends OO.ui.Widget
3619 * @mixins OO.ui.mixin.GroupElement
3622 * @param {Object} [config] Configuration options
3623 * @cfg {OO.ui.ButtonWidget[]} [items] Buttons to add
3625 OO
.ui
.ButtonGroupWidget
= function OoUiButtonGroupWidget( config
) {
3626 // Configuration initialization
3627 config
= config
|| {};
3629 // Parent constructor
3630 OO
.ui
.ButtonGroupWidget
.parent
.call( this, config
);
3632 // Mixin constructors
3633 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
3636 this.$element
.addClass( 'oo-ui-buttonGroupWidget' );
3637 if ( Array
.isArray( config
.items
) ) {
3638 this.addItems( config
.items
);
3644 OO
.inheritClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.Widget
);
3645 OO
.mixinClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.mixin
.GroupElement
);
3647 /* Static Properties */
3653 OO
.ui
.ButtonGroupWidget
.static.tagName
= 'span';
3656 * IconWidget is a generic widget for {@link OO.ui.mixin.IconElement icons}. In general, IconWidgets should be used with OO.ui.LabelWidget,
3657 * which creates a label that identifies the icon’s function. See the [OOjs UI documentation on MediaWiki] [1]
3658 * for a list of icons included in the library.
3661 * // An icon widget with a label
3662 * var myIcon = new OO.ui.IconWidget( {
3666 * // Create a label.
3667 * var iconLabel = new OO.ui.LabelWidget( {
3670 * $( 'body' ).append( myIcon.$element, iconLabel.$element );
3672 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
3675 * @extends OO.ui.Widget
3676 * @mixins OO.ui.mixin.IconElement
3677 * @mixins OO.ui.mixin.TitledElement
3678 * @mixins OO.ui.mixin.FlaggedElement
3681 * @param {Object} [config] Configuration options
3683 OO
.ui
.IconWidget
= function OoUiIconWidget( config
) {
3684 // Configuration initialization
3685 config
= config
|| {};
3687 // Parent constructor
3688 OO
.ui
.IconWidget
.parent
.call( this, config
);
3690 // Mixin constructors
3691 OO
.ui
.mixin
.IconElement
.call( this, $.extend( {}, config
, { $icon
: this.$element
} ) );
3692 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3693 OO
.ui
.mixin
.FlaggedElement
.call( this, $.extend( {}, config
, { $flagged
: this.$element
} ) );
3696 this.$element
.addClass( 'oo-ui-iconWidget' );
3701 OO
.inheritClass( OO
.ui
.IconWidget
, OO
.ui
.Widget
);
3702 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.IconElement
);
3703 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.TitledElement
);
3704 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.FlaggedElement
);
3706 /* Static Properties */
3712 OO
.ui
.IconWidget
.static.tagName
= 'span';
3715 * IndicatorWidgets create indicators, which are small graphics that are generally used to draw
3716 * attention to the status of an item or to clarify the function of a control. For a list of
3717 * indicators included in the library, please see the [OOjs UI documentation on MediaWiki][1].
3720 * // Example of an indicator widget
3721 * var indicator1 = new OO.ui.IndicatorWidget( {
3722 * indicator: 'alert'
3725 * // Create a fieldset layout to add a label
3726 * var fieldset = new OO.ui.FieldsetLayout();
3727 * fieldset.addItems( [
3728 * new OO.ui.FieldLayout( indicator1, { label: 'An alert indicator:' } )
3730 * $( 'body' ).append( fieldset.$element );
3732 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
3735 * @extends OO.ui.Widget
3736 * @mixins OO.ui.mixin.IndicatorElement
3737 * @mixins OO.ui.mixin.TitledElement
3740 * @param {Object} [config] Configuration options
3742 OO
.ui
.IndicatorWidget
= function OoUiIndicatorWidget( config
) {
3743 // Configuration initialization
3744 config
= config
|| {};
3746 // Parent constructor
3747 OO
.ui
.IndicatorWidget
.parent
.call( this, config
);
3749 // Mixin constructors
3750 OO
.ui
.mixin
.IndicatorElement
.call( this, $.extend( {}, config
, { $indicator
: this.$element
} ) );
3751 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3754 this.$element
.addClass( 'oo-ui-indicatorWidget' );
3759 OO
.inheritClass( OO
.ui
.IndicatorWidget
, OO
.ui
.Widget
);
3760 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.IndicatorElement
);
3761 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.TitledElement
);
3763 /* Static Properties */
3769 OO
.ui
.IndicatorWidget
.static.tagName
= 'span';
3772 * LabelWidgets help identify the function of interface elements. Each LabelWidget can
3773 * be configured with a `label` option that is set to a string, a label node, or a function:
3775 * - String: a plaintext string
3776 * - jQuery selection: a jQuery selection, used for anything other than a plaintext label, e.g., a
3777 * label that includes a link or special styling, such as a gray color or additional graphical elements.
3778 * - Function: a function that will produce a string in the future. Functions are used
3779 * in cases where the value of the label is not currently defined.
3781 * In addition, the LabelWidget can be associated with an {@link OO.ui.InputWidget input widget}, which
3782 * will come into focus when the label is clicked.
3785 * // Examples of LabelWidgets
3786 * var label1 = new OO.ui.LabelWidget( {
3787 * label: 'plaintext label'
3789 * var label2 = new OO.ui.LabelWidget( {
3790 * label: $( '<a href="default.html">jQuery label</a>' )
3792 * // Create a fieldset layout with fields for each example
3793 * var fieldset = new OO.ui.FieldsetLayout();
3794 * fieldset.addItems( [
3795 * new OO.ui.FieldLayout( label1 ),
3796 * new OO.ui.FieldLayout( label2 )
3798 * $( 'body' ).append( fieldset.$element );
3801 * @extends OO.ui.Widget
3802 * @mixins OO.ui.mixin.LabelElement
3803 * @mixins OO.ui.mixin.TitledElement
3806 * @param {Object} [config] Configuration options
3807 * @cfg {OO.ui.InputWidget} [input] {@link OO.ui.InputWidget Input widget} that uses the label.
3808 * Clicking the label will focus the specified input field.
3810 OO
.ui
.LabelWidget
= function OoUiLabelWidget( config
) {
3811 // Configuration initialization
3812 config
= config
|| {};
3814 // Parent constructor
3815 OO
.ui
.LabelWidget
.parent
.call( this, config
);
3817 // Mixin constructors
3818 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, { $label
: this.$element
} ) );
3819 OO
.ui
.mixin
.TitledElement
.call( this, config
);
3822 this.input
= config
.input
;
3825 if ( this.input
instanceof OO
.ui
.InputWidget
) {
3826 if ( this.input
.getInputId() ) {
3827 this.$element
.attr( 'for', this.input
.getInputId() );
3829 this.$label
.on( 'click', function () {
3830 this.fieldWidget
.focus();
3835 this.$element
.addClass( 'oo-ui-labelWidget' );
3840 OO
.inheritClass( OO
.ui
.LabelWidget
, OO
.ui
.Widget
);
3841 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.LabelElement
);
3842 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.TitledElement
);
3844 /* Static Properties */
3850 OO
.ui
.LabelWidget
.static.tagName
= 'label';
3853 * PendingElement is a mixin that is used to create elements that notify users that something is happening
3854 * and that they should wait before proceeding. The pending state is visually represented with a pending
3855 * texture that appears in the head of a pending {@link OO.ui.ProcessDialog process dialog} or in the input
3856 * field of a {@link OO.ui.TextInputWidget text input widget}.
3858 * Currently, {@link OO.ui.ActionWidget Action widgets}, which mix in this class, can also be marked as pending, but only when
3859 * used in {@link OO.ui.MessageDialog message dialogs}. The behavior is not currently supported for action widgets used
3860 * in process dialogs.
3863 * function MessageDialog( config ) {
3864 * MessageDialog.parent.call( this, config );
3866 * OO.inheritClass( MessageDialog, OO.ui.MessageDialog );
3868 * MessageDialog.static.name = 'myMessageDialog';
3869 * MessageDialog.static.actions = [
3870 * { action: 'save', label: 'Done', flags: 'primary' },
3871 * { label: 'Cancel', flags: 'safe' }
3874 * MessageDialog.prototype.initialize = function () {
3875 * MessageDialog.parent.prototype.initialize.apply( this, arguments );
3876 * this.content = new OO.ui.PanelLayout( { $: this.$, padded: true } );
3877 * 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>' );
3878 * this.$body.append( this.content.$element );
3880 * MessageDialog.prototype.getBodyHeight = function () {
3883 * MessageDialog.prototype.getActionProcess = function ( action ) {
3884 * var dialog = this;
3885 * if ( action === 'save' ) {
3886 * dialog.getActions().get({actions: 'save'})[0].pushPending();
3887 * return new OO.ui.Process()
3889 * .next( function () {
3890 * dialog.getActions().get({actions: 'save'})[0].popPending();
3893 * return MessageDialog.parent.prototype.getActionProcess.call( this, action );
3896 * var windowManager = new OO.ui.WindowManager();
3897 * $( 'body' ).append( windowManager.$element );
3899 * var dialog = new MessageDialog();
3900 * windowManager.addWindows( [ dialog ] );
3901 * windowManager.openWindow( dialog );
3907 * @param {Object} [config] Configuration options
3908 * @cfg {jQuery} [$pending] Element to mark as pending, defaults to this.$element
3910 OO
.ui
.mixin
.PendingElement
= function OoUiMixinPendingElement( config
) {
3911 // Configuration initialization
3912 config
= config
|| {};
3916 this.$pending
= null;
3919 this.setPendingElement( config
.$pending
|| this.$element
);
3924 OO
.initClass( OO
.ui
.mixin
.PendingElement
);
3929 * Set the pending element (and clean up any existing one).
3931 * @param {jQuery} $pending The element to set to pending.
3933 OO
.ui
.mixin
.PendingElement
.prototype.setPendingElement = function ( $pending
) {
3934 if ( this.$pending
) {
3935 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
3938 this.$pending
= $pending
;
3939 if ( this.pending
> 0 ) {
3940 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
3945 * Check if an element is pending.
3947 * @return {boolean} Element is pending
3949 OO
.ui
.mixin
.PendingElement
.prototype.isPending = function () {
3950 return !!this.pending
;
3954 * Increase the pending counter. The pending state will remain active until the counter is zero
3955 * (i.e., the number of calls to #pushPending and #popPending is the same).
3959 OO
.ui
.mixin
.PendingElement
.prototype.pushPending = function () {
3960 if ( this.pending
=== 0 ) {
3961 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
3962 this.updateThemeClasses();
3970 * Decrease the pending counter. The pending state will remain active until the counter is zero
3971 * (i.e., the number of calls to #pushPending and #popPending is the same).
3975 OO
.ui
.mixin
.PendingElement
.prototype.popPending = function () {
3976 if ( this.pending
=== 1 ) {
3977 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
3978 this.updateThemeClasses();
3980 this.pending
= Math
.max( 0, this.pending
- 1 );
3986 * Element that will stick adjacent to a specified container, even when it is inserted elsewhere
3987 * in the document (for example, in an OO.ui.Window's $overlay).
3989 * The elements's position is automatically calculated and maintained when window is resized or the
3990 * page is scrolled. If you reposition the container manually, you have to call #position to make
3991 * sure the element is still placed correctly.
3993 * As positioning is only possible when both the element and the container are attached to the DOM
3994 * and visible, it's only done after you call #togglePositioning. You might want to do this inside
3995 * the #toggle method to display a floating popup, for example.
4001 * @param {Object} [config] Configuration options
4002 * @cfg {jQuery} [$floatable] Node to position, assigned to #$floatable, omit to use #$element
4003 * @cfg {jQuery} [$floatableContainer] Node to position adjacent to
4004 * @cfg {string} [verticalPosition='below'] Where to position $floatable vertically:
4005 * 'below': Directly below $floatableContainer, aligning f's top edge with fC's bottom edge
4006 * 'above': Directly above $floatableContainer, aligning f's bottom edge with fC's top edge
4007 * 'top': Align the top edge with $floatableContainer's top edge
4008 * 'bottom': Align the bottom edge with $floatableContainer's bottom edge
4009 * 'center': Vertically align the center with $floatableContainer's center
4010 * @cfg {string} [horizontalPosition='start'] Where to position $floatable horizontally:
4011 * 'before': Directly before $floatableContainer, aligning f's end edge with fC's start edge
4012 * 'after': Directly after $floatableContainer, algining f's start edge with fC's end edge
4013 * 'start': Align the start (left in LTR, right in RTL) edge with $floatableContainer's start edge
4014 * 'end': Align the end (right in LTR, left in RTL) edge with $floatableContainer's end edge
4015 * 'center': Horizontally align the center with $floatableContainer's center
4016 * @cfg {boolean} [hideWhenOutOfView=true] Whether to hide the floatable element if the container
4019 OO
.ui
.mixin
.FloatableElement
= function OoUiMixinFloatableElement( config
) {
4020 // Configuration initialization
4021 config
= config
|| {};
4024 this.$floatable
= null;
4025 this.$floatableContainer
= null;
4026 this.$floatableWindow
= null;
4027 this.$floatableClosestScrollable
= null;
4028 this.onFloatableScrollHandler
= this.position
.bind( this );
4029 this.onFloatableWindowResizeHandler
= this.position
.bind( this );
4032 this.setFloatableContainer( config
.$floatableContainer
);
4033 this.setFloatableElement( config
.$floatable
|| this.$element
);
4034 this.setVerticalPosition( config
.verticalPosition
|| 'below' );
4035 this.setHorizontalPosition( config
.horizontalPosition
|| 'start' );
4036 this.hideWhenOutOfView
= config
.hideWhenOutOfView
=== undefined ? true : !!config
.hideWhenOutOfView
;
4042 * Set floatable element.
4044 * If an element is already set, it will be cleaned up before setting up the new element.
4046 * @param {jQuery} $floatable Element to make floatable
4048 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableElement = function ( $floatable
) {
4049 if ( this.$floatable
) {
4050 this.$floatable
.removeClass( 'oo-ui-floatableElement-floatable' );
4051 this.$floatable
.css( { left
: '', top
: '' } );
4054 this.$floatable
= $floatable
.addClass( 'oo-ui-floatableElement-floatable' );
4059 * Set floatable container.
4061 * The element will be positioned relative to the specified container.
4063 * @param {jQuery|null} $floatableContainer Container to keep visible, or null to unset
4065 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableContainer = function ( $floatableContainer
) {
4066 this.$floatableContainer
= $floatableContainer
;
4067 if ( this.$floatable
) {
4073 * Change how the element is positioned vertically.
4075 * @param {string} position 'below', 'above', 'top', 'bottom' or 'center'
4077 OO
.ui
.mixin
.FloatableElement
.prototype.setVerticalPosition = function ( position
) {
4078 if ( [ 'below', 'above', 'top', 'bottom', 'center' ].indexOf( position
) === -1 ) {
4079 throw new Error( 'Invalid value for vertical position: ' + position
);
4081 if ( this.verticalPosition
!== position
) {
4082 this.verticalPosition
= position
;
4083 if ( this.$floatable
) {
4090 * Change how the element is positioned horizontally.
4092 * @param {string} position 'before', 'after', 'start', 'end' or 'center'
4094 OO
.ui
.mixin
.FloatableElement
.prototype.setHorizontalPosition = function ( position
) {
4095 if ( [ 'before', 'after', 'start', 'end', 'center' ].indexOf( position
) === -1 ) {
4096 throw new Error( 'Invalid value for horizontal position: ' + position
);
4098 if ( this.horizontalPosition
!== position
) {
4099 this.horizontalPosition
= position
;
4100 if ( this.$floatable
) {
4107 * Toggle positioning.
4109 * Do not turn positioning on until after the element is attached to the DOM and visible.
4111 * @param {boolean} [positioning] Enable positioning, omit to toggle
4114 OO
.ui
.mixin
.FloatableElement
.prototype.togglePositioning = function ( positioning
) {
4115 var closestScrollableOfContainer
;
4117 if ( !this.$floatable
|| !this.$floatableContainer
) {
4121 positioning
= positioning
=== undefined ? !this.positioning
: !!positioning
;
4123 if ( positioning
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
4124 OO
.ui
.warnDeprecation( 'FloatableElement#togglePositioning: Before calling this method, the element must be attached to the DOM.' );
4125 this.warnedUnattached
= true;
4128 if ( this.positioning
!== positioning
) {
4129 this.positioning
= positioning
;
4131 this.needsCustomPosition
=
4132 this.verticalPostion
!== 'below' ||
4133 this.horizontalPosition
!== 'start' ||
4134 !OO
.ui
.contains( this.$floatableContainer
[ 0 ], this.$floatable
[ 0 ] );
4136 closestScrollableOfContainer
= OO
.ui
.Element
.static.getClosestScrollableContainer( this.$floatableContainer
[ 0 ] );
4137 // If the scrollable is the root, we have to listen to scroll events
4138 // on the window because of browser inconsistencies.
4139 if ( $( closestScrollableOfContainer
).is( 'html, body' ) ) {
4140 closestScrollableOfContainer
= OO
.ui
.Element
.static.getWindow( closestScrollableOfContainer
);
4143 if ( positioning
) {
4144 this.$floatableWindow
= $( this.getElementWindow() );
4145 this.$floatableWindow
.on( 'resize', this.onFloatableWindowResizeHandler
);
4147 this.$floatableClosestScrollable
= $( closestScrollableOfContainer
);
4148 this.$floatableClosestScrollable
.on( 'scroll', this.onFloatableScrollHandler
);
4150 // Initial position after visible
4153 if ( this.$floatableWindow
) {
4154 this.$floatableWindow
.off( 'resize', this.onFloatableWindowResizeHandler
);
4155 this.$floatableWindow
= null;
4158 if ( this.$floatableClosestScrollable
) {
4159 this.$floatableClosestScrollable
.off( 'scroll', this.onFloatableScrollHandler
);
4160 this.$floatableClosestScrollable
= null;
4163 this.$floatable
.css( { left
: '', right
: '', top
: '' } );
4171 * Check whether the bottom edge of the given element is within the viewport of the given container.
4174 * @param {jQuery} $element
4175 * @param {jQuery} $container
4178 OO
.ui
.mixin
.FloatableElement
.prototype.isElementInViewport = function ( $element
, $container
) {
4179 var elemRect
, contRect
, topEdgeInBounds
, bottomEdgeInBounds
, leftEdgeInBounds
, rightEdgeInBounds
,
4180 startEdgeInBounds
, endEdgeInBounds
,
4181 direction
= $element
.css( 'direction' );
4183 elemRect
= $element
[ 0 ].getBoundingClientRect();
4184 if ( $container
[ 0 ] === window
) {
4188 right
: document
.documentElement
.clientWidth
,
4189 bottom
: document
.documentElement
.clientHeight
4192 contRect
= $container
[ 0 ].getBoundingClientRect();
4195 topEdgeInBounds
= elemRect
.top
>= contRect
.top
&& elemRect
.top
<= contRect
.bottom
;
4196 bottomEdgeInBounds
= elemRect
.bottom
>= contRect
.top
&& elemRect
.bottom
<= contRect
.bottom
;
4197 leftEdgeInBounds
= elemRect
.left
>= contRect
.left
&& elemRect
.left
<= contRect
.right
;
4198 rightEdgeInBounds
= elemRect
.right
>= contRect
.left
&& elemRect
.right
<= contRect
.right
;
4199 if ( direction
=== 'rtl' ) {
4200 startEdgeInBounds
= rightEdgeInBounds
;
4201 endEdgeInBounds
= leftEdgeInBounds
;
4203 startEdgeInBounds
= leftEdgeInBounds
;
4204 endEdgeInBounds
= rightEdgeInBounds
;
4207 if ( this.verticalPosition
=== 'below' && !bottomEdgeInBounds
) {
4210 if ( this.verticalPosition
=== 'above' && !topEdgeInBounds
) {
4213 if ( this.horizontalPosition
=== 'before' && !startEdgeInBounds
) {
4216 if ( this.horizontalPosition
=== 'after' && !endEdgeInBounds
) {
4220 // The other positioning values are all about being inside the container,
4221 // so in those cases all we care about is that any part of the container is visible.
4222 return elemRect
.top
<= contRect
.bottom
&& elemRect
.bottom
>= contRect
.top
&&
4223 elemRect
.left
<= contRect
.right
&& elemRect
.right
>= contRect
.left
;
4227 * Position the floatable below its container.
4229 * This should only be done when both of them are attached to the DOM and visible.
4233 OO
.ui
.mixin
.FloatableElement
.prototype.position = function () {
4234 if ( !this.positioning
) {
4239 // To continue, some things need to be true:
4240 // The element must actually be in the DOM
4241 this.isElementAttached() && (
4242 // The closest scrollable is the current window
4243 this.$floatableClosestScrollable
[ 0 ] === this.getElementWindow() ||
4244 // OR is an element in the element's DOM
4245 $.contains( this.getElementDocument(), this.$floatableClosestScrollable
[ 0 ] )
4248 // Abort early if important parts of the widget are no longer attached to the DOM
4252 if ( this.hideWhenOutOfView
&& !this.isElementInViewport( this.$floatableContainer
, this.$floatableClosestScrollable
) ) {
4253 this.$floatable
.addClass( 'oo-ui-element-hidden' );
4256 this.$floatable
.removeClass( 'oo-ui-element-hidden' );
4259 if ( !this.needsCustomPosition
) {
4263 this.$floatable
.css( this.computePosition() );
4265 // We updated the position, so re-evaluate the clipping state.
4266 // (ClippableElement does not listen to 'scroll' events on $floatableContainer's parent, and so
4267 // will not notice the need to update itself.)
4268 // TODO: This is terrible, we shouldn't need to know about ClippableElement at all here. Why does
4269 // it not listen to the right events in the right places?
4278 * Compute how #$floatable should be positioned based on the position of #$floatableContainer
4279 * and the positioning settings. This is a helper for #position that shouldn't be called directly,
4280 * but may be overridden by subclasses if they want to change or add to the positioning logic.
4282 * @return {Object} New position to apply with .css(). Keys are 'top', 'left', 'bottom' and 'right'.
4284 OO
.ui
.mixin
.FloatableElement
.prototype.computePosition = function () {
4285 var isBody
, scrollableX
, scrollableY
, containerPos
,
4286 horizScrollbarHeight
, vertScrollbarWidth
, scrollTop
, scrollLeft
,
4287 newPos
= { top
: '', left
: '', bottom
: '', right
: '' },
4288 direction
= this.$floatableContainer
.css( 'direction' ),
4289 $offsetParent
= this.$floatable
.offsetParent();
4291 if ( $offsetParent
.is( 'html' ) ) {
4292 // The innerHeight/Width and clientHeight/Width calculations don't work well on the
4293 // <html> element, but they do work on the <body>
4294 $offsetParent
= $( $offsetParent
[ 0 ].ownerDocument
.body
);
4296 isBody
= $offsetParent
.is( 'body' );
4297 scrollableX
= $offsetParent
.css( 'overflow-x' ) === 'scroll' || $offsetParent
.css( 'overflow-x' ) === 'auto';
4298 scrollableY
= $offsetParent
.css( 'overflow-y' ) === 'scroll' || $offsetParent
.css( 'overflow-y' ) === 'auto';
4300 vertScrollbarWidth
= $offsetParent
.innerWidth() - $offsetParent
.prop( 'clientWidth' );
4301 horizScrollbarHeight
= $offsetParent
.innerHeight() - $offsetParent
.prop( 'clientHeight' );
4302 // We don't need to compute and add scrollTop and scrollLeft if the scrollable container is the body,
4303 // or if it isn't scrollable
4304 scrollTop
= scrollableY
&& !isBody
? $offsetParent
.scrollTop() : 0;
4305 scrollLeft
= scrollableX
&& !isBody
? OO
.ui
.Element
.static.getScrollLeft( $offsetParent
[ 0 ] ) : 0;
4307 // Avoid passing the <body> to getRelativePosition(), because it won't return what we expect
4308 // if the <body> has a margin
4309 containerPos
= isBody
?
4310 this.$floatableContainer
.offset() :
4311 OO
.ui
.Element
.static.getRelativePosition( this.$floatableContainer
, $offsetParent
);
4312 containerPos
.bottom
= containerPos
.top
+ this.$floatableContainer
.outerHeight();
4313 containerPos
.right
= containerPos
.left
+ this.$floatableContainer
.outerWidth();
4314 containerPos
.start
= direction
=== 'rtl' ? containerPos
.right
: containerPos
.left
;
4315 containerPos
.end
= direction
=== 'rtl' ? containerPos
.left
: containerPos
.right
;
4317 if ( this.verticalPosition
=== 'below' ) {
4318 newPos
.top
= containerPos
.bottom
;
4319 } else if ( this.verticalPosition
=== 'above' ) {
4320 newPos
.bottom
= $offsetParent
.outerHeight() - containerPos
.top
;
4321 } else if ( this.verticalPosition
=== 'top' ) {
4322 newPos
.top
= containerPos
.top
;
4323 } else if ( this.verticalPosition
=== 'bottom' ) {
4324 newPos
.bottom
= $offsetParent
.outerHeight() - containerPos
.bottom
;
4325 } else if ( this.verticalPosition
=== 'center' ) {
4326 newPos
.top
= containerPos
.top
+
4327 ( this.$floatableContainer
.height() - this.$floatable
.height() ) / 2;
4330 if ( this.horizontalPosition
=== 'before' ) {
4331 newPos
.end
= containerPos
.start
;
4332 } else if ( this.horizontalPosition
=== 'after' ) {
4333 newPos
.start
= containerPos
.end
;
4334 } else if ( this.horizontalPosition
=== 'start' ) {
4335 newPos
.start
= containerPos
.start
;
4336 } else if ( this.horizontalPosition
=== 'end' ) {
4337 newPos
.end
= containerPos
.end
;
4338 } else if ( this.horizontalPosition
=== 'center' ) {
4339 newPos
.left
= containerPos
.left
+
4340 ( this.$floatableContainer
.width() - this.$floatable
.width() ) / 2;
4343 if ( newPos
.start
!== undefined ) {
4344 if ( direction
=== 'rtl' ) {
4345 newPos
.right
= ( isBody
? $( $offsetParent
[ 0 ].ownerDocument
.documentElement
) : $offsetParent
).outerWidth() - newPos
.start
;
4347 newPos
.left
= newPos
.start
;
4349 delete newPos
.start
;
4351 if ( newPos
.end
!== undefined ) {
4352 if ( direction
=== 'rtl' ) {
4353 newPos
.left
= newPos
.end
;
4355 newPos
.right
= ( isBody
? $( $offsetParent
[ 0 ].ownerDocument
.documentElement
) : $offsetParent
).outerWidth() - newPos
.end
;
4360 // Account for scroll position
4361 if ( newPos
.top
!== '' ) {
4362 newPos
.top
+= scrollTop
;
4364 if ( newPos
.bottom
!== '' ) {
4365 newPos
.bottom
-= scrollTop
;
4367 if ( newPos
.left
!== '' ) {
4368 newPos
.left
+= scrollLeft
;
4370 if ( newPos
.right
!== '' ) {
4371 newPos
.right
-= scrollLeft
;
4374 // Account for scrollbar gutter
4375 if ( newPos
.bottom
!== '' ) {
4376 newPos
.bottom
-= horizScrollbarHeight
;
4378 if ( direction
=== 'rtl' ) {
4379 if ( newPos
.left
!== '' ) {
4380 newPos
.left
-= vertScrollbarWidth
;
4383 if ( newPos
.right
!== '' ) {
4384 newPos
.right
-= vertScrollbarWidth
;
4392 * Element that can be automatically clipped to visible boundaries.
4394 * Whenever the element's natural height changes, you have to call
4395 * {@link OO.ui.mixin.ClippableElement#clip} to make sure it's still
4396 * clipping correctly.
4398 * The dimensions of #$clippableContainer will be compared to the boundaries of the
4399 * nearest scrollable container. If #$clippableContainer is too tall and/or too wide,
4400 * then #$clippable will be given a fixed reduced height and/or width and will be made
4401 * scrollable. By default, #$clippable and #$clippableContainer are the same element,
4402 * but you can build a static footer by setting #$clippableContainer to an element that contains
4403 * #$clippable and the footer.
4409 * @param {Object} [config] Configuration options
4410 * @cfg {jQuery} [$clippable] Node to clip, assigned to #$clippable, omit to use #$element
4411 * @cfg {jQuery} [$clippableContainer] Node to keep visible, assigned to #$clippableContainer,
4412 * omit to use #$clippable
4414 OO
.ui
.mixin
.ClippableElement
= function OoUiMixinClippableElement( config
) {
4415 // Configuration initialization
4416 config
= config
|| {};
4419 this.$clippable
= null;
4420 this.$clippableContainer
= null;
4421 this.clipping
= false;
4422 this.clippedHorizontally
= false;
4423 this.clippedVertically
= false;
4424 this.$clippableScrollableContainer
= null;
4425 this.$clippableScroller
= null;
4426 this.$clippableWindow
= null;
4427 this.idealWidth
= null;
4428 this.idealHeight
= null;
4429 this.onClippableScrollHandler
= this.clip
.bind( this );
4430 this.onClippableWindowResizeHandler
= this.clip
.bind( this );
4433 if ( config
.$clippableContainer
) {
4434 this.setClippableContainer( config
.$clippableContainer
);
4436 this.setClippableElement( config
.$clippable
|| this.$element
);
4442 * Set clippable element.
4444 * If an element is already set, it will be cleaned up before setting up the new element.
4446 * @param {jQuery} $clippable Element to make clippable
4448 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableElement = function ( $clippable
) {
4449 if ( this.$clippable
) {
4450 this.$clippable
.removeClass( 'oo-ui-clippableElement-clippable' );
4451 this.$clippable
.css( { width
: '', height
: '', overflowX
: '', overflowY
: '' } );
4452 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4455 this.$clippable
= $clippable
.addClass( 'oo-ui-clippableElement-clippable' );
4460 * Set clippable container.
4462 * This is the container that will be measured when deciding whether to clip. When clipping,
4463 * #$clippable will be resized in order to keep the clippable container fully visible.
4465 * If the clippable container is unset, #$clippable will be used.
4467 * @param {jQuery|null} $clippableContainer Container to keep visible, or null to unset
4469 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableContainer = function ( $clippableContainer
) {
4470 this.$clippableContainer
= $clippableContainer
;
4471 if ( this.$clippable
) {
4479 * Do not turn clipping on until after the element is attached to the DOM and visible.
4481 * @param {boolean} [clipping] Enable clipping, omit to toggle
4484 OO
.ui
.mixin
.ClippableElement
.prototype.toggleClipping = function ( clipping
) {
4485 clipping
= clipping
=== undefined ? !this.clipping
: !!clipping
;
4487 if ( clipping
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
4488 OO
.ui
.warnDeprecation( 'ClippableElement#toggleClipping: Before calling this method, the element must be attached to the DOM.' );
4489 this.warnedUnattached
= true;
4492 if ( this.clipping
!== clipping
) {
4493 this.clipping
= clipping
;
4495 this.$clippableScrollableContainer
= $( this.getClosestScrollableElementContainer() );
4496 // If the clippable container is the root, we have to listen to scroll events and check
4497 // jQuery.scrollTop on the window because of browser inconsistencies
4498 this.$clippableScroller
= this.$clippableScrollableContainer
.is( 'html, body' ) ?
4499 $( OO
.ui
.Element
.static.getWindow( this.$clippableScrollableContainer
) ) :
4500 this.$clippableScrollableContainer
;
4501 this.$clippableScroller
.on( 'scroll', this.onClippableScrollHandler
);
4502 this.$clippableWindow
= $( this.getElementWindow() )
4503 .on( 'resize', this.onClippableWindowResizeHandler
);
4504 // Initial clip after visible
4507 this.$clippable
.css( {
4515 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4517 this.$clippableScrollableContainer
= null;
4518 this.$clippableScroller
.off( 'scroll', this.onClippableScrollHandler
);
4519 this.$clippableScroller
= null;
4520 this.$clippableWindow
.off( 'resize', this.onClippableWindowResizeHandler
);
4521 this.$clippableWindow
= null;
4529 * Check if the element will be clipped to fit the visible area of the nearest scrollable container.
4531 * @return {boolean} Element will be clipped to the visible area
4533 OO
.ui
.mixin
.ClippableElement
.prototype.isClipping = function () {
4534 return this.clipping
;
4538 * Check if the bottom or right of the element is being clipped by the nearest scrollable container.
4540 * @return {boolean} Part of the element is being clipped
4542 OO
.ui
.mixin
.ClippableElement
.prototype.isClipped = function () {
4543 return this.clippedHorizontally
|| this.clippedVertically
;
4547 * Check if the right of the element is being clipped by the nearest scrollable container.
4549 * @return {boolean} Part of the element is being clipped
4551 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedHorizontally = function () {
4552 return this.clippedHorizontally
;
4556 * Check if the bottom of the element is being clipped by the nearest scrollable container.
4558 * @return {boolean} Part of the element is being clipped
4560 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedVertically = function () {
4561 return this.clippedVertically
;
4565 * Set the ideal size. These are the dimensions #$clippable will have when it's not being clipped.
4567 * @param {number|string} [width] Width as a number of pixels or CSS string with unit suffix
4568 * @param {number|string} [height] Height as a number of pixels or CSS string with unit suffix
4570 OO
.ui
.mixin
.ClippableElement
.prototype.setIdealSize = function ( width
, height
) {
4571 this.idealWidth
= width
;
4572 this.idealHeight
= height
;
4574 if ( !this.clipping
) {
4575 // Update dimensions
4576 this.$clippable
.css( { width
: width
, height
: height
} );
4578 // While clipping, idealWidth and idealHeight are not considered
4582 * Clip element to visible boundaries and allow scrolling when needed. You should call this method
4583 * when the element's natural height changes.
4585 * Element will be clipped the bottom or right of the element is within 10px of the edge of, or
4586 * overlapped by, the visible area of the nearest scrollable container.
4588 * Because calling clip() when the natural height changes isn't always possible, we also set
4589 * max-height when the element isn't being clipped. This means that if the element tries to grow
4590 * beyond the edge, something reasonable will happen before clip() is called.
4594 OO
.ui
.mixin
.ClippableElement
.prototype.clip = function () {
4595 var $container
, extraHeight
, extraWidth
, ccOffset
,
4596 $scrollableContainer
, scOffset
, scHeight
, scWidth
,
4597 ccWidth
, scrollerIsWindow
, scrollTop
, scrollLeft
,
4598 desiredWidth
, desiredHeight
, allotedWidth
, allotedHeight
,
4599 naturalWidth
, naturalHeight
, clipWidth
, clipHeight
,
4600 buffer
= 7; // Chosen by fair dice roll
4602 if ( !this.clipping
) {
4603 // this.$clippableScrollableContainer and this.$clippableWindow are null, so the below will fail
4607 $container
= this.$clippableContainer
|| this.$clippable
;
4608 extraHeight
= $container
.outerHeight() - this.$clippable
.outerHeight();
4609 extraWidth
= $container
.outerWidth() - this.$clippable
.outerWidth();
4610 ccOffset
= $container
.offset();
4611 if ( this.$clippableScrollableContainer
.is( 'html, body' ) ) {
4612 $scrollableContainer
= this.$clippableWindow
;
4613 scOffset
= { top
: 0, left
: 0 };
4615 $scrollableContainer
= this.$clippableScrollableContainer
;
4616 scOffset
= $scrollableContainer
.offset();
4618 scHeight
= $scrollableContainer
.innerHeight() - buffer
;
4619 scWidth
= $scrollableContainer
.innerWidth() - buffer
;
4620 ccWidth
= $container
.outerWidth() + buffer
;
4621 scrollerIsWindow
= this.$clippableScroller
[ 0 ] === this.$clippableWindow
[ 0 ];
4622 scrollTop
= scrollerIsWindow
? this.$clippableScroller
.scrollTop() : 0;
4623 scrollLeft
= scrollerIsWindow
? this.$clippableScroller
.scrollLeft() : 0;
4624 desiredWidth
= ccOffset
.left
< 0 ?
4625 ccWidth
+ ccOffset
.left
:
4626 ( scOffset
.left
+ scrollLeft
+ scWidth
) - ccOffset
.left
;
4627 desiredHeight
= ( scOffset
.top
+ scrollTop
+ scHeight
) - ccOffset
.top
;
4628 // It should never be desirable to exceed the dimensions of the browser viewport... right?
4629 desiredWidth
= Math
.min( desiredWidth
, document
.documentElement
.clientWidth
);
4630 desiredHeight
= Math
.min( desiredHeight
, document
.documentElement
.clientHeight
);
4631 allotedWidth
= Math
.ceil( desiredWidth
- extraWidth
);
4632 allotedHeight
= Math
.ceil( desiredHeight
- extraHeight
);
4633 naturalWidth
= this.$clippable
.prop( 'scrollWidth' );
4634 naturalHeight
= this.$clippable
.prop( 'scrollHeight' );
4635 clipWidth
= allotedWidth
< naturalWidth
;
4636 clipHeight
= allotedHeight
< naturalHeight
;
4639 // The order matters here. If overflow is not set first, Chrome displays bogus scrollbars. (T157672)
4640 // Forcing a reflow is a smaller workaround than calling reconsiderScrollbars() for this case.
4641 this.$clippable
.css( 'overflowX', 'scroll' );
4642 void this.$clippable
[ 0 ].offsetHeight
; // Force reflow
4643 this.$clippable
.css( {
4644 width
: Math
.max( 0, allotedWidth
),
4648 this.$clippable
.css( {
4650 width
: this.idealWidth
|| '',
4651 maxWidth
: Math
.max( 0, allotedWidth
)
4655 // The order matters here. If overflow is not set first, Chrome displays bogus scrollbars. (T157672)
4656 // Forcing a reflow is a smaller workaround than calling reconsiderScrollbars() for this case.
4657 this.$clippable
.css( 'overflowY', 'scroll' );
4658 void this.$clippable
[ 0 ].offsetHeight
; // Force reflow
4659 this.$clippable
.css( {
4660 height
: Math
.max( 0, allotedHeight
),
4664 this.$clippable
.css( {
4666 height
: this.idealHeight
|| '',
4667 maxHeight
: Math
.max( 0, allotedHeight
)
4671 // If we stopped clipping in at least one of the dimensions
4672 if ( ( this.clippedHorizontally
&& !clipWidth
) || ( this.clippedVertically
&& !clipHeight
) ) {
4673 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4676 this.clippedHorizontally
= clipWidth
;
4677 this.clippedVertically
= clipHeight
;
4683 * PopupWidget is a container for content. The popup is overlaid and positioned absolutely.
4684 * By default, each popup has an anchor that points toward its origin.
4685 * Please see the [OOjs UI documentation on Mediawiki] [1] for more information and examples.
4687 * Unlike most widgets, PopupWidget is initially hidden and must be shown by calling #toggle.
4690 * // A popup widget.
4691 * var popup = new OO.ui.PopupWidget( {
4692 * $content: $( '<p>Hi there!</p>' ),
4697 * $( 'body' ).append( popup.$element );
4698 * // To display the popup, toggle the visibility to 'true'.
4699 * popup.toggle( true );
4701 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups
4704 * @extends OO.ui.Widget
4705 * @mixins OO.ui.mixin.LabelElement
4706 * @mixins OO.ui.mixin.ClippableElement
4707 * @mixins OO.ui.mixin.FloatableElement
4710 * @param {Object} [config] Configuration options
4711 * @cfg {number} [width=320] Width of popup in pixels
4712 * @cfg {number} [height] Height of popup in pixels. Omit to use the automatic height.
4713 * @cfg {boolean} [anchor=true] Show anchor pointing to origin of popup
4714 * @cfg {string} [position='below'] Where to position the popup relative to $floatableContainer
4715 * 'above': Put popup above $floatableContainer; anchor points down to the horizontal center
4716 * of $floatableContainer
4717 * 'below': Put popup below $floatableContainer; anchor points up to the horizontal center
4718 * of $floatableContainer
4719 * 'before': Put popup to the left (LTR) / right (RTL) of $floatableContainer; anchor points
4720 * endwards (right/left) to the vertical center of $floatableContainer
4721 * 'after': Put popup to the right (LTR) / left (RTL) of $floatableContainer; anchor points
4722 * startwards (left/right) to the vertical center of $floatableContainer
4723 * @cfg {string} [align='center'] How to align the popup to $floatableContainer
4724 * 'forwards': If position is above/below, move the popup as far endwards (right in LTR, left in RTL)
4725 * as possible while still keeping the anchor within the popup;
4726 * if position is before/after, move the popup as far downwards as possible.
4727 * 'backwards': If position is above/below, move the popup as far startwards (left in LTR, right in RTL)
4728 * as possible while still keeping the anchor within the popup;
4729 * if position in before/after, move the popup as far upwards as possible.
4730 * 'center': Horizontally (if position is above/below) or vertically (before/after) align the center
4731 * of the popup with the center of $floatableContainer.
4732 * 'force-left': Alias for 'forwards' in LTR and 'backwards' in RTL
4733 * 'force-right': Alias for 'backwards' in RTL and 'forwards' in LTR
4734 * @cfg {jQuery} [$container] Constrain the popup to the boundaries of the specified container.
4735 * See the [OOjs UI docs on MediaWiki][3] for an example.
4736 * [3]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#containerExample
4737 * @cfg {number} [containerPadding=10] Padding between the popup and its container, specified as a number of pixels.
4738 * @cfg {jQuery} [$content] Content to append to the popup's body
4739 * @cfg {jQuery} [$footer] Content to append to the popup's footer
4740 * @cfg {boolean} [autoClose=false] Automatically close the popup when it loses focus.
4741 * @cfg {jQuery} [$autoCloseIgnore] Elements that will not close the popup when clicked.
4742 * This config option is only relevant if #autoClose is set to `true`. See the [OOjs UI docs on MediaWiki][2]
4744 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#autocloseExample
4745 * @cfg {boolean} [head=false] Show a popup header that contains a #label (if specified) and close
4747 * @cfg {boolean} [padded=false] Add padding to the popup's body
4749 OO
.ui
.PopupWidget
= function OoUiPopupWidget( config
) {
4750 // Configuration initialization
4751 config
= config
|| {};
4753 // Parent constructor
4754 OO
.ui
.PopupWidget
.parent
.call( this, config
);
4756 // Properties (must be set before ClippableElement constructor call)
4757 this.$body
= $( '<div>' );
4758 this.$popup
= $( '<div>' );
4760 // Mixin constructors
4761 OO
.ui
.mixin
.LabelElement
.call( this, config
);
4762 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, {
4763 $clippable
: this.$body
,
4764 $clippableContainer
: this.$popup
4766 OO
.ui
.mixin
.FloatableElement
.call( this, config
);
4769 this.$anchor
= $( '<div>' );
4770 // If undefined, will be computed lazily in updateDimensions()
4771 this.$container
= config
.$container
;
4772 this.containerPadding
= config
.containerPadding
!== undefined ? config
.containerPadding
: 10;
4773 this.autoClose
= !!config
.autoClose
;
4774 this.$autoCloseIgnore
= config
.$autoCloseIgnore
;
4775 this.transitionTimeout
= null;
4776 this.anchored
= false;
4777 this.width
= config
.width
!== undefined ? config
.width
: 320;
4778 this.height
= config
.height
!== undefined ? config
.height
: null;
4779 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
4780 this.onDocumentKeyDownHandler
= this.onDocumentKeyDown
.bind( this );
4783 this.toggleAnchor( config
.anchor
=== undefined || config
.anchor
);
4784 this.setAlignment( config
.align
|| 'center' );
4785 this.setPosition( config
.position
|| 'below' );
4786 this.$body
.addClass( 'oo-ui-popupWidget-body' );
4787 this.$anchor
.addClass( 'oo-ui-popupWidget-anchor' );
4789 .addClass( 'oo-ui-popupWidget-popup' )
4790 .append( this.$body
);
4792 .addClass( 'oo-ui-popupWidget' )
4793 .append( this.$popup
, this.$anchor
);
4794 // Move content, which was added to #$element by OO.ui.Widget, to the body
4795 // FIXME This is gross, we should use '$body' or something for the config
4796 if ( config
.$content
instanceof jQuery
) {
4797 this.$body
.append( config
.$content
);
4800 if ( config
.padded
) {
4801 this.$body
.addClass( 'oo-ui-popupWidget-body-padded' );
4804 if ( config
.head
) {
4805 this.closeButton
= new OO
.ui
.ButtonWidget( { framed
: false, icon
: 'close' } );
4806 this.closeButton
.connect( this, { click
: 'onCloseButtonClick' } );
4807 this.$head
= $( '<div>' )
4808 .addClass( 'oo-ui-popupWidget-head' )
4809 .append( this.$label
, this.closeButton
.$element
);
4810 this.$popup
.prepend( this.$head
);
4813 if ( config
.$footer
) {
4814 this.$footer
= $( '<div>' )
4815 .addClass( 'oo-ui-popupWidget-footer' )
4816 .append( config
.$footer
);
4817 this.$popup
.append( this.$footer
);
4820 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
4821 // that reference properties not initialized at that time of parent class construction
4822 // TODO: Find a better way to handle post-constructor setup
4823 this.visible
= false;
4824 this.$element
.addClass( 'oo-ui-element-hidden' );
4829 OO
.inheritClass( OO
.ui
.PopupWidget
, OO
.ui
.Widget
);
4830 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.LabelElement
);
4831 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.ClippableElement
);
4832 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.FloatableElement
);
4839 * The popup is ready: it is visible and has been positioned and clipped.
4845 * Handles mouse down events.
4848 * @param {MouseEvent} e Mouse down event
4850 OO
.ui
.PopupWidget
.prototype.onMouseDown = function ( e
) {
4853 !OO
.ui
.contains( this.$element
.add( this.$autoCloseIgnore
).get(), e
.target
, true )
4855 this.toggle( false );
4860 * Bind mouse down listener.
4864 OO
.ui
.PopupWidget
.prototype.bindMouseDownListener = function () {
4865 // Capture clicks outside popup
4866 this.getElementWindow().addEventListener( 'mousedown', this.onMouseDownHandler
, true );
4870 * Handles close button click events.
4874 OO
.ui
.PopupWidget
.prototype.onCloseButtonClick = function () {
4875 if ( this.isVisible() ) {
4876 this.toggle( false );
4881 * Unbind mouse down listener.
4885 OO
.ui
.PopupWidget
.prototype.unbindMouseDownListener = function () {
4886 this.getElementWindow().removeEventListener( 'mousedown', this.onMouseDownHandler
, true );
4890 * Handles key down events.
4893 * @param {KeyboardEvent} e Key down event
4895 OO
.ui
.PopupWidget
.prototype.onDocumentKeyDown = function ( e
) {
4897 e
.which
=== OO
.ui
.Keys
.ESCAPE
&&
4900 this.toggle( false );
4902 e
.stopPropagation();
4907 * Bind key down listener.
4911 OO
.ui
.PopupWidget
.prototype.bindKeyDownListener = function () {
4912 this.getElementWindow().addEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
4916 * Unbind key down listener.
4920 OO
.ui
.PopupWidget
.prototype.unbindKeyDownListener = function () {
4921 this.getElementWindow().removeEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
4925 * Show, hide, or toggle the visibility of the anchor.
4927 * @param {boolean} [show] Show anchor, omit to toggle
4929 OO
.ui
.PopupWidget
.prototype.toggleAnchor = function ( show
) {
4930 show
= show
=== undefined ? !this.anchored
: !!show
;
4932 if ( this.anchored
!== show
) {
4934 this.$element
.addClass( 'oo-ui-popupWidget-anchored' );
4935 this.$element
.addClass( 'oo-ui-popupWidget-anchored-' + this.anchorEdge
);
4937 this.$element
.removeClass( 'oo-ui-popupWidget-anchored' );
4938 this.$element
.removeClass( 'oo-ui-popupWidget-anchored-' + this.anchorEdge
);
4940 this.anchored
= show
;
4944 * Change which edge the anchor appears on.
4946 * @param {string} edge 'top', 'bottom', 'start' or 'end'
4948 OO
.ui
.PopupWidget
.prototype.setAnchorEdge = function ( edge
) {
4949 if ( [ 'top', 'bottom', 'start', 'end' ].indexOf( edge
) === -1 ) {
4950 throw new Error( 'Invalid value for edge: ' + edge
);
4952 if ( this.anchorEdge
!== null ) {
4953 this.$element
.removeClass( 'oo-ui-popupWidget-anchored-' + this.anchorEdge
);
4955 this.anchorEdge
= edge
;
4956 if ( this.anchored
) {
4957 this.$element
.addClass( 'oo-ui-popupWidget-anchored-' + edge
);
4962 * Check if the anchor is visible.
4964 * @return {boolean} Anchor is visible
4966 OO
.ui
.PopupWidget
.prototype.hasAnchor = function () {
4967 return this.anchored
;
4971 * Toggle visibility of the popup. The popup is initially hidden and must be shown by calling
4972 * `.toggle( true )` after its #$element is attached to the DOM.
4974 * Do not show the popup while it is not attached to the DOM. The calculations required to display
4975 * it in the right place and with the right dimensions only work correctly while it is attached.
4976 * Side-effects may include broken interface and exceptions being thrown. This wasn't always
4977 * strictly enforced, so currently it only generates a warning in the browser console.
4982 OO
.ui
.PopupWidget
.prototype.toggle = function ( show
) {
4984 show
= show
=== undefined ? !this.isVisible() : !!show
;
4986 change
= show
!== this.isVisible();
4988 if ( show
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
4989 OO
.ui
.warnDeprecation( 'PopupWidget#toggle: Before calling this method, the popup must be attached to the DOM.' );
4990 this.warnedUnattached
= true;
4992 if ( show
&& !this.$floatableContainer
&& this.isElementAttached() ) {
4993 // Fall back to the parent node if the floatableContainer is not set
4994 this.setFloatableContainer( this.$element
.parent() );
4998 OO
.ui
.PopupWidget
.parent
.prototype.toggle
.call( this, show
);
5001 this.togglePositioning( show
&& !!this.$floatableContainer
);
5004 if ( this.autoClose
) {
5005 this.bindMouseDownListener();
5006 this.bindKeyDownListener();
5008 this.updateDimensions();
5009 this.toggleClipping( true );
5010 this.emit( 'ready' );
5012 this.toggleClipping( false );
5013 if ( this.autoClose
) {
5014 this.unbindMouseDownListener();
5015 this.unbindKeyDownListener();
5024 * Set the size of the popup.
5026 * Changing the size may also change the popup's position depending on the alignment.
5028 * @param {number} width Width in pixels
5029 * @param {number} height Height in pixels
5030 * @param {boolean} [transition=false] Use a smooth transition
5033 OO
.ui
.PopupWidget
.prototype.setSize = function ( width
, height
, transition
) {
5035 this.height
= height
!== undefined ? height
: null;
5036 if ( this.isVisible() ) {
5037 this.updateDimensions( transition
);
5042 * Update the size and position.
5044 * Only use this to keep the popup properly anchored. Use #setSize to change the size, and this will
5045 * be called automatically.
5047 * @param {boolean} [transition=false] Use a smooth transition
5050 OO
.ui
.PopupWidget
.prototype.updateDimensions = function ( transition
) {
5053 // Prevent transition from being interrupted
5054 clearTimeout( this.transitionTimeout
);
5056 // Enable transition
5057 this.$element
.addClass( 'oo-ui-popupWidget-transitioning' );
5063 // Prevent transitioning after transition is complete
5064 this.transitionTimeout
= setTimeout( function () {
5065 widget
.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
5068 // Prevent transitioning immediately
5069 this.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
5076 OO
.ui
.PopupWidget
.prototype.computePosition = function () {
5077 var direction
, align
, vertical
, start
, end
, near
, far
, sizeProp
, popupSize
, anchorSize
, anchorPos
,
5078 anchorOffset
, anchorMargin
, parentPosition
, positionProp
, positionAdjustment
, floatablePos
,
5079 offsetParentPos
, containerPos
,
5081 anchorCss
= { left
: '', right
: '', top
: '', bottom
: '' },
5084 'force-left': 'backwards',
5085 'force-right': 'forwards'
5088 'force-left': 'forwards',
5089 'force-right': 'backwards'
5109 if ( !this.$container
) {
5110 // Lazy-initialize $container if not specified in constructor
5111 this.$container
= $( this.getClosestScrollableElementContainer() );
5113 direction
= this.$container
.css( 'direction' );
5115 // Set height and width before we do anything else, since it might cause our measurements
5116 // to change (e.g. due to scrollbars appearing or disappearing), and it also affects centering
5119 height
: this.height
!== null ? this.height
: 'auto'
5122 align
= alignMap
[ direction
][ this.align
] || this.align
;
5123 // If the popup is positioned before or after, then the anchor positioning is vertical, otherwise horizontal
5124 vertical
= this.popupPosition
=== 'before' || this.popupPosition
=== 'after';
5125 start
= vertical
? 'top' : ( direction
=== 'rtl' ? 'right' : 'left' );
5126 end
= vertical
? 'bottom' : ( direction
=== 'rtl' ? 'left' : 'right' );
5127 near
= vertical
? 'top' : 'left';
5128 far
= vertical
? 'bottom' : 'right';
5129 sizeProp
= vertical
? 'Height' : 'Width';
5130 popupSize
= vertical
? ( this.height
|| this.$popup
.height() ) : this.width
;
5132 this.setAnchorEdge( anchorEdgeMap
[ this.popupPosition
] );
5133 this.horizontalPosition
= vertical
? this.popupPosition
: hPosMap
[ align
];
5134 this.verticalPosition
= vertical
? vPosMap
[ align
] : this.popupPosition
;
5137 parentPosition
= OO
.ui
.mixin
.FloatableElement
.prototype.computePosition
.call( this );
5138 // Find out which property FloatableElement used for positioning, and adjust that value
5139 positionProp
= vertical
?
5140 ( parentPosition
.top
!== '' ? 'top' : 'bottom' ) :
5141 ( parentPosition
.left
!== '' ? 'left' : 'right' );
5143 // Figure out where the near and far edges of the popup and $floatableContainer are
5144 floatablePos
= this.$floatableContainer
.offset();
5145 floatablePos
[ far
] = floatablePos
[ near
] + this.$floatableContainer
[ 'outer' + sizeProp
]();
5146 // Measure where the offsetParent is and compute our position based on that and parentPosition
5147 offsetParentPos
= this.$element
.offsetParent().offset();
5149 if ( positionProp
=== near
) {
5150 popupPos
[ near
] = offsetParentPos
[ near
] + parentPosition
[ near
];
5151 popupPos
[ far
] = popupPos
[ near
] + popupSize
;
5153 popupPos
[ far
] = offsetParentPos
[ near
] +
5154 this.$element
.offsetParent()[ 'inner' + sizeProp
]() - parentPosition
[ far
];
5155 popupPos
[ near
] = popupPos
[ far
] - popupSize
;
5158 // Position the anchor (which is positioned relative to the popup) to point to $floatableContainer
5159 anchorPos
= ( floatablePos
[ start
] + floatablePos
[ end
] ) / 2;
5160 anchorOffset
= ( start
=== far
? -1 : 1 ) * ( anchorPos
- popupPos
[ start
] );
5162 // If the anchor is less than 2*anchorSize from either edge, move the popup to make more space
5163 // this.$anchor.width()/height() returns 0 because of the CSS trickery we use, so use scrollWidth/Height
5164 anchorSize
= this.$anchor
[ 0 ][ 'scroll' + sizeProp
];
5165 anchorMargin
= parseFloat( this.$anchor
.css( 'margin-' + start
) );
5166 if ( anchorOffset
+ anchorMargin
< 2 * anchorSize
) {
5167 // Not enough space for the anchor on the start side; pull the popup startwards
5168 positionAdjustment
= ( positionProp
=== start
? -1 : 1 ) *
5169 ( 2 * anchorSize
- ( anchorOffset
+ anchorMargin
) );
5170 } else if ( anchorOffset
+ anchorMargin
> popupSize
- 2 * anchorSize
) {
5171 // Not enough space for the anchor on the end side; pull the popup endwards
5172 positionAdjustment
= ( positionProp
=== end
? -1 : 1 ) *
5173 ( anchorOffset
+ anchorMargin
- ( popupSize
- 2 * anchorSize
) );
5175 positionAdjustment
= 0;
5178 // Check if the popup will go beyond the edge of this.$container
5179 containerPos
= this.$container
.offset();
5180 containerPos
[ far
] = containerPos
[ near
] + this.$container
[ 'inner' + sizeProp
]();
5181 // Take into account how much the popup will move because of the adjustments we're going to make
5182 popupPos
[ near
] += ( positionProp
=== near
? 1 : -1 ) * positionAdjustment
;
5183 popupPos
[ far
] += ( positionProp
=== near
? 1 : -1 ) * positionAdjustment
;
5184 if ( containerPos
[ near
] + this.containerPadding
> popupPos
[ near
] ) {
5185 // Popup goes beyond the near (left/top) edge, move it to the right/bottom
5186 positionAdjustment
+= ( positionProp
=== near
? 1 : -1 ) *
5187 ( containerPos
[ near
] + this.containerPadding
- popupPos
[ near
] );
5188 } else if ( containerPos
[ far
] - this.containerPadding
< popupPos
[ far
] ) {
5189 // Popup goes beyond the far (right/bottom) edge, move it to the left/top
5190 positionAdjustment
+= ( positionProp
=== far
? 1 : -1 ) *
5191 ( popupPos
[ far
] - ( containerPos
[ far
] - this.containerPadding
) );
5194 // Adjust anchorOffset for positionAdjustment
5195 anchorOffset
+= ( positionProp
=== start
? -1 : 1 ) * positionAdjustment
;
5197 // Position the anchor
5198 anchorCss
[ start
] = anchorOffset
;
5199 this.$anchor
.css( anchorCss
);
5200 // Move the popup if needed
5201 parentPosition
[ positionProp
] += positionAdjustment
;
5203 return parentPosition
;
5207 * Set popup alignment
5209 * @param {string} [align=center] Alignment of the popup, `center`, `force-left`, `force-right`,
5210 * `backwards` or `forwards`.
5212 OO
.ui
.PopupWidget
.prototype.setAlignment = function ( align
) {
5213 // Validate alignment
5214 if ( [ 'force-left', 'force-right', 'backwards', 'forwards', 'center' ].indexOf( align
) > -1 ) {
5217 this.align
= 'center';
5223 * Get popup alignment
5225 * @return {string} Alignment of the popup, `center`, `force-left`, `force-right`,
5226 * `backwards` or `forwards`.
5228 OO
.ui
.PopupWidget
.prototype.getAlignment = function () {
5233 * Change the positioning of the popup.
5235 * @param {string} position 'above', 'below', 'before' or 'after'
5237 OO
.ui
.PopupWidget
.prototype.setPosition = function ( position
) {
5238 if ( [ 'above', 'below', 'before', 'after' ].indexOf( position
) === -1 ) {
5241 this.popupPosition
= position
;
5246 * Get popup positioning.
5248 * @return {string} 'above', 'below', 'before' or 'after'
5250 OO
.ui
.PopupWidget
.prototype.getPosition = function () {
5251 return this.popupPosition
;
5255 * PopupElement is mixed into other classes to generate a {@link OO.ui.PopupWidget popup widget}.
5256 * A popup is a container for content. It is overlaid and positioned absolutely. By default, each
5257 * popup has an anchor, which is an arrow-like protrusion that points toward the popup’s origin.
5258 * See {@link OO.ui.PopupWidget PopupWidget} for an example.
5264 * @param {Object} [config] Configuration options
5265 * @cfg {Object} [popup] Configuration to pass to popup
5266 * @cfg {boolean} [popup.autoClose=true] Popup auto-closes when it loses focus
5268 OO
.ui
.mixin
.PopupElement
= function OoUiMixinPopupElement( config
) {
5269 // Configuration initialization
5270 config
= config
|| {};
5273 this.popup
= new OO
.ui
.PopupWidget( $.extend(
5276 $floatableContainer
: this.$element
5280 $autoCloseIgnore
: this.$element
.add( config
.popup
&& config
.popup
.$autoCloseIgnore
)
5290 * @return {OO.ui.PopupWidget} Popup widget
5292 OO
.ui
.mixin
.PopupElement
.prototype.getPopup = function () {
5297 * PopupButtonWidgets toggle the visibility of a contained {@link OO.ui.PopupWidget PopupWidget},
5298 * which is used to display additional information or options.
5301 * // Example of a popup button.
5302 * var popupButton = new OO.ui.PopupButtonWidget( {
5303 * label: 'Popup button with options',
5306 * $content: $( '<p>Additional options here.</p>' ),
5308 * align: 'force-left'
5311 * // Append the button to the DOM.
5312 * $( 'body' ).append( popupButton.$element );
5315 * @extends OO.ui.ButtonWidget
5316 * @mixins OO.ui.mixin.PopupElement
5319 * @param {Object} [config] Configuration options
5320 * @cfg {jQuery} [$overlay] Render the popup into a separate layer. This configuration is useful in cases where
5321 * the expanded popup is larger than its containing `<div>`. The specified overlay layer is usually on top of the
5322 * containing `<div>` and has a larger area. By default, the popup uses relative positioning.
5324 OO
.ui
.PopupButtonWidget
= function OoUiPopupButtonWidget( config
) {
5325 // Parent constructor
5326 OO
.ui
.PopupButtonWidget
.parent
.call( this, config
);
5328 // Mixin constructors
5329 OO
.ui
.mixin
.PopupElement
.call( this, config
);
5332 this.$overlay
= config
.$overlay
|| this.$element
;
5335 this.connect( this, { click
: 'onAction' } );
5339 .addClass( 'oo-ui-popupButtonWidget' )
5340 .attr( 'aria-haspopup', 'true' );
5342 .addClass( 'oo-ui-popupButtonWidget-popup' )
5343 .toggleClass( 'oo-ui-popupButtonWidget-framed-popup', this.isFramed() )
5344 .toggleClass( 'oo-ui-popupButtonWidget-frameless-popup', !this.isFramed() );
5345 this.$overlay
.append( this.popup
.$element
);
5350 OO
.inheritClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.ButtonWidget
);
5351 OO
.mixinClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.mixin
.PopupElement
);
5356 * Handle the button action being triggered.
5360 OO
.ui
.PopupButtonWidget
.prototype.onAction = function () {
5361 this.popup
.toggle();
5365 * Mixin for OO.ui.Widget subclasses to provide OO.ui.mixin.GroupElement.
5367 * Use together with OO.ui.mixin.ItemWidget to make disabled state inheritable.
5372 * @mixins OO.ui.mixin.GroupElement
5375 * @param {Object} [config] Configuration options
5377 OO
.ui
.mixin
.GroupWidget
= function OoUiMixinGroupWidget( config
) {
5378 // Mixin constructors
5379 OO
.ui
.mixin
.GroupElement
.call( this, config
);
5384 OO
.mixinClass( OO
.ui
.mixin
.GroupWidget
, OO
.ui
.mixin
.GroupElement
);
5389 * Set the disabled state of the widget.
5391 * This will also update the disabled state of child widgets.
5393 * @param {boolean} disabled Disable widget
5396 OO
.ui
.mixin
.GroupWidget
.prototype.setDisabled = function ( disabled
) {
5400 // Note: Calling #setDisabled this way assumes this is mixed into an OO.ui.Widget
5401 OO
.ui
.Widget
.prototype.setDisabled
.call( this, disabled
);
5403 // During construction, #setDisabled is called before the OO.ui.mixin.GroupElement constructor
5405 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5406 this.items
[ i
].updateDisabled();
5414 * Mixin for widgets used as items in widgets that mix in OO.ui.mixin.GroupWidget.
5416 * Item widgets have a reference to a OO.ui.mixin.GroupWidget while they are attached to the group. This
5417 * allows bidirectional communication.
5419 * Use together with OO.ui.mixin.GroupWidget to make disabled state inheritable.
5427 OO
.ui
.mixin
.ItemWidget
= function OoUiMixinItemWidget() {
5434 * Check if widget is disabled.
5436 * Checks parent if present, making disabled state inheritable.
5438 * @return {boolean} Widget is disabled
5440 OO
.ui
.mixin
.ItemWidget
.prototype.isDisabled = function () {
5441 return this.disabled
||
5442 ( this.elementGroup
instanceof OO
.ui
.Widget
&& this.elementGroup
.isDisabled() );
5446 * Set group element is in.
5448 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
5451 OO
.ui
.mixin
.ItemWidget
.prototype.setElementGroup = function ( group
) {
5453 // Note: Calling #setElementGroup this way assumes this is mixed into an OO.ui.Element
5454 OO
.ui
.Element
.prototype.setElementGroup
.call( this, group
);
5456 // Initialize item disabled states
5457 this.updateDisabled();
5463 * OptionWidgets are special elements that can be selected and configured with data. The
5464 * data is often unique for each option, but it does not have to be. OptionWidgets are used
5465 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
5466 * and examples, please see the [OOjs UI documentation on MediaWiki][1].
5468 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5471 * @extends OO.ui.Widget
5472 * @mixins OO.ui.mixin.ItemWidget
5473 * @mixins OO.ui.mixin.LabelElement
5474 * @mixins OO.ui.mixin.FlaggedElement
5475 * @mixins OO.ui.mixin.AccessKeyedElement
5478 * @param {Object} [config] Configuration options
5480 OO
.ui
.OptionWidget
= function OoUiOptionWidget( config
) {
5481 // Configuration initialization
5482 config
= config
|| {};
5484 // Parent constructor
5485 OO
.ui
.OptionWidget
.parent
.call( this, config
);
5487 // Mixin constructors
5488 OO
.ui
.mixin
.ItemWidget
.call( this );
5489 OO
.ui
.mixin
.LabelElement
.call( this, config
);
5490 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
5491 OO
.ui
.mixin
.AccessKeyedElement
.call( this, config
);
5494 this.selected
= false;
5495 this.highlighted
= false;
5496 this.pressed
= false;
5500 .data( 'oo-ui-optionWidget', this )
5501 // Allow programmatic focussing (and by accesskey), but not tabbing
5502 .attr( 'tabindex', '-1' )
5503 .attr( 'role', 'option' )
5504 .attr( 'aria-selected', 'false' )
5505 .addClass( 'oo-ui-optionWidget' )
5506 .append( this.$label
);
5511 OO
.inheritClass( OO
.ui
.OptionWidget
, OO
.ui
.Widget
);
5512 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.ItemWidget
);
5513 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.LabelElement
);
5514 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.FlaggedElement
);
5515 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
5517 /* Static Properties */
5520 * Whether this option can be selected. See #setSelected.
5524 * @property {boolean}
5526 OO
.ui
.OptionWidget
.static.selectable
= true;
5529 * Whether this option can be highlighted. See #setHighlighted.
5533 * @property {boolean}
5535 OO
.ui
.OptionWidget
.static.highlightable
= true;
5538 * Whether this option can be pressed. See #setPressed.
5542 * @property {boolean}
5544 OO
.ui
.OptionWidget
.static.pressable
= true;
5547 * Whether this option will be scrolled into view when it is selected.
5551 * @property {boolean}
5553 OO
.ui
.OptionWidget
.static.scrollIntoViewOnSelect
= false;
5558 * Check if the option can be selected.
5560 * @return {boolean} Item is selectable
5562 OO
.ui
.OptionWidget
.prototype.isSelectable = function () {
5563 return this.constructor.static.selectable
&& !this.isDisabled() && this.isVisible();
5567 * Check if the option can be highlighted. A highlight indicates that the option
5568 * may be selected when a user presses enter or clicks. Disabled items cannot
5571 * @return {boolean} Item is highlightable
5573 OO
.ui
.OptionWidget
.prototype.isHighlightable = function () {
5574 return this.constructor.static.highlightable
&& !this.isDisabled() && this.isVisible();
5578 * Check if the option can be pressed. The pressed state occurs when a user mouses
5579 * down on an item, but has not yet let go of the mouse.
5581 * @return {boolean} Item is pressable
5583 OO
.ui
.OptionWidget
.prototype.isPressable = function () {
5584 return this.constructor.static.pressable
&& !this.isDisabled() && this.isVisible();
5588 * Check if the option is selected.
5590 * @return {boolean} Item is selected
5592 OO
.ui
.OptionWidget
.prototype.isSelected = function () {
5593 return this.selected
;
5597 * Check if the option is highlighted. A highlight indicates that the
5598 * item may be selected when a user presses enter or clicks.
5600 * @return {boolean} Item is highlighted
5602 OO
.ui
.OptionWidget
.prototype.isHighlighted = function () {
5603 return this.highlighted
;
5607 * Check if the option is pressed. The pressed state occurs when a user mouses
5608 * down on an item, but has not yet let go of the mouse. The item may appear
5609 * selected, but it will not be selected until the user releases the mouse.
5611 * @return {boolean} Item is pressed
5613 OO
.ui
.OptionWidget
.prototype.isPressed = function () {
5614 return this.pressed
;
5618 * Set the option’s selected state. In general, all modifications to the selection
5619 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
5620 * method instead of this method.
5622 * @param {boolean} [state=false] Select option
5625 OO
.ui
.OptionWidget
.prototype.setSelected = function ( state
) {
5626 if ( this.constructor.static.selectable
) {
5627 this.selected
= !!state
;
5629 .toggleClass( 'oo-ui-optionWidget-selected', state
)
5630 .attr( 'aria-selected', state
.toString() );
5631 if ( state
&& this.constructor.static.scrollIntoViewOnSelect
) {
5632 this.scrollElementIntoView();
5634 this.updateThemeClasses();
5640 * Set the option’s highlighted state. In general, all programmatic
5641 * modifications to the highlight should be handled by the
5642 * SelectWidget’s {@link OO.ui.SelectWidget#highlightItem highlightItem( [item] )}
5643 * method instead of this method.
5645 * @param {boolean} [state=false] Highlight option
5648 OO
.ui
.OptionWidget
.prototype.setHighlighted = function ( state
) {
5649 if ( this.constructor.static.highlightable
) {
5650 this.highlighted
= !!state
;
5651 this.$element
.toggleClass( 'oo-ui-optionWidget-highlighted', state
);
5652 this.updateThemeClasses();
5658 * Set the option’s pressed state. In general, all
5659 * programmatic modifications to the pressed state should be handled by the
5660 * SelectWidget’s {@link OO.ui.SelectWidget#pressItem pressItem( [item] )}
5661 * method instead of this method.
5663 * @param {boolean} [state=false] Press option
5666 OO
.ui
.OptionWidget
.prototype.setPressed = function ( state
) {
5667 if ( this.constructor.static.pressable
) {
5668 this.pressed
= !!state
;
5669 this.$element
.toggleClass( 'oo-ui-optionWidget-pressed', state
);
5670 this.updateThemeClasses();
5676 * Get text to match search strings against.
5678 * The default implementation returns the label text, but subclasses
5679 * can override this to provide more complex behavior.
5681 * @return {string|boolean} String to match search string against
5683 OO
.ui
.OptionWidget
.prototype.getMatchText = function () {
5684 var label
= this.getLabel();
5685 return typeof label
=== 'string' ? label
: this.$label
.text();
5689 * A SelectWidget is of a generic selection of options. The OOjs UI library contains several types of
5690 * select widgets, including {@link OO.ui.ButtonSelectWidget button selects},
5691 * {@link OO.ui.RadioSelectWidget radio selects}, and {@link OO.ui.MenuSelectWidget
5694 * This class should be used together with OO.ui.OptionWidget or OO.ui.DecoratedOptionWidget. For more
5695 * information, please see the [OOjs UI documentation on MediaWiki][1].
5698 * // Example of a select widget with three options
5699 * var select = new OO.ui.SelectWidget( {
5701 * new OO.ui.OptionWidget( {
5703 * label: 'Option One',
5705 * new OO.ui.OptionWidget( {
5707 * label: 'Option Two',
5709 * new OO.ui.OptionWidget( {
5711 * label: 'Option Three',
5715 * $( 'body' ).append( select.$element );
5717 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5721 * @extends OO.ui.Widget
5722 * @mixins OO.ui.mixin.GroupWidget
5725 * @param {Object} [config] Configuration options
5726 * @cfg {OO.ui.OptionWidget[]} [items] An array of options to add to the select.
5727 * Options are created with {@link OO.ui.OptionWidget OptionWidget} classes. See
5728 * the [OOjs UI documentation on MediaWiki] [2] for examples.
5729 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5731 OO
.ui
.SelectWidget
= function OoUiSelectWidget( config
) {
5732 // Configuration initialization
5733 config
= config
|| {};
5735 // Parent constructor
5736 OO
.ui
.SelectWidget
.parent
.call( this, config
);
5738 // Mixin constructors
5739 OO
.ui
.mixin
.GroupWidget
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
5742 this.pressed
= false;
5743 this.selecting
= null;
5744 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
5745 this.onMouseMoveHandler
= this.onMouseMove
.bind( this );
5746 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
5747 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
5748 this.keyPressBuffer
= '';
5749 this.keyPressBufferTimer
= null;
5750 this.blockMouseOverEvents
= 0;
5753 this.connect( this, {
5757 focusin
: this.onFocus
.bind( this ),
5758 mousedown
: this.onMouseDown
.bind( this ),
5759 mouseover
: this.onMouseOver
.bind( this ),
5760 mouseleave
: this.onMouseLeave
.bind( this )
5765 .addClass( 'oo-ui-selectWidget oo-ui-selectWidget-depressed' )
5766 .attr( 'role', 'listbox' );
5767 if ( Array
.isArray( config
.items
) ) {
5768 this.addItems( config
.items
);
5774 OO
.inheritClass( OO
.ui
.SelectWidget
, OO
.ui
.Widget
);
5775 OO
.mixinClass( OO
.ui
.SelectWidget
, OO
.ui
.mixin
.GroupWidget
);
5782 * A `highlight` event is emitted when the highlight is changed with the #highlightItem method.
5784 * @param {OO.ui.OptionWidget|null} item Highlighted item
5790 * A `press` event is emitted when the #pressItem method is used to programmatically modify the
5791 * pressed state of an option.
5793 * @param {OO.ui.OptionWidget|null} item Pressed item
5799 * A `select` event is emitted when the selection is modified programmatically with the #selectItem method.
5801 * @param {OO.ui.OptionWidget|null} item Selected item
5806 * A `choose` event is emitted when an item is chosen with the #chooseItem method.
5807 * @param {OO.ui.OptionWidget} item Chosen item
5813 * An `add` event is emitted when options are added to the select with the #addItems method.
5815 * @param {OO.ui.OptionWidget[]} items Added items
5816 * @param {number} index Index of insertion point
5822 * A `remove` event is emitted when options are removed from the select with the #clearItems
5823 * or #removeItems methods.
5825 * @param {OO.ui.OptionWidget[]} items Removed items
5831 * Handle focus events
5834 * @param {jQuery.Event} event
5836 OO
.ui
.SelectWidget
.prototype.onFocus = function ( event
) {
5838 if ( event
.target
=== this.$element
[ 0 ] ) {
5839 // This widget was focussed, e.g. by the user tabbing to it.
5840 // The styles for focus state depend on one of the items being selected.
5841 if ( !this.getSelectedItem() ) {
5842 item
= this.getFirstSelectableItem();
5845 // One of the options got focussed (and the event bubbled up here).
5846 // They can't be tabbed to, but they can be activated using accesskeys.
5847 item
= this.getTargetItem( event
);
5851 if ( item
.constructor.static.highlightable
) {
5852 this.highlightItem( item
);
5854 this.selectItem( item
);
5858 if ( event
.target
!== this.$element
[ 0 ] ) {
5859 this.$element
.focus();
5864 * Handle mouse down events.
5867 * @param {jQuery.Event} e Mouse down event
5869 OO
.ui
.SelectWidget
.prototype.onMouseDown = function ( e
) {
5872 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
5873 this.togglePressed( true );
5874 item
= this.getTargetItem( e
);
5875 if ( item
&& item
.isSelectable() ) {
5876 this.pressItem( item
);
5877 this.selecting
= item
;
5878 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
5879 this.getElementDocument().addEventListener( 'mousemove', this.onMouseMoveHandler
, true );
5886 * Handle mouse up events.
5889 * @param {MouseEvent} e Mouse up event
5891 OO
.ui
.SelectWidget
.prototype.onMouseUp = function ( e
) {
5894 this.togglePressed( false );
5895 if ( !this.selecting
) {
5896 item
= this.getTargetItem( e
);
5897 if ( item
&& item
.isSelectable() ) {
5898 this.selecting
= item
;
5901 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
&& this.selecting
) {
5902 this.pressItem( null );
5903 this.chooseItem( this.selecting
);
5904 this.selecting
= null;
5907 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
5908 this.getElementDocument().removeEventListener( 'mousemove', this.onMouseMoveHandler
, true );
5914 * Handle mouse move events.
5917 * @param {MouseEvent} e Mouse move event
5919 OO
.ui
.SelectWidget
.prototype.onMouseMove = function ( e
) {
5922 if ( !this.isDisabled() && this.pressed
) {
5923 item
= this.getTargetItem( e
);
5924 if ( item
&& item
!== this.selecting
&& item
.isSelectable() ) {
5925 this.pressItem( item
);
5926 this.selecting
= item
;
5932 * Handle mouse over events.
5935 * @param {jQuery.Event} e Mouse over event
5937 OO
.ui
.SelectWidget
.prototype.onMouseOver = function ( e
) {
5939 if ( this.blockMouseOverEvents
) {
5942 if ( !this.isDisabled() ) {
5943 item
= this.getTargetItem( e
);
5944 this.highlightItem( item
&& item
.isHighlightable() ? item
: null );
5950 * Handle mouse leave events.
5953 * @param {jQuery.Event} e Mouse over event
5955 OO
.ui
.SelectWidget
.prototype.onMouseLeave = function () {
5956 if ( !this.isDisabled() ) {
5957 this.highlightItem( null );
5963 * Handle key down events.
5966 * @param {KeyboardEvent} e Key down event
5968 OO
.ui
.SelectWidget
.prototype.onKeyDown = function ( e
) {
5971 currentItem
= this.getHighlightedItem() || this.getSelectedItem();
5973 if ( !this.isDisabled() && this.isVisible() ) {
5974 switch ( e
.keyCode
) {
5975 case OO
.ui
.Keys
.ENTER
:
5976 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
5977 // Was only highlighted, now let's select it. No-op if already selected.
5978 this.chooseItem( currentItem
);
5983 case OO
.ui
.Keys
.LEFT
:
5984 this.clearKeyPressBuffer();
5985 nextItem
= this.getRelativeSelectableItem( currentItem
, -1 );
5988 case OO
.ui
.Keys
.DOWN
:
5989 case OO
.ui
.Keys
.RIGHT
:
5990 this.clearKeyPressBuffer();
5991 nextItem
= this.getRelativeSelectableItem( currentItem
, 1 );
5994 case OO
.ui
.Keys
.ESCAPE
:
5995 case OO
.ui
.Keys
.TAB
:
5996 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
5997 currentItem
.setHighlighted( false );
5999 this.unbindKeyDownListener();
6000 this.unbindKeyPressListener();
6001 // Don't prevent tabbing away / defocusing
6007 if ( nextItem
.constructor.static.highlightable
) {
6008 this.highlightItem( nextItem
);
6010 this.chooseItem( nextItem
);
6012 this.scrollItemIntoView( nextItem
);
6017 e
.stopPropagation();
6023 * Bind key down listener.
6027 OO
.ui
.SelectWidget
.prototype.bindKeyDownListener = function () {
6028 this.getElementWindow().addEventListener( 'keydown', this.onKeyDownHandler
, true );
6032 * Unbind key down listener.
6036 OO
.ui
.SelectWidget
.prototype.unbindKeyDownListener = function () {
6037 this.getElementWindow().removeEventListener( 'keydown', this.onKeyDownHandler
, true );
6041 * Scroll item into view, preventing spurious mouse highlight actions from happening.
6043 * @param {OO.ui.OptionWidget} item Item to scroll into view
6045 OO
.ui
.SelectWidget
.prototype.scrollItemIntoView = function ( item
) {
6047 // Chromium's Blink engine will generate spurious 'mouseover' events during programmatic scrolling
6048 // and around 100-150 ms after it is finished.
6049 this.blockMouseOverEvents
++;
6050 item
.scrollElementIntoView().done( function () {
6051 setTimeout( function () {
6052 widget
.blockMouseOverEvents
--;
6058 * Clear the key-press buffer
6062 OO
.ui
.SelectWidget
.prototype.clearKeyPressBuffer = function () {
6063 if ( this.keyPressBufferTimer
) {
6064 clearTimeout( this.keyPressBufferTimer
);
6065 this.keyPressBufferTimer
= null;
6067 this.keyPressBuffer
= '';
6071 * Handle key press events.
6074 * @param {KeyboardEvent} e Key press event
6076 OO
.ui
.SelectWidget
.prototype.onKeyPress = function ( e
) {
6077 var c
, filter
, item
;
6079 if ( !e
.charCode
) {
6080 if ( e
.keyCode
=== OO
.ui
.Keys
.BACKSPACE
&& this.keyPressBuffer
!== '' ) {
6081 this.keyPressBuffer
= this.keyPressBuffer
.substr( 0, this.keyPressBuffer
.length
- 1 );
6086 if ( String
.fromCodePoint
) {
6087 c
= String
.fromCodePoint( e
.charCode
);
6089 c
= String
.fromCharCode( e
.charCode
);
6092 if ( this.keyPressBufferTimer
) {
6093 clearTimeout( this.keyPressBufferTimer
);
6095 this.keyPressBufferTimer
= setTimeout( this.clearKeyPressBuffer
.bind( this ), 1500 );
6097 item
= this.getHighlightedItem() || this.getSelectedItem();
6099 if ( this.keyPressBuffer
=== c
) {
6100 // Common (if weird) special case: typing "xxxx" will cycle through all
6101 // the items beginning with "x".
6103 item
= this.getRelativeSelectableItem( item
, 1 );
6106 this.keyPressBuffer
+= c
;
6109 filter
= this.getItemMatcher( this.keyPressBuffer
, false );
6110 if ( !item
|| !filter( item
) ) {
6111 item
= this.getRelativeSelectableItem( item
, 1, filter
);
6114 if ( this.isVisible() && item
.constructor.static.highlightable
) {
6115 this.highlightItem( item
);
6117 this.chooseItem( item
);
6119 this.scrollItemIntoView( item
);
6123 e
.stopPropagation();
6127 * Get a matcher for the specific string
6130 * @param {string} s String to match against items
6131 * @param {boolean} [exact=false] Only accept exact matches
6132 * @return {Function} function ( OO.ui.OptionWidget ) => boolean
6134 OO
.ui
.SelectWidget
.prototype.getItemMatcher = function ( s
, exact
) {
6137 if ( s
.normalize
) {
6140 s
= exact
? s
.trim() : s
.replace( /^\s+/, '' );
6141 re
= '^\\s*' + s
.replace( /([\\{}()|.?*+\-\^$\[\]])/g, '\\$1' ).replace( /\s+/g, '\\s+' );
6145 re
= new RegExp( re
, 'i' );
6146 return function ( item
) {
6147 var matchText
= item
.getMatchText();
6148 if ( matchText
.normalize
) {
6149 matchText
= matchText
.normalize();
6151 return re
.test( matchText
);
6156 * Bind key press listener.
6160 OO
.ui
.SelectWidget
.prototype.bindKeyPressListener = function () {
6161 this.getElementWindow().addEventListener( 'keypress', this.onKeyPressHandler
, true );
6165 * Unbind key down listener.
6167 * If you override this, be sure to call this.clearKeyPressBuffer() from your
6172 OO
.ui
.SelectWidget
.prototype.unbindKeyPressListener = function () {
6173 this.getElementWindow().removeEventListener( 'keypress', this.onKeyPressHandler
, true );
6174 this.clearKeyPressBuffer();
6178 * Visibility change handler
6181 * @param {boolean} visible
6183 OO
.ui
.SelectWidget
.prototype.onToggle = function ( visible
) {
6185 this.clearKeyPressBuffer();
6190 * Get the closest item to a jQuery.Event.
6193 * @param {jQuery.Event} e
6194 * @return {OO.ui.OptionWidget|null} Outline item widget, `null` if none was found
6196 OO
.ui
.SelectWidget
.prototype.getTargetItem = function ( e
) {
6197 return $( e
.target
).closest( '.oo-ui-optionWidget' ).data( 'oo-ui-optionWidget' ) || null;
6201 * Get selected item.
6203 * @return {OO.ui.OptionWidget|null} Selected item, `null` if no item is selected
6205 OO
.ui
.SelectWidget
.prototype.getSelectedItem = function () {
6208 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6209 if ( this.items
[ i
].isSelected() ) {
6210 return this.items
[ i
];
6217 * Get highlighted item.
6219 * @return {OO.ui.OptionWidget|null} Highlighted item, `null` if no item is highlighted
6221 OO
.ui
.SelectWidget
.prototype.getHighlightedItem = function () {
6224 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6225 if ( this.items
[ i
].isHighlighted() ) {
6226 return this.items
[ i
];
6233 * Toggle pressed state.
6235 * Press is a state that occurs when a user mouses down on an item, but
6236 * has not yet let go of the mouse. The item may appear selected, but it will not be selected
6237 * until the user releases the mouse.
6239 * @param {boolean} pressed An option is being pressed
6241 OO
.ui
.SelectWidget
.prototype.togglePressed = function ( pressed
) {
6242 if ( pressed
=== undefined ) {
6243 pressed
= !this.pressed
;
6245 if ( pressed
!== this.pressed
) {
6247 .toggleClass( 'oo-ui-selectWidget-pressed', pressed
)
6248 .toggleClass( 'oo-ui-selectWidget-depressed', !pressed
);
6249 this.pressed
= pressed
;
6254 * Highlight an option. If the `item` param is omitted, no options will be highlighted
6255 * and any existing highlight will be removed. The highlight is mutually exclusive.
6257 * @param {OO.ui.OptionWidget} [item] Item to highlight, omit for no highlight
6261 OO
.ui
.SelectWidget
.prototype.highlightItem = function ( item
) {
6262 var i
, len
, highlighted
,
6265 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6266 highlighted
= this.items
[ i
] === item
;
6267 if ( this.items
[ i
].isHighlighted() !== highlighted
) {
6268 this.items
[ i
].setHighlighted( highlighted
);
6273 this.emit( 'highlight', item
);
6280 * Fetch an item by its label.
6282 * @param {string} label Label of the item to select.
6283 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
6284 * @return {OO.ui.Element|null} Item with equivalent label, `null` if none exists
6286 OO
.ui
.SelectWidget
.prototype.getItemFromLabel = function ( label
, prefix
) {
6288 len
= this.items
.length
,
6289 filter
= this.getItemMatcher( label
, true );
6291 for ( i
= 0; i
< len
; i
++ ) {
6292 item
= this.items
[ i
];
6293 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
6300 filter
= this.getItemMatcher( label
, false );
6301 for ( i
= 0; i
< len
; i
++ ) {
6302 item
= this.items
[ i
];
6303 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
6319 * Programmatically select an option by its label. If the item does not exist,
6320 * all options will be deselected.
6322 * @param {string} [label] Label of the item to select.
6323 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
6327 OO
.ui
.SelectWidget
.prototype.selectItemByLabel = function ( label
, prefix
) {
6328 var itemFromLabel
= this.getItemFromLabel( label
, !!prefix
);
6329 if ( label
=== undefined || !itemFromLabel
) {
6330 return this.selectItem();
6332 return this.selectItem( itemFromLabel
);
6336 * Programmatically select an option by its data. If the `data` parameter is omitted,
6337 * or if the item does not exist, all options will be deselected.
6339 * @param {Object|string} [data] Value of the item to select, omit to deselect all
6343 OO
.ui
.SelectWidget
.prototype.selectItemByData = function ( data
) {
6344 var itemFromData
= this.getItemFromData( data
);
6345 if ( data
=== undefined || !itemFromData
) {
6346 return this.selectItem();
6348 return this.selectItem( itemFromData
);
6352 * Programmatically select an option by its reference. If the `item` parameter is omitted,
6353 * all options will be deselected.
6355 * @param {OO.ui.OptionWidget} [item] Item to select, omit to deselect all
6359 OO
.ui
.SelectWidget
.prototype.selectItem = function ( item
) {
6360 var i
, len
, selected
,
6363 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6364 selected
= this.items
[ i
] === item
;
6365 if ( this.items
[ i
].isSelected() !== selected
) {
6366 this.items
[ i
].setSelected( selected
);
6371 this.emit( 'select', item
);
6380 * Press is a state that occurs when a user mouses down on an item, but has not
6381 * yet let go of the mouse. The item may appear selected, but it will not be selected until the user
6382 * releases the mouse.
6384 * @param {OO.ui.OptionWidget} [item] Item to press, omit to depress all
6388 OO
.ui
.SelectWidget
.prototype.pressItem = function ( item
) {
6389 var i
, len
, pressed
,
6392 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
6393 pressed
= this.items
[ i
] === item
;
6394 if ( this.items
[ i
].isPressed() !== pressed
) {
6395 this.items
[ i
].setPressed( pressed
);
6400 this.emit( 'press', item
);
6409 * Note that ‘choose’ should never be modified programmatically. A user can choose
6410 * an option with the keyboard or mouse and it becomes selected. To select an item programmatically,
6411 * use the #selectItem method.
6413 * This method is identical to #selectItem, but may vary in subclasses that take additional action
6414 * when users choose an item with the keyboard or mouse.
6416 * @param {OO.ui.OptionWidget} item Item to choose
6420 OO
.ui
.SelectWidget
.prototype.chooseItem = function ( item
) {
6422 this.selectItem( item
);
6423 this.emit( 'choose', item
);
6430 * Get an option by its position relative to the specified item (or to the start of the option array,
6431 * if item is `null`). The direction in which to search through the option array is specified with a
6432 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
6433 * `null` if there are no options in the array.
6435 * @param {OO.ui.OptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
6436 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
6437 * @param {Function} [filter] Only consider items for which this function returns
6438 * true. Function takes an OO.ui.OptionWidget and returns a boolean.
6439 * @return {OO.ui.OptionWidget|null} Item at position, `null` if there are no items in the select
6441 OO
.ui
.SelectWidget
.prototype.getRelativeSelectableItem = function ( item
, direction
, filter
) {
6442 var currentIndex
, nextIndex
, i
,
6443 increase
= direction
> 0 ? 1 : -1,
6444 len
= this.items
.length
;
6446 if ( item
instanceof OO
.ui
.OptionWidget
) {
6447 currentIndex
= this.items
.indexOf( item
);
6448 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
6450 // If no item is selected and moving forward, start at the beginning.
6451 // If moving backward, start at the end.
6452 nextIndex
= direction
> 0 ? 0 : len
- 1;
6455 for ( i
= 0; i
< len
; i
++ ) {
6456 item
= this.items
[ nextIndex
];
6458 item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() &&
6459 ( !filter
|| filter( item
) )
6463 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
6469 * Get the next selectable item or `null` if there are no selectable items.
6470 * Disabled options and menu-section markers and breaks are not selectable.
6472 * @return {OO.ui.OptionWidget|null} Item, `null` if there aren't any selectable items
6474 OO
.ui
.SelectWidget
.prototype.getFirstSelectableItem = function () {
6475 return this.getRelativeSelectableItem( null, 1 );
6479 * Add an array of options to the select. Optionally, an index number can be used to
6480 * specify an insertion point.
6482 * @param {OO.ui.OptionWidget[]} items Items to add
6483 * @param {number} [index] Index to insert items after
6487 OO
.ui
.SelectWidget
.prototype.addItems = function ( items
, index
) {
6489 OO
.ui
.mixin
.GroupWidget
.prototype.addItems
.call( this, items
, index
);
6491 // Always provide an index, even if it was omitted
6492 this.emit( 'add', items
, index
=== undefined ? this.items
.length
- items
.length
- 1 : index
);
6498 * Remove the specified array of options from the select. Options will be detached
6499 * from the DOM, not removed, so they can be reused later. To remove all options from
6500 * the select, you may wish to use the #clearItems method instead.
6502 * @param {OO.ui.OptionWidget[]} items Items to remove
6506 OO
.ui
.SelectWidget
.prototype.removeItems = function ( items
) {
6509 // Deselect items being removed
6510 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
6512 if ( item
.isSelected() ) {
6513 this.selectItem( null );
6518 OO
.ui
.mixin
.GroupWidget
.prototype.removeItems
.call( this, items
);
6520 this.emit( 'remove', items
);
6526 * Clear all options from the select. Options will be detached from the DOM, not removed,
6527 * so that they can be reused later. To remove a subset of options from the select, use
6528 * the #removeItems method.
6533 OO
.ui
.SelectWidget
.prototype.clearItems = function () {
6534 var items
= this.items
.slice();
6537 OO
.ui
.mixin
.GroupWidget
.prototype.clearItems
.call( this );
6540 this.selectItem( null );
6542 this.emit( 'remove', items
);
6548 * DecoratedOptionWidgets are {@link OO.ui.OptionWidget options} that can be configured
6549 * with an {@link OO.ui.mixin.IconElement icon} and/or {@link OO.ui.mixin.IndicatorElement indicator}.
6550 * This class is used with OO.ui.SelectWidget to create a selection of mutually exclusive
6551 * options. For more information about options and selects, please see the
6552 * [OOjs UI documentation on MediaWiki][1].
6555 * // Decorated options in a select widget
6556 * var select = new OO.ui.SelectWidget( {
6558 * new OO.ui.DecoratedOptionWidget( {
6560 * label: 'Option with icon',
6563 * new OO.ui.DecoratedOptionWidget( {
6565 * label: 'Option with indicator',
6570 * $( 'body' ).append( select.$element );
6572 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6575 * @extends OO.ui.OptionWidget
6576 * @mixins OO.ui.mixin.IconElement
6577 * @mixins OO.ui.mixin.IndicatorElement
6580 * @param {Object} [config] Configuration options
6582 OO
.ui
.DecoratedOptionWidget
= function OoUiDecoratedOptionWidget( config
) {
6583 // Parent constructor
6584 OO
.ui
.DecoratedOptionWidget
.parent
.call( this, config
);
6586 // Mixin constructors
6587 OO
.ui
.mixin
.IconElement
.call( this, config
);
6588 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
6592 .addClass( 'oo-ui-decoratedOptionWidget' )
6593 .prepend( this.$icon
)
6594 .append( this.$indicator
);
6599 OO
.inheritClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.OptionWidget
);
6600 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IconElement
);
6601 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IndicatorElement
);
6604 * MenuOptionWidget is an option widget that looks like a menu item. The class is used with
6605 * OO.ui.MenuSelectWidget to create a menu of mutually exclusive options. Please see
6606 * the [OOjs UI documentation on MediaWiki] [1] for more information.
6608 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
6611 * @extends OO.ui.DecoratedOptionWidget
6614 * @param {Object} [config] Configuration options
6616 OO
.ui
.MenuOptionWidget
= function OoUiMenuOptionWidget( config
) {
6617 // Parent constructor
6618 OO
.ui
.MenuOptionWidget
.parent
.call( this, config
);
6622 .attr( 'role', 'menuitem' )
6623 .addClass( 'oo-ui-menuOptionWidget' );
6628 OO
.inheritClass( OO
.ui
.MenuOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
6630 /* Static Properties */
6636 OO
.ui
.MenuOptionWidget
.static.scrollIntoViewOnSelect
= true;
6639 * MenuSectionOptionWidgets are used inside {@link OO.ui.MenuSelectWidget menu select widgets} to group one or more related
6640 * {@link OO.ui.MenuOptionWidget menu options}. MenuSectionOptionWidgets cannot be highlighted or selected.
6643 * var myDropdown = new OO.ui.DropdownWidget( {
6646 * new OO.ui.MenuSectionOptionWidget( {
6649 * new OO.ui.MenuOptionWidget( {
6651 * label: 'Welsh Corgi'
6653 * new OO.ui.MenuOptionWidget( {
6655 * label: 'Standard Poodle'
6657 * new OO.ui.MenuSectionOptionWidget( {
6660 * new OO.ui.MenuOptionWidget( {
6667 * $( 'body' ).append( myDropdown.$element );
6670 * @extends OO.ui.DecoratedOptionWidget
6673 * @param {Object} [config] Configuration options
6675 OO
.ui
.MenuSectionOptionWidget
= function OoUiMenuSectionOptionWidget( config
) {
6676 // Parent constructor
6677 OO
.ui
.MenuSectionOptionWidget
.parent
.call( this, config
);
6680 this.$element
.addClass( 'oo-ui-menuSectionOptionWidget' )
6681 .attr( 'role', '' );
6686 OO
.inheritClass( OO
.ui
.MenuSectionOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
6688 /* Static Properties */
6694 OO
.ui
.MenuSectionOptionWidget
.static.selectable
= false;
6700 OO
.ui
.MenuSectionOptionWidget
.static.highlightable
= false;
6703 * MenuSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains options and
6704 * is used together with OO.ui.MenuOptionWidget. It is designed be used as part of another widget.
6705 * See {@link OO.ui.DropdownWidget DropdownWidget}, {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget},
6706 * and {@link OO.ui.mixin.LookupElement LookupElement} for examples of widgets that contain menus.
6707 * MenuSelectWidgets themselves are not instantiated directly, rather subclassed
6708 * and customized to be opened, closed, and displayed as needed.
6710 * By default, menus are clipped to the visible viewport and are not visible when a user presses the
6711 * mouse outside the menu.
6713 * Menus also have support for keyboard interaction:
6715 * - Enter/Return key: choose and select a menu option
6716 * - Up-arrow key: highlight the previous menu option
6717 * - Down-arrow key: highlight the next menu option
6718 * - Esc key: hide the menu
6720 * Unlike most widgets, MenuSelectWidget is initially hidden and must be shown by calling #toggle.
6722 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
6723 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6726 * @extends OO.ui.SelectWidget
6727 * @mixins OO.ui.mixin.ClippableElement
6730 * @param {Object} [config] Configuration options
6731 * @cfg {OO.ui.TextInputWidget} [input] Text input used to implement option highlighting for menu items that match
6732 * the text the user types. This config is used by {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget}
6733 * and {@link OO.ui.mixin.LookupElement LookupElement}
6734 * @cfg {jQuery} [$input] Text input used to implement option highlighting for menu items that match
6735 * the text the user types. This config is used by {@link OO.ui.CapsuleMultiselectWidget CapsuleMultiselectWidget}
6736 * @cfg {OO.ui.Widget} [widget] Widget associated with the menu's active state. If the user clicks the mouse
6737 * anywhere on the page outside of this widget, the menu is hidden. For example, if there is a button
6738 * that toggles the menu's visibility on click, the menu will be hidden then re-shown when the user clicks
6739 * that button, unless the button (or its parent widget) is passed in here.
6740 * @cfg {boolean} [autoHide=true] Hide the menu when the mouse is pressed outside the menu.
6741 * @cfg {jQuery} [$autoCloseIgnore] If these elements are clicked, don't auto-hide the menu.
6742 * @cfg {boolean} [hideOnChoose=true] Hide the menu when the user chooses an option.
6743 * @cfg {boolean} [filterFromInput=false] Filter the displayed options from the input
6744 * @cfg {boolean} [highlightOnFilter] Highlight the first result when filtering
6746 OO
.ui
.MenuSelectWidget
= function OoUiMenuSelectWidget( config
) {
6747 // Configuration initialization
6748 config
= config
|| {};
6750 // Parent constructor
6751 OO
.ui
.MenuSelectWidget
.parent
.call( this, config
);
6753 // Mixin constructors
6754 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, { $clippable
: this.$group
} ) );
6757 this.autoHide
= config
.autoHide
=== undefined || !!config
.autoHide
;
6758 this.hideOnChoose
= config
.hideOnChoose
=== undefined || !!config
.hideOnChoose
;
6759 this.filterFromInput
= !!config
.filterFromInput
;
6760 this.$input
= config
.$input
? config
.$input
: config
.input
? config
.input
.$input
: null;
6761 this.$widget
= config
.widget
? config
.widget
.$element
: null;
6762 this.$autoCloseIgnore
= config
.$autoCloseIgnore
|| $( [] );
6763 this.onDocumentMouseDownHandler
= this.onDocumentMouseDown
.bind( this );
6764 this.onInputEditHandler
= OO
.ui
.debounce( this.updateItemVisibility
.bind( this ), 100 );
6765 this.highlightOnFilter
= !!config
.highlightOnFilter
;
6769 .addClass( 'oo-ui-menuSelectWidget' )
6770 .attr( 'role', 'menu' );
6772 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
6773 // that reference properties not initialized at that time of parent class construction
6774 // TODO: Find a better way to handle post-constructor setup
6775 this.visible
= false;
6776 this.$element
.addClass( 'oo-ui-element-hidden' );
6781 OO
.inheritClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.SelectWidget
);
6782 OO
.mixinClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.mixin
.ClippableElement
);
6787 * Handles document mouse down events.
6790 * @param {MouseEvent} e Mouse down event
6792 OO
.ui
.MenuSelectWidget
.prototype.onDocumentMouseDown = function ( e
) {
6796 this.$element
.add( this.$widget
).add( this.$autoCloseIgnore
).get(),
6801 this.toggle( false );
6808 OO
.ui
.MenuSelectWidget
.prototype.onKeyDown = function ( e
) {
6809 var currentItem
= this.getHighlightedItem() || this.getSelectedItem();
6811 if ( !this.isDisabled() && this.isVisible() ) {
6812 switch ( e
.keyCode
) {
6813 case OO
.ui
.Keys
.LEFT
:
6814 case OO
.ui
.Keys
.RIGHT
:
6815 // Do nothing if a text field is associated, arrow keys will be handled natively
6816 if ( !this.$input
) {
6817 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
6820 case OO
.ui
.Keys
.ESCAPE
:
6821 case OO
.ui
.Keys
.TAB
:
6822 if ( currentItem
) {
6823 currentItem
.setHighlighted( false );
6825 this.toggle( false );
6826 // Don't prevent tabbing away, prevent defocusing
6827 if ( e
.keyCode
=== OO
.ui
.Keys
.ESCAPE
) {
6829 e
.stopPropagation();
6833 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
6840 * Update menu item visibility after input changes.
6844 OO
.ui
.MenuSelectWidget
.prototype.updateItemVisibility = function () {
6845 var i
, item
, visible
, section
, sectionEmpty
,
6846 firstItemFound
= false,
6848 len
= this.items
.length
,
6849 showAll
= !this.isVisible(),
6850 filter
= showAll
? null : this.getItemMatcher( this.$input
.val() );
6852 // Hide non-matching options, and also hide section headers if all options
6853 // in their section are hidden.
6854 for ( i
= 0; i
< len
; i
++ ) {
6855 item
= this.items
[ i
];
6856 if ( item
instanceof OO
.ui
.MenuSectionOptionWidget
) {
6858 // If the previous section was empty, hide its header
6859 section
.toggle( showAll
|| !sectionEmpty
);
6862 sectionEmpty
= true;
6863 } else if ( item
instanceof OO
.ui
.OptionWidget
) {
6864 visible
= showAll
|| filter( item
);
6865 anyVisible
= anyVisible
|| visible
;
6866 sectionEmpty
= sectionEmpty
&& !visible
;
6867 item
.toggle( visible
);
6868 if ( this.highlightOnFilter
&& visible
&& !firstItemFound
) {
6869 // Highlight the first item in the list
6870 this.highlightItem( item
);
6871 firstItemFound
= true;
6875 // Process the final section
6877 section
.toggle( showAll
|| !sectionEmpty
);
6880 this.$element
.toggleClass( 'oo-ui-menuSelectWidget-invisible', !anyVisible
);
6882 // Reevaluate clipping
6889 OO
.ui
.MenuSelectWidget
.prototype.bindKeyDownListener = function () {
6890 if ( this.$input
) {
6891 this.$input
.on( 'keydown', this.onKeyDownHandler
);
6893 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyDownListener
.call( this );
6900 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyDownListener = function () {
6901 if ( this.$input
) {
6902 this.$input
.off( 'keydown', this.onKeyDownHandler
);
6904 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyDownListener
.call( this );
6911 OO
.ui
.MenuSelectWidget
.prototype.bindKeyPressListener = function () {
6912 if ( this.$input
) {
6913 if ( this.filterFromInput
) {
6914 this.$input
.on( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
6917 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyPressListener
.call( this );
6924 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyPressListener = function () {
6925 if ( this.$input
) {
6926 if ( this.filterFromInput
) {
6927 this.$input
.off( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
6928 this.updateItemVisibility();
6931 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyPressListener
.call( this );
6938 * When a user chooses an item, the menu is closed, unless the hideOnChoose config option is set to false.
6940 * Note that ‘choose’ should never be modified programmatically. A user can choose an option with the keyboard
6941 * or mouse and it becomes selected. To select an item programmatically, use the #selectItem method.
6943 * @param {OO.ui.OptionWidget} item Item to choose
6946 OO
.ui
.MenuSelectWidget
.prototype.chooseItem = function ( item
) {
6947 OO
.ui
.MenuSelectWidget
.parent
.prototype.chooseItem
.call( this, item
);
6948 if ( this.hideOnChoose
) {
6949 this.toggle( false );
6957 OO
.ui
.MenuSelectWidget
.prototype.addItems = function ( items
, index
) {
6959 OO
.ui
.MenuSelectWidget
.parent
.prototype.addItems
.call( this, items
, index
);
6961 // Reevaluate clipping
6970 OO
.ui
.MenuSelectWidget
.prototype.removeItems = function ( items
) {
6972 OO
.ui
.MenuSelectWidget
.parent
.prototype.removeItems
.call( this, items
);
6974 // Reevaluate clipping
6983 OO
.ui
.MenuSelectWidget
.prototype.clearItems = function () {
6985 OO
.ui
.MenuSelectWidget
.parent
.prototype.clearItems
.call( this );
6987 // Reevaluate clipping
6994 * Toggle visibility of the menu. The menu is initially hidden and must be shown by calling
6995 * `.toggle( true )` after its #$element is attached to the DOM.
6997 * Do not show the menu while it is not attached to the DOM. The calculations required to display
6998 * it in the right place and with the right dimensions only work correctly while it is attached.
6999 * Side-effects may include broken interface and exceptions being thrown. This wasn't always
7000 * strictly enforced, so currently it only generates a warning in the browser console.
7004 OO
.ui
.MenuSelectWidget
.prototype.toggle = function ( visible
) {
7007 visible
= ( visible
=== undefined ? !this.visible
: !!visible
) && !!this.items
.length
;
7008 change
= visible
!== this.isVisible();
7010 if ( visible
&& !this.warnedUnattached
&& !this.isElementAttached() ) {
7011 OO
.ui
.warnDeprecation( 'MenuSelectWidget#toggle: Before calling this method, the menu must be attached to the DOM.' );
7012 this.warnedUnattached
= true;
7016 OO
.ui
.MenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
7020 this.bindKeyDownListener();
7021 this.bindKeyPressListener();
7023 this.toggleClipping( true );
7025 if ( this.getSelectedItem() ) {
7026 this.getSelectedItem().scrollElementIntoView( { duration
: 0 } );
7030 if ( this.autoHide
) {
7031 this.getElementDocument().addEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
7034 this.unbindKeyDownListener();
7035 this.unbindKeyPressListener();
7036 this.getElementDocument().removeEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
7037 this.toggleClipping( false );
7045 * DropdownWidgets are not menus themselves, rather they contain a menu of options created with
7046 * OO.ui.MenuOptionWidget. The DropdownWidget takes care of opening and displaying the menu so that
7047 * users can interact with it.
7049 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
7050 * OO.ui.DropdownInputWidget instead.
7053 * // Example: A DropdownWidget with a menu that contains three options
7054 * var dropDown = new OO.ui.DropdownWidget( {
7055 * label: 'Dropdown menu: Select a menu option',
7058 * new OO.ui.MenuOptionWidget( {
7062 * new OO.ui.MenuOptionWidget( {
7066 * new OO.ui.MenuOptionWidget( {
7074 * $( 'body' ).append( dropDown.$element );
7076 * dropDown.getMenu().selectItemByData( 'b' );
7078 * dropDown.getMenu().getSelectedItem().getData(); // returns 'b'
7080 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
7082 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
7085 * @extends OO.ui.Widget
7086 * @mixins OO.ui.mixin.IconElement
7087 * @mixins OO.ui.mixin.IndicatorElement
7088 * @mixins OO.ui.mixin.LabelElement
7089 * @mixins OO.ui.mixin.TitledElement
7090 * @mixins OO.ui.mixin.TabIndexedElement
7093 * @param {Object} [config] Configuration options
7094 * @cfg {Object} [menu] Configuration options to pass to {@link OO.ui.FloatingMenuSelectWidget menu select widget}
7095 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
7096 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
7097 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
7099 OO
.ui
.DropdownWidget
= function OoUiDropdownWidget( config
) {
7100 // Configuration initialization
7101 config
= $.extend( { indicator
: 'down' }, config
);
7103 // Parent constructor
7104 OO
.ui
.DropdownWidget
.parent
.call( this, config
);
7106 // Properties (must be set before TabIndexedElement constructor call)
7107 this.$handle
= this.$( '<span>' );
7108 this.$overlay
= config
.$overlay
|| this.$element
;
7110 // Mixin constructors
7111 OO
.ui
.mixin
.IconElement
.call( this, config
);
7112 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
7113 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7114 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
7115 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$handle
} ) );
7118 this.menu
= new OO
.ui
.FloatingMenuSelectWidget( $.extend( {
7120 $container
: this.$element
7125 click
: this.onClick
.bind( this ),
7126 keydown
: this.onKeyDown
.bind( this ),
7127 // Hack? Handle type-to-search when menu is not expanded and not handling its own events
7128 keypress
: this.menu
.onKeyPressHandler
,
7129 blur
: this.menu
.clearKeyPressBuffer
.bind( this.menu
)
7131 this.menu
.connect( this, {
7132 select
: 'onMenuSelect',
7133 toggle
: 'onMenuToggle'
7138 .addClass( 'oo-ui-dropdownWidget-handle' )
7139 .append( this.$icon
, this.$label
, this.$indicator
);
7141 .addClass( 'oo-ui-dropdownWidget' )
7142 .append( this.$handle
);
7143 this.$overlay
.append( this.menu
.$element
);
7148 OO
.inheritClass( OO
.ui
.DropdownWidget
, OO
.ui
.Widget
);
7149 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IconElement
);
7150 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IndicatorElement
);
7151 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.LabelElement
);
7152 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TitledElement
);
7153 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TabIndexedElement
);
7160 * @return {OO.ui.MenuSelectWidget} Menu of widget
7162 OO
.ui
.DropdownWidget
.prototype.getMenu = function () {
7167 * Handles menu select events.
7170 * @param {OO.ui.MenuOptionWidget} item Selected menu item
7172 OO
.ui
.DropdownWidget
.prototype.onMenuSelect = function ( item
) {
7176 this.setLabel( null );
7180 selectedLabel
= item
.getLabel();
7182 // If the label is a DOM element, clone it, because setLabel will append() it
7183 if ( selectedLabel
instanceof jQuery
) {
7184 selectedLabel
= selectedLabel
.clone();
7187 this.setLabel( selectedLabel
);
7191 * Handle menu toggle events.
7194 * @param {boolean} isVisible Menu toggle event
7196 OO
.ui
.DropdownWidget
.prototype.onMenuToggle = function ( isVisible
) {
7197 this.$element
.toggleClass( 'oo-ui-dropdownWidget-open', isVisible
);
7201 * Handle mouse click events.
7204 * @param {jQuery.Event} e Mouse click event
7206 OO
.ui
.DropdownWidget
.prototype.onClick = function ( e
) {
7207 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
7214 * Handle key down events.
7217 * @param {jQuery.Event} e Key down event
7219 OO
.ui
.DropdownWidget
.prototype.onKeyDown = function ( e
) {
7221 !this.isDisabled() &&
7223 e
.which
=== OO
.ui
.Keys
.ENTER
||
7225 !this.menu
.isVisible() &&
7227 e
.which
=== OO
.ui
.Keys
.SPACE
||
7228 e
.which
=== OO
.ui
.Keys
.UP
||
7229 e
.which
=== OO
.ui
.Keys
.DOWN
7240 * RadioOptionWidget is an option widget that looks like a radio button.
7241 * The class is used with OO.ui.RadioSelectWidget to create a selection of radio options.
7242 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
7244 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option
7247 * @extends OO.ui.OptionWidget
7250 * @param {Object} [config] Configuration options
7252 OO
.ui
.RadioOptionWidget
= function OoUiRadioOptionWidget( config
) {
7253 // Configuration initialization
7254 config
= config
|| {};
7256 // Properties (must be done before parent constructor which calls #setDisabled)
7257 this.radio
= new OO
.ui
.RadioInputWidget( { value
: config
.data
, tabIndex
: -1 } );
7259 // Parent constructor
7260 OO
.ui
.RadioOptionWidget
.parent
.call( this, config
);
7263 // Remove implicit role, we're handling it ourselves
7264 this.radio
.$input
.attr( 'role', 'presentation' );
7266 .addClass( 'oo-ui-radioOptionWidget' )
7267 .attr( 'role', 'radio' )
7268 .attr( 'aria-checked', 'false' )
7269 .removeAttr( 'aria-selected' )
7270 .prepend( this.radio
.$element
);
7275 OO
.inheritClass( OO
.ui
.RadioOptionWidget
, OO
.ui
.OptionWidget
);
7277 /* Static Properties */
7283 OO
.ui
.RadioOptionWidget
.static.highlightable
= false;
7289 OO
.ui
.RadioOptionWidget
.static.scrollIntoViewOnSelect
= true;
7295 OO
.ui
.RadioOptionWidget
.static.pressable
= false;
7301 OO
.ui
.RadioOptionWidget
.static.tagName
= 'label';
7308 OO
.ui
.RadioOptionWidget
.prototype.setSelected = function ( state
) {
7309 OO
.ui
.RadioOptionWidget
.parent
.prototype.setSelected
.call( this, state
);
7311 this.radio
.setSelected( state
);
7313 .attr( 'aria-checked', state
.toString() )
7314 .removeAttr( 'aria-selected' );
7322 OO
.ui
.RadioOptionWidget
.prototype.setDisabled = function ( disabled
) {
7323 OO
.ui
.RadioOptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
7325 this.radio
.setDisabled( this.isDisabled() );
7331 * RadioSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains radio
7332 * options and is used together with OO.ui.RadioOptionWidget. The RadioSelectWidget provides
7333 * an interface for adding, removing and selecting options.
7334 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
7336 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
7337 * OO.ui.RadioSelectInputWidget instead.
7340 * // A RadioSelectWidget with RadioOptions.
7341 * var option1 = new OO.ui.RadioOptionWidget( {
7343 * label: 'Selected radio option'
7346 * var option2 = new OO.ui.RadioOptionWidget( {
7348 * label: 'Unselected radio option'
7351 * var radioSelect=new OO.ui.RadioSelectWidget( {
7352 * items: [ option1, option2 ]
7355 * // Select 'option 1' using the RadioSelectWidget's selectItem() method.
7356 * radioSelect.selectItem( option1 );
7358 * $( 'body' ).append( radioSelect.$element );
7360 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
7364 * @extends OO.ui.SelectWidget
7365 * @mixins OO.ui.mixin.TabIndexedElement
7368 * @param {Object} [config] Configuration options
7370 OO
.ui
.RadioSelectWidget
= function OoUiRadioSelectWidget( config
) {
7371 // Parent constructor
7372 OO
.ui
.RadioSelectWidget
.parent
.call( this, config
);
7374 // Mixin constructors
7375 OO
.ui
.mixin
.TabIndexedElement
.call( this, config
);
7379 focus
: this.bindKeyDownListener
.bind( this ),
7380 blur
: this.unbindKeyDownListener
.bind( this )
7385 .addClass( 'oo-ui-radioSelectWidget' )
7386 .attr( 'role', 'radiogroup' );
7391 OO
.inheritClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.SelectWidget
);
7392 OO
.mixinClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.mixin
.TabIndexedElement
);
7395 * MultioptionWidgets are special elements that can be selected and configured with data. The
7396 * data is often unique for each option, but it does not have to be. MultioptionWidgets are used
7397 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
7398 * and examples, please see the [OOjs UI documentation on MediaWiki][1].
7400 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Multioptions
7403 * @extends OO.ui.Widget
7404 * @mixins OO.ui.mixin.ItemWidget
7405 * @mixins OO.ui.mixin.LabelElement
7408 * @param {Object} [config] Configuration options
7409 * @cfg {boolean} [selected=false] Whether the option is initially selected
7411 OO
.ui
.MultioptionWidget
= function OoUiMultioptionWidget( config
) {
7412 // Configuration initialization
7413 config
= config
|| {};
7415 // Parent constructor
7416 OO
.ui
.MultioptionWidget
.parent
.call( this, config
);
7418 // Mixin constructors
7419 OO
.ui
.mixin
.ItemWidget
.call( this );
7420 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7423 this.selected
= null;
7427 .addClass( 'oo-ui-multioptionWidget' )
7428 .append( this.$label
);
7429 this.setSelected( config
.selected
);
7434 OO
.inheritClass( OO
.ui
.MultioptionWidget
, OO
.ui
.Widget
);
7435 OO
.mixinClass( OO
.ui
.MultioptionWidget
, OO
.ui
.mixin
.ItemWidget
);
7436 OO
.mixinClass( OO
.ui
.MultioptionWidget
, OO
.ui
.mixin
.LabelElement
);
7443 * A change event is emitted when the selected state of the option changes.
7445 * @param {boolean} selected Whether the option is now selected
7451 * Check if the option is selected.
7453 * @return {boolean} Item is selected
7455 OO
.ui
.MultioptionWidget
.prototype.isSelected = function () {
7456 return this.selected
;
7460 * Set the option’s selected state. In general, all modifications to the selection
7461 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
7462 * method instead of this method.
7464 * @param {boolean} [state=false] Select option
7467 OO
.ui
.MultioptionWidget
.prototype.setSelected = function ( state
) {
7469 if ( this.selected
!== state
) {
7470 this.selected
= state
;
7471 this.emit( 'change', state
);
7472 this.$element
.toggleClass( 'oo-ui-multioptionWidget-selected', state
);
7478 * MultiselectWidget allows selecting multiple options from a list.
7480 * For more information about menus and options, please see the [OOjs UI documentation on MediaWiki][1].
7482 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
7486 * @extends OO.ui.Widget
7487 * @mixins OO.ui.mixin.GroupWidget
7490 * @param {Object} [config] Configuration options
7491 * @cfg {OO.ui.MultioptionWidget[]} [items] An array of options to add to the multiselect.
7493 OO
.ui
.MultiselectWidget
= function OoUiMultiselectWidget( config
) {
7494 // Parent constructor
7495 OO
.ui
.MultiselectWidget
.parent
.call( this, config
);
7497 // Configuration initialization
7498 config
= config
|| {};
7500 // Mixin constructors
7501 OO
.ui
.mixin
.GroupWidget
.call( this, config
);
7504 this.aggregate( { change
: 'select' } );
7505 // This is mostly for compatibility with CapsuleMultiselectWidget... normally, 'change' is emitted
7506 // by GroupElement only when items are added/removed
7507 this.connect( this, { select
: [ 'emit', 'change' ] } );
7510 if ( config
.items
) {
7511 this.addItems( config
.items
);
7513 this.$group
.addClass( 'oo-ui-multiselectWidget-group' );
7514 this.$element
.addClass( 'oo-ui-multiselectWidget' )
7515 .append( this.$group
);
7520 OO
.inheritClass( OO
.ui
.MultiselectWidget
, OO
.ui
.Widget
);
7521 OO
.mixinClass( OO
.ui
.MultiselectWidget
, OO
.ui
.mixin
.GroupWidget
);
7528 * A change event is emitted when the set of items changes, or an item is selected or deselected.
7534 * A select event is emitted when an item is selected or deselected.
7540 * Get options that are selected.
7542 * @return {OO.ui.MultioptionWidget[]} Selected options
7544 OO
.ui
.MultiselectWidget
.prototype.getSelectedItems = function () {
7545 return this.items
.filter( function ( item
) {
7546 return item
.isSelected();
7551 * Get the data of options that are selected.
7553 * @return {Object[]|string[]} Values of selected options
7555 OO
.ui
.MultiselectWidget
.prototype.getSelectedItemsData = function () {
7556 return this.getSelectedItems().map( function ( item
) {
7562 * Select options by reference. Options not mentioned in the `items` array will be deselected.
7564 * @param {OO.ui.MultioptionWidget[]} items Items to select
7567 OO
.ui
.MultiselectWidget
.prototype.selectItems = function ( items
) {
7568 this.items
.forEach( function ( item
) {
7569 var selected
= items
.indexOf( item
) !== -1;
7570 item
.setSelected( selected
);
7576 * Select items by their data. Options not mentioned in the `datas` array will be deselected.
7578 * @param {Object[]|string[]} datas Values of items to select
7581 OO
.ui
.MultiselectWidget
.prototype.selectItemsByData = function ( datas
) {
7584 items
= datas
.map( function ( data
) {
7585 return widget
.getItemFromData( data
);
7587 this.selectItems( items
);
7592 * CheckboxMultioptionWidget is an option widget that looks like a checkbox.
7593 * The class is used with OO.ui.CheckboxMultiselectWidget to create a selection of checkbox options.
7594 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
7596 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option
7599 * @extends OO.ui.MultioptionWidget
7602 * @param {Object} [config] Configuration options
7604 OO
.ui
.CheckboxMultioptionWidget
= function OoUiCheckboxMultioptionWidget( config
) {
7605 // Configuration initialization
7606 config
= config
|| {};
7608 // Properties (must be done before parent constructor which calls #setDisabled)
7609 this.checkbox
= new OO
.ui
.CheckboxInputWidget();
7611 // Parent constructor
7612 OO
.ui
.CheckboxMultioptionWidget
.parent
.call( this, config
);
7615 this.checkbox
.on( 'change', this.onCheckboxChange
.bind( this ) );
7616 this.$element
.on( 'keydown', this.onKeyDown
.bind( this ) );
7620 .addClass( 'oo-ui-checkboxMultioptionWidget' )
7621 .prepend( this.checkbox
.$element
);
7626 OO
.inheritClass( OO
.ui
.CheckboxMultioptionWidget
, OO
.ui
.MultioptionWidget
);
7628 /* Static Properties */
7634 OO
.ui
.CheckboxMultioptionWidget
.static.tagName
= 'label';
7639 * Handle checkbox selected state change.
7643 OO
.ui
.CheckboxMultioptionWidget
.prototype.onCheckboxChange = function () {
7644 this.setSelected( this.checkbox
.isSelected() );
7650 OO
.ui
.CheckboxMultioptionWidget
.prototype.setSelected = function ( state
) {
7651 OO
.ui
.CheckboxMultioptionWidget
.parent
.prototype.setSelected
.call( this, state
);
7652 this.checkbox
.setSelected( state
);
7659 OO
.ui
.CheckboxMultioptionWidget
.prototype.setDisabled = function ( disabled
) {
7660 OO
.ui
.CheckboxMultioptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
7661 this.checkbox
.setDisabled( this.isDisabled() );
7668 OO
.ui
.CheckboxMultioptionWidget
.prototype.focus = function () {
7669 this.checkbox
.focus();
7673 * Handle key down events.
7676 * @param {jQuery.Event} e
7678 OO
.ui
.CheckboxMultioptionWidget
.prototype.onKeyDown = function ( e
) {
7680 element
= this.getElementGroup(),
7683 if ( e
.keyCode
=== OO
.ui
.Keys
.LEFT
|| e
.keyCode
=== OO
.ui
.Keys
.UP
) {
7684 nextItem
= element
.getRelativeFocusableItem( this, -1 );
7685 } else if ( e
.keyCode
=== OO
.ui
.Keys
.RIGHT
|| e
.keyCode
=== OO
.ui
.Keys
.DOWN
) {
7686 nextItem
= element
.getRelativeFocusableItem( this, 1 );
7696 * CheckboxMultiselectWidget is a {@link OO.ui.MultiselectWidget multiselect widget} that contains
7697 * checkboxes and is used together with OO.ui.CheckboxMultioptionWidget. The
7698 * CheckboxMultiselectWidget provides an interface for adding, removing and selecting options.
7699 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
7701 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
7702 * OO.ui.CheckboxMultiselectInputWidget instead.
7705 * // A CheckboxMultiselectWidget with CheckboxMultioptions.
7706 * var option1 = new OO.ui.CheckboxMultioptionWidget( {
7709 * label: 'Selected checkbox'
7712 * var option2 = new OO.ui.CheckboxMultioptionWidget( {
7714 * label: 'Unselected checkbox'
7717 * var multiselect=new OO.ui.CheckboxMultiselectWidget( {
7718 * items: [ option1, option2 ]
7721 * $( 'body' ).append( multiselect.$element );
7723 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
7726 * @extends OO.ui.MultiselectWidget
7729 * @param {Object} [config] Configuration options
7731 OO
.ui
.CheckboxMultiselectWidget
= function OoUiCheckboxMultiselectWidget( config
) {
7732 // Parent constructor
7733 OO
.ui
.CheckboxMultiselectWidget
.parent
.call( this, config
);
7736 this.$lastClicked
= null;
7739 this.$group
.on( 'click', this.onClick
.bind( this ) );
7743 .addClass( 'oo-ui-checkboxMultiselectWidget' );
7748 OO
.inheritClass( OO
.ui
.CheckboxMultiselectWidget
, OO
.ui
.MultiselectWidget
);
7753 * Get an option by its position relative to the specified item (or to the start of the option array,
7754 * if item is `null`). The direction in which to search through the option array is specified with a
7755 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
7756 * `null` if there are no options in the array.
7758 * @param {OO.ui.CheckboxMultioptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
7759 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
7760 * @return {OO.ui.CheckboxMultioptionWidget|null} Item at position, `null` if there are no items in the select
7762 OO
.ui
.CheckboxMultiselectWidget
.prototype.getRelativeFocusableItem = function ( item
, direction
) {
7763 var currentIndex
, nextIndex
, i
,
7764 increase
= direction
> 0 ? 1 : -1,
7765 len
= this.items
.length
;
7768 currentIndex
= this.items
.indexOf( item
);
7769 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
7771 // If no item is selected and moving forward, start at the beginning.
7772 // If moving backward, start at the end.
7773 nextIndex
= direction
> 0 ? 0 : len
- 1;
7776 for ( i
= 0; i
< len
; i
++ ) {
7777 item
= this.items
[ nextIndex
];
7778 if ( item
&& !item
.isDisabled() ) {
7781 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
7787 * Handle click events on checkboxes.
7789 * @param {jQuery.Event} e
7791 OO
.ui
.CheckboxMultiselectWidget
.prototype.onClick = function ( e
) {
7792 var $options
, lastClickedIndex
, nowClickedIndex
, i
, direction
, wasSelected
, items
,
7793 $lastClicked
= this.$lastClicked
,
7794 $nowClicked
= $( e
.target
).closest( '.oo-ui-checkboxMultioptionWidget' )
7795 .not( '.oo-ui-widget-disabled' );
7797 // Allow selecting multiple options at once by Shift-clicking them
7798 if ( $lastClicked
&& $nowClicked
.length
&& e
.shiftKey
) {
7799 $options
= this.$group
.find( '.oo-ui-checkboxMultioptionWidget' );
7800 lastClickedIndex
= $options
.index( $lastClicked
);
7801 nowClickedIndex
= $options
.index( $nowClicked
);
7802 // If it's the same item, either the user is being silly, or it's a fake event generated by the
7803 // browser. In either case we don't need custom handling.
7804 if ( nowClickedIndex
!== lastClickedIndex
) {
7806 wasSelected
= items
[ nowClickedIndex
].isSelected();
7807 direction
= nowClickedIndex
> lastClickedIndex
? 1 : -1;
7809 // This depends on the DOM order of the items and the order of the .items array being the same.
7810 for ( i
= lastClickedIndex
; i
!== nowClickedIndex
; i
+= direction
) {
7811 if ( !items
[ i
].isDisabled() ) {
7812 items
[ i
].setSelected( !wasSelected
);
7815 // For the now-clicked element, use immediate timeout to allow the browser to do its own
7816 // handling first, then set our value. The order in which events happen is different for
7817 // clicks on the <input> and on the <label> and there are additional fake clicks fired for
7818 // non-click actions that change the checkboxes.
7820 setTimeout( function () {
7821 if ( !items
[ nowClickedIndex
].isDisabled() ) {
7822 items
[ nowClickedIndex
].setSelected( !wasSelected
);
7828 if ( $nowClicked
.length
) {
7829 this.$lastClicked
= $nowClicked
;
7834 * FloatingMenuSelectWidget is a menu that will stick under a specified
7835 * container, even when it is inserted elsewhere in the document (for example,
7836 * in a OO.ui.Window's $overlay). This is sometimes necessary to prevent the
7837 * menu from being clipped too aggresively.
7839 * The menu's position is automatically calculated and maintained when the menu
7840 * is toggled or the window is resized.
7842 * See OO.ui.ComboBoxInputWidget for an example of a widget that uses this class.
7845 * @extends OO.ui.MenuSelectWidget
7846 * @mixins OO.ui.mixin.FloatableElement
7849 * @param {OO.ui.Widget} [inputWidget] Widget to provide the menu for.
7850 * Deprecated, omit this parameter and specify `$container` instead.
7851 * @param {Object} [config] Configuration options
7852 * @cfg {jQuery} [$container=inputWidget.$element] Element to render menu under
7853 * @cfg {number} [width] Width of the menu
7855 OO
.ui
.FloatingMenuSelectWidget
= function OoUiFloatingMenuSelectWidget( inputWidget
, config
) {
7856 // Allow 'inputWidget' parameter and config for backwards compatibility
7857 if ( OO
.isPlainObject( inputWidget
) && config
=== undefined ) {
7858 config
= inputWidget
;
7859 inputWidget
= config
.inputWidget
;
7862 // Configuration initialization
7863 config
= config
|| {};
7865 this.width
= config
.width
;
7867 // Parent constructor
7868 OO
.ui
.FloatingMenuSelectWidget
.parent
.call( this, config
);
7870 // Properties (must be set before mixin constructors)
7871 this.inputWidget
= inputWidget
; // For backwards compatibility
7872 this.$container
= config
.$container
|| this.inputWidget
.$element
;
7874 // Mixins constructors
7875 OO
.ui
.mixin
.FloatableElement
.call( this, $.extend( {}, config
, { $floatableContainer
: this.$container
} ) );
7878 this.$element
.addClass( 'oo-ui-floatingMenuSelectWidget' );
7879 // For backwards compatibility
7880 this.$element
.addClass( 'oo-ui-textInputMenuSelectWidget' );
7885 OO
.inheritClass( OO
.ui
.FloatingMenuSelectWidget
, OO
.ui
.MenuSelectWidget
);
7886 OO
.mixinClass( OO
.ui
.FloatingMenuSelectWidget
, OO
.ui
.mixin
.FloatableElement
);
7893 * The menu is ready: it is visible and has been positioned and clipped.
7902 OO
.ui
.FloatingMenuSelectWidget
.prototype.toggle = function ( visible
) {
7904 visible
= visible
=== undefined ? !this.isVisible() : !!visible
;
7905 change
= visible
!== this.isVisible();
7907 if ( change
&& visible
) {
7908 // Make sure the width is set before the parent method runs.
7909 this.setIdealSize( this.width
|| this.$container
.width() );
7913 // This will call this.clip(), which is nonsensical since we're not positioned yet...
7914 OO
.ui
.FloatingMenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
7917 this.togglePositioning( this.isVisible() );
7919 this.emit( 'ready' );
7927 * Progress bars visually display the status of an operation, such as a download,
7928 * and can be either determinate or indeterminate:
7930 * - **determinate** process bars show the percent of an operation that is complete.
7932 * - **indeterminate** process bars use a visual display of motion to indicate that an operation
7933 * is taking place. Because the extent of an indeterminate operation is unknown, the bar does
7934 * not use percentages.
7936 * The value of the `progress` configuration determines whether the bar is determinate or indeterminate.
7939 * // Examples of determinate and indeterminate progress bars.
7940 * var progressBar1 = new OO.ui.ProgressBarWidget( {
7943 * var progressBar2 = new OO.ui.ProgressBarWidget();
7945 * // Create a FieldsetLayout to layout progress bars
7946 * var fieldset = new OO.ui.FieldsetLayout;
7947 * fieldset.addItems( [
7948 * new OO.ui.FieldLayout( progressBar1, {label: 'Determinate', align: 'top'}),
7949 * new OO.ui.FieldLayout( progressBar2, {label: 'Indeterminate', align: 'top'})
7951 * $( 'body' ).append( fieldset.$element );
7954 * @extends OO.ui.Widget
7957 * @param {Object} [config] Configuration options
7958 * @cfg {number|boolean} [progress=false] The type of progress bar (determinate or indeterminate).
7959 * To create a determinate progress bar, specify a number that reflects the initial percent complete.
7960 * By default, the progress bar is indeterminate.
7962 OO
.ui
.ProgressBarWidget
= function OoUiProgressBarWidget( config
) {
7963 // Configuration initialization
7964 config
= config
|| {};
7966 // Parent constructor
7967 OO
.ui
.ProgressBarWidget
.parent
.call( this, config
);
7970 this.$bar
= $( '<div>' );
7971 this.progress
= null;
7974 this.setProgress( config
.progress
!== undefined ? config
.progress
: false );
7975 this.$bar
.addClass( 'oo-ui-progressBarWidget-bar' );
7978 role
: 'progressbar',
7980 'aria-valuemax': 100
7982 .addClass( 'oo-ui-progressBarWidget' )
7983 .append( this.$bar
);
7988 OO
.inheritClass( OO
.ui
.ProgressBarWidget
, OO
.ui
.Widget
);
7990 /* Static Properties */
7996 OO
.ui
.ProgressBarWidget
.static.tagName
= 'div';
8001 * Get the percent of the progress that has been completed. Indeterminate progresses will return `false`.
8003 * @return {number|boolean} Progress percent
8005 OO
.ui
.ProgressBarWidget
.prototype.getProgress = function () {
8006 return this.progress
;
8010 * Set the percent of the process completed or `false` for an indeterminate process.
8012 * @param {number|boolean} progress Progress percent or `false` for indeterminate
8014 OO
.ui
.ProgressBarWidget
.prototype.setProgress = function ( progress
) {
8015 this.progress
= progress
;
8017 if ( progress
!== false ) {
8018 this.$bar
.css( 'width', this.progress
+ '%' );
8019 this.$element
.attr( 'aria-valuenow', this.progress
);
8021 this.$bar
.css( 'width', '' );
8022 this.$element
.removeAttr( 'aria-valuenow' );
8024 this.$element
.toggleClass( 'oo-ui-progressBarWidget-indeterminate', progress
=== false );
8028 * InputWidget is the base class for all input widgets, which
8029 * include {@link OO.ui.TextInputWidget text inputs}, {@link OO.ui.CheckboxInputWidget checkbox inputs},
8030 * {@link OO.ui.RadioInputWidget radio inputs}, and {@link OO.ui.ButtonInputWidget button inputs}.
8031 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
8033 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8037 * @extends OO.ui.Widget
8038 * @mixins OO.ui.mixin.FlaggedElement
8039 * @mixins OO.ui.mixin.TabIndexedElement
8040 * @mixins OO.ui.mixin.TitledElement
8041 * @mixins OO.ui.mixin.AccessKeyedElement
8044 * @param {Object} [config] Configuration options
8045 * @cfg {string} [name=''] The value of the input’s HTML `name` attribute.
8046 * @cfg {string} [value=''] The value of the input.
8047 * @cfg {string} [dir] The directionality of the input (ltr/rtl).
8048 * @cfg {Function} [inputFilter] The name of an input filter function. Input filters modify the value of an input
8049 * before it is accepted.
8051 OO
.ui
.InputWidget
= function OoUiInputWidget( config
) {
8052 // Configuration initialization
8053 config
= config
|| {};
8055 // Parent constructor
8056 OO
.ui
.InputWidget
.parent
.call( this, config
);
8059 // See #reusePreInfuseDOM about config.$input
8060 this.$input
= config
.$input
|| this.getInputElement( config
);
8062 this.inputFilter
= config
.inputFilter
;
8064 // Mixin constructors
8065 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
8066 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$input
} ) );
8067 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
8068 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$input
} ) );
8071 this.$input
.on( 'keydown mouseup cut paste change input select', this.onEdit
.bind( this ) );
8075 .addClass( 'oo-ui-inputWidget-input' )
8076 .attr( 'name', config
.name
)
8077 .prop( 'disabled', this.isDisabled() );
8079 .addClass( 'oo-ui-inputWidget' )
8080 .append( this.$input
);
8081 this.setValue( config
.value
);
8083 this.setDir( config
.dir
);
8089 OO
.inheritClass( OO
.ui
.InputWidget
, OO
.ui
.Widget
);
8090 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.FlaggedElement
);
8091 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TabIndexedElement
);
8092 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TitledElement
);
8093 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
8095 /* Static Properties */
8101 OO
.ui
.InputWidget
.static.supportsSimpleLabel
= true;
8103 /* Static Methods */
8108 OO
.ui
.InputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
8109 config
= OO
.ui
.InputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
8110 // Reusing $input lets browsers preserve inputted values across page reloads (T114134)
8111 config
.$input
= $( node
).find( '.oo-ui-inputWidget-input' );
8118 OO
.ui
.InputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8119 var state
= OO
.ui
.InputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8120 if ( config
.$input
&& config
.$input
.length
) {
8121 state
.value
= config
.$input
.val();
8122 // Might be better in TabIndexedElement, but it's awkward to do there because mixins are awkward
8123 state
.focus
= config
.$input
.is( ':focus' );
8133 * A change event is emitted when the value of the input changes.
8135 * @param {string} value
8141 * Get input element.
8143 * Subclasses of OO.ui.InputWidget use the `config` parameter to produce different elements in
8144 * different circumstances. The element must have a `value` property (like form elements).
8147 * @param {Object} config Configuration options
8148 * @return {jQuery} Input element
8150 OO
.ui
.InputWidget
.prototype.getInputElement = function () {
8151 return $( '<input>' );
8155 * Get input element's ID.
8157 * If the element already has an ID then that is returned, otherwise unique ID is
8158 * generated, set on the element, and returned.
8160 * @return {string} The ID of the element
8162 OO
.ui
.InputWidget
.prototype.getInputId = function () {
8163 var id
= this.$input
.attr( 'id' );
8165 if ( id
=== undefined ) {
8166 id
= OO
.ui
.generateElementId();
8167 this.$input
.attr( 'id', id
);
8174 * Handle potentially value-changing events.
8177 * @param {jQuery.Event} e Key down, mouse up, cut, paste, change, input, or select event
8179 OO
.ui
.InputWidget
.prototype.onEdit = function () {
8181 if ( !this.isDisabled() ) {
8182 // Allow the stack to clear so the value will be updated
8183 setTimeout( function () {
8184 widget
.setValue( widget
.$input
.val() );
8190 * Get the value of the input.
8192 * @return {string} Input value
8194 OO
.ui
.InputWidget
.prototype.getValue = function () {
8195 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
8196 // it, and we won't know unless they're kind enough to trigger a 'change' event.
8197 var value
= this.$input
.val();
8198 if ( this.value
!== value
) {
8199 this.setValue( value
);
8205 * Set the directionality of the input.
8207 * @param {string} dir Text directionality: 'ltr', 'rtl' or 'auto'
8210 OO
.ui
.InputWidget
.prototype.setDir = function ( dir
) {
8211 this.$input
.prop( 'dir', dir
);
8216 * Set the value of the input.
8218 * @param {string} value New value
8222 OO
.ui
.InputWidget
.prototype.setValue = function ( value
) {
8223 value
= this.cleanUpValue( value
);
8224 // Update the DOM if it has changed. Note that with cleanUpValue, it
8225 // is possible for the DOM value to change without this.value changing.
8226 if ( this.$input
.val() !== value
) {
8227 this.$input
.val( value
);
8229 if ( this.value
!== value
) {
8231 this.emit( 'change', this.value
);
8237 * Clean up incoming value.
8239 * Ensures value is a string, and converts undefined and null to empty string.
8242 * @param {string} value Original value
8243 * @return {string} Cleaned up value
8245 OO
.ui
.InputWidget
.prototype.cleanUpValue = function ( value
) {
8246 if ( value
=== undefined || value
=== null ) {
8248 } else if ( this.inputFilter
) {
8249 return this.inputFilter( String( value
) );
8251 return String( value
);
8256 * Simulate the behavior of clicking on a label bound to this input. This method is only called by
8257 * {@link OO.ui.LabelWidget LabelWidget} and {@link OO.ui.FieldLayout FieldLayout}. It should not be
8260 OO
.ui
.InputWidget
.prototype.simulateLabelClick = function () {
8261 OO
.ui
.warnDeprecation( 'InputWidget: simulateLabelClick() is deprecated.' );
8262 if ( !this.isDisabled() ) {
8263 if ( this.$input
.is( ':checkbox, :radio' ) ) {
8264 this.$input
.click();
8266 if ( this.$input
.is( ':input' ) ) {
8267 this.$input
[ 0 ].focus();
8275 OO
.ui
.InputWidget
.prototype.setDisabled = function ( state
) {
8276 OO
.ui
.InputWidget
.parent
.prototype.setDisabled
.call( this, state
);
8277 if ( this.$input
) {
8278 this.$input
.prop( 'disabled', this.isDisabled() );
8288 OO
.ui
.InputWidget
.prototype.focus = function () {
8289 this.$input
[ 0 ].focus();
8298 OO
.ui
.InputWidget
.prototype.blur = function () {
8299 this.$input
[ 0 ].blur();
8306 OO
.ui
.InputWidget
.prototype.restorePreInfuseState = function ( state
) {
8307 OO
.ui
.InputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8308 if ( state
.value
!== undefined && state
.value
!== this.getValue() ) {
8309 this.setValue( state
.value
);
8311 if ( state
.focus
) {
8317 * ButtonInputWidget is used to submit HTML forms and is intended to be used within
8318 * a OO.ui.FormLayout. If you do not need the button to work with HTML forms, you probably
8319 * want to use OO.ui.ButtonWidget instead. Button input widgets can be rendered as either an
8320 * HTML `<button>` (the default) or an HTML `<input>` tags. See the
8321 * [OOjs UI documentation on MediaWiki] [1] for more information.
8324 * // A ButtonInputWidget rendered as an HTML button, the default.
8325 * var button = new OO.ui.ButtonInputWidget( {
8326 * label: 'Input button',
8330 * $( 'body' ).append( button.$element );
8332 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs#Button_inputs
8335 * @extends OO.ui.InputWidget
8336 * @mixins OO.ui.mixin.ButtonElement
8337 * @mixins OO.ui.mixin.IconElement
8338 * @mixins OO.ui.mixin.IndicatorElement
8339 * @mixins OO.ui.mixin.LabelElement
8340 * @mixins OO.ui.mixin.TitledElement
8343 * @param {Object} [config] Configuration options
8344 * @cfg {string} [type='button'] The value of the HTML `'type'` attribute: 'button', 'submit' or 'reset'.
8345 * @cfg {boolean} [useInputTag=false] Use an `<input>` tag instead of a `<button>` tag, the default.
8346 * Widgets configured to be an `<input>` do not support {@link #icon icons} and {@link #indicator indicators},
8347 * non-plaintext {@link #label labels}, or {@link #value values}. In general, useInputTag should only
8348 * be set to `true` when there’s need to support IE 6 in a form with multiple buttons.
8350 OO
.ui
.ButtonInputWidget
= function OoUiButtonInputWidget( config
) {
8351 // Configuration initialization
8352 config
= $.extend( { type
: 'button', useInputTag
: false }, config
);
8354 // See InputWidget#reusePreInfuseDOM about config.$input
8355 if ( config
.$input
) {
8356 config
.$input
.empty();
8359 // Properties (must be set before parent constructor, which calls #setValue)
8360 this.useInputTag
= config
.useInputTag
;
8362 // Parent constructor
8363 OO
.ui
.ButtonInputWidget
.parent
.call( this, config
);
8365 // Mixin constructors
8366 OO
.ui
.mixin
.ButtonElement
.call( this, $.extend( {}, config
, { $button
: this.$input
} ) );
8367 OO
.ui
.mixin
.IconElement
.call( this, config
);
8368 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
8369 OO
.ui
.mixin
.LabelElement
.call( this, config
);
8370 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
8373 if ( !config
.useInputTag
) {
8374 this.$input
.append( this.$icon
, this.$label
, this.$indicator
);
8376 this.$element
.addClass( 'oo-ui-buttonInputWidget' );
8381 OO
.inheritClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.InputWidget
);
8382 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.ButtonElement
);
8383 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IconElement
);
8384 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
8385 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.LabelElement
);
8386 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.TitledElement
);
8388 /* Static Properties */
8391 * Disable generating `<label>` elements for buttons. One would very rarely need additional label
8392 * for a button, and it's already a big clickable target, and it causes unexpected rendering.
8397 OO
.ui
.ButtonInputWidget
.static.supportsSimpleLabel
= false;
8403 OO
.ui
.ButtonInputWidget
.static.tagName
= 'span';
8411 OO
.ui
.ButtonInputWidget
.prototype.getInputElement = function ( config
) {
8413 type
= [ 'button', 'submit', 'reset' ].indexOf( config
.type
) !== -1 ? config
.type
: 'button';
8414 return $( '<' + ( config
.useInputTag
? 'input' : 'button' ) + ' type="' + type
+ '">' );
8420 * If #useInputTag is `true`, the label is set as the `value` of the `<input>` tag.
8422 * @param {jQuery|string|Function|null} label Label nodes, text, a function that returns nodes or
8423 * text, or `null` for no label
8426 OO
.ui
.ButtonInputWidget
.prototype.setLabel = function ( label
) {
8427 if ( typeof label
=== 'function' ) {
8428 label
= OO
.ui
.resolveMsg( label
);
8431 if ( this.useInputTag
) {
8432 // Discard non-plaintext labels
8433 if ( typeof label
!== 'string' ) {
8437 this.$input
.val( label
);
8440 return OO
.ui
.mixin
.LabelElement
.prototype.setLabel
.call( this, label
);
8444 * Set the value of the input.
8446 * This method is disabled for button inputs configured as {@link #useInputTag <input> tags}, as
8447 * they do not support {@link #value values}.
8449 * @param {string} value New value
8452 OO
.ui
.ButtonInputWidget
.prototype.setValue = function ( value
) {
8453 if ( !this.useInputTag
) {
8454 OO
.ui
.ButtonInputWidget
.parent
.prototype.setValue
.call( this, value
);
8460 * CheckboxInputWidgets, like HTML checkboxes, can be selected and/or configured with a value.
8461 * Note that these {@link OO.ui.InputWidget input widgets} are best laid out
8462 * in {@link OO.ui.FieldLayout field layouts} that use the {@link OO.ui.FieldLayout#align inline}
8463 * alignment. For more information, please see the [OOjs UI documentation on MediaWiki][1].
8465 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
8468 * // An example of selected, unselected, and disabled checkbox inputs
8469 * var checkbox1=new OO.ui.CheckboxInputWidget( {
8473 * var checkbox2=new OO.ui.CheckboxInputWidget( {
8476 * var checkbox3=new OO.ui.CheckboxInputWidget( {
8480 * // Create a fieldset layout with fields for each checkbox.
8481 * var fieldset = new OO.ui.FieldsetLayout( {
8482 * label: 'Checkboxes'
8484 * fieldset.addItems( [
8485 * new OO.ui.FieldLayout( checkbox1, { label: 'Selected checkbox', align: 'inline' } ),
8486 * new OO.ui.FieldLayout( checkbox2, { label: 'Unselected checkbox', align: 'inline' } ),
8487 * new OO.ui.FieldLayout( checkbox3, { label: 'Disabled checkbox', align: 'inline' } ),
8489 * $( 'body' ).append( fieldset.$element );
8491 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8494 * @extends OO.ui.InputWidget
8497 * @param {Object} [config] Configuration options
8498 * @cfg {boolean} [selected=false] Select the checkbox initially. By default, the checkbox is not selected.
8500 OO
.ui
.CheckboxInputWidget
= function OoUiCheckboxInputWidget( config
) {
8501 // Configuration initialization
8502 config
= config
|| {};
8504 // Parent constructor
8505 OO
.ui
.CheckboxInputWidget
.parent
.call( this, config
);
8509 .addClass( 'oo-ui-checkboxInputWidget' )
8510 // Required for pretty styling in MediaWiki theme
8511 .append( $( '<span>' ) );
8512 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
8517 OO
.inheritClass( OO
.ui
.CheckboxInputWidget
, OO
.ui
.InputWidget
);
8519 /* Static Properties */
8525 OO
.ui
.CheckboxInputWidget
.static.tagName
= 'span';
8527 /* Static Methods */
8532 OO
.ui
.CheckboxInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8533 var state
= OO
.ui
.CheckboxInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8534 state
.checked
= config
.$input
.prop( 'checked' );
8544 OO
.ui
.CheckboxInputWidget
.prototype.getInputElement = function () {
8545 return $( '<input>' ).attr( 'type', 'checkbox' );
8551 OO
.ui
.CheckboxInputWidget
.prototype.onEdit = function () {
8553 if ( !this.isDisabled() ) {
8554 // Allow the stack to clear so the value will be updated
8555 setTimeout( function () {
8556 widget
.setSelected( widget
.$input
.prop( 'checked' ) );
8562 * Set selection state of this checkbox.
8564 * @param {boolean} state `true` for selected
8567 OO
.ui
.CheckboxInputWidget
.prototype.setSelected = function ( state
) {
8569 if ( this.selected
!== state
) {
8570 this.selected
= state
;
8571 this.$input
.prop( 'checked', this.selected
);
8572 this.emit( 'change', this.selected
);
8578 * Check if this checkbox is selected.
8580 * @return {boolean} Checkbox is selected
8582 OO
.ui
.CheckboxInputWidget
.prototype.isSelected = function () {
8583 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
8584 // it, and we won't know unless they're kind enough to trigger a 'change' event.
8585 var selected
= this.$input
.prop( 'checked' );
8586 if ( this.selected
!== selected
) {
8587 this.setSelected( selected
);
8589 return this.selected
;
8595 OO
.ui
.CheckboxInputWidget
.prototype.restorePreInfuseState = function ( state
) {
8596 OO
.ui
.CheckboxInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8597 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
8598 this.setSelected( state
.checked
);
8603 * DropdownInputWidget is a {@link OO.ui.DropdownWidget DropdownWidget} intended to be used
8604 * within an HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
8605 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
8606 * more information about input widgets.
8608 * A DropdownInputWidget always has a value (one of the options is always selected), unless there
8609 * are no options. If no `value` configuration option is provided, the first option is selected.
8610 * If you need a state representing no value (no option being selected), use a DropdownWidget.
8612 * This and OO.ui.RadioSelectInputWidget support the same configuration options.
8615 * // Example: A DropdownInputWidget with three options
8616 * var dropdownInput = new OO.ui.DropdownInputWidget( {
8618 * { data: 'a', label: 'First' },
8619 * { data: 'b', label: 'Second'},
8620 * { data: 'c', label: 'Third' }
8623 * $( 'body' ).append( dropdownInput.$element );
8625 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8628 * @extends OO.ui.InputWidget
8629 * @mixins OO.ui.mixin.TitledElement
8632 * @param {Object} [config] Configuration options
8633 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
8634 * @cfg {Object} [dropdown] Configuration options for {@link OO.ui.DropdownWidget DropdownWidget}
8636 OO
.ui
.DropdownInputWidget
= function OoUiDropdownInputWidget( config
) {
8637 // Configuration initialization
8638 config
= config
|| {};
8640 // See InputWidget#reusePreInfuseDOM about config.$input
8641 if ( config
.$input
) {
8642 config
.$input
.addClass( 'oo-ui-element-hidden' );
8645 // Properties (must be done before parent constructor which calls #setDisabled)
8646 this.dropdownWidget
= new OO
.ui
.DropdownWidget( config
.dropdown
);
8648 // Parent constructor
8649 OO
.ui
.DropdownInputWidget
.parent
.call( this, config
);
8651 // Mixin constructors
8652 OO
.ui
.mixin
.TitledElement
.call( this, config
);
8655 this.dropdownWidget
.getMenu().connect( this, { select
: 'onMenuSelect' } );
8658 this.setOptions( config
.options
|| [] );
8660 .addClass( 'oo-ui-dropdownInputWidget' )
8661 .append( this.dropdownWidget
.$element
);
8662 this.setTabIndexedElement( null );
8667 OO
.inheritClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.InputWidget
);
8668 OO
.mixinClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.mixin
.TitledElement
);
8676 OO
.ui
.DropdownInputWidget
.prototype.getInputElement = function () {
8677 return $( '<input>' ).attr( 'type', 'hidden' );
8681 * Handles menu select events.
8684 * @param {OO.ui.MenuOptionWidget} item Selected menu item
8686 OO
.ui
.DropdownInputWidget
.prototype.onMenuSelect = function ( item
) {
8687 this.setValue( item
.getData() );
8693 OO
.ui
.DropdownInputWidget
.prototype.setValue = function ( value
) {
8695 value
= this.cleanUpValue( value
);
8696 this.dropdownWidget
.getMenu().selectItemByData( value
);
8697 // Only allow setting values that are actually present in the dropdown
8698 selected
= this.dropdownWidget
.getMenu().getSelectedItem();
8699 value
= selected
? selected
.getData() : '';
8700 OO
.ui
.DropdownInputWidget
.parent
.prototype.setValue
.call( this, value
);
8707 OO
.ui
.DropdownInputWidget
.prototype.setDisabled = function ( state
) {
8708 this.dropdownWidget
.setDisabled( state
);
8709 OO
.ui
.DropdownInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
8714 * Set the options available for this input.
8716 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
8719 OO
.ui
.DropdownInputWidget
.prototype.setOptions = function ( options
) {
8721 value
= this.getValue(),
8724 // Rebuild the dropdown menu
8725 this.dropdownWidget
.getMenu()
8727 .addItems( options
.map( function ( opt
) {
8728 var optValue
= widget
.cleanUpValue( opt
.data
);
8730 if ( opt
.optgroup
=== undefined ) {
8731 return new OO
.ui
.MenuOptionWidget( {
8733 label
: opt
.label
!== undefined ? opt
.label
: optValue
8736 return new OO
.ui
.MenuSectionOptionWidget( {
8742 // Restore the previous value, or reset to something sensible
8743 if ( this.dropdownWidget
.getMenu().getItemFromData( value
) ) {
8744 // Previous value is still available, ensure consistency with the dropdown
8745 this.setValue( value
);
8747 // No longer valid, reset
8748 if ( options
.length
) {
8749 this.setValue( options
[ 0 ].data
);
8759 OO
.ui
.DropdownInputWidget
.prototype.focus = function () {
8760 this.dropdownWidget
.getMenu().toggle( true );
8767 OO
.ui
.DropdownInputWidget
.prototype.blur = function () {
8768 this.dropdownWidget
.getMenu().toggle( false );
8773 * RadioInputWidget creates a single radio button. Because radio buttons are usually used as a set,
8774 * in most cases you will want to use a {@link OO.ui.RadioSelectWidget radio select}
8775 * with {@link OO.ui.RadioOptionWidget radio options} instead of this class. For more information,
8776 * please see the [OOjs UI documentation on MediaWiki][1].
8778 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
8781 * // An example of selected, unselected, and disabled radio inputs
8782 * var radio1 = new OO.ui.RadioInputWidget( {
8786 * var radio2 = new OO.ui.RadioInputWidget( {
8789 * var radio3 = new OO.ui.RadioInputWidget( {
8793 * // Create a fieldset layout with fields for each radio button.
8794 * var fieldset = new OO.ui.FieldsetLayout( {
8795 * label: 'Radio inputs'
8797 * fieldset.addItems( [
8798 * new OO.ui.FieldLayout( radio1, { label: 'Selected', align: 'inline' } ),
8799 * new OO.ui.FieldLayout( radio2, { label: 'Unselected', align: 'inline' } ),
8800 * new OO.ui.FieldLayout( radio3, { label: 'Disabled', align: 'inline' } ),
8802 * $( 'body' ).append( fieldset.$element );
8804 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8807 * @extends OO.ui.InputWidget
8810 * @param {Object} [config] Configuration options
8811 * @cfg {boolean} [selected=false] Select the radio button initially. By default, the radio button is not selected.
8813 OO
.ui
.RadioInputWidget
= function OoUiRadioInputWidget( config
) {
8814 // Configuration initialization
8815 config
= config
|| {};
8817 // Parent constructor
8818 OO
.ui
.RadioInputWidget
.parent
.call( this, config
);
8822 .addClass( 'oo-ui-radioInputWidget' )
8823 // Required for pretty styling in MediaWiki theme
8824 .append( $( '<span>' ) );
8825 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
8830 OO
.inheritClass( OO
.ui
.RadioInputWidget
, OO
.ui
.InputWidget
);
8832 /* Static Properties */
8838 OO
.ui
.RadioInputWidget
.static.tagName
= 'span';
8840 /* Static Methods */
8845 OO
.ui
.RadioInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8846 var state
= OO
.ui
.RadioInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8847 state
.checked
= config
.$input
.prop( 'checked' );
8857 OO
.ui
.RadioInputWidget
.prototype.getInputElement = function () {
8858 return $( '<input>' ).attr( 'type', 'radio' );
8864 OO
.ui
.RadioInputWidget
.prototype.onEdit = function () {
8865 // RadioInputWidget doesn't track its state.
8869 * Set selection state of this radio button.
8871 * @param {boolean} state `true` for selected
8874 OO
.ui
.RadioInputWidget
.prototype.setSelected = function ( state
) {
8875 // RadioInputWidget doesn't track its state.
8876 this.$input
.prop( 'checked', state
);
8881 * Check if this radio button is selected.
8883 * @return {boolean} Radio is selected
8885 OO
.ui
.RadioInputWidget
.prototype.isSelected = function () {
8886 return this.$input
.prop( 'checked' );
8892 OO
.ui
.RadioInputWidget
.prototype.restorePreInfuseState = function ( state
) {
8893 OO
.ui
.RadioInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8894 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
8895 this.setSelected( state
.checked
);
8900 * RadioSelectInputWidget is a {@link OO.ui.RadioSelectWidget RadioSelectWidget} intended to be used
8901 * within an HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
8902 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
8903 * more information about input widgets.
8905 * This and OO.ui.DropdownInputWidget support the same configuration options.
8908 * // Example: A RadioSelectInputWidget with three options
8909 * var radioSelectInput = new OO.ui.RadioSelectInputWidget( {
8911 * { data: 'a', label: 'First' },
8912 * { data: 'b', label: 'Second'},
8913 * { data: 'c', label: 'Third' }
8916 * $( 'body' ).append( radioSelectInput.$element );
8918 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8921 * @extends OO.ui.InputWidget
8924 * @param {Object} [config] Configuration options
8925 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
8927 OO
.ui
.RadioSelectInputWidget
= function OoUiRadioSelectInputWidget( config
) {
8928 // Configuration initialization
8929 config
= config
|| {};
8931 // Properties (must be done before parent constructor which calls #setDisabled)
8932 this.radioSelectWidget
= new OO
.ui
.RadioSelectWidget();
8934 // Parent constructor
8935 OO
.ui
.RadioSelectInputWidget
.parent
.call( this, config
);
8938 this.radioSelectWidget
.connect( this, { select
: 'onMenuSelect' } );
8941 this.setOptions( config
.options
|| [] );
8943 .addClass( 'oo-ui-radioSelectInputWidget' )
8944 .append( this.radioSelectWidget
.$element
);
8945 this.setTabIndexedElement( null );
8950 OO
.inheritClass( OO
.ui
.RadioSelectInputWidget
, OO
.ui
.InputWidget
);
8952 /* Static Properties */
8958 OO
.ui
.RadioSelectInputWidget
.static.supportsSimpleLabel
= false;
8960 /* Static Methods */
8965 OO
.ui
.RadioSelectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8966 var state
= OO
.ui
.RadioSelectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8967 state
.value
= $( node
).find( '.oo-ui-radioInputWidget .oo-ui-inputWidget-input:checked' ).val();
8974 OO
.ui
.RadioSelectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
8975 config
= OO
.ui
.RadioSelectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
8976 // Cannot reuse the `<input type=radio>` set
8977 delete config
.$input
;
8987 OO
.ui
.RadioSelectInputWidget
.prototype.getInputElement = function () {
8988 return $( '<input>' ).attr( 'type', 'hidden' );
8992 * Handles menu select events.
8995 * @param {OO.ui.RadioOptionWidget} item Selected menu item
8997 OO
.ui
.RadioSelectInputWidget
.prototype.onMenuSelect = function ( item
) {
8998 this.setValue( item
.getData() );
9004 OO
.ui
.RadioSelectInputWidget
.prototype.setValue = function ( value
) {
9005 value
= this.cleanUpValue( value
);
9006 this.radioSelectWidget
.selectItemByData( value
);
9007 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setValue
.call( this, value
);
9014 OO
.ui
.RadioSelectInputWidget
.prototype.setDisabled = function ( state
) {
9015 this.radioSelectWidget
.setDisabled( state
);
9016 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
9021 * Set the options available for this input.
9023 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
9026 OO
.ui
.RadioSelectInputWidget
.prototype.setOptions = function ( options
) {
9028 value
= this.getValue(),
9031 // Rebuild the radioSelect menu
9032 this.radioSelectWidget
9034 .addItems( options
.map( function ( opt
) {
9035 var optValue
= widget
.cleanUpValue( opt
.data
);
9036 return new OO
.ui
.RadioOptionWidget( {
9038 label
: opt
.label
!== undefined ? opt
.label
: optValue
9042 // Restore the previous value, or reset to something sensible
9043 if ( this.radioSelectWidget
.getItemFromData( value
) ) {
9044 // Previous value is still available, ensure consistency with the radioSelect
9045 this.setValue( value
);
9047 // No longer valid, reset
9048 if ( options
.length
) {
9049 this.setValue( options
[ 0 ].data
);
9057 * CheckboxMultiselectInputWidget is a
9058 * {@link OO.ui.CheckboxMultiselectWidget CheckboxMultiselectWidget} intended to be used within a
9059 * HTML form, such as a OO.ui.FormLayout. The selected values are synchronized with the value of
9060 * HTML `<input type=checkbox>` tags. Please see the [OOjs UI documentation on MediaWiki][1] for
9061 * more information about input widgets.
9064 * // Example: A CheckboxMultiselectInputWidget with three options
9065 * var multiselectInput = new OO.ui.CheckboxMultiselectInputWidget( {
9067 * { data: 'a', label: 'First' },
9068 * { data: 'b', label: 'Second'},
9069 * { data: 'c', label: 'Third' }
9072 * $( 'body' ).append( multiselectInput.$element );
9074 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
9077 * @extends OO.ui.InputWidget
9080 * @param {Object} [config] Configuration options
9081 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: …, disabled: … }`
9083 OO
.ui
.CheckboxMultiselectInputWidget
= function OoUiCheckboxMultiselectInputWidget( config
) {
9084 // Configuration initialization
9085 config
= config
|| {};
9087 // Properties (must be done before parent constructor which calls #setDisabled)
9088 this.checkboxMultiselectWidget
= new OO
.ui
.CheckboxMultiselectWidget();
9090 // Parent constructor
9091 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.call( this, config
);
9094 this.inputName
= config
.name
;
9098 .addClass( 'oo-ui-checkboxMultiselectInputWidget' )
9099 .append( this.checkboxMultiselectWidget
.$element
);
9100 // We don't use this.$input, but rather the CheckboxInputWidgets inside each option
9101 this.$input
.detach();
9102 this.setOptions( config
.options
|| [] );
9103 // Have to repeat this from parent, as we need options to be set up for this to make sense
9104 this.setValue( config
.value
);
9109 OO
.inheritClass( OO
.ui
.CheckboxMultiselectInputWidget
, OO
.ui
.InputWidget
);
9111 /* Static Properties */
9117 OO
.ui
.CheckboxMultiselectInputWidget
.static.supportsSimpleLabel
= false;
9119 /* Static Methods */
9124 OO
.ui
.CheckboxMultiselectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
9125 var state
= OO
.ui
.CheckboxMultiselectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
9126 state
.value
= $( node
).find( '.oo-ui-checkboxInputWidget .oo-ui-inputWidget-input:checked' )
9127 .toArray().map( function ( el
) { return el
.value
; } );
9134 OO
.ui
.CheckboxMultiselectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
9135 config
= OO
.ui
.CheckboxMultiselectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
9136 // Cannot reuse the `<input type=checkbox>` set
9137 delete config
.$input
;
9147 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.getInputElement = function () {
9149 return $( '<div>' );
9155 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.getValue = function () {
9156 var value
= this.$element
.find( '.oo-ui-checkboxInputWidget .oo-ui-inputWidget-input:checked' )
9157 .toArray().map( function ( el
) { return el
.value
; } );
9158 if ( this.value
!== value
) {
9159 this.setValue( value
);
9167 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setValue = function ( value
) {
9168 value
= this.cleanUpValue( value
);
9169 this.checkboxMultiselectWidget
.selectItemsByData( value
);
9170 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.setValue
.call( this, value
);
9175 * Clean up incoming value.
9177 * @param {string[]} value Original value
9178 * @return {string[]} Cleaned up value
9180 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.cleanUpValue = function ( value
) {
9183 if ( !Array
.isArray( value
) ) {
9186 for ( i
= 0; i
< value
.length
; i
++ ) {
9188 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.cleanUpValue
.call( this, value
[ i
] );
9189 // Remove options that we don't have here
9190 if ( !this.checkboxMultiselectWidget
.getItemFromData( singleValue
) ) {
9193 cleanValue
.push( singleValue
);
9201 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setDisabled = function ( state
) {
9202 this.checkboxMultiselectWidget
.setDisabled( state
);
9203 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
9208 * Set the options available for this input.
9210 * @param {Object[]} options Array of menu options in the format `{ data: …, label: …, disabled: … }`
9213 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setOptions = function ( options
) {
9216 // Rebuild the checkboxMultiselectWidget menu
9217 this.checkboxMultiselectWidget
9219 .addItems( options
.map( function ( opt
) {
9220 var optValue
, item
, optDisabled
;
9222 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.cleanUpValue
.call( widget
, opt
.data
);
9223 optDisabled
= opt
.disabled
!== undefined ? opt
.disabled
: false;
9224 item
= new OO
.ui
.CheckboxMultioptionWidget( {
9226 label
: opt
.label
!== undefined ? opt
.label
: optValue
,
9227 disabled
: optDisabled
9229 // Set the 'name' and 'value' for form submission
9230 item
.checkbox
.$input
.attr( 'name', widget
.inputName
);
9231 item
.checkbox
.setValue( optValue
);
9235 // Re-set the value, checking the checkboxes as needed.
9236 // This will also get rid of any stale options that we just removed.
9237 this.setValue( this.getValue() );
9243 * TextInputWidgets, like HTML text inputs, can be configured with options that customize the
9244 * size of the field as well as its presentation. In addition, these widgets can be configured
9245 * with {@link OO.ui.mixin.IconElement icons}, {@link OO.ui.mixin.IndicatorElement indicators}, an optional
9246 * validation-pattern (used to determine if an input value is valid or not) and an input filter,
9247 * which modifies incoming values rather than validating them.
9248 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
9250 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
9253 * // Example of a text input widget
9254 * var textInput = new OO.ui.TextInputWidget( {
9255 * value: 'Text input'
9257 * $( 'body' ).append( textInput.$element );
9259 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
9262 * @extends OO.ui.InputWidget
9263 * @mixins OO.ui.mixin.IconElement
9264 * @mixins OO.ui.mixin.IndicatorElement
9265 * @mixins OO.ui.mixin.PendingElement
9266 * @mixins OO.ui.mixin.LabelElement
9269 * @param {Object} [config] Configuration options
9270 * @cfg {string} [type='text'] The value of the HTML `type` attribute: 'text', 'password', 'search',
9271 * 'email', 'url' or 'number'. Ignored if `multiline` is true.
9273 * Some values of `type` result in additional behaviors:
9275 * - `search`: implies `icon: 'search'` and `indicator: 'clear'`; when clicked, the indicator
9276 * empties the text field
9277 * @cfg {string} [placeholder] Placeholder text
9278 * @cfg {boolean} [autofocus=false] Use an HTML `autofocus` attribute to
9279 * instruct the browser to focus this widget.
9280 * @cfg {boolean} [readOnly=false] Prevent changes to the value of the text input.
9281 * @cfg {number} [maxLength] Maximum number of characters allowed in the input.
9282 * @cfg {boolean} [multiline=false] Allow multiple lines of text
9283 * @cfg {number} [rows] If multiline, number of visible lines in textarea. If used with `autosize`,
9284 * specifies minimum number of rows to display.
9285 * @cfg {boolean} [autosize=false] Automatically resize the text input to fit its content.
9286 * Use the #maxRows config to specify a maximum number of displayed rows.
9287 * @cfg {number} [maxRows] Maximum number of rows to display when #autosize is set to true.
9288 * Defaults to the maximum of `10` and `2 * rows`, or `10` if `rows` isn't provided.
9289 * @cfg {string} [labelPosition='after'] The position of the inline label relative to that of
9290 * the value or placeholder text: `'before'` or `'after'`
9291 * @cfg {boolean} [required=false] Mark the field as required. Implies `indicator: 'required'`.
9292 * @cfg {boolean} [autocomplete=true] Should the browser support autocomplete for this field
9293 * @cfg {RegExp|Function|string} [validate] Validation pattern: when string, a symbolic name of a
9294 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer'
9295 * (the value must contain only numbers); when RegExp, a regular expression that must match the
9296 * value for it to be considered valid; when Function, a function receiving the value as parameter
9297 * that must return true, or promise resolving to true, for it to be considered valid.
9299 OO
.ui
.TextInputWidget
= function OoUiTextInputWidget( config
) {
9300 // Configuration initialization
9301 config
= $.extend( {
9303 labelPosition
: 'after'
9306 if ( config
.type
=== 'search' ) {
9307 OO
.ui
.warnDeprecation( 'TextInputWidget: config.type=\'search\' is deprecated. Use the SearchInputWidget instead. See T148471 for details.' );
9308 if ( config
.icon
=== undefined ) {
9309 config
.icon
= 'search';
9311 // indicator: 'clear' is set dynamically later, depending on value
9314 // Parent constructor
9315 OO
.ui
.TextInputWidget
.parent
.call( this, config
);
9317 // Mixin constructors
9318 OO
.ui
.mixin
.IconElement
.call( this, config
);
9319 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
9320 OO
.ui
.mixin
.PendingElement
.call( this, $.extend( {}, config
, { $pending
: this.$input
} ) );
9321 OO
.ui
.mixin
.LabelElement
.call( this, config
);
9324 this.type
= this.getSaneType( config
);
9325 this.readOnly
= false;
9326 this.required
= false;
9327 this.multiline
= !!config
.multiline
;
9328 this.autosize
= !!config
.autosize
;
9329 this.minRows
= config
.rows
!== undefined ? config
.rows
: '';
9330 this.maxRows
= config
.maxRows
|| Math
.max( 2 * ( this.minRows
|| 0 ), 10 );
9331 this.validate
= null;
9332 this.styleHeight
= null;
9333 this.scrollWidth
= null;
9335 // Clone for resizing
9336 if ( this.autosize
) {
9337 this.$clone
= this.$input
9339 .insertAfter( this.$input
)
9340 .attr( 'aria-hidden', 'true' )
9341 .addClass( 'oo-ui-element-hidden' );
9344 this.setValidation( config
.validate
);
9345 this.setLabelPosition( config
.labelPosition
);
9349 keypress
: this.onKeyPress
.bind( this ),
9350 blur
: this.onBlur
.bind( this ),
9351 focus
: this.onFocus
.bind( this )
9353 this.$icon
.on( 'mousedown', this.onIconMouseDown
.bind( this ) );
9354 this.$indicator
.on( 'mousedown', this.onIndicatorMouseDown
.bind( this ) );
9355 this.on( 'labelChange', this.updatePosition
.bind( this ) );
9356 this.connect( this, {
9358 disable
: 'onDisable'
9360 this.on( 'change', OO
.ui
.debounce( this.onDebouncedChange
.bind( this ), 250 ) );
9364 .addClass( 'oo-ui-textInputWidget oo-ui-textInputWidget-type-' + this.type
)
9365 .append( this.$icon
, this.$indicator
);
9366 this.setReadOnly( !!config
.readOnly
);
9367 this.setRequired( !!config
.required
);
9368 this.updateSearchIndicator();
9369 if ( config
.placeholder
!== undefined ) {
9370 this.$input
.attr( 'placeholder', config
.placeholder
);
9372 if ( config
.maxLength
!== undefined ) {
9373 this.$input
.attr( 'maxlength', config
.maxLength
);
9375 if ( config
.autofocus
) {
9376 this.$input
.attr( 'autofocus', 'autofocus' );
9378 if ( config
.autocomplete
=== false ) {
9379 this.$input
.attr( 'autocomplete', 'off' );
9380 // Turning off autocompletion also disables "form caching" when the user navigates to a
9381 // different page and then clicks "Back". Re-enable it when leaving. Borrowed from jQuery UI.
9383 beforeunload: function () {
9384 this.$input
.removeAttr( 'autocomplete' );
9386 pageshow: function () {
9387 // Browsers don't seem to actually fire this event on "Back", they instead just reload the
9388 // whole page... it shouldn't hurt, though.
9389 this.$input
.attr( 'autocomplete', 'off' );
9393 if ( this.multiline
&& config
.rows
) {
9394 this.$input
.attr( 'rows', config
.rows
);
9396 if ( this.label
|| config
.autosize
) {
9397 this.isWaitingToBeAttached
= true;
9398 this.installParentChangeDetector();
9404 OO
.inheritClass( OO
.ui
.TextInputWidget
, OO
.ui
.InputWidget
);
9405 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IconElement
);
9406 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
9407 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.PendingElement
);
9408 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.LabelElement
);
9410 /* Static Properties */
9412 OO
.ui
.TextInputWidget
.static.validationPatterns
= {
9417 /* Static Methods */
9422 OO
.ui
.TextInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
9423 var state
= OO
.ui
.TextInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
9424 if ( config
.multiline
) {
9425 state
.scrollTop
= config
.$input
.scrollTop();
9433 * An `enter` event is emitted when the user presses 'enter' inside the text box.
9435 * Not emitted if the input is multiline.
9441 * A `resize` event is emitted when autosize is set and the widget resizes
9449 * Handle icon mouse down events.
9452 * @param {jQuery.Event} e Mouse down event
9454 OO
.ui
.TextInputWidget
.prototype.onIconMouseDown = function ( e
) {
9455 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
9456 this.$input
[ 0 ].focus();
9462 * Handle indicator mouse down events.
9465 * @param {jQuery.Event} e Mouse down event
9467 OO
.ui
.TextInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
9468 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
9469 if ( this.type
=== 'search' ) {
9470 // Clear the text field
9471 this.setValue( '' );
9473 this.$input
[ 0 ].focus();
9479 * Handle key press events.
9482 * @param {jQuery.Event} e Key press event
9483 * @fires enter If enter key is pressed and input is not multiline
9485 OO
.ui
.TextInputWidget
.prototype.onKeyPress = function ( e
) {
9486 if ( e
.which
=== OO
.ui
.Keys
.ENTER
&& !this.multiline
) {
9487 this.emit( 'enter', e
);
9492 * Handle blur events.
9495 * @param {jQuery.Event} e Blur event
9497 OO
.ui
.TextInputWidget
.prototype.onBlur = function () {
9498 this.setValidityFlag();
9502 * Handle focus events.
9505 * @param {jQuery.Event} e Focus event
9507 OO
.ui
.TextInputWidget
.prototype.onFocus = function () {
9508 if ( this.isWaitingToBeAttached
) {
9509 // If we've received focus, then we must be attached to the document, and if
9510 // isWaitingToBeAttached is still true, that means the handler never fired. Fire it now.
9511 this.onElementAttach();
9513 this.setValidityFlag( true );
9517 * Handle element attach events.
9520 * @param {jQuery.Event} e Element attach event
9522 OO
.ui
.TextInputWidget
.prototype.onElementAttach = function () {
9523 this.isWaitingToBeAttached
= false;
9524 // Any previously calculated size is now probably invalid if we reattached elsewhere
9525 this.valCache
= null;
9527 this.positionLabel();
9531 * Handle change events.
9533 * @param {string} value
9536 OO
.ui
.TextInputWidget
.prototype.onChange = function () {
9537 this.updateSearchIndicator();
9542 * Handle debounced change events.
9544 * @param {string} value
9547 OO
.ui
.TextInputWidget
.prototype.onDebouncedChange = function () {
9548 this.setValidityFlag();
9552 * Handle disable events.
9554 * @param {boolean} disabled Element is disabled
9557 OO
.ui
.TextInputWidget
.prototype.onDisable = function () {
9558 this.updateSearchIndicator();
9562 * Check if the input is {@link #readOnly read-only}.
9566 OO
.ui
.TextInputWidget
.prototype.isReadOnly = function () {
9567 return this.readOnly
;
9571 * Set the {@link #readOnly read-only} state of the input.
9573 * @param {boolean} state Make input read-only
9576 OO
.ui
.TextInputWidget
.prototype.setReadOnly = function ( state
) {
9577 this.readOnly
= !!state
;
9578 this.$input
.prop( 'readOnly', this.readOnly
);
9579 this.updateSearchIndicator();
9584 * Check if the input is {@link #required required}.
9588 OO
.ui
.TextInputWidget
.prototype.isRequired = function () {
9589 return this.required
;
9593 * Set the {@link #required required} state of the input.
9595 * @param {boolean} state Make input required
9598 OO
.ui
.TextInputWidget
.prototype.setRequired = function ( state
) {
9599 this.required
= !!state
;
9600 if ( this.required
) {
9602 .prop( 'required', true )
9603 .attr( 'aria-required', 'true' );
9604 if ( this.getIndicator() === null ) {
9605 this.setIndicator( 'required' );
9609 .prop( 'required', false )
9610 .removeAttr( 'aria-required' );
9611 if ( this.getIndicator() === 'required' ) {
9612 this.setIndicator( null );
9615 this.updateSearchIndicator();
9620 * Support function for making #onElementAttach work across browsers.
9622 * This whole function could be replaced with one line of code using the DOMNodeInsertedIntoDocument
9623 * event, but it's not supported by Firefox and allegedly deprecated, so we only use it as fallback.
9625 * Due to MutationObserver performance woes, #onElementAttach is only somewhat reliably called the
9626 * first time that the element gets attached to the documented.
9628 OO
.ui
.TextInputWidget
.prototype.installParentChangeDetector = function () {
9629 var mutationObserver
, onRemove
, topmostNode
, fakeParentNode
,
9630 MutationObserver
= window
.MutationObserver
|| window
.WebKitMutationObserver
|| window
.MozMutationObserver
,
9633 if ( MutationObserver
) {
9634 // The new way. If only it wasn't so ugly.
9636 if ( this.isElementAttached() ) {
9637 // Widget is attached already, do nothing. This breaks the functionality of this function when
9638 // the widget is detached and reattached. Alas, doing this correctly with MutationObserver
9639 // would require observation of the whole document, which would hurt performance of other,
9640 // more important code.
9644 // Find topmost node in the tree
9645 topmostNode
= this.$element
[ 0 ];
9646 while ( topmostNode
.parentNode
) {
9647 topmostNode
= topmostNode
.parentNode
;
9650 // We have no way to detect the $element being attached somewhere without observing the entire
9651 // DOM with subtree modifications, which would hurt performance. So we cheat: we hook to the
9652 // parent node of $element, and instead detect when $element is removed from it (and thus
9653 // probably attached somewhere else). If there is no parent, we create a "fake" one. If it
9654 // doesn't get attached, we end up back here and create the parent.
9656 mutationObserver
= new MutationObserver( function ( mutations
) {
9657 var i
, j
, removedNodes
;
9658 for ( i
= 0; i
< mutations
.length
; i
++ ) {
9659 removedNodes
= mutations
[ i
].removedNodes
;
9660 for ( j
= 0; j
< removedNodes
.length
; j
++ ) {
9661 if ( removedNodes
[ j
] === topmostNode
) {
9662 setTimeout( onRemove
, 0 );
9669 onRemove = function () {
9670 // If the node was attached somewhere else, report it
9671 if ( widget
.isElementAttached() ) {
9672 widget
.onElementAttach();
9674 mutationObserver
.disconnect();
9675 widget
.installParentChangeDetector();
9678 // Create a fake parent and observe it
9679 fakeParentNode
= $( '<div>' ).append( topmostNode
)[ 0 ];
9680 mutationObserver
.observe( fakeParentNode
, { childList
: true } );
9682 // Using the DOMNodeInsertedIntoDocument event is much nicer and less magical, and works for
9683 // detachment and reattachment, but it's not supported by Firefox and allegedly deprecated.
9684 this.$element
.on( 'DOMNodeInsertedIntoDocument', this.onElementAttach
.bind( this ) );
9689 * Automatically adjust the size of the text input.
9691 * This only affects #multiline inputs that are {@link #autosize autosized}.
9696 OO
.ui
.TextInputWidget
.prototype.adjustSize = function () {
9697 var scrollHeight
, innerHeight
, outerHeight
, maxInnerHeight
, measurementError
,
9698 idealHeight
, newHeight
, scrollWidth
, property
;
9700 if ( this.isWaitingToBeAttached
) {
9701 // #onElementAttach will be called soon, which calls this method
9705 if ( this.multiline
&& this.$input
.val() !== this.valCache
) {
9706 if ( this.autosize
) {
9708 .val( this.$input
.val() )
9709 .attr( 'rows', this.minRows
)
9710 // Set inline height property to 0 to measure scroll height
9711 .css( 'height', 0 );
9713 this.$clone
.removeClass( 'oo-ui-element-hidden' );
9715 this.valCache
= this.$input
.val();
9717 scrollHeight
= this.$clone
[ 0 ].scrollHeight
;
9719 // Remove inline height property to measure natural heights
9720 this.$clone
.css( 'height', '' );
9721 innerHeight
= this.$clone
.innerHeight();
9722 outerHeight
= this.$clone
.outerHeight();
9724 // Measure max rows height
9726 .attr( 'rows', this.maxRows
)
9727 .css( 'height', 'auto' )
9729 maxInnerHeight
= this.$clone
.innerHeight();
9731 // Difference between reported innerHeight and scrollHeight with no scrollbars present.
9732 // This is sometimes non-zero on Blink-based browsers, depending on zoom level.
9733 measurementError
= maxInnerHeight
- this.$clone
[ 0 ].scrollHeight
;
9734 idealHeight
= Math
.min( maxInnerHeight
, scrollHeight
+ measurementError
);
9736 this.$clone
.addClass( 'oo-ui-element-hidden' );
9738 // Only apply inline height when expansion beyond natural height is needed
9739 // Use the difference between the inner and outer height as a buffer
9740 newHeight
= idealHeight
> innerHeight
? idealHeight
+ ( outerHeight
- innerHeight
) : '';
9741 if ( newHeight
!== this.styleHeight
) {
9742 this.$input
.css( 'height', newHeight
);
9743 this.styleHeight
= newHeight
;
9744 this.emit( 'resize' );
9747 scrollWidth
= this.$input
[ 0 ].offsetWidth
- this.$input
[ 0 ].clientWidth
;
9748 if ( scrollWidth
!== this.scrollWidth
) {
9749 property
= this.$element
.css( 'direction' ) === 'rtl' ? 'left' : 'right';
9751 this.$label
.css( { right
: '', left
: '' } );
9752 this.$indicator
.css( { right
: '', left
: '' } );
9754 if ( scrollWidth
) {
9755 this.$indicator
.css( property
, scrollWidth
);
9756 if ( this.labelPosition
=== 'after' ) {
9757 this.$label
.css( property
, scrollWidth
);
9761 this.scrollWidth
= scrollWidth
;
9762 this.positionLabel();
9772 OO
.ui
.TextInputWidget
.prototype.getInputElement = function ( config
) {
9773 if ( config
.multiline
) {
9774 return $( '<textarea>' );
9775 } else if ( this.getSaneType( config
) === 'number' ) {
9776 return $( '<input>' )
9777 .attr( 'step', 'any' )
9778 .attr( 'type', 'number' );
9780 return $( '<input>' ).attr( 'type', this.getSaneType( config
) );
9785 * Get sanitized value for 'type' for given config.
9787 * @param {Object} config Configuration options
9788 * @return {string|null}
9791 OO
.ui
.TextInputWidget
.prototype.getSaneType = function ( config
) {
9792 var allowedTypes
= [
9800 return allowedTypes
.indexOf( config
.type
) !== -1 ? config
.type
: 'text';
9804 * Check if the input supports multiple lines.
9808 OO
.ui
.TextInputWidget
.prototype.isMultiline = function () {
9809 return !!this.multiline
;
9813 * Check if the input automatically adjusts its size.
9817 OO
.ui
.TextInputWidget
.prototype.isAutosizing = function () {
9818 return !!this.autosize
;
9822 * Focus the input and select a specified range within the text.
9824 * @param {number} from Select from offset
9825 * @param {number} [to] Select to offset, defaults to from
9828 OO
.ui
.TextInputWidget
.prototype.selectRange = function ( from, to
) {
9829 var isBackwards
, start
, end
,
9830 input
= this.$input
[ 0 ];
9834 isBackwards
= to
< from;
9835 start
= isBackwards
? to
: from;
9836 end
= isBackwards
? from : to
;
9841 input
.setSelectionRange( start
, end
, isBackwards
? 'backward' : 'forward' );
9843 // IE throws an exception if you call setSelectionRange on a unattached DOM node.
9844 // Rather than expensively check if the input is attached every time, just check
9845 // if it was the cause of an error being thrown. If not, rethrow the error.
9846 if ( this.getElementDocument().body
.contains( input
) ) {
9854 * Get an object describing the current selection range in a directional manner
9856 * @return {Object} Object containing 'from' and 'to' offsets
9858 OO
.ui
.TextInputWidget
.prototype.getRange = function () {
9859 var input
= this.$input
[ 0 ],
9860 start
= input
.selectionStart
,
9861 end
= input
.selectionEnd
,
9862 isBackwards
= input
.selectionDirection
=== 'backward';
9865 from: isBackwards
? end
: start
,
9866 to
: isBackwards
? start
: end
9871 * Get the length of the text input value.
9873 * This could differ from the length of #getValue if the
9874 * value gets filtered
9876 * @return {number} Input length
9878 OO
.ui
.TextInputWidget
.prototype.getInputLength = function () {
9879 return this.$input
[ 0 ].value
.length
;
9883 * Focus the input and select the entire text.
9887 OO
.ui
.TextInputWidget
.prototype.select = function () {
9888 return this.selectRange( 0, this.getInputLength() );
9892 * Focus the input and move the cursor to the start.
9896 OO
.ui
.TextInputWidget
.prototype.moveCursorToStart = function () {
9897 return this.selectRange( 0 );
9901 * Focus the input and move the cursor to the end.
9905 OO
.ui
.TextInputWidget
.prototype.moveCursorToEnd = function () {
9906 return this.selectRange( this.getInputLength() );
9910 * Insert new content into the input.
9912 * @param {string} content Content to be inserted
9915 OO
.ui
.TextInputWidget
.prototype.insertContent = function ( content
) {
9917 range
= this.getRange(),
9918 value
= this.getValue();
9920 start
= Math
.min( range
.from, range
.to
);
9921 end
= Math
.max( range
.from, range
.to
);
9923 this.setValue( value
.slice( 0, start
) + content
+ value
.slice( end
) );
9924 this.selectRange( start
+ content
.length
);
9929 * Insert new content either side of a selection.
9931 * @param {string} pre Content to be inserted before the selection
9932 * @param {string} post Content to be inserted after the selection
9935 OO
.ui
.TextInputWidget
.prototype.encapsulateContent = function ( pre
, post
) {
9937 range
= this.getRange(),
9938 offset
= pre
.length
;
9940 start
= Math
.min( range
.from, range
.to
);
9941 end
= Math
.max( range
.from, range
.to
);
9943 this.selectRange( start
).insertContent( pre
);
9944 this.selectRange( offset
+ end
).insertContent( post
);
9946 this.selectRange( offset
+ start
, offset
+ end
);
9951 * Set the validation pattern.
9953 * The validation pattern is either a regular expression, a function, or the symbolic name of a
9954 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer' (the
9955 * value must contain only numbers).
9957 * @param {RegExp|Function|string|null} validate Regular expression, function, or the symbolic name
9958 * of a pattern (either ‘integer’ or ‘non-empty’) defined by the class.
9960 OO
.ui
.TextInputWidget
.prototype.setValidation = function ( validate
) {
9961 if ( validate
instanceof RegExp
|| validate
instanceof Function
) {
9962 this.validate
= validate
;
9964 this.validate
= this.constructor.static.validationPatterns
[ validate
] || /.*/;
9969 * Sets the 'invalid' flag appropriately.
9971 * @param {boolean} [isValid] Optionally override validation result
9973 OO
.ui
.TextInputWidget
.prototype.setValidityFlag = function ( isValid
) {
9975 setFlag = function ( valid
) {
9977 widget
.$input
.attr( 'aria-invalid', 'true' );
9979 widget
.$input
.removeAttr( 'aria-invalid' );
9981 widget
.setFlags( { invalid
: !valid
} );
9984 if ( isValid
!== undefined ) {
9987 this.getValidity().then( function () {
9996 * Get the validity of current value.
9998 * This method returns a promise that resolves if the value is valid and rejects if
9999 * it isn't. Uses the {@link #validate validation pattern} to check for validity.
10001 * @return {jQuery.Promise} A promise that resolves if the value is valid, rejects if not.
10003 OO
.ui
.TextInputWidget
.prototype.getValidity = function () {
10006 function rejectOrResolve( valid
) {
10008 return $.Deferred().resolve().promise();
10010 return $.Deferred().reject().promise();
10014 // Check browser validity and reject if it is invalid
10016 this.$input
[ 0 ].checkValidity
!== undefined &&
10017 this.$input
[ 0 ].checkValidity() === false
10019 return rejectOrResolve( false );
10022 // Run our checks if the browser thinks the field is valid
10023 if ( this.validate
instanceof Function
) {
10024 result
= this.validate( this.getValue() );
10025 if ( result
&& $.isFunction( result
.promise
) ) {
10026 return result
.promise().then( function ( valid
) {
10027 return rejectOrResolve( valid
);
10030 return rejectOrResolve( result
);
10033 return rejectOrResolve( this.getValue().match( this.validate
) );
10038 * Set the position of the inline label relative to that of the value: `‘before’` or `‘after’`.
10040 * @param {string} labelPosition Label position, 'before' or 'after'
10043 OO
.ui
.TextInputWidget
.prototype.setLabelPosition = function ( labelPosition
) {
10044 this.labelPosition
= labelPosition
;
10045 if ( this.label
) {
10046 // If there is no label and we only change the position, #updatePosition is a no-op,
10047 // but it takes really a lot of work to do nothing.
10048 this.updatePosition();
10054 * Update the position of the inline label.
10056 * This method is called by #setLabelPosition, and can also be called on its own if
10057 * something causes the label to be mispositioned.
10061 OO
.ui
.TextInputWidget
.prototype.updatePosition = function () {
10062 var after
= this.labelPosition
=== 'after';
10065 .toggleClass( 'oo-ui-textInputWidget-labelPosition-after', !!this.label
&& after
)
10066 .toggleClass( 'oo-ui-textInputWidget-labelPosition-before', !!this.label
&& !after
);
10068 this.valCache
= null;
10069 this.scrollWidth
= null;
10071 this.positionLabel();
10077 * Update the 'clear' indicator displayed on type: 'search' text fields, hiding it when the field is
10078 * already empty or when it's not editable.
10080 OO
.ui
.TextInputWidget
.prototype.updateSearchIndicator = function () {
10081 if ( this.type
=== 'search' ) {
10082 if ( this.getValue() === '' || this.isDisabled() || this.isReadOnly() ) {
10083 this.setIndicator( null );
10085 this.setIndicator( 'clear' );
10091 * Position the label by setting the correct padding on the input.
10096 OO
.ui
.TextInputWidget
.prototype.positionLabel = function () {
10097 var after
, rtl
, property
;
10099 if ( this.isWaitingToBeAttached
) {
10100 // #onElementAttach will be called soon, which calls this method
10104 // Clear old values
10106 // Clear old values if present
10108 'padding-right': '',
10112 if ( this.label
) {
10113 this.$element
.append( this.$label
);
10115 this.$label
.detach();
10119 after
= this.labelPosition
=== 'after';
10120 rtl
= this.$element
.css( 'direction' ) === 'rtl';
10121 property
= after
=== rtl
? 'padding-left' : 'padding-right';
10123 this.$input
.css( property
, this.$label
.outerWidth( true ) + ( after
? this.scrollWidth
: 0 ) );
10131 OO
.ui
.TextInputWidget
.prototype.restorePreInfuseState = function ( state
) {
10132 OO
.ui
.TextInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
10133 if ( state
.scrollTop
!== undefined ) {
10134 this.$input
.scrollTop( state
.scrollTop
);
10140 * @extends OO.ui.TextInputWidget
10143 * @param {Object} [config] Configuration options
10145 OO
.ui
.SearchInputWidget
= function OoUiSearchInputWidget( config
) {
10146 config
= $.extend( {
10150 // Set type to text so that TextInputWidget doesn't
10151 // get stuck in an infinite loop.
10152 config
.type
= 'text';
10154 // Parent constructor
10155 OO
.ui
.SearchInputWidget
.parent
.call( this, config
);
10158 this.$element
.addClass( 'oo-ui-textInputWidget-type-search' );
10159 this.updateSearchIndicator();
10160 this.connect( this, {
10161 disable
: 'onDisable'
10167 OO
.inheritClass( OO
.ui
.SearchInputWidget
, OO
.ui
.TextInputWidget
);
10175 OO
.ui
.SearchInputWidget
.prototype.getInputElement = function () {
10176 return $( '<input>' ).attr( 'type', 'search' );
10182 OO
.ui
.SearchInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
10183 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
10184 // Clear the text field
10185 this.setValue( '' );
10186 this.$input
[ 0 ].focus();
10192 * Update the 'clear' indicator displayed on type: 'search' text
10193 * fields, hiding it when the field is already empty or when it's not
10196 OO
.ui
.SearchInputWidget
.prototype.updateSearchIndicator = function () {
10197 if ( this.getValue() === '' || this.isDisabled() || this.isReadOnly() ) {
10198 this.setIndicator( null );
10200 this.setIndicator( 'clear' );
10207 OO
.ui
.SearchInputWidget
.prototype.onChange = function () {
10208 OO
.ui
.SearchInputWidget
.parent
.prototype.onChange
.call( this );
10209 this.updateSearchIndicator();
10213 * Handle disable events.
10215 * @param {boolean} disabled Element is disabled
10218 OO
.ui
.SearchInputWidget
.prototype.onDisable = function () {
10219 this.updateSearchIndicator();
10225 OO
.ui
.SearchInputWidget
.prototype.setReadOnly = function ( state
) {
10226 OO
.ui
.SearchInputWidget
.parent
.prototype.setReadOnly
.call( this, state
);
10227 this.updateSearchIndicator();
10232 * ComboBoxInputWidgets combine a {@link OO.ui.TextInputWidget text input} (where a value
10233 * can be entered manually) and a {@link OO.ui.MenuSelectWidget menu of options} (from which
10234 * a value can be chosen instead). Users can choose options from the combo box in one of two ways:
10236 * - by typing a value in the text input field. If the value exactly matches the value of a menu
10237 * option, that option will appear to be selected.
10238 * - by choosing a value from the menu. The value of the chosen option will then appear in the text
10241 * After the user chooses an option, its `data` will be used as a new value for the widget.
10242 * A `label` also can be specified for each option: if given, it will be shown instead of the
10243 * `data` in the dropdown menu.
10245 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
10247 * For more information about menus and options, please see the [OOjs UI documentation on MediaWiki][1].
10250 * // Example: A ComboBoxInputWidget.
10251 * var comboBox = new OO.ui.ComboBoxInputWidget( {
10252 * value: 'Option 1',
10254 * { data: 'Option 1' },
10255 * { data: 'Option 2' },
10256 * { data: 'Option 3' }
10259 * $( 'body' ).append( comboBox.$element );
10262 * // Example: A ComboBoxInputWidget with additional option labels.
10263 * var comboBox = new OO.ui.ComboBoxInputWidget( {
10264 * value: 'Option 1',
10267 * data: 'Option 1',
10268 * label: 'Option One'
10271 * data: 'Option 2',
10272 * label: 'Option Two'
10275 * data: 'Option 3',
10276 * label: 'Option Three'
10280 * $( 'body' ).append( comboBox.$element );
10282 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
10285 * @extends OO.ui.TextInputWidget
10288 * @param {Object} [config] Configuration options
10289 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
10290 * @cfg {Object} [menu] Configuration options to pass to the {@link OO.ui.FloatingMenuSelectWidget menu select widget}.
10291 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
10292 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
10293 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
10295 OO
.ui
.ComboBoxInputWidget
= function OoUiComboBoxInputWidget( config
) {
10296 // Configuration initialization
10297 config
= $.extend( {
10298 autocomplete
: false
10301 // ComboBoxInputWidget shouldn't support `multiline`
10302 config
.multiline
= false;
10304 // See InputWidget#reusePreInfuseDOM about `config.$input`
10305 if ( config
.$input
) {
10306 config
.$input
.removeAttr( 'list' );
10309 // Parent constructor
10310 OO
.ui
.ComboBoxInputWidget
.parent
.call( this, config
);
10313 this.$overlay
= config
.$overlay
|| this.$element
;
10314 this.dropdownButton
= new OO
.ui
.ButtonWidget( {
10315 classes
: [ 'oo-ui-comboBoxInputWidget-dropdownButton' ],
10317 disabled
: this.disabled
10319 this.menu
= new OO
.ui
.FloatingMenuSelectWidget( $.extend(
10323 $container
: this.$element
,
10324 disabled
: this.isDisabled()
10330 this.connect( this, {
10331 change
: 'onInputChange',
10332 enter
: 'onInputEnter'
10334 this.dropdownButton
.connect( this, {
10335 click
: 'onDropdownButtonClick'
10337 this.menu
.connect( this, {
10338 choose
: 'onMenuChoose',
10339 add
: 'onMenuItemsChange',
10340 remove
: 'onMenuItemsChange'
10344 this.$input
.attr( {
10346 'aria-autocomplete': 'list'
10348 // Do not override options set via config.menu.items
10349 if ( config
.options
!== undefined ) {
10350 this.setOptions( config
.options
);
10352 this.$field
= $( '<div>' )
10353 .addClass( 'oo-ui-comboBoxInputWidget-field' )
10354 .append( this.$input
, this.dropdownButton
.$element
);
10356 .addClass( 'oo-ui-comboBoxInputWidget' )
10357 .append( this.$field
);
10358 this.$overlay
.append( this.menu
.$element
);
10359 this.onMenuItemsChange();
10364 OO
.inheritClass( OO
.ui
.ComboBoxInputWidget
, OO
.ui
.TextInputWidget
);
10369 * Get the combobox's menu.
10371 * @return {OO.ui.FloatingMenuSelectWidget} Menu widget
10373 OO
.ui
.ComboBoxInputWidget
.prototype.getMenu = function () {
10378 * Get the combobox's text input widget.
10380 * @return {OO.ui.TextInputWidget} Text input widget
10382 OO
.ui
.ComboBoxInputWidget
.prototype.getInput = function () {
10387 * Handle input change events.
10390 * @param {string} value New value
10392 OO
.ui
.ComboBoxInputWidget
.prototype.onInputChange = function ( value
) {
10393 var match
= this.menu
.getItemFromData( value
);
10395 this.menu
.selectItem( match
);
10396 if ( this.menu
.getHighlightedItem() ) {
10397 this.menu
.highlightItem( match
);
10400 if ( !this.isDisabled() ) {
10401 this.menu
.toggle( true );
10406 * Handle input enter events.
10410 OO
.ui
.ComboBoxInputWidget
.prototype.onInputEnter = function () {
10411 if ( !this.isDisabled() ) {
10412 this.menu
.toggle( false );
10417 * Handle button click events.
10421 OO
.ui
.ComboBoxInputWidget
.prototype.onDropdownButtonClick = function () {
10422 this.menu
.toggle();
10423 this.$input
[ 0 ].focus();
10427 * Handle menu choose events.
10430 * @param {OO.ui.OptionWidget} item Chosen item
10432 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuChoose = function ( item
) {
10433 this.setValue( item
.getData() );
10437 * Handle menu item change events.
10441 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuItemsChange = function () {
10442 var match
= this.menu
.getItemFromData( this.getValue() );
10443 this.menu
.selectItem( match
);
10444 if ( this.menu
.getHighlightedItem() ) {
10445 this.menu
.highlightItem( match
);
10447 this.$element
.toggleClass( 'oo-ui-comboBoxInputWidget-empty', this.menu
.isEmpty() );
10453 OO
.ui
.ComboBoxInputWidget
.prototype.setDisabled = function ( disabled
) {
10455 OO
.ui
.ComboBoxInputWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
10457 if ( this.dropdownButton
) {
10458 this.dropdownButton
.setDisabled( this.isDisabled() );
10461 this.menu
.setDisabled( this.isDisabled() );
10468 * Set the options available for this input.
10470 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
10473 OO
.ui
.ComboBoxInputWidget
.prototype.setOptions = function ( options
) {
10476 .addItems( options
.map( function ( opt
) {
10477 return new OO
.ui
.MenuOptionWidget( {
10479 label
: opt
.label
!== undefined ? opt
.label
: opt
.data
10487 * FieldLayouts are used with OO.ui.FieldsetLayout. Each FieldLayout requires a field-widget,
10488 * which is a widget that is specified by reference before any optional configuration settings.
10490 * Field layouts can be configured with help text and/or labels. Labels are aligned in one of four ways:
10492 * - **left**: The label is placed before the field-widget and aligned with the left margin.
10493 * A left-alignment is used for forms with many fields.
10494 * - **right**: The label is placed before the field-widget and aligned to the right margin.
10495 * A right-alignment is used for long but familiar forms which users tab through,
10496 * verifying the current field with a quick glance at the label.
10497 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
10498 * that users fill out from top to bottom.
10499 * - **inline**: The label is placed after the field-widget and aligned to the left.
10500 * An inline-alignment is best used with checkboxes or radio buttons.
10502 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout.
10503 * Please see the [OOjs UI documentation on MediaWiki] [1] for examples and more information.
10505 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
10508 * @extends OO.ui.Layout
10509 * @mixins OO.ui.mixin.LabelElement
10510 * @mixins OO.ui.mixin.TitledElement
10513 * @param {OO.ui.Widget} fieldWidget Field widget
10514 * @param {Object} [config] Configuration options
10515 * @cfg {string} [align='left'] Alignment of the label: 'left', 'right', 'top' or 'inline'
10516 * @cfg {Array} [errors] Error messages about the widget, which will be displayed below the widget.
10517 * The array may contain strings or OO.ui.HtmlSnippet instances.
10518 * @cfg {Array} [notices] Notices about the widget, which will be displayed below the widget.
10519 * The array may contain strings or OO.ui.HtmlSnippet instances.
10520 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified, a "help" icon will appear
10521 * in the upper-right corner of the rendered field; clicking it will display the text in a popup.
10522 * For important messages, you are advised to use `notices`, as they are always shown.
10523 * @cfg {jQuery} [$overlay] Passed to OO.ui.PopupButtonWidget for help popup, if `help` is given.
10525 * @throws {Error} An error is thrown if no widget is specified
10527 OO
.ui
.FieldLayout
= function OoUiFieldLayout( fieldWidget
, config
) {
10528 // Allow passing positional parameters inside the config object
10529 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
10530 config
= fieldWidget
;
10531 fieldWidget
= config
.fieldWidget
;
10534 // Make sure we have required constructor arguments
10535 if ( fieldWidget
=== undefined ) {
10536 throw new Error( 'Widget not found' );
10539 // Configuration initialization
10540 config
= $.extend( { align
: 'left' }, config
);
10542 // Parent constructor
10543 OO
.ui
.FieldLayout
.parent
.call( this, config
);
10545 // Mixin constructors
10546 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, {
10547 $label
: $( '<label>' )
10549 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
10552 this.fieldWidget
= fieldWidget
;
10555 this.$field
= this.isFieldInline() ? $( '<span>' ) : $( '<div>' );
10556 this.$messages
= $( '<ul>' );
10557 this.$header
= $( '<span>' );
10558 this.$body
= $( '<div>' );
10560 if ( config
.help
) {
10561 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
10562 $overlay
: config
.$overlay
,
10566 classes
: [ 'oo-ui-fieldLayout-help' ],
10570 if ( config
.help
instanceof OO
.ui
.HtmlSnippet
) {
10571 this.popupButtonWidget
.getPopup().$body
.html( config
.help
.toString() );
10573 this.popupButtonWidget
.getPopup().$body
.text( config
.help
);
10575 this.$help
= this.popupButtonWidget
.$element
;
10577 this.$help
= $( [] );
10581 this.fieldWidget
.connect( this, { disable
: 'onFieldDisable' } );
10584 if ( fieldWidget
.constructor.static.supportsSimpleLabel
) {
10585 if ( this.fieldWidget
.getInputId() ) {
10586 this.$label
.attr( 'for', this.fieldWidget
.getInputId() );
10588 this.$label
.on( 'click', function () {
10589 this.fieldWidget
.focus();
10595 .addClass( 'oo-ui-fieldLayout' )
10596 .toggleClass( 'oo-ui-fieldLayout-disabled', this.fieldWidget
.isDisabled() )
10597 .append( this.$body
);
10598 this.$body
.addClass( 'oo-ui-fieldLayout-body' );
10599 this.$header
.addClass( 'oo-ui-fieldLayout-header' );
10600 this.$messages
.addClass( 'oo-ui-fieldLayout-messages' );
10602 .addClass( 'oo-ui-fieldLayout-field' )
10603 .append( this.fieldWidget
.$element
);
10605 this.setErrors( config
.errors
|| [] );
10606 this.setNotices( config
.notices
|| [] );
10607 this.setAlignment( config
.align
);
10612 OO
.inheritClass( OO
.ui
.FieldLayout
, OO
.ui
.Layout
);
10613 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.LabelElement
);
10614 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.TitledElement
);
10619 * Handle field disable events.
10622 * @param {boolean} value Field is disabled
10624 OO
.ui
.FieldLayout
.prototype.onFieldDisable = function ( value
) {
10625 this.$element
.toggleClass( 'oo-ui-fieldLayout-disabled', value
);
10629 * Get the widget contained by the field.
10631 * @return {OO.ui.Widget} Field widget
10633 OO
.ui
.FieldLayout
.prototype.getField = function () {
10634 return this.fieldWidget
;
10638 * Return `true` if the given field widget can be used with `'inline'` alignment (see
10639 * #setAlignment). Return `false` if it can't or if this can't be determined.
10641 * @return {boolean}
10643 OO
.ui
.FieldLayout
.prototype.isFieldInline = function () {
10644 // This is very simplistic, but should be good enough.
10645 return this.getField().$element
.prop( 'tagName' ).toLowerCase() === 'span';
10650 * @param {string} kind 'error' or 'notice'
10651 * @param {string|OO.ui.HtmlSnippet} text
10654 OO
.ui
.FieldLayout
.prototype.makeMessage = function ( kind
, text
) {
10655 var $listItem
, $icon
, message
;
10656 $listItem
= $( '<li>' );
10657 if ( kind
=== 'error' ) {
10658 $icon
= new OO
.ui
.IconWidget( { icon
: 'alert', flags
: [ 'warning' ] } ).$element
;
10659 } else if ( kind
=== 'notice' ) {
10660 $icon
= new OO
.ui
.IconWidget( { icon
: 'info' } ).$element
;
10664 message
= new OO
.ui
.LabelWidget( { label
: text
} );
10666 .append( $icon
, message
.$element
)
10667 .addClass( 'oo-ui-fieldLayout-messages-' + kind
);
10672 * Set the field alignment mode.
10675 * @param {string} value Alignment mode, either 'left', 'right', 'top' or 'inline'
10678 OO
.ui
.FieldLayout
.prototype.setAlignment = function ( value
) {
10679 if ( value
!== this.align
) {
10680 // Default to 'left'
10681 if ( [ 'left', 'right', 'top', 'inline' ].indexOf( value
) === -1 ) {
10685 if ( value
=== 'inline' && !this.isFieldInline() ) {
10688 // Reorder elements
10689 if ( value
=== 'top' ) {
10690 this.$header
.append( this.$label
, this.$help
);
10691 this.$body
.append( this.$header
, this.$field
);
10692 } else if ( value
=== 'inline' ) {
10693 this.$header
.append( this.$label
, this.$help
);
10694 this.$body
.append( this.$field
, this.$header
);
10696 this.$header
.append( this.$label
);
10697 this.$body
.append( this.$header
, this.$help
, this.$field
);
10699 // Set classes. The following classes can be used here:
10700 // * oo-ui-fieldLayout-align-left
10701 // * oo-ui-fieldLayout-align-right
10702 // * oo-ui-fieldLayout-align-top
10703 // * oo-ui-fieldLayout-align-inline
10704 if ( this.align
) {
10705 this.$element
.removeClass( 'oo-ui-fieldLayout-align-' + this.align
);
10707 this.$element
.addClass( 'oo-ui-fieldLayout-align-' + value
);
10708 this.align
= value
;
10715 * Set the list of error messages.
10717 * @param {Array} errors Error messages about the widget, which will be displayed below the widget.
10718 * The array may contain strings or OO.ui.HtmlSnippet instances.
10721 OO
.ui
.FieldLayout
.prototype.setErrors = function ( errors
) {
10722 this.errors
= errors
.slice();
10723 this.updateMessages();
10728 * Set the list of notice messages.
10730 * @param {Array} notices Notices about the widget, which will be displayed below the widget.
10731 * The array may contain strings or OO.ui.HtmlSnippet instances.
10734 OO
.ui
.FieldLayout
.prototype.setNotices = function ( notices
) {
10735 this.notices
= notices
.slice();
10736 this.updateMessages();
10741 * Update the rendering of error and notice messages.
10745 OO
.ui
.FieldLayout
.prototype.updateMessages = function () {
10747 this.$messages
.empty();
10749 if ( this.errors
.length
|| this.notices
.length
) {
10750 this.$body
.after( this.$messages
);
10752 this.$messages
.remove();
10756 for ( i
= 0; i
< this.notices
.length
; i
++ ) {
10757 this.$messages
.append( this.makeMessage( 'notice', this.notices
[ i
] ) );
10759 for ( i
= 0; i
< this.errors
.length
; i
++ ) {
10760 this.$messages
.append( this.makeMessage( 'error', this.errors
[ i
] ) );
10765 * ActionFieldLayouts are used with OO.ui.FieldsetLayout. The layout consists of a field-widget, a button,
10766 * and an optional label and/or help text. The field-widget (e.g., a {@link OO.ui.TextInputWidget TextInputWidget}),
10767 * is required and is specified before any optional configuration settings.
10769 * Labels can be aligned in one of four ways:
10771 * - **left**: The label is placed before the field-widget and aligned with the left margin.
10772 * A left-alignment is used for forms with many fields.
10773 * - **right**: The label is placed before the field-widget and aligned to the right margin.
10774 * A right-alignment is used for long but familiar forms which users tab through,
10775 * verifying the current field with a quick glance at the label.
10776 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
10777 * that users fill out from top to bottom.
10778 * - **inline**: The label is placed after the field-widget and aligned to the left.
10779 * An inline-alignment is best used with checkboxes or radio buttons.
10781 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout when help
10782 * text is specified.
10785 * // Example of an ActionFieldLayout
10786 * var actionFieldLayout = new OO.ui.ActionFieldLayout(
10787 * new OO.ui.TextInputWidget( {
10788 * placeholder: 'Field widget'
10790 * new OO.ui.ButtonWidget( {
10794 * label: 'An ActionFieldLayout. This label is aligned top',
10796 * help: 'This is help text'
10800 * $( 'body' ).append( actionFieldLayout.$element );
10803 * @extends OO.ui.FieldLayout
10806 * @param {OO.ui.Widget} fieldWidget Field widget
10807 * @param {OO.ui.ButtonWidget} buttonWidget Button widget
10808 * @param {Object} config
10810 OO
.ui
.ActionFieldLayout
= function OoUiActionFieldLayout( fieldWidget
, buttonWidget
, config
) {
10811 // Allow passing positional parameters inside the config object
10812 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
10813 config
= fieldWidget
;
10814 fieldWidget
= config
.fieldWidget
;
10815 buttonWidget
= config
.buttonWidget
;
10818 // Parent constructor
10819 OO
.ui
.ActionFieldLayout
.parent
.call( this, fieldWidget
, config
);
10822 this.buttonWidget
= buttonWidget
;
10823 this.$button
= $( '<span>' );
10824 this.$input
= this.isFieldInline() ? $( '<span>' ) : $( '<div>' );
10828 .addClass( 'oo-ui-actionFieldLayout' );
10830 .addClass( 'oo-ui-actionFieldLayout-button' )
10831 .append( this.buttonWidget
.$element
);
10833 .addClass( 'oo-ui-actionFieldLayout-input' )
10834 .append( this.fieldWidget
.$element
);
10836 .append( this.$input
, this.$button
);
10841 OO
.inheritClass( OO
.ui
.ActionFieldLayout
, OO
.ui
.FieldLayout
);
10844 * FieldsetLayouts are composed of one or more {@link OO.ui.FieldLayout FieldLayouts},
10845 * which each contain an individual widget and, optionally, a label. Each Fieldset can be
10846 * configured with a label as well. For more information and examples,
10847 * please see the [OOjs UI documentation on MediaWiki][1].
10850 * // Example of a fieldset layout
10851 * var input1 = new OO.ui.TextInputWidget( {
10852 * placeholder: 'A text input field'
10855 * var input2 = new OO.ui.TextInputWidget( {
10856 * placeholder: 'A text input field'
10859 * var fieldset = new OO.ui.FieldsetLayout( {
10860 * label: 'Example of a fieldset layout'
10863 * fieldset.addItems( [
10864 * new OO.ui.FieldLayout( input1, {
10865 * label: 'Field One'
10867 * new OO.ui.FieldLayout( input2, {
10868 * label: 'Field Two'
10871 * $( 'body' ).append( fieldset.$element );
10873 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
10876 * @extends OO.ui.Layout
10877 * @mixins OO.ui.mixin.IconElement
10878 * @mixins OO.ui.mixin.LabelElement
10879 * @mixins OO.ui.mixin.GroupElement
10882 * @param {Object} [config] Configuration options
10883 * @cfg {OO.ui.FieldLayout[]} [items] An array of fields to add to the fieldset. See OO.ui.FieldLayout for more information about fields.
10884 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified, a "help" icon will appear
10885 * in the upper-right corner of the rendered field; clicking it will display the text in a popup.
10886 * For important messages, you are advised to use `notices`, as they are always shown.
10887 * @cfg {jQuery} [$overlay] Passed to OO.ui.PopupButtonWidget for help popup, if `help` is given.
10889 OO
.ui
.FieldsetLayout
= function OoUiFieldsetLayout( config
) {
10890 // Configuration initialization
10891 config
= config
|| {};
10893 // Parent constructor
10894 OO
.ui
.FieldsetLayout
.parent
.call( this, config
);
10896 // Mixin constructors
10897 OO
.ui
.mixin
.IconElement
.call( this, config
);
10898 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, { $label
: $( '<div>' ) } ) );
10899 OO
.ui
.mixin
.GroupElement
.call( this, config
);
10902 this.$header
= $( '<div>' );
10903 if ( config
.help
) {
10904 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
10905 $overlay
: config
.$overlay
,
10909 classes
: [ 'oo-ui-fieldsetLayout-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
= $( [] );
10925 .addClass( 'oo-ui-fieldsetLayout-header' )
10926 .append( this.$icon
, this.$label
, this.$help
);
10927 this.$group
.addClass( 'oo-ui-fieldsetLayout-group' );
10929 .addClass( 'oo-ui-fieldsetLayout' )
10930 .prepend( this.$header
, this.$group
);
10931 if ( Array
.isArray( config
.items
) ) {
10932 this.addItems( config
.items
);
10938 OO
.inheritClass( OO
.ui
.FieldsetLayout
, OO
.ui
.Layout
);
10939 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.IconElement
);
10940 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.LabelElement
);
10941 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.GroupElement
);
10943 /* Static Properties */
10949 OO
.ui
.FieldsetLayout
.static.tagName
= 'fieldset';
10952 * FormLayouts are used to wrap {@link OO.ui.FieldsetLayout FieldsetLayouts} when you intend to use browser-based
10953 * form submission for the fields instead of handling them in JavaScript. Form layouts can be configured with an
10954 * HTML form action, an encoding type, and a method using the #action, #enctype, and #method configs, respectively.
10955 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
10957 * Only widgets from the {@link OO.ui.InputWidget InputWidget} family support form submission. It
10958 * includes standard form elements like {@link OO.ui.CheckboxInputWidget checkboxes}, {@link
10959 * OO.ui.RadioInputWidget radio buttons} and {@link OO.ui.TextInputWidget text fields}, as well as
10960 * some fancier controls. Some controls have both regular and InputWidget variants, for example
10961 * OO.ui.DropdownWidget and OO.ui.DropdownInputWidget – only the latter support form submission and
10962 * often have simplified APIs to match the capabilities of HTML forms.
10963 * See the [OOjs UI Inputs documentation on MediaWiki] [2] for more information about InputWidgets.
10965 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Forms
10966 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
10969 * // Example of a form layout that wraps a fieldset layout
10970 * var input1 = new OO.ui.TextInputWidget( {
10971 * placeholder: 'Username'
10973 * var input2 = new OO.ui.TextInputWidget( {
10974 * placeholder: 'Password',
10977 * var submit = new OO.ui.ButtonInputWidget( {
10981 * var fieldset = new OO.ui.FieldsetLayout( {
10982 * label: 'A form layout'
10984 * fieldset.addItems( [
10985 * new OO.ui.FieldLayout( input1, {
10986 * label: 'Username',
10989 * new OO.ui.FieldLayout( input2, {
10990 * label: 'Password',
10993 * new OO.ui.FieldLayout( submit )
10995 * var form = new OO.ui.FormLayout( {
10996 * items: [ fieldset ],
10997 * action: '/api/formhandler',
11000 * $( 'body' ).append( form.$element );
11003 * @extends OO.ui.Layout
11004 * @mixins OO.ui.mixin.GroupElement
11007 * @param {Object} [config] Configuration options
11008 * @cfg {string} [method] HTML form `method` attribute
11009 * @cfg {string} [action] HTML form `action` attribute
11010 * @cfg {string} [enctype] HTML form `enctype` attribute
11011 * @cfg {OO.ui.FieldsetLayout[]} [items] Fieldset layouts to add to the form layout.
11013 OO
.ui
.FormLayout
= function OoUiFormLayout( config
) {
11016 // Configuration initialization
11017 config
= config
|| {};
11019 // Parent constructor
11020 OO
.ui
.FormLayout
.parent
.call( this, config
);
11022 // Mixin constructors
11023 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
11026 this.$element
.on( 'submit', this.onFormSubmit
.bind( this ) );
11028 // Make sure the action is safe
11029 action
= config
.action
;
11030 if ( action
!== undefined && !OO
.ui
.isSafeUrl( action
) ) {
11031 action
= './' + action
;
11036 .addClass( 'oo-ui-formLayout' )
11038 method
: config
.method
,
11040 enctype
: config
.enctype
11042 if ( Array
.isArray( config
.items
) ) {
11043 this.addItems( config
.items
);
11049 OO
.inheritClass( OO
.ui
.FormLayout
, OO
.ui
.Layout
);
11050 OO
.mixinClass( OO
.ui
.FormLayout
, OO
.ui
.mixin
.GroupElement
);
11055 * A 'submit' event is emitted when the form is submitted.
11060 /* Static Properties */
11066 OO
.ui
.FormLayout
.static.tagName
= 'form';
11071 * Handle form submit events.
11074 * @param {jQuery.Event} e Submit event
11077 OO
.ui
.FormLayout
.prototype.onFormSubmit = function () {
11078 if ( this.emit( 'submit' ) ) {
11084 * PanelLayouts expand to cover the entire area of their parent. They can be configured with scrolling, padding,
11085 * and a frame, and are often used together with {@link OO.ui.StackLayout StackLayouts}.
11088 * // Example of a panel layout
11089 * var panel = new OO.ui.PanelLayout( {
11093 * $content: $( '<p>A panel layout with padding and a frame.</p>' )
11095 * $( 'body' ).append( panel.$element );
11098 * @extends OO.ui.Layout
11101 * @param {Object} [config] Configuration options
11102 * @cfg {boolean} [scrollable=false] Allow vertical scrolling
11103 * @cfg {boolean} [padded=false] Add padding between the content and the edges of the panel.
11104 * @cfg {boolean} [expanded=true] Expand the panel to fill the entire parent element.
11105 * @cfg {boolean} [framed=false] Render the panel with a frame to visually separate it from outside content.
11107 OO
.ui
.PanelLayout
= function OoUiPanelLayout( config
) {
11108 // Configuration initialization
11109 config
= $.extend( {
11116 // Parent constructor
11117 OO
.ui
.PanelLayout
.parent
.call( this, config
);
11120 this.$element
.addClass( 'oo-ui-panelLayout' );
11121 if ( config
.scrollable
) {
11122 this.$element
.addClass( 'oo-ui-panelLayout-scrollable' );
11124 if ( config
.padded
) {
11125 this.$element
.addClass( 'oo-ui-panelLayout-padded' );
11127 if ( config
.expanded
) {
11128 this.$element
.addClass( 'oo-ui-panelLayout-expanded' );
11130 if ( config
.framed
) {
11131 this.$element
.addClass( 'oo-ui-panelLayout-framed' );
11137 OO
.inheritClass( OO
.ui
.PanelLayout
, OO
.ui
.Layout
);
11142 * Focus the panel layout
11144 * The default implementation just focuses the first focusable element in the panel
11146 OO
.ui
.PanelLayout
.prototype.focus = function () {
11147 OO
.ui
.findFocusable( this.$element
).focus();
11151 * HorizontalLayout arranges its contents in a single line (using `display: inline-block` for its
11152 * items), with small margins between them. Convenient when you need to put a number of block-level
11153 * widgets on a single line next to each other.
11155 * Note that inline elements, such as OO.ui.ButtonWidgets, do not need this wrapper.
11158 * // HorizontalLayout with a text input and a label
11159 * var layout = new OO.ui.HorizontalLayout( {
11161 * new OO.ui.LabelWidget( { label: 'Label' } ),
11162 * new OO.ui.TextInputWidget( { value: 'Text' } )
11165 * $( 'body' ).append( layout.$element );
11168 * @extends OO.ui.Layout
11169 * @mixins OO.ui.mixin.GroupElement
11172 * @param {Object} [config] Configuration options
11173 * @cfg {OO.ui.Widget[]|OO.ui.Layout[]} [items] Widgets or other layouts to add to the layout.
11175 OO
.ui
.HorizontalLayout
= function OoUiHorizontalLayout( config
) {
11176 // Configuration initialization
11177 config
= config
|| {};
11179 // Parent constructor
11180 OO
.ui
.HorizontalLayout
.parent
.call( this, config
);
11182 // Mixin constructors
11183 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
11186 this.$element
.addClass( 'oo-ui-horizontalLayout' );
11187 if ( Array
.isArray( config
.items
) ) {
11188 this.addItems( config
.items
);
11194 OO
.inheritClass( OO
.ui
.HorizontalLayout
, OO
.ui
.Layout
);
11195 OO
.mixinClass( OO
.ui
.HorizontalLayout
, OO
.ui
.mixin
.GroupElement
);