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-02-01T23:04:40Z
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 from :focusable in jQueryUI v1.11.4 - 2015-04-14
78 * @param {jQuery} $element Element to test
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
.filters
.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, 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
239 * @param {number} wait
240 * @param {boolean} immediate
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
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
286 * @param {number} wait
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
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
= $.parseJSON( 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
=== 9 && 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
=== 9;
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 scrollable object parent
1078 * documentElement can't be used to get or set the scrollTop
1079 * property on Blink. Changing and testing its value lets us
1080 * use 'body' or 'documentElement' based on what is working.
1082 * https://code.google.com/p/chromium/issues/detail?id=303131
1085 * @param {HTMLElement} el Element to find scrollable parent for
1086 * @return {HTMLElement} Scrollable parent
1088 OO
.ui
.Element
.static.getRootScrollableElement = function ( el
) {
1089 var scrollTop
, body
;
1091 if ( OO
.ui
.scrollableElement
=== undefined ) {
1092 body
= el
.ownerDocument
.body
;
1093 scrollTop
= body
.scrollTop
;
1096 if ( body
.scrollTop
=== 1 ) {
1097 body
.scrollTop
= scrollTop
;
1098 OO
.ui
.scrollableElement
= 'body';
1100 OO
.ui
.scrollableElement
= 'documentElement';
1104 return el
.ownerDocument
[ OO
.ui
.scrollableElement
];
1108 * Get closest scrollable container.
1110 * Traverses up until either a scrollable element or the root is reached, in which case the window
1114 * @param {HTMLElement} el Element to find scrollable container for
1115 * @param {string} [dimension] Dimension of scrolling to look for; `x`, `y` or omit for either
1116 * @return {HTMLElement} Closest scrollable container
1118 OO
.ui
.Element
.static.getClosestScrollableContainer = function ( el
, dimension
) {
1120 // props = [ 'overflow' ] doesn't work due to https://bugzilla.mozilla.org/show_bug.cgi?id=889091
1121 props
= [ 'overflow-x', 'overflow-y' ],
1122 $parent
= $( el
).parent();
1124 if ( dimension
=== 'x' || dimension
=== 'y' ) {
1125 props
= [ 'overflow-' + dimension
];
1128 while ( $parent
.length
) {
1129 if ( $parent
[ 0 ] === this.getRootScrollableElement( el
) ) {
1130 return $parent
[ 0 ];
1134 val
= $parent
.css( props
[ i
] );
1135 if ( val
=== 'auto' || val
=== 'scroll' ) {
1136 return $parent
[ 0 ];
1139 $parent
= $parent
.parent();
1141 return this.getDocument( el
).body
;
1145 * Scroll element into view.
1148 * @param {HTMLElement} el Element to scroll into view
1149 * @param {Object} [config] Configuration options
1150 * @param {string} [config.duration='fast'] jQuery animation duration value
1151 * @param {string} [config.direction] Scroll in only one direction, e.g. 'x' or 'y', omit
1152 * to scroll in both directions
1153 * @param {Function} [config.complete] Function to call when scrolling completes.
1154 * Deprecated since 0.15.4, use the return promise instead.
1155 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1157 OO
.ui
.Element
.static.scrollIntoView = function ( el
, config
) {
1158 var position
, animations
, callback
, container
, $container
, elementDimensions
, containerDimensions
, $window
,
1159 deferred
= $.Deferred();
1161 // Configuration initialization
1162 config
= config
|| {};
1165 callback
= typeof config
.complete
=== 'function' && config
.complete
;
1167 OO
.ui
.warnDeprecation( 'Element#scrollIntoView: The `complete` callback config option is deprecated. Use the return promise instead.' );
1169 container
= this.getClosestScrollableContainer( el
, config
.direction
);
1170 $container
= $( container
);
1171 elementDimensions
= this.getDimensions( el
);
1172 containerDimensions
= this.getDimensions( container
);
1173 $window
= $( this.getWindow( el
) );
1175 // Compute the element's position relative to the container
1176 if ( $container
.is( 'html, body' ) ) {
1177 // If the scrollable container is the root, this is easy
1179 top
: elementDimensions
.rect
.top
,
1180 bottom
: $window
.innerHeight() - elementDimensions
.rect
.bottom
,
1181 left
: elementDimensions
.rect
.left
,
1182 right
: $window
.innerWidth() - elementDimensions
.rect
.right
1185 // Otherwise, we have to subtract el's coordinates from container's coordinates
1187 top
: elementDimensions
.rect
.top
- ( containerDimensions
.rect
.top
+ containerDimensions
.borders
.top
),
1188 bottom
: containerDimensions
.rect
.bottom
- containerDimensions
.borders
.bottom
- containerDimensions
.scrollbar
.bottom
- elementDimensions
.rect
.bottom
,
1189 left
: elementDimensions
.rect
.left
- ( containerDimensions
.rect
.left
+ containerDimensions
.borders
.left
),
1190 right
: containerDimensions
.rect
.right
- containerDimensions
.borders
.right
- containerDimensions
.scrollbar
.right
- elementDimensions
.rect
.right
1194 if ( !config
.direction
|| config
.direction
=== 'y' ) {
1195 if ( position
.top
< 0 ) {
1196 animations
.scrollTop
= containerDimensions
.scroll
.top
+ position
.top
;
1197 } else if ( position
.top
> 0 && position
.bottom
< 0 ) {
1198 animations
.scrollTop
= containerDimensions
.scroll
.top
+ Math
.min( position
.top
, -position
.bottom
);
1201 if ( !config
.direction
|| config
.direction
=== 'x' ) {
1202 if ( position
.left
< 0 ) {
1203 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ position
.left
;
1204 } else if ( position
.left
> 0 && position
.right
< 0 ) {
1205 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ Math
.min( position
.left
, -position
.right
);
1208 if ( !$.isEmptyObject( animations
) ) {
1209 $container
.stop( true ).animate( animations
, config
.duration
=== undefined ? 'fast' : config
.duration
);
1210 $container
.queue( function ( next
) {
1223 return deferred
.promise();
1227 * Force the browser to reconsider whether it really needs to render scrollbars inside the element
1228 * and reserve space for them, because it probably doesn't.
1230 * Workaround primarily for <https://code.google.com/p/chromium/issues/detail?id=387290>, but also
1231 * similar bugs in other browsers. "Just" forcing a reflow is not sufficient in all cases, we need
1232 * to first actually detach (or hide, but detaching is simpler) all children, *then* force a reflow,
1233 * and then reattach (or show) them back.
1236 * @param {HTMLElement} el Element to reconsider the scrollbars on
1238 OO
.ui
.Element
.static.reconsiderScrollbars = function ( el
) {
1239 var i
, len
, scrollLeft
, scrollTop
, nodes
= [];
1240 // Save scroll position
1241 scrollLeft
= el
.scrollLeft
;
1242 scrollTop
= el
.scrollTop
;
1243 // Detach all children
1244 while ( el
.firstChild
) {
1245 nodes
.push( el
.firstChild
);
1246 el
.removeChild( el
.firstChild
);
1249 void el
.offsetHeight
;
1250 // Reattach all children
1251 for ( i
= 0, len
= nodes
.length
; i
< len
; i
++ ) {
1252 el
.appendChild( nodes
[ i
] );
1254 // Restore scroll position (no-op if scrollbars disappeared)
1255 el
.scrollLeft
= scrollLeft
;
1256 el
.scrollTop
= scrollTop
;
1262 * Toggle visibility of an element.
1264 * @param {boolean} [show] Make element visible, omit to toggle visibility
1268 OO
.ui
.Element
.prototype.toggle = function ( show
) {
1269 show
= show
=== undefined ? !this.visible
: !!show
;
1271 if ( show
!== this.isVisible() ) {
1272 this.visible
= show
;
1273 this.$element
.toggleClass( 'oo-ui-element-hidden', !this.visible
);
1274 this.emit( 'toggle', show
);
1281 * Check if element is visible.
1283 * @return {boolean} element is visible
1285 OO
.ui
.Element
.prototype.isVisible = function () {
1286 return this.visible
;
1292 * @return {Mixed} Element data
1294 OO
.ui
.Element
.prototype.getData = function () {
1301 * @param {Mixed} data Element data
1304 OO
.ui
.Element
.prototype.setData = function ( data
) {
1310 * Check if element supports one or more methods.
1312 * @param {string|string[]} methods Method or list of methods to check
1313 * @return {boolean} All methods are supported
1315 OO
.ui
.Element
.prototype.supports = function ( methods
) {
1319 methods
= Array
.isArray( methods
) ? methods
: [ methods
];
1320 for ( i
= 0, len
= methods
.length
; i
< len
; i
++ ) {
1321 if ( $.isFunction( this[ methods
[ i
] ] ) ) {
1326 return methods
.length
=== support
;
1330 * Update the theme-provided classes.
1332 * @localdoc This is called in element mixins and widget classes any time state changes.
1333 * Updating is debounced, minimizing overhead of changing multiple attributes and
1334 * guaranteeing that theme updates do not occur within an element's constructor
1336 OO
.ui
.Element
.prototype.updateThemeClasses = function () {
1337 OO
.ui
.theme
.queueUpdateElementClasses( this );
1341 * Get the HTML tag name.
1343 * Override this method to base the result on instance information.
1345 * @return {string} HTML tag name
1347 OO
.ui
.Element
.prototype.getTagName = function () {
1348 return this.constructor.static.tagName
;
1352 * Check if the element is attached to the DOM
1354 * @return {boolean} The element is attached to the DOM
1356 OO
.ui
.Element
.prototype.isElementAttached = function () {
1357 return $.contains( this.getElementDocument(), this.$element
[ 0 ] );
1361 * Get the DOM document.
1363 * @return {HTMLDocument} Document object
1365 OO
.ui
.Element
.prototype.getElementDocument = function () {
1366 // Don't cache this in other ways either because subclasses could can change this.$element
1367 return OO
.ui
.Element
.static.getDocument( this.$element
);
1371 * Get the DOM window.
1373 * @return {Window} Window object
1375 OO
.ui
.Element
.prototype.getElementWindow = function () {
1376 return OO
.ui
.Element
.static.getWindow( this.$element
);
1380 * Get closest scrollable container.
1382 * @return {HTMLElement} Closest scrollable container
1384 OO
.ui
.Element
.prototype.getClosestScrollableElementContainer = function () {
1385 return OO
.ui
.Element
.static.getClosestScrollableContainer( this.$element
[ 0 ] );
1389 * Get group element is in.
1391 * @return {OO.ui.mixin.GroupElement|null} Group element, null if none
1393 OO
.ui
.Element
.prototype.getElementGroup = function () {
1394 return this.elementGroup
;
1398 * Set group element is in.
1400 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
1403 OO
.ui
.Element
.prototype.setElementGroup = function ( group
) {
1404 this.elementGroup
= group
;
1409 * Scroll element into view.
1411 * @param {Object} [config] Configuration options
1412 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1414 OO
.ui
.Element
.prototype.scrollElementIntoView = function ( config
) {
1416 !this.isElementAttached() ||
1417 !this.isVisible() ||
1418 ( this.getElementGroup() && !this.getElementGroup().isVisible() )
1420 return $.Deferred().resolve();
1422 return OO
.ui
.Element
.static.scrollIntoView( this.$element
[ 0 ], config
);
1426 * Restore the pre-infusion dynamic state for this widget.
1428 * This method is called after #$element has been inserted into DOM. The parameter is the return
1429 * value of #gatherPreInfuseState.
1432 * @param {Object} state
1434 OO
.ui
.Element
.prototype.restorePreInfuseState = function () {
1438 * Wraps an HTML snippet for use with configuration values which default
1439 * to strings. This bypasses the default html-escaping done to string
1445 * @param {string} [content] HTML content
1447 OO
.ui
.HtmlSnippet
= function OoUiHtmlSnippet( content
) {
1449 this.content
= content
;
1454 OO
.initClass( OO
.ui
.HtmlSnippet
);
1461 * @return {string} Unchanged HTML snippet.
1463 OO
.ui
.HtmlSnippet
.prototype.toString = function () {
1464 return this.content
;
1468 * Layouts are containers for elements and are used to arrange other widgets of arbitrary type in a way
1469 * that is centrally controlled and can be updated dynamically. Layouts can be, and usually are, combined.
1470 * See {@link OO.ui.FieldsetLayout FieldsetLayout}, {@link OO.ui.FieldLayout FieldLayout}, {@link OO.ui.FormLayout FormLayout},
1471 * {@link OO.ui.PanelLayout PanelLayout}, {@link OO.ui.StackLayout StackLayout}, {@link OO.ui.PageLayout PageLayout},
1472 * {@link OO.ui.HorizontalLayout HorizontalLayout}, and {@link OO.ui.BookletLayout BookletLayout} for more information and examples.
1476 * @extends OO.ui.Element
1477 * @mixins OO.EventEmitter
1480 * @param {Object} [config] Configuration options
1482 OO
.ui
.Layout
= function OoUiLayout( config
) {
1483 // Configuration initialization
1484 config
= config
|| {};
1486 // Parent constructor
1487 OO
.ui
.Layout
.parent
.call( this, config
);
1489 // Mixin constructors
1490 OO
.EventEmitter
.call( this );
1493 this.$element
.addClass( 'oo-ui-layout' );
1498 OO
.inheritClass( OO
.ui
.Layout
, OO
.ui
.Element
);
1499 OO
.mixinClass( OO
.ui
.Layout
, OO
.EventEmitter
);
1502 * Widgets are compositions of one or more OOjs UI elements that users can both view
1503 * and interact with. All widgets can be configured and modified via a standard API,
1504 * and their state can change dynamically according to a model.
1508 * @extends OO.ui.Element
1509 * @mixins OO.EventEmitter
1512 * @param {Object} [config] Configuration options
1513 * @cfg {boolean} [disabled=false] Disable the widget. Disabled widgets cannot be used and their
1514 * appearance reflects this state.
1516 OO
.ui
.Widget
= function OoUiWidget( config
) {
1517 // Initialize config
1518 config
= $.extend( { disabled
: false }, config
);
1520 // Parent constructor
1521 OO
.ui
.Widget
.parent
.call( this, config
);
1523 // Mixin constructors
1524 OO
.EventEmitter
.call( this );
1527 this.disabled
= null;
1528 this.wasDisabled
= null;
1531 this.$element
.addClass( 'oo-ui-widget' );
1532 this.setDisabled( !!config
.disabled
);
1537 OO
.inheritClass( OO
.ui
.Widget
, OO
.ui
.Element
);
1538 OO
.mixinClass( OO
.ui
.Widget
, OO
.EventEmitter
);
1540 /* Static Properties */
1543 * Whether this widget will behave reasonably when wrapped in an HTML `<label>`. If this is true,
1544 * wrappers such as OO.ui.FieldLayout may use a `<label>` instead of implementing own label click
1549 * @property {boolean}
1551 OO
.ui
.Widget
.static.supportsSimpleLabel
= false;
1558 * A 'disable' event is emitted when the disabled state of the widget changes
1559 * (i.e. on disable **and** enable).
1561 * @param {boolean} disabled Widget is disabled
1567 * A 'toggle' event is emitted when the visibility of the widget changes.
1569 * @param {boolean} visible Widget is visible
1575 * Check if the widget is disabled.
1577 * @return {boolean} Widget is disabled
1579 OO
.ui
.Widget
.prototype.isDisabled = function () {
1580 return this.disabled
;
1584 * Set the 'disabled' state of the widget.
1586 * When a widget is disabled, it cannot be used and its appearance is updated to reflect this state.
1588 * @param {boolean} disabled Disable widget
1591 OO
.ui
.Widget
.prototype.setDisabled = function ( disabled
) {
1594 this.disabled
= !!disabled
;
1595 isDisabled
= this.isDisabled();
1596 if ( isDisabled
!== this.wasDisabled
) {
1597 this.$element
.toggleClass( 'oo-ui-widget-disabled', isDisabled
);
1598 this.$element
.toggleClass( 'oo-ui-widget-enabled', !isDisabled
);
1599 this.$element
.attr( 'aria-disabled', isDisabled
.toString() );
1600 this.emit( 'disable', isDisabled
);
1601 this.updateThemeClasses();
1603 this.wasDisabled
= isDisabled
;
1609 * Update the disabled state, in case of changes in parent widget.
1613 OO
.ui
.Widget
.prototype.updateDisabled = function () {
1614 this.setDisabled( this.disabled
);
1626 OO
.ui
.Theme
= function OoUiTheme() {
1627 this.elementClassesQueue
= [];
1628 this.debouncedUpdateQueuedElementClasses
= OO
.ui
.debounce( this.updateQueuedElementClasses
);
1633 OO
.initClass( OO
.ui
.Theme
);
1638 * Get a list of classes to be applied to a widget.
1640 * The 'on' and 'off' lists combined MUST contain keys for all classes the theme adds or removes,
1641 * otherwise state transitions will not work properly.
1643 * @param {OO.ui.Element} element Element for which to get classes
1644 * @return {Object.<string,string[]>} Categorized class names with `on` and `off` lists
1646 OO
.ui
.Theme
.prototype.getElementClasses = function () {
1647 return { on
: [], off
: [] };
1651 * Update CSS classes provided by the theme.
1653 * For elements with theme logic hooks, this should be called any time there's a state change.
1655 * @param {OO.ui.Element} element Element for which to update classes
1657 OO
.ui
.Theme
.prototype.updateElementClasses = function ( element
) {
1658 var $elements
= $( [] ),
1659 classes
= this.getElementClasses( element
);
1661 if ( element
.$icon
) {
1662 $elements
= $elements
.add( element
.$icon
);
1664 if ( element
.$indicator
) {
1665 $elements
= $elements
.add( element
.$indicator
);
1669 .removeClass( classes
.off
.join( ' ' ) )
1670 .addClass( classes
.on
.join( ' ' ) );
1676 OO
.ui
.Theme
.prototype.updateQueuedElementClasses = function () {
1678 for ( i
= 0; i
< this.elementClassesQueue
.length
; i
++ ) {
1679 this.updateElementClasses( this.elementClassesQueue
[ i
] );
1682 this.elementClassesQueue
= [];
1686 * Queue #updateElementClasses to be called for this element.
1688 * @localdoc QUnit tests override this method to directly call #queueUpdateElementClasses,
1689 * to make them synchronous.
1691 * @param {OO.ui.Element} element Element for which to update classes
1693 OO
.ui
.Theme
.prototype.queueUpdateElementClasses = function ( element
) {
1694 // Keep items in the queue unique. Use lastIndexOf to start checking from the end because that's
1695 // the most common case (this method is often called repeatedly for the same element).
1696 if ( this.elementClassesQueue
.lastIndexOf( element
) !== -1 ) {
1699 this.elementClassesQueue
.push( element
);
1700 this.debouncedUpdateQueuedElementClasses();
1704 * Get the transition duration in milliseconds for dialogs opening/closing
1706 * The dialog should be fully rendered this many milliseconds after the
1707 * ready process has executed.
1709 * @return {number} Transition duration in milliseconds
1711 OO
.ui
.Theme
.prototype.getDialogTransitionDuration = function () {
1716 * The TabIndexedElement class is an attribute mixin used to add additional functionality to an
1717 * element created by another class. The mixin provides a ‘tabIndex’ property, which specifies the
1718 * order in which users will navigate through the focusable elements via the "tab" key.
1721 * // TabIndexedElement is mixed into the ButtonWidget class
1722 * // to provide a tabIndex property.
1723 * var button1 = new OO.ui.ButtonWidget( {
1727 * var button2 = new OO.ui.ButtonWidget( {
1731 * var button3 = new OO.ui.ButtonWidget( {
1735 * var button4 = new OO.ui.ButtonWidget( {
1739 * $( 'body' ).append( button1.$element, button2.$element, button3.$element, button4.$element );
1745 * @param {Object} [config] Configuration options
1746 * @cfg {jQuery} [$tabIndexed] The element that should use the tabindex functionality. By default,
1747 * the functionality is applied to the element created by the class ($element). If a different element is specified, the tabindex
1748 * functionality will be applied to it instead.
1749 * @cfg {number|null} [tabIndex=0] Number that specifies the element’s position in the tab-navigation
1750 * order (e.g., 1 for the first focusable element). Use 0 to use the default navigation order; use -1
1751 * to remove the element from the tab-navigation flow.
1753 OO
.ui
.mixin
.TabIndexedElement
= function OoUiMixinTabIndexedElement( config
) {
1754 // Configuration initialization
1755 config
= $.extend( { tabIndex
: 0 }, config
);
1758 this.$tabIndexed
= null;
1759 this.tabIndex
= null;
1762 this.connect( this, { disable
: 'onTabIndexedElementDisable' } );
1765 this.setTabIndex( config
.tabIndex
);
1766 this.setTabIndexedElement( config
.$tabIndexed
|| this.$element
);
1771 OO
.initClass( OO
.ui
.mixin
.TabIndexedElement
);
1776 * Set the element that should use the tabindex functionality.
1778 * This method is used to retarget a tabindex mixin so that its functionality applies
1779 * to the specified element. If an element is currently using the functionality, the mixin’s
1780 * effect on that element is removed before the new element is set up.
1782 * @param {jQuery} $tabIndexed Element that should use the tabindex functionality
1785 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndexedElement = function ( $tabIndexed
) {
1786 var tabIndex
= this.tabIndex
;
1787 // Remove attributes from old $tabIndexed
1788 this.setTabIndex( null );
1789 // Force update of new $tabIndexed
1790 this.$tabIndexed
= $tabIndexed
;
1791 this.tabIndex
= tabIndex
;
1792 return this.updateTabIndex();
1796 * Set the value of the tabindex.
1798 * @param {number|null} tabIndex Tabindex value, or `null` for no tabindex
1801 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndex = function ( tabIndex
) {
1802 tabIndex
= typeof tabIndex
=== 'number' ? tabIndex
: null;
1804 if ( this.tabIndex
!== tabIndex
) {
1805 this.tabIndex
= tabIndex
;
1806 this.updateTabIndex();
1813 * Update the `tabindex` attribute, in case of changes to tab index or
1819 OO
.ui
.mixin
.TabIndexedElement
.prototype.updateTabIndex = function () {
1820 if ( this.$tabIndexed
) {
1821 if ( this.tabIndex
!== null ) {
1822 // Do not index over disabled elements
1823 this.$tabIndexed
.attr( {
1824 tabindex
: this.isDisabled() ? -1 : this.tabIndex
,
1825 // Support: ChromeVox and NVDA
1826 // These do not seem to inherit aria-disabled from parent elements
1827 'aria-disabled': this.isDisabled().toString()
1830 this.$tabIndexed
.removeAttr( 'tabindex aria-disabled' );
1837 * Handle disable events.
1840 * @param {boolean} disabled Element is disabled
1842 OO
.ui
.mixin
.TabIndexedElement
.prototype.onTabIndexedElementDisable = function () {
1843 this.updateTabIndex();
1847 * Get the value of the tabindex.
1849 * @return {number|null} Tabindex value
1851 OO
.ui
.mixin
.TabIndexedElement
.prototype.getTabIndex = function () {
1852 return this.tabIndex
;
1856 * ButtonElement is often mixed into other classes to generate a button, which is a clickable
1857 * interface element that can be configured with access keys for accessibility.
1858 * See the [OOjs UI documentation on MediaWiki] [1] for examples.
1860 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#Buttons
1866 * @param {Object} [config] Configuration options
1867 * @cfg {jQuery} [$button] The button element created by the class.
1868 * If this configuration is omitted, the button element will use a generated `<a>`.
1869 * @cfg {boolean} [framed=true] Render the button with a frame
1871 OO
.ui
.mixin
.ButtonElement
= function OoUiMixinButtonElement( config
) {
1872 // Configuration initialization
1873 config
= config
|| {};
1876 this.$button
= null;
1878 this.active
= config
.active
!== undefined && config
.active
;
1879 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
1880 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
1881 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
1882 this.onKeyUpHandler
= this.onKeyUp
.bind( this );
1883 this.onClickHandler
= this.onClick
.bind( this );
1884 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
1887 this.$element
.addClass( 'oo-ui-buttonElement' );
1888 this.toggleFramed( config
.framed
=== undefined || config
.framed
);
1889 this.setButtonElement( config
.$button
|| $( '<a>' ) );
1894 OO
.initClass( OO
.ui
.mixin
.ButtonElement
);
1896 /* Static Properties */
1899 * Cancel mouse down events.
1901 * This property is usually set to `true` to prevent the focus from changing when the button is clicked.
1902 * Classes such as {@link OO.ui.mixin.DraggableElement DraggableElement} and {@link OO.ui.ButtonOptionWidget ButtonOptionWidget}
1903 * use a value of `false` so that dragging behavior is possible and mousedown events can be handled by a
1908 * @property {boolean}
1910 OO
.ui
.mixin
.ButtonElement
.static.cancelButtonMouseDownEvents
= true;
1915 * A 'click' event is emitted when the button element is clicked.
1923 * Set the button element.
1925 * This method is used to retarget a button mixin so that its functionality applies to
1926 * the specified button element instead of the one created by the class. If a button element
1927 * is already set, the method will remove the mixin’s effect on that element.
1929 * @param {jQuery} $button Element to use as button
1931 OO
.ui
.mixin
.ButtonElement
.prototype.setButtonElement = function ( $button
) {
1932 if ( this.$button
) {
1934 .removeClass( 'oo-ui-buttonElement-button' )
1935 .removeAttr( 'role accesskey' )
1937 mousedown
: this.onMouseDownHandler
,
1938 keydown
: this.onKeyDownHandler
,
1939 click
: this.onClickHandler
,
1940 keypress
: this.onKeyPressHandler
1944 this.$button
= $button
1945 .addClass( 'oo-ui-buttonElement-button' )
1947 mousedown
: this.onMouseDownHandler
,
1948 keydown
: this.onKeyDownHandler
,
1949 click
: this.onClickHandler
,
1950 keypress
: this.onKeyPressHandler
1953 // Add `role="button"` on `<a>` elements, where it's needed
1954 // `toUppercase()` is added for XHTML documents
1955 if ( this.$button
.prop( 'tagName' ).toUpperCase() === 'A' ) {
1956 this.$button
.attr( 'role', 'button' );
1961 * Handles mouse down events.
1964 * @param {jQuery.Event} e Mouse down event
1966 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseDown = function ( e
) {
1967 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
1970 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
1971 // Run the mouseup handler no matter where the mouse is when the button is let go, so we can
1972 // reliably remove the pressed class
1973 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
1974 // Prevent change of focus unless specifically configured otherwise
1975 if ( this.constructor.static.cancelButtonMouseDownEvents
) {
1981 * Handles mouse up events.
1984 * @param {MouseEvent} e Mouse up event
1986 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseUp = function ( e
) {
1987 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
1990 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
1991 // Stop listening for mouseup, since we only needed this once
1992 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
1996 * Handles mouse click events.
1999 * @param {jQuery.Event} e Mouse click event
2002 OO
.ui
.mixin
.ButtonElement
.prototype.onClick = function ( e
) {
2003 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
2004 if ( this.emit( 'click' ) ) {
2011 * Handles key down events.
2014 * @param {jQuery.Event} e Key down event
2016 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyDown = function ( e
) {
2017 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
2020 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
2021 // Run the keyup handler no matter where the key is when the button is let go, so we can
2022 // reliably remove the pressed class
2023 this.getElementDocument().addEventListener( 'keyup', this.onKeyUpHandler
, true );
2027 * Handles key up events.
2030 * @param {KeyboardEvent} e Key up event
2032 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyUp = function ( e
) {
2033 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
2036 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
2037 // Stop listening for keyup, since we only needed this once
2038 this.getElementDocument().removeEventListener( 'keyup', this.onKeyUpHandler
, true );
2042 * Handles key press events.
2045 * @param {jQuery.Event} e Key press event
2048 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyPress = function ( e
) {
2049 if ( !this.isDisabled() && ( e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
) ) {
2050 if ( this.emit( 'click' ) ) {
2057 * Check if button has a frame.
2059 * @return {boolean} Button is framed
2061 OO
.ui
.mixin
.ButtonElement
.prototype.isFramed = function () {
2066 * Render the button with or without a frame. Omit the `framed` parameter to toggle the button frame on and off.
2068 * @param {boolean} [framed] Make button framed, omit to toggle
2071 OO
.ui
.mixin
.ButtonElement
.prototype.toggleFramed = function ( framed
) {
2072 framed
= framed
=== undefined ? !this.framed
: !!framed
;
2073 if ( framed
!== this.framed
) {
2074 this.framed
= framed
;
2076 .toggleClass( 'oo-ui-buttonElement-frameless', !framed
)
2077 .toggleClass( 'oo-ui-buttonElement-framed', framed
);
2078 this.updateThemeClasses();
2085 * Set the button's active state.
2087 * The active state can be set on:
2089 * - {@link OO.ui.ButtonOptionWidget ButtonOptionWidget} when it is selected
2090 * - {@link OO.ui.ToggleButtonWidget ToggleButtonWidget} when it is toggle on
2091 * - {@link OO.ui.ButtonWidget ButtonWidget} when clicking the button would only refresh the page
2094 * @param {boolean} value Make button active
2097 OO
.ui
.mixin
.ButtonElement
.prototype.setActive = function ( value
) {
2098 this.active
= !!value
;
2099 this.$element
.toggleClass( 'oo-ui-buttonElement-active', this.active
);
2100 this.updateThemeClasses();
2105 * Check if the button is active
2108 * @return {boolean} The button is active
2110 OO
.ui
.mixin
.ButtonElement
.prototype.isActive = function () {
2115 * Any OOjs UI widget that contains other widgets (such as {@link OO.ui.ButtonWidget buttons} or
2116 * {@link OO.ui.OptionWidget options}) mixes in GroupElement. Adding, removing, and clearing
2117 * items from the group is done through the interface the class provides.
2118 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
2120 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Groups
2126 * @param {Object} [config] Configuration options
2127 * @cfg {jQuery} [$group] The container element created by the class. If this configuration
2128 * is omitted, the group element will use a generated `<div>`.
2130 OO
.ui
.mixin
.GroupElement
= function OoUiMixinGroupElement( config
) {
2131 // Configuration initialization
2132 config
= config
|| {};
2137 this.aggregateItemEvents
= {};
2140 this.setGroupElement( config
.$group
|| $( '<div>' ) );
2148 * A change event is emitted when the set of selected items changes.
2150 * @param {OO.ui.Element[]} items Items currently in the group
2156 * Set the group element.
2158 * If an element is already set, items will be moved to the new element.
2160 * @param {jQuery} $group Element to use as group
2162 OO
.ui
.mixin
.GroupElement
.prototype.setGroupElement = function ( $group
) {
2165 this.$group
= $group
;
2166 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2167 this.$group
.append( this.items
[ i
].$element
);
2172 * Check if a group contains no items.
2174 * @return {boolean} Group is empty
2176 OO
.ui
.mixin
.GroupElement
.prototype.isEmpty = function () {
2177 return !this.items
.length
;
2181 * Get all items in the group.
2183 * The method returns an array of item references (e.g., [button1, button2, button3]) and is useful
2184 * when synchronizing groups of items, or whenever the references are required (e.g., when removing items
2187 * @return {OO.ui.Element[]} An array of items.
2189 OO
.ui
.mixin
.GroupElement
.prototype.getItems = function () {
2190 return this.items
.slice( 0 );
2194 * Get an item by its data.
2196 * Only the first item with matching data will be returned. To return all matching items,
2197 * use the #getItemsFromData method.
2199 * @param {Object} data Item data to search for
2200 * @return {OO.ui.Element|null} Item with equivalent data, `null` if none exists
2202 OO
.ui
.mixin
.GroupElement
.prototype.getItemFromData = function ( data
) {
2204 hash
= OO
.getHash( data
);
2206 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2207 item
= this.items
[ i
];
2208 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2217 * Get items by their data.
2219 * All items with matching data will be returned. To return only the first match, use the #getItemFromData method instead.
2221 * @param {Object} data Item data to search for
2222 * @return {OO.ui.Element[]} Items with equivalent data
2224 OO
.ui
.mixin
.GroupElement
.prototype.getItemsFromData = function ( data
) {
2226 hash
= OO
.getHash( data
),
2229 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2230 item
= this.items
[ i
];
2231 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2240 * Aggregate the events emitted by the group.
2242 * When events are aggregated, the group will listen to all contained items for the event,
2243 * and then emit the event under a new name. The new event will contain an additional leading
2244 * parameter containing the item that emitted the original event. Other arguments emitted from
2245 * the original event are passed through.
2247 * @param {Object.<string,string|null>} events An object keyed by the name of the event that should be
2248 * aggregated (e.g., ‘click’) and the value of the new name to use (e.g., ‘groupClick’).
2249 * A `null` value will remove aggregated events.
2251 * @throws {Error} An error is thrown if aggregation already exists.
2253 OO
.ui
.mixin
.GroupElement
.prototype.aggregate = function ( events
) {
2254 var i
, len
, item
, add
, remove
, itemEvent
, groupEvent
;
2256 for ( itemEvent
in events
) {
2257 groupEvent
= events
[ itemEvent
];
2259 // Remove existing aggregated event
2260 if ( Object
.prototype.hasOwnProperty
.call( this.aggregateItemEvents
, itemEvent
) ) {
2261 // Don't allow duplicate aggregations
2263 throw new Error( 'Duplicate item event aggregation for ' + itemEvent
);
2265 // Remove event aggregation from existing items
2266 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2267 item
= this.items
[ i
];
2268 if ( item
.connect
&& item
.disconnect
) {
2270 remove
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2271 item
.disconnect( this, remove
);
2274 // Prevent future items from aggregating event
2275 delete this.aggregateItemEvents
[ itemEvent
];
2278 // Add new aggregate event
2280 // Make future items aggregate event
2281 this.aggregateItemEvents
[ itemEvent
] = groupEvent
;
2282 // Add event aggregation to existing items
2283 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2284 item
= this.items
[ i
];
2285 if ( item
.connect
&& item
.disconnect
) {
2287 add
[ itemEvent
] = [ 'emit', groupEvent
, item
];
2288 item
.connect( this, add
);
2296 * Add items to the group.
2298 * Items will be added to the end of the group array unless the optional `index` parameter specifies
2299 * a different insertion point. Adding an existing item will move it to the end of the array or the point specified by the `index`.
2301 * @param {OO.ui.Element[]} items An array of items to add to the group
2302 * @param {number} [index] Index of the insertion point
2305 OO
.ui
.mixin
.GroupElement
.prototype.addItems = function ( items
, index
) {
2306 var i
, len
, item
, itemEvent
, events
, currentIndex
,
2309 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
2312 // Check if item exists then remove it first, effectively "moving" it
2313 currentIndex
= this.items
.indexOf( item
);
2314 if ( currentIndex
>= 0 ) {
2315 this.removeItems( [ item
] );
2316 // Adjust index to compensate for removal
2317 if ( currentIndex
< index
) {
2322 if ( item
.connect
&& item
.disconnect
&& !$.isEmptyObject( this.aggregateItemEvents
) ) {
2324 for ( itemEvent
in this.aggregateItemEvents
) {
2325 events
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2327 item
.connect( this, events
);
2329 item
.setElementGroup( this );
2330 itemElements
.push( item
.$element
.get( 0 ) );
2333 if ( index
=== undefined || index
< 0 || index
>= this.items
.length
) {
2334 this.$group
.append( itemElements
);
2335 this.items
.push
.apply( this.items
, items
);
2336 } else if ( index
=== 0 ) {
2337 this.$group
.prepend( itemElements
);
2338 this.items
.unshift
.apply( this.items
, items
);
2340 this.items
[ index
].$element
.before( itemElements
);
2341 this.items
.splice
.apply( this.items
, [ index
, 0 ].concat( items
) );
2344 this.emit( 'change', this.getItems() );
2349 * Remove the specified items from a group.
2351 * Removed items are detached (not removed) from the DOM so that they may be reused.
2352 * To remove all items from a group, you may wish to use the #clearItems method instead.
2354 * @param {OO.ui.Element[]} items An array of items to remove
2357 OO
.ui
.mixin
.GroupElement
.prototype.removeItems = function ( items
) {
2358 var i
, len
, item
, index
, events
, itemEvent
;
2360 // Remove specific items
2361 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
2363 index
= this.items
.indexOf( item
);
2364 if ( index
!== -1 ) {
2365 if ( item
.connect
&& item
.disconnect
&& !$.isEmptyObject( this.aggregateItemEvents
) ) {
2367 for ( itemEvent
in this.aggregateItemEvents
) {
2368 events
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2370 item
.disconnect( this, events
);
2372 item
.setElementGroup( null );
2373 this.items
.splice( index
, 1 );
2374 item
.$element
.detach();
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 () {
2391 var i
, len
, item
, remove
, itemEvent
;
2394 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2395 item
= this.items
[ i
];
2397 item
.connect
&& item
.disconnect
&&
2398 !$.isEmptyObject( this.aggregateItemEvents
)
2401 if ( Object
.prototype.hasOwnProperty
.call( this.aggregateItemEvents
, itemEvent
) ) {
2402 remove
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2404 item
.disconnect( this, remove
);
2406 item
.setElementGroup( null );
2407 item
.$element
.detach();
2410 this.emit( 'change', this.getItems() );
2416 * IconElement is often mixed into other classes to generate an icon.
2417 * Icons are graphics, about the size of normal text. They are used to aid the user
2418 * in locating a control or to convey information in a space-efficient way. See the
2419 * [OOjs UI documentation on MediaWiki] [1] for a list of icons
2420 * included in the library.
2422 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2428 * @param {Object} [config] Configuration options
2429 * @cfg {jQuery} [$icon] The icon element created by the class. If this configuration is omitted,
2430 * the icon element will use a generated `<span>`. To use a different HTML tag, or to specify that
2431 * the icon element be set to an existing icon instead of the one generated by this class, set a
2432 * value using a jQuery selection. For example:
2434 * // Use a <div> tag instead of a <span>
2436 * // Use an existing icon element instead of the one generated by the class
2437 * $icon: this.$element
2438 * // Use an icon element from a child widget
2439 * $icon: this.childwidget.$element
2440 * @cfg {Object|string} [icon=''] The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of
2441 * symbolic names. A map is used for i18n purposes and contains a `default` icon
2442 * name and additional names keyed by language code. The `default` name is used when no icon is keyed
2443 * by the user's language.
2445 * Example of an i18n map:
2447 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2448 * See the [OOjs UI documentation on MediaWiki] [2] for a list of icons included in the library.
2449 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2450 * @cfg {string|Function} [iconTitle] A text string used as the icon title, or a function that returns title
2451 * text. The icon title is displayed when users move the mouse over the icon.
2453 OO
.ui
.mixin
.IconElement
= function OoUiMixinIconElement( config
) {
2454 // Configuration initialization
2455 config
= config
|| {};
2460 this.iconTitle
= null;
2463 this.setIcon( config
.icon
|| this.constructor.static.icon
);
2464 this.setIconTitle( config
.iconTitle
|| this.constructor.static.iconTitle
);
2465 this.setIconElement( config
.$icon
|| $( '<span>' ) );
2470 OO
.initClass( OO
.ui
.mixin
.IconElement
);
2472 /* Static Properties */
2475 * The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of symbolic names. A map is used
2476 * for i18n purposes and contains a `default` icon name and additional names keyed by
2477 * language code. The `default` name is used when no icon is keyed by the user's language.
2479 * Example of an i18n map:
2481 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2483 * Note: the static property will be overridden if the #icon configuration is used.
2487 * @property {Object|string}
2489 OO
.ui
.mixin
.IconElement
.static.icon
= null;
2492 * The icon title, displayed when users move the mouse over the icon. The value can be text, a
2493 * function that returns title text, or `null` for no title.
2495 * The static property will be overridden if the #iconTitle configuration is used.
2499 * @property {string|Function|null}
2501 OO
.ui
.mixin
.IconElement
.static.iconTitle
= null;
2506 * Set the icon element. This method is used to retarget an icon mixin so that its functionality
2507 * applies to the specified icon element instead of the one created by the class. If an icon
2508 * element is already set, the mixin’s effect on that element is removed. Generated CSS classes
2509 * and mixin methods will no longer affect the element.
2511 * @param {jQuery} $icon Element to use as icon
2513 OO
.ui
.mixin
.IconElement
.prototype.setIconElement = function ( $icon
) {
2516 .removeClass( 'oo-ui-iconElement-icon oo-ui-icon-' + this.icon
)
2517 .removeAttr( 'title' );
2521 .addClass( 'oo-ui-iconElement-icon' )
2522 .toggleClass( 'oo-ui-icon-' + this.icon
, !!this.icon
);
2523 if ( this.iconTitle
!== null ) {
2524 this.$icon
.attr( 'title', this.iconTitle
);
2527 this.updateThemeClasses();
2531 * Set icon by symbolic name (e.g., ‘remove’ or ‘menu’). Use `null` to remove an icon.
2532 * The icon parameter can also be set to a map of icon names. See the #icon config setting
2535 * @param {Object|string|null} icon A symbolic icon name, a {@link #icon map of icon names} keyed
2536 * by language code, or `null` to remove the icon.
2539 OO
.ui
.mixin
.IconElement
.prototype.setIcon = function ( icon
) {
2540 icon
= OO
.isPlainObject( icon
) ? OO
.ui
.getLocalValue( icon
, null, 'default' ) : icon
;
2541 icon
= typeof icon
=== 'string' && icon
.trim().length
? icon
.trim() : null;
2543 if ( this.icon
!== icon
) {
2545 if ( this.icon
!== null ) {
2546 this.$icon
.removeClass( 'oo-ui-icon-' + this.icon
);
2548 if ( icon
!== null ) {
2549 this.$icon
.addClass( 'oo-ui-icon-' + icon
);
2555 this.$element
.toggleClass( 'oo-ui-iconElement', !!this.icon
);
2556 this.updateThemeClasses();
2562 * Set the icon title. Use `null` to remove the title.
2564 * @param {string|Function|null} iconTitle A text string used as the icon title,
2565 * a function that returns title text, or `null` for no title.
2568 OO
.ui
.mixin
.IconElement
.prototype.setIconTitle = function ( iconTitle
) {
2569 iconTitle
= typeof iconTitle
=== 'function' ||
2570 ( typeof iconTitle
=== 'string' && iconTitle
.length
) ?
2571 OO
.ui
.resolveMsg( iconTitle
) : null;
2573 if ( this.iconTitle
!== iconTitle
) {
2574 this.iconTitle
= iconTitle
;
2576 if ( this.iconTitle
!== null ) {
2577 this.$icon
.attr( 'title', iconTitle
);
2579 this.$icon
.removeAttr( 'title' );
2588 * Get the symbolic name of the icon.
2590 * @return {string} Icon name
2592 OO
.ui
.mixin
.IconElement
.prototype.getIcon = function () {
2597 * Get the icon title. The title text is displayed when a user moves the mouse over the icon.
2599 * @return {string} Icon title text
2601 OO
.ui
.mixin
.IconElement
.prototype.getIconTitle = function () {
2602 return this.iconTitle
;
2606 * IndicatorElement is often mixed into other classes to generate an indicator.
2607 * Indicators are small graphics that are generally used in two ways:
2609 * - To draw attention to the status of an item. For example, an indicator might be
2610 * used to show that an item in a list has errors that need to be resolved.
2611 * - To clarify the function of a control that acts in an exceptional way (a button
2612 * that opens a menu instead of performing an action directly, for example).
2614 * For a list of indicators included in the library, please see the
2615 * [OOjs UI documentation on MediaWiki] [1].
2617 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2623 * @param {Object} [config] Configuration options
2624 * @cfg {jQuery} [$indicator] The indicator element created by the class. If this
2625 * configuration is omitted, the indicator element will use a generated `<span>`.
2626 * @cfg {string} [indicator] Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2627 * See the [OOjs UI documentation on MediaWiki][2] for a list of indicators included
2629 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2630 * @cfg {string|Function} [indicatorTitle] A text string used as the indicator title,
2631 * or a function that returns title text. The indicator title is displayed when users move
2632 * the mouse over the indicator.
2634 OO
.ui
.mixin
.IndicatorElement
= function OoUiMixinIndicatorElement( config
) {
2635 // Configuration initialization
2636 config
= config
|| {};
2639 this.$indicator
= null;
2640 this.indicator
= null;
2641 this.indicatorTitle
= null;
2644 this.setIndicator( config
.indicator
|| this.constructor.static.indicator
);
2645 this.setIndicatorTitle( config
.indicatorTitle
|| this.constructor.static.indicatorTitle
);
2646 this.setIndicatorElement( config
.$indicator
|| $( '<span>' ) );
2651 OO
.initClass( OO
.ui
.mixin
.IndicatorElement
);
2653 /* Static Properties */
2656 * Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2657 * The static property will be overridden if the #indicator configuration is used.
2661 * @property {string|null}
2663 OO
.ui
.mixin
.IndicatorElement
.static.indicator
= null;
2666 * A text string used as the indicator title, a function that returns title text, or `null`
2667 * for no title. The static property will be overridden if the #indicatorTitle configuration is used.
2671 * @property {string|Function|null}
2673 OO
.ui
.mixin
.IndicatorElement
.static.indicatorTitle
= null;
2678 * Set the indicator element.
2680 * If an element is already set, it will be cleaned up before setting up the new element.
2682 * @param {jQuery} $indicator Element to use as indicator
2684 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorElement = function ( $indicator
) {
2685 if ( this.$indicator
) {
2687 .removeClass( 'oo-ui-indicatorElement-indicator oo-ui-indicator-' + this.indicator
)
2688 .removeAttr( 'title' );
2691 this.$indicator
= $indicator
2692 .addClass( 'oo-ui-indicatorElement-indicator' )
2693 .toggleClass( 'oo-ui-indicator-' + this.indicator
, !!this.indicator
);
2694 if ( this.indicatorTitle
!== null ) {
2695 this.$indicator
.attr( 'title', this.indicatorTitle
);
2698 this.updateThemeClasses();
2702 * Set the indicator by its symbolic name: ‘alert’, ‘down’, ‘next’, ‘previous’, ‘required’, ‘up’. Use `null` to remove the indicator.
2704 * @param {string|null} indicator Symbolic name of indicator, or `null` for no indicator
2707 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicator = function ( indicator
) {
2708 indicator
= typeof indicator
=== 'string' && indicator
.length
? indicator
.trim() : null;
2710 if ( this.indicator
!== indicator
) {
2711 if ( this.$indicator
) {
2712 if ( this.indicator
!== null ) {
2713 this.$indicator
.removeClass( 'oo-ui-indicator-' + this.indicator
);
2715 if ( indicator
!== null ) {
2716 this.$indicator
.addClass( 'oo-ui-indicator-' + indicator
);
2719 this.indicator
= indicator
;
2722 this.$element
.toggleClass( 'oo-ui-indicatorElement', !!this.indicator
);
2723 this.updateThemeClasses();
2729 * Set the indicator title.
2731 * The title is displayed when a user moves the mouse over the indicator.
2733 * @param {string|Function|null} indicatorTitle Indicator title text, a function that returns text, or
2734 * `null` for no indicator title
2737 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorTitle = function ( indicatorTitle
) {
2738 indicatorTitle
= typeof indicatorTitle
=== 'function' ||
2739 ( typeof indicatorTitle
=== 'string' && indicatorTitle
.length
) ?
2740 OO
.ui
.resolveMsg( indicatorTitle
) : null;
2742 if ( this.indicatorTitle
!== indicatorTitle
) {
2743 this.indicatorTitle
= indicatorTitle
;
2744 if ( this.$indicator
) {
2745 if ( this.indicatorTitle
!== null ) {
2746 this.$indicator
.attr( 'title', indicatorTitle
);
2748 this.$indicator
.removeAttr( 'title' );
2757 * Get the symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2759 * @return {string} Symbolic name of indicator
2761 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicator = function () {
2762 return this.indicator
;
2766 * Get the indicator title.
2768 * The title is displayed when a user moves the mouse over the indicator.
2770 * @return {string} Indicator title text
2772 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicatorTitle = function () {
2773 return this.indicatorTitle
;
2777 * LabelElement is often mixed into other classes to generate a label, which
2778 * helps identify the function of an interface element.
2779 * See the [OOjs UI documentation on MediaWiki] [1] for more information.
2781 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2787 * @param {Object} [config] Configuration options
2788 * @cfg {jQuery} [$label] The label element created by the class. If this
2789 * configuration is omitted, the label element will use a generated `<span>`.
2790 * @cfg {jQuery|string|Function|OO.ui.HtmlSnippet} [label] The label text. The label can be specified
2791 * as a plaintext string, a jQuery selection of elements, or a function that will produce a string
2792 * in the future. See the [OOjs UI documentation on MediaWiki] [2] for examples.
2793 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2795 OO
.ui
.mixin
.LabelElement
= function OoUiMixinLabelElement( config
) {
2796 // Configuration initialization
2797 config
= config
|| {};
2804 this.setLabel( config
.label
|| this.constructor.static.label
);
2805 this.setLabelElement( config
.$label
|| $( '<span>' ) );
2810 OO
.initClass( OO
.ui
.mixin
.LabelElement
);
2815 * @event labelChange
2816 * @param {string} value
2819 /* Static Properties */
2822 * The label text. The label can be specified as a plaintext string, a function that will
2823 * produce a string in the future, or `null` for no label. The static value will
2824 * be overridden if a label is specified with the #label config option.
2828 * @property {string|Function|null}
2830 OO
.ui
.mixin
.LabelElement
.static.label
= null;
2832 /* Static methods */
2835 * Highlight the first occurrence of the query in the given text
2837 * @param {string} text Text
2838 * @param {string} query Query to find
2839 * @return {jQuery} Text with the first match of the query
2840 * sub-string wrapped in highlighted span
2842 OO
.ui
.mixin
.LabelElement
.static.highlightQuery = function ( text
, query
) {
2843 var $result
= $( '<span>' ),
2844 offset
= text
.toLowerCase().indexOf( query
.toLowerCase() );
2846 if ( !query
.length
|| offset
=== -1 ) {
2847 return $result
.text( text
);
2850 document
.createTextNode( text
.slice( 0, offset
) ),
2852 .addClass( 'oo-ui-labelElement-label-highlight' )
2853 .text( text
.slice( offset
, offset
+ query
.length
) ),
2854 document
.createTextNode( text
.slice( offset
+ query
.length
) )
2856 return $result
.contents();
2862 * Set the label element.
2864 * If an element is already set, it will be cleaned up before setting up the new element.
2866 * @param {jQuery} $label Element to use as label
2868 OO
.ui
.mixin
.LabelElement
.prototype.setLabelElement = function ( $label
) {
2869 if ( this.$label
) {
2870 this.$label
.removeClass( 'oo-ui-labelElement-label' ).empty();
2873 this.$label
= $label
.addClass( 'oo-ui-labelElement-label' );
2874 this.setLabelContent( this.label
);
2880 * An empty string will result in the label being hidden. A string containing only whitespace will
2881 * be converted to a single ` `.
2883 * @param {jQuery|string|OO.ui.HtmlSnippet|Function|null} label Label nodes; text; a function that returns nodes or
2884 * text; or null for no label
2887 OO
.ui
.mixin
.LabelElement
.prototype.setLabel = function ( label
) {
2888 label
= typeof label
=== 'function' ? OO
.ui
.resolveMsg( label
) : label
;
2889 label
= ( ( typeof label
=== 'string' || label
instanceof jQuery
) && label
.length
) || ( label
instanceof OO
.ui
.HtmlSnippet
&& label
.toString().length
) ? label
: null;
2891 if ( this.label
!== label
) {
2892 if ( this.$label
) {
2893 this.setLabelContent( label
);
2896 this.emit( 'labelChange' );
2899 this.$element
.toggleClass( 'oo-ui-labelElement', !!this.label
);
2905 * Set the label as plain text with a highlighted query
2907 * @param {string} text Text label to set
2908 * @param {string} query Substring of text to highlight
2911 OO
.ui
.mixin
.LabelElement
.prototype.setHighlightedQuery = function ( text
, query
) {
2912 return this.setLabel( this.constructor.static.highlightQuery( text
, query
) );
2918 * @return {jQuery|string|Function|null} Label nodes; text; a function that returns nodes or
2919 * text; or null for no label
2921 OO
.ui
.mixin
.LabelElement
.prototype.getLabel = function () {
2926 * Set the content of the label.
2928 * Do not call this method until after the label element has been set by #setLabelElement.
2931 * @param {jQuery|string|Function|null} label Label nodes; text; a function that returns nodes or
2932 * text; or null for no label
2934 OO
.ui
.mixin
.LabelElement
.prototype.setLabelContent = function ( label
) {
2935 if ( typeof label
=== 'string' ) {
2936 if ( label
.match( /^\s*$/ ) ) {
2937 // Convert whitespace only string to a single non-breaking space
2938 this.$label
.html( ' ' );
2940 this.$label
.text( label
);
2942 } else if ( label
instanceof OO
.ui
.HtmlSnippet
) {
2943 this.$label
.html( label
.toString() );
2944 } else if ( label
instanceof jQuery
) {
2945 this.$label
.empty().append( label
);
2947 this.$label
.empty();
2952 * The FlaggedElement class is an attribute mixin, meaning that it is used to add
2953 * additional functionality to an element created by another class. The class provides
2954 * a ‘flags’ property assigned the name (or an array of names) of styling flags,
2955 * which are used to customize the look and feel of a widget to better describe its
2956 * importance and functionality.
2958 * The library currently contains the following styling flags for general use:
2960 * - **progressive**: Progressive styling is applied to convey that the widget will move the user forward in a process.
2961 * - **destructive**: Destructive styling is applied to convey that the widget will remove something.
2962 * - **constructive**: Constructive styling is applied to convey that the widget will create something.
2964 * The flags affect the appearance of the buttons:
2967 * // FlaggedElement is mixed into ButtonWidget to provide styling flags
2968 * var button1 = new OO.ui.ButtonWidget( {
2969 * label: 'Constructive',
2970 * flags: 'constructive'
2972 * var button2 = new OO.ui.ButtonWidget( {
2973 * label: 'Destructive',
2974 * flags: 'destructive'
2976 * var button3 = new OO.ui.ButtonWidget( {
2977 * label: 'Progressive',
2978 * flags: 'progressive'
2980 * $( 'body' ).append( button1.$element, button2.$element, button3.$element );
2982 * {@link OO.ui.ActionWidget ActionWidgets}, which are a special kind of button that execute an action, use these flags: **primary** and **safe**.
2983 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
2985 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
2991 * @param {Object} [config] Configuration options
2992 * @cfg {string|string[]} [flags] The name or names of the flags (e.g., 'constructive' or 'primary') to apply.
2993 * Please see the [OOjs UI documentation on MediaWiki] [2] for more information about available flags.
2994 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
2995 * @cfg {jQuery} [$flagged] The flagged element. By default,
2996 * the flagged functionality is applied to the element created by the class ($element).
2997 * If a different element is specified, the flagged functionality will be applied to it instead.
2999 OO
.ui
.mixin
.FlaggedElement
= function OoUiMixinFlaggedElement( config
) {
3000 // Configuration initialization
3001 config
= config
|| {};
3005 this.$flagged
= null;
3008 this.setFlags( config
.flags
);
3009 this.setFlaggedElement( config
.$flagged
|| this.$element
);
3016 * A flag event is emitted when the #clearFlags or #setFlags methods are used. The `changes`
3017 * parameter contains the name of each modified flag and indicates whether it was
3020 * @param {Object.<string,boolean>} changes Object keyed by flag name. A Boolean `true` indicates
3021 * that the flag was added, `false` that the flag was removed.
3027 * Set the flagged element.
3029 * This method is used to retarget a flagged mixin so that its functionality applies to the specified element.
3030 * If an element is already set, the method will remove the mixin’s effect on that element.
3032 * @param {jQuery} $flagged Element that should be flagged
3034 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlaggedElement = function ( $flagged
) {
3035 var classNames
= Object
.keys( this.flags
).map( function ( flag
) {
3036 return 'oo-ui-flaggedElement-' + flag
;
3039 if ( this.$flagged
) {
3040 this.$flagged
.removeClass( classNames
);
3043 this.$flagged
= $flagged
.addClass( classNames
);
3047 * Check if the specified flag is set.
3049 * @param {string} flag Name of flag
3050 * @return {boolean} The flag is set
3052 OO
.ui
.mixin
.FlaggedElement
.prototype.hasFlag = function ( flag
) {
3053 // This may be called before the constructor, thus before this.flags is set
3054 return this.flags
&& ( flag
in this.flags
);
3058 * Get the names of all flags set.
3060 * @return {string[]} Flag names
3062 OO
.ui
.mixin
.FlaggedElement
.prototype.getFlags = function () {
3063 // This may be called before the constructor, thus before this.flags is set
3064 return Object
.keys( this.flags
|| {} );
3073 OO
.ui
.mixin
.FlaggedElement
.prototype.clearFlags = function () {
3074 var flag
, className
,
3077 classPrefix
= 'oo-ui-flaggedElement-';
3079 for ( flag
in this.flags
) {
3080 className
= classPrefix
+ flag
;
3081 changes
[ flag
] = false;
3082 delete this.flags
[ flag
];
3083 remove
.push( className
);
3086 if ( this.$flagged
) {
3087 this.$flagged
.removeClass( remove
.join( ' ' ) );
3090 this.updateThemeClasses();
3091 this.emit( 'flag', changes
);
3097 * Add one or more flags.
3099 * @param {string|string[]|Object.<string, boolean>} flags A flag name, an array of flag names,
3100 * or an object keyed by flag name with a boolean value that indicates whether the flag should
3101 * be added (`true`) or removed (`false`).
3105 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlags = function ( flags
) {
3106 var i
, len
, flag
, className
,
3110 classPrefix
= 'oo-ui-flaggedElement-';
3112 if ( typeof flags
=== 'string' ) {
3113 className
= classPrefix
+ flags
;
3115 if ( !this.flags
[ flags
] ) {
3116 this.flags
[ flags
] = true;
3117 add
.push( className
);
3119 } else if ( Array
.isArray( flags
) ) {
3120 for ( i
= 0, len
= flags
.length
; i
< len
; i
++ ) {
3122 className
= classPrefix
+ flag
;
3124 if ( !this.flags
[ flag
] ) {
3125 changes
[ flag
] = true;
3126 this.flags
[ flag
] = true;
3127 add
.push( className
);
3130 } else if ( OO
.isPlainObject( flags
) ) {
3131 for ( flag
in flags
) {
3132 className
= classPrefix
+ flag
;
3133 if ( flags
[ flag
] ) {
3135 if ( !this.flags
[ flag
] ) {
3136 changes
[ flag
] = true;
3137 this.flags
[ flag
] = true;
3138 add
.push( className
);
3142 if ( this.flags
[ flag
] ) {
3143 changes
[ flag
] = false;
3144 delete this.flags
[ flag
];
3145 remove
.push( className
);
3151 if ( this.$flagged
) {
3153 .addClass( add
.join( ' ' ) )
3154 .removeClass( remove
.join( ' ' ) );
3157 this.updateThemeClasses();
3158 this.emit( 'flag', changes
);
3164 * TitledElement is mixed into other classes to provide a `title` attribute.
3165 * Titles are rendered by the browser and are made visible when the user moves
3166 * the mouse over the element. Titles are not visible on touch devices.
3169 * // TitledElement provides a 'title' attribute to the
3170 * // ButtonWidget class
3171 * var button = new OO.ui.ButtonWidget( {
3172 * label: 'Button with Title',
3173 * title: 'I am a button'
3175 * $( 'body' ).append( button.$element );
3181 * @param {Object} [config] Configuration options
3182 * @cfg {jQuery} [$titled] The element to which the `title` attribute is applied.
3183 * If this config is omitted, the title functionality is applied to $element, the
3184 * element created by the class.
3185 * @cfg {string|Function} [title] The title text or a function that returns text. If
3186 * this config is omitted, the value of the {@link #static-title static title} property is used.
3188 OO
.ui
.mixin
.TitledElement
= function OoUiMixinTitledElement( config
) {
3189 // Configuration initialization
3190 config
= config
|| {};
3193 this.$titled
= null;
3197 this.setTitle( config
.title
!== undefined ? config
.title
: this.constructor.static.title
);
3198 this.setTitledElement( config
.$titled
|| this.$element
);
3203 OO
.initClass( OO
.ui
.mixin
.TitledElement
);
3205 /* Static Properties */
3208 * The title text, a function that returns text, or `null` for no title. The value of the static property
3209 * is overridden if the #title config option is used.
3213 * @property {string|Function|null}
3215 OO
.ui
.mixin
.TitledElement
.static.title
= null;
3220 * Set the titled element.
3222 * This method is used to retarget a titledElement mixin so that its functionality applies to the specified element.
3223 * If an element is already set, the mixin’s effect on that element is removed before the new element is set up.
3225 * @param {jQuery} $titled Element that should use the 'titled' functionality
3227 OO
.ui
.mixin
.TitledElement
.prototype.setTitledElement = function ( $titled
) {
3228 if ( this.$titled
) {
3229 this.$titled
.removeAttr( 'title' );
3232 this.$titled
= $titled
;
3234 this.$titled
.attr( 'title', this.title
);
3241 * @param {string|Function|null} title Title text, a function that returns text, or `null` for no title
3244 OO
.ui
.mixin
.TitledElement
.prototype.setTitle = function ( title
) {
3245 title
= typeof title
=== 'function' ? OO
.ui
.resolveMsg( title
) : title
;
3246 title
= ( typeof title
=== 'string' && title
.length
) ? title
: null;
3248 if ( this.title
!== title
) {
3249 if ( this.$titled
) {
3250 if ( title
!== null ) {
3251 this.$titled
.attr( 'title', title
);
3253 this.$titled
.removeAttr( 'title' );
3265 * @return {string} Title string
3267 OO
.ui
.mixin
.TitledElement
.prototype.getTitle = function () {
3272 * AccessKeyedElement is mixed into other classes to provide an `accesskey` attribute.
3273 * Accesskeys allow an user to go to a specific element by using
3274 * a shortcut combination of a browser specific keys + the key
3278 * // AccessKeyedElement provides an 'accesskey' attribute to the
3279 * // ButtonWidget class
3280 * var button = new OO.ui.ButtonWidget( {
3281 * label: 'Button with Accesskey',
3284 * $( 'body' ).append( button.$element );
3290 * @param {Object} [config] Configuration options
3291 * @cfg {jQuery} [$accessKeyed] The element to which the `accesskey` attribute is applied.
3292 * If this config is omitted, the accesskey functionality is applied to $element, the
3293 * element created by the class.
3294 * @cfg {string|Function} [accessKey] The key or a function that returns the key. If
3295 * this config is omitted, no accesskey will be added.
3297 OO
.ui
.mixin
.AccessKeyedElement
= function OoUiMixinAccessKeyedElement( config
) {
3298 // Configuration initialization
3299 config
= config
|| {};
3302 this.$accessKeyed
= null;
3303 this.accessKey
= null;
3306 this.setAccessKey( config
.accessKey
|| null );
3307 this.setAccessKeyedElement( config
.$accessKeyed
|| this.$element
);
3312 OO
.initClass( OO
.ui
.mixin
.AccessKeyedElement
);
3314 /* Static Properties */
3317 * The access key, a function that returns a key, or `null` for no accesskey.
3321 * @property {string|Function|null}
3323 OO
.ui
.mixin
.AccessKeyedElement
.static.accessKey
= null;
3328 * Set the accesskeyed element.
3330 * This method is used to retarget a AccessKeyedElement mixin so that its functionality applies to the specified element.
3331 * If an element is already set, the mixin's effect on that element is removed before the new element is set up.
3333 * @param {jQuery} $accessKeyed Element that should use the 'accesskeyes' functionality
3335 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKeyedElement = function ( $accessKeyed
) {
3336 if ( this.$accessKeyed
) {
3337 this.$accessKeyed
.removeAttr( 'accesskey' );
3340 this.$accessKeyed
= $accessKeyed
;
3341 if ( this.accessKey
) {
3342 this.$accessKeyed
.attr( 'accesskey', this.accessKey
);
3349 * @param {string|Function|null} accessKey Key, a function that returns a key, or `null` for no accesskey
3352 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKey = function ( accessKey
) {
3353 accessKey
= typeof accessKey
=== 'string' ? OO
.ui
.resolveMsg( accessKey
) : null;
3355 if ( this.accessKey
!== accessKey
) {
3356 if ( this.$accessKeyed
) {
3357 if ( accessKey
!== null ) {
3358 this.$accessKeyed
.attr( 'accesskey', accessKey
);
3360 this.$accessKeyed
.removeAttr( 'accesskey' );
3363 this.accessKey
= accessKey
;
3372 * @return {string} accessKey string
3374 OO
.ui
.mixin
.AccessKeyedElement
.prototype.getAccessKey = function () {
3375 return this.accessKey
;
3379 * ButtonWidget is a generic widget for buttons. A wide variety of looks,
3380 * feels, and functionality can be customized via the class’s configuration options
3381 * and methods. Please see the [OOjs UI documentation on MediaWiki] [1] for more information
3384 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches
3387 * // A button widget
3388 * var button = new OO.ui.ButtonWidget( {
3389 * label: 'Button with Icon',
3391 * iconTitle: 'Remove'
3393 * $( 'body' ).append( button.$element );
3395 * NOTE: HTML form buttons should use the OO.ui.ButtonInputWidget class.
3398 * @extends OO.ui.Widget
3399 * @mixins OO.ui.mixin.ButtonElement
3400 * @mixins OO.ui.mixin.IconElement
3401 * @mixins OO.ui.mixin.IndicatorElement
3402 * @mixins OO.ui.mixin.LabelElement
3403 * @mixins OO.ui.mixin.TitledElement
3404 * @mixins OO.ui.mixin.FlaggedElement
3405 * @mixins OO.ui.mixin.TabIndexedElement
3406 * @mixins OO.ui.mixin.AccessKeyedElement
3409 * @param {Object} [config] Configuration options
3410 * @cfg {boolean} [active=false] Whether button should be shown as active
3411 * @cfg {string} [href] Hyperlink to visit when the button is clicked.
3412 * @cfg {string} [target] The frame or window in which to open the hyperlink.
3413 * @cfg {boolean} [noFollow] Search engine traversal hint (default: true)
3415 OO
.ui
.ButtonWidget
= function OoUiButtonWidget( config
) {
3416 // Configuration initialization
3417 config
= config
|| {};
3419 // Parent constructor
3420 OO
.ui
.ButtonWidget
.parent
.call( this, config
);
3422 // Mixin constructors
3423 OO
.ui
.mixin
.ButtonElement
.call( this, config
);
3424 OO
.ui
.mixin
.IconElement
.call( this, config
);
3425 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
3426 OO
.ui
.mixin
.LabelElement
.call( this, config
);
3427 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$button
} ) );
3428 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
3429 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$button
} ) );
3430 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$button
} ) );
3435 this.noFollow
= false;
3438 this.connect( this, { disable
: 'onDisable' } );
3441 this.$button
.append( this.$icon
, this.$label
, this.$indicator
);
3443 .addClass( 'oo-ui-buttonWidget' )
3444 .append( this.$button
);
3445 this.setActive( config
.active
);
3446 this.setHref( config
.href
);
3447 this.setTarget( config
.target
);
3448 this.setNoFollow( config
.noFollow
);
3453 OO
.inheritClass( OO
.ui
.ButtonWidget
, OO
.ui
.Widget
);
3454 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.ButtonElement
);
3455 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IconElement
);
3456 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IndicatorElement
);
3457 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.LabelElement
);
3458 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TitledElement
);
3459 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.FlaggedElement
);
3460 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TabIndexedElement
);
3461 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
3463 /* Static Properties */
3468 OO
.ui
.ButtonWidget
.static.cancelButtonMouseDownEvents
= false;
3473 * Get hyperlink location.
3475 * @return {string} Hyperlink location
3477 OO
.ui
.ButtonWidget
.prototype.getHref = function () {
3482 * Get hyperlink target.
3484 * @return {string} Hyperlink target
3486 OO
.ui
.ButtonWidget
.prototype.getTarget = function () {
3491 * Get search engine traversal hint.
3493 * @return {boolean} Whether search engines should avoid traversing this hyperlink
3495 OO
.ui
.ButtonWidget
.prototype.getNoFollow = function () {
3496 return this.noFollow
;
3500 * Set hyperlink location.
3502 * @param {string|null} href Hyperlink location, null to remove
3504 OO
.ui
.ButtonWidget
.prototype.setHref = function ( href
) {
3505 href
= typeof href
=== 'string' ? href
: null;
3506 if ( href
!== null && !OO
.ui
.isSafeUrl( href
) ) {
3510 if ( href
!== this.href
) {
3519 * Update the `href` attribute, in case of changes to href or
3525 OO
.ui
.ButtonWidget
.prototype.updateHref = function () {
3526 if ( this.href
!== null && !this.isDisabled() ) {
3527 this.$button
.attr( 'href', this.href
);
3529 this.$button
.removeAttr( 'href' );
3536 * Handle disable events.
3539 * @param {boolean} disabled Element is disabled
3541 OO
.ui
.ButtonWidget
.prototype.onDisable = function () {
3546 * Set hyperlink target.
3548 * @param {string|null} target Hyperlink target, null to remove
3550 OO
.ui
.ButtonWidget
.prototype.setTarget = function ( target
) {
3551 target
= typeof target
=== 'string' ? target
: null;
3553 if ( target
!== this.target
) {
3554 this.target
= target
;
3555 if ( target
!== null ) {
3556 this.$button
.attr( 'target', target
);
3558 this.$button
.removeAttr( 'target' );
3566 * Set search engine traversal hint.
3568 * @param {boolean} noFollow True if search engines should avoid traversing this hyperlink
3570 OO
.ui
.ButtonWidget
.prototype.setNoFollow = function ( noFollow
) {
3571 noFollow
= typeof noFollow
=== 'boolean' ? noFollow
: true;
3573 if ( noFollow
!== this.noFollow
) {
3574 this.noFollow
= noFollow
;
3576 this.$button
.attr( 'rel', 'nofollow' );
3578 this.$button
.removeAttr( 'rel' );
3585 // 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
);
3648 * IconWidget is a generic widget for {@link OO.ui.mixin.IconElement icons}. In general, IconWidgets should be used with OO.ui.LabelWidget,
3649 * which creates a label that identifies the icon’s function. See the [OOjs UI documentation on MediaWiki] [1]
3650 * for a list of icons included in the library.
3653 * // An icon widget with a label
3654 * var myIcon = new OO.ui.IconWidget( {
3658 * // Create a label.
3659 * var iconLabel = new OO.ui.LabelWidget( {
3662 * $( 'body' ).append( myIcon.$element, iconLabel.$element );
3664 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
3667 * @extends OO.ui.Widget
3668 * @mixins OO.ui.mixin.IconElement
3669 * @mixins OO.ui.mixin.TitledElement
3670 * @mixins OO.ui.mixin.FlaggedElement
3673 * @param {Object} [config] Configuration options
3675 OO
.ui
.IconWidget
= function OoUiIconWidget( config
) {
3676 // Configuration initialization
3677 config
= config
|| {};
3679 // Parent constructor
3680 OO
.ui
.IconWidget
.parent
.call( this, config
);
3682 // Mixin constructors
3683 OO
.ui
.mixin
.IconElement
.call( this, $.extend( {}, config
, { $icon
: this.$element
} ) );
3684 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3685 OO
.ui
.mixin
.FlaggedElement
.call( this, $.extend( {}, config
, { $flagged
: this.$element
} ) );
3688 this.$element
.addClass( 'oo-ui-iconWidget' );
3693 OO
.inheritClass( OO
.ui
.IconWidget
, OO
.ui
.Widget
);
3694 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.IconElement
);
3695 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.TitledElement
);
3696 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.FlaggedElement
);
3698 /* Static Properties */
3700 OO
.ui
.IconWidget
.static.tagName
= 'span';
3703 * IndicatorWidgets create indicators, which are small graphics that are generally used to draw
3704 * attention to the status of an item or to clarify the function of a control. For a list of
3705 * indicators included in the library, please see the [OOjs UI documentation on MediaWiki][1].
3708 * // Example of an indicator widget
3709 * var indicator1 = new OO.ui.IndicatorWidget( {
3710 * indicator: 'alert'
3713 * // Create a fieldset layout to add a label
3714 * var fieldset = new OO.ui.FieldsetLayout();
3715 * fieldset.addItems( [
3716 * new OO.ui.FieldLayout( indicator1, { label: 'An alert indicator:' } )
3718 * $( 'body' ).append( fieldset.$element );
3720 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
3723 * @extends OO.ui.Widget
3724 * @mixins OO.ui.mixin.IndicatorElement
3725 * @mixins OO.ui.mixin.TitledElement
3728 * @param {Object} [config] Configuration options
3730 OO
.ui
.IndicatorWidget
= function OoUiIndicatorWidget( config
) {
3731 // Configuration initialization
3732 config
= config
|| {};
3734 // Parent constructor
3735 OO
.ui
.IndicatorWidget
.parent
.call( this, config
);
3737 // Mixin constructors
3738 OO
.ui
.mixin
.IndicatorElement
.call( this, $.extend( {}, config
, { $indicator
: this.$element
} ) );
3739 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3742 this.$element
.addClass( 'oo-ui-indicatorWidget' );
3747 OO
.inheritClass( OO
.ui
.IndicatorWidget
, OO
.ui
.Widget
);
3748 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.IndicatorElement
);
3749 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.TitledElement
);
3751 /* Static Properties */
3753 OO
.ui
.IndicatorWidget
.static.tagName
= 'span';
3756 * LabelWidgets help identify the function of interface elements. Each LabelWidget can
3757 * be configured with a `label` option that is set to a string, a label node, or a function:
3759 * - String: a plaintext string
3760 * - jQuery selection: a jQuery selection, used for anything other than a plaintext label, e.g., a
3761 * label that includes a link or special styling, such as a gray color or additional graphical elements.
3762 * - Function: a function that will produce a string in the future. Functions are used
3763 * in cases where the value of the label is not currently defined.
3765 * In addition, the LabelWidget can be associated with an {@link OO.ui.InputWidget input widget}, which
3766 * will come into focus when the label is clicked.
3769 * // Examples of LabelWidgets
3770 * var label1 = new OO.ui.LabelWidget( {
3771 * label: 'plaintext label'
3773 * var label2 = new OO.ui.LabelWidget( {
3774 * label: $( '<a href="default.html">jQuery label</a>' )
3776 * // Create a fieldset layout with fields for each example
3777 * var fieldset = new OO.ui.FieldsetLayout();
3778 * fieldset.addItems( [
3779 * new OO.ui.FieldLayout( label1 ),
3780 * new OO.ui.FieldLayout( label2 )
3782 * $( 'body' ).append( fieldset.$element );
3785 * @extends OO.ui.Widget
3786 * @mixins OO.ui.mixin.LabelElement
3787 * @mixins OO.ui.mixin.TitledElement
3790 * @param {Object} [config] Configuration options
3791 * @cfg {OO.ui.InputWidget} [input] {@link OO.ui.InputWidget Input widget} that uses the label.
3792 * Clicking the label will focus the specified input field.
3794 OO
.ui
.LabelWidget
= function OoUiLabelWidget( config
) {
3795 // Configuration initialization
3796 config
= config
|| {};
3798 // Parent constructor
3799 OO
.ui
.LabelWidget
.parent
.call( this, config
);
3801 // Mixin constructors
3802 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, { $label
: this.$element
} ) );
3803 OO
.ui
.mixin
.TitledElement
.call( this, config
);
3806 this.input
= config
.input
;
3809 if ( this.input
instanceof OO
.ui
.InputWidget
) {
3810 this.$element
.on( 'click', this.onClick
.bind( this ) );
3814 this.$element
.addClass( 'oo-ui-labelWidget' );
3819 OO
.inheritClass( OO
.ui
.LabelWidget
, OO
.ui
.Widget
);
3820 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.LabelElement
);
3821 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.TitledElement
);
3823 /* Static Properties */
3825 OO
.ui
.LabelWidget
.static.tagName
= 'span';
3830 * Handles label mouse click events.
3833 * @param {jQuery.Event} e Mouse click event
3835 OO
.ui
.LabelWidget
.prototype.onClick = function () {
3836 this.input
.simulateLabelClick();
3841 * PendingElement is a mixin that is used to create elements that notify users that something is happening
3842 * and that they should wait before proceeding. The pending state is visually represented with a pending
3843 * texture that appears in the head of a pending {@link OO.ui.ProcessDialog process dialog} or in the input
3844 * field of a {@link OO.ui.TextInputWidget text input widget}.
3846 * Currently, {@link OO.ui.ActionWidget Action widgets}, which mix in this class, can also be marked as pending, but only when
3847 * used in {@link OO.ui.MessageDialog message dialogs}. The behavior is not currently supported for action widgets used
3848 * in process dialogs.
3851 * function MessageDialog( config ) {
3852 * MessageDialog.parent.call( this, config );
3854 * OO.inheritClass( MessageDialog, OO.ui.MessageDialog );
3856 * MessageDialog.static.actions = [
3857 * { action: 'save', label: 'Done', flags: 'primary' },
3858 * { label: 'Cancel', flags: 'safe' }
3861 * MessageDialog.prototype.initialize = function () {
3862 * MessageDialog.parent.prototype.initialize.apply( this, arguments );
3863 * this.content = new OO.ui.PanelLayout( { $: this.$, padded: true } );
3864 * 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>' );
3865 * this.$body.append( this.content.$element );
3867 * MessageDialog.prototype.getBodyHeight = function () {
3870 * MessageDialog.prototype.getActionProcess = function ( action ) {
3871 * var dialog = this;
3872 * if ( action === 'save' ) {
3873 * dialog.getActions().get({actions: 'save'})[0].pushPending();
3874 * return new OO.ui.Process()
3876 * .next( function () {
3877 * dialog.getActions().get({actions: 'save'})[0].popPending();
3880 * return MessageDialog.parent.prototype.getActionProcess.call( this, action );
3883 * var windowManager = new OO.ui.WindowManager();
3884 * $( 'body' ).append( windowManager.$element );
3886 * var dialog = new MessageDialog();
3887 * windowManager.addWindows( [ dialog ] );
3888 * windowManager.openWindow( dialog );
3894 * @param {Object} [config] Configuration options
3895 * @cfg {jQuery} [$pending] Element to mark as pending, defaults to this.$element
3897 OO
.ui
.mixin
.PendingElement
= function OoUiMixinPendingElement( config
) {
3898 // Configuration initialization
3899 config
= config
|| {};
3903 this.$pending
= null;
3906 this.setPendingElement( config
.$pending
|| this.$element
);
3911 OO
.initClass( OO
.ui
.mixin
.PendingElement
);
3916 * Set the pending element (and clean up any existing one).
3918 * @param {jQuery} $pending The element to set to pending.
3920 OO
.ui
.mixin
.PendingElement
.prototype.setPendingElement = function ( $pending
) {
3921 if ( this.$pending
) {
3922 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
3925 this.$pending
= $pending
;
3926 if ( this.pending
> 0 ) {
3927 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
3932 * Check if an element is pending.
3934 * @return {boolean} Element is pending
3936 OO
.ui
.mixin
.PendingElement
.prototype.isPending = function () {
3937 return !!this.pending
;
3941 * Increase the pending counter. The pending state will remain active until the counter is zero
3942 * (i.e., the number of calls to #pushPending and #popPending is the same).
3946 OO
.ui
.mixin
.PendingElement
.prototype.pushPending = function () {
3947 if ( this.pending
=== 0 ) {
3948 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
3949 this.updateThemeClasses();
3957 * Decrease the pending counter. The pending state will remain active until the counter is zero
3958 * (i.e., the number of calls to #pushPending and #popPending is the same).
3962 OO
.ui
.mixin
.PendingElement
.prototype.popPending = function () {
3963 if ( this.pending
=== 1 ) {
3964 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
3965 this.updateThemeClasses();
3967 this.pending
= Math
.max( 0, this.pending
- 1 );
3973 * Element that will stick under a specified container, even when it is inserted elsewhere in the
3974 * document (for example, in a OO.ui.Window's $overlay).
3976 * The elements's position is automatically calculated and maintained when window is resized or the
3977 * page is scrolled. If you reposition the container manually, you have to call #position to make
3978 * sure the element is still placed correctly.
3980 * As positioning is only possible when both the element and the container are attached to the DOM
3981 * and visible, it's only done after you call #togglePositioning. You might want to do this inside
3982 * the #toggle method to display a floating popup, for example.
3988 * @param {Object} [config] Configuration options
3989 * @cfg {jQuery} [$floatable] Node to position, assigned to #$floatable, omit to use #$element
3990 * @cfg {jQuery} [$floatableContainer] Node to position below
3992 OO
.ui
.mixin
.FloatableElement
= function OoUiMixinFloatableElement( config
) {
3993 // Configuration initialization
3994 config
= config
|| {};
3997 this.$floatable
= null;
3998 this.$floatableContainer
= null;
3999 this.$floatableWindow
= null;
4000 this.$floatableClosestScrollable
= null;
4001 this.onFloatableScrollHandler
= this.position
.bind( this );
4002 this.onFloatableWindowResizeHandler
= this.position
.bind( this );
4005 this.setFloatableContainer( config
.$floatableContainer
);
4006 this.setFloatableElement( config
.$floatable
|| this.$element
);
4012 * Set floatable element.
4014 * If an element is already set, it will be cleaned up before setting up the new element.
4016 * @param {jQuery} $floatable Element to make floatable
4018 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableElement = function ( $floatable
) {
4019 if ( this.$floatable
) {
4020 this.$floatable
.removeClass( 'oo-ui-floatableElement-floatable' );
4021 this.$floatable
.css( { left
: '', top
: '' } );
4024 this.$floatable
= $floatable
.addClass( 'oo-ui-floatableElement-floatable' );
4029 * Set floatable container.
4031 * The element will be always positioned under the specified container.
4033 * @param {jQuery|null} $floatableContainer Container to keep visible, or null to unset
4035 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableContainer = function ( $floatableContainer
) {
4036 this.$floatableContainer
= $floatableContainer
;
4037 if ( this.$floatable
) {
4043 * Toggle positioning.
4045 * Do not turn positioning on until after the element is attached to the DOM and visible.
4047 * @param {boolean} [positioning] Enable positioning, omit to toggle
4050 OO
.ui
.mixin
.FloatableElement
.prototype.togglePositioning = function ( positioning
) {
4051 var closestScrollableOfContainer
;
4053 if ( !this.$floatable
|| !this.$floatableContainer
) {
4057 positioning
= positioning
=== undefined ? !this.positioning
: !!positioning
;
4059 if ( this.positioning
!== positioning
) {
4060 this.positioning
= positioning
;
4062 closestScrollableOfContainer
= OO
.ui
.Element
.static.getClosestScrollableContainer( this.$floatableContainer
[ 0 ] );
4063 this.needsCustomPosition
= !OO
.ui
.contains( this.$floatableContainer
[ 0 ], this.$floatable
[ 0 ] );
4064 // If the scrollable is the root, we have to listen to scroll events
4065 // on the window because of browser inconsistencies.
4066 if ( $( closestScrollableOfContainer
).is( 'html, body' ) ) {
4067 closestScrollableOfContainer
= OO
.ui
.Element
.static.getWindow( closestScrollableOfContainer
);
4070 if ( positioning
) {
4071 this.$floatableWindow
= $( this.getElementWindow() );
4072 this.$floatableWindow
.on( 'resize', this.onFloatableWindowResizeHandler
);
4074 this.$floatableClosestScrollable
= $( closestScrollableOfContainer
);
4075 this.$floatableClosestScrollable
.on( 'scroll', this.onFloatableScrollHandler
);
4077 // Initial position after visible
4080 if ( this.$floatableWindow
) {
4081 this.$floatableWindow
.off( 'resize', this.onFloatableWindowResizeHandler
);
4082 this.$floatableWindow
= null;
4085 if ( this.$floatableClosestScrollable
) {
4086 this.$floatableClosestScrollable
.off( 'scroll', this.onFloatableScrollHandler
);
4087 this.$floatableClosestScrollable
= null;
4090 this.$floatable
.css( { left
: '', top
: '' } );
4098 * Check whether the bottom edge of the given element is within the viewport of the given container.
4101 * @param {jQuery} $element
4102 * @param {jQuery} $container
4105 OO
.ui
.mixin
.FloatableElement
.prototype.isElementInViewport = function ( $element
, $container
) {
4106 var elemRect
, contRect
,
4107 leftEdgeInBounds
= false,
4108 bottomEdgeInBounds
= false,
4109 rightEdgeInBounds
= false;
4111 elemRect
= $element
[ 0 ].getBoundingClientRect();
4112 if ( $container
[ 0 ] === window
) {
4116 right
: document
.documentElement
.clientWidth
,
4117 bottom
: document
.documentElement
.clientHeight
4120 contRect
= $container
[ 0 ].getBoundingClientRect();
4123 // For completeness, if we still cared about topEdgeInBounds, that'd be:
4124 // elemRect.top >= contRect.top && elemRect.top <= contRect.bottom
4125 if ( elemRect
.left
>= contRect
.left
&& elemRect
.left
<= contRect
.right
) {
4126 leftEdgeInBounds
= true;
4128 if ( elemRect
.bottom
>= contRect
.top
&& elemRect
.bottom
<= contRect
.bottom
) {
4129 bottomEdgeInBounds
= true;
4131 if ( elemRect
.right
>= contRect
.left
&& elemRect
.right
<= contRect
.right
) {
4132 rightEdgeInBounds
= true;
4135 // We only care that any part of the bottom edge is visible
4136 return bottomEdgeInBounds
&& ( leftEdgeInBounds
|| rightEdgeInBounds
);
4140 * Position the floatable below its container.
4142 * This should only be done when both of them are attached to the DOM and visible.
4146 OO
.ui
.mixin
.FloatableElement
.prototype.position = function () {
4149 if ( !this.positioning
) {
4153 if ( !this.isElementInViewport( this.$floatableContainer
, this.$floatableClosestScrollable
) ) {
4154 this.$floatable
.addClass( 'oo-ui-element-hidden' );
4157 this.$floatable
.removeClass( 'oo-ui-element-hidden' );
4160 if ( !this.needsCustomPosition
) {
4164 pos
= OO
.ui
.Element
.static.getRelativePosition( this.$floatableContainer
, this.$floatable
.offsetParent() );
4166 // Position under container
4167 pos
.top
+= this.$floatableContainer
.height();
4168 this.$floatable
.css( pos
);
4170 // We updated the position, so re-evaluate the clipping state.
4171 // (ClippableElement does not listen to 'scroll' events on $floatableContainer's parent, and so
4172 // will not notice the need to update itself.)
4173 // TODO: This is terrible, we shouldn't need to know about ClippableElement at all here. Why does
4174 // it not listen to the right events in the right places?
4183 * Element that can be automatically clipped to visible boundaries.
4185 * Whenever the element's natural height changes, you have to call
4186 * {@link OO.ui.mixin.ClippableElement#clip} to make sure it's still
4187 * clipping correctly.
4189 * The dimensions of #$clippableContainer will be compared to the boundaries of the
4190 * nearest scrollable container. If #$clippableContainer is too tall and/or too wide,
4191 * then #$clippable will be given a fixed reduced height and/or width and will be made
4192 * scrollable. By default, #$clippable and #$clippableContainer are the same element,
4193 * but you can build a static footer by setting #$clippableContainer to an element that contains
4194 * #$clippable and the footer.
4200 * @param {Object} [config] Configuration options
4201 * @cfg {jQuery} [$clippable] Node to clip, assigned to #$clippable, omit to use #$element
4202 * @cfg {jQuery} [$clippableContainer] Node to keep visible, assigned to #$clippableContainer,
4203 * omit to use #$clippable
4205 OO
.ui
.mixin
.ClippableElement
= function OoUiMixinClippableElement( config
) {
4206 // Configuration initialization
4207 config
= config
|| {};
4210 this.$clippable
= null;
4211 this.$clippableContainer
= null;
4212 this.clipping
= false;
4213 this.clippedHorizontally
= false;
4214 this.clippedVertically
= false;
4215 this.$clippableScrollableContainer
= null;
4216 this.$clippableScroller
= null;
4217 this.$clippableWindow
= null;
4218 this.idealWidth
= null;
4219 this.idealHeight
= null;
4220 this.onClippableScrollHandler
= this.clip
.bind( this );
4221 this.onClippableWindowResizeHandler
= this.clip
.bind( this );
4224 if ( config
.$clippableContainer
) {
4225 this.setClippableContainer( config
.$clippableContainer
);
4227 this.setClippableElement( config
.$clippable
|| this.$element
);
4233 * Set clippable element.
4235 * If an element is already set, it will be cleaned up before setting up the new element.
4237 * @param {jQuery} $clippable Element to make clippable
4239 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableElement = function ( $clippable
) {
4240 if ( this.$clippable
) {
4241 this.$clippable
.removeClass( 'oo-ui-clippableElement-clippable' );
4242 this.$clippable
.css( { width
: '', height
: '', overflowX
: '', overflowY
: '' } );
4243 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4246 this.$clippable
= $clippable
.addClass( 'oo-ui-clippableElement-clippable' );
4251 * Set clippable container.
4253 * This is the container that will be measured when deciding whether to clip. When clipping,
4254 * #$clippable will be resized in order to keep the clippable container fully visible.
4256 * If the clippable container is unset, #$clippable will be used.
4258 * @param {jQuery|null} $clippableContainer Container to keep visible, or null to unset
4260 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableContainer = function ( $clippableContainer
) {
4261 this.$clippableContainer
= $clippableContainer
;
4262 if ( this.$clippable
) {
4270 * Do not turn clipping on until after the element is attached to the DOM and visible.
4272 * @param {boolean} [clipping] Enable clipping, omit to toggle
4275 OO
.ui
.mixin
.ClippableElement
.prototype.toggleClipping = function ( clipping
) {
4276 clipping
= clipping
=== undefined ? !this.clipping
: !!clipping
;
4278 if ( this.clipping
!== clipping
) {
4279 this.clipping
= clipping
;
4281 this.$clippableScrollableContainer
= $( this.getClosestScrollableElementContainer() );
4282 // If the clippable container is the root, we have to listen to scroll events and check
4283 // jQuery.scrollTop on the window because of browser inconsistencies
4284 this.$clippableScroller
= this.$clippableScrollableContainer
.is( 'html, body' ) ?
4285 $( OO
.ui
.Element
.static.getWindow( this.$clippableScrollableContainer
) ) :
4286 this.$clippableScrollableContainer
;
4287 this.$clippableScroller
.on( 'scroll', this.onClippableScrollHandler
);
4288 this.$clippableWindow
= $( this.getElementWindow() )
4289 .on( 'resize', this.onClippableWindowResizeHandler
);
4290 // Initial clip after visible
4293 this.$clippable
.css( {
4301 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4303 this.$clippableScrollableContainer
= null;
4304 this.$clippableScroller
.off( 'scroll', this.onClippableScrollHandler
);
4305 this.$clippableScroller
= null;
4306 this.$clippableWindow
.off( 'resize', this.onClippableWindowResizeHandler
);
4307 this.$clippableWindow
= null;
4315 * Check if the element will be clipped to fit the visible area of the nearest scrollable container.
4317 * @return {boolean} Element will be clipped to the visible area
4319 OO
.ui
.mixin
.ClippableElement
.prototype.isClipping = function () {
4320 return this.clipping
;
4324 * Check if the bottom or right of the element is being clipped by the nearest scrollable container.
4326 * @return {boolean} Part of the element is being clipped
4328 OO
.ui
.mixin
.ClippableElement
.prototype.isClipped = function () {
4329 return this.clippedHorizontally
|| this.clippedVertically
;
4333 * Check if the right of the element is being clipped by the nearest scrollable container.
4335 * @return {boolean} Part of the element is being clipped
4337 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedHorizontally = function () {
4338 return this.clippedHorizontally
;
4342 * Check if the bottom of the element is being clipped by the nearest scrollable container.
4344 * @return {boolean} Part of the element is being clipped
4346 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedVertically = function () {
4347 return this.clippedVertically
;
4351 * Set the ideal size. These are the dimensions the element will have when it's not being clipped.
4353 * @param {number|string} [width] Width as a number of pixels or CSS string with unit suffix
4354 * @param {number|string} [height] Height as a number of pixels or CSS string with unit suffix
4356 OO
.ui
.mixin
.ClippableElement
.prototype.setIdealSize = function ( width
, height
) {
4357 this.idealWidth
= width
;
4358 this.idealHeight
= height
;
4360 if ( !this.clipping
) {
4361 // Update dimensions
4362 this.$clippable
.css( { width
: width
, height
: height
} );
4364 // While clipping, idealWidth and idealHeight are not considered
4368 * Clip element to visible boundaries and allow scrolling when needed. You should call this method
4369 * when the element's natural height changes.
4371 * Element will be clipped the bottom or right of the element is within 10px of the edge of, or
4372 * overlapped by, the visible area of the nearest scrollable container.
4374 * Because calling clip() when the natural height changes isn't always possible, we also set
4375 * max-height when the element isn't being clipped. This means that if the element tries to grow
4376 * beyond the edge, something reasonable will happen before clip() is called.
4380 OO
.ui
.mixin
.ClippableElement
.prototype.clip = function () {
4381 var $container
, extraHeight
, extraWidth
, ccOffset
,
4382 $scrollableContainer
, scOffset
, scHeight
, scWidth
,
4383 ccWidth
, scrollerIsWindow
, scrollTop
, scrollLeft
,
4384 desiredWidth
, desiredHeight
, allotedWidth
, allotedHeight
,
4385 naturalWidth
, naturalHeight
, clipWidth
, clipHeight
,
4386 buffer
= 7; // Chosen by fair dice roll
4388 if ( !this.clipping
) {
4389 // this.$clippableScrollableContainer and this.$clippableWindow are null, so the below will fail
4393 $container
= this.$clippableContainer
|| this.$clippable
;
4394 extraHeight
= $container
.outerHeight() - this.$clippable
.outerHeight();
4395 extraWidth
= $container
.outerWidth() - this.$clippable
.outerWidth();
4396 ccOffset
= $container
.offset();
4397 if ( this.$clippableScrollableContainer
.is( 'html, body' ) ) {
4398 $scrollableContainer
= this.$clippableWindow
;
4399 scOffset
= { top
: 0, left
: 0 };
4401 $scrollableContainer
= this.$clippableScrollableContainer
;
4402 scOffset
= $scrollableContainer
.offset();
4404 scHeight
= $scrollableContainer
.innerHeight() - buffer
;
4405 scWidth
= $scrollableContainer
.innerWidth() - buffer
;
4406 ccWidth
= $container
.outerWidth() + buffer
;
4407 scrollerIsWindow
= this.$clippableScroller
[ 0 ] === this.$clippableWindow
[ 0 ];
4408 scrollTop
= scrollerIsWindow
? this.$clippableScroller
.scrollTop() : 0;
4409 scrollLeft
= scrollerIsWindow
? this.$clippableScroller
.scrollLeft() : 0;
4410 desiredWidth
= ccOffset
.left
< 0 ?
4411 ccWidth
+ ccOffset
.left
:
4412 ( scOffset
.left
+ scrollLeft
+ scWidth
) - ccOffset
.left
;
4413 desiredHeight
= ( scOffset
.top
+ scrollTop
+ scHeight
) - ccOffset
.top
;
4414 // It should never be desirable to exceed the dimensions of the browser viewport... right?
4415 desiredWidth
= Math
.min( desiredWidth
, document
.documentElement
.clientWidth
);
4416 desiredHeight
= Math
.min( desiredHeight
, document
.documentElement
.clientHeight
);
4417 allotedWidth
= Math
.ceil( desiredWidth
- extraWidth
);
4418 allotedHeight
= Math
.ceil( desiredHeight
- extraHeight
);
4419 naturalWidth
= this.$clippable
.prop( 'scrollWidth' );
4420 naturalHeight
= this.$clippable
.prop( 'scrollHeight' );
4421 clipWidth
= allotedWidth
< naturalWidth
;
4422 clipHeight
= allotedHeight
< naturalHeight
;
4425 this.$clippable
.css( {
4426 overflowX
: 'scroll',
4427 width
: Math
.max( 0, allotedWidth
),
4431 this.$clippable
.css( {
4433 width
: this.idealWidth
? this.idealWidth
- extraWidth
: '',
4434 maxWidth
: Math
.max( 0, allotedWidth
)
4438 this.$clippable
.css( {
4439 overflowY
: 'scroll',
4440 height
: Math
.max( 0, allotedHeight
),
4444 this.$clippable
.css( {
4446 height
: this.idealHeight
? this.idealHeight
- extraHeight
: '',
4447 maxHeight
: Math
.max( 0, allotedHeight
)
4451 // If we stopped clipping in at least one of the dimensions
4452 if ( ( this.clippedHorizontally
&& !clipWidth
) || ( this.clippedVertically
&& !clipHeight
) ) {
4453 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4456 this.clippedHorizontally
= clipWidth
;
4457 this.clippedVertically
= clipHeight
;
4463 * PopupWidget is a container for content. The popup is overlaid and positioned absolutely.
4464 * By default, each popup has an anchor that points toward its origin.
4465 * Please see the [OOjs UI documentation on Mediawiki] [1] for more information and examples.
4468 * // A popup widget.
4469 * var popup = new OO.ui.PopupWidget( {
4470 * $content: $( '<p>Hi there!</p>' ),
4475 * $( 'body' ).append( popup.$element );
4476 * // To display the popup, toggle the visibility to 'true'.
4477 * popup.toggle( true );
4479 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups
4482 * @extends OO.ui.Widget
4483 * @mixins OO.ui.mixin.LabelElement
4484 * @mixins OO.ui.mixin.ClippableElement
4485 * @mixins OO.ui.mixin.FloatableElement
4488 * @param {Object} [config] Configuration options
4489 * @cfg {number} [width=320] Width of popup in pixels
4490 * @cfg {number} [height] Height of popup in pixels. Omit to use the automatic height.
4491 * @cfg {boolean} [anchor=true] Show anchor pointing to origin of popup
4492 * @cfg {string} [align='center'] Alignment of the popup: `center`, `force-left`, `force-right`, `backwards` or `forwards`.
4493 * If the popup is forced-left the popup body is leaning towards the left. For force-right alignment, the body of the
4494 * popup is leaning towards the right of the screen.
4495 * Using 'backwards' is a logical direction which will result in the popup leaning towards the beginning of the sentence
4496 * in the given language, which means it will flip to the correct positioning in right-to-left languages.
4497 * Using 'forward' will also result in a logical alignment where the body of the popup leans towards the end of the
4498 * sentence in the given language.
4499 * @cfg {jQuery} [$container] Constrain the popup to the boundaries of the specified container.
4500 * See the [OOjs UI docs on MediaWiki][3] for an example.
4501 * [3]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#containerExample
4502 * @cfg {number} [containerPadding=10] Padding between the popup and its container, specified as a number of pixels.
4503 * @cfg {jQuery} [$content] Content to append to the popup's body
4504 * @cfg {jQuery} [$footer] Content to append to the popup's footer
4505 * @cfg {boolean} [autoClose=false] Automatically close the popup when it loses focus.
4506 * @cfg {jQuery} [$autoCloseIgnore] Elements that will not close the popup when clicked.
4507 * This config option is only relevant if #autoClose is set to `true`. See the [OOjs UI docs on MediaWiki][2]
4509 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#autocloseExample
4510 * @cfg {boolean} [head=false] Show a popup header that contains a #label (if specified) and close
4512 * @cfg {boolean} [padded=false] Add padding to the popup's body
4514 OO
.ui
.PopupWidget
= function OoUiPopupWidget( config
) {
4515 // Configuration initialization
4516 config
= config
|| {};
4518 // Parent constructor
4519 OO
.ui
.PopupWidget
.parent
.call( this, config
);
4521 // Properties (must be set before ClippableElement constructor call)
4522 this.$body
= $( '<div>' );
4523 this.$popup
= $( '<div>' );
4525 // Mixin constructors
4526 OO
.ui
.mixin
.LabelElement
.call( this, config
);
4527 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, {
4528 $clippable
: this.$body
,
4529 $clippableContainer
: this.$popup
4531 OO
.ui
.mixin
.FloatableElement
.call( this, config
);
4534 this.$anchor
= $( '<div>' );
4535 // If undefined, will be computed lazily in updateDimensions()
4536 this.$container
= config
.$container
;
4537 this.containerPadding
= config
.containerPadding
!== undefined ? config
.containerPadding
: 10;
4538 this.autoClose
= !!config
.autoClose
;
4539 this.$autoCloseIgnore
= config
.$autoCloseIgnore
;
4540 this.transitionTimeout
= null;
4542 this.width
= config
.width
!== undefined ? config
.width
: 320;
4543 this.height
= config
.height
!== undefined ? config
.height
: null;
4544 this.setAlignment( config
.align
);
4545 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
4546 this.onDocumentKeyDownHandler
= this.onDocumentKeyDown
.bind( this );
4549 this.toggleAnchor( config
.anchor
=== undefined || config
.anchor
);
4550 this.$body
.addClass( 'oo-ui-popupWidget-body' );
4551 this.$anchor
.addClass( 'oo-ui-popupWidget-anchor' );
4553 .addClass( 'oo-ui-popupWidget-popup' )
4554 .append( this.$body
);
4556 .addClass( 'oo-ui-popupWidget' )
4557 .append( this.$popup
, this.$anchor
);
4558 // Move content, which was added to #$element by OO.ui.Widget, to the body
4559 // FIXME This is gross, we should use '$body' or something for the config
4560 if ( config
.$content
instanceof jQuery
) {
4561 this.$body
.append( config
.$content
);
4564 if ( config
.padded
) {
4565 this.$body
.addClass( 'oo-ui-popupWidget-body-padded' );
4568 if ( config
.head
) {
4569 this.closeButton
= new OO
.ui
.ButtonWidget( { framed
: false, icon
: 'close' } );
4570 this.closeButton
.connect( this, { click
: 'onCloseButtonClick' } );
4571 this.$head
= $( '<div>' )
4572 .addClass( 'oo-ui-popupWidget-head' )
4573 .append( this.$label
, this.closeButton
.$element
);
4574 this.$popup
.prepend( this.$head
);
4577 if ( config
.$footer
) {
4578 this.$footer
= $( '<div>' )
4579 .addClass( 'oo-ui-popupWidget-footer' )
4580 .append( config
.$footer
);
4581 this.$popup
.append( this.$footer
);
4584 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
4585 // that reference properties not initialized at that time of parent class construction
4586 // TODO: Find a better way to handle post-constructor setup
4587 this.visible
= false;
4588 this.$element
.addClass( 'oo-ui-element-hidden' );
4593 OO
.inheritClass( OO
.ui
.PopupWidget
, OO
.ui
.Widget
);
4594 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.LabelElement
);
4595 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.ClippableElement
);
4596 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.FloatableElement
);
4601 * Handles mouse down events.
4604 * @param {MouseEvent} e Mouse down event
4606 OO
.ui
.PopupWidget
.prototype.onMouseDown = function ( e
) {
4609 !OO
.ui
.contains( this.$element
.add( this.$autoCloseIgnore
).get(), e
.target
, true )
4611 this.toggle( false );
4616 * Bind mouse down listener.
4620 OO
.ui
.PopupWidget
.prototype.bindMouseDownListener = function () {
4621 // Capture clicks outside popup
4622 this.getElementWindow().addEventListener( 'mousedown', this.onMouseDownHandler
, true );
4626 * Handles close button click events.
4630 OO
.ui
.PopupWidget
.prototype.onCloseButtonClick = function () {
4631 if ( this.isVisible() ) {
4632 this.toggle( false );
4637 * Unbind mouse down listener.
4641 OO
.ui
.PopupWidget
.prototype.unbindMouseDownListener = function () {
4642 this.getElementWindow().removeEventListener( 'mousedown', this.onMouseDownHandler
, true );
4646 * Handles key down events.
4649 * @param {KeyboardEvent} e Key down event
4651 OO
.ui
.PopupWidget
.prototype.onDocumentKeyDown = function ( e
) {
4653 e
.which
=== OO
.ui
.Keys
.ESCAPE
&&
4656 this.toggle( false );
4658 e
.stopPropagation();
4663 * Bind key down listener.
4667 OO
.ui
.PopupWidget
.prototype.bindKeyDownListener = function () {
4668 this.getElementWindow().addEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
4672 * Unbind key down listener.
4676 OO
.ui
.PopupWidget
.prototype.unbindKeyDownListener = function () {
4677 this.getElementWindow().removeEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
4681 * Show, hide, or toggle the visibility of the anchor.
4683 * @param {boolean} [show] Show anchor, omit to toggle
4685 OO
.ui
.PopupWidget
.prototype.toggleAnchor = function ( show
) {
4686 show
= show
=== undefined ? !this.anchored
: !!show
;
4688 if ( this.anchored
!== show
) {
4690 this.$element
.addClass( 'oo-ui-popupWidget-anchored' );
4692 this.$element
.removeClass( 'oo-ui-popupWidget-anchored' );
4694 this.anchored
= show
;
4699 * Check if the anchor is visible.
4701 * @return {boolean} Anchor is visible
4703 OO
.ui
.PopupWidget
.prototype.hasAnchor = function () {
4710 OO
.ui
.PopupWidget
.prototype.toggle = function ( show
) {
4712 show
= show
=== undefined ? !this.isVisible() : !!show
;
4714 change
= show
!== this.isVisible();
4717 OO
.ui
.PopupWidget
.parent
.prototype.toggle
.call( this, show
);
4720 this.togglePositioning( show
&& !!this.$floatableContainer
);
4723 if ( this.autoClose
) {
4724 this.bindMouseDownListener();
4725 this.bindKeyDownListener();
4727 this.updateDimensions();
4728 this.toggleClipping( true );
4730 this.toggleClipping( false );
4731 if ( this.autoClose
) {
4732 this.unbindMouseDownListener();
4733 this.unbindKeyDownListener();
4742 * Set the size of the popup.
4744 * Changing the size may also change the popup's position depending on the alignment.
4746 * @param {number} width Width in pixels
4747 * @param {number} height Height in pixels
4748 * @param {boolean} [transition=false] Use a smooth transition
4751 OO
.ui
.PopupWidget
.prototype.setSize = function ( width
, height
, transition
) {
4753 this.height
= height
!== undefined ? height
: null;
4754 if ( this.isVisible() ) {
4755 this.updateDimensions( transition
);
4760 * Update the size and position.
4762 * Only use this to keep the popup properly anchored. Use #setSize to change the size, and this will
4763 * be called automatically.
4765 * @param {boolean} [transition=false] Use a smooth transition
4768 OO
.ui
.PopupWidget
.prototype.updateDimensions = function ( transition
) {
4769 var popupOffset
, originOffset
, containerLeft
, containerWidth
, containerRight
,
4770 popupLeft
, popupRight
, overlapLeft
, overlapRight
, anchorWidth
,
4774 if ( !this.$container
) {
4775 // Lazy-initialize $container if not specified in constructor
4776 this.$container
= $( this.getClosestScrollableElementContainer() );
4779 // Set height and width before measuring things, since it might cause our measurements
4780 // to change (e.g. due to scrollbars appearing or disappearing)
4783 height
: this.height
!== null ? this.height
: 'auto'
4786 // If we are in RTL, we need to flip the alignment, unless it is center
4787 if ( align
=== 'forwards' || align
=== 'backwards' ) {
4788 if ( this.$container
.css( 'direction' ) === 'rtl' ) {
4789 align
= ( { forwards
: 'force-left', backwards
: 'force-right' } )[ this.align
];
4791 align
= ( { forwards
: 'force-right', backwards
: 'force-left' } )[ this.align
];
4796 // Compute initial popupOffset based on alignment
4797 popupOffset
= this.width
* ( { 'force-left': -1, center
: -0.5, 'force-right': 0 } )[ align
];
4799 // Figure out if this will cause the popup to go beyond the edge of the container
4800 originOffset
= this.$element
.offset().left
;
4801 containerLeft
= this.$container
.offset().left
;
4802 containerWidth
= this.$container
.innerWidth();
4803 containerRight
= containerLeft
+ containerWidth
;
4804 popupLeft
= popupOffset
- this.containerPadding
;
4805 popupRight
= popupOffset
+ this.containerPadding
+ this.width
+ this.containerPadding
;
4806 overlapLeft
= ( originOffset
+ popupLeft
) - containerLeft
;
4807 overlapRight
= containerRight
- ( originOffset
+ popupRight
);
4809 // Adjust offset to make the popup not go beyond the edge, if needed
4810 if ( overlapRight
< 0 ) {
4811 popupOffset
+= overlapRight
;
4812 } else if ( overlapLeft
< 0 ) {
4813 popupOffset
-= overlapLeft
;
4816 // Adjust offset to avoid anchor being rendered too close to the edge
4817 // $anchor.width() doesn't work with the pure CSS anchor (returns 0)
4818 // TODO: Find a measurement that works for CSS anchors and image anchors
4819 anchorWidth
= this.$anchor
[ 0 ].scrollWidth
* 2;
4820 if ( popupOffset
+ this.width
< anchorWidth
) {
4821 popupOffset
= anchorWidth
- this.width
;
4822 } else if ( -popupOffset
< anchorWidth
) {
4823 popupOffset
= -anchorWidth
;
4826 // Prevent transition from being interrupted
4827 clearTimeout( this.transitionTimeout
);
4829 // Enable transition
4830 this.$element
.addClass( 'oo-ui-popupWidget-transitioning' );
4833 // Position body relative to anchor
4834 this.$popup
.css( 'margin-left', popupOffset
);
4837 // Prevent transitioning after transition is complete
4838 this.transitionTimeout
= setTimeout( function () {
4839 widget
.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
4842 // Prevent transitioning immediately
4843 this.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
4846 // Reevaluate clipping state since we've relocated and resized the popup
4853 * Set popup alignment
4855 * @param {string} [align=center] Alignment of the popup, `center`, `force-left`, `force-right`,
4856 * `backwards` or `forwards`.
4858 OO
.ui
.PopupWidget
.prototype.setAlignment = function ( align
) {
4859 // Transform values deprecated since v0.11.0
4860 if ( align
=== 'left' || align
=== 'right' ) {
4861 OO
.ui
.warnDeprecation( 'PopupWidget#setAlignment parameter value `' + align
+ '` is deprecated. Use `force-right` or `force-left` instead.' );
4862 align
= { left
: 'force-right', right
: 'force-left' }[ align
];
4865 // Validate alignment
4866 if ( [ 'force-left', 'force-right', 'backwards', 'forwards', 'center' ].indexOf( align
) > -1 ) {
4869 this.align
= 'center';
4874 * Get popup alignment
4876 * @return {string} align Alignment of the popup, `center`, `force-left`, `force-right`,
4877 * `backwards` or `forwards`.
4879 OO
.ui
.PopupWidget
.prototype.getAlignment = function () {
4884 * PopupElement is mixed into other classes to generate a {@link OO.ui.PopupWidget popup widget}.
4885 * A popup is a container for content. It is overlaid and positioned absolutely. By default, each
4886 * popup has an anchor, which is an arrow-like protrusion that points toward the popup’s origin.
4887 * See {@link OO.ui.PopupWidget PopupWidget} for an example.
4893 * @param {Object} [config] Configuration options
4894 * @cfg {Object} [popup] Configuration to pass to popup
4895 * @cfg {boolean} [popup.autoClose=true] Popup auto-closes when it loses focus
4897 OO
.ui
.mixin
.PopupElement
= function OoUiMixinPopupElement( config
) {
4898 // Configuration initialization
4899 config
= config
|| {};
4902 this.popup
= new OO
.ui
.PopupWidget( $.extend(
4903 { autoClose
: true },
4905 { $autoCloseIgnore
: this.$element
.add( config
.popup
&& config
.popup
.$autoCloseIgnore
) }
4914 * @return {OO.ui.PopupWidget} Popup widget
4916 OO
.ui
.mixin
.PopupElement
.prototype.getPopup = function () {
4921 * PopupButtonWidgets toggle the visibility of a contained {@link OO.ui.PopupWidget PopupWidget},
4922 * which is used to display additional information or options.
4925 * // Example of a popup button.
4926 * var popupButton = new OO.ui.PopupButtonWidget( {
4927 * label: 'Popup button with options',
4930 * $content: $( '<p>Additional options here.</p>' ),
4932 * align: 'force-left'
4935 * // Append the button to the DOM.
4936 * $( 'body' ).append( popupButton.$element );
4939 * @extends OO.ui.ButtonWidget
4940 * @mixins OO.ui.mixin.PopupElement
4943 * @param {Object} [config] Configuration options
4944 * @cfg {jQuery} [$overlay] Render the popup into a separate layer. This configuration is useful in cases where
4945 * the expanded popup is larger than its containing `<div>`. The specified overlay layer is usually on top of the
4946 * containing `<div>` and has a larger area. By default, the popup uses relative positioning.
4948 OO
.ui
.PopupButtonWidget
= function OoUiPopupButtonWidget( config
) {
4949 // Parent constructor
4950 OO
.ui
.PopupButtonWidget
.parent
.call( this, config
);
4952 // Mixin constructors
4953 OO
.ui
.mixin
.PopupElement
.call( this, $.extend( true, {}, config
, {
4955 $floatableContainer
: this.$element
4960 this.$overlay
= config
.$overlay
|| this.$element
;
4963 this.connect( this, { click
: 'onAction' } );
4967 .addClass( 'oo-ui-popupButtonWidget' )
4968 .attr( 'aria-haspopup', 'true' );
4970 .addClass( 'oo-ui-popupButtonWidget-popup' )
4971 .toggleClass( 'oo-ui-popupButtonWidget-framed-popup', this.isFramed() )
4972 .toggleClass( 'oo-ui-popupButtonWidget-frameless-popup', !this.isFramed() );
4973 this.$overlay
.append( this.popup
.$element
);
4978 OO
.inheritClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.ButtonWidget
);
4979 OO
.mixinClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.mixin
.PopupElement
);
4984 * Handle the button action being triggered.
4988 OO
.ui
.PopupButtonWidget
.prototype.onAction = function () {
4989 this.popup
.toggle();
4993 * Mixin for OO.ui.Widget subclasses to provide OO.ui.mixin.GroupElement.
4995 * Use together with OO.ui.mixin.ItemWidget to make disabled state inheritable.
5000 * @mixins OO.ui.mixin.GroupElement
5003 * @param {Object} [config] Configuration options
5005 OO
.ui
.mixin
.GroupWidget
= function OoUiMixinGroupWidget( config
) {
5006 // Mixin constructors
5007 OO
.ui
.mixin
.GroupElement
.call( this, config
);
5012 OO
.mixinClass( OO
.ui
.mixin
.GroupWidget
, OO
.ui
.mixin
.GroupElement
);
5017 * Set the disabled state of the widget.
5019 * This will also update the disabled state of child widgets.
5021 * @param {boolean} disabled Disable widget
5024 OO
.ui
.mixin
.GroupWidget
.prototype.setDisabled = function ( disabled
) {
5028 // Note: Calling #setDisabled this way assumes this is mixed into an OO.ui.Widget
5029 OO
.ui
.Widget
.prototype.setDisabled
.call( this, disabled
);
5031 // During construction, #setDisabled is called before the OO.ui.mixin.GroupElement constructor
5033 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5034 this.items
[ i
].updateDisabled();
5042 * Mixin for widgets used as items in widgets that mix in OO.ui.mixin.GroupWidget.
5044 * Item widgets have a reference to a OO.ui.mixin.GroupWidget while they are attached to the group. This
5045 * allows bidirectional communication.
5047 * Use together with OO.ui.mixin.GroupWidget to make disabled state inheritable.
5055 OO
.ui
.mixin
.ItemWidget
= function OoUiMixinItemWidget() {
5062 * Check if widget is disabled.
5064 * Checks parent if present, making disabled state inheritable.
5066 * @return {boolean} Widget is disabled
5068 OO
.ui
.mixin
.ItemWidget
.prototype.isDisabled = function () {
5069 return this.disabled
||
5070 ( this.elementGroup
instanceof OO
.ui
.Widget
&& this.elementGroup
.isDisabled() );
5074 * Set group element is in.
5076 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
5079 OO
.ui
.mixin
.ItemWidget
.prototype.setElementGroup = function ( group
) {
5081 // Note: Calling #setElementGroup this way assumes this is mixed into an OO.ui.Element
5082 OO
.ui
.Element
.prototype.setElementGroup
.call( this, group
);
5084 // Initialize item disabled states
5085 this.updateDisabled();
5091 * OptionWidgets are special elements that can be selected and configured with data. The
5092 * data is often unique for each option, but it does not have to be. OptionWidgets are used
5093 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
5094 * and examples, please see the [OOjs UI documentation on MediaWiki][1].
5096 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5099 * @extends OO.ui.Widget
5100 * @mixins OO.ui.mixin.ItemWidget
5101 * @mixins OO.ui.mixin.LabelElement
5102 * @mixins OO.ui.mixin.FlaggedElement
5103 * @mixins OO.ui.mixin.AccessKeyedElement
5106 * @param {Object} [config] Configuration options
5108 OO
.ui
.OptionWidget
= function OoUiOptionWidget( config
) {
5109 // Configuration initialization
5110 config
= config
|| {};
5112 // Parent constructor
5113 OO
.ui
.OptionWidget
.parent
.call( this, config
);
5115 // Mixin constructors
5116 OO
.ui
.mixin
.ItemWidget
.call( this );
5117 OO
.ui
.mixin
.LabelElement
.call( this, config
);
5118 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
5119 OO
.ui
.mixin
.AccessKeyedElement
.call( this, config
);
5122 this.selected
= false;
5123 this.highlighted
= false;
5124 this.pressed
= false;
5128 .data( 'oo-ui-optionWidget', this )
5129 // Allow programmatic focussing (and by accesskey), but not tabbing
5130 .attr( 'tabindex', '-1' )
5131 .attr( 'role', 'option' )
5132 .attr( 'aria-selected', 'false' )
5133 .addClass( 'oo-ui-optionWidget' )
5134 .append( this.$label
);
5139 OO
.inheritClass( OO
.ui
.OptionWidget
, OO
.ui
.Widget
);
5140 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.ItemWidget
);
5141 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.LabelElement
);
5142 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.FlaggedElement
);
5143 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
5145 /* Static Properties */
5147 OO
.ui
.OptionWidget
.static.selectable
= true;
5149 OO
.ui
.OptionWidget
.static.highlightable
= true;
5151 OO
.ui
.OptionWidget
.static.pressable
= true;
5153 OO
.ui
.OptionWidget
.static.scrollIntoViewOnSelect
= false;
5158 * Check if the option can be selected.
5160 * @return {boolean} Item is selectable
5162 OO
.ui
.OptionWidget
.prototype.isSelectable = function () {
5163 return this.constructor.static.selectable
&& !this.isDisabled() && this.isVisible();
5167 * Check if the option can be highlighted. A highlight indicates that the option
5168 * may be selected when a user presses enter or clicks. Disabled items cannot
5171 * @return {boolean} Item is highlightable
5173 OO
.ui
.OptionWidget
.prototype.isHighlightable = function () {
5174 return this.constructor.static.highlightable
&& !this.isDisabled() && this.isVisible();
5178 * Check if the option can be pressed. The pressed state occurs when a user mouses
5179 * down on an item, but has not yet let go of the mouse.
5181 * @return {boolean} Item is pressable
5183 OO
.ui
.OptionWidget
.prototype.isPressable = function () {
5184 return this.constructor.static.pressable
&& !this.isDisabled() && this.isVisible();
5188 * Check if the option is selected.
5190 * @return {boolean} Item is selected
5192 OO
.ui
.OptionWidget
.prototype.isSelected = function () {
5193 return this.selected
;
5197 * Check if the option is highlighted. A highlight indicates that the
5198 * item may be selected when a user presses enter or clicks.
5200 * @return {boolean} Item is highlighted
5202 OO
.ui
.OptionWidget
.prototype.isHighlighted = function () {
5203 return this.highlighted
;
5207 * Check if the option is pressed. The pressed state occurs when a user mouses
5208 * down on an item, but has not yet let go of the mouse. The item may appear
5209 * selected, but it will not be selected until the user releases the mouse.
5211 * @return {boolean} Item is pressed
5213 OO
.ui
.OptionWidget
.prototype.isPressed = function () {
5214 return this.pressed
;
5218 * Set the option’s selected state. In general, all modifications to the selection
5219 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
5220 * method instead of this method.
5222 * @param {boolean} [state=false] Select option
5225 OO
.ui
.OptionWidget
.prototype.setSelected = function ( state
) {
5226 if ( this.constructor.static.selectable
) {
5227 this.selected
= !!state
;
5229 .toggleClass( 'oo-ui-optionWidget-selected', state
)
5230 .attr( 'aria-selected', state
.toString() );
5231 if ( state
&& this.constructor.static.scrollIntoViewOnSelect
) {
5232 this.scrollElementIntoView();
5234 this.updateThemeClasses();
5240 * Set the option’s highlighted state. In general, all programmatic
5241 * modifications to the highlight should be handled by the
5242 * SelectWidget’s {@link OO.ui.SelectWidget#highlightItem highlightItem( [item] )}
5243 * method instead of this method.
5245 * @param {boolean} [state=false] Highlight option
5248 OO
.ui
.OptionWidget
.prototype.setHighlighted = function ( state
) {
5249 if ( this.constructor.static.highlightable
) {
5250 this.highlighted
= !!state
;
5251 this.$element
.toggleClass( 'oo-ui-optionWidget-highlighted', state
);
5252 this.updateThemeClasses();
5258 * Set the option’s pressed state. In general, all
5259 * programmatic modifications to the pressed state should be handled by the
5260 * SelectWidget’s {@link OO.ui.SelectWidget#pressItem pressItem( [item] )}
5261 * method instead of this method.
5263 * @param {boolean} [state=false] Press option
5266 OO
.ui
.OptionWidget
.prototype.setPressed = function ( state
) {
5267 if ( this.constructor.static.pressable
) {
5268 this.pressed
= !!state
;
5269 this.$element
.toggleClass( 'oo-ui-optionWidget-pressed', state
);
5270 this.updateThemeClasses();
5276 * Get text to match search strings against.
5278 * The default implementation returns the label text, but subclasses
5279 * can override this to provide more complex behavior.
5281 * @return {string|boolean} String to match search string against
5283 OO
.ui
.OptionWidget
.prototype.getMatchText = function () {
5284 var label
= this.getLabel();
5285 return typeof label
=== 'string' ? label
: this.$label
.text();
5289 * A SelectWidget is of a generic selection of options. The OOjs UI library contains several types of
5290 * select widgets, including {@link OO.ui.ButtonSelectWidget button selects},
5291 * {@link OO.ui.RadioSelectWidget radio selects}, and {@link OO.ui.MenuSelectWidget
5294 * This class should be used together with OO.ui.OptionWidget or OO.ui.DecoratedOptionWidget. For more
5295 * information, please see the [OOjs UI documentation on MediaWiki][1].
5298 * // Example of a select widget with three options
5299 * var select = new OO.ui.SelectWidget( {
5301 * new OO.ui.OptionWidget( {
5303 * label: 'Option One',
5305 * new OO.ui.OptionWidget( {
5307 * label: 'Option Two',
5309 * new OO.ui.OptionWidget( {
5311 * label: 'Option Three',
5315 * $( 'body' ).append( select.$element );
5317 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5321 * @extends OO.ui.Widget
5322 * @mixins OO.ui.mixin.GroupWidget
5325 * @param {Object} [config] Configuration options
5326 * @cfg {OO.ui.OptionWidget[]} [items] An array of options to add to the select.
5327 * Options are created with {@link OO.ui.OptionWidget OptionWidget} classes. See
5328 * the [OOjs UI documentation on MediaWiki] [2] for examples.
5329 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5331 OO
.ui
.SelectWidget
= function OoUiSelectWidget( config
) {
5332 // Configuration initialization
5333 config
= config
|| {};
5335 // Parent constructor
5336 OO
.ui
.SelectWidget
.parent
.call( this, config
);
5338 // Mixin constructors
5339 OO
.ui
.mixin
.GroupWidget
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
5342 this.pressed
= false;
5343 this.selecting
= null;
5344 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
5345 this.onMouseMoveHandler
= this.onMouseMove
.bind( this );
5346 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
5347 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
5348 this.keyPressBuffer
= '';
5349 this.keyPressBufferTimer
= null;
5350 this.blockMouseOverEvents
= 0;
5353 this.connect( this, {
5357 focusin
: this.onFocus
.bind( this ),
5358 mousedown
: this.onMouseDown
.bind( this ),
5359 mouseover
: this.onMouseOver
.bind( this ),
5360 mouseleave
: this.onMouseLeave
.bind( this )
5365 .addClass( 'oo-ui-selectWidget oo-ui-selectWidget-depressed' )
5366 .attr( 'role', 'listbox' );
5367 if ( Array
.isArray( config
.items
) ) {
5368 this.addItems( config
.items
);
5374 OO
.inheritClass( OO
.ui
.SelectWidget
, OO
.ui
.Widget
);
5375 OO
.mixinClass( OO
.ui
.SelectWidget
, OO
.ui
.mixin
.GroupWidget
);
5382 * A `highlight` event is emitted when the highlight is changed with the #highlightItem method.
5384 * @param {OO.ui.OptionWidget|null} item Highlighted item
5390 * A `press` event is emitted when the #pressItem method is used to programmatically modify the
5391 * pressed state of an option.
5393 * @param {OO.ui.OptionWidget|null} item Pressed item
5399 * A `select` event is emitted when the selection is modified programmatically with the #selectItem method.
5401 * @param {OO.ui.OptionWidget|null} item Selected item
5406 * A `choose` event is emitted when an item is chosen with the #chooseItem method.
5407 * @param {OO.ui.OptionWidget} item Chosen item
5413 * An `add` event is emitted when options are added to the select with the #addItems method.
5415 * @param {OO.ui.OptionWidget[]} items Added items
5416 * @param {number} index Index of insertion point
5422 * A `remove` event is emitted when options are removed from the select with the #clearItems
5423 * or #removeItems methods.
5425 * @param {OO.ui.OptionWidget[]} items Removed items
5431 * Handle focus events
5434 * @param {jQuery.Event} event
5436 OO
.ui
.SelectWidget
.prototype.onFocus = function ( event
) {
5438 if ( event
.target
=== this.$element
[ 0 ] ) {
5439 // This widget was focussed, e.g. by the user tabbing to it.
5440 // The styles for focus state depend on one of the items being selected.
5441 if ( !this.getSelectedItem() ) {
5442 item
= this.getFirstSelectableItem();
5445 // One of the options got focussed (and the event bubbled up here).
5446 // They can't be tabbed to, but they can be activated using accesskeys.
5447 item
= this.getTargetItem( event
);
5451 if ( item
.constructor.static.highlightable
) {
5452 this.highlightItem( item
);
5454 this.selectItem( item
);
5458 if ( event
.target
!== this.$element
[ 0 ] ) {
5459 this.$element
.focus();
5464 * Handle mouse down events.
5467 * @param {jQuery.Event} e Mouse down event
5469 OO
.ui
.SelectWidget
.prototype.onMouseDown = function ( e
) {
5472 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
5473 this.togglePressed( true );
5474 item
= this.getTargetItem( e
);
5475 if ( item
&& item
.isSelectable() ) {
5476 this.pressItem( item
);
5477 this.selecting
= item
;
5478 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
5479 this.getElementDocument().addEventListener( 'mousemove', this.onMouseMoveHandler
, true );
5486 * Handle mouse up events.
5489 * @param {MouseEvent} e Mouse up event
5491 OO
.ui
.SelectWidget
.prototype.onMouseUp = function ( e
) {
5494 this.togglePressed( false );
5495 if ( !this.selecting
) {
5496 item
= this.getTargetItem( e
);
5497 if ( item
&& item
.isSelectable() ) {
5498 this.selecting
= item
;
5501 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
&& this.selecting
) {
5502 this.pressItem( null );
5503 this.chooseItem( this.selecting
);
5504 this.selecting
= null;
5507 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
5508 this.getElementDocument().removeEventListener( 'mousemove', this.onMouseMoveHandler
, true );
5514 * Handle mouse move events.
5517 * @param {MouseEvent} e Mouse move event
5519 OO
.ui
.SelectWidget
.prototype.onMouseMove = function ( e
) {
5522 if ( !this.isDisabled() && this.pressed
) {
5523 item
= this.getTargetItem( e
);
5524 if ( item
&& item
!== this.selecting
&& item
.isSelectable() ) {
5525 this.pressItem( item
);
5526 this.selecting
= item
;
5532 * Handle mouse over events.
5535 * @param {jQuery.Event} e Mouse over event
5537 OO
.ui
.SelectWidget
.prototype.onMouseOver = function ( e
) {
5539 if ( this.blockMouseOverEvents
) {
5542 if ( !this.isDisabled() ) {
5543 item
= this.getTargetItem( e
);
5544 this.highlightItem( item
&& item
.isHighlightable() ? item
: null );
5550 * Handle mouse leave events.
5553 * @param {jQuery.Event} e Mouse over event
5555 OO
.ui
.SelectWidget
.prototype.onMouseLeave = function () {
5556 if ( !this.isDisabled() ) {
5557 this.highlightItem( null );
5563 * Handle key down events.
5566 * @param {KeyboardEvent} e Key down event
5568 OO
.ui
.SelectWidget
.prototype.onKeyDown = function ( e
) {
5571 currentItem
= this.getHighlightedItem() || this.getSelectedItem();
5573 if ( !this.isDisabled() && this.isVisible() ) {
5574 switch ( e
.keyCode
) {
5575 case OO
.ui
.Keys
.ENTER
:
5576 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
5577 // Was only highlighted, now let's select it. No-op if already selected.
5578 this.chooseItem( currentItem
);
5583 case OO
.ui
.Keys
.LEFT
:
5584 this.clearKeyPressBuffer();
5585 nextItem
= this.getRelativeSelectableItem( currentItem
, -1 );
5588 case OO
.ui
.Keys
.DOWN
:
5589 case OO
.ui
.Keys
.RIGHT
:
5590 this.clearKeyPressBuffer();
5591 nextItem
= this.getRelativeSelectableItem( currentItem
, 1 );
5594 case OO
.ui
.Keys
.ESCAPE
:
5595 case OO
.ui
.Keys
.TAB
:
5596 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
5597 currentItem
.setHighlighted( false );
5599 this.unbindKeyDownListener();
5600 this.unbindKeyPressListener();
5601 // Don't prevent tabbing away / defocusing
5607 if ( nextItem
.constructor.static.highlightable
) {
5608 this.highlightItem( nextItem
);
5610 this.chooseItem( nextItem
);
5612 this.scrollItemIntoView( nextItem
);
5617 e
.stopPropagation();
5623 * Bind key down listener.
5627 OO
.ui
.SelectWidget
.prototype.bindKeyDownListener = function () {
5628 this.getElementWindow().addEventListener( 'keydown', this.onKeyDownHandler
, true );
5632 * Unbind key down listener.
5636 OO
.ui
.SelectWidget
.prototype.unbindKeyDownListener = function () {
5637 this.getElementWindow().removeEventListener( 'keydown', this.onKeyDownHandler
, true );
5641 * Scroll item into view, preventing spurious mouse highlight actions from happening.
5643 * @param {OO.ui.OptionWidget} item Item to scroll into view
5645 OO
.ui
.SelectWidget
.prototype.scrollItemIntoView = function ( item
) {
5647 // Chromium's Blink engine will generate spurious 'mouseover' events during programmatic scrolling
5648 // and around 100-150 ms after it is finished.
5649 this.blockMouseOverEvents
++;
5650 item
.scrollElementIntoView().done( function () {
5651 setTimeout( function () {
5652 widget
.blockMouseOverEvents
--;
5658 * Clear the key-press buffer
5662 OO
.ui
.SelectWidget
.prototype.clearKeyPressBuffer = function () {
5663 if ( this.keyPressBufferTimer
) {
5664 clearTimeout( this.keyPressBufferTimer
);
5665 this.keyPressBufferTimer
= null;
5667 this.keyPressBuffer
= '';
5671 * Handle key press events.
5674 * @param {KeyboardEvent} e Key press event
5676 OO
.ui
.SelectWidget
.prototype.onKeyPress = function ( e
) {
5677 var c
, filter
, item
;
5679 if ( !e
.charCode
) {
5680 if ( e
.keyCode
=== OO
.ui
.Keys
.BACKSPACE
&& this.keyPressBuffer
!== '' ) {
5681 this.keyPressBuffer
= this.keyPressBuffer
.substr( 0, this.keyPressBuffer
.length
- 1 );
5686 if ( String
.fromCodePoint
) {
5687 c
= String
.fromCodePoint( e
.charCode
);
5689 c
= String
.fromCharCode( e
.charCode
);
5692 if ( this.keyPressBufferTimer
) {
5693 clearTimeout( this.keyPressBufferTimer
);
5695 this.keyPressBufferTimer
= setTimeout( this.clearKeyPressBuffer
.bind( this ), 1500 );
5697 item
= this.getHighlightedItem() || this.getSelectedItem();
5699 if ( this.keyPressBuffer
=== c
) {
5700 // Common (if weird) special case: typing "xxxx" will cycle through all
5701 // the items beginning with "x".
5703 item
= this.getRelativeSelectableItem( item
, 1 );
5706 this.keyPressBuffer
+= c
;
5709 filter
= this.getItemMatcher( this.keyPressBuffer
, false );
5710 if ( !item
|| !filter( item
) ) {
5711 item
= this.getRelativeSelectableItem( item
, 1, filter
);
5714 if ( this.isVisible() && item
.constructor.static.highlightable
) {
5715 this.highlightItem( item
);
5717 this.chooseItem( item
);
5719 this.scrollItemIntoView( item
);
5723 e
.stopPropagation();
5727 * Get a matcher for the specific string
5730 * @param {string} s String to match against items
5731 * @param {boolean} [exact=false] Only accept exact matches
5732 * @return {Function} function ( OO.ui.OptionWidget ) => boolean
5734 OO
.ui
.SelectWidget
.prototype.getItemMatcher = function ( s
, exact
) {
5737 if ( s
.normalize
) {
5740 s
= exact
? s
.trim() : s
.replace( /^\s+/, '' );
5741 re
= '^\\s*' + s
.replace( /([\\{}()|.?*+\-\^$\[\]])/g, '\\$1' ).replace( /\s+/g, '\\s+' );
5745 re
= new RegExp( re
, 'i' );
5746 return function ( item
) {
5747 var matchText
= item
.getMatchText();
5748 if ( matchText
.normalize
) {
5749 matchText
= matchText
.normalize();
5751 return re
.test( matchText
);
5756 * Bind key press listener.
5760 OO
.ui
.SelectWidget
.prototype.bindKeyPressListener = function () {
5761 this.getElementWindow().addEventListener( 'keypress', this.onKeyPressHandler
, true );
5765 * Unbind key down listener.
5767 * If you override this, be sure to call this.clearKeyPressBuffer() from your
5772 OO
.ui
.SelectWidget
.prototype.unbindKeyPressListener = function () {
5773 this.getElementWindow().removeEventListener( 'keypress', this.onKeyPressHandler
, true );
5774 this.clearKeyPressBuffer();
5778 * Visibility change handler
5781 * @param {boolean} visible
5783 OO
.ui
.SelectWidget
.prototype.onToggle = function ( visible
) {
5785 this.clearKeyPressBuffer();
5790 * Get the closest item to a jQuery.Event.
5793 * @param {jQuery.Event} e
5794 * @return {OO.ui.OptionWidget|null} Outline item widget, `null` if none was found
5796 OO
.ui
.SelectWidget
.prototype.getTargetItem = function ( e
) {
5797 return $( e
.target
).closest( '.oo-ui-optionWidget' ).data( 'oo-ui-optionWidget' ) || null;
5801 * Get selected item.
5803 * @return {OO.ui.OptionWidget|null} Selected item, `null` if no item is selected
5805 OO
.ui
.SelectWidget
.prototype.getSelectedItem = function () {
5808 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5809 if ( this.items
[ i
].isSelected() ) {
5810 return this.items
[ i
];
5817 * Get highlighted item.
5819 * @return {OO.ui.OptionWidget|null} Highlighted item, `null` if no item is highlighted
5821 OO
.ui
.SelectWidget
.prototype.getHighlightedItem = function () {
5824 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5825 if ( this.items
[ i
].isHighlighted() ) {
5826 return this.items
[ i
];
5833 * Toggle pressed state.
5835 * Press is a state that occurs when a user mouses down on an item, but
5836 * has not yet let go of the mouse. The item may appear selected, but it will not be selected
5837 * until the user releases the mouse.
5839 * @param {boolean} pressed An option is being pressed
5841 OO
.ui
.SelectWidget
.prototype.togglePressed = function ( pressed
) {
5842 if ( pressed
=== undefined ) {
5843 pressed
= !this.pressed
;
5845 if ( pressed
!== this.pressed
) {
5847 .toggleClass( 'oo-ui-selectWidget-pressed', pressed
)
5848 .toggleClass( 'oo-ui-selectWidget-depressed', !pressed
);
5849 this.pressed
= pressed
;
5854 * Highlight an option. If the `item` param is omitted, no options will be highlighted
5855 * and any existing highlight will be removed. The highlight is mutually exclusive.
5857 * @param {OO.ui.OptionWidget} [item] Item to highlight, omit for no highlight
5861 OO
.ui
.SelectWidget
.prototype.highlightItem = function ( item
) {
5862 var i
, len
, highlighted
,
5865 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5866 highlighted
= this.items
[ i
] === item
;
5867 if ( this.items
[ i
].isHighlighted() !== highlighted
) {
5868 this.items
[ i
].setHighlighted( highlighted
);
5873 this.emit( 'highlight', item
);
5880 * Fetch an item by its label.
5882 * @param {string} label Label of the item to select.
5883 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
5884 * @return {OO.ui.Element|null} Item with equivalent label, `null` if none exists
5886 OO
.ui
.SelectWidget
.prototype.getItemFromLabel = function ( label
, prefix
) {
5888 len
= this.items
.length
,
5889 filter
= this.getItemMatcher( label
, true );
5891 for ( i
= 0; i
< len
; i
++ ) {
5892 item
= this.items
[ i
];
5893 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
5900 filter
= this.getItemMatcher( label
, false );
5901 for ( i
= 0; i
< len
; i
++ ) {
5902 item
= this.items
[ i
];
5903 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
5919 * Programmatically select an option by its label. If the item does not exist,
5920 * all options will be deselected.
5922 * @param {string} [label] Label of the item to select.
5923 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
5927 OO
.ui
.SelectWidget
.prototype.selectItemByLabel = function ( label
, prefix
) {
5928 var itemFromLabel
= this.getItemFromLabel( label
, !!prefix
);
5929 if ( label
=== undefined || !itemFromLabel
) {
5930 return this.selectItem();
5932 return this.selectItem( itemFromLabel
);
5936 * Programmatically select an option by its data. If the `data` parameter is omitted,
5937 * or if the item does not exist, all options will be deselected.
5939 * @param {Object|string} [data] Value of the item to select, omit to deselect all
5943 OO
.ui
.SelectWidget
.prototype.selectItemByData = function ( data
) {
5944 var itemFromData
= this.getItemFromData( data
);
5945 if ( data
=== undefined || !itemFromData
) {
5946 return this.selectItem();
5948 return this.selectItem( itemFromData
);
5952 * Programmatically select an option by its reference. If the `item` parameter is omitted,
5953 * all options will be deselected.
5955 * @param {OO.ui.OptionWidget} [item] Item to select, omit to deselect all
5959 OO
.ui
.SelectWidget
.prototype.selectItem = function ( item
) {
5960 var i
, len
, selected
,
5963 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5964 selected
= this.items
[ i
] === item
;
5965 if ( this.items
[ i
].isSelected() !== selected
) {
5966 this.items
[ i
].setSelected( selected
);
5971 this.emit( 'select', item
);
5980 * Press is a state that occurs when a user mouses down on an item, but has not
5981 * yet let go of the mouse. The item may appear selected, but it will not be selected until the user
5982 * releases the mouse.
5984 * @param {OO.ui.OptionWidget} [item] Item to press, omit to depress all
5988 OO
.ui
.SelectWidget
.prototype.pressItem = function ( item
) {
5989 var i
, len
, pressed
,
5992 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5993 pressed
= this.items
[ i
] === item
;
5994 if ( this.items
[ i
].isPressed() !== pressed
) {
5995 this.items
[ i
].setPressed( pressed
);
6000 this.emit( 'press', item
);
6009 * Note that ‘choose’ should never be modified programmatically. A user can choose
6010 * an option with the keyboard or mouse and it becomes selected. To select an item programmatically,
6011 * use the #selectItem method.
6013 * This method is identical to #selectItem, but may vary in subclasses that take additional action
6014 * when users choose an item with the keyboard or mouse.
6016 * @param {OO.ui.OptionWidget} item Item to choose
6020 OO
.ui
.SelectWidget
.prototype.chooseItem = function ( item
) {
6022 this.selectItem( item
);
6023 this.emit( 'choose', item
);
6030 * Get an option by its position relative to the specified item (or to the start of the option array,
6031 * if item is `null`). The direction in which to search through the option array is specified with a
6032 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
6033 * `null` if there are no options in the array.
6035 * @param {OO.ui.OptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
6036 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
6037 * @param {Function} [filter] Only consider items for which this function returns
6038 * true. Function takes an OO.ui.OptionWidget and returns a boolean.
6039 * @return {OO.ui.OptionWidget|null} Item at position, `null` if there are no items in the select
6041 OO
.ui
.SelectWidget
.prototype.getRelativeSelectableItem = function ( item
, direction
, filter
) {
6042 var currentIndex
, nextIndex
, i
,
6043 increase
= direction
> 0 ? 1 : -1,
6044 len
= this.items
.length
;
6046 if ( item
instanceof OO
.ui
.OptionWidget
) {
6047 currentIndex
= this.items
.indexOf( item
);
6048 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
6050 // If no item is selected and moving forward, start at the beginning.
6051 // If moving backward, start at the end.
6052 nextIndex
= direction
> 0 ? 0 : len
- 1;
6055 for ( i
= 0; i
< len
; i
++ ) {
6056 item
= this.items
[ nextIndex
];
6058 item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() &&
6059 ( !filter
|| filter( item
) )
6063 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
6069 * Get the next selectable item or `null` if there are no selectable items.
6070 * Disabled options and menu-section markers and breaks are not selectable.
6072 * @return {OO.ui.OptionWidget|null} Item, `null` if there aren't any selectable items
6074 OO
.ui
.SelectWidget
.prototype.getFirstSelectableItem = function () {
6075 return this.getRelativeSelectableItem( null, 1 );
6079 * Add an array of options to the select. Optionally, an index number can be used to
6080 * specify an insertion point.
6082 * @param {OO.ui.OptionWidget[]} items Items to add
6083 * @param {number} [index] Index to insert items after
6087 OO
.ui
.SelectWidget
.prototype.addItems = function ( items
, index
) {
6089 OO
.ui
.mixin
.GroupWidget
.prototype.addItems
.call( this, items
, index
);
6091 // Always provide an index, even if it was omitted
6092 this.emit( 'add', items
, index
=== undefined ? this.items
.length
- items
.length
- 1 : index
);
6098 * Remove the specified array of options from the select. Options will be detached
6099 * from the DOM, not removed, so they can be reused later. To remove all options from
6100 * the select, you may wish to use the #clearItems method instead.
6102 * @param {OO.ui.OptionWidget[]} items Items to remove
6106 OO
.ui
.SelectWidget
.prototype.removeItems = function ( items
) {
6109 // Deselect items being removed
6110 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
6112 if ( item
.isSelected() ) {
6113 this.selectItem( null );
6118 OO
.ui
.mixin
.GroupWidget
.prototype.removeItems
.call( this, items
);
6120 this.emit( 'remove', items
);
6126 * Clear all options from the select. Options will be detached from the DOM, not removed,
6127 * so that they can be reused later. To remove a subset of options from the select, use
6128 * the #removeItems method.
6133 OO
.ui
.SelectWidget
.prototype.clearItems = function () {
6134 var items
= this.items
.slice();
6137 OO
.ui
.mixin
.GroupWidget
.prototype.clearItems
.call( this );
6140 this.selectItem( null );
6142 this.emit( 'remove', items
);
6148 * DecoratedOptionWidgets are {@link OO.ui.OptionWidget options} that can be configured
6149 * with an {@link OO.ui.mixin.IconElement icon} and/or {@link OO.ui.mixin.IndicatorElement indicator}.
6150 * This class is used with OO.ui.SelectWidget to create a selection of mutually exclusive
6151 * options. For more information about options and selects, please see the
6152 * [OOjs UI documentation on MediaWiki][1].
6155 * // Decorated options in a select widget
6156 * var select = new OO.ui.SelectWidget( {
6158 * new OO.ui.DecoratedOptionWidget( {
6160 * label: 'Option with icon',
6163 * new OO.ui.DecoratedOptionWidget( {
6165 * label: 'Option with indicator',
6170 * $( 'body' ).append( select.$element );
6172 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6175 * @extends OO.ui.OptionWidget
6176 * @mixins OO.ui.mixin.IconElement
6177 * @mixins OO.ui.mixin.IndicatorElement
6180 * @param {Object} [config] Configuration options
6182 OO
.ui
.DecoratedOptionWidget
= function OoUiDecoratedOptionWidget( config
) {
6183 // Parent constructor
6184 OO
.ui
.DecoratedOptionWidget
.parent
.call( this, config
);
6186 // Mixin constructors
6187 OO
.ui
.mixin
.IconElement
.call( this, config
);
6188 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
6192 .addClass( 'oo-ui-decoratedOptionWidget' )
6193 .prepend( this.$icon
)
6194 .append( this.$indicator
);
6199 OO
.inheritClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.OptionWidget
);
6200 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IconElement
);
6201 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IndicatorElement
);
6204 * MenuOptionWidget is an option widget that looks like a menu item. The class is used with
6205 * OO.ui.MenuSelectWidget to create a menu of mutually exclusive options. Please see
6206 * the [OOjs UI documentation on MediaWiki] [1] for more information.
6208 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
6211 * @extends OO.ui.DecoratedOptionWidget
6214 * @param {Object} [config] Configuration options
6216 OO
.ui
.MenuOptionWidget
= function OoUiMenuOptionWidget( config
) {
6217 // Configuration initialization
6218 config
= $.extend( { icon
: 'check' }, config
);
6220 // Parent constructor
6221 OO
.ui
.MenuOptionWidget
.parent
.call( this, config
);
6225 .attr( 'role', 'menuitem' )
6226 .addClass( 'oo-ui-menuOptionWidget' );
6231 OO
.inheritClass( OO
.ui
.MenuOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
6233 /* Static Properties */
6235 OO
.ui
.MenuOptionWidget
.static.scrollIntoViewOnSelect
= true;
6238 * MenuSectionOptionWidgets are used inside {@link OO.ui.MenuSelectWidget menu select widgets} to group one or more related
6239 * {@link OO.ui.MenuOptionWidget menu options}. MenuSectionOptionWidgets cannot be highlighted or selected.
6242 * var myDropdown = new OO.ui.DropdownWidget( {
6245 * new OO.ui.MenuSectionOptionWidget( {
6248 * new OO.ui.MenuOptionWidget( {
6250 * label: 'Welsh Corgi'
6252 * new OO.ui.MenuOptionWidget( {
6254 * label: 'Standard Poodle'
6256 * new OO.ui.MenuSectionOptionWidget( {
6259 * new OO.ui.MenuOptionWidget( {
6266 * $( 'body' ).append( myDropdown.$element );
6269 * @extends OO.ui.DecoratedOptionWidget
6272 * @param {Object} [config] Configuration options
6274 OO
.ui
.MenuSectionOptionWidget
= function OoUiMenuSectionOptionWidget( config
) {
6275 // Parent constructor
6276 OO
.ui
.MenuSectionOptionWidget
.parent
.call( this, config
);
6279 this.$element
.addClass( 'oo-ui-menuSectionOptionWidget' );
6284 OO
.inheritClass( OO
.ui
.MenuSectionOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
6286 /* Static Properties */
6288 OO
.ui
.MenuSectionOptionWidget
.static.selectable
= false;
6290 OO
.ui
.MenuSectionOptionWidget
.static.highlightable
= false;
6293 * MenuSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains options and
6294 * is used together with OO.ui.MenuOptionWidget. It is designed be used as part of another widget.
6295 * See {@link OO.ui.DropdownWidget DropdownWidget}, {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget},
6296 * and {@link OO.ui.mixin.LookupElement LookupElement} for examples of widgets that contain menus.
6297 * MenuSelectWidgets themselves are not instantiated directly, rather subclassed
6298 * and customized to be opened, closed, and displayed as needed.
6300 * By default, menus are clipped to the visible viewport and are not visible when a user presses the
6301 * mouse outside the menu.
6303 * Menus also have support for keyboard interaction:
6305 * - Enter/Return key: choose and select a menu option
6306 * - Up-arrow key: highlight the previous menu option
6307 * - Down-arrow key: highlight the next menu option
6308 * - Esc key: hide the menu
6310 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
6311 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6314 * @extends OO.ui.SelectWidget
6315 * @mixins OO.ui.mixin.ClippableElement
6318 * @param {Object} [config] Configuration options
6319 * @cfg {OO.ui.TextInputWidget} [input] Text input used to implement option highlighting for menu items that match
6320 * the text the user types. This config is used by {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget}
6321 * and {@link OO.ui.mixin.LookupElement LookupElement}
6322 * @cfg {jQuery} [$input] Text input used to implement option highlighting for menu items that match
6323 * the text the user types. This config is used by {@link OO.ui.CapsuleMultiselectWidget CapsuleMultiselectWidget}
6324 * @cfg {OO.ui.Widget} [widget] Widget associated with the menu's active state. If the user clicks the mouse
6325 * anywhere on the page outside of this widget, the menu is hidden. For example, if there is a button
6326 * that toggles the menu's visibility on click, the menu will be hidden then re-shown when the user clicks
6327 * that button, unless the button (or its parent widget) is passed in here.
6328 * @cfg {boolean} [autoHide=true] Hide the menu when the mouse is pressed outside the menu.
6329 * @cfg {boolean} [filterFromInput=false] Filter the displayed options from the input
6331 OO
.ui
.MenuSelectWidget
= function OoUiMenuSelectWidget( config
) {
6332 // Configuration initialization
6333 config
= config
|| {};
6335 // Parent constructor
6336 OO
.ui
.MenuSelectWidget
.parent
.call( this, config
);
6338 // Mixin constructors
6339 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, { $clippable
: this.$group
} ) );
6342 this.autoHide
= config
.autoHide
=== undefined || !!config
.autoHide
;
6343 this.filterFromInput
= !!config
.filterFromInput
;
6344 this.$input
= config
.$input
? config
.$input
: config
.input
? config
.input
.$input
: null;
6345 this.$widget
= config
.widget
? config
.widget
.$element
: null;
6346 this.onDocumentMouseDownHandler
= this.onDocumentMouseDown
.bind( this );
6347 this.onInputEditHandler
= OO
.ui
.debounce( this.updateItemVisibility
.bind( this ), 100 );
6351 .addClass( 'oo-ui-menuSelectWidget' )
6352 .attr( 'role', 'menu' );
6354 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
6355 // that reference properties not initialized at that time of parent class construction
6356 // TODO: Find a better way to handle post-constructor setup
6357 this.visible
= false;
6358 this.$element
.addClass( 'oo-ui-element-hidden' );
6363 OO
.inheritClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.SelectWidget
);
6364 OO
.mixinClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.mixin
.ClippableElement
);
6369 * Handles document mouse down events.
6372 * @param {MouseEvent} e Mouse down event
6374 OO
.ui
.MenuSelectWidget
.prototype.onDocumentMouseDown = function ( e
) {
6376 !OO
.ui
.contains( this.$element
[ 0 ], e
.target
, true ) &&
6377 ( !this.$widget
|| !OO
.ui
.contains( this.$widget
[ 0 ], e
.target
, true ) )
6379 this.toggle( false );
6386 OO
.ui
.MenuSelectWidget
.prototype.onKeyDown = function ( e
) {
6387 var currentItem
= this.getHighlightedItem() || this.getSelectedItem();
6389 if ( !this.isDisabled() && this.isVisible() ) {
6390 switch ( e
.keyCode
) {
6391 case OO
.ui
.Keys
.LEFT
:
6392 case OO
.ui
.Keys
.RIGHT
:
6393 // Do nothing if a text field is associated, arrow keys will be handled natively
6394 if ( !this.$input
) {
6395 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
6398 case OO
.ui
.Keys
.ESCAPE
:
6399 case OO
.ui
.Keys
.TAB
:
6400 if ( currentItem
) {
6401 currentItem
.setHighlighted( false );
6403 this.toggle( false );
6404 // Don't prevent tabbing away, prevent defocusing
6405 if ( e
.keyCode
=== OO
.ui
.Keys
.ESCAPE
) {
6407 e
.stopPropagation();
6411 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
6418 * Update menu item visibility after input changes.
6422 OO
.ui
.MenuSelectWidget
.prototype.updateItemVisibility = function () {
6423 var i
, item
, visible
,
6425 len
= this.items
.length
,
6426 showAll
= !this.isVisible(),
6427 filter
= showAll
? null : this.getItemMatcher( this.$input
.val() );
6429 for ( i
= 0; i
< len
; i
++ ) {
6430 item
= this.items
[ i
];
6431 if ( item
instanceof OO
.ui
.OptionWidget
) {
6432 visible
= showAll
|| filter( item
);
6433 anyVisible
= anyVisible
|| visible
;
6434 item
.toggle( visible
);
6438 this.$element
.toggleClass( 'oo-ui-menuSelectWidget-invisible', !anyVisible
);
6440 // Reevaluate clipping
6447 OO
.ui
.MenuSelectWidget
.prototype.bindKeyDownListener = function () {
6448 if ( this.$input
) {
6449 this.$input
.on( 'keydown', this.onKeyDownHandler
);
6451 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyDownListener
.call( this );
6458 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyDownListener = function () {
6459 if ( this.$input
) {
6460 this.$input
.off( 'keydown', this.onKeyDownHandler
);
6462 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyDownListener
.call( this );
6469 OO
.ui
.MenuSelectWidget
.prototype.bindKeyPressListener = function () {
6470 if ( this.$input
) {
6471 if ( this.filterFromInput
) {
6472 this.$input
.on( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
6475 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyPressListener
.call( this );
6482 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyPressListener = function () {
6483 if ( this.$input
) {
6484 if ( this.filterFromInput
) {
6485 this.$input
.off( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
6486 this.updateItemVisibility();
6489 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyPressListener
.call( this );
6496 * When a user chooses an item, the menu is closed.
6498 * Note that ‘choose’ should never be modified programmatically. A user can choose an option with the keyboard
6499 * or mouse and it becomes selected. To select an item programmatically, use the #selectItem method.
6501 * @param {OO.ui.OptionWidget} item Item to choose
6504 OO
.ui
.MenuSelectWidget
.prototype.chooseItem = function ( item
) {
6505 OO
.ui
.MenuSelectWidget
.parent
.prototype.chooseItem
.call( this, item
);
6506 this.toggle( false );
6513 OO
.ui
.MenuSelectWidget
.prototype.addItems = function ( items
, index
) {
6515 OO
.ui
.MenuSelectWidget
.parent
.prototype.addItems
.call( this, items
, index
);
6517 // Reevaluate clipping
6526 OO
.ui
.MenuSelectWidget
.prototype.removeItems = function ( items
) {
6528 OO
.ui
.MenuSelectWidget
.parent
.prototype.removeItems
.call( this, items
);
6530 // Reevaluate clipping
6539 OO
.ui
.MenuSelectWidget
.prototype.clearItems = function () {
6541 OO
.ui
.MenuSelectWidget
.parent
.prototype.clearItems
.call( this );
6543 // Reevaluate clipping
6552 OO
.ui
.MenuSelectWidget
.prototype.toggle = function ( visible
) {
6555 visible
= ( visible
=== undefined ? !this.visible
: !!visible
) && !!this.items
.length
;
6556 change
= visible
!== this.isVisible();
6559 OO
.ui
.MenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
6563 this.bindKeyDownListener();
6564 this.bindKeyPressListener();
6566 this.toggleClipping( true );
6568 if ( this.getSelectedItem() ) {
6569 this.getSelectedItem().scrollElementIntoView( { duration
: 0 } );
6573 if ( this.autoHide
) {
6574 this.getElementDocument().addEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
6577 this.unbindKeyDownListener();
6578 this.unbindKeyPressListener();
6579 this.getElementDocument().removeEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
6580 this.toggleClipping( false );
6588 * DropdownWidgets are not menus themselves, rather they contain a menu of options created with
6589 * OO.ui.MenuOptionWidget. The DropdownWidget takes care of opening and displaying the menu so that
6590 * users can interact with it.
6592 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
6593 * OO.ui.DropdownInputWidget instead.
6596 * // Example: A DropdownWidget with a menu that contains three options
6597 * var dropDown = new OO.ui.DropdownWidget( {
6598 * label: 'Dropdown menu: Select a menu option',
6601 * new OO.ui.MenuOptionWidget( {
6605 * new OO.ui.MenuOptionWidget( {
6609 * new OO.ui.MenuOptionWidget( {
6617 * $( 'body' ).append( dropDown.$element );
6619 * dropDown.getMenu().selectItemByData( 'b' );
6621 * dropDown.getMenu().getSelectedItem().getData(); // returns 'b'
6623 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
6625 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
6628 * @extends OO.ui.Widget
6629 * @mixins OO.ui.mixin.IconElement
6630 * @mixins OO.ui.mixin.IndicatorElement
6631 * @mixins OO.ui.mixin.LabelElement
6632 * @mixins OO.ui.mixin.TitledElement
6633 * @mixins OO.ui.mixin.TabIndexedElement
6636 * @param {Object} [config] Configuration options
6637 * @cfg {Object} [menu] Configuration options to pass to {@link OO.ui.FloatingMenuSelectWidget menu select widget}
6638 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
6639 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
6640 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
6642 OO
.ui
.DropdownWidget
= function OoUiDropdownWidget( config
) {
6643 // Configuration initialization
6644 config
= $.extend( { indicator
: 'down' }, config
);
6646 // Parent constructor
6647 OO
.ui
.DropdownWidget
.parent
.call( this, config
);
6649 // Properties (must be set before TabIndexedElement constructor call)
6650 this.$handle
= this.$( '<span>' );
6651 this.$overlay
= config
.$overlay
|| this.$element
;
6653 // Mixin constructors
6654 OO
.ui
.mixin
.IconElement
.call( this, config
);
6655 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
6656 OO
.ui
.mixin
.LabelElement
.call( this, config
);
6657 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
6658 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$handle
} ) );
6661 this.menu
= new OO
.ui
.FloatingMenuSelectWidget( $.extend( {
6663 $container
: this.$element
6668 click
: this.onClick
.bind( this ),
6669 keydown
: this.onKeyDown
.bind( this ),
6670 // Hack? Handle type-to-search when menu is not expanded and not handling its own events
6671 keypress
: this.menu
.onKeyPressHandler
,
6672 blur
: this.menu
.clearKeyPressBuffer
.bind( this.menu
)
6674 this.menu
.connect( this, {
6675 select
: 'onMenuSelect',
6676 toggle
: 'onMenuToggle'
6681 .addClass( 'oo-ui-dropdownWidget-handle' )
6682 .append( this.$icon
, this.$label
, this.$indicator
);
6684 .addClass( 'oo-ui-dropdownWidget' )
6685 .append( this.$handle
);
6686 this.$overlay
.append( this.menu
.$element
);
6691 OO
.inheritClass( OO
.ui
.DropdownWidget
, OO
.ui
.Widget
);
6692 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IconElement
);
6693 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IndicatorElement
);
6694 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.LabelElement
);
6695 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TitledElement
);
6696 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TabIndexedElement
);
6703 * @return {OO.ui.MenuSelectWidget} Menu of widget
6705 OO
.ui
.DropdownWidget
.prototype.getMenu = function () {
6710 * Handles menu select events.
6713 * @param {OO.ui.MenuOptionWidget} item Selected menu item
6715 OO
.ui
.DropdownWidget
.prototype.onMenuSelect = function ( item
) {
6719 this.setLabel( null );
6723 selectedLabel
= item
.getLabel();
6725 // If the label is a DOM element, clone it, because setLabel will append() it
6726 if ( selectedLabel
instanceof jQuery
) {
6727 selectedLabel
= selectedLabel
.clone();
6730 this.setLabel( selectedLabel
);
6734 * Handle menu toggle events.
6737 * @param {boolean} isVisible Menu toggle event
6739 OO
.ui
.DropdownWidget
.prototype.onMenuToggle = function ( isVisible
) {
6740 this.$element
.toggleClass( 'oo-ui-dropdownWidget-open', isVisible
);
6744 * Handle mouse click events.
6747 * @param {jQuery.Event} e Mouse click event
6749 OO
.ui
.DropdownWidget
.prototype.onClick = function ( e
) {
6750 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
6757 * Handle key down events.
6760 * @param {jQuery.Event} e Key down event
6762 OO
.ui
.DropdownWidget
.prototype.onKeyDown = function ( e
) {
6764 !this.isDisabled() &&
6766 e
.which
=== OO
.ui
.Keys
.ENTER
||
6768 !this.menu
.isVisible() &&
6770 e
.which
=== OO
.ui
.Keys
.SPACE
||
6771 e
.which
=== OO
.ui
.Keys
.UP
||
6772 e
.which
=== OO
.ui
.Keys
.DOWN
6783 * RadioOptionWidget is an option widget that looks like a radio button.
6784 * The class is used with OO.ui.RadioSelectWidget to create a selection of radio options.
6785 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
6787 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option
6790 * @extends OO.ui.OptionWidget
6793 * @param {Object} [config] Configuration options
6795 OO
.ui
.RadioOptionWidget
= function OoUiRadioOptionWidget( config
) {
6796 // Configuration initialization
6797 config
= config
|| {};
6799 // Properties (must be done before parent constructor which calls #setDisabled)
6800 this.radio
= new OO
.ui
.RadioInputWidget( { value
: config
.data
, tabIndex
: -1 } );
6802 // Parent constructor
6803 OO
.ui
.RadioOptionWidget
.parent
.call( this, config
);
6806 // Remove implicit role, we're handling it ourselves
6807 this.radio
.$input
.attr( 'role', 'presentation' );
6809 .addClass( 'oo-ui-radioOptionWidget' )
6810 .attr( 'role', 'radio' )
6811 .attr( 'aria-checked', 'false' )
6812 .removeAttr( 'aria-selected' )
6813 .prepend( this.radio
.$element
);
6818 OO
.inheritClass( OO
.ui
.RadioOptionWidget
, OO
.ui
.OptionWidget
);
6820 /* Static Properties */
6822 OO
.ui
.RadioOptionWidget
.static.highlightable
= false;
6824 OO
.ui
.RadioOptionWidget
.static.scrollIntoViewOnSelect
= true;
6826 OO
.ui
.RadioOptionWidget
.static.pressable
= false;
6828 OO
.ui
.RadioOptionWidget
.static.tagName
= 'label';
6835 OO
.ui
.RadioOptionWidget
.prototype.setSelected = function ( state
) {
6836 OO
.ui
.RadioOptionWidget
.parent
.prototype.setSelected
.call( this, state
);
6838 this.radio
.setSelected( state
);
6840 .attr( 'aria-checked', state
.toString() )
6841 .removeAttr( 'aria-selected' );
6849 OO
.ui
.RadioOptionWidget
.prototype.setDisabled = function ( disabled
) {
6850 OO
.ui
.RadioOptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
6852 this.radio
.setDisabled( this.isDisabled() );
6858 * RadioSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains radio
6859 * options and is used together with OO.ui.RadioOptionWidget. The RadioSelectWidget provides
6860 * an interface for adding, removing and selecting options.
6861 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
6863 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
6864 * OO.ui.RadioSelectInputWidget instead.
6867 * // A RadioSelectWidget with RadioOptions.
6868 * var option1 = new OO.ui.RadioOptionWidget( {
6870 * label: 'Selected radio option'
6873 * var option2 = new OO.ui.RadioOptionWidget( {
6875 * label: 'Unselected radio option'
6878 * var radioSelect=new OO.ui.RadioSelectWidget( {
6879 * items: [ option1, option2 ]
6882 * // Select 'option 1' using the RadioSelectWidget's selectItem() method.
6883 * radioSelect.selectItem( option1 );
6885 * $( 'body' ).append( radioSelect.$element );
6887 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6891 * @extends OO.ui.SelectWidget
6892 * @mixins OO.ui.mixin.TabIndexedElement
6895 * @param {Object} [config] Configuration options
6897 OO
.ui
.RadioSelectWidget
= function OoUiRadioSelectWidget( config
) {
6898 // Parent constructor
6899 OO
.ui
.RadioSelectWidget
.parent
.call( this, config
);
6901 // Mixin constructors
6902 OO
.ui
.mixin
.TabIndexedElement
.call( this, config
);
6906 focus
: this.bindKeyDownListener
.bind( this ),
6907 blur
: this.unbindKeyDownListener
.bind( this )
6912 .addClass( 'oo-ui-radioSelectWidget' )
6913 .attr( 'role', 'radiogroup' );
6918 OO
.inheritClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.SelectWidget
);
6919 OO
.mixinClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.mixin
.TabIndexedElement
);
6922 * MultioptionWidgets are special elements that can be selected and configured with data. The
6923 * data is often unique for each option, but it does not have to be. MultioptionWidgets are used
6924 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
6925 * and examples, please see the [OOjs UI documentation on MediaWiki][1].
6927 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Multioptions
6930 * @extends OO.ui.Widget
6931 * @mixins OO.ui.mixin.ItemWidget
6932 * @mixins OO.ui.mixin.LabelElement
6935 * @param {Object} [config] Configuration options
6936 * @cfg {boolean} [selected=false] Whether the option is initially selected
6938 OO
.ui
.MultioptionWidget
= function OoUiMultioptionWidget( config
) {
6939 // Configuration initialization
6940 config
= config
|| {};
6942 // Parent constructor
6943 OO
.ui
.MultioptionWidget
.parent
.call( this, config
);
6945 // Mixin constructors
6946 OO
.ui
.mixin
.ItemWidget
.call( this );
6947 OO
.ui
.mixin
.LabelElement
.call( this, config
);
6950 this.selected
= null;
6954 .addClass( 'oo-ui-multioptionWidget' )
6955 .append( this.$label
);
6956 this.setSelected( config
.selected
);
6961 OO
.inheritClass( OO
.ui
.MultioptionWidget
, OO
.ui
.Widget
);
6962 OO
.mixinClass( OO
.ui
.MultioptionWidget
, OO
.ui
.mixin
.ItemWidget
);
6963 OO
.mixinClass( OO
.ui
.MultioptionWidget
, OO
.ui
.mixin
.LabelElement
);
6970 * A change event is emitted when the selected state of the option changes.
6972 * @param {boolean} selected Whether the option is now selected
6978 * Check if the option is selected.
6980 * @return {boolean} Item is selected
6982 OO
.ui
.MultioptionWidget
.prototype.isSelected = function () {
6983 return this.selected
;
6987 * Set the option’s selected state. In general, all modifications to the selection
6988 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
6989 * method instead of this method.
6991 * @param {boolean} [state=false] Select option
6994 OO
.ui
.MultioptionWidget
.prototype.setSelected = function ( state
) {
6996 if ( this.selected
!== state
) {
6997 this.selected
= state
;
6998 this.emit( 'change', state
);
6999 this.$element
.toggleClass( 'oo-ui-multioptionWidget-selected', state
);
7005 * MultiselectWidget allows selecting multiple options from a list.
7007 * For more information about menus and options, please see the [OOjs UI documentation on MediaWiki][1].
7009 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
7013 * @extends OO.ui.Widget
7014 * @mixins OO.ui.mixin.GroupWidget
7017 * @param {Object} [config] Configuration options
7018 * @cfg {OO.ui.MultioptionWidget[]} [items] An array of options to add to the multiselect.
7020 OO
.ui
.MultiselectWidget
= function OoUiMultiselectWidget( config
) {
7021 // Parent constructor
7022 OO
.ui
.MultiselectWidget
.parent
.call( this, config
);
7024 // Configuration initialization
7025 config
= config
|| {};
7027 // Mixin constructors
7028 OO
.ui
.mixin
.GroupWidget
.call( this, config
);
7031 this.aggregate( { change
: 'select' } );
7032 // This is mostly for compatibility with CapsuleMultiselectWidget... normally, 'change' is emitted
7033 // by GroupElement only when items are added/removed
7034 this.connect( this, { select
: [ 'emit', 'change' ] } );
7037 if ( config
.items
) {
7038 this.addItems( config
.items
);
7040 this.$group
.addClass( 'oo-ui-multiselectWidget-group' );
7041 this.$element
.addClass( 'oo-ui-multiselectWidget' )
7042 .append( this.$group
);
7047 OO
.inheritClass( OO
.ui
.MultiselectWidget
, OO
.ui
.Widget
);
7048 OO
.mixinClass( OO
.ui
.MultiselectWidget
, OO
.ui
.mixin
.GroupWidget
);
7055 * A change event is emitted when the set of items changes, or an item is selected or deselected.
7061 * A select event is emitted when an item is selected or deselected.
7067 * Get options that are selected.
7069 * @return {OO.ui.MultioptionWidget[]} Selected options
7071 OO
.ui
.MultiselectWidget
.prototype.getSelectedItems = function () {
7072 return this.items
.filter( function ( item
) {
7073 return item
.isSelected();
7078 * Get the data of options that are selected.
7080 * @return {Object[]|string[]} Values of selected options
7082 OO
.ui
.MultiselectWidget
.prototype.getSelectedItemsData = function () {
7083 return this.getSelectedItems().map( function ( item
) {
7089 * Select options by reference. Options not mentioned in the `items` array will be deselected.
7091 * @param {OO.ui.MultioptionWidget[]} items Items to select
7094 OO
.ui
.MultiselectWidget
.prototype.selectItems = function ( items
) {
7095 this.items
.forEach( function ( item
) {
7096 var selected
= items
.indexOf( item
) !== -1;
7097 item
.setSelected( selected
);
7103 * Select items by their data. Options not mentioned in the `datas` array will be deselected.
7105 * @param {Object[]|string[]} datas Values of items to select
7108 OO
.ui
.MultiselectWidget
.prototype.selectItemsByData = function ( datas
) {
7111 items
= datas
.map( function ( data
) {
7112 return widget
.getItemFromData( data
);
7114 this.selectItems( items
);
7119 * CheckboxMultioptionWidget is an option widget that looks like a checkbox.
7120 * The class is used with OO.ui.CheckboxMultiselectWidget to create a selection of checkbox options.
7121 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
7123 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option
7126 * @extends OO.ui.MultioptionWidget
7129 * @param {Object} [config] Configuration options
7131 OO
.ui
.CheckboxMultioptionWidget
= function OoUiCheckboxMultioptionWidget( config
) {
7132 // Configuration initialization
7133 config
= config
|| {};
7135 // Properties (must be done before parent constructor which calls #setDisabled)
7136 this.checkbox
= new OO
.ui
.CheckboxInputWidget();
7138 // Parent constructor
7139 OO
.ui
.CheckboxMultioptionWidget
.parent
.call( this, config
);
7142 this.checkbox
.on( 'change', this.onCheckboxChange
.bind( this ) );
7143 this.$element
.on( 'keydown', this.onKeyDown
.bind( this ) );
7147 .addClass( 'oo-ui-checkboxMultioptionWidget' )
7148 .prepend( this.checkbox
.$element
);
7153 OO
.inheritClass( OO
.ui
.CheckboxMultioptionWidget
, OO
.ui
.MultioptionWidget
);
7155 /* Static Properties */
7157 OO
.ui
.CheckboxMultioptionWidget
.static.tagName
= 'label';
7162 * Handle checkbox selected state change.
7166 OO
.ui
.CheckboxMultioptionWidget
.prototype.onCheckboxChange = function () {
7167 this.setSelected( this.checkbox
.isSelected() );
7173 OO
.ui
.CheckboxMultioptionWidget
.prototype.setSelected = function ( state
) {
7174 OO
.ui
.CheckboxMultioptionWidget
.parent
.prototype.setSelected
.call( this, state
);
7175 this.checkbox
.setSelected( state
);
7182 OO
.ui
.CheckboxMultioptionWidget
.prototype.setDisabled = function ( disabled
) {
7183 OO
.ui
.CheckboxMultioptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
7184 this.checkbox
.setDisabled( this.isDisabled() );
7191 OO
.ui
.CheckboxMultioptionWidget
.prototype.focus = function () {
7192 this.checkbox
.focus();
7196 * Handle key down events.
7199 * @param {jQuery.Event} e
7201 OO
.ui
.CheckboxMultioptionWidget
.prototype.onKeyDown = function ( e
) {
7203 element
= this.getElementGroup(),
7206 if ( e
.keyCode
=== OO
.ui
.Keys
.LEFT
|| e
.keyCode
=== OO
.ui
.Keys
.UP
) {
7207 nextItem
= element
.getRelativeFocusableItem( this, -1 );
7208 } else if ( e
.keyCode
=== OO
.ui
.Keys
.RIGHT
|| e
.keyCode
=== OO
.ui
.Keys
.DOWN
) {
7209 nextItem
= element
.getRelativeFocusableItem( this, 1 );
7219 * CheckboxMultiselectWidget is a {@link OO.ui.MultiselectWidget multiselect widget} that contains
7220 * checkboxes and is used together with OO.ui.CheckboxMultioptionWidget. The
7221 * CheckboxMultiselectWidget provides an interface for adding, removing and selecting options.
7222 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
7224 * If you want to use this within an HTML form, such as a OO.ui.FormLayout, use
7225 * OO.ui.CheckboxMultiselectInputWidget instead.
7228 * // A CheckboxMultiselectWidget with CheckboxMultioptions.
7229 * var option1 = new OO.ui.CheckboxMultioptionWidget( {
7232 * label: 'Selected checkbox'
7235 * var option2 = new OO.ui.CheckboxMultioptionWidget( {
7237 * label: 'Unselected checkbox'
7240 * var multiselect=new OO.ui.CheckboxMultiselectWidget( {
7241 * items: [ option1, option2 ]
7244 * $( 'body' ).append( multiselect.$element );
7246 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
7249 * @extends OO.ui.MultiselectWidget
7252 * @param {Object} [config] Configuration options
7254 OO
.ui
.CheckboxMultiselectWidget
= function OoUiCheckboxMultiselectWidget( config
) {
7255 // Parent constructor
7256 OO
.ui
.CheckboxMultiselectWidget
.parent
.call( this, config
);
7259 this.$lastClicked
= null;
7262 this.$group
.on( 'click', this.onClick
.bind( this ) );
7266 .addClass( 'oo-ui-checkboxMultiselectWidget' );
7271 OO
.inheritClass( OO
.ui
.CheckboxMultiselectWidget
, OO
.ui
.MultiselectWidget
);
7276 * Get an option by its position relative to the specified item (or to the start of the option array,
7277 * if item is `null`). The direction in which to search through the option array is specified with a
7278 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
7279 * `null` if there are no options in the array.
7281 * @param {OO.ui.CheckboxMultioptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
7282 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
7283 * @return {OO.ui.CheckboxMultioptionWidget|null} Item at position, `null` if there are no items in the select
7285 OO
.ui
.CheckboxMultiselectWidget
.prototype.getRelativeFocusableItem = function ( item
, direction
) {
7286 var currentIndex
, nextIndex
, i
,
7287 increase
= direction
> 0 ? 1 : -1,
7288 len
= this.items
.length
;
7291 currentIndex
= this.items
.indexOf( item
);
7292 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
7294 // If no item is selected and moving forward, start at the beginning.
7295 // If moving backward, start at the end.
7296 nextIndex
= direction
> 0 ? 0 : len
- 1;
7299 for ( i
= 0; i
< len
; i
++ ) {
7300 item
= this.items
[ nextIndex
];
7301 if ( item
&& !item
.isDisabled() ) {
7304 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
7310 * Handle click events on checkboxes.
7312 * @param {jQuery.Event} e
7314 OO
.ui
.CheckboxMultiselectWidget
.prototype.onClick = function ( e
) {
7315 var $options
, lastClickedIndex
, nowClickedIndex
, i
, direction
, wasSelected
, items
,
7316 $lastClicked
= this.$lastClicked
,
7317 $nowClicked
= $( e
.target
).closest( '.oo-ui-checkboxMultioptionWidget' )
7318 .not( '.oo-ui-widget-disabled' );
7320 // Allow selecting multiple options at once by Shift-clicking them
7321 if ( $lastClicked
&& $nowClicked
.length
&& e
.shiftKey
) {
7322 $options
= this.$group
.find( '.oo-ui-checkboxMultioptionWidget' );
7323 lastClickedIndex
= $options
.index( $lastClicked
);
7324 nowClickedIndex
= $options
.index( $nowClicked
);
7325 // If it's the same item, either the user is being silly, or it's a fake event generated by the
7326 // browser. In either case we don't need custom handling.
7327 if ( nowClickedIndex
!== lastClickedIndex
) {
7329 wasSelected
= items
[ nowClickedIndex
].isSelected();
7330 direction
= nowClickedIndex
> lastClickedIndex
? 1 : -1;
7332 // This depends on the DOM order of the items and the order of the .items array being the same.
7333 for ( i
= lastClickedIndex
; i
!== nowClickedIndex
; i
+= direction
) {
7334 if ( !items
[ i
].isDisabled() ) {
7335 items
[ i
].setSelected( !wasSelected
);
7338 // For the now-clicked element, use immediate timeout to allow the browser to do its own
7339 // handling first, then set our value. The order in which events happen is different for
7340 // clicks on the <input> and on the <label> and there are additional fake clicks fired for
7341 // non-click actions that change the checkboxes.
7343 setTimeout( function () {
7344 if ( !items
[ nowClickedIndex
].isDisabled() ) {
7345 items
[ nowClickedIndex
].setSelected( !wasSelected
);
7351 if ( $nowClicked
.length
) {
7352 this.$lastClicked
= $nowClicked
;
7357 * FloatingMenuSelectWidget is a menu that will stick under a specified
7358 * container, even when it is inserted elsewhere in the document (for example,
7359 * in a OO.ui.Window's $overlay). This is sometimes necessary to prevent the
7360 * menu from being clipped too aggresively.
7362 * The menu's position is automatically calculated and maintained when the menu
7363 * is toggled or the window is resized.
7365 * See OO.ui.ComboBoxInputWidget for an example of a widget that uses this class.
7368 * @extends OO.ui.MenuSelectWidget
7369 * @mixins OO.ui.mixin.FloatableElement
7372 * @param {OO.ui.Widget} [inputWidget] Widget to provide the menu for.
7373 * Deprecated, omit this parameter and specify `$container` instead.
7374 * @param {Object} [config] Configuration options
7375 * @cfg {jQuery} [$container=inputWidget.$element] Element to render menu under
7377 OO
.ui
.FloatingMenuSelectWidget
= function OoUiFloatingMenuSelectWidget( inputWidget
, config
) {
7378 // Allow 'inputWidget' parameter and config for backwards compatibility
7379 if ( OO
.isPlainObject( inputWidget
) && config
=== undefined ) {
7380 config
= inputWidget
;
7381 inputWidget
= config
.inputWidget
;
7384 // Configuration initialization
7385 config
= config
|| {};
7387 // Parent constructor
7388 OO
.ui
.FloatingMenuSelectWidget
.parent
.call( this, config
);
7390 // Properties (must be set before mixin constructors)
7391 this.inputWidget
= inputWidget
; // For backwards compatibility
7392 this.$container
= config
.$container
|| this.inputWidget
.$element
;
7394 // Mixins constructors
7395 OO
.ui
.mixin
.FloatableElement
.call( this, $.extend( {}, config
, { $floatableContainer
: this.$container
} ) );
7398 this.$element
.addClass( 'oo-ui-floatingMenuSelectWidget' );
7399 // For backwards compatibility
7400 this.$element
.addClass( 'oo-ui-textInputMenuSelectWidget' );
7405 OO
.inheritClass( OO
.ui
.FloatingMenuSelectWidget
, OO
.ui
.MenuSelectWidget
);
7406 OO
.mixinClass( OO
.ui
.FloatingMenuSelectWidget
, OO
.ui
.mixin
.FloatableElement
);
7413 OO
.ui
.FloatingMenuSelectWidget
.prototype.toggle = function ( visible
) {
7415 visible
= visible
=== undefined ? !this.isVisible() : !!visible
;
7416 change
= visible
!== this.isVisible();
7418 if ( change
&& visible
) {
7419 // Make sure the width is set before the parent method runs.
7420 this.setIdealSize( this.$container
.width() );
7424 // This will call this.clip(), which is nonsensical since we're not positioned yet...
7425 OO
.ui
.FloatingMenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
7428 this.togglePositioning( this.isVisible() );
7435 * The old name for the FloatingMenuSelectWidget widget, provided for backwards-compatibility.
7438 * @extends OO.ui.FloatingMenuSelectWidget
7441 * @deprecated since v0.12.5.
7443 OO
.ui
.TextInputMenuSelectWidget
= function OoUiTextInputMenuSelectWidget() {
7444 OO
.ui
.warnDeprecation( 'TextInputMenuSelectWidget is deprecated. Use the FloatingMenuSelectWidget instead.' );
7445 // Parent constructor
7446 OO
.ui
.TextInputMenuSelectWidget
.parent
.apply( this, arguments
);
7449 OO
.inheritClass( OO
.ui
.TextInputMenuSelectWidget
, OO
.ui
.FloatingMenuSelectWidget
);
7452 * Progress bars visually display the status of an operation, such as a download,
7453 * and can be either determinate or indeterminate:
7455 * - **determinate** process bars show the percent of an operation that is complete.
7457 * - **indeterminate** process bars use a visual display of motion to indicate that an operation
7458 * is taking place. Because the extent of an indeterminate operation is unknown, the bar does
7459 * not use percentages.
7461 * The value of the `progress` configuration determines whether the bar is determinate or indeterminate.
7464 * // Examples of determinate and indeterminate progress bars.
7465 * var progressBar1 = new OO.ui.ProgressBarWidget( {
7468 * var progressBar2 = new OO.ui.ProgressBarWidget();
7470 * // Create a FieldsetLayout to layout progress bars
7471 * var fieldset = new OO.ui.FieldsetLayout;
7472 * fieldset.addItems( [
7473 * new OO.ui.FieldLayout( progressBar1, {label: 'Determinate', align: 'top'}),
7474 * new OO.ui.FieldLayout( progressBar2, {label: 'Indeterminate', align: 'top'})
7476 * $( 'body' ).append( fieldset.$element );
7479 * @extends OO.ui.Widget
7482 * @param {Object} [config] Configuration options
7483 * @cfg {number|boolean} [progress=false] The type of progress bar (determinate or indeterminate).
7484 * To create a determinate progress bar, specify a number that reflects the initial percent complete.
7485 * By default, the progress bar is indeterminate.
7487 OO
.ui
.ProgressBarWidget
= function OoUiProgressBarWidget( config
) {
7488 // Configuration initialization
7489 config
= config
|| {};
7491 // Parent constructor
7492 OO
.ui
.ProgressBarWidget
.parent
.call( this, config
);
7495 this.$bar
= $( '<div>' );
7496 this.progress
= null;
7499 this.setProgress( config
.progress
!== undefined ? config
.progress
: false );
7500 this.$bar
.addClass( 'oo-ui-progressBarWidget-bar' );
7503 role
: 'progressbar',
7505 'aria-valuemax': 100
7507 .addClass( 'oo-ui-progressBarWidget' )
7508 .append( this.$bar
);
7513 OO
.inheritClass( OO
.ui
.ProgressBarWidget
, OO
.ui
.Widget
);
7515 /* Static Properties */
7517 OO
.ui
.ProgressBarWidget
.static.tagName
= 'div';
7522 * Get the percent of the progress that has been completed. Indeterminate progresses will return `false`.
7524 * @return {number|boolean} Progress percent
7526 OO
.ui
.ProgressBarWidget
.prototype.getProgress = function () {
7527 return this.progress
;
7531 * Set the percent of the process completed or `false` for an indeterminate process.
7533 * @param {number|boolean} progress Progress percent or `false` for indeterminate
7535 OO
.ui
.ProgressBarWidget
.prototype.setProgress = function ( progress
) {
7536 this.progress
= progress
;
7538 if ( progress
!== false ) {
7539 this.$bar
.css( 'width', this.progress
+ '%' );
7540 this.$element
.attr( 'aria-valuenow', this.progress
);
7542 this.$bar
.css( 'width', '' );
7543 this.$element
.removeAttr( 'aria-valuenow' );
7545 this.$element
.toggleClass( 'oo-ui-progressBarWidget-indeterminate', progress
=== false );
7549 * InputWidget is the base class for all input widgets, which
7550 * include {@link OO.ui.TextInputWidget text inputs}, {@link OO.ui.CheckboxInputWidget checkbox inputs},
7551 * {@link OO.ui.RadioInputWidget radio inputs}, and {@link OO.ui.ButtonInputWidget button inputs}.
7552 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
7554 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7558 * @extends OO.ui.Widget
7559 * @mixins OO.ui.mixin.FlaggedElement
7560 * @mixins OO.ui.mixin.TabIndexedElement
7561 * @mixins OO.ui.mixin.TitledElement
7562 * @mixins OO.ui.mixin.AccessKeyedElement
7565 * @param {Object} [config] Configuration options
7566 * @cfg {string} [name=''] The value of the input’s HTML `name` attribute.
7567 * @cfg {string} [value=''] The value of the input.
7568 * @cfg {string} [dir] The directionality of the input (ltr/rtl).
7569 * @cfg {Function} [inputFilter] The name of an input filter function. Input filters modify the value of an input
7570 * before it is accepted.
7572 OO
.ui
.InputWidget
= function OoUiInputWidget( config
) {
7573 // Configuration initialization
7574 config
= config
|| {};
7576 // Parent constructor
7577 OO
.ui
.InputWidget
.parent
.call( this, config
);
7580 // See #reusePreInfuseDOM about config.$input
7581 this.$input
= config
.$input
|| this.getInputElement( config
);
7583 this.inputFilter
= config
.inputFilter
;
7585 // Mixin constructors
7586 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
7587 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$input
} ) );
7588 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
7589 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$input
} ) );
7592 this.$input
.on( 'keydown mouseup cut paste change input select', this.onEdit
.bind( this ) );
7596 .addClass( 'oo-ui-inputWidget-input' )
7597 .attr( 'name', config
.name
)
7598 .prop( 'disabled', this.isDisabled() );
7600 .addClass( 'oo-ui-inputWidget' )
7601 .append( this.$input
);
7602 this.setValue( config
.value
);
7604 this.setDir( config
.dir
);
7610 OO
.inheritClass( OO
.ui
.InputWidget
, OO
.ui
.Widget
);
7611 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.FlaggedElement
);
7612 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TabIndexedElement
);
7613 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TitledElement
);
7614 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
7616 /* Static Properties */
7618 OO
.ui
.InputWidget
.static.supportsSimpleLabel
= true;
7620 /* Static Methods */
7625 OO
.ui
.InputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
7626 config
= OO
.ui
.InputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
7627 // Reusing $input lets browsers preserve inputted values across page reloads (T114134)
7628 config
.$input
= $( node
).find( '.oo-ui-inputWidget-input' );
7635 OO
.ui
.InputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
7636 var state
= OO
.ui
.InputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
7637 if ( config
.$input
&& config
.$input
.length
) {
7638 state
.value
= config
.$input
.val();
7639 // Might be better in TabIndexedElement, but it's awkward to do there because mixins are awkward
7640 state
.focus
= config
.$input
.is( ':focus' );
7650 * A change event is emitted when the value of the input changes.
7652 * @param {string} value
7658 * Get input element.
7660 * Subclasses of OO.ui.InputWidget use the `config` parameter to produce different elements in
7661 * different circumstances. The element must have a `value` property (like form elements).
7664 * @param {Object} config Configuration options
7665 * @return {jQuery} Input element
7667 OO
.ui
.InputWidget
.prototype.getInputElement = function () {
7668 return $( '<input>' );
7672 * Handle potentially value-changing events.
7675 * @param {jQuery.Event} e Key down, mouse up, cut, paste, change, input, or select event
7677 OO
.ui
.InputWidget
.prototype.onEdit = function () {
7679 if ( !this.isDisabled() ) {
7680 // Allow the stack to clear so the value will be updated
7681 setTimeout( function () {
7682 widget
.setValue( widget
.$input
.val() );
7688 * Get the value of the input.
7690 * @return {string} Input value
7692 OO
.ui
.InputWidget
.prototype.getValue = function () {
7693 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
7694 // it, and we won't know unless they're kind enough to trigger a 'change' event.
7695 var value
= this.$input
.val();
7696 if ( this.value
!== value
) {
7697 this.setValue( value
);
7703 * Set the directionality of the input.
7705 * @param {string} dir Text directionality: 'ltr', 'rtl' or 'auto'
7708 OO
.ui
.InputWidget
.prototype.setDir = function ( dir
) {
7709 this.$input
.prop( 'dir', dir
);
7714 * Set the value of the input.
7716 * @param {string} value New value
7720 OO
.ui
.InputWidget
.prototype.setValue = function ( value
) {
7721 value
= this.cleanUpValue( value
);
7722 // Update the DOM if it has changed. Note that with cleanUpValue, it
7723 // is possible for the DOM value to change without this.value changing.
7724 if ( this.$input
.val() !== value
) {
7725 this.$input
.val( value
);
7727 if ( this.value
!== value
) {
7729 this.emit( 'change', this.value
);
7735 * Clean up incoming value.
7737 * Ensures value is a string, and converts undefined and null to empty string.
7740 * @param {string} value Original value
7741 * @return {string} Cleaned up value
7743 OO
.ui
.InputWidget
.prototype.cleanUpValue = function ( value
) {
7744 if ( value
=== undefined || value
=== null ) {
7746 } else if ( this.inputFilter
) {
7747 return this.inputFilter( String( value
) );
7749 return String( value
);
7754 * Simulate the behavior of clicking on a label bound to this input. This method is only called by
7755 * {@link OO.ui.LabelWidget LabelWidget} and {@link OO.ui.FieldLayout FieldLayout}. It should not be
7758 OO
.ui
.InputWidget
.prototype.simulateLabelClick = function () {
7759 if ( !this.isDisabled() ) {
7760 if ( this.$input
.is( ':checkbox, :radio' ) ) {
7761 this.$input
.click();
7763 if ( this.$input
.is( ':input' ) ) {
7764 this.$input
[ 0 ].focus();
7772 OO
.ui
.InputWidget
.prototype.setDisabled = function ( state
) {
7773 OO
.ui
.InputWidget
.parent
.prototype.setDisabled
.call( this, state
);
7774 if ( this.$input
) {
7775 this.$input
.prop( 'disabled', this.isDisabled() );
7785 OO
.ui
.InputWidget
.prototype.focus = function () {
7786 this.$input
[ 0 ].focus();
7795 OO
.ui
.InputWidget
.prototype.blur = function () {
7796 this.$input
[ 0 ].blur();
7803 OO
.ui
.InputWidget
.prototype.restorePreInfuseState = function ( state
) {
7804 OO
.ui
.InputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
7805 if ( state
.value
!== undefined && state
.value
!== this.getValue() ) {
7806 this.setValue( state
.value
);
7808 if ( state
.focus
) {
7814 * ButtonInputWidget is used to submit HTML forms and is intended to be used within
7815 * a OO.ui.FormLayout. If you do not need the button to work with HTML forms, you probably
7816 * want to use OO.ui.ButtonWidget instead. Button input widgets can be rendered as either an
7817 * HTML `<button>` (the default) or an HTML `<input>` tags. See the
7818 * [OOjs UI documentation on MediaWiki] [1] for more information.
7821 * // A ButtonInputWidget rendered as an HTML button, the default.
7822 * var button = new OO.ui.ButtonInputWidget( {
7823 * label: 'Input button',
7827 * $( 'body' ).append( button.$element );
7829 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs#Button_inputs
7832 * @extends OO.ui.InputWidget
7833 * @mixins OO.ui.mixin.ButtonElement
7834 * @mixins OO.ui.mixin.IconElement
7835 * @mixins OO.ui.mixin.IndicatorElement
7836 * @mixins OO.ui.mixin.LabelElement
7837 * @mixins OO.ui.mixin.TitledElement
7840 * @param {Object} [config] Configuration options
7841 * @cfg {string} [type='button'] The value of the HTML `'type'` attribute: 'button', 'submit' or 'reset'.
7842 * @cfg {boolean} [useInputTag=false] Use an `<input>` tag instead of a `<button>` tag, the default.
7843 * Widgets configured to be an `<input>` do not support {@link #icon icons} and {@link #indicator indicators},
7844 * non-plaintext {@link #label labels}, or {@link #value values}. In general, useInputTag should only
7845 * be set to `true` when there’s need to support IE 6 in a form with multiple buttons.
7847 OO
.ui
.ButtonInputWidget
= function OoUiButtonInputWidget( config
) {
7848 // Configuration initialization
7849 config
= $.extend( { type
: 'button', useInputTag
: false }, config
);
7851 // See InputWidget#reusePreInfuseDOM about config.$input
7852 if ( config
.$input
) {
7853 config
.$input
.empty();
7856 // Properties (must be set before parent constructor, which calls #setValue)
7857 this.useInputTag
= config
.useInputTag
;
7859 // Parent constructor
7860 OO
.ui
.ButtonInputWidget
.parent
.call( this, config
);
7862 // Mixin constructors
7863 OO
.ui
.mixin
.ButtonElement
.call( this, $.extend( {}, config
, { $button
: this.$input
} ) );
7864 OO
.ui
.mixin
.IconElement
.call( this, config
);
7865 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
7866 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7867 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
7870 if ( !config
.useInputTag
) {
7871 this.$input
.append( this.$icon
, this.$label
, this.$indicator
);
7873 this.$element
.addClass( 'oo-ui-buttonInputWidget' );
7878 OO
.inheritClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.InputWidget
);
7879 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.ButtonElement
);
7880 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IconElement
);
7881 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
7882 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.LabelElement
);
7883 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.TitledElement
);
7885 /* Static Properties */
7888 * Disable generating `<label>` elements for buttons. One would very rarely need additional label
7889 * for a button, and it's already a big clickable target, and it causes unexpected rendering.
7891 OO
.ui
.ButtonInputWidget
.static.supportsSimpleLabel
= false;
7899 OO
.ui
.ButtonInputWidget
.prototype.getInputElement = function ( config
) {
7901 type
= [ 'button', 'submit', 'reset' ].indexOf( config
.type
) !== -1 ? config
.type
: 'button';
7902 return $( '<' + ( config
.useInputTag
? 'input' : 'button' ) + ' type="' + type
+ '">' );
7908 * If #useInputTag is `true`, the label is set as the `value` of the `<input>` tag.
7910 * @param {jQuery|string|Function|null} label Label nodes, text, a function that returns nodes or
7911 * text, or `null` for no label
7914 OO
.ui
.ButtonInputWidget
.prototype.setLabel = function ( label
) {
7915 if ( typeof label
=== 'function' ) {
7916 label
= OO
.ui
.resolveMsg( label
);
7919 if ( this.useInputTag
) {
7920 // Discard non-plaintext labels
7921 if ( typeof label
!== 'string' ) {
7925 this.$input
.val( label
);
7928 return OO
.ui
.mixin
.LabelElement
.prototype.setLabel
.call( this, label
);
7932 * Set the value of the input.
7934 * This method is disabled for button inputs configured as {@link #useInputTag <input> tags}, as
7935 * they do not support {@link #value values}.
7937 * @param {string} value New value
7940 OO
.ui
.ButtonInputWidget
.prototype.setValue = function ( value
) {
7941 if ( !this.useInputTag
) {
7942 OO
.ui
.ButtonInputWidget
.parent
.prototype.setValue
.call( this, value
);
7948 * CheckboxInputWidgets, like HTML checkboxes, can be selected and/or configured with a value.
7949 * Note that these {@link OO.ui.InputWidget input widgets} are best laid out
7950 * in {@link OO.ui.FieldLayout field layouts} that use the {@link OO.ui.FieldLayout#align inline}
7951 * alignment. For more information, please see the [OOjs UI documentation on MediaWiki][1].
7953 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
7956 * // An example of selected, unselected, and disabled checkbox inputs
7957 * var checkbox1=new OO.ui.CheckboxInputWidget( {
7961 * var checkbox2=new OO.ui.CheckboxInputWidget( {
7964 * var checkbox3=new OO.ui.CheckboxInputWidget( {
7968 * // Create a fieldset layout with fields for each checkbox.
7969 * var fieldset = new OO.ui.FieldsetLayout( {
7970 * label: 'Checkboxes'
7972 * fieldset.addItems( [
7973 * new OO.ui.FieldLayout( checkbox1, { label: 'Selected checkbox', align: 'inline' } ),
7974 * new OO.ui.FieldLayout( checkbox2, { label: 'Unselected checkbox', align: 'inline' } ),
7975 * new OO.ui.FieldLayout( checkbox3, { label: 'Disabled checkbox', align: 'inline' } ),
7977 * $( 'body' ).append( fieldset.$element );
7979 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7982 * @extends OO.ui.InputWidget
7985 * @param {Object} [config] Configuration options
7986 * @cfg {boolean} [selected=false] Select the checkbox initially. By default, the checkbox is not selected.
7988 OO
.ui
.CheckboxInputWidget
= function OoUiCheckboxInputWidget( config
) {
7989 // Configuration initialization
7990 config
= config
|| {};
7992 // Parent constructor
7993 OO
.ui
.CheckboxInputWidget
.parent
.call( this, config
);
7997 .addClass( 'oo-ui-checkboxInputWidget' )
7998 // Required for pretty styling in MediaWiki theme
7999 .append( $( '<span>' ) );
8000 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
8005 OO
.inheritClass( OO
.ui
.CheckboxInputWidget
, OO
.ui
.InputWidget
);
8007 /* Static Methods */
8012 OO
.ui
.CheckboxInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8013 var state
= OO
.ui
.CheckboxInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8014 state
.checked
= config
.$input
.prop( 'checked' );
8024 OO
.ui
.CheckboxInputWidget
.prototype.getInputElement = function () {
8025 return $( '<input>' ).attr( 'type', 'checkbox' );
8031 OO
.ui
.CheckboxInputWidget
.prototype.onEdit = function () {
8033 if ( !this.isDisabled() ) {
8034 // Allow the stack to clear so the value will be updated
8035 setTimeout( function () {
8036 widget
.setSelected( widget
.$input
.prop( 'checked' ) );
8042 * Set selection state of this checkbox.
8044 * @param {boolean} state `true` for selected
8047 OO
.ui
.CheckboxInputWidget
.prototype.setSelected = function ( state
) {
8049 if ( this.selected
!== state
) {
8050 this.selected
= state
;
8051 this.$input
.prop( 'checked', this.selected
);
8052 this.emit( 'change', this.selected
);
8058 * Check if this checkbox is selected.
8060 * @return {boolean} Checkbox is selected
8062 OO
.ui
.CheckboxInputWidget
.prototype.isSelected = function () {
8063 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
8064 // it, and we won't know unless they're kind enough to trigger a 'change' event.
8065 var selected
= this.$input
.prop( 'checked' );
8066 if ( this.selected
!== selected
) {
8067 this.setSelected( selected
);
8069 return this.selected
;
8075 OO
.ui
.CheckboxInputWidget
.prototype.restorePreInfuseState = function ( state
) {
8076 OO
.ui
.CheckboxInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8077 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
8078 this.setSelected( state
.checked
);
8083 * DropdownInputWidget is a {@link OO.ui.DropdownWidget DropdownWidget} intended to be used
8084 * within an HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
8085 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
8086 * more information about input widgets.
8088 * A DropdownInputWidget always has a value (one of the options is always selected), unless there
8089 * are no options. If no `value` configuration option is provided, the first option is selected.
8090 * If you need a state representing no value (no option being selected), use a DropdownWidget.
8092 * This and OO.ui.RadioSelectInputWidget support the same configuration options.
8095 * // Example: A DropdownInputWidget with three options
8096 * var dropdownInput = new OO.ui.DropdownInputWidget( {
8098 * { data: 'a', label: 'First' },
8099 * { data: 'b', label: 'Second'},
8100 * { data: 'c', label: 'Third' }
8103 * $( 'body' ).append( dropdownInput.$element );
8105 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8108 * @extends OO.ui.InputWidget
8109 * @mixins OO.ui.mixin.TitledElement
8112 * @param {Object} [config] Configuration options
8113 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
8114 * @cfg {Object} [dropdown] Configuration options for {@link OO.ui.DropdownWidget DropdownWidget}
8116 OO
.ui
.DropdownInputWidget
= function OoUiDropdownInputWidget( config
) {
8117 // Configuration initialization
8118 config
= config
|| {};
8120 // See InputWidget#reusePreInfuseDOM about config.$input
8121 if ( config
.$input
) {
8122 config
.$input
.addClass( 'oo-ui-element-hidden' );
8125 // Properties (must be done before parent constructor which calls #setDisabled)
8126 this.dropdownWidget
= new OO
.ui
.DropdownWidget( config
.dropdown
);
8128 // Parent constructor
8129 OO
.ui
.DropdownInputWidget
.parent
.call( this, config
);
8131 // Mixin constructors
8132 OO
.ui
.mixin
.TitledElement
.call( this, config
);
8135 this.dropdownWidget
.getMenu().connect( this, { select
: 'onMenuSelect' } );
8138 this.setOptions( config
.options
|| [] );
8140 .addClass( 'oo-ui-dropdownInputWidget' )
8141 .append( this.dropdownWidget
.$element
);
8146 OO
.inheritClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.InputWidget
);
8147 OO
.mixinClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.mixin
.TitledElement
);
8155 OO
.ui
.DropdownInputWidget
.prototype.getInputElement = function () {
8156 return $( '<input>' ).attr( 'type', 'hidden' );
8160 * Handles menu select events.
8163 * @param {OO.ui.MenuOptionWidget} item Selected menu item
8165 OO
.ui
.DropdownInputWidget
.prototype.onMenuSelect = function ( item
) {
8166 this.setValue( item
.getData() );
8172 OO
.ui
.DropdownInputWidget
.prototype.setValue = function ( value
) {
8173 value
= this.cleanUpValue( value
);
8174 this.dropdownWidget
.getMenu().selectItemByData( value
);
8175 OO
.ui
.DropdownInputWidget
.parent
.prototype.setValue
.call( this, value
);
8182 OO
.ui
.DropdownInputWidget
.prototype.setDisabled = function ( state
) {
8183 this.dropdownWidget
.setDisabled( state
);
8184 OO
.ui
.DropdownInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
8189 * Set the options available for this input.
8191 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
8194 OO
.ui
.DropdownInputWidget
.prototype.setOptions = function ( options
) {
8196 value
= this.getValue(),
8199 // Rebuild the dropdown menu
8200 this.dropdownWidget
.getMenu()
8202 .addItems( options
.map( function ( opt
) {
8203 var optValue
= widget
.cleanUpValue( opt
.data
);
8204 return new OO
.ui
.MenuOptionWidget( {
8206 label
: opt
.label
!== undefined ? opt
.label
: optValue
8210 // Restore the previous value, or reset to something sensible
8211 if ( this.dropdownWidget
.getMenu().getItemFromData( value
) ) {
8212 // Previous value is still available, ensure consistency with the dropdown
8213 this.setValue( value
);
8215 // No longer valid, reset
8216 if ( options
.length
) {
8217 this.setValue( options
[ 0 ].data
);
8227 OO
.ui
.DropdownInputWidget
.prototype.focus = function () {
8228 this.dropdownWidget
.getMenu().toggle( true );
8235 OO
.ui
.DropdownInputWidget
.prototype.blur = function () {
8236 this.dropdownWidget
.getMenu().toggle( false );
8241 * RadioInputWidget creates a single radio button. Because radio buttons are usually used as a set,
8242 * in most cases you will want to use a {@link OO.ui.RadioSelectWidget radio select}
8243 * with {@link OO.ui.RadioOptionWidget radio options} instead of this class. For more information,
8244 * please see the [OOjs UI documentation on MediaWiki][1].
8246 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
8249 * // An example of selected, unselected, and disabled radio inputs
8250 * var radio1 = new OO.ui.RadioInputWidget( {
8254 * var radio2 = new OO.ui.RadioInputWidget( {
8257 * var radio3 = new OO.ui.RadioInputWidget( {
8261 * // Create a fieldset layout with fields for each radio button.
8262 * var fieldset = new OO.ui.FieldsetLayout( {
8263 * label: 'Radio inputs'
8265 * fieldset.addItems( [
8266 * new OO.ui.FieldLayout( radio1, { label: 'Selected', align: 'inline' } ),
8267 * new OO.ui.FieldLayout( radio2, { label: 'Unselected', align: 'inline' } ),
8268 * new OO.ui.FieldLayout( radio3, { label: 'Disabled', align: 'inline' } ),
8270 * $( 'body' ).append( fieldset.$element );
8272 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8275 * @extends OO.ui.InputWidget
8278 * @param {Object} [config] Configuration options
8279 * @cfg {boolean} [selected=false] Select the radio button initially. By default, the radio button is not selected.
8281 OO
.ui
.RadioInputWidget
= function OoUiRadioInputWidget( config
) {
8282 // Configuration initialization
8283 config
= config
|| {};
8285 // Parent constructor
8286 OO
.ui
.RadioInputWidget
.parent
.call( this, config
);
8290 .addClass( 'oo-ui-radioInputWidget' )
8291 // Required for pretty styling in MediaWiki theme
8292 .append( $( '<span>' ) );
8293 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
8298 OO
.inheritClass( OO
.ui
.RadioInputWidget
, OO
.ui
.InputWidget
);
8300 /* Static Methods */
8305 OO
.ui
.RadioInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8306 var state
= OO
.ui
.RadioInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8307 state
.checked
= config
.$input
.prop( 'checked' );
8317 OO
.ui
.RadioInputWidget
.prototype.getInputElement = function () {
8318 return $( '<input>' ).attr( 'type', 'radio' );
8324 OO
.ui
.RadioInputWidget
.prototype.onEdit = function () {
8325 // RadioInputWidget doesn't track its state.
8329 * Set selection state of this radio button.
8331 * @param {boolean} state `true` for selected
8334 OO
.ui
.RadioInputWidget
.prototype.setSelected = function ( state
) {
8335 // RadioInputWidget doesn't track its state.
8336 this.$input
.prop( 'checked', state
);
8341 * Check if this radio button is selected.
8343 * @return {boolean} Radio is selected
8345 OO
.ui
.RadioInputWidget
.prototype.isSelected = function () {
8346 return this.$input
.prop( 'checked' );
8352 OO
.ui
.RadioInputWidget
.prototype.restorePreInfuseState = function ( state
) {
8353 OO
.ui
.RadioInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8354 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
8355 this.setSelected( state
.checked
);
8360 * RadioSelectInputWidget is a {@link OO.ui.RadioSelectWidget RadioSelectWidget} intended to be used
8361 * within an HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
8362 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
8363 * more information about input widgets.
8365 * This and OO.ui.DropdownInputWidget support the same configuration options.
8368 * // Example: A RadioSelectInputWidget with three options
8369 * var radioSelectInput = new OO.ui.RadioSelectInputWidget( {
8371 * { data: 'a', label: 'First' },
8372 * { data: 'b', label: 'Second'},
8373 * { data: 'c', label: 'Third' }
8376 * $( 'body' ).append( radioSelectInput.$element );
8378 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8381 * @extends OO.ui.InputWidget
8384 * @param {Object} [config] Configuration options
8385 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
8387 OO
.ui
.RadioSelectInputWidget
= function OoUiRadioSelectInputWidget( config
) {
8388 // Configuration initialization
8389 config
= config
|| {};
8391 // Properties (must be done before parent constructor which calls #setDisabled)
8392 this.radioSelectWidget
= new OO
.ui
.RadioSelectWidget();
8394 // Parent constructor
8395 OO
.ui
.RadioSelectInputWidget
.parent
.call( this, config
);
8398 this.radioSelectWidget
.connect( this, { select
: 'onMenuSelect' } );
8401 this.setOptions( config
.options
|| [] );
8403 .addClass( 'oo-ui-radioSelectInputWidget' )
8404 .append( this.radioSelectWidget
.$element
);
8409 OO
.inheritClass( OO
.ui
.RadioSelectInputWidget
, OO
.ui
.InputWidget
);
8411 /* Static Properties */
8413 OO
.ui
.RadioSelectInputWidget
.static.supportsSimpleLabel
= false;
8415 /* Static Methods */
8420 OO
.ui
.RadioSelectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8421 var state
= OO
.ui
.RadioSelectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8422 state
.value
= $( node
).find( '.oo-ui-radioInputWidget .oo-ui-inputWidget-input:checked' ).val();
8429 OO
.ui
.RadioSelectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
8430 config
= OO
.ui
.RadioSelectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
8431 // Cannot reuse the `<input type=radio>` set
8432 delete config
.$input
;
8442 OO
.ui
.RadioSelectInputWidget
.prototype.getInputElement = function () {
8443 return $( '<input>' ).attr( 'type', 'hidden' );
8447 * Handles menu select events.
8450 * @param {OO.ui.RadioOptionWidget} item Selected menu item
8452 OO
.ui
.RadioSelectInputWidget
.prototype.onMenuSelect = function ( item
) {
8453 this.setValue( item
.getData() );
8459 OO
.ui
.RadioSelectInputWidget
.prototype.setValue = function ( value
) {
8460 value
= this.cleanUpValue( value
);
8461 this.radioSelectWidget
.selectItemByData( value
);
8462 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setValue
.call( this, value
);
8469 OO
.ui
.RadioSelectInputWidget
.prototype.setDisabled = function ( state
) {
8470 this.radioSelectWidget
.setDisabled( state
);
8471 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
8476 * Set the options available for this input.
8478 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
8481 OO
.ui
.RadioSelectInputWidget
.prototype.setOptions = function ( options
) {
8483 value
= this.getValue(),
8486 // Rebuild the radioSelect menu
8487 this.radioSelectWidget
8489 .addItems( options
.map( function ( opt
) {
8490 var optValue
= widget
.cleanUpValue( opt
.data
);
8491 return new OO
.ui
.RadioOptionWidget( {
8493 label
: opt
.label
!== undefined ? opt
.label
: optValue
8497 // Restore the previous value, or reset to something sensible
8498 if ( this.radioSelectWidget
.getItemFromData( value
) ) {
8499 // Previous value is still available, ensure consistency with the radioSelect
8500 this.setValue( value
);
8502 // No longer valid, reset
8503 if ( options
.length
) {
8504 this.setValue( options
[ 0 ].data
);
8512 * CheckboxMultiselectInputWidget is a
8513 * {@link OO.ui.CheckboxMultiselectWidget CheckboxMultiselectWidget} intended to be used within a
8514 * HTML form, such as a OO.ui.FormLayout. The selected values are synchronized with the value of
8515 * HTML `<input type=checkbox>` tags. Please see the [OOjs UI documentation on MediaWiki][1] for
8516 * more information about input widgets.
8519 * // Example: A CheckboxMultiselectInputWidget with three options
8520 * var multiselectInput = new OO.ui.CheckboxMultiselectInputWidget( {
8522 * { data: 'a', label: 'First' },
8523 * { data: 'b', label: 'Second'},
8524 * { data: 'c', label: 'Third' }
8527 * $( 'body' ).append( multiselectInput.$element );
8529 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8532 * @extends OO.ui.InputWidget
8535 * @param {Object} [config] Configuration options
8536 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
8538 OO
.ui
.CheckboxMultiselectInputWidget
= function OoUiCheckboxMultiselectInputWidget( config
) {
8539 // Configuration initialization
8540 config
= config
|| {};
8542 // Properties (must be done before parent constructor which calls #setDisabled)
8543 this.checkboxMultiselectWidget
= new OO
.ui
.CheckboxMultiselectWidget();
8545 // Parent constructor
8546 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.call( this, config
);
8549 this.inputName
= config
.name
;
8553 .addClass( 'oo-ui-checkboxMultiselectInputWidget' )
8554 .append( this.checkboxMultiselectWidget
.$element
);
8555 // We don't use this.$input, but rather the CheckboxInputWidgets inside each option
8556 this.$input
.detach();
8557 this.setOptions( config
.options
|| [] );
8558 // Have to repeat this from parent, as we need options to be set up for this to make sense
8559 this.setValue( config
.value
);
8564 OO
.inheritClass( OO
.ui
.CheckboxMultiselectInputWidget
, OO
.ui
.InputWidget
);
8566 /* Static Properties */
8568 OO
.ui
.CheckboxMultiselectInputWidget
.static.supportsSimpleLabel
= false;
8570 /* Static Methods */
8575 OO
.ui
.CheckboxMultiselectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8576 var state
= OO
.ui
.CheckboxMultiselectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8577 state
.value
= $( node
).find( '.oo-ui-checkboxInputWidget .oo-ui-inputWidget-input:checked' )
8578 .toArray().map( function ( el
) { return el
.value
; } );
8585 OO
.ui
.CheckboxMultiselectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
8586 config
= OO
.ui
.CheckboxMultiselectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
8587 // Cannot reuse the `<input type=checkbox>` set
8588 delete config
.$input
;
8598 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.getInputElement = function () {
8600 return $( '<div>' );
8606 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.getValue = function () {
8607 var value
= this.$element
.find( '.oo-ui-checkboxInputWidget .oo-ui-inputWidget-input:checked' )
8608 .toArray().map( function ( el
) { return el
.value
; } );
8609 if ( this.value
!== value
) {
8610 this.setValue( value
);
8618 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setValue = function ( value
) {
8619 value
= this.cleanUpValue( value
);
8620 this.checkboxMultiselectWidget
.selectItemsByData( value
);
8621 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.setValue
.call( this, value
);
8626 * Clean up incoming value.
8628 * @param {string[]} value Original value
8629 * @return {string[]} Cleaned up value
8631 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.cleanUpValue = function ( value
) {
8634 if ( !Array
.isArray( value
) ) {
8637 for ( i
= 0; i
< value
.length
; i
++ ) {
8639 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.cleanUpValue
.call( this, value
[ i
] );
8640 // Remove options that we don't have here
8641 if ( !this.checkboxMultiselectWidget
.getItemFromData( singleValue
) ) {
8644 cleanValue
.push( singleValue
);
8652 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setDisabled = function ( state
) {
8653 this.checkboxMultiselectWidget
.setDisabled( state
);
8654 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
8659 * Set the options available for this input.
8661 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
8664 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setOptions = function ( options
) {
8667 // Rebuild the checkboxMultiselectWidget menu
8668 this.checkboxMultiselectWidget
8670 .addItems( options
.map( function ( opt
) {
8673 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.cleanUpValue
.call( widget
, opt
.data
);
8674 item
= new OO
.ui
.CheckboxMultioptionWidget( {
8676 label
: opt
.label
!== undefined ? opt
.label
: optValue
8678 // Set the 'name' and 'value' for form submission
8679 item
.checkbox
.$input
.attr( 'name', widget
.inputName
);
8680 item
.checkbox
.setValue( optValue
);
8684 // Re-set the value, checking the checkboxes as needed.
8685 // This will also get rid of any stale options that we just removed.
8686 this.setValue( this.getValue() );
8692 * TextInputWidgets, like HTML text inputs, can be configured with options that customize the
8693 * size of the field as well as its presentation. In addition, these widgets can be configured
8694 * with {@link OO.ui.mixin.IconElement icons}, {@link OO.ui.mixin.IndicatorElement indicators}, an optional
8695 * validation-pattern (used to determine if an input value is valid or not) and an input filter,
8696 * which modifies incoming values rather than validating them.
8697 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
8699 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
8702 * // Example of a text input widget
8703 * var textInput = new OO.ui.TextInputWidget( {
8704 * value: 'Text input'
8706 * $( 'body' ).append( textInput.$element );
8708 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8711 * @extends OO.ui.InputWidget
8712 * @mixins OO.ui.mixin.IconElement
8713 * @mixins OO.ui.mixin.IndicatorElement
8714 * @mixins OO.ui.mixin.PendingElement
8715 * @mixins OO.ui.mixin.LabelElement
8718 * @param {Object} [config] Configuration options
8719 * @cfg {string} [type='text'] The value of the HTML `type` attribute: 'text', 'password', 'search',
8720 * 'email', 'url', 'date', 'month' or 'number'. Ignored if `multiline` is true.
8722 * Some values of `type` result in additional behaviors:
8724 * - `search`: implies `icon: 'search'` and `indicator: 'clear'`; when clicked, the indicator
8725 * empties the text field
8726 * @cfg {string} [placeholder] Placeholder text
8727 * @cfg {boolean} [autofocus=false] Use an HTML `autofocus` attribute to
8728 * instruct the browser to focus this widget.
8729 * @cfg {boolean} [readOnly=false] Prevent changes to the value of the text input.
8730 * @cfg {number} [maxLength] Maximum number of characters allowed in the input.
8731 * @cfg {boolean} [multiline=false] Allow multiple lines of text
8732 * @cfg {number} [rows] If multiline, number of visible lines in textarea. If used with `autosize`,
8733 * specifies minimum number of rows to display.
8734 * @cfg {boolean} [autosize=false] Automatically resize the text input to fit its content.
8735 * Use the #maxRows config to specify a maximum number of displayed rows.
8736 * @cfg {boolean} [maxRows] Maximum number of rows to display when #autosize is set to true.
8737 * Defaults to the maximum of `10` and `2 * rows`, or `10` if `rows` isn't provided.
8738 * @cfg {string} [labelPosition='after'] The position of the inline label relative to that of
8739 * the value or placeholder text: `'before'` or `'after'`
8740 * @cfg {boolean} [required=false] Mark the field as required. Implies `indicator: 'required'`.
8741 * @cfg {boolean} [autocomplete=true] Should the browser support autocomplete for this field
8742 * @cfg {RegExp|Function|string} [validate] Validation pattern: when string, a symbolic name of a
8743 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer'
8744 * (the value must contain only numbers); when RegExp, a regular expression that must match the
8745 * value for it to be considered valid; when Function, a function receiving the value as parameter
8746 * that must return true, or promise resolving to true, for it to be considered valid.
8748 OO
.ui
.TextInputWidget
= function OoUiTextInputWidget( config
) {
8749 // Configuration initialization
8750 config
= $.extend( {
8752 labelPosition
: 'after'
8755 if ( config
.type
=== 'search' ) {
8756 OO
.ui
.warnDeprecation( 'TextInputWidget: config.type=\'search\' is deprecated. Use the SearchInputWidget instead. See T148471 for details.' );
8757 if ( config
.icon
=== undefined ) {
8758 config
.icon
= 'search';
8760 // indicator: 'clear' is set dynamically later, depending on value
8763 // Parent constructor
8764 OO
.ui
.TextInputWidget
.parent
.call( this, config
);
8766 // Mixin constructors
8767 OO
.ui
.mixin
.IconElement
.call( this, config
);
8768 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
8769 OO
.ui
.mixin
.PendingElement
.call( this, $.extend( {}, config
, { $pending
: this.$input
} ) );
8770 OO
.ui
.mixin
.LabelElement
.call( this, config
);
8773 this.type
= this.getSaneType( config
);
8774 this.readOnly
= false;
8775 this.required
= false;
8776 this.multiline
= !!config
.multiline
;
8777 this.autosize
= !!config
.autosize
;
8778 this.minRows
= config
.rows
!== undefined ? config
.rows
: '';
8779 this.maxRows
= config
.maxRows
|| Math
.max( 2 * ( this.minRows
|| 0 ), 10 );
8780 this.validate
= null;
8781 this.styleHeight
= null;
8782 this.scrollWidth
= null;
8784 // Clone for resizing
8785 if ( this.autosize
) {
8786 this.$clone
= this.$input
8788 .insertAfter( this.$input
)
8789 .attr( 'aria-hidden', 'true' )
8790 .addClass( 'oo-ui-element-hidden' );
8793 this.setValidation( config
.validate
);
8794 this.setLabelPosition( config
.labelPosition
);
8798 keypress
: this.onKeyPress
.bind( this ),
8799 blur
: this.onBlur
.bind( this ),
8800 focus
: this.onFocus
.bind( this )
8802 this.$icon
.on( 'mousedown', this.onIconMouseDown
.bind( this ) );
8803 this.$indicator
.on( 'mousedown', this.onIndicatorMouseDown
.bind( this ) );
8804 this.on( 'labelChange', this.updatePosition
.bind( this ) );
8805 this.connect( this, {
8807 disable
: 'onDisable'
8809 this.on( 'change', OO
.ui
.debounce( this.onDebouncedChange
.bind( this ), 250 ) );
8813 .addClass( 'oo-ui-textInputWidget oo-ui-textInputWidget-type-' + this.type
)
8814 .append( this.$icon
, this.$indicator
);
8815 this.setReadOnly( !!config
.readOnly
);
8816 this.setRequired( !!config
.required
);
8817 this.updateSearchIndicator();
8818 if ( config
.placeholder
!== undefined ) {
8819 this.$input
.attr( 'placeholder', config
.placeholder
);
8821 if ( config
.maxLength
!== undefined ) {
8822 this.$input
.attr( 'maxlength', config
.maxLength
);
8824 if ( config
.autofocus
) {
8825 this.$input
.attr( 'autofocus', 'autofocus' );
8827 if ( config
.autocomplete
=== false ) {
8828 this.$input
.attr( 'autocomplete', 'off' );
8829 // Turning off autocompletion also disables "form caching" when the user navigates to a
8830 // different page and then clicks "Back". Re-enable it when leaving. Borrowed from jQuery UI.
8832 beforeunload: function () {
8833 this.$input
.removeAttr( 'autocomplete' );
8835 pageshow: function () {
8836 // Browsers don't seem to actually fire this event on "Back", they instead just reload the
8837 // whole page... it shouldn't hurt, though.
8838 this.$input
.attr( 'autocomplete', 'off' );
8842 if ( this.multiline
&& config
.rows
) {
8843 this.$input
.attr( 'rows', config
.rows
);
8845 if ( this.label
|| config
.autosize
) {
8846 this.isWaitingToBeAttached
= true;
8847 this.installParentChangeDetector();
8853 OO
.inheritClass( OO
.ui
.TextInputWidget
, OO
.ui
.InputWidget
);
8854 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IconElement
);
8855 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
8856 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.PendingElement
);
8857 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.LabelElement
);
8859 /* Static Properties */
8861 OO
.ui
.TextInputWidget
.static.validationPatterns
= {
8866 /* Static Methods */
8871 OO
.ui
.TextInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8872 var state
= OO
.ui
.TextInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8873 if ( config
.multiline
) {
8874 state
.scrollTop
= config
.$input
.scrollTop();
8882 * An `enter` event is emitted when the user presses 'enter' inside the text box.
8884 * Not emitted if the input is multiline.
8890 * A `resize` event is emitted when autosize is set and the widget resizes
8898 * Handle icon mouse down events.
8901 * @param {jQuery.Event} e Mouse down event
8903 OO
.ui
.TextInputWidget
.prototype.onIconMouseDown = function ( e
) {
8904 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
8905 this.$input
[ 0 ].focus();
8911 * Handle indicator mouse down events.
8914 * @param {jQuery.Event} e Mouse down event
8916 OO
.ui
.TextInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
8917 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
8918 if ( this.type
=== 'search' ) {
8919 // Clear the text field
8920 this.setValue( '' );
8922 this.$input
[ 0 ].focus();
8928 * Handle key press events.
8931 * @param {jQuery.Event} e Key press event
8932 * @fires enter If enter key is pressed and input is not multiline
8934 OO
.ui
.TextInputWidget
.prototype.onKeyPress = function ( e
) {
8935 if ( e
.which
=== OO
.ui
.Keys
.ENTER
&& !this.multiline
) {
8936 this.emit( 'enter', e
);
8941 * Handle blur events.
8944 * @param {jQuery.Event} e Blur event
8946 OO
.ui
.TextInputWidget
.prototype.onBlur = function () {
8947 this.setValidityFlag();
8951 * Handle focus events.
8954 * @param {jQuery.Event} e Focus event
8956 OO
.ui
.TextInputWidget
.prototype.onFocus = function () {
8957 if ( this.isWaitingToBeAttached
) {
8958 // If we've received focus, then we must be attached to the document, and if
8959 // isWaitingToBeAttached is still true, that means the handler never fired. Fire it now.
8960 this.onElementAttach();
8962 this.setValidityFlag( true );
8966 * Handle element attach events.
8969 * @param {jQuery.Event} e Element attach event
8971 OO
.ui
.TextInputWidget
.prototype.onElementAttach = function () {
8972 this.isWaitingToBeAttached
= false;
8973 // Any previously calculated size is now probably invalid if we reattached elsewhere
8974 this.valCache
= null;
8976 this.positionLabel();
8980 * Handle change events.
8982 * @param {string} value
8985 OO
.ui
.TextInputWidget
.prototype.onChange = function () {
8986 this.updateSearchIndicator();
8991 * Handle debounced change events.
8993 * @param {string} value
8996 OO
.ui
.TextInputWidget
.prototype.onDebouncedChange = function () {
8997 this.setValidityFlag();
9001 * Handle disable events.
9003 * @param {boolean} disabled Element is disabled
9006 OO
.ui
.TextInputWidget
.prototype.onDisable = function () {
9007 this.updateSearchIndicator();
9011 * Check if the input is {@link #readOnly read-only}.
9015 OO
.ui
.TextInputWidget
.prototype.isReadOnly = function () {
9016 return this.readOnly
;
9020 * Set the {@link #readOnly read-only} state of the input.
9022 * @param {boolean} state Make input read-only
9025 OO
.ui
.TextInputWidget
.prototype.setReadOnly = function ( state
) {
9026 this.readOnly
= !!state
;
9027 this.$input
.prop( 'readOnly', this.readOnly
);
9028 this.updateSearchIndicator();
9033 * Check if the input is {@link #required required}.
9037 OO
.ui
.TextInputWidget
.prototype.isRequired = function () {
9038 return this.required
;
9042 * Set the {@link #required required} state of the input.
9044 * @param {boolean} state Make input required
9047 OO
.ui
.TextInputWidget
.prototype.setRequired = function ( state
) {
9048 this.required
= !!state
;
9049 if ( this.required
) {
9051 .attr( 'required', 'required' )
9052 .attr( 'aria-required', 'true' );
9053 if ( this.getIndicator() === null ) {
9054 this.setIndicator( 'required' );
9058 .removeAttr( 'required' )
9059 .removeAttr( 'aria-required' );
9060 if ( this.getIndicator() === 'required' ) {
9061 this.setIndicator( null );
9064 this.updateSearchIndicator();
9069 * Support function for making #onElementAttach work across browsers.
9071 * This whole function could be replaced with one line of code using the DOMNodeInsertedIntoDocument
9072 * event, but it's not supported by Firefox and allegedly deprecated, so we only use it as fallback.
9074 * Due to MutationObserver performance woes, #onElementAttach is only somewhat reliably called the
9075 * first time that the element gets attached to the documented.
9077 OO
.ui
.TextInputWidget
.prototype.installParentChangeDetector = function () {
9078 var mutationObserver
, onRemove
, topmostNode
, fakeParentNode
,
9079 MutationObserver
= window
.MutationObserver
|| window
.WebKitMutationObserver
|| window
.MozMutationObserver
,
9082 if ( MutationObserver
) {
9083 // The new way. If only it wasn't so ugly.
9085 if ( this.isElementAttached() ) {
9086 // Widget is attached already, do nothing. This breaks the functionality of this function when
9087 // the widget is detached and reattached. Alas, doing this correctly with MutationObserver
9088 // would require observation of the whole document, which would hurt performance of other,
9089 // more important code.
9093 // Find topmost node in the tree
9094 topmostNode
= this.$element
[ 0 ];
9095 while ( topmostNode
.parentNode
) {
9096 topmostNode
= topmostNode
.parentNode
;
9099 // We have no way to detect the $element being attached somewhere without observing the entire
9100 // DOM with subtree modifications, which would hurt performance. So we cheat: we hook to the
9101 // parent node of $element, and instead detect when $element is removed from it (and thus
9102 // probably attached somewhere else). If there is no parent, we create a "fake" one. If it
9103 // doesn't get attached, we end up back here and create the parent.
9105 mutationObserver
= new MutationObserver( function ( mutations
) {
9106 var i
, j
, removedNodes
;
9107 for ( i
= 0; i
< mutations
.length
; i
++ ) {
9108 removedNodes
= mutations
[ i
].removedNodes
;
9109 for ( j
= 0; j
< removedNodes
.length
; j
++ ) {
9110 if ( removedNodes
[ j
] === topmostNode
) {
9111 setTimeout( onRemove
, 0 );
9118 onRemove = function () {
9119 // If the node was attached somewhere else, report it
9120 if ( widget
.isElementAttached() ) {
9121 widget
.onElementAttach();
9123 mutationObserver
.disconnect();
9124 widget
.installParentChangeDetector();
9127 // Create a fake parent and observe it
9128 fakeParentNode
= $( '<div>' ).append( topmostNode
)[ 0 ];
9129 mutationObserver
.observe( fakeParentNode
, { childList
: true } );
9131 // Using the DOMNodeInsertedIntoDocument event is much nicer and less magical, and works for
9132 // detachment and reattachment, but it's not supported by Firefox and allegedly deprecated.
9133 this.$element
.on( 'DOMNodeInsertedIntoDocument', this.onElementAttach
.bind( this ) );
9138 * Automatically adjust the size of the text input.
9140 * This only affects #multiline inputs that are {@link #autosize autosized}.
9145 OO
.ui
.TextInputWidget
.prototype.adjustSize = function () {
9146 var scrollHeight
, innerHeight
, outerHeight
, maxInnerHeight
, measurementError
,
9147 idealHeight
, newHeight
, scrollWidth
, property
;
9149 if ( this.isWaitingToBeAttached
) {
9150 // #onElementAttach will be called soon, which calls this method
9154 if ( this.multiline
&& this.$input
.val() !== this.valCache
) {
9155 if ( this.autosize
) {
9157 .val( this.$input
.val() )
9158 .attr( 'rows', this.minRows
)
9159 // Set inline height property to 0 to measure scroll height
9160 .css( 'height', 0 );
9162 this.$clone
.removeClass( 'oo-ui-element-hidden' );
9164 this.valCache
= this.$input
.val();
9166 scrollHeight
= this.$clone
[ 0 ].scrollHeight
;
9168 // Remove inline height property to measure natural heights
9169 this.$clone
.css( 'height', '' );
9170 innerHeight
= this.$clone
.innerHeight();
9171 outerHeight
= this.$clone
.outerHeight();
9173 // Measure max rows height
9175 .attr( 'rows', this.maxRows
)
9176 .css( 'height', 'auto' )
9178 maxInnerHeight
= this.$clone
.innerHeight();
9180 // Difference between reported innerHeight and scrollHeight with no scrollbars present.
9181 // This is sometimes non-zero on Blink-based browsers, depending on zoom level.
9182 measurementError
= maxInnerHeight
- this.$clone
[ 0 ].scrollHeight
;
9183 idealHeight
= Math
.min( maxInnerHeight
, scrollHeight
+ measurementError
);
9185 this.$clone
.addClass( 'oo-ui-element-hidden' );
9187 // Only apply inline height when expansion beyond natural height is needed
9188 // Use the difference between the inner and outer height as a buffer
9189 newHeight
= idealHeight
> innerHeight
? idealHeight
+ ( outerHeight
- innerHeight
) : '';
9190 if ( newHeight
!== this.styleHeight
) {
9191 this.$input
.css( 'height', newHeight
);
9192 this.styleHeight
= newHeight
;
9193 this.emit( 'resize' );
9196 scrollWidth
= this.$input
[ 0 ].offsetWidth
- this.$input
[ 0 ].clientWidth
;
9197 if ( scrollWidth
!== this.scrollWidth
) {
9198 property
= this.$element
.css( 'direction' ) === 'rtl' ? 'left' : 'right';
9200 this.$label
.css( { right
: '', left
: '' } );
9201 this.$indicator
.css( { right
: '', left
: '' } );
9203 if ( scrollWidth
) {
9204 this.$indicator
.css( property
, scrollWidth
);
9205 if ( this.labelPosition
=== 'after' ) {
9206 this.$label
.css( property
, scrollWidth
);
9210 this.scrollWidth
= scrollWidth
;
9211 this.positionLabel();
9221 OO
.ui
.TextInputWidget
.prototype.getInputElement = function ( config
) {
9222 if ( config
.multiline
) {
9223 return $( '<textarea>' );
9224 } else if ( this.getSaneType( config
) === 'number' ) {
9225 return $( '<input>' )
9226 .attr( 'step', 'any' )
9227 .attr( 'type', 'number' );
9229 return $( '<input>' ).attr( 'type', this.getSaneType( config
) );
9234 * Get sanitized value for 'type' for given config.
9236 * @param {Object} config Configuration options
9237 * @return {string|null}
9240 OO
.ui
.TextInputWidget
.prototype.getSaneType = function ( config
) {
9241 var allowedTypes
= [
9251 return allowedTypes
.indexOf( config
.type
) !== -1 ? config
.type
: 'text';
9255 * Check if the input supports multiple lines.
9259 OO
.ui
.TextInputWidget
.prototype.isMultiline = function () {
9260 return !!this.multiline
;
9264 * Check if the input automatically adjusts its size.
9268 OO
.ui
.TextInputWidget
.prototype.isAutosizing = function () {
9269 return !!this.autosize
;
9273 * Focus the input and select a specified range within the text.
9275 * @param {number} from Select from offset
9276 * @param {number} [to] Select to offset, defaults to from
9279 OO
.ui
.TextInputWidget
.prototype.selectRange = function ( from, to
) {
9280 var isBackwards
, start
, end
,
9281 input
= this.$input
[ 0 ];
9285 isBackwards
= to
< from;
9286 start
= isBackwards
? to
: from;
9287 end
= isBackwards
? from : to
;
9292 input
.setSelectionRange( start
, end
, isBackwards
? 'backward' : 'forward' );
9294 // IE throws an exception if you call setSelectionRange on a unattached DOM node.
9295 // Rather than expensively check if the input is attached every time, just check
9296 // if it was the cause of an error being thrown. If not, rethrow the error.
9297 if ( this.getElementDocument().body
.contains( input
) ) {
9305 * Get an object describing the current selection range in a directional manner
9307 * @return {Object} Object containing 'from' and 'to' offsets
9309 OO
.ui
.TextInputWidget
.prototype.getRange = function () {
9310 var input
= this.$input
[ 0 ],
9311 start
= input
.selectionStart
,
9312 end
= input
.selectionEnd
,
9313 isBackwards
= input
.selectionDirection
=== 'backward';
9316 from: isBackwards
? end
: start
,
9317 to
: isBackwards
? start
: end
9322 * Get the length of the text input value.
9324 * This could differ from the length of #getValue if the
9325 * value gets filtered
9327 * @return {number} Input length
9329 OO
.ui
.TextInputWidget
.prototype.getInputLength = function () {
9330 return this.$input
[ 0 ].value
.length
;
9334 * Focus the input and select the entire text.
9338 OO
.ui
.TextInputWidget
.prototype.select = function () {
9339 return this.selectRange( 0, this.getInputLength() );
9343 * Focus the input and move the cursor to the start.
9347 OO
.ui
.TextInputWidget
.prototype.moveCursorToStart = function () {
9348 return this.selectRange( 0 );
9352 * Focus the input and move the cursor to the end.
9356 OO
.ui
.TextInputWidget
.prototype.moveCursorToEnd = function () {
9357 return this.selectRange( this.getInputLength() );
9361 * Insert new content into the input.
9363 * @param {string} content Content to be inserted
9366 OO
.ui
.TextInputWidget
.prototype.insertContent = function ( content
) {
9368 range
= this.getRange(),
9369 value
= this.getValue();
9371 start
= Math
.min( range
.from, range
.to
);
9372 end
= Math
.max( range
.from, range
.to
);
9374 this.setValue( value
.slice( 0, start
) + content
+ value
.slice( end
) );
9375 this.selectRange( start
+ content
.length
);
9380 * Insert new content either side of a selection.
9382 * @param {string} pre Content to be inserted before the selection
9383 * @param {string} post Content to be inserted after the selection
9386 OO
.ui
.TextInputWidget
.prototype.encapsulateContent = function ( pre
, post
) {
9388 range
= this.getRange(),
9389 offset
= pre
.length
;
9391 start
= Math
.min( range
.from, range
.to
);
9392 end
= Math
.max( range
.from, range
.to
);
9394 this.selectRange( start
).insertContent( pre
);
9395 this.selectRange( offset
+ end
).insertContent( post
);
9397 this.selectRange( offset
+ start
, offset
+ end
);
9402 * Set the validation pattern.
9404 * The validation pattern is either a regular expression, a function, or the symbolic name of a
9405 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer' (the
9406 * value must contain only numbers).
9408 * @param {RegExp|Function|string|null} validate Regular expression, function, or the symbolic name
9409 * of a pattern (either ‘integer’ or ‘non-empty’) defined by the class.
9411 OO
.ui
.TextInputWidget
.prototype.setValidation = function ( validate
) {
9412 if ( validate
instanceof RegExp
|| validate
instanceof Function
) {
9413 this.validate
= validate
;
9415 this.validate
= this.constructor.static.validationPatterns
[ validate
] || /.*/;
9420 * Sets the 'invalid' flag appropriately.
9422 * @param {boolean} [isValid] Optionally override validation result
9424 OO
.ui
.TextInputWidget
.prototype.setValidityFlag = function ( isValid
) {
9426 setFlag = function ( valid
) {
9428 widget
.$input
.attr( 'aria-invalid', 'true' );
9430 widget
.$input
.removeAttr( 'aria-invalid' );
9432 widget
.setFlags( { invalid
: !valid
} );
9435 if ( isValid
!== undefined ) {
9438 this.getValidity().then( function () {
9447 * Get the validity of current value.
9449 * This method returns a promise that resolves if the value is valid and rejects if
9450 * it isn't. Uses the {@link #validate validation pattern} to check for validity.
9452 * @return {jQuery.Promise} A promise that resolves if the value is valid, rejects if not.
9454 OO
.ui
.TextInputWidget
.prototype.getValidity = function () {
9457 function rejectOrResolve( valid
) {
9459 return $.Deferred().resolve().promise();
9461 return $.Deferred().reject().promise();
9465 if ( this.validate
instanceof Function
) {
9466 result
= this.validate( this.getValue() );
9467 if ( result
&& $.isFunction( result
.promise
) ) {
9468 return result
.promise().then( function ( valid
) {
9469 return rejectOrResolve( valid
);
9472 return rejectOrResolve( result
);
9475 return rejectOrResolve( this.getValue().match( this.validate
) );
9480 * Set the position of the inline label relative to that of the value: `‘before’` or `‘after’`.
9482 * @param {string} labelPosition Label position, 'before' or 'after'
9485 OO
.ui
.TextInputWidget
.prototype.setLabelPosition = function ( labelPosition
) {
9486 this.labelPosition
= labelPosition
;
9488 // If there is no label and we only change the position, #updatePosition is a no-op,
9489 // but it takes really a lot of work to do nothing.
9490 this.updatePosition();
9496 * Update the position of the inline label.
9498 * This method is called by #setLabelPosition, and can also be called on its own if
9499 * something causes the label to be mispositioned.
9503 OO
.ui
.TextInputWidget
.prototype.updatePosition = function () {
9504 var after
= this.labelPosition
=== 'after';
9507 .toggleClass( 'oo-ui-textInputWidget-labelPosition-after', !!this.label
&& after
)
9508 .toggleClass( 'oo-ui-textInputWidget-labelPosition-before', !!this.label
&& !after
);
9510 this.valCache
= null;
9511 this.scrollWidth
= null;
9513 this.positionLabel();
9519 * Update the 'clear' indicator displayed on type: 'search' text fields, hiding it when the field is
9520 * already empty or when it's not editable.
9522 OO
.ui
.TextInputWidget
.prototype.updateSearchIndicator = function () {
9523 if ( this.type
=== 'search' ) {
9524 if ( this.getValue() === '' || this.isDisabled() || this.isReadOnly() ) {
9525 this.setIndicator( null );
9527 this.setIndicator( 'clear' );
9533 * Position the label by setting the correct padding on the input.
9538 OO
.ui
.TextInputWidget
.prototype.positionLabel = function () {
9539 var after
, rtl
, property
;
9541 if ( this.isWaitingToBeAttached
) {
9542 // #onElementAttach will be called soon, which calls this method
9548 // Clear old values if present
9550 'padding-right': '',
9555 this.$element
.append( this.$label
);
9557 this.$label
.detach();
9561 after
= this.labelPosition
=== 'after';
9562 rtl
= this.$element
.css( 'direction' ) === 'rtl';
9563 property
= after
=== rtl
? 'padding-left' : 'padding-right';
9565 this.$input
.css( property
, this.$label
.outerWidth( true ) + ( after
? this.scrollWidth
: 0 ) );
9573 OO
.ui
.TextInputWidget
.prototype.restorePreInfuseState = function ( state
) {
9574 OO
.ui
.TextInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
9575 if ( state
.scrollTop
!== undefined ) {
9576 this.$input
.scrollTop( state
.scrollTop
);
9582 * @extends OO.ui.TextInputWidget
9585 * @param {Object} [config] Configuration options
9587 OO
.ui
.SearchInputWidget
= function OoUiSearchInputWidget( config
) {
9588 config
= $.extend( {
9592 // Set type to text so that TextInputWidget doesn't
9593 // get stuck in an infinite loop.
9594 config
.type
= 'text';
9596 // Parent constructor
9597 OO
.ui
.SearchInputWidget
.parent
.call( this, config
);
9600 this.$element
.addClass( 'oo-ui-textInputWidget-type-search' );
9601 this.updateSearchIndicator();
9602 this.connect( this, {
9603 disable
: 'onDisable'
9609 OO
.inheritClass( OO
.ui
.SearchInputWidget
, OO
.ui
.TextInputWidget
);
9617 OO
.ui
.SearchInputWidget
.prototype.getInputElement = function () {
9618 return $( '<input>' ).attr( 'type', 'search' );
9624 OO
.ui
.SearchInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
9625 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
9626 // Clear the text field
9627 this.setValue( '' );
9628 this.$input
[ 0 ].focus();
9634 * Update the 'clear' indicator displayed on type: 'search' text
9635 * fields, hiding it when the field is already empty or when it's not
9638 OO
.ui
.SearchInputWidget
.prototype.updateSearchIndicator = function () {
9639 if ( this.getValue() === '' || this.isDisabled() || this.isReadOnly() ) {
9640 this.setIndicator( null );
9642 this.setIndicator( 'clear' );
9649 OO
.ui
.SearchInputWidget
.prototype.onChange = function () {
9650 OO
.ui
.SearchInputWidget
.parent
.prototype.onChange
.call( this );
9651 this.updateSearchIndicator();
9655 * Handle disable events.
9657 * @param {boolean} disabled Element is disabled
9660 OO
.ui
.SearchInputWidget
.prototype.onDisable = function () {
9661 this.updateSearchIndicator();
9667 OO
.ui
.SearchInputWidget
.prototype.setReadOnly = function ( state
) {
9668 OO
.ui
.SearchInputWidget
.parent
.prototype.setReadOnly
.call( this, state
);
9669 this.updateSearchIndicator();
9674 * ComboBoxInputWidgets combine a {@link OO.ui.TextInputWidget text input} (where a value
9675 * can be entered manually) and a {@link OO.ui.MenuSelectWidget menu of options} (from which
9676 * a value can be chosen instead). Users can choose options from the combo box in one of two ways:
9678 * - by typing a value in the text input field. If the value exactly matches the value of a menu
9679 * option, that option will appear to be selected.
9680 * - by choosing a value from the menu. The value of the chosen option will then appear in the text
9683 * This widget can be used inside an HTML form, such as a OO.ui.FormLayout.
9685 * For more information about menus and options, please see the [OOjs UI documentation on MediaWiki][1].
9688 * // Example: A ComboBoxInputWidget.
9689 * var comboBox = new OO.ui.ComboBoxInputWidget( {
9690 * label: 'ComboBoxInputWidget',
9691 * value: 'Option 1',
9694 * new OO.ui.MenuOptionWidget( {
9696 * label: 'Option One'
9698 * new OO.ui.MenuOptionWidget( {
9700 * label: 'Option Two'
9702 * new OO.ui.MenuOptionWidget( {
9704 * label: 'Option Three'
9706 * new OO.ui.MenuOptionWidget( {
9708 * label: 'Option Four'
9710 * new OO.ui.MenuOptionWidget( {
9712 * label: 'Option Five'
9717 * $( 'body' ).append( comboBox.$element );
9719 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
9722 * @extends OO.ui.TextInputWidget
9725 * @param {Object} [config] Configuration options
9726 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
9727 * @cfg {Object} [menu] Configuration options to pass to the {@link OO.ui.FloatingMenuSelectWidget menu select widget}.
9728 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
9729 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
9730 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
9732 OO
.ui
.ComboBoxInputWidget
= function OoUiComboBoxInputWidget( config
) {
9733 // Configuration initialization
9734 config
= $.extend( {
9738 // ComboBoxInputWidget shouldn't support multiline
9739 config
.multiline
= false;
9741 // Parent constructor
9742 OO
.ui
.ComboBoxInputWidget
.parent
.call( this, config
);
9745 this.$overlay
= config
.$overlay
|| this.$element
;
9746 this.dropdownButton
= new OO
.ui
.ButtonWidget( {
9747 classes
: [ 'oo-ui-comboBoxInputWidget-dropdownButton' ],
9749 disabled
: this.disabled
9751 this.menu
= new OO
.ui
.FloatingMenuSelectWidget( $.extend(
9755 $container
: this.$element
,
9756 disabled
: this.isDisabled()
9762 this.connect( this, {
9763 change
: 'onInputChange',
9764 enter
: 'onInputEnter'
9766 this.dropdownButton
.connect( this, {
9767 click
: 'onDropdownButtonClick'
9769 this.menu
.connect( this, {
9770 choose
: 'onMenuChoose',
9771 add
: 'onMenuItemsChange',
9772 remove
: 'onMenuItemsChange'
9778 'aria-autocomplete': 'list'
9780 // Do not override options set via config.menu.items
9781 if ( config
.options
!== undefined ) {
9782 this.setOptions( config
.options
);
9784 this.$field
= $( '<div>' )
9785 .addClass( 'oo-ui-comboBoxInputWidget-field' )
9786 .append( this.$input
, this.dropdownButton
.$element
);
9788 .addClass( 'oo-ui-comboBoxInputWidget' )
9789 .append( this.$field
);
9790 this.$overlay
.append( this.menu
.$element
);
9791 this.onMenuItemsChange();
9796 OO
.inheritClass( OO
.ui
.ComboBoxInputWidget
, OO
.ui
.TextInputWidget
);
9801 * Get the combobox's menu.
9803 * @return {OO.ui.FloatingMenuSelectWidget} Menu widget
9805 OO
.ui
.ComboBoxInputWidget
.prototype.getMenu = function () {
9810 * Get the combobox's text input widget.
9812 * @return {OO.ui.TextInputWidget} Text input widget
9814 OO
.ui
.ComboBoxInputWidget
.prototype.getInput = function () {
9819 * Handle input change events.
9822 * @param {string} value New value
9824 OO
.ui
.ComboBoxInputWidget
.prototype.onInputChange = function ( value
) {
9825 var match
= this.menu
.getItemFromData( value
);
9827 this.menu
.selectItem( match
);
9828 if ( this.menu
.getHighlightedItem() ) {
9829 this.menu
.highlightItem( match
);
9832 if ( !this.isDisabled() ) {
9833 this.menu
.toggle( true );
9838 * Handle input enter events.
9842 OO
.ui
.ComboBoxInputWidget
.prototype.onInputEnter = function () {
9843 if ( !this.isDisabled() ) {
9844 this.menu
.toggle( false );
9849 * Handle button click events.
9853 OO
.ui
.ComboBoxInputWidget
.prototype.onDropdownButtonClick = function () {
9855 this.$input
[ 0 ].focus();
9859 * Handle menu choose events.
9862 * @param {OO.ui.OptionWidget} item Chosen item
9864 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuChoose = function ( item
) {
9865 this.setValue( item
.getData() );
9869 * Handle menu item change events.
9873 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuItemsChange = function () {
9874 var match
= this.menu
.getItemFromData( this.getValue() );
9875 this.menu
.selectItem( match
);
9876 if ( this.menu
.getHighlightedItem() ) {
9877 this.menu
.highlightItem( match
);
9879 this.$element
.toggleClass( 'oo-ui-comboBoxInputWidget-empty', this.menu
.isEmpty() );
9885 OO
.ui
.ComboBoxInputWidget
.prototype.setDisabled = function ( disabled
) {
9887 OO
.ui
.ComboBoxInputWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
9889 if ( this.dropdownButton
) {
9890 this.dropdownButton
.setDisabled( this.isDisabled() );
9893 this.menu
.setDisabled( this.isDisabled() );
9900 * Set the options available for this input.
9902 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
9905 OO
.ui
.ComboBoxInputWidget
.prototype.setOptions = function ( options
) {
9908 .addItems( options
.map( function ( opt
) {
9909 return new OO
.ui
.MenuOptionWidget( {
9911 label
: opt
.label
!== undefined ? opt
.label
: opt
.data
9919 * FieldLayouts are used with OO.ui.FieldsetLayout. Each FieldLayout requires a field-widget,
9920 * which is a widget that is specified by reference before any optional configuration settings.
9922 * Field layouts can be configured with help text and/or labels. Labels are aligned in one of four ways:
9924 * - **left**: The label is placed before the field-widget and aligned with the left margin.
9925 * A left-alignment is used for forms with many fields.
9926 * - **right**: The label is placed before the field-widget and aligned to the right margin.
9927 * A right-alignment is used for long but familiar forms which users tab through,
9928 * verifying the current field with a quick glance at the label.
9929 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
9930 * that users fill out from top to bottom.
9931 * - **inline**: The label is placed after the field-widget and aligned to the left.
9932 * An inline-alignment is best used with checkboxes or radio buttons.
9934 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout.
9935 * Please see the [OOjs UI documentation on MediaWiki] [1] for examples and more information.
9937 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
9940 * @extends OO.ui.Layout
9941 * @mixins OO.ui.mixin.LabelElement
9942 * @mixins OO.ui.mixin.TitledElement
9945 * @param {OO.ui.Widget} fieldWidget Field widget
9946 * @param {Object} [config] Configuration options
9947 * @cfg {string} [align='left'] Alignment of the label: 'left', 'right', 'top' or 'inline'
9948 * @cfg {Array} [errors] Error messages about the widget, which will be displayed below the widget.
9949 * The array may contain strings or OO.ui.HtmlSnippet instances.
9950 * @cfg {Array} [notices] Notices about the widget, which will be displayed below the widget.
9951 * The array may contain strings or OO.ui.HtmlSnippet instances.
9952 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified, a "help" icon will appear
9953 * in the upper-right corner of the rendered field; clicking it will display the text in a popup.
9954 * For important messages, you are advised to use `notices`, as they are always shown.
9956 * @throws {Error} An error is thrown if no widget is specified
9958 OO
.ui
.FieldLayout
= function OoUiFieldLayout( fieldWidget
, config
) {
9961 // Allow passing positional parameters inside the config object
9962 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
9963 config
= fieldWidget
;
9964 fieldWidget
= config
.fieldWidget
;
9967 // Make sure we have required constructor arguments
9968 if ( fieldWidget
=== undefined ) {
9969 throw new Error( 'Widget not found' );
9972 hasInputWidget
= fieldWidget
.constructor.static.supportsSimpleLabel
;
9974 // Configuration initialization
9975 config
= $.extend( { align
: 'left' }, config
);
9977 // Parent constructor
9978 OO
.ui
.FieldLayout
.parent
.call( this, config
);
9980 // Mixin constructors
9981 OO
.ui
.mixin
.LabelElement
.call( this, config
);
9982 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
9985 this.fieldWidget
= fieldWidget
;
9988 this.$field
= $( '<div>' );
9989 this.$messages
= $( '<ul>' );
9990 this.$header
= $( '<div>' );
9991 this.$body
= $( '<' + ( hasInputWidget
? 'label' : 'div' ) + '>' );
9993 if ( config
.help
) {
9994 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
9998 classes
: [ 'oo-ui-fieldLayout-help' ],
10002 if ( config
.help
instanceof OO
.ui
.HtmlSnippet
) {
10003 this.popupButtonWidget
.getPopup().$body
.html( config
.help
.toString() );
10005 this.popupButtonWidget
.getPopup().$body
.text( config
.help
);
10007 this.$help
= this.popupButtonWidget
.$element
;
10009 this.$help
= $( [] );
10013 if ( hasInputWidget
) {
10014 this.$label
.on( 'click', this.onLabelClick
.bind( this ) );
10016 this.fieldWidget
.connect( this, { disable
: 'onFieldDisable' } );
10020 .addClass( 'oo-ui-fieldLayout' )
10021 .toggleClass( 'oo-ui-fieldLayout-disabled', this.fieldWidget
.isDisabled() )
10022 .append( this.$body
);
10023 this.$body
.addClass( 'oo-ui-fieldLayout-body' );
10024 this.$header
.addClass( 'oo-ui-fieldLayout-header' );
10025 this.$messages
.addClass( 'oo-ui-fieldLayout-messages' );
10027 .addClass( 'oo-ui-fieldLayout-field' )
10028 .append( this.fieldWidget
.$element
);
10030 this.setErrors( config
.errors
|| [] );
10031 this.setNotices( config
.notices
|| [] );
10032 this.setAlignment( config
.align
);
10037 OO
.inheritClass( OO
.ui
.FieldLayout
, OO
.ui
.Layout
);
10038 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.LabelElement
);
10039 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.TitledElement
);
10044 * Handle field disable events.
10047 * @param {boolean} value Field is disabled
10049 OO
.ui
.FieldLayout
.prototype.onFieldDisable = function ( value
) {
10050 this.$element
.toggleClass( 'oo-ui-fieldLayout-disabled', value
);
10054 * Handle label mouse click events.
10057 * @param {jQuery.Event} e Mouse click event
10059 OO
.ui
.FieldLayout
.prototype.onLabelClick = function () {
10060 this.fieldWidget
.simulateLabelClick();
10065 * Get the widget contained by the field.
10067 * @return {OO.ui.Widget} Field widget
10069 OO
.ui
.FieldLayout
.prototype.getField = function () {
10070 return this.fieldWidget
;
10075 * @param {string} kind 'error' or 'notice'
10076 * @param {string|OO.ui.HtmlSnippet} text
10079 OO
.ui
.FieldLayout
.prototype.makeMessage = function ( kind
, text
) {
10080 var $listItem
, $icon
, message
;
10081 $listItem
= $( '<li>' );
10082 if ( kind
=== 'error' ) {
10083 $icon
= new OO
.ui
.IconWidget( { icon
: 'alert', flags
: [ 'warning' ] } ).$element
;
10084 } else if ( kind
=== 'notice' ) {
10085 $icon
= new OO
.ui
.IconWidget( { icon
: 'info' } ).$element
;
10089 message
= new OO
.ui
.LabelWidget( { label
: text
} );
10091 .append( $icon
, message
.$element
)
10092 .addClass( 'oo-ui-fieldLayout-messages-' + kind
);
10097 * Set the field alignment mode.
10100 * @param {string} value Alignment mode, either 'left', 'right', 'top' or 'inline'
10103 OO
.ui
.FieldLayout
.prototype.setAlignment = function ( value
) {
10104 if ( value
!== this.align
) {
10105 // Default to 'left'
10106 if ( [ 'left', 'right', 'top', 'inline' ].indexOf( value
) === -1 ) {
10109 // Reorder elements
10110 if ( value
=== 'top' ) {
10111 this.$header
.append( this.$label
, this.$help
);
10112 this.$body
.append( this.$header
, this.$field
);
10113 } else if ( value
=== 'inline' ) {
10114 this.$header
.append( this.$label
, this.$help
);
10115 this.$body
.append( this.$field
, this.$header
);
10117 this.$header
.append( this.$label
);
10118 this.$body
.append( this.$header
, this.$help
, this.$field
);
10120 // Set classes. The following classes can be used here:
10121 // * oo-ui-fieldLayout-align-left
10122 // * oo-ui-fieldLayout-align-right
10123 // * oo-ui-fieldLayout-align-top
10124 // * oo-ui-fieldLayout-align-inline
10125 if ( this.align
) {
10126 this.$element
.removeClass( 'oo-ui-fieldLayout-align-' + this.align
);
10128 this.$element
.addClass( 'oo-ui-fieldLayout-align-' + value
);
10129 this.align
= value
;
10136 * Set the list of error messages.
10138 * @param {Array} errors Error messages about the widget, which will be displayed below the widget.
10139 * The array may contain strings or OO.ui.HtmlSnippet instances.
10142 OO
.ui
.FieldLayout
.prototype.setErrors = function ( errors
) {
10143 this.errors
= errors
.slice();
10144 this.updateMessages();
10149 * Set the list of notice messages.
10151 * @param {Array} notices Notices about the widget, which will be displayed below the widget.
10152 * The array may contain strings or OO.ui.HtmlSnippet instances.
10155 OO
.ui
.FieldLayout
.prototype.setNotices = function ( notices
) {
10156 this.notices
= notices
.slice();
10157 this.updateMessages();
10162 * Update the rendering of error and notice messages.
10166 OO
.ui
.FieldLayout
.prototype.updateMessages = function () {
10168 this.$messages
.empty();
10170 if ( this.errors
.length
|| this.notices
.length
) {
10171 this.$body
.after( this.$messages
);
10173 this.$messages
.remove();
10177 for ( i
= 0; i
< this.notices
.length
; i
++ ) {
10178 this.$messages
.append( this.makeMessage( 'notice', this.notices
[ i
] ) );
10180 for ( i
= 0; i
< this.errors
.length
; i
++ ) {
10181 this.$messages
.append( this.makeMessage( 'error', this.errors
[ i
] ) );
10186 * ActionFieldLayouts are used with OO.ui.FieldsetLayout. The layout consists of a field-widget, a button,
10187 * and an optional label and/or help text. The field-widget (e.g., a {@link OO.ui.TextInputWidget TextInputWidget}),
10188 * is required and is specified before any optional configuration settings.
10190 * Labels can be aligned in one of four ways:
10192 * - **left**: The label is placed before the field-widget and aligned with the left margin.
10193 * A left-alignment is used for forms with many fields.
10194 * - **right**: The label is placed before the field-widget and aligned to the right margin.
10195 * A right-alignment is used for long but familiar forms which users tab through,
10196 * verifying the current field with a quick glance at the label.
10197 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
10198 * that users fill out from top to bottom.
10199 * - **inline**: The label is placed after the field-widget and aligned to the left.
10200 * An inline-alignment is best used with checkboxes or radio buttons.
10202 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout when help
10203 * text is specified.
10206 * // Example of an ActionFieldLayout
10207 * var actionFieldLayout = new OO.ui.ActionFieldLayout(
10208 * new OO.ui.TextInputWidget( {
10209 * placeholder: 'Field widget'
10211 * new OO.ui.ButtonWidget( {
10215 * label: 'An ActionFieldLayout. This label is aligned top',
10217 * help: 'This is help text'
10221 * $( 'body' ).append( actionFieldLayout.$element );
10224 * @extends OO.ui.FieldLayout
10227 * @param {OO.ui.Widget} fieldWidget Field widget
10228 * @param {OO.ui.ButtonWidget} buttonWidget Button widget
10229 * @param {Object} config
10231 OO
.ui
.ActionFieldLayout
= function OoUiActionFieldLayout( fieldWidget
, buttonWidget
, config
) {
10232 // Allow passing positional parameters inside the config object
10233 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
10234 config
= fieldWidget
;
10235 fieldWidget
= config
.fieldWidget
;
10236 buttonWidget
= config
.buttonWidget
;
10239 // Parent constructor
10240 OO
.ui
.ActionFieldLayout
.parent
.call( this, fieldWidget
, config
);
10243 this.buttonWidget
= buttonWidget
;
10244 this.$button
= $( '<div>' );
10245 this.$input
= $( '<div>' );
10249 .addClass( 'oo-ui-actionFieldLayout' );
10251 .addClass( 'oo-ui-actionFieldLayout-button' )
10252 .append( this.buttonWidget
.$element
);
10254 .addClass( 'oo-ui-actionFieldLayout-input' )
10255 .append( this.fieldWidget
.$element
);
10257 .append( this.$input
, this.$button
);
10262 OO
.inheritClass( OO
.ui
.ActionFieldLayout
, OO
.ui
.FieldLayout
);
10265 * FieldsetLayouts are composed of one or more {@link OO.ui.FieldLayout FieldLayouts},
10266 * which each contain an individual widget and, optionally, a label. Each Fieldset can be
10267 * configured with a label as well. For more information and examples,
10268 * please see the [OOjs UI documentation on MediaWiki][1].
10271 * // Example of a fieldset layout
10272 * var input1 = new OO.ui.TextInputWidget( {
10273 * placeholder: 'A text input field'
10276 * var input2 = new OO.ui.TextInputWidget( {
10277 * placeholder: 'A text input field'
10280 * var fieldset = new OO.ui.FieldsetLayout( {
10281 * label: 'Example of a fieldset layout'
10284 * fieldset.addItems( [
10285 * new OO.ui.FieldLayout( input1, {
10286 * label: 'Field One'
10288 * new OO.ui.FieldLayout( input2, {
10289 * label: 'Field Two'
10292 * $( 'body' ).append( fieldset.$element );
10294 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
10297 * @extends OO.ui.Layout
10298 * @mixins OO.ui.mixin.IconElement
10299 * @mixins OO.ui.mixin.LabelElement
10300 * @mixins OO.ui.mixin.GroupElement
10303 * @param {Object} [config] Configuration options
10304 * @cfg {OO.ui.FieldLayout[]} [items] An array of fields to add to the fieldset. See OO.ui.FieldLayout for more information about fields.
10305 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified, a "help" icon will appear
10306 * in the upper-right corner of the rendered field; clicking it will display the text in a popup.
10307 * For important messages, you are advised to use `notices`, as they are always shown.
10309 OO
.ui
.FieldsetLayout
= function OoUiFieldsetLayout( config
) {
10310 // Configuration initialization
10311 config
= config
|| {};
10313 // Parent constructor
10314 OO
.ui
.FieldsetLayout
.parent
.call( this, config
);
10316 // Mixin constructors
10317 OO
.ui
.mixin
.IconElement
.call( this, config
);
10318 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, { $label
: $( '<div>' ) } ) );
10319 OO
.ui
.mixin
.GroupElement
.call( this, config
);
10322 this.$header
= $( '<div>' );
10323 if ( config
.help
) {
10324 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
10328 classes
: [ 'oo-ui-fieldsetLayout-help' ],
10332 if ( config
.help
instanceof OO
.ui
.HtmlSnippet
) {
10333 this.popupButtonWidget
.getPopup().$body
.html( config
.help
.toString() );
10335 this.popupButtonWidget
.getPopup().$body
.text( config
.help
);
10337 this.$help
= this.popupButtonWidget
.$element
;
10339 this.$help
= $( [] );
10344 .addClass( 'oo-ui-fieldsetLayout-header' )
10345 .append( this.$icon
, this.$label
, this.$help
);
10346 this.$group
.addClass( 'oo-ui-fieldsetLayout-group' );
10348 .addClass( 'oo-ui-fieldsetLayout' )
10349 .prepend( this.$header
, this.$group
);
10350 if ( Array
.isArray( config
.items
) ) {
10351 this.addItems( config
.items
);
10357 OO
.inheritClass( OO
.ui
.FieldsetLayout
, OO
.ui
.Layout
);
10358 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.IconElement
);
10359 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.LabelElement
);
10360 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.GroupElement
);
10362 /* Static Properties */
10364 OO
.ui
.FieldsetLayout
.static.tagName
= 'fieldset';
10367 * FormLayouts are used to wrap {@link OO.ui.FieldsetLayout FieldsetLayouts} when you intend to use browser-based
10368 * form submission for the fields instead of handling them in JavaScript. Form layouts can be configured with an
10369 * HTML form action, an encoding type, and a method using the #action, #enctype, and #method configs, respectively.
10370 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
10372 * Only widgets from the {@link OO.ui.InputWidget InputWidget} family support form submission. It
10373 * includes standard form elements like {@link OO.ui.CheckboxInputWidget checkboxes}, {@link
10374 * OO.ui.RadioInputWidget radio buttons} and {@link OO.ui.TextInputWidget text fields}, as well as
10375 * some fancier controls. Some controls have both regular and InputWidget variants, for example
10376 * OO.ui.DropdownWidget and OO.ui.DropdownInputWidget – only the latter support form submission and
10377 * often have simplified APIs to match the capabilities of HTML forms.
10378 * See the [OOjs UI Inputs documentation on MediaWiki] [2] for more information about InputWidgets.
10380 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Forms
10381 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
10384 * // Example of a form layout that wraps a fieldset layout
10385 * var input1 = new OO.ui.TextInputWidget( {
10386 * placeholder: 'Username'
10388 * var input2 = new OO.ui.TextInputWidget( {
10389 * placeholder: 'Password',
10392 * var submit = new OO.ui.ButtonInputWidget( {
10396 * var fieldset = new OO.ui.FieldsetLayout( {
10397 * label: 'A form layout'
10399 * fieldset.addItems( [
10400 * new OO.ui.FieldLayout( input1, {
10401 * label: 'Username',
10404 * new OO.ui.FieldLayout( input2, {
10405 * label: 'Password',
10408 * new OO.ui.FieldLayout( submit )
10410 * var form = new OO.ui.FormLayout( {
10411 * items: [ fieldset ],
10412 * action: '/api/formhandler',
10415 * $( 'body' ).append( form.$element );
10418 * @extends OO.ui.Layout
10419 * @mixins OO.ui.mixin.GroupElement
10422 * @param {Object} [config] Configuration options
10423 * @cfg {string} [method] HTML form `method` attribute
10424 * @cfg {string} [action] HTML form `action` attribute
10425 * @cfg {string} [enctype] HTML form `enctype` attribute
10426 * @cfg {OO.ui.FieldsetLayout[]} [items] Fieldset layouts to add to the form layout.
10428 OO
.ui
.FormLayout
= function OoUiFormLayout( config
) {
10431 // Configuration initialization
10432 config
= config
|| {};
10434 // Parent constructor
10435 OO
.ui
.FormLayout
.parent
.call( this, config
);
10437 // Mixin constructors
10438 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
10441 this.$element
.on( 'submit', this.onFormSubmit
.bind( this ) );
10443 // Make sure the action is safe
10444 action
= config
.action
;
10445 if ( action
!== undefined && !OO
.ui
.isSafeUrl( action
) ) {
10446 action
= './' + action
;
10451 .addClass( 'oo-ui-formLayout' )
10453 method
: config
.method
,
10455 enctype
: config
.enctype
10457 if ( Array
.isArray( config
.items
) ) {
10458 this.addItems( config
.items
);
10464 OO
.inheritClass( OO
.ui
.FormLayout
, OO
.ui
.Layout
);
10465 OO
.mixinClass( OO
.ui
.FormLayout
, OO
.ui
.mixin
.GroupElement
);
10470 * A 'submit' event is emitted when the form is submitted.
10475 /* Static Properties */
10477 OO
.ui
.FormLayout
.static.tagName
= 'form';
10482 * Handle form submit events.
10485 * @param {jQuery.Event} e Submit event
10488 OO
.ui
.FormLayout
.prototype.onFormSubmit = function () {
10489 if ( this.emit( 'submit' ) ) {
10495 * PanelLayouts expand to cover the entire area of their parent. They can be configured with scrolling, padding,
10496 * and a frame, and are often used together with {@link OO.ui.StackLayout StackLayouts}.
10499 * // Example of a panel layout
10500 * var panel = new OO.ui.PanelLayout( {
10504 * $content: $( '<p>A panel layout with padding and a frame.</p>' )
10506 * $( 'body' ).append( panel.$element );
10509 * @extends OO.ui.Layout
10512 * @param {Object} [config] Configuration options
10513 * @cfg {boolean} [scrollable=false] Allow vertical scrolling
10514 * @cfg {boolean} [padded=false] Add padding between the content and the edges of the panel.
10515 * @cfg {boolean} [expanded=true] Expand the panel to fill the entire parent element.
10516 * @cfg {boolean} [framed=false] Render the panel with a frame to visually separate it from outside content.
10518 OO
.ui
.PanelLayout
= function OoUiPanelLayout( config
) {
10519 // Configuration initialization
10520 config
= $.extend( {
10527 // Parent constructor
10528 OO
.ui
.PanelLayout
.parent
.call( this, config
);
10531 this.$element
.addClass( 'oo-ui-panelLayout' );
10532 if ( config
.scrollable
) {
10533 this.$element
.addClass( 'oo-ui-panelLayout-scrollable' );
10535 if ( config
.padded
) {
10536 this.$element
.addClass( 'oo-ui-panelLayout-padded' );
10538 if ( config
.expanded
) {
10539 this.$element
.addClass( 'oo-ui-panelLayout-expanded' );
10541 if ( config
.framed
) {
10542 this.$element
.addClass( 'oo-ui-panelLayout-framed' );
10548 OO
.inheritClass( OO
.ui
.PanelLayout
, OO
.ui
.Layout
);
10553 * Focus the panel layout
10555 * The default implementation just focuses the first focusable element in the panel
10557 OO
.ui
.PanelLayout
.prototype.focus = function () {
10558 OO
.ui
.findFocusable( this.$element
).focus();
10562 * HorizontalLayout arranges its contents in a single line (using `display: inline-block` for its
10563 * items), with small margins between them. Convenient when you need to put a number of block-level
10564 * widgets on a single line next to each other.
10566 * Note that inline elements, such as OO.ui.ButtonWidgets, do not need this wrapper.
10569 * // HorizontalLayout with a text input and a label
10570 * var layout = new OO.ui.HorizontalLayout( {
10572 * new OO.ui.LabelWidget( { label: 'Label' } ),
10573 * new OO.ui.TextInputWidget( { value: 'Text' } )
10576 * $( 'body' ).append( layout.$element );
10579 * @extends OO.ui.Layout
10580 * @mixins OO.ui.mixin.GroupElement
10583 * @param {Object} [config] Configuration options
10584 * @cfg {OO.ui.Widget[]|OO.ui.Layout[]} [items] Widgets or other layouts to add to the layout.
10586 OO
.ui
.HorizontalLayout
= function OoUiHorizontalLayout( config
) {
10587 // Configuration initialization
10588 config
= config
|| {};
10590 // Parent constructor
10591 OO
.ui
.HorizontalLayout
.parent
.call( this, config
);
10593 // Mixin constructors
10594 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
10597 this.$element
.addClass( 'oo-ui-horizontalLayout' );
10598 if ( Array
.isArray( config
.items
) ) {
10599 this.addItems( config
.items
);
10605 OO
.inheritClass( OO
.ui
.HorizontalLayout
, OO
.ui
.Layout
);
10606 OO
.mixinClass( OO
.ui
.HorizontalLayout
, OO
.ui
.mixin
.GroupElement
);