3 * https://www.mediawiki.org/wiki/OOjs_UI
5 * Copyright 2011–2016 OOjs UI Team and other contributors.
6 * Released under the MIT license
7 * http://oojs.mit-license.org
9 * Date: 2016-06-29T13:27:08Z
16 * Namespace for all classes, static methods and static properties.
48 * Constants for MouseEvent.which
52 OO
.ui
.MouseButtons
= {
64 * Generate a unique ID for element
66 * @return {string} [id]
68 OO
.ui
.generateElementId = function () {
70 return 'oojsui-' + OO
.ui
.elementId
;
74 * Check if an element is focusable.
75 * Inspired from :focusable in jQueryUI v1.11.4 - 2015-04-14
77 * @param {jQuery} $element Element to test
80 OO
.ui
.isFocusableElement = function ( $element
) {
82 element
= $element
[ 0 ];
84 // Anything disabled is not focusable
85 if ( element
.disabled
) {
89 // Check if the element is visible
91 // This is quicker than calling $element.is( ':visible' )
92 $.expr
.filters
.visible( element
) &&
93 // Check that all parents are visible
94 !$element
.parents().addBack().filter( function () {
95 return $.css( this, 'visibility' ) === 'hidden';
101 // Check if the element is ContentEditable, which is the string 'true'
102 if ( element
.contentEditable
=== 'true' ) {
106 // Anything with a non-negative numeric tabIndex is focusable.
107 // Use .prop to avoid browser bugs
108 if ( $element
.prop( 'tabIndex' ) >= 0 ) {
112 // Some element types are naturally focusable
113 // (indexOf is much faster than regex in Chrome and about the
114 // same in FF: https://jsperf.com/regex-vs-indexof-array2)
115 nodeName
= element
.nodeName
.toLowerCase();
116 if ( [ 'input', 'select', 'textarea', 'button', 'object' ].indexOf( nodeName
) !== -1 ) {
120 // Links and areas are focusable if they have an href
121 if ( ( nodeName
=== 'a' || nodeName
=== 'area' ) && $element
.attr( 'href' ) !== undefined ) {
129 * Find a focusable child
131 * @param {jQuery} $container Container to search in
132 * @param {boolean} [backwards] Search backwards
133 * @return {jQuery} Focusable child, an empty jQuery object if none found
135 OO
.ui
.findFocusable = function ( $container
, backwards
) {
136 var $focusable
= $( [] ),
137 // $focusableCandidates is a superset of things that
138 // could get matched by isFocusableElement
139 $focusableCandidates
= $container
140 .find( 'input, select, textarea, button, object, a, area, [contenteditable], [tabindex]' );
143 $focusableCandidates
= Array
.prototype.reverse
.call( $focusableCandidates
);
146 $focusableCandidates
.each( function () {
147 var $this = $( this );
148 if ( OO
.ui
.isFocusableElement( $this ) ) {
157 * Get the user's language and any fallback languages.
159 * These language codes are used to localize user interface elements in the user's language.
161 * In environments that provide a localization system, this function should be overridden to
162 * return the user's language(s). The default implementation returns English (en) only.
164 * @return {string[]} Language codes, in descending order of priority
166 OO
.ui
.getUserLanguages = function () {
171 * Get a value in an object keyed by language code.
173 * @param {Object.<string,Mixed>} obj Object keyed by language code
174 * @param {string|null} [lang] Language code, if omitted or null defaults to any user language
175 * @param {string} [fallback] Fallback code, used if no matching language can be found
176 * @return {Mixed} Local value
178 OO
.ui
.getLocalValue = function ( obj
, lang
, fallback
) {
181 // Requested language
185 // Known user language
186 langs
= OO
.ui
.getUserLanguages();
187 for ( i
= 0, len
= langs
.length
; i
< len
; i
++ ) {
194 if ( obj
[ fallback
] ) {
195 return obj
[ fallback
];
197 // First existing language
198 for ( lang
in obj
) {
206 * Check if a node is contained within another node
208 * Similar to jQuery#contains except a list of containers can be supplied
209 * and a boolean argument allows you to include the container in the match list
211 * @param {HTMLElement|HTMLElement[]} containers Container node(s) to search in
212 * @param {HTMLElement} contained Node to find
213 * @param {boolean} [matchContainers] Include the container(s) in the list of nodes to match, otherwise only match descendants
214 * @return {boolean} The node is in the list of target nodes
216 OO
.ui
.contains = function ( containers
, contained
, matchContainers
) {
218 if ( !Array
.isArray( containers
) ) {
219 containers
= [ containers
];
221 for ( i
= containers
.length
- 1; i
>= 0; i
-- ) {
222 if ( ( matchContainers
&& contained
=== containers
[ i
] ) || $.contains( containers
[ i
], contained
) ) {
230 * Return a function, that, as long as it continues to be invoked, will not
231 * be triggered. The function will be called after it stops being called for
232 * N milliseconds. If `immediate` is passed, trigger the function on the
233 * leading edge, instead of the trailing.
235 * Ported from: http://underscorejs.org/underscore.js
237 * @param {Function} func
238 * @param {number} wait
239 * @param {boolean} immediate
242 OO
.ui
.debounce = function ( func
, wait
, immediate
) {
247 later = function () {
250 func
.apply( context
, args
);
253 if ( immediate
&& !timeout
) {
254 func
.apply( context
, args
);
256 if ( !timeout
|| wait
) {
257 clearTimeout( timeout
);
258 timeout
= setTimeout( later
, wait
);
264 * Returns a function, that, when invoked, will only be triggered at most once
265 * during a given window of time. If called again during that window, it will
266 * wait until the window ends and then trigger itself again.
268 * As it's not knowable to the caller whether the function will actually run
269 * when the wrapper is called, return values from the function are entirely
272 * @param {Function} func
273 * @param {number} wait
276 OO
.ui
.throttle = function ( func
, wait
) {
277 var context
, args
, timeout
,
281 previous
= OO
.ui
.now();
282 func
.apply( context
, args
);
285 // Check how long it's been since the last time the function was
286 // called, and whether it's more or less than the requested throttle
287 // period. If it's less, run the function immediately. If it's more,
288 // set a timeout for the remaining time -- but don't replace an
289 // existing timeout, since that'd indefinitely prolong the wait.
290 var remaining
= wait
- ( OO
.ui
.now() - previous
);
293 if ( remaining
<= 0 ) {
294 // Note: unless wait was ridiculously large, this means we'll
295 // automatically run the first time the function was called in a
296 // given period. (If you provide a wait period larger than the
297 // current Unix timestamp, you *deserve* unexpected behavior.)
298 clearTimeout( timeout
);
300 } else if ( !timeout
) {
301 timeout
= setTimeout( run
, remaining
);
307 * A (possibly faster) way to get the current timestamp as an integer
309 * @return {number} Current timestamp
311 OO
.ui
.now
= Date
.now
|| function () {
312 return new Date().getTime();
316 * Proxy for `node.addEventListener( eventName, handler, true )`.
318 * @param {HTMLElement} node
319 * @param {string} eventName
320 * @param {Function} handler
321 * @deprecated since 0.15.0
323 OO
.ui
.addCaptureEventListener = function ( node
, eventName
, handler
) {
324 node
.addEventListener( eventName
, handler
, true );
328 * Proxy for `node.removeEventListener( eventName, handler, true )`.
330 * @param {HTMLElement} node
331 * @param {string} eventName
332 * @param {Function} handler
333 * @deprecated since 0.15.0
335 OO
.ui
.removeCaptureEventListener = function ( node
, eventName
, handler
) {
336 node
.removeEventListener( eventName
, handler
, true );
340 * Reconstitute a JavaScript object corresponding to a widget created by
341 * the PHP implementation.
343 * This is an alias for `OO.ui.Element.static.infuse()`.
345 * @param {string|HTMLElement|jQuery} idOrNode
346 * A DOM id (if a string) or node for the widget to infuse.
347 * @return {OO.ui.Element}
348 * The `OO.ui.Element` corresponding to this (infusable) document node.
350 OO
.ui
.infuse = function ( idOrNode
) {
351 return OO
.ui
.Element
.static.infuse( idOrNode
);
356 * Message store for the default implementation of OO.ui.msg
358 * Environments that provide a localization system should not use this, but should override
359 * OO.ui.msg altogether.
364 // Tool tip for a button that moves items in a list down one place
365 'ooui-outline-control-move-down': 'Move item down',
366 // Tool tip for a button that moves items in a list up one place
367 'ooui-outline-control-move-up': 'Move item up',
368 // Tool tip for a button that removes items from a list
369 'ooui-outline-control-remove': 'Remove item',
370 // Label for the toolbar group that contains a list of all other available tools
371 'ooui-toolbar-more': 'More',
372 // Label for the fake tool that expands the full list of tools in a toolbar group
373 'ooui-toolgroup-expand': 'More',
374 // Label for the fake tool that collapses the full list of tools in a toolbar group
375 'ooui-toolgroup-collapse': 'Fewer',
376 // Default label for the accept button of a confirmation dialog
377 'ooui-dialog-message-accept': 'OK',
378 // Default label for the reject button of a confirmation dialog
379 'ooui-dialog-message-reject': 'Cancel',
380 // Title for process dialog error description
381 'ooui-dialog-process-error': 'Something went wrong',
382 // Label for process dialog dismiss error button, visible when describing errors
383 'ooui-dialog-process-dismiss': 'Dismiss',
384 // Label for process dialog retry action button, visible when describing only recoverable errors
385 'ooui-dialog-process-retry': 'Try again',
386 // Label for process dialog retry action button, visible when describing only warnings
387 'ooui-dialog-process-continue': 'Continue',
388 // Label for the file selection widget's select file button
389 'ooui-selectfile-button-select': 'Select a file',
390 // Label for the file selection widget if file selection is not supported
391 'ooui-selectfile-not-supported': 'File selection is not supported',
392 // Label for the file selection widget when no file is currently selected
393 'ooui-selectfile-placeholder': 'No file is selected',
394 // Label for the file selection widget's drop target
395 'ooui-selectfile-dragdrop-placeholder': 'Drop file here'
399 * Get a localized message.
401 * In environments that provide a localization system, this function should be overridden to
402 * return the message translated in the user's language. The default implementation always returns
405 * After the message key, message parameters may optionally be passed. In the default implementation,
406 * any occurrences of $1 are replaced with the first parameter, $2 with the second parameter, etc.
407 * Alternative implementations of OO.ui.msg may use any substitution system they like, as long as
408 * they support unnamed, ordered message parameters.
410 * @param {string} key Message key
411 * @param {...Mixed} [params] Message parameters
412 * @return {string} Translated message with parameters substituted
414 OO
.ui
.msg = function ( key
) {
415 var message
= messages
[ key
],
416 params
= Array
.prototype.slice
.call( arguments
, 1 );
417 if ( typeof message
=== 'string' ) {
418 // Perform $1 substitution
419 message
= message
.replace( /\$(\d+)/g, function ( unused
, n
) {
420 var i
= parseInt( n
, 10 );
421 return params
[ i
- 1 ] !== undefined ? params
[ i
- 1 ] : '$' + n
;
424 // Return placeholder if message not found
425 message
= '[' + key
+ ']';
432 * Package a message and arguments for deferred resolution.
434 * Use this when you are statically specifying a message and the message may not yet be present.
436 * @param {string} key Message key
437 * @param {...Mixed} [params] Message parameters
438 * @return {Function} Function that returns the resolved message when executed
440 OO
.ui
.deferMsg = function () {
441 var args
= arguments
;
443 return OO
.ui
.msg
.apply( OO
.ui
, args
);
450 * If the message is a function it will be executed, otherwise it will pass through directly.
452 * @param {Function|string} msg Deferred message, or message text
453 * @return {string} Resolved message
455 OO
.ui
.resolveMsg = function ( msg
) {
456 if ( $.isFunction( msg
) ) {
463 * @param {string} url
466 OO
.ui
.isSafeUrl = function ( url
) {
467 // Keep this function in sync with php/Tag.php
468 var i
, protocolWhitelist
;
470 function stringStartsWith( haystack
, needle
) {
471 return haystack
.substr( 0, needle
.length
) === needle
;
474 protocolWhitelist
= [
475 'bitcoin', 'ftp', 'ftps', 'geo', 'git', 'gopher', 'http', 'https', 'irc', 'ircs',
476 'magnet', 'mailto', 'mms', 'news', 'nntp', 'redis', 'sftp', 'sip', 'sips', 'sms', 'ssh',
477 'svn', 'tel', 'telnet', 'urn', 'worldwind', 'xmpp'
484 for ( i
= 0; i
< protocolWhitelist
.length
; i
++ ) {
485 if ( stringStartsWith( url
, protocolWhitelist
[ i
] + ':' ) ) {
490 // This matches '//' too
491 if ( stringStartsWith( url
, '/' ) || stringStartsWith( url
, './' ) ) {
494 if ( stringStartsWith( url
, '?' ) || stringStartsWith( url
, '#' ) ) {
506 * Namespace for OOjs UI mixins.
508 * Mixins are named according to the type of object they are intended to
509 * be mixed in to. For example, OO.ui.mixin.GroupElement is intended to be
510 * mixed in to an instance of OO.ui.Element, and OO.ui.mixin.GroupWidget
511 * is intended to be mixed in to an instance of OO.ui.Widget.
519 * Each Element represents a rendering in the DOM—a button or an icon, for example, or anything
520 * that is visible to a user. Unlike {@link OO.ui.Widget widgets}, plain elements usually do not have events
521 * connected to them and can't be interacted with.
527 * @param {Object} [config] Configuration options
528 * @cfg {string[]} [classes] The names of the CSS classes to apply to the element. CSS styles are added
529 * to the top level (e.g., the outermost div) of the element. See the [OOjs UI documentation on MediaWiki][2]
531 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#cssExample
532 * @cfg {string} [id] The HTML id attribute used in the rendered tag.
533 * @cfg {string} [text] Text to insert
534 * @cfg {Array} [content] An array of content elements to append (after #text).
535 * Strings will be html-escaped; use an OO.ui.HtmlSnippet to append raw HTML.
536 * Instances of OO.ui.Element will have their $element appended.
537 * @cfg {jQuery} [$content] Content elements to append (after #text).
538 * @cfg {jQuery} [$element] Wrapper element. Defaults to a new element with #getTagName.
539 * @cfg {Mixed} [data] Custom data of any type or combination of types (e.g., string, number, array, object).
540 * Data can also be specified with the #setData method.
542 OO
.ui
.Element
= function OoUiElement( config
) {
543 // Configuration initialization
544 config
= config
|| {};
549 this.data
= config
.data
;
550 this.$element
= config
.$element
||
551 $( document
.createElement( this.getTagName() ) );
552 this.elementGroup
= null;
553 this.debouncedUpdateThemeClassesHandler
= OO
.ui
.debounce( this.debouncedUpdateThemeClasses
);
556 if ( Array
.isArray( config
.classes
) ) {
557 this.$element
.addClass( config
.classes
.join( ' ' ) );
560 this.$element
.attr( 'id', config
.id
);
563 this.$element
.text( config
.text
);
565 if ( config
.content
) {
566 // The `content` property treats plain strings as text; use an
567 // HtmlSnippet to append HTML content. `OO.ui.Element`s get their
568 // appropriate $element appended.
569 this.$element
.append( config
.content
.map( function ( v
) {
570 if ( typeof v
=== 'string' ) {
571 // Escape string so it is properly represented in HTML.
572 return document
.createTextNode( v
);
573 } else if ( v
instanceof OO
.ui
.HtmlSnippet
) {
576 } else if ( v
instanceof OO
.ui
.Element
) {
582 if ( config
.$content
) {
583 // The `$content` property treats plain strings as HTML.
584 this.$element
.append( config
.$content
);
590 OO
.initClass( OO
.ui
.Element
);
592 /* Static Properties */
595 * The name of the HTML tag used by the element.
597 * The static value may be ignored if the #getTagName method is overridden.
603 OO
.ui
.Element
.static.tagName
= 'div';
608 * Reconstitute a JavaScript object corresponding to a widget created
609 * by the PHP implementation.
611 * @param {string|HTMLElement|jQuery} idOrNode
612 * A DOM id (if a string) or node for the widget to infuse.
613 * @return {OO.ui.Element}
614 * The `OO.ui.Element` corresponding to this (infusable) document node.
615 * For `Tag` objects emitted on the HTML side (used occasionally for content)
616 * the value returned is a newly-created Element wrapping around the existing
619 OO
.ui
.Element
.static.infuse = function ( idOrNode
) {
620 var obj
= OO
.ui
.Element
.static.unsafeInfuse( idOrNode
, false );
621 // Verify that the type matches up.
622 // FIXME: uncomment after T89721 is fixed (see T90929)
624 if ( !( obj instanceof this['class'] ) ) {
625 throw new Error( 'Infusion type mismatch!' );
632 * Implementation helper for `infuse`; skips the type check and has an
633 * extra property so that only the top-level invocation touches the DOM.
636 * @param {string|HTMLElement|jQuery} idOrNode
637 * @param {jQuery.Promise|boolean} domPromise A promise that will be resolved
638 * when the top-level widget of this infusion is inserted into DOM,
639 * replacing the original node; or false for top-level invocation.
640 * @return {OO.ui.Element}
642 OO
.ui
.Element
.static.unsafeInfuse = function ( idOrNode
, domPromise
) {
643 // look for a cached result of a previous infusion.
644 var id
, $elem
, data
, cls
, parts
, parent
, obj
, top
, state
, infusedChildren
;
645 if ( typeof idOrNode
=== 'string' ) {
647 $elem
= $( document
.getElementById( id
) );
649 $elem
= $( idOrNode
);
650 id
= $elem
.attr( 'id' );
652 if ( !$elem
.length
) {
653 throw new Error( 'Widget not found: ' + id
);
655 if ( $elem
[ 0 ].oouiInfused
) {
656 $elem
= $elem
[ 0 ].oouiInfused
;
658 data
= $elem
.data( 'ooui-infused' );
661 if ( data
=== true ) {
662 throw new Error( 'Circular dependency! ' + id
);
665 // pick up dynamic state, like focus, value of form inputs, scroll position, etc.
666 state
= data
.constructor.static.gatherPreInfuseState( $elem
, data
);
667 // restore dynamic state after the new element is re-inserted into DOM under infused parent
668 domPromise
.done( data
.restorePreInfuseState
.bind( data
, state
) );
669 infusedChildren
= $elem
.data( 'ooui-infused-children' );
670 if ( infusedChildren
&& infusedChildren
.length
) {
671 infusedChildren
.forEach( function ( data
) {
672 var state
= data
.constructor.static.gatherPreInfuseState( $elem
, data
);
673 domPromise
.done( data
.restorePreInfuseState
.bind( data
, state
) );
679 data
= $elem
.attr( 'data-ooui' );
681 throw new Error( 'No infusion data found: ' + id
);
684 data
= $.parseJSON( data
);
688 if ( !( data
&& data
._
) ) {
689 throw new Error( 'No valid infusion data found: ' + id
);
691 if ( data
._
=== 'Tag' ) {
692 // Special case: this is a raw Tag; wrap existing node, don't rebuild.
693 return new OO
.ui
.Element( { $element
: $elem
} );
695 parts
= data
._
.split( '.' );
696 cls
= OO
.getProp
.apply( OO
, [ window
].concat( parts
) );
697 if ( cls
=== undefined ) {
698 // The PHP output might be old and not including the "OO.ui" prefix
699 // TODO: Remove this back-compat after next major release
700 cls
= OO
.getProp
.apply( OO
, [ OO
.ui
].concat( parts
) );
701 if ( cls
=== undefined ) {
702 throw new Error( 'Unknown widget type: id: ' + id
+ ', class: ' + data
._
);
706 // Verify that we're creating an OO.ui.Element instance
709 while ( parent
!== undefined ) {
710 if ( parent
=== OO
.ui
.Element
) {
715 parent
= parent
.parent
;
718 if ( parent
!== OO
.ui
.Element
) {
719 throw new Error( 'Unknown widget type: id: ' + id
+ ', class: ' + data
._
);
722 if ( domPromise
=== false ) {
724 domPromise
= top
.promise();
726 $elem
.data( 'ooui-infused', true ); // prevent loops
727 data
.id
= id
; // implicit
728 infusedChildren
= [];
729 data
= OO
.copy( data
, null, function deserialize( value
) {
731 if ( OO
.isPlainObject( value
) ) {
733 infused
= OO
.ui
.Element
.static.unsafeInfuse( value
.tag
, domPromise
);
734 infusedChildren
.push( infused
);
735 // Flatten the structure
736 infusedChildren
.push
.apply( infusedChildren
, infused
.$element
.data( 'ooui-infused-children' ) || [] );
737 infused
.$element
.removeData( 'ooui-infused-children' );
740 if ( value
.html
!== undefined ) {
741 return new OO
.ui
.HtmlSnippet( value
.html
);
745 // allow widgets to reuse parts of the DOM
746 data
= cls
.static.reusePreInfuseDOM( $elem
[ 0 ], data
);
747 // pick up dynamic state, like focus, value of form inputs, scroll position, etc.
748 state
= cls
.static.gatherPreInfuseState( $elem
[ 0 ], data
);
750 // jscs:disable requireCapitalizedConstructors
751 obj
= new cls( data
);
752 // jscs:enable requireCapitalizedConstructors
753 // now replace old DOM with this new DOM.
755 // An efficient constructor might be able to reuse the entire DOM tree of the original element,
756 // so only mutate the DOM if we need to.
757 if ( $elem
[ 0 ] !== obj
.$element
[ 0 ] ) {
758 $elem
.replaceWith( obj
.$element
);
759 // This element is now gone from the DOM, but if anyone is holding a reference to it,
760 // let's allow them to OO.ui.infuse() it and do what they expect (T105828).
761 // Do not use jQuery.data(), as using it on detached nodes leaks memory in 1.x line by design.
762 $elem
[ 0 ].oouiInfused
= obj
.$element
;
766 obj
.$element
.data( 'ooui-infused', obj
);
767 obj
.$element
.data( 'ooui-infused-children', infusedChildren
);
768 // set the 'data-ooui' attribute so we can identify infused widgets
769 obj
.$element
.attr( 'data-ooui', '' );
770 // restore dynamic state after the new element is inserted into DOM
771 domPromise
.done( obj
.restorePreInfuseState
.bind( obj
, state
) );
776 * Pick out parts of `node`'s DOM to be reused when infusing a widget.
778 * This method **must not** make any changes to the DOM, only find interesting pieces and add them
779 * to `config` (which should then be returned). Actual DOM juggling should then be done by the
780 * constructor, which will be given the enhanced config.
783 * @param {HTMLElement} node
784 * @param {Object} config
787 OO
.ui
.Element
.static.reusePreInfuseDOM = function ( node
, config
) {
792 * Gather the dynamic state (focus, value of form inputs, scroll position, etc.) of a HTML DOM node
793 * (and its children) that represent an Element of the same class and the given configuration,
794 * generated by the PHP implementation.
796 * This method is called just before `node` is detached from the DOM. The return value of this
797 * function will be passed to #restorePreInfuseState after the newly created widget's #$element
798 * is inserted into DOM to replace `node`.
801 * @param {HTMLElement} node
802 * @param {Object} config
805 OO
.ui
.Element
.static.gatherPreInfuseState = function () {
810 * Get a jQuery function within a specific document.
813 * @param {jQuery|HTMLElement|HTMLDocument|Window} context Context to bind the function to
814 * @param {jQuery} [$iframe] HTML iframe element that contains the document, omit if document is
816 * @return {Function} Bound jQuery function
818 OO
.ui
.Element
.static.getJQuery = function ( context
, $iframe
) {
819 function wrapper( selector
) {
820 return $( selector
, wrapper
.context
);
823 wrapper
.context
= this.getDocument( context
);
826 wrapper
.$iframe
= $iframe
;
833 * Get the document of an element.
836 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Object to get the document for
837 * @return {HTMLDocument|null} Document object
839 OO
.ui
.Element
.static.getDocument = function ( obj
) {
840 // jQuery - selections created "offscreen" won't have a context, so .context isn't reliable
841 return ( obj
[ 0 ] && obj
[ 0 ].ownerDocument
) ||
842 // Empty jQuery selections might have a context
849 ( obj
.nodeType
=== 9 && obj
) ||
854 * Get the window of an element or document.
857 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the window for
858 * @return {Window} Window object
860 OO
.ui
.Element
.static.getWindow = function ( obj
) {
861 var doc
= this.getDocument( obj
);
862 return doc
.defaultView
;
866 * Get the direction of an element or document.
869 * @param {jQuery|HTMLElement|HTMLDocument|Window} obj Context to get the direction for
870 * @return {string} Text direction, either 'ltr' or 'rtl'
872 OO
.ui
.Element
.static.getDir = function ( obj
) {
875 if ( obj
instanceof jQuery
) {
878 isDoc
= obj
.nodeType
=== 9;
879 isWin
= obj
.document
!== undefined;
880 if ( isDoc
|| isWin
) {
886 return $( obj
).css( 'direction' );
890 * Get the offset between two frames.
892 * TODO: Make this function not use recursion.
895 * @param {Window} from Window of the child frame
896 * @param {Window} [to=window] Window of the parent frame
897 * @param {Object} [offset] Offset to start with, used internally
898 * @return {Object} Offset object, containing left and top properties
900 OO
.ui
.Element
.static.getFrameOffset = function ( from, to
, offset
) {
901 var i
, len
, frames
, frame
, rect
;
907 offset
= { top
: 0, left
: 0 };
909 if ( from.parent
=== from ) {
913 // Get iframe element
914 frames
= from.parent
.document
.getElementsByTagName( 'iframe' );
915 for ( i
= 0, len
= frames
.length
; i
< len
; i
++ ) {
916 if ( frames
[ i
].contentWindow
=== from ) {
922 // Recursively accumulate offset values
924 rect
= frame
.getBoundingClientRect();
925 offset
.left
+= rect
.left
;
926 offset
.top
+= rect
.top
;
928 this.getFrameOffset( from.parent
, offset
);
935 * Get the offset between two elements.
937 * The two elements may be in a different frame, but in that case the frame $element is in must
938 * be contained in the frame $anchor is in.
941 * @param {jQuery} $element Element whose position to get
942 * @param {jQuery} $anchor Element to get $element's position relative to
943 * @return {Object} Translated position coordinates, containing top and left properties
945 OO
.ui
.Element
.static.getRelativePosition = function ( $element
, $anchor
) {
946 var iframe
, iframePos
,
947 pos
= $element
.offset(),
948 anchorPos
= $anchor
.offset(),
949 elementDocument
= this.getDocument( $element
),
950 anchorDocument
= this.getDocument( $anchor
);
952 // If $element isn't in the same document as $anchor, traverse up
953 while ( elementDocument
!== anchorDocument
) {
954 iframe
= elementDocument
.defaultView
.frameElement
;
956 throw new Error( '$element frame is not contained in $anchor frame' );
958 iframePos
= $( iframe
).offset();
959 pos
.left
+= iframePos
.left
;
960 pos
.top
+= iframePos
.top
;
961 elementDocument
= iframe
.ownerDocument
;
963 pos
.left
-= anchorPos
.left
;
964 pos
.top
-= anchorPos
.top
;
969 * Get element border sizes.
972 * @param {HTMLElement} el Element to measure
973 * @return {Object} Dimensions object with `top`, `left`, `bottom` and `right` properties
975 OO
.ui
.Element
.static.getBorders = function ( el
) {
976 var doc
= el
.ownerDocument
,
977 win
= doc
.defaultView
,
978 style
= win
.getComputedStyle( el
, null ),
980 top
= parseFloat( style
? style
.borderTopWidth
: $el
.css( 'borderTopWidth' ) ) || 0,
981 left
= parseFloat( style
? style
.borderLeftWidth
: $el
.css( 'borderLeftWidth' ) ) || 0,
982 bottom
= parseFloat( style
? style
.borderBottomWidth
: $el
.css( 'borderBottomWidth' ) ) || 0,
983 right
= parseFloat( style
? style
.borderRightWidth
: $el
.css( 'borderRightWidth' ) ) || 0;
994 * Get dimensions of an element or window.
997 * @param {HTMLElement|Window} el Element to measure
998 * @return {Object} Dimensions object with `borders`, `scroll`, `scrollbar` and `rect` properties
1000 OO
.ui
.Element
.static.getDimensions = function ( el
) {
1002 doc
= el
.ownerDocument
|| el
.document
,
1003 win
= doc
.defaultView
;
1005 if ( win
=== el
|| el
=== doc
.documentElement
) {
1008 borders
: { top
: 0, left
: 0, bottom
: 0, right
: 0 },
1010 top
: $win
.scrollTop(),
1011 left
: $win
.scrollLeft()
1013 scrollbar
: { right
: 0, bottom
: 0 },
1017 bottom
: $win
.innerHeight(),
1018 right
: $win
.innerWidth()
1024 borders
: this.getBorders( el
),
1026 top
: $el
.scrollTop(),
1027 left
: $el
.scrollLeft()
1030 right
: $el
.innerWidth() - el
.clientWidth
,
1031 bottom
: $el
.innerHeight() - el
.clientHeight
1033 rect
: el
.getBoundingClientRect()
1039 * Get scrollable object parent
1041 * documentElement can't be used to get or set the scrollTop
1042 * property on Blink. Changing and testing its value lets us
1043 * use 'body' or 'documentElement' based on what is working.
1045 * https://code.google.com/p/chromium/issues/detail?id=303131
1048 * @param {HTMLElement} el Element to find scrollable parent for
1049 * @return {HTMLElement} Scrollable parent
1051 OO
.ui
.Element
.static.getRootScrollableElement = function ( el
) {
1052 var scrollTop
, body
;
1054 if ( OO
.ui
.scrollableElement
=== undefined ) {
1055 body
= el
.ownerDocument
.body
;
1056 scrollTop
= body
.scrollTop
;
1059 if ( body
.scrollTop
=== 1 ) {
1060 body
.scrollTop
= scrollTop
;
1061 OO
.ui
.scrollableElement
= 'body';
1063 OO
.ui
.scrollableElement
= 'documentElement';
1067 return el
.ownerDocument
[ OO
.ui
.scrollableElement
];
1071 * Get closest scrollable container.
1073 * Traverses up until either a scrollable element or the root is reached, in which case the window
1077 * @param {HTMLElement} el Element to find scrollable container for
1078 * @param {string} [dimension] Dimension of scrolling to look for; `x`, `y` or omit for either
1079 * @return {HTMLElement} Closest scrollable container
1081 OO
.ui
.Element
.static.getClosestScrollableContainer = function ( el
, dimension
) {
1083 // props = [ 'overflow' ] doesn't work due to https://bugzilla.mozilla.org/show_bug.cgi?id=889091
1084 props
= [ 'overflow-x', 'overflow-y' ],
1085 $parent
= $( el
).parent();
1087 if ( dimension
=== 'x' || dimension
=== 'y' ) {
1088 props
= [ 'overflow-' + dimension
];
1091 while ( $parent
.length
) {
1092 if ( $parent
[ 0 ] === this.getRootScrollableElement( el
) ) {
1093 return $parent
[ 0 ];
1097 val
= $parent
.css( props
[ i
] );
1098 if ( val
=== 'auto' || val
=== 'scroll' ) {
1099 return $parent
[ 0 ];
1102 $parent
= $parent
.parent();
1104 return this.getDocument( el
).body
;
1108 * Scroll element into view.
1111 * @param {HTMLElement} el Element to scroll into view
1112 * @param {Object} [config] Configuration options
1113 * @param {string} [config.duration='fast'] jQuery animation duration value
1114 * @param {string} [config.direction] Scroll in only one direction, e.g. 'x' or 'y', omit
1115 * to scroll in both directions
1116 * @param {Function} [config.complete] Function to call when scrolling completes.
1117 * Deprecated since 0.15.4, use the return promise instead.
1118 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1120 OO
.ui
.Element
.static.scrollIntoView = function ( el
, config
) {
1121 var position
, animations
, callback
, container
, $container
, elementDimensions
, containerDimensions
, $window
,
1122 deferred
= $.Deferred();
1124 // Configuration initialization
1125 config
= config
|| {};
1128 callback
= typeof config
.complete
=== 'function' && config
.complete
;
1129 container
= this.getClosestScrollableContainer( el
, config
.direction
);
1130 $container
= $( container
);
1131 elementDimensions
= this.getDimensions( el
);
1132 containerDimensions
= this.getDimensions( container
);
1133 $window
= $( this.getWindow( el
) );
1135 // Compute the element's position relative to the container
1136 if ( $container
.is( 'html, body' ) ) {
1137 // If the scrollable container is the root, this is easy
1139 top
: elementDimensions
.rect
.top
,
1140 bottom
: $window
.innerHeight() - elementDimensions
.rect
.bottom
,
1141 left
: elementDimensions
.rect
.left
,
1142 right
: $window
.innerWidth() - elementDimensions
.rect
.right
1145 // Otherwise, we have to subtract el's coordinates from container's coordinates
1147 top
: elementDimensions
.rect
.top
- ( containerDimensions
.rect
.top
+ containerDimensions
.borders
.top
),
1148 bottom
: containerDimensions
.rect
.bottom
- containerDimensions
.borders
.bottom
- containerDimensions
.scrollbar
.bottom
- elementDimensions
.rect
.bottom
,
1149 left
: elementDimensions
.rect
.left
- ( containerDimensions
.rect
.left
+ containerDimensions
.borders
.left
),
1150 right
: containerDimensions
.rect
.right
- containerDimensions
.borders
.right
- containerDimensions
.scrollbar
.right
- elementDimensions
.rect
.right
1154 if ( !config
.direction
|| config
.direction
=== 'y' ) {
1155 if ( position
.top
< 0 ) {
1156 animations
.scrollTop
= containerDimensions
.scroll
.top
+ position
.top
;
1157 } else if ( position
.top
> 0 && position
.bottom
< 0 ) {
1158 animations
.scrollTop
= containerDimensions
.scroll
.top
+ Math
.min( position
.top
, -position
.bottom
);
1161 if ( !config
.direction
|| config
.direction
=== 'x' ) {
1162 if ( position
.left
< 0 ) {
1163 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ position
.left
;
1164 } else if ( position
.left
> 0 && position
.right
< 0 ) {
1165 animations
.scrollLeft
= containerDimensions
.scroll
.left
+ Math
.min( position
.left
, -position
.right
);
1168 if ( !$.isEmptyObject( animations
) ) {
1169 $container
.stop( true ).animate( animations
, config
.duration
=== undefined ? 'fast' : config
.duration
);
1170 $container
.queue( function ( next
) {
1183 return deferred
.promise();
1187 * Force the browser to reconsider whether it really needs to render scrollbars inside the element
1188 * and reserve space for them, because it probably doesn't.
1190 * Workaround primarily for <https://code.google.com/p/chromium/issues/detail?id=387290>, but also
1191 * similar bugs in other browsers. "Just" forcing a reflow is not sufficient in all cases, we need
1192 * to first actually detach (or hide, but detaching is simpler) all children, *then* force a reflow,
1193 * and then reattach (or show) them back.
1196 * @param {HTMLElement} el Element to reconsider the scrollbars on
1198 OO
.ui
.Element
.static.reconsiderScrollbars = function ( el
) {
1199 var i
, len
, scrollLeft
, scrollTop
, nodes
= [];
1200 // Save scroll position
1201 scrollLeft
= el
.scrollLeft
;
1202 scrollTop
= el
.scrollTop
;
1203 // Detach all children
1204 while ( el
.firstChild
) {
1205 nodes
.push( el
.firstChild
);
1206 el
.removeChild( el
.firstChild
);
1209 void el
.offsetHeight
;
1210 // Reattach all children
1211 for ( i
= 0, len
= nodes
.length
; i
< len
; i
++ ) {
1212 el
.appendChild( nodes
[ i
] );
1214 // Restore scroll position (no-op if scrollbars disappeared)
1215 el
.scrollLeft
= scrollLeft
;
1216 el
.scrollTop
= scrollTop
;
1222 * Toggle visibility of an element.
1224 * @param {boolean} [show] Make element visible, omit to toggle visibility
1228 OO
.ui
.Element
.prototype.toggle = function ( show
) {
1229 show
= show
=== undefined ? !this.visible
: !!show
;
1231 if ( show
!== this.isVisible() ) {
1232 this.visible
= show
;
1233 this.$element
.toggleClass( 'oo-ui-element-hidden', !this.visible
);
1234 this.emit( 'toggle', show
);
1241 * Check if element is visible.
1243 * @return {boolean} element is visible
1245 OO
.ui
.Element
.prototype.isVisible = function () {
1246 return this.visible
;
1252 * @return {Mixed} Element data
1254 OO
.ui
.Element
.prototype.getData = function () {
1261 * @param {Mixed} data Element data
1264 OO
.ui
.Element
.prototype.setData = function ( data
) {
1270 * Check if element supports one or more methods.
1272 * @param {string|string[]} methods Method or list of methods to check
1273 * @return {boolean} All methods are supported
1275 OO
.ui
.Element
.prototype.supports = function ( methods
) {
1279 methods
= Array
.isArray( methods
) ? methods
: [ methods
];
1280 for ( i
= 0, len
= methods
.length
; i
< len
; i
++ ) {
1281 if ( $.isFunction( this[ methods
[ i
] ] ) ) {
1286 return methods
.length
=== support
;
1290 * Update the theme-provided classes.
1292 * @localdoc This is called in element mixins and widget classes any time state changes.
1293 * Updating is debounced, minimizing overhead of changing multiple attributes and
1294 * guaranteeing that theme updates do not occur within an element's constructor
1296 OO
.ui
.Element
.prototype.updateThemeClasses = function () {
1297 this.debouncedUpdateThemeClassesHandler();
1302 * @localdoc This method is called directly from the QUnit tests instead of #updateThemeClasses, to
1303 * make them synchronous.
1305 OO
.ui
.Element
.prototype.debouncedUpdateThemeClasses = function () {
1306 OO
.ui
.theme
.updateElementClasses( this );
1310 * Get the HTML tag name.
1312 * Override this method to base the result on instance information.
1314 * @return {string} HTML tag name
1316 OO
.ui
.Element
.prototype.getTagName = function () {
1317 return this.constructor.static.tagName
;
1321 * Check if the element is attached to the DOM
1323 * @return {boolean} The element is attached to the DOM
1325 OO
.ui
.Element
.prototype.isElementAttached = function () {
1326 return $.contains( this.getElementDocument(), this.$element
[ 0 ] );
1330 * Get the DOM document.
1332 * @return {HTMLDocument} Document object
1334 OO
.ui
.Element
.prototype.getElementDocument = function () {
1335 // Don't cache this in other ways either because subclasses could can change this.$element
1336 return OO
.ui
.Element
.static.getDocument( this.$element
);
1340 * Get the DOM window.
1342 * @return {Window} Window object
1344 OO
.ui
.Element
.prototype.getElementWindow = function () {
1345 return OO
.ui
.Element
.static.getWindow( this.$element
);
1349 * Get closest scrollable container.
1351 * @return {HTMLElement} Closest scrollable container
1353 OO
.ui
.Element
.prototype.getClosestScrollableElementContainer = function () {
1354 return OO
.ui
.Element
.static.getClosestScrollableContainer( this.$element
[ 0 ] );
1358 * Get group element is in.
1360 * @return {OO.ui.mixin.GroupElement|null} Group element, null if none
1362 OO
.ui
.Element
.prototype.getElementGroup = function () {
1363 return this.elementGroup
;
1367 * Set group element is in.
1369 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
1372 OO
.ui
.Element
.prototype.setElementGroup = function ( group
) {
1373 this.elementGroup
= group
;
1378 * Scroll element into view.
1380 * @param {Object} [config] Configuration options
1381 * @return {jQuery.Promise} Promise which resolves when the scroll is complete
1383 OO
.ui
.Element
.prototype.scrollElementIntoView = function ( config
) {
1384 return OO
.ui
.Element
.static.scrollIntoView( this.$element
[ 0 ], config
);
1388 * Restore the pre-infusion dynamic state for this widget.
1390 * This method is called after #$element has been inserted into DOM. The parameter is the return
1391 * value of #gatherPreInfuseState.
1394 * @param {Object} state
1396 OO
.ui
.Element
.prototype.restorePreInfuseState = function () {
1400 * Wraps an HTML snippet for use with configuration values which default
1401 * to strings. This bypasses the default html-escaping done to string
1407 * @param {string} [content] HTML content
1409 OO
.ui
.HtmlSnippet
= function OoUiHtmlSnippet( content
) {
1411 this.content
= content
;
1416 OO
.initClass( OO
.ui
.HtmlSnippet
);
1423 * @return {string} Unchanged HTML snippet.
1425 OO
.ui
.HtmlSnippet
.prototype.toString = function () {
1426 return this.content
;
1430 * Layouts are containers for elements and are used to arrange other widgets of arbitrary type in a way
1431 * that is centrally controlled and can be updated dynamically. Layouts can be, and usually are, combined.
1432 * See {@link OO.ui.FieldsetLayout FieldsetLayout}, {@link OO.ui.FieldLayout FieldLayout}, {@link OO.ui.FormLayout FormLayout},
1433 * {@link OO.ui.PanelLayout PanelLayout}, {@link OO.ui.StackLayout StackLayout}, {@link OO.ui.PageLayout PageLayout},
1434 * {@link OO.ui.HorizontalLayout HorizontalLayout}, and {@link OO.ui.BookletLayout BookletLayout} for more information and examples.
1438 * @extends OO.ui.Element
1439 * @mixins OO.EventEmitter
1442 * @param {Object} [config] Configuration options
1444 OO
.ui
.Layout
= function OoUiLayout( config
) {
1445 // Configuration initialization
1446 config
= config
|| {};
1448 // Parent constructor
1449 OO
.ui
.Layout
.parent
.call( this, config
);
1451 // Mixin constructors
1452 OO
.EventEmitter
.call( this );
1455 this.$element
.addClass( 'oo-ui-layout' );
1460 OO
.inheritClass( OO
.ui
.Layout
, OO
.ui
.Element
);
1461 OO
.mixinClass( OO
.ui
.Layout
, OO
.EventEmitter
);
1464 * Widgets are compositions of one or more OOjs UI elements that users can both view
1465 * and interact with. All widgets can be configured and modified via a standard API,
1466 * and their state can change dynamically according to a model.
1470 * @extends OO.ui.Element
1471 * @mixins OO.EventEmitter
1474 * @param {Object} [config] Configuration options
1475 * @cfg {boolean} [disabled=false] Disable the widget. Disabled widgets cannot be used and their
1476 * appearance reflects this state.
1478 OO
.ui
.Widget
= function OoUiWidget( config
) {
1479 // Initialize config
1480 config
= $.extend( { disabled
: false }, config
);
1482 // Parent constructor
1483 OO
.ui
.Widget
.parent
.call( this, config
);
1485 // Mixin constructors
1486 OO
.EventEmitter
.call( this );
1489 this.disabled
= null;
1490 this.wasDisabled
= null;
1493 this.$element
.addClass( 'oo-ui-widget' );
1494 this.setDisabled( !!config
.disabled
);
1499 OO
.inheritClass( OO
.ui
.Widget
, OO
.ui
.Element
);
1500 OO
.mixinClass( OO
.ui
.Widget
, OO
.EventEmitter
);
1502 /* Static Properties */
1505 * Whether this widget will behave reasonably when wrapped in a HTML `<label>`. If this is true,
1506 * wrappers such as OO.ui.FieldLayout may use a `<label>` instead of implementing own label click
1511 * @property {boolean}
1513 OO
.ui
.Widget
.static.supportsSimpleLabel
= false;
1520 * A 'disable' event is emitted when the disabled state of the widget changes
1521 * (i.e. on disable **and** enable).
1523 * @param {boolean} disabled Widget is disabled
1529 * A 'toggle' event is emitted when the visibility of the widget changes.
1531 * @param {boolean} visible Widget is visible
1537 * Check if the widget is disabled.
1539 * @return {boolean} Widget is disabled
1541 OO
.ui
.Widget
.prototype.isDisabled = function () {
1542 return this.disabled
;
1546 * Set the 'disabled' state of the widget.
1548 * When a widget is disabled, it cannot be used and its appearance is updated to reflect this state.
1550 * @param {boolean} disabled Disable widget
1553 OO
.ui
.Widget
.prototype.setDisabled = function ( disabled
) {
1556 this.disabled
= !!disabled
;
1557 isDisabled
= this.isDisabled();
1558 if ( isDisabled
!== this.wasDisabled
) {
1559 this.$element
.toggleClass( 'oo-ui-widget-disabled', isDisabled
);
1560 this.$element
.toggleClass( 'oo-ui-widget-enabled', !isDisabled
);
1561 this.$element
.attr( 'aria-disabled', isDisabled
.toString() );
1562 this.emit( 'disable', isDisabled
);
1563 this.updateThemeClasses();
1565 this.wasDisabled
= isDisabled
;
1571 * Update the disabled state, in case of changes in parent widget.
1575 OO
.ui
.Widget
.prototype.updateDisabled = function () {
1576 this.setDisabled( this.disabled
);
1587 * @param {Object} [config] Configuration options
1589 OO
.ui
.Theme
= function OoUiTheme( config
) {
1590 // Configuration initialization
1591 config
= config
|| {};
1596 OO
.initClass( OO
.ui
.Theme
);
1601 * Get a list of classes to be applied to a widget.
1603 * The 'on' and 'off' lists combined MUST contain keys for all classes the theme adds or removes,
1604 * otherwise state transitions will not work properly.
1606 * @param {OO.ui.Element} element Element for which to get classes
1607 * @return {Object.<string,string[]>} Categorized class names with `on` and `off` lists
1609 OO
.ui
.Theme
.prototype.getElementClasses = function () {
1610 return { on
: [], off
: [] };
1614 * Update CSS classes provided by the theme.
1616 * For elements with theme logic hooks, this should be called any time there's a state change.
1618 * @param {OO.ui.Element} element Element for which to update classes
1619 * @return {Object.<string,string[]>} Categorized class names with `on` and `off` lists
1621 OO
.ui
.Theme
.prototype.updateElementClasses = function ( element
) {
1622 var $elements
= $( [] ),
1623 classes
= this.getElementClasses( element
);
1625 if ( element
.$icon
) {
1626 $elements
= $elements
.add( element
.$icon
);
1628 if ( element
.$indicator
) {
1629 $elements
= $elements
.add( element
.$indicator
);
1633 .removeClass( classes
.off
.join( ' ' ) )
1634 .addClass( classes
.on
.join( ' ' ) );
1638 * The TabIndexedElement class is an attribute mixin used to add additional functionality to an
1639 * element created by another class. The mixin provides a ‘tabIndex’ property, which specifies the
1640 * order in which users will navigate through the focusable elements via the "tab" key.
1643 * // TabIndexedElement is mixed into the ButtonWidget class
1644 * // to provide a tabIndex property.
1645 * var button1 = new OO.ui.ButtonWidget( {
1649 * var button2 = new OO.ui.ButtonWidget( {
1653 * var button3 = new OO.ui.ButtonWidget( {
1657 * var button4 = new OO.ui.ButtonWidget( {
1661 * $( 'body' ).append( button1.$element, button2.$element, button3.$element, button4.$element );
1667 * @param {Object} [config] Configuration options
1668 * @cfg {jQuery} [$tabIndexed] The element that should use the tabindex functionality. By default,
1669 * the functionality is applied to the element created by the class ($element). If a different element is specified, the tabindex
1670 * functionality will be applied to it instead.
1671 * @cfg {number|null} [tabIndex=0] Number that specifies the element’s position in the tab-navigation
1672 * order (e.g., 1 for the first focusable element). Use 0 to use the default navigation order; use -1
1673 * to remove the element from the tab-navigation flow.
1675 OO
.ui
.mixin
.TabIndexedElement
= function OoUiMixinTabIndexedElement( config
) {
1676 // Configuration initialization
1677 config
= $.extend( { tabIndex
: 0 }, config
);
1680 this.$tabIndexed
= null;
1681 this.tabIndex
= null;
1684 this.connect( this, { disable
: 'onTabIndexedElementDisable' } );
1687 this.setTabIndex( config
.tabIndex
);
1688 this.setTabIndexedElement( config
.$tabIndexed
|| this.$element
);
1693 OO
.initClass( OO
.ui
.mixin
.TabIndexedElement
);
1698 * Set the element that should use the tabindex functionality.
1700 * This method is used to retarget a tabindex mixin so that its functionality applies
1701 * to the specified element. If an element is currently using the functionality, the mixin’s
1702 * effect on that element is removed before the new element is set up.
1704 * @param {jQuery} $tabIndexed Element that should use the tabindex functionality
1707 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndexedElement = function ( $tabIndexed
) {
1708 var tabIndex
= this.tabIndex
;
1709 // Remove attributes from old $tabIndexed
1710 this.setTabIndex( null );
1711 // Force update of new $tabIndexed
1712 this.$tabIndexed
= $tabIndexed
;
1713 this.tabIndex
= tabIndex
;
1714 return this.updateTabIndex();
1718 * Set the value of the tabindex.
1720 * @param {number|null} tabIndex Tabindex value, or `null` for no tabindex
1723 OO
.ui
.mixin
.TabIndexedElement
.prototype.setTabIndex = function ( tabIndex
) {
1724 tabIndex
= typeof tabIndex
=== 'number' ? tabIndex
: null;
1726 if ( this.tabIndex
!== tabIndex
) {
1727 this.tabIndex
= tabIndex
;
1728 this.updateTabIndex();
1735 * Update the `tabindex` attribute, in case of changes to tab index or
1741 OO
.ui
.mixin
.TabIndexedElement
.prototype.updateTabIndex = function () {
1742 if ( this.$tabIndexed
) {
1743 if ( this.tabIndex
!== null ) {
1744 // Do not index over disabled elements
1745 this.$tabIndexed
.attr( {
1746 tabindex
: this.isDisabled() ? -1 : this.tabIndex
,
1747 // Support: ChromeVox and NVDA
1748 // These do not seem to inherit aria-disabled from parent elements
1749 'aria-disabled': this.isDisabled().toString()
1752 this.$tabIndexed
.removeAttr( 'tabindex aria-disabled' );
1759 * Handle disable events.
1762 * @param {boolean} disabled Element is disabled
1764 OO
.ui
.mixin
.TabIndexedElement
.prototype.onTabIndexedElementDisable = function () {
1765 this.updateTabIndex();
1769 * Get the value of the tabindex.
1771 * @return {number|null} Tabindex value
1773 OO
.ui
.mixin
.TabIndexedElement
.prototype.getTabIndex = function () {
1774 return this.tabIndex
;
1778 * ButtonElement is often mixed into other classes to generate a button, which is a clickable
1779 * interface element that can be configured with access keys for accessibility.
1780 * See the [OOjs UI documentation on MediaWiki] [1] for examples.
1782 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches#Buttons
1788 * @param {Object} [config] Configuration options
1789 * @cfg {jQuery} [$button] The button element created by the class.
1790 * If this configuration is omitted, the button element will use a generated `<a>`.
1791 * @cfg {boolean} [framed=true] Render the button with a frame
1793 OO
.ui
.mixin
.ButtonElement
= function OoUiMixinButtonElement( config
) {
1794 // Configuration initialization
1795 config
= config
|| {};
1798 this.$button
= null;
1800 this.active
= false;
1801 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
1802 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
1803 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
1804 this.onKeyUpHandler
= this.onKeyUp
.bind( this );
1805 this.onClickHandler
= this.onClick
.bind( this );
1806 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
1809 this.$element
.addClass( 'oo-ui-buttonElement' );
1810 this.toggleFramed( config
.framed
=== undefined || config
.framed
);
1811 this.setButtonElement( config
.$button
|| $( '<a>' ) );
1816 OO
.initClass( OO
.ui
.mixin
.ButtonElement
);
1818 /* Static Properties */
1821 * Cancel mouse down events.
1823 * This property is usually set to `true` to prevent the focus from changing when the button is clicked.
1824 * Classes such as {@link OO.ui.mixin.DraggableElement DraggableElement} and {@link OO.ui.ButtonOptionWidget ButtonOptionWidget}
1825 * use a value of `false` so that dragging behavior is possible and mousedown events can be handled by a
1830 * @property {boolean}
1832 OO
.ui
.mixin
.ButtonElement
.static.cancelButtonMouseDownEvents
= true;
1837 * A 'click' event is emitted when the button element is clicked.
1845 * Set the button element.
1847 * This method is used to retarget a button mixin so that its functionality applies to
1848 * the specified button element instead of the one created by the class. If a button element
1849 * is already set, the method will remove the mixin’s effect on that element.
1851 * @param {jQuery} $button Element to use as button
1853 OO
.ui
.mixin
.ButtonElement
.prototype.setButtonElement = function ( $button
) {
1854 if ( this.$button
) {
1856 .removeClass( 'oo-ui-buttonElement-button' )
1857 .removeAttr( 'role accesskey' )
1859 mousedown
: this.onMouseDownHandler
,
1860 keydown
: this.onKeyDownHandler
,
1861 click
: this.onClickHandler
,
1862 keypress
: this.onKeyPressHandler
1866 this.$button
= $button
1867 .addClass( 'oo-ui-buttonElement-button' )
1868 .attr( { role
: 'button' } )
1870 mousedown
: this.onMouseDownHandler
,
1871 keydown
: this.onKeyDownHandler
,
1872 click
: this.onClickHandler
,
1873 keypress
: this.onKeyPressHandler
1878 * Handles mouse down events.
1881 * @param {jQuery.Event} e Mouse down event
1883 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseDown = function ( e
) {
1884 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
1887 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
1888 // Run the mouseup handler no matter where the mouse is when the button is let go, so we can
1889 // reliably remove the pressed class
1890 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
1891 // Prevent change of focus unless specifically configured otherwise
1892 if ( this.constructor.static.cancelButtonMouseDownEvents
) {
1898 * Handles mouse up events.
1901 * @param {MouseEvent} e Mouse up event
1903 OO
.ui
.mixin
.ButtonElement
.prototype.onMouseUp = function ( e
) {
1904 if ( this.isDisabled() || e
.which
!== OO
.ui
.MouseButtons
.LEFT
) {
1907 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
1908 // Stop listening for mouseup, since we only needed this once
1909 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
1913 * Handles mouse click events.
1916 * @param {jQuery.Event} e Mouse click event
1919 OO
.ui
.mixin
.ButtonElement
.prototype.onClick = function ( e
) {
1920 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
1921 if ( this.emit( 'click' ) ) {
1928 * Handles key down events.
1931 * @param {jQuery.Event} e Key down event
1933 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyDown = function ( e
) {
1934 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
1937 this.$element
.addClass( 'oo-ui-buttonElement-pressed' );
1938 // Run the keyup handler no matter where the key is when the button is let go, so we can
1939 // reliably remove the pressed class
1940 this.getElementDocument().addEventListener( 'keyup', this.onKeyUpHandler
, true );
1944 * Handles key up events.
1947 * @param {KeyboardEvent} e Key up event
1949 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyUp = function ( e
) {
1950 if ( this.isDisabled() || ( e
.which
!== OO
.ui
.Keys
.SPACE
&& e
.which
!== OO
.ui
.Keys
.ENTER
) ) {
1953 this.$element
.removeClass( 'oo-ui-buttonElement-pressed' );
1954 // Stop listening for keyup, since we only needed this once
1955 this.getElementDocument().removeEventListener( 'keyup', this.onKeyUpHandler
, true );
1959 * Handles key press events.
1962 * @param {jQuery.Event} e Key press event
1965 OO
.ui
.mixin
.ButtonElement
.prototype.onKeyPress = function ( e
) {
1966 if ( !this.isDisabled() && ( e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
) ) {
1967 if ( this.emit( 'click' ) ) {
1974 * Check if button has a frame.
1976 * @return {boolean} Button is framed
1978 OO
.ui
.mixin
.ButtonElement
.prototype.isFramed = function () {
1983 * Render the button with or without a frame. Omit the `framed` parameter to toggle the button frame on and off.
1985 * @param {boolean} [framed] Make button framed, omit to toggle
1988 OO
.ui
.mixin
.ButtonElement
.prototype.toggleFramed = function ( framed
) {
1989 framed
= framed
=== undefined ? !this.framed
: !!framed
;
1990 if ( framed
!== this.framed
) {
1991 this.framed
= framed
;
1993 .toggleClass( 'oo-ui-buttonElement-frameless', !framed
)
1994 .toggleClass( 'oo-ui-buttonElement-framed', framed
);
1995 this.updateThemeClasses();
2002 * Set the button's active state.
2004 * The active state can be set on:
2006 * - {@link OO.ui.ButtonOptionWidget ButtonOptionWidget} when it is selected
2007 * - {@link OO.ui.ToggleButtonWidget ToggleButtonWidget} when it is toggle on
2008 * - {@link OO.ui.ButtonWidget ButtonWidget} when clicking the button would only refresh the page
2011 * @param {boolean} value Make button active
2014 OO
.ui
.mixin
.ButtonElement
.prototype.setActive = function ( value
) {
2015 this.active
= !!value
;
2016 this.$element
.toggleClass( 'oo-ui-buttonElement-active', this.active
);
2021 * Check if the button is active
2024 * @return {boolean} The button is active
2026 OO
.ui
.mixin
.ButtonElement
.prototype.isActive = function () {
2031 * Any OOjs UI widget that contains other widgets (such as {@link OO.ui.ButtonWidget buttons} or
2032 * {@link OO.ui.OptionWidget options}) mixes in GroupElement. Adding, removing, and clearing
2033 * items from the group is done through the interface the class provides.
2034 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
2036 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Groups
2042 * @param {Object} [config] Configuration options
2043 * @cfg {jQuery} [$group] The container element created by the class. If this configuration
2044 * is omitted, the group element will use a generated `<div>`.
2046 OO
.ui
.mixin
.GroupElement
= function OoUiMixinGroupElement( config
) {
2047 // Configuration initialization
2048 config
= config
|| {};
2053 this.aggregateItemEvents
= {};
2056 this.setGroupElement( config
.$group
|| $( '<div>' ) );
2064 * A change event is emitted when the set of selected items changes.
2066 * @param {OO.ui.Element[]} items Items currently in the group
2072 * Set the group element.
2074 * If an element is already set, items will be moved to the new element.
2076 * @param {jQuery} $group Element to use as group
2078 OO
.ui
.mixin
.GroupElement
.prototype.setGroupElement = function ( $group
) {
2081 this.$group
= $group
;
2082 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2083 this.$group
.append( this.items
[ i
].$element
);
2088 * Check if a group contains no items.
2090 * @return {boolean} Group is empty
2092 OO
.ui
.mixin
.GroupElement
.prototype.isEmpty = function () {
2093 return !this.items
.length
;
2097 * Get all items in the group.
2099 * The method returns an array of item references (e.g., [button1, button2, button3]) and is useful
2100 * when synchronizing groups of items, or whenever the references are required (e.g., when removing items
2103 * @return {OO.ui.Element[]} An array of items.
2105 OO
.ui
.mixin
.GroupElement
.prototype.getItems = function () {
2106 return this.items
.slice( 0 );
2110 * Get an item by its data.
2112 * Only the first item with matching data will be returned. To return all matching items,
2113 * use the #getItemsFromData method.
2115 * @param {Object} data Item data to search for
2116 * @return {OO.ui.Element|null} Item with equivalent data, `null` if none exists
2118 OO
.ui
.mixin
.GroupElement
.prototype.getItemFromData = function ( data
) {
2120 hash
= OO
.getHash( data
);
2122 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2123 item
= this.items
[ i
];
2124 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2133 * Get items by their data.
2135 * All items with matching data will be returned. To return only the first match, use the #getItemFromData method instead.
2137 * @param {Object} data Item data to search for
2138 * @return {OO.ui.Element[]} Items with equivalent data
2140 OO
.ui
.mixin
.GroupElement
.prototype.getItemsFromData = function ( data
) {
2142 hash
= OO
.getHash( data
),
2145 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2146 item
= this.items
[ i
];
2147 if ( hash
=== OO
.getHash( item
.getData() ) ) {
2156 * Aggregate the events emitted by the group.
2158 * When events are aggregated, the group will listen to all contained items for the event,
2159 * and then emit the event under a new name. The new event will contain an additional leading
2160 * parameter containing the item that emitted the original event. Other arguments emitted from
2161 * the original event are passed through.
2163 * @param {Object.<string,string|null>} events An object keyed by the name of the event that should be
2164 * aggregated (e.g., ‘click’) and the value of the new name to use (e.g., ‘groupClick’).
2165 * A `null` value will remove aggregated events.
2167 * @throws {Error} An error is thrown if aggregation already exists.
2169 OO
.ui
.mixin
.GroupElement
.prototype.aggregate = function ( events
) {
2170 var i
, len
, item
, add
, remove
, itemEvent
, groupEvent
;
2172 for ( itemEvent
in events
) {
2173 groupEvent
= events
[ itemEvent
];
2175 // Remove existing aggregated event
2176 if ( Object
.prototype.hasOwnProperty
.call( this.aggregateItemEvents
, itemEvent
) ) {
2177 // Don't allow duplicate aggregations
2179 throw new Error( 'Duplicate item event aggregation for ' + itemEvent
);
2181 // Remove event aggregation from existing items
2182 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2183 item
= this.items
[ i
];
2184 if ( item
.connect
&& item
.disconnect
) {
2186 remove
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2187 item
.disconnect( this, remove
);
2190 // Prevent future items from aggregating event
2191 delete this.aggregateItemEvents
[ itemEvent
];
2194 // Add new aggregate event
2196 // Make future items aggregate event
2197 this.aggregateItemEvents
[ itemEvent
] = groupEvent
;
2198 // Add event aggregation to existing items
2199 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2200 item
= this.items
[ i
];
2201 if ( item
.connect
&& item
.disconnect
) {
2203 add
[ itemEvent
] = [ 'emit', groupEvent
, item
];
2204 item
.connect( this, add
);
2212 * Add items to the group.
2214 * Items will be added to the end of the group array unless the optional `index` parameter specifies
2215 * a different insertion point. Adding an existing item will move it to the end of the array or the point specified by the `index`.
2217 * @param {OO.ui.Element[]} items An array of items to add to the group
2218 * @param {number} [index] Index of the insertion point
2221 OO
.ui
.mixin
.GroupElement
.prototype.addItems = function ( items
, index
) {
2222 var i
, len
, item
, itemEvent
, events
, currentIndex
,
2225 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
2228 // Check if item exists then remove it first, effectively "moving" it
2229 currentIndex
= this.items
.indexOf( item
);
2230 if ( currentIndex
>= 0 ) {
2231 this.removeItems( [ item
] );
2232 // Adjust index to compensate for removal
2233 if ( currentIndex
< index
) {
2238 if ( item
.connect
&& item
.disconnect
&& !$.isEmptyObject( this.aggregateItemEvents
) ) {
2240 for ( itemEvent
in this.aggregateItemEvents
) {
2241 events
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2243 item
.connect( this, events
);
2245 item
.setElementGroup( this );
2246 itemElements
.push( item
.$element
.get( 0 ) );
2249 if ( index
=== undefined || index
< 0 || index
>= this.items
.length
) {
2250 this.$group
.append( itemElements
);
2251 this.items
.push
.apply( this.items
, items
);
2252 } else if ( index
=== 0 ) {
2253 this.$group
.prepend( itemElements
);
2254 this.items
.unshift
.apply( this.items
, items
);
2256 this.items
[ index
].$element
.before( itemElements
);
2257 this.items
.splice
.apply( this.items
, [ index
, 0 ].concat( items
) );
2260 this.emit( 'change', this.getItems() );
2265 * Remove the specified items from a group.
2267 * Removed items are detached (not removed) from the DOM so that they may be reused.
2268 * To remove all items from a group, you may wish to use the #clearItems method instead.
2270 * @param {OO.ui.Element[]} items An array of items to remove
2273 OO
.ui
.mixin
.GroupElement
.prototype.removeItems = function ( items
) {
2274 var i
, len
, item
, index
, events
, itemEvent
;
2276 // Remove specific items
2277 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
2279 index
= this.items
.indexOf( item
);
2280 if ( index
!== -1 ) {
2281 if ( item
.connect
&& item
.disconnect
&& !$.isEmptyObject( this.aggregateItemEvents
) ) {
2283 for ( itemEvent
in this.aggregateItemEvents
) {
2284 events
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2286 item
.disconnect( this, events
);
2288 item
.setElementGroup( null );
2289 this.items
.splice( index
, 1 );
2290 item
.$element
.detach();
2294 this.emit( 'change', this.getItems() );
2299 * Clear all items from the group.
2301 * Cleared items are detached from the DOM, not removed, so that they may be reused.
2302 * To remove only a subset of items from a group, use the #removeItems method.
2306 OO
.ui
.mixin
.GroupElement
.prototype.clearItems = function () {
2307 var i
, len
, item
, remove
, itemEvent
;
2310 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2311 item
= this.items
[ i
];
2313 item
.connect
&& item
.disconnect
&&
2314 !$.isEmptyObject( this.aggregateItemEvents
)
2317 if ( Object
.prototype.hasOwnProperty
.call( this.aggregateItemEvents
, itemEvent
) ) {
2318 remove
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2320 item
.disconnect( this, remove
);
2322 item
.setElementGroup( null );
2323 item
.$element
.detach();
2326 this.emit( 'change', this.getItems() );
2332 * IconElement is often mixed into other classes to generate an icon.
2333 * Icons are graphics, about the size of normal text. They are used to aid the user
2334 * in locating a control or to convey information in a space-efficient way. See the
2335 * [OOjs UI documentation on MediaWiki] [1] for a list of icons
2336 * included in the library.
2338 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2344 * @param {Object} [config] Configuration options
2345 * @cfg {jQuery} [$icon] The icon element created by the class. If this configuration is omitted,
2346 * the icon element will use a generated `<span>`. To use a different HTML tag, or to specify that
2347 * the icon element be set to an existing icon instead of the one generated by this class, set a
2348 * value using a jQuery selection. For example:
2350 * // Use a <div> tag instead of a <span>
2352 * // Use an existing icon element instead of the one generated by the class
2353 * $icon: this.$element
2354 * // Use an icon element from a child widget
2355 * $icon: this.childwidget.$element
2356 * @cfg {Object|string} [icon=''] The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of
2357 * symbolic names. A map is used for i18n purposes and contains a `default` icon
2358 * name and additional names keyed by language code. The `default` name is used when no icon is keyed
2359 * by the user's language.
2361 * Example of an i18n map:
2363 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2364 * See the [OOjs UI documentation on MediaWiki] [2] for a list of icons included in the library.
2365 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2366 * @cfg {string|Function} [iconTitle] A text string used as the icon title, or a function that returns title
2367 * text. The icon title is displayed when users move the mouse over the icon.
2369 OO
.ui
.mixin
.IconElement
= function OoUiMixinIconElement( config
) {
2370 // Configuration initialization
2371 config
= config
|| {};
2376 this.iconTitle
= null;
2379 this.setIcon( config
.icon
|| this.constructor.static.icon
);
2380 this.setIconTitle( config
.iconTitle
|| this.constructor.static.iconTitle
);
2381 this.setIconElement( config
.$icon
|| $( '<span>' ) );
2386 OO
.initClass( OO
.ui
.mixin
.IconElement
);
2388 /* Static Properties */
2391 * The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of symbolic names. A map is used
2392 * for i18n purposes and contains a `default` icon name and additional names keyed by
2393 * language code. The `default` name is used when no icon is keyed by the user's language.
2395 * Example of an i18n map:
2397 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2399 * Note: the static property will be overridden if the #icon configuration is used.
2403 * @property {Object|string}
2405 OO
.ui
.mixin
.IconElement
.static.icon
= null;
2408 * The icon title, displayed when users move the mouse over the icon. The value can be text, a
2409 * function that returns title text, or `null` for no title.
2411 * The static property will be overridden if the #iconTitle configuration is used.
2415 * @property {string|Function|null}
2417 OO
.ui
.mixin
.IconElement
.static.iconTitle
= null;
2422 * Set the icon element. This method is used to retarget an icon mixin so that its functionality
2423 * applies to the specified icon element instead of the one created by the class. If an icon
2424 * element is already set, the mixin’s effect on that element is removed. Generated CSS classes
2425 * and mixin methods will no longer affect the element.
2427 * @param {jQuery} $icon Element to use as icon
2429 OO
.ui
.mixin
.IconElement
.prototype.setIconElement = function ( $icon
) {
2432 .removeClass( 'oo-ui-iconElement-icon oo-ui-icon-' + this.icon
)
2433 .removeAttr( 'title' );
2437 .addClass( 'oo-ui-iconElement-icon' )
2438 .toggleClass( 'oo-ui-icon-' + this.icon
, !!this.icon
);
2439 if ( this.iconTitle
!== null ) {
2440 this.$icon
.attr( 'title', this.iconTitle
);
2443 this.updateThemeClasses();
2447 * Set icon by symbolic name (e.g., ‘remove’ or ‘menu’). Use `null` to remove an icon.
2448 * The icon parameter can also be set to a map of icon names. See the #icon config setting
2451 * @param {Object|string|null} icon A symbolic icon name, a {@link #icon map of icon names} keyed
2452 * by language code, or `null` to remove the icon.
2455 OO
.ui
.mixin
.IconElement
.prototype.setIcon = function ( icon
) {
2456 icon
= OO
.isPlainObject( icon
) ? OO
.ui
.getLocalValue( icon
, null, 'default' ) : icon
;
2457 icon
= typeof icon
=== 'string' && icon
.trim().length
? icon
.trim() : null;
2459 if ( this.icon
!== icon
) {
2461 if ( this.icon
!== null ) {
2462 this.$icon
.removeClass( 'oo-ui-icon-' + this.icon
);
2464 if ( icon
!== null ) {
2465 this.$icon
.addClass( 'oo-ui-icon-' + icon
);
2471 this.$element
.toggleClass( 'oo-ui-iconElement', !!this.icon
);
2472 this.updateThemeClasses();
2478 * Set the icon title. Use `null` to remove the title.
2480 * @param {string|Function|null} iconTitle A text string used as the icon title,
2481 * a function that returns title text, or `null` for no title.
2484 OO
.ui
.mixin
.IconElement
.prototype.setIconTitle = function ( iconTitle
) {
2485 iconTitle
= typeof iconTitle
=== 'function' ||
2486 ( typeof iconTitle
=== 'string' && iconTitle
.length
) ?
2487 OO
.ui
.resolveMsg( iconTitle
) : null;
2489 if ( this.iconTitle
!== iconTitle
) {
2490 this.iconTitle
= iconTitle
;
2492 if ( this.iconTitle
!== null ) {
2493 this.$icon
.attr( 'title', iconTitle
);
2495 this.$icon
.removeAttr( 'title' );
2504 * Get the symbolic name of the icon.
2506 * @return {string} Icon name
2508 OO
.ui
.mixin
.IconElement
.prototype.getIcon = function () {
2513 * Get the icon title. The title text is displayed when a user moves the mouse over the icon.
2515 * @return {string} Icon title text
2517 OO
.ui
.mixin
.IconElement
.prototype.getIconTitle = function () {
2518 return this.iconTitle
;
2522 * IndicatorElement is often mixed into other classes to generate an indicator.
2523 * Indicators are small graphics that are generally used in two ways:
2525 * - To draw attention to the status of an item. For example, an indicator might be
2526 * used to show that an item in a list has errors that need to be resolved.
2527 * - To clarify the function of a control that acts in an exceptional way (a button
2528 * that opens a menu instead of performing an action directly, for example).
2530 * For a list of indicators included in the library, please see the
2531 * [OOjs UI documentation on MediaWiki] [1].
2533 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2539 * @param {Object} [config] Configuration options
2540 * @cfg {jQuery} [$indicator] The indicator element created by the class. If this
2541 * configuration is omitted, the indicator element will use a generated `<span>`.
2542 * @cfg {string} [indicator] Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2543 * See the [OOjs UI documentation on MediaWiki][2] for a list of indicators included
2545 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2546 * @cfg {string|Function} [indicatorTitle] A text string used as the indicator title,
2547 * or a function that returns title text. The indicator title is displayed when users move
2548 * the mouse over the indicator.
2550 OO
.ui
.mixin
.IndicatorElement
= function OoUiMixinIndicatorElement( config
) {
2551 // Configuration initialization
2552 config
= config
|| {};
2555 this.$indicator
= null;
2556 this.indicator
= null;
2557 this.indicatorTitle
= null;
2560 this.setIndicator( config
.indicator
|| this.constructor.static.indicator
);
2561 this.setIndicatorTitle( config
.indicatorTitle
|| this.constructor.static.indicatorTitle
);
2562 this.setIndicatorElement( config
.$indicator
|| $( '<span>' ) );
2567 OO
.initClass( OO
.ui
.mixin
.IndicatorElement
);
2569 /* Static Properties */
2572 * Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2573 * The static property will be overridden if the #indicator configuration is used.
2577 * @property {string|null}
2579 OO
.ui
.mixin
.IndicatorElement
.static.indicator
= null;
2582 * A text string used as the indicator title, a function that returns title text, or `null`
2583 * for no title. The static property will be overridden if the #indicatorTitle configuration is used.
2587 * @property {string|Function|null}
2589 OO
.ui
.mixin
.IndicatorElement
.static.indicatorTitle
= null;
2594 * Set the indicator element.
2596 * If an element is already set, it will be cleaned up before setting up the new element.
2598 * @param {jQuery} $indicator Element to use as indicator
2600 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorElement = function ( $indicator
) {
2601 if ( this.$indicator
) {
2603 .removeClass( 'oo-ui-indicatorElement-indicator oo-ui-indicator-' + this.indicator
)
2604 .removeAttr( 'title' );
2607 this.$indicator
= $indicator
2608 .addClass( 'oo-ui-indicatorElement-indicator' )
2609 .toggleClass( 'oo-ui-indicator-' + this.indicator
, !!this.indicator
);
2610 if ( this.indicatorTitle
!== null ) {
2611 this.$indicator
.attr( 'title', this.indicatorTitle
);
2614 this.updateThemeClasses();
2618 * Set the indicator by its symbolic name: ‘alert’, ‘down’, ‘next’, ‘previous’, ‘required’, ‘up’. Use `null` to remove the indicator.
2620 * @param {string|null} indicator Symbolic name of indicator, or `null` for no indicator
2623 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicator = function ( indicator
) {
2624 indicator
= typeof indicator
=== 'string' && indicator
.length
? indicator
.trim() : null;
2626 if ( this.indicator
!== indicator
) {
2627 if ( this.$indicator
) {
2628 if ( this.indicator
!== null ) {
2629 this.$indicator
.removeClass( 'oo-ui-indicator-' + this.indicator
);
2631 if ( indicator
!== null ) {
2632 this.$indicator
.addClass( 'oo-ui-indicator-' + indicator
);
2635 this.indicator
= indicator
;
2638 this.$element
.toggleClass( 'oo-ui-indicatorElement', !!this.indicator
);
2639 this.updateThemeClasses();
2645 * Set the indicator title.
2647 * The title is displayed when a user moves the mouse over the indicator.
2649 * @param {string|Function|null} indicatorTitle Indicator title text, a function that returns text, or
2650 * `null` for no indicator title
2653 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorTitle = function ( indicatorTitle
) {
2654 indicatorTitle
= typeof indicatorTitle
=== 'function' ||
2655 ( typeof indicatorTitle
=== 'string' && indicatorTitle
.length
) ?
2656 OO
.ui
.resolveMsg( indicatorTitle
) : null;
2658 if ( this.indicatorTitle
!== indicatorTitle
) {
2659 this.indicatorTitle
= indicatorTitle
;
2660 if ( this.$indicator
) {
2661 if ( this.indicatorTitle
!== null ) {
2662 this.$indicator
.attr( 'title', indicatorTitle
);
2664 this.$indicator
.removeAttr( 'title' );
2673 * Get the symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2675 * @return {string} Symbolic name of indicator
2677 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicator = function () {
2678 return this.indicator
;
2682 * Get the indicator title.
2684 * The title is displayed when a user moves the mouse over the indicator.
2686 * @return {string} Indicator title text
2688 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicatorTitle = function () {
2689 return this.indicatorTitle
;
2693 * LabelElement is often mixed into other classes to generate a label, which
2694 * helps identify the function of an interface element.
2695 * See the [OOjs UI documentation on MediaWiki] [1] for more information.
2697 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2703 * @param {Object} [config] Configuration options
2704 * @cfg {jQuery} [$label] The label element created by the class. If this
2705 * configuration is omitted, the label element will use a generated `<span>`.
2706 * @cfg {jQuery|string|Function|OO.ui.HtmlSnippet} [label] The label text. The label can be specified
2707 * as a plaintext string, a jQuery selection of elements, or a function that will produce a string
2708 * in the future. See the [OOjs UI documentation on MediaWiki] [2] for examples.
2709 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2711 OO
.ui
.mixin
.LabelElement
= function OoUiMixinLabelElement( config
) {
2712 // Configuration initialization
2713 config
= config
|| {};
2720 this.setLabel( config
.label
|| this.constructor.static.label
);
2721 this.setLabelElement( config
.$label
|| $( '<span>' ) );
2726 OO
.initClass( OO
.ui
.mixin
.LabelElement
);
2731 * @event labelChange
2732 * @param {string} value
2735 /* Static Properties */
2738 * The label text. The label can be specified as a plaintext string, a function that will
2739 * produce a string in the future, or `null` for no label. The static value will
2740 * be overridden if a label is specified with the #label config option.
2744 * @property {string|Function|null}
2746 OO
.ui
.mixin
.LabelElement
.static.label
= null;
2748 /* Static methods */
2751 * Highlight the first occurrence of the query in the given text
2753 * @param {string} text Text
2754 * @param {string} query Query to find
2755 * @return {jQuery} Text with the first match of the query
2756 * sub-string wrapped in highlighted span
2758 OO
.ui
.mixin
.LabelElement
.static.highlightQuery = function ( text
, query
) {
2759 var $result
= $( '<span>' ),
2760 offset
= text
.toLowerCase().indexOf( query
.toLowerCase() );
2762 if ( !query
.length
|| offset
=== -1 ) {
2763 return $result
.text( text
);
2766 document
.createTextNode( text
.slice( 0, offset
) ),
2768 .addClass( 'oo-ui-labelElement-label-highlight' )
2769 .text( text
.slice( offset
, offset
+ query
.length
) ),
2770 document
.createTextNode( text
.slice( offset
+ query
.length
) )
2772 return $result
.contents();
2778 * Set the label element.
2780 * If an element is already set, it will be cleaned up before setting up the new element.
2782 * @param {jQuery} $label Element to use as label
2784 OO
.ui
.mixin
.LabelElement
.prototype.setLabelElement = function ( $label
) {
2785 if ( this.$label
) {
2786 this.$label
.removeClass( 'oo-ui-labelElement-label' ).empty();
2789 this.$label
= $label
.addClass( 'oo-ui-labelElement-label' );
2790 this.setLabelContent( this.label
);
2796 * An empty string will result in the label being hidden. A string containing only whitespace will
2797 * be converted to a single ` `.
2799 * @param {jQuery|string|OO.ui.HtmlSnippet|Function|null} label Label nodes; text; a function that returns nodes or
2800 * text; or null for no label
2803 OO
.ui
.mixin
.LabelElement
.prototype.setLabel = function ( label
) {
2804 label
= typeof label
=== 'function' ? OO
.ui
.resolveMsg( label
) : label
;
2805 label
= ( ( typeof label
=== 'string' || label
instanceof jQuery
) && label
.length
) || ( label
instanceof OO
.ui
.HtmlSnippet
&& label
.toString().length
) ? label
: null;
2807 if ( this.label
!== label
) {
2808 if ( this.$label
) {
2809 this.setLabelContent( label
);
2812 this.emit( 'labelChange' );
2815 this.$element
.toggleClass( 'oo-ui-labelElement', !!this.label
);
2821 * Set the label as plain text with a highlighted query
2823 * @param {string} text Text label to set
2824 * @param {string} query Substring of text to highlight
2827 OO
.ui
.mixin
.LabelElement
.prototype.setHighlightedQuery = function ( text
, query
) {
2828 return this.setLabel( this.constructor.static.highlightQuery( text
, query
) );
2834 * @return {jQuery|string|Function|null} Label nodes; text; a function that returns nodes or
2835 * text; or null for no label
2837 OO
.ui
.mixin
.LabelElement
.prototype.getLabel = function () {
2845 * @deprecated since 0.16.0
2847 OO
.ui
.mixin
.LabelElement
.prototype.fitLabel = function () {
2852 * Set the content of the label.
2854 * Do not call this method until after the label element has been set by #setLabelElement.
2857 * @param {jQuery|string|Function|null} label Label nodes; text; a function that returns nodes or
2858 * text; or null for no label
2860 OO
.ui
.mixin
.LabelElement
.prototype.setLabelContent = function ( label
) {
2861 if ( typeof label
=== 'string' ) {
2862 if ( label
.match( /^\s*$/ ) ) {
2863 // Convert whitespace only string to a single non-breaking space
2864 this.$label
.html( ' ' );
2866 this.$label
.text( label
);
2868 } else if ( label
instanceof OO
.ui
.HtmlSnippet
) {
2869 this.$label
.html( label
.toString() );
2870 } else if ( label
instanceof jQuery
) {
2871 this.$label
.empty().append( label
);
2873 this.$label
.empty();
2878 * The FlaggedElement class is an attribute mixin, meaning that it is used to add
2879 * additional functionality to an element created by another class. The class provides
2880 * a ‘flags’ property assigned the name (or an array of names) of styling flags,
2881 * which are used to customize the look and feel of a widget to better describe its
2882 * importance and functionality.
2884 * The library currently contains the following styling flags for general use:
2886 * - **progressive**: Progressive styling is applied to convey that the widget will move the user forward in a process.
2887 * - **destructive**: Destructive styling is applied to convey that the widget will remove something.
2888 * - **constructive**: Constructive styling is applied to convey that the widget will create something.
2890 * The flags affect the appearance of the buttons:
2893 * // FlaggedElement is mixed into ButtonWidget to provide styling flags
2894 * var button1 = new OO.ui.ButtonWidget( {
2895 * label: 'Constructive',
2896 * flags: 'constructive'
2898 * var button2 = new OO.ui.ButtonWidget( {
2899 * label: 'Destructive',
2900 * flags: 'destructive'
2902 * var button3 = new OO.ui.ButtonWidget( {
2903 * label: 'Progressive',
2904 * flags: 'progressive'
2906 * $( 'body' ).append( button1.$element, button2.$element, button3.$element );
2908 * {@link OO.ui.ActionWidget ActionWidgets}, which are a special kind of button that execute an action, use these flags: **primary** and **safe**.
2909 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
2911 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
2917 * @param {Object} [config] Configuration options
2918 * @cfg {string|string[]} [flags] The name or names of the flags (e.g., 'constructive' or 'primary') to apply.
2919 * Please see the [OOjs UI documentation on MediaWiki] [2] for more information about available flags.
2920 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
2921 * @cfg {jQuery} [$flagged] The flagged element. By default,
2922 * the flagged functionality is applied to the element created by the class ($element).
2923 * If a different element is specified, the flagged functionality will be applied to it instead.
2925 OO
.ui
.mixin
.FlaggedElement
= function OoUiMixinFlaggedElement( config
) {
2926 // Configuration initialization
2927 config
= config
|| {};
2931 this.$flagged
= null;
2934 this.setFlags( config
.flags
);
2935 this.setFlaggedElement( config
.$flagged
|| this.$element
);
2942 * A flag event is emitted when the #clearFlags or #setFlags methods are used. The `changes`
2943 * parameter contains the name of each modified flag and indicates whether it was
2946 * @param {Object.<string,boolean>} changes Object keyed by flag name. A Boolean `true` indicates
2947 * that the flag was added, `false` that the flag was removed.
2953 * Set the flagged element.
2955 * This method is used to retarget a flagged mixin so that its functionality applies to the specified element.
2956 * If an element is already set, the method will remove the mixin’s effect on that element.
2958 * @param {jQuery} $flagged Element that should be flagged
2960 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlaggedElement = function ( $flagged
) {
2961 var classNames
= Object
.keys( this.flags
).map( function ( flag
) {
2962 return 'oo-ui-flaggedElement-' + flag
;
2965 if ( this.$flagged
) {
2966 this.$flagged
.removeClass( classNames
);
2969 this.$flagged
= $flagged
.addClass( classNames
);
2973 * Check if the specified flag is set.
2975 * @param {string} flag Name of flag
2976 * @return {boolean} The flag is set
2978 OO
.ui
.mixin
.FlaggedElement
.prototype.hasFlag = function ( flag
) {
2979 // This may be called before the constructor, thus before this.flags is set
2980 return this.flags
&& ( flag
in this.flags
);
2984 * Get the names of all flags set.
2986 * @return {string[]} Flag names
2988 OO
.ui
.mixin
.FlaggedElement
.prototype.getFlags = function () {
2989 // This may be called before the constructor, thus before this.flags is set
2990 return Object
.keys( this.flags
|| {} );
2999 OO
.ui
.mixin
.FlaggedElement
.prototype.clearFlags = function () {
3000 var flag
, className
,
3003 classPrefix
= 'oo-ui-flaggedElement-';
3005 for ( flag
in this.flags
) {
3006 className
= classPrefix
+ flag
;
3007 changes
[ flag
] = false;
3008 delete this.flags
[ flag
];
3009 remove
.push( className
);
3012 if ( this.$flagged
) {
3013 this.$flagged
.removeClass( remove
.join( ' ' ) );
3016 this.updateThemeClasses();
3017 this.emit( 'flag', changes
);
3023 * Add one or more flags.
3025 * @param {string|string[]|Object.<string, boolean>} flags A flag name, an array of flag names,
3026 * or an object keyed by flag name with a boolean value that indicates whether the flag should
3027 * be added (`true`) or removed (`false`).
3031 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlags = function ( flags
) {
3032 var i
, len
, flag
, className
,
3036 classPrefix
= 'oo-ui-flaggedElement-';
3038 if ( typeof flags
=== 'string' ) {
3039 className
= classPrefix
+ flags
;
3041 if ( !this.flags
[ flags
] ) {
3042 this.flags
[ flags
] = true;
3043 add
.push( className
);
3045 } else if ( Array
.isArray( flags
) ) {
3046 for ( i
= 0, len
= flags
.length
; i
< len
; i
++ ) {
3048 className
= classPrefix
+ flag
;
3050 if ( !this.flags
[ flag
] ) {
3051 changes
[ flag
] = true;
3052 this.flags
[ flag
] = true;
3053 add
.push( className
);
3056 } else if ( OO
.isPlainObject( flags
) ) {
3057 for ( flag
in flags
) {
3058 className
= classPrefix
+ flag
;
3059 if ( flags
[ flag
] ) {
3061 if ( !this.flags
[ flag
] ) {
3062 changes
[ flag
] = true;
3063 this.flags
[ flag
] = true;
3064 add
.push( className
);
3068 if ( this.flags
[ flag
] ) {
3069 changes
[ flag
] = false;
3070 delete this.flags
[ flag
];
3071 remove
.push( className
);
3077 if ( this.$flagged
) {
3079 .addClass( add
.join( ' ' ) )
3080 .removeClass( remove
.join( ' ' ) );
3083 this.updateThemeClasses();
3084 this.emit( 'flag', changes
);
3090 * TitledElement is mixed into other classes to provide a `title` attribute.
3091 * Titles are rendered by the browser and are made visible when the user moves
3092 * the mouse over the element. Titles are not visible on touch devices.
3095 * // TitledElement provides a 'title' attribute to the
3096 * // ButtonWidget class
3097 * var button = new OO.ui.ButtonWidget( {
3098 * label: 'Button with Title',
3099 * title: 'I am a button'
3101 * $( 'body' ).append( button.$element );
3107 * @param {Object} [config] Configuration options
3108 * @cfg {jQuery} [$titled] The element to which the `title` attribute is applied.
3109 * If this config is omitted, the title functionality is applied to $element, the
3110 * element created by the class.
3111 * @cfg {string|Function} [title] The title text or a function that returns text. If
3112 * this config is omitted, the value of the {@link #static-title static title} property is used.
3114 OO
.ui
.mixin
.TitledElement
= function OoUiMixinTitledElement( config
) {
3115 // Configuration initialization
3116 config
= config
|| {};
3119 this.$titled
= null;
3123 this.setTitle( config
.title
!== undefined ? config
.title
: this.constructor.static.title
);
3124 this.setTitledElement( config
.$titled
|| this.$element
);
3129 OO
.initClass( OO
.ui
.mixin
.TitledElement
);
3131 /* Static Properties */
3134 * The title text, a function that returns text, or `null` for no title. The value of the static property
3135 * is overridden if the #title config option is used.
3139 * @property {string|Function|null}
3141 OO
.ui
.mixin
.TitledElement
.static.title
= null;
3146 * Set the titled element.
3148 * This method is used to retarget a titledElement mixin so that its functionality applies to the specified element.
3149 * If an element is already set, the mixin’s effect on that element is removed before the new element is set up.
3151 * @param {jQuery} $titled Element that should use the 'titled' functionality
3153 OO
.ui
.mixin
.TitledElement
.prototype.setTitledElement = function ( $titled
) {
3154 if ( this.$titled
) {
3155 this.$titled
.removeAttr( 'title' );
3158 this.$titled
= $titled
;
3160 this.$titled
.attr( 'title', this.title
);
3167 * @param {string|Function|null} title Title text, a function that returns text, or `null` for no title
3170 OO
.ui
.mixin
.TitledElement
.prototype.setTitle = function ( title
) {
3171 title
= typeof title
=== 'function' ? OO
.ui
.resolveMsg( title
) : title
;
3172 title
= ( typeof title
=== 'string' && title
.length
) ? title
: null;
3174 if ( this.title
!== title
) {
3175 if ( this.$titled
) {
3176 if ( title
!== null ) {
3177 this.$titled
.attr( 'title', title
);
3179 this.$titled
.removeAttr( 'title' );
3191 * @return {string} Title string
3193 OO
.ui
.mixin
.TitledElement
.prototype.getTitle = function () {
3198 * AccessKeyedElement is mixed into other classes to provide an `accesskey` attribute.
3199 * Accesskeys allow an user to go to a specific element by using
3200 * a shortcut combination of a browser specific keys + the key
3204 * // AccessKeyedElement provides an 'accesskey' attribute to the
3205 * // ButtonWidget class
3206 * var button = new OO.ui.ButtonWidget( {
3207 * label: 'Button with Accesskey',
3210 * $( 'body' ).append( button.$element );
3216 * @param {Object} [config] Configuration options
3217 * @cfg {jQuery} [$accessKeyed] The element to which the `accesskey` attribute is applied.
3218 * If this config is omitted, the accesskey functionality is applied to $element, the
3219 * element created by the class.
3220 * @cfg {string|Function} [accessKey] The key or a function that returns the key. If
3221 * this config is omitted, no accesskey will be added.
3223 OO
.ui
.mixin
.AccessKeyedElement
= function OoUiMixinAccessKeyedElement( config
) {
3224 // Configuration initialization
3225 config
= config
|| {};
3228 this.$accessKeyed
= null;
3229 this.accessKey
= null;
3232 this.setAccessKey( config
.accessKey
|| null );
3233 this.setAccessKeyedElement( config
.$accessKeyed
|| this.$element
);
3238 OO
.initClass( OO
.ui
.mixin
.AccessKeyedElement
);
3240 /* Static Properties */
3243 * The access key, a function that returns a key, or `null` for no accesskey.
3247 * @property {string|Function|null}
3249 OO
.ui
.mixin
.AccessKeyedElement
.static.accessKey
= null;
3254 * Set the accesskeyed element.
3256 * This method is used to retarget a AccessKeyedElement mixin so that its functionality applies to the specified element.
3257 * If an element is already set, the mixin's effect on that element is removed before the new element is set up.
3259 * @param {jQuery} $accessKeyed Element that should use the 'accesskeyes' functionality
3261 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKeyedElement = function ( $accessKeyed
) {
3262 if ( this.$accessKeyed
) {
3263 this.$accessKeyed
.removeAttr( 'accesskey' );
3266 this.$accessKeyed
= $accessKeyed
;
3267 if ( this.accessKey
) {
3268 this.$accessKeyed
.attr( 'accesskey', this.accessKey
);
3275 * @param {string|Function|null} accessKey Key, a function that returns a key, or `null` for no accesskey
3278 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKey = function ( accessKey
) {
3279 accessKey
= typeof accessKey
=== 'string' ? OO
.ui
.resolveMsg( accessKey
) : null;
3281 if ( this.accessKey
!== accessKey
) {
3282 if ( this.$accessKeyed
) {
3283 if ( accessKey
!== null ) {
3284 this.$accessKeyed
.attr( 'accesskey', accessKey
);
3286 this.$accessKeyed
.removeAttr( 'accesskey' );
3289 this.accessKey
= accessKey
;
3298 * @return {string} accessKey string
3300 OO
.ui
.mixin
.AccessKeyedElement
.prototype.getAccessKey = function () {
3301 return this.accessKey
;
3305 * ButtonWidget is a generic widget for buttons. A wide variety of looks,
3306 * feels, and functionality can be customized via the class’s configuration options
3307 * and methods. Please see the [OOjs UI documentation on MediaWiki] [1] for more information
3310 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches
3313 * // A button widget
3314 * var button = new OO.ui.ButtonWidget( {
3315 * label: 'Button with Icon',
3317 * iconTitle: 'Remove'
3319 * $( 'body' ).append( button.$element );
3321 * NOTE: HTML form buttons should use the OO.ui.ButtonInputWidget class.
3324 * @extends OO.ui.Widget
3325 * @mixins OO.ui.mixin.ButtonElement
3326 * @mixins OO.ui.mixin.IconElement
3327 * @mixins OO.ui.mixin.IndicatorElement
3328 * @mixins OO.ui.mixin.LabelElement
3329 * @mixins OO.ui.mixin.TitledElement
3330 * @mixins OO.ui.mixin.FlaggedElement
3331 * @mixins OO.ui.mixin.TabIndexedElement
3332 * @mixins OO.ui.mixin.AccessKeyedElement
3335 * @param {Object} [config] Configuration options
3336 * @cfg {boolean} [active=false] Whether button should be shown as active
3337 * @cfg {string} [href] Hyperlink to visit when the button is clicked.
3338 * @cfg {string} [target] The frame or window in which to open the hyperlink.
3339 * @cfg {boolean} [noFollow] Search engine traversal hint (default: true)
3341 OO
.ui
.ButtonWidget
= function OoUiButtonWidget( config
) {
3342 // Configuration initialization
3343 config
= config
|| {};
3345 // Parent constructor
3346 OO
.ui
.ButtonWidget
.parent
.call( this, config
);
3348 // Mixin constructors
3349 OO
.ui
.mixin
.ButtonElement
.call( this, config
);
3350 OO
.ui
.mixin
.IconElement
.call( this, config
);
3351 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
3352 OO
.ui
.mixin
.LabelElement
.call( this, config
);
3353 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$button
} ) );
3354 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
3355 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$button
} ) );
3356 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$button
} ) );
3361 this.noFollow
= false;
3364 this.connect( this, { disable
: 'onDisable' } );
3367 this.$button
.append( this.$icon
, this.$label
, this.$indicator
);
3369 .addClass( 'oo-ui-buttonWidget' )
3370 .append( this.$button
);
3371 this.setActive( config
.active
);
3372 this.setHref( config
.href
);
3373 this.setTarget( config
.target
);
3374 this.setNoFollow( config
.noFollow
);
3379 OO
.inheritClass( OO
.ui
.ButtonWidget
, OO
.ui
.Widget
);
3380 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.ButtonElement
);
3381 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IconElement
);
3382 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IndicatorElement
);
3383 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.LabelElement
);
3384 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TitledElement
);
3385 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.FlaggedElement
);
3386 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TabIndexedElement
);
3387 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
3394 OO
.ui
.ButtonWidget
.prototype.onMouseDown = function ( e
) {
3395 if ( !this.isDisabled() ) {
3396 // Remove the tab-index while the button is down to prevent the button from stealing focus
3397 this.$button
.removeAttr( 'tabindex' );
3400 return OO
.ui
.mixin
.ButtonElement
.prototype.onMouseDown
.call( this, e
);
3406 OO
.ui
.ButtonWidget
.prototype.onMouseUp = function ( e
) {
3407 if ( !this.isDisabled() ) {
3408 // Restore the tab-index after the button is up to restore the button's accessibility
3409 this.$button
.attr( 'tabindex', this.tabIndex
);
3412 return OO
.ui
.mixin
.ButtonElement
.prototype.onMouseUp
.call( this, e
);
3416 * Get hyperlink location.
3418 * @return {string} Hyperlink location
3420 OO
.ui
.ButtonWidget
.prototype.getHref = function () {
3425 * Get hyperlink target.
3427 * @return {string} Hyperlink target
3429 OO
.ui
.ButtonWidget
.prototype.getTarget = function () {
3434 * Get search engine traversal hint.
3436 * @return {boolean} Whether search engines should avoid traversing this hyperlink
3438 OO
.ui
.ButtonWidget
.prototype.getNoFollow = function () {
3439 return this.noFollow
;
3443 * Set hyperlink location.
3445 * @param {string|null} href Hyperlink location, null to remove
3447 OO
.ui
.ButtonWidget
.prototype.setHref = function ( href
) {
3448 href
= typeof href
=== 'string' ? href
: null;
3449 if ( href
!== null && !OO
.ui
.isSafeUrl( href
) ) {
3453 if ( href
!== this.href
) {
3462 * Update the `href` attribute, in case of changes to href or
3468 OO
.ui
.ButtonWidget
.prototype.updateHref = function () {
3469 if ( this.href
!== null && !this.isDisabled() ) {
3470 this.$button
.attr( 'href', this.href
);
3472 this.$button
.removeAttr( 'href' );
3479 * Handle disable events.
3482 * @param {boolean} disabled Element is disabled
3484 OO
.ui
.ButtonWidget
.prototype.onDisable = function () {
3489 * Set hyperlink target.
3491 * @param {string|null} target Hyperlink target, null to remove
3493 OO
.ui
.ButtonWidget
.prototype.setTarget = function ( target
) {
3494 target
= typeof target
=== 'string' ? target
: null;
3496 if ( target
!== this.target
) {
3497 this.target
= target
;
3498 if ( target
!== null ) {
3499 this.$button
.attr( 'target', target
);
3501 this.$button
.removeAttr( 'target' );
3509 * Set search engine traversal hint.
3511 * @param {boolean} noFollow True if search engines should avoid traversing this hyperlink
3513 OO
.ui
.ButtonWidget
.prototype.setNoFollow = function ( noFollow
) {
3514 noFollow
= typeof noFollow
=== 'boolean' ? noFollow
: true;
3516 if ( noFollow
!== this.noFollow
) {
3517 this.noFollow
= noFollow
;
3519 this.$button
.attr( 'rel', 'nofollow' );
3521 this.$button
.removeAttr( 'rel' );
3528 // Override method visibility hints from ButtonElement
3537 * A ButtonGroupWidget groups related buttons and is used together with OO.ui.ButtonWidget and
3538 * its subclasses. Each button in a group is addressed by a unique reference. Buttons can be added,
3539 * removed, and cleared from the group.
3542 * // Example: A ButtonGroupWidget with two buttons
3543 * var button1 = new OO.ui.PopupButtonWidget( {
3544 * label: 'Select a category',
3547 * $content: $( '<p>List of categories...</p>' ),
3552 * var button2 = new OO.ui.ButtonWidget( {
3555 * var buttonGroup = new OO.ui.ButtonGroupWidget( {
3556 * items: [button1, button2]
3558 * $( 'body' ).append( buttonGroup.$element );
3561 * @extends OO.ui.Widget
3562 * @mixins OO.ui.mixin.GroupElement
3565 * @param {Object} [config] Configuration options
3566 * @cfg {OO.ui.ButtonWidget[]} [items] Buttons to add
3568 OO
.ui
.ButtonGroupWidget
= function OoUiButtonGroupWidget( config
) {
3569 // Configuration initialization
3570 config
= config
|| {};
3572 // Parent constructor
3573 OO
.ui
.ButtonGroupWidget
.parent
.call( this, config
);
3575 // Mixin constructors
3576 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
3579 this.$element
.addClass( 'oo-ui-buttonGroupWidget' );
3580 if ( Array
.isArray( config
.items
) ) {
3581 this.addItems( config
.items
);
3587 OO
.inheritClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.Widget
);
3588 OO
.mixinClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.mixin
.GroupElement
);
3591 * IconWidget is a generic widget for {@link OO.ui.mixin.IconElement icons}. In general, IconWidgets should be used with OO.ui.LabelWidget,
3592 * which creates a label that identifies the icon’s function. See the [OOjs UI documentation on MediaWiki] [1]
3593 * for a list of icons included in the library.
3596 * // An icon widget with a label
3597 * var myIcon = new OO.ui.IconWidget( {
3601 * // Create a label.
3602 * var iconLabel = new OO.ui.LabelWidget( {
3605 * $( 'body' ).append( myIcon.$element, iconLabel.$element );
3607 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
3610 * @extends OO.ui.Widget
3611 * @mixins OO.ui.mixin.IconElement
3612 * @mixins OO.ui.mixin.TitledElement
3613 * @mixins OO.ui.mixin.FlaggedElement
3616 * @param {Object} [config] Configuration options
3618 OO
.ui
.IconWidget
= function OoUiIconWidget( config
) {
3619 // Configuration initialization
3620 config
= config
|| {};
3622 // Parent constructor
3623 OO
.ui
.IconWidget
.parent
.call( this, config
);
3625 // Mixin constructors
3626 OO
.ui
.mixin
.IconElement
.call( this, $.extend( {}, config
, { $icon
: this.$element
} ) );
3627 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3628 OO
.ui
.mixin
.FlaggedElement
.call( this, $.extend( {}, config
, { $flagged
: this.$element
} ) );
3631 this.$element
.addClass( 'oo-ui-iconWidget' );
3636 OO
.inheritClass( OO
.ui
.IconWidget
, OO
.ui
.Widget
);
3637 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.IconElement
);
3638 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.TitledElement
);
3639 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.FlaggedElement
);
3641 /* Static Properties */
3643 OO
.ui
.IconWidget
.static.tagName
= 'span';
3646 * IndicatorWidgets create indicators, which are small graphics that are generally used to draw
3647 * attention to the status of an item or to clarify the function of a control. For a list of
3648 * indicators included in the library, please see the [OOjs UI documentation on MediaWiki][1].
3651 * // Example of an indicator widget
3652 * var indicator1 = new OO.ui.IndicatorWidget( {
3653 * indicator: 'alert'
3656 * // Create a fieldset layout to add a label
3657 * var fieldset = new OO.ui.FieldsetLayout();
3658 * fieldset.addItems( [
3659 * new OO.ui.FieldLayout( indicator1, { label: 'An alert indicator:' } )
3661 * $( 'body' ).append( fieldset.$element );
3663 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
3666 * @extends OO.ui.Widget
3667 * @mixins OO.ui.mixin.IndicatorElement
3668 * @mixins OO.ui.mixin.TitledElement
3671 * @param {Object} [config] Configuration options
3673 OO
.ui
.IndicatorWidget
= function OoUiIndicatorWidget( config
) {
3674 // Configuration initialization
3675 config
= config
|| {};
3677 // Parent constructor
3678 OO
.ui
.IndicatorWidget
.parent
.call( this, config
);
3680 // Mixin constructors
3681 OO
.ui
.mixin
.IndicatorElement
.call( this, $.extend( {}, config
, { $indicator
: this.$element
} ) );
3682 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3685 this.$element
.addClass( 'oo-ui-indicatorWidget' );
3690 OO
.inheritClass( OO
.ui
.IndicatorWidget
, OO
.ui
.Widget
);
3691 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.IndicatorElement
);
3692 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.TitledElement
);
3694 /* Static Properties */
3696 OO
.ui
.IndicatorWidget
.static.tagName
= 'span';
3699 * LabelWidgets help identify the function of interface elements. Each LabelWidget can
3700 * be configured with a `label` option that is set to a string, a label node, or a function:
3702 * - String: a plaintext string
3703 * - jQuery selection: a jQuery selection, used for anything other than a plaintext label, e.g., a
3704 * label that includes a link or special styling, such as a gray color or additional graphical elements.
3705 * - Function: a function that will produce a string in the future. Functions are used
3706 * in cases where the value of the label is not currently defined.
3708 * In addition, the LabelWidget can be associated with an {@link OO.ui.InputWidget input widget}, which
3709 * will come into focus when the label is clicked.
3712 * // Examples of LabelWidgets
3713 * var label1 = new OO.ui.LabelWidget( {
3714 * label: 'plaintext label'
3716 * var label2 = new OO.ui.LabelWidget( {
3717 * label: $( '<a href="default.html">jQuery label</a>' )
3719 * // Create a fieldset layout with fields for each example
3720 * var fieldset = new OO.ui.FieldsetLayout();
3721 * fieldset.addItems( [
3722 * new OO.ui.FieldLayout( label1 ),
3723 * new OO.ui.FieldLayout( label2 )
3725 * $( 'body' ).append( fieldset.$element );
3728 * @extends OO.ui.Widget
3729 * @mixins OO.ui.mixin.LabelElement
3732 * @param {Object} [config] Configuration options
3733 * @cfg {OO.ui.InputWidget} [input] {@link OO.ui.InputWidget Input widget} that uses the label.
3734 * Clicking the label will focus the specified input field.
3736 OO
.ui
.LabelWidget
= function OoUiLabelWidget( config
) {
3737 // Configuration initialization
3738 config
= config
|| {};
3740 // Parent constructor
3741 OO
.ui
.LabelWidget
.parent
.call( this, config
);
3743 // Mixin constructors
3744 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, { $label
: this.$element
} ) );
3745 OO
.ui
.mixin
.TitledElement
.call( this, config
);
3748 this.input
= config
.input
;
3751 if ( this.input
instanceof OO
.ui
.InputWidget
) {
3752 this.$element
.on( 'click', this.onClick
.bind( this ) );
3756 this.$element
.addClass( 'oo-ui-labelWidget' );
3761 OO
.inheritClass( OO
.ui
.LabelWidget
, OO
.ui
.Widget
);
3762 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.LabelElement
);
3763 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.TitledElement
);
3765 /* Static Properties */
3767 OO
.ui
.LabelWidget
.static.tagName
= 'span';
3772 * Handles label mouse click events.
3775 * @param {jQuery.Event} e Mouse click event
3777 OO
.ui
.LabelWidget
.prototype.onClick = function () {
3778 this.input
.simulateLabelClick();
3783 * PendingElement is a mixin that is used to create elements that notify users that something is happening
3784 * and that they should wait before proceeding. The pending state is visually represented with a pending
3785 * texture that appears in the head of a pending {@link OO.ui.ProcessDialog process dialog} or in the input
3786 * field of a {@link OO.ui.TextInputWidget text input widget}.
3788 * Currently, {@link OO.ui.ActionWidget Action widgets}, which mix in this class, can also be marked as pending, but only when
3789 * used in {@link OO.ui.MessageDialog message dialogs}. The behavior is not currently supported for action widgets used
3790 * in process dialogs.
3793 * function MessageDialog( config ) {
3794 * MessageDialog.parent.call( this, config );
3796 * OO.inheritClass( MessageDialog, OO.ui.MessageDialog );
3798 * MessageDialog.static.actions = [
3799 * { action: 'save', label: 'Done', flags: 'primary' },
3800 * { label: 'Cancel', flags: 'safe' }
3803 * MessageDialog.prototype.initialize = function () {
3804 * MessageDialog.parent.prototype.initialize.apply( this, arguments );
3805 * this.content = new OO.ui.PanelLayout( { $: this.$, padded: true } );
3806 * 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>' );
3807 * this.$body.append( this.content.$element );
3809 * MessageDialog.prototype.getBodyHeight = function () {
3812 * MessageDialog.prototype.getActionProcess = function ( action ) {
3813 * var dialog = this;
3814 * if ( action === 'save' ) {
3815 * dialog.getActions().get({actions: 'save'})[0].pushPending();
3816 * return new OO.ui.Process()
3818 * .next( function () {
3819 * dialog.getActions().get({actions: 'save'})[0].popPending();
3822 * return MessageDialog.parent.prototype.getActionProcess.call( this, action );
3825 * var windowManager = new OO.ui.WindowManager();
3826 * $( 'body' ).append( windowManager.$element );
3828 * var dialog = new MessageDialog();
3829 * windowManager.addWindows( [ dialog ] );
3830 * windowManager.openWindow( dialog );
3836 * @param {Object} [config] Configuration options
3837 * @cfg {jQuery} [$pending] Element to mark as pending, defaults to this.$element
3839 OO
.ui
.mixin
.PendingElement
= function OoUiMixinPendingElement( config
) {
3840 // Configuration initialization
3841 config
= config
|| {};
3845 this.$pending
= null;
3848 this.setPendingElement( config
.$pending
|| this.$element
);
3853 OO
.initClass( OO
.ui
.mixin
.PendingElement
);
3858 * Set the pending element (and clean up any existing one).
3860 * @param {jQuery} $pending The element to set to pending.
3862 OO
.ui
.mixin
.PendingElement
.prototype.setPendingElement = function ( $pending
) {
3863 if ( this.$pending
) {
3864 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
3867 this.$pending
= $pending
;
3868 if ( this.pending
> 0 ) {
3869 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
3874 * Check if an element is pending.
3876 * @return {boolean} Element is pending
3878 OO
.ui
.mixin
.PendingElement
.prototype.isPending = function () {
3879 return !!this.pending
;
3883 * Increase the pending counter. The pending state will remain active until the counter is zero
3884 * (i.e., the number of calls to #pushPending and #popPending is the same).
3888 OO
.ui
.mixin
.PendingElement
.prototype.pushPending = function () {
3889 if ( this.pending
=== 0 ) {
3890 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
3891 this.updateThemeClasses();
3899 * Decrease the pending counter. The pending state will remain active until the counter is zero
3900 * (i.e., the number of calls to #pushPending and #popPending is the same).
3904 OO
.ui
.mixin
.PendingElement
.prototype.popPending = function () {
3905 if ( this.pending
=== 1 ) {
3906 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
3907 this.updateThemeClasses();
3909 this.pending
= Math
.max( 0, this.pending
- 1 );
3915 * Element that can be automatically clipped to visible boundaries.
3917 * Whenever the element's natural height changes, you have to call
3918 * {@link OO.ui.mixin.ClippableElement#clip} to make sure it's still
3919 * clipping correctly.
3921 * The dimensions of #$clippableContainer will be compared to the boundaries of the
3922 * nearest scrollable container. If #$clippableContainer is too tall and/or too wide,
3923 * then #$clippable will be given a fixed reduced height and/or width and will be made
3924 * scrollable. By default, #$clippable and #$clippableContainer are the same element,
3925 * but you can build a static footer by setting #$clippableContainer to an element that contains
3926 * #$clippable and the footer.
3932 * @param {Object} [config] Configuration options
3933 * @cfg {jQuery} [$clippable] Node to clip, assigned to #$clippable, omit to use #$element
3934 * @cfg {jQuery} [$clippableContainer] Node to keep visible, assigned to #$clippableContainer,
3935 * omit to use #$clippable
3937 OO
.ui
.mixin
.ClippableElement
= function OoUiMixinClippableElement( config
) {
3938 // Configuration initialization
3939 config
= config
|| {};
3942 this.$clippable
= null;
3943 this.$clippableContainer
= null;
3944 this.clipping
= false;
3945 this.clippedHorizontally
= false;
3946 this.clippedVertically
= false;
3947 this.$clippableScrollableContainer
= null;
3948 this.$clippableScroller
= null;
3949 this.$clippableWindow
= null;
3950 this.idealWidth
= null;
3951 this.idealHeight
= null;
3952 this.onClippableScrollHandler
= this.clip
.bind( this );
3953 this.onClippableWindowResizeHandler
= this.clip
.bind( this );
3956 if ( config
.$clippableContainer
) {
3957 this.setClippableContainer( config
.$clippableContainer
);
3959 this.setClippableElement( config
.$clippable
|| this.$element
);
3965 * Set clippable element.
3967 * If an element is already set, it will be cleaned up before setting up the new element.
3969 * @param {jQuery} $clippable Element to make clippable
3971 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableElement = function ( $clippable
) {
3972 if ( this.$clippable
) {
3973 this.$clippable
.removeClass( 'oo-ui-clippableElement-clippable' );
3974 this.$clippable
.css( { width
: '', height
: '', overflowX
: '', overflowY
: '' } );
3975 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
3978 this.$clippable
= $clippable
.addClass( 'oo-ui-clippableElement-clippable' );
3983 * Set clippable container.
3985 * This is the container that will be measured when deciding whether to clip. When clipping,
3986 * #$clippable will be resized in order to keep the clippable container fully visible.
3988 * If the clippable container is unset, #$clippable will be used.
3990 * @param {jQuery|null} $clippableContainer Container to keep visible, or null to unset
3992 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableContainer = function ( $clippableContainer
) {
3993 this.$clippableContainer
= $clippableContainer
;
3994 if ( this.$clippable
) {
4002 * Do not turn clipping on until after the element is attached to the DOM and visible.
4004 * @param {boolean} [clipping] Enable clipping, omit to toggle
4007 OO
.ui
.mixin
.ClippableElement
.prototype.toggleClipping = function ( clipping
) {
4008 clipping
= clipping
=== undefined ? !this.clipping
: !!clipping
;
4010 if ( this.clipping
!== clipping
) {
4011 this.clipping
= clipping
;
4013 this.$clippableScrollableContainer
= $( this.getClosestScrollableElementContainer() );
4014 // If the clippable container is the root, we have to listen to scroll events and check
4015 // jQuery.scrollTop on the window because of browser inconsistencies
4016 this.$clippableScroller
= this.$clippableScrollableContainer
.is( 'html, body' ) ?
4017 $( OO
.ui
.Element
.static.getWindow( this.$clippableScrollableContainer
) ) :
4018 this.$clippableScrollableContainer
;
4019 this.$clippableScroller
.on( 'scroll', this.onClippableScrollHandler
);
4020 this.$clippableWindow
= $( this.getElementWindow() )
4021 .on( 'resize', this.onClippableWindowResizeHandler
);
4022 // Initial clip after visible
4025 this.$clippable
.css( { width
: '', height
: '', overflowX
: '', overflowY
: '' } );
4026 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4028 this.$clippableScrollableContainer
= null;
4029 this.$clippableScroller
.off( 'scroll', this.onClippableScrollHandler
);
4030 this.$clippableScroller
= null;
4031 this.$clippableWindow
.off( 'resize', this.onClippableWindowResizeHandler
);
4032 this.$clippableWindow
= null;
4040 * Check if the element will be clipped to fit the visible area of the nearest scrollable container.
4042 * @return {boolean} Element will be clipped to the visible area
4044 OO
.ui
.mixin
.ClippableElement
.prototype.isClipping = function () {
4045 return this.clipping
;
4049 * Check if the bottom or right of the element is being clipped by the nearest scrollable container.
4051 * @return {boolean} Part of the element is being clipped
4053 OO
.ui
.mixin
.ClippableElement
.prototype.isClipped = function () {
4054 return this.clippedHorizontally
|| this.clippedVertically
;
4058 * Check if the right of the element is being clipped by the nearest scrollable container.
4060 * @return {boolean} Part of the element is being clipped
4062 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedHorizontally = function () {
4063 return this.clippedHorizontally
;
4067 * Check if the bottom of the element is being clipped by the nearest scrollable container.
4069 * @return {boolean} Part of the element is being clipped
4071 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedVertically = function () {
4072 return this.clippedVertically
;
4076 * Set the ideal size. These are the dimensions the element will have when it's not being clipped.
4078 * @param {number|string} [width] Width as a number of pixels or CSS string with unit suffix
4079 * @param {number|string} [height] Height as a number of pixels or CSS string with unit suffix
4081 OO
.ui
.mixin
.ClippableElement
.prototype.setIdealSize = function ( width
, height
) {
4082 this.idealWidth
= width
;
4083 this.idealHeight
= height
;
4085 if ( !this.clipping
) {
4086 // Update dimensions
4087 this.$clippable
.css( { width
: width
, height
: height
} );
4089 // While clipping, idealWidth and idealHeight are not considered
4093 * Clip element to visible boundaries and allow scrolling when needed. You should call this method
4094 * when the element's natural height changes.
4096 * Element will be clipped the bottom or right of the element is within 10px of the edge of, or
4097 * overlapped by, the visible area of the nearest scrollable container.
4099 * Because calling clip() when the natural height changes isn't always possible, we also set
4100 * max-height when the element isn't being clipped. This means that if the element tries to grow
4101 * beyond the edge, something reasonable will happen before clip() is called.
4105 OO
.ui
.mixin
.ClippableElement
.prototype.clip = function () {
4106 var $container
, extraHeight
, extraWidth
, ccOffset
,
4107 $scrollableContainer
, scOffset
, scHeight
, scWidth
,
4108 ccWidth
, scrollerIsWindow
, scrollTop
, scrollLeft
,
4109 desiredWidth
, desiredHeight
, allotedWidth
, allotedHeight
,
4110 naturalWidth
, naturalHeight
, clipWidth
, clipHeight
,
4111 buffer
= 7; // Chosen by fair dice roll
4113 if ( !this.clipping
) {
4114 // this.$clippableScrollableContainer and this.$clippableWindow are null, so the below will fail
4118 $container
= this.$clippableContainer
|| this.$clippable
;
4119 extraHeight
= $container
.outerHeight() - this.$clippable
.outerHeight();
4120 extraWidth
= $container
.outerWidth() - this.$clippable
.outerWidth();
4121 ccOffset
= $container
.offset();
4122 $scrollableContainer
= this.$clippableScrollableContainer
.is( 'html, body' ) ?
4123 this.$clippableWindow
: this.$clippableScrollableContainer
;
4124 scOffset
= $scrollableContainer
.offset() || { top
: 0, left
: 0 };
4125 scHeight
= $scrollableContainer
.innerHeight() - buffer
;
4126 scWidth
= $scrollableContainer
.innerWidth() - buffer
;
4127 ccWidth
= $container
.outerWidth() + buffer
;
4128 scrollerIsWindow
= this.$clippableScroller
[ 0 ] === this.$clippableWindow
[ 0 ];
4129 scrollTop
= scrollerIsWindow
? this.$clippableScroller
.scrollTop() : 0;
4130 scrollLeft
= scrollerIsWindow
? this.$clippableScroller
.scrollLeft() : 0;
4131 desiredWidth
= ccOffset
.left
< 0 ?
4132 ccWidth
+ ccOffset
.left
:
4133 ( scOffset
.left
+ scrollLeft
+ scWidth
) - ccOffset
.left
;
4134 desiredHeight
= ( scOffset
.top
+ scrollTop
+ scHeight
) - ccOffset
.top
;
4135 // It should never be desirable to exceed the dimensions of the browser viewport... right?
4136 desiredWidth
= Math
.min( desiredWidth
, document
.documentElement
.clientWidth
);
4137 desiredHeight
= Math
.min( desiredHeight
, document
.documentElement
.clientHeight
);
4138 allotedWidth
= Math
.ceil( desiredWidth
- extraWidth
);
4139 allotedHeight
= Math
.ceil( desiredHeight
- extraHeight
);
4140 naturalWidth
= this.$clippable
.prop( 'scrollWidth' );
4141 naturalHeight
= this.$clippable
.prop( 'scrollHeight' );
4142 clipWidth
= allotedWidth
< naturalWidth
;
4143 clipHeight
= allotedHeight
< naturalHeight
;
4146 this.$clippable
.css( {
4147 overflowX
: 'scroll',
4148 width
: Math
.max( 0, allotedWidth
),
4152 this.$clippable
.css( {
4154 width
: this.idealWidth
? this.idealWidth
- extraWidth
: '',
4155 maxWidth
: Math
.max( 0, allotedWidth
)
4159 this.$clippable
.css( {
4160 overflowY
: 'scroll',
4161 height
: Math
.max( 0, allotedHeight
),
4165 this.$clippable
.css( {
4167 height
: this.idealHeight
? this.idealHeight
- extraHeight
: '',
4168 maxHeight
: Math
.max( 0, allotedHeight
)
4172 // If we stopped clipping in at least one of the dimensions
4173 if ( ( this.clippedHorizontally
&& !clipWidth
) || ( this.clippedVertically
&& !clipHeight
) ) {
4174 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4177 this.clippedHorizontally
= clipWidth
;
4178 this.clippedVertically
= clipHeight
;
4184 * PopupWidget is a container for content. The popup is overlaid and positioned absolutely.
4185 * By default, each popup has an anchor that points toward its origin.
4186 * Please see the [OOjs UI documentation on Mediawiki] [1] for more information and examples.
4189 * // A popup widget.
4190 * var popup = new OO.ui.PopupWidget( {
4191 * $content: $( '<p>Hi there!</p>' ),
4196 * $( 'body' ).append( popup.$element );
4197 * // To display the popup, toggle the visibility to 'true'.
4198 * popup.toggle( true );
4200 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups
4203 * @extends OO.ui.Widget
4204 * @mixins OO.ui.mixin.LabelElement
4205 * @mixins OO.ui.mixin.ClippableElement
4208 * @param {Object} [config] Configuration options
4209 * @cfg {number} [width=320] Width of popup in pixels
4210 * @cfg {number} [height] Height of popup in pixels. Omit to use the automatic height.
4211 * @cfg {boolean} [anchor=true] Show anchor pointing to origin of popup
4212 * @cfg {string} [align='center'] Alignment of the popup: `center`, `force-left`, `force-right`, `backwards` or `forwards`.
4213 * If the popup is forced-left the popup body is leaning towards the left. For force-right alignment, the body of the
4214 * popup is leaning towards the right of the screen.
4215 * Using 'backwards' is a logical direction which will result in the popup leaning towards the beginning of the sentence
4216 * in the given language, which means it will flip to the correct positioning in right-to-left languages.
4217 * Using 'forward' will also result in a logical alignment where the body of the popup leans towards the end of the
4218 * sentence in the given language.
4219 * @cfg {jQuery} [$container] Constrain the popup to the boundaries of the specified container.
4220 * See the [OOjs UI docs on MediaWiki][3] for an example.
4221 * [3]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#containerExample
4222 * @cfg {number} [containerPadding=10] Padding between the popup and its container, specified as a number of pixels.
4223 * @cfg {jQuery} [$content] Content to append to the popup's body
4224 * @cfg {jQuery} [$footer] Content to append to the popup's footer
4225 * @cfg {boolean} [autoClose=false] Automatically close the popup when it loses focus.
4226 * @cfg {jQuery} [$autoCloseIgnore] Elements that will not close the popup when clicked.
4227 * This config option is only relevant if #autoClose is set to `true`. See the [OOjs UI docs on MediaWiki][2]
4229 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#autocloseExample
4230 * @cfg {boolean} [head=false] Show a popup header that contains a #label (if specified) and close
4232 * @cfg {boolean} [padded=false] Add padding to the popup's body
4234 OO
.ui
.PopupWidget
= function OoUiPopupWidget( config
) {
4235 // Configuration initialization
4236 config
= config
|| {};
4238 // Parent constructor
4239 OO
.ui
.PopupWidget
.parent
.call( this, config
);
4241 // Properties (must be set before ClippableElement constructor call)
4242 this.$body
= $( '<div>' );
4243 this.$popup
= $( '<div>' );
4245 // Mixin constructors
4246 OO
.ui
.mixin
.LabelElement
.call( this, config
);
4247 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, {
4248 $clippable
: this.$body
,
4249 $clippableContainer
: this.$popup
4253 this.$anchor
= $( '<div>' );
4254 // If undefined, will be computed lazily in updateDimensions()
4255 this.$container
= config
.$container
;
4256 this.containerPadding
= config
.containerPadding
!== undefined ? config
.containerPadding
: 10;
4257 this.autoClose
= !!config
.autoClose
;
4258 this.$autoCloseIgnore
= config
.$autoCloseIgnore
;
4259 this.transitionTimeout
= null;
4261 this.width
= config
.width
!== undefined ? config
.width
: 320;
4262 this.height
= config
.height
!== undefined ? config
.height
: null;
4263 this.setAlignment( config
.align
);
4264 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
4265 this.onDocumentKeyDownHandler
= this.onDocumentKeyDown
.bind( this );
4268 this.toggleAnchor( config
.anchor
=== undefined || config
.anchor
);
4269 this.$body
.addClass( 'oo-ui-popupWidget-body' );
4270 this.$anchor
.addClass( 'oo-ui-popupWidget-anchor' );
4272 .addClass( 'oo-ui-popupWidget-popup' )
4273 .append( this.$body
);
4275 .addClass( 'oo-ui-popupWidget' )
4276 .append( this.$popup
, this.$anchor
);
4277 // Move content, which was added to #$element by OO.ui.Widget, to the body
4278 // FIXME This is gross, we should use '$body' or something for the config
4279 if ( config
.$content
instanceof jQuery
) {
4280 this.$body
.append( config
.$content
);
4283 if ( config
.padded
) {
4284 this.$body
.addClass( 'oo-ui-popupWidget-body-padded' );
4287 if ( config
.head
) {
4288 this.closeButton
= new OO
.ui
.ButtonWidget( { framed
: false, icon
: 'close' } );
4289 this.closeButton
.connect( this, { click
: 'onCloseButtonClick' } );
4290 this.$head
= $( '<div>' )
4291 .addClass( 'oo-ui-popupWidget-head' )
4292 .append( this.$label
, this.closeButton
.$element
);
4293 this.$popup
.prepend( this.$head
);
4296 if ( config
.$footer
) {
4297 this.$footer
= $( '<div>' )
4298 .addClass( 'oo-ui-popupWidget-footer' )
4299 .append( config
.$footer
);
4300 this.$popup
.append( this.$footer
);
4303 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
4304 // that reference properties not initialized at that time of parent class construction
4305 // TODO: Find a better way to handle post-constructor setup
4306 this.visible
= false;
4307 this.$element
.addClass( 'oo-ui-element-hidden' );
4312 OO
.inheritClass( OO
.ui
.PopupWidget
, OO
.ui
.Widget
);
4313 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.LabelElement
);
4314 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.ClippableElement
);
4319 * Handles mouse down events.
4322 * @param {MouseEvent} e Mouse down event
4324 OO
.ui
.PopupWidget
.prototype.onMouseDown = function ( e
) {
4327 !$.contains( this.$element
[ 0 ], e
.target
) &&
4328 ( !this.$autoCloseIgnore
|| !this.$autoCloseIgnore
.has( e
.target
).length
)
4330 this.toggle( false );
4335 * Bind mouse down listener.
4339 OO
.ui
.PopupWidget
.prototype.bindMouseDownListener = function () {
4340 // Capture clicks outside popup
4341 this.getElementWindow().addEventListener( 'mousedown', this.onMouseDownHandler
, true );
4345 * Handles close button click events.
4349 OO
.ui
.PopupWidget
.prototype.onCloseButtonClick = function () {
4350 if ( this.isVisible() ) {
4351 this.toggle( false );
4356 * Unbind mouse down listener.
4360 OO
.ui
.PopupWidget
.prototype.unbindMouseDownListener = function () {
4361 this.getElementWindow().removeEventListener( 'mousedown', this.onMouseDownHandler
, true );
4365 * Handles key down events.
4368 * @param {KeyboardEvent} e Key down event
4370 OO
.ui
.PopupWidget
.prototype.onDocumentKeyDown = function ( e
) {
4372 e
.which
=== OO
.ui
.Keys
.ESCAPE
&&
4375 this.toggle( false );
4377 e
.stopPropagation();
4382 * Bind key down listener.
4386 OO
.ui
.PopupWidget
.prototype.bindKeyDownListener = function () {
4387 this.getElementWindow().addEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
4391 * Unbind key down listener.
4395 OO
.ui
.PopupWidget
.prototype.unbindKeyDownListener = function () {
4396 this.getElementWindow().removeEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
4400 * Show, hide, or toggle the visibility of the anchor.
4402 * @param {boolean} [show] Show anchor, omit to toggle
4404 OO
.ui
.PopupWidget
.prototype.toggleAnchor = function ( show
) {
4405 show
= show
=== undefined ? !this.anchored
: !!show
;
4407 if ( this.anchored
!== show
) {
4409 this.$element
.addClass( 'oo-ui-popupWidget-anchored' );
4411 this.$element
.removeClass( 'oo-ui-popupWidget-anchored' );
4413 this.anchored
= show
;
4418 * Check if the anchor is visible.
4420 * @return {boolean} Anchor is visible
4422 OO
.ui
.PopupWidget
.prototype.hasAnchor = function () {
4429 OO
.ui
.PopupWidget
.prototype.toggle = function ( show
) {
4431 show
= show
=== undefined ? !this.isVisible() : !!show
;
4433 change
= show
!== this.isVisible();
4436 OO
.ui
.PopupWidget
.parent
.prototype.toggle
.call( this, show
);
4440 if ( this.autoClose
) {
4441 this.bindMouseDownListener();
4442 this.bindKeyDownListener();
4444 this.updateDimensions();
4445 this.toggleClipping( true );
4447 this.toggleClipping( false );
4448 if ( this.autoClose
) {
4449 this.unbindMouseDownListener();
4450 this.unbindKeyDownListener();
4459 * Set the size of the popup.
4461 * Changing the size may also change the popup's position depending on the alignment.
4463 * @param {number} width Width in pixels
4464 * @param {number} height Height in pixels
4465 * @param {boolean} [transition=false] Use a smooth transition
4468 OO
.ui
.PopupWidget
.prototype.setSize = function ( width
, height
, transition
) {
4470 this.height
= height
!== undefined ? height
: null;
4471 if ( this.isVisible() ) {
4472 this.updateDimensions( transition
);
4477 * Update the size and position.
4479 * Only use this to keep the popup properly anchored. Use #setSize to change the size, and this will
4480 * be called automatically.
4482 * @param {boolean} [transition=false] Use a smooth transition
4485 OO
.ui
.PopupWidget
.prototype.updateDimensions = function ( transition
) {
4486 var popupOffset
, originOffset
, containerLeft
, containerWidth
, containerRight
,
4487 popupLeft
, popupRight
, overlapLeft
, overlapRight
, anchorWidth
,
4491 if ( !this.$container
) {
4492 // Lazy-initialize $container if not specified in constructor
4493 this.$container
= $( this.getClosestScrollableElementContainer() );
4496 // Set height and width before measuring things, since it might cause our measurements
4497 // to change (e.g. due to scrollbars appearing or disappearing)
4500 height
: this.height
!== null ? this.height
: 'auto'
4503 // If we are in RTL, we need to flip the alignment, unless it is center
4504 if ( align
=== 'forwards' || align
=== 'backwards' ) {
4505 if ( this.$container
.css( 'direction' ) === 'rtl' ) {
4506 align
= ( { forwards
: 'force-left', backwards
: 'force-right' } )[ this.align
];
4508 align
= ( { forwards
: 'force-right', backwards
: 'force-left' } )[ this.align
];
4513 // Compute initial popupOffset based on alignment
4514 popupOffset
= this.width
* ( { 'force-left': -1, center
: -0.5, 'force-right': 0 } )[ align
];
4516 // Figure out if this will cause the popup to go beyond the edge of the container
4517 originOffset
= this.$element
.offset().left
;
4518 containerLeft
= this.$container
.offset().left
;
4519 containerWidth
= this.$container
.innerWidth();
4520 containerRight
= containerLeft
+ containerWidth
;
4521 popupLeft
= popupOffset
- this.containerPadding
;
4522 popupRight
= popupOffset
+ this.containerPadding
+ this.width
+ this.containerPadding
;
4523 overlapLeft
= ( originOffset
+ popupLeft
) - containerLeft
;
4524 overlapRight
= containerRight
- ( originOffset
+ popupRight
);
4526 // Adjust offset to make the popup not go beyond the edge, if needed
4527 if ( overlapRight
< 0 ) {
4528 popupOffset
+= overlapRight
;
4529 } else if ( overlapLeft
< 0 ) {
4530 popupOffset
-= overlapLeft
;
4533 // Adjust offset to avoid anchor being rendered too close to the edge
4534 // $anchor.width() doesn't work with the pure CSS anchor (returns 0)
4535 // TODO: Find a measurement that works for CSS anchors and image anchors
4536 anchorWidth
= this.$anchor
[ 0 ].scrollWidth
* 2;
4537 if ( popupOffset
+ this.width
< anchorWidth
) {
4538 popupOffset
= anchorWidth
- this.width
;
4539 } else if ( -popupOffset
< anchorWidth
) {
4540 popupOffset
= -anchorWidth
;
4543 // Prevent transition from being interrupted
4544 clearTimeout( this.transitionTimeout
);
4546 // Enable transition
4547 this.$element
.addClass( 'oo-ui-popupWidget-transitioning' );
4550 // Position body relative to anchor
4551 this.$popup
.css( 'margin-left', popupOffset
);
4554 // Prevent transitioning after transition is complete
4555 this.transitionTimeout
= setTimeout( function () {
4556 widget
.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
4559 // Prevent transitioning immediately
4560 this.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
4563 // Reevaluate clipping state since we've relocated and resized the popup
4570 * Set popup alignment
4572 * @param {string} align Alignment of the popup, `center`, `force-left`, `force-right`,
4573 * `backwards` or `forwards`.
4575 OO
.ui
.PopupWidget
.prototype.setAlignment = function ( align
) {
4576 // Validate alignment and transform deprecated values
4577 if ( [ 'left', 'right', 'force-left', 'force-right', 'backwards', 'forwards', 'center' ].indexOf( align
) > -1 ) {
4578 this.align
= { left
: 'force-right', right
: 'force-left' }[ align
] || align
;
4580 this.align
= 'center';
4585 * Get popup alignment
4587 * @return {string} align Alignment of the popup, `center`, `force-left`, `force-right`,
4588 * `backwards` or `forwards`.
4590 OO
.ui
.PopupWidget
.prototype.getAlignment = function () {
4595 * PopupElement is mixed into other classes to generate a {@link OO.ui.PopupWidget popup widget}.
4596 * A popup is a container for content. It is overlaid and positioned absolutely. By default, each
4597 * popup has an anchor, which is an arrow-like protrusion that points toward the popup’s origin.
4598 * See {@link OO.ui.PopupWidget PopupWidget} for an example.
4604 * @param {Object} [config] Configuration options
4605 * @cfg {Object} [popup] Configuration to pass to popup
4606 * @cfg {boolean} [popup.autoClose=true] Popup auto-closes when it loses focus
4608 OO
.ui
.mixin
.PopupElement
= function OoUiMixinPopupElement( config
) {
4609 // Configuration initialization
4610 config
= config
|| {};
4613 this.popup
= new OO
.ui
.PopupWidget( $.extend(
4614 { autoClose
: true },
4616 { $autoCloseIgnore
: this.$element
}
4625 * @return {OO.ui.PopupWidget} Popup widget
4627 OO
.ui
.mixin
.PopupElement
.prototype.getPopup = function () {
4632 * PopupButtonWidgets toggle the visibility of a contained {@link OO.ui.PopupWidget PopupWidget},
4633 * which is used to display additional information or options.
4636 * // Example of a popup button.
4637 * var popupButton = new OO.ui.PopupButtonWidget( {
4638 * label: 'Popup button with options',
4641 * $content: $( '<p>Additional options here.</p>' ),
4643 * align: 'force-left'
4646 * // Append the button to the DOM.
4647 * $( 'body' ).append( popupButton.$element );
4650 * @extends OO.ui.ButtonWidget
4651 * @mixins OO.ui.mixin.PopupElement
4654 * @param {Object} [config] Configuration options
4656 OO
.ui
.PopupButtonWidget
= function OoUiPopupButtonWidget( config
) {
4657 // Parent constructor
4658 OO
.ui
.PopupButtonWidget
.parent
.call( this, config
);
4660 // Mixin constructors
4661 OO
.ui
.mixin
.PopupElement
.call( this, config
);
4664 this.connect( this, { click
: 'onAction' } );
4668 .addClass( 'oo-ui-popupButtonWidget' )
4669 .attr( 'aria-haspopup', 'true' )
4670 .append( this.popup
.$element
);
4675 OO
.inheritClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.ButtonWidget
);
4676 OO
.mixinClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.mixin
.PopupElement
);
4681 * Handle the button action being triggered.
4685 OO
.ui
.PopupButtonWidget
.prototype.onAction = function () {
4686 this.popup
.toggle();
4690 * Mixin for OO.ui.Widget subclasses to provide OO.ui.mixin.GroupElement.
4692 * Use together with OO.ui.mixin.ItemWidget to make disabled state inheritable.
4697 * @mixins OO.ui.mixin.GroupElement
4700 * @param {Object} [config] Configuration options
4702 OO
.ui
.mixin
.GroupWidget
= function OoUiMixinGroupWidget( config
) {
4703 // Mixin constructors
4704 OO
.ui
.mixin
.GroupElement
.call( this, config
);
4709 OO
.mixinClass( OO
.ui
.mixin
.GroupWidget
, OO
.ui
.mixin
.GroupElement
);
4714 * Set the disabled state of the widget.
4716 * This will also update the disabled state of child widgets.
4718 * @param {boolean} disabled Disable widget
4721 OO
.ui
.mixin
.GroupWidget
.prototype.setDisabled = function ( disabled
) {
4725 // Note: Calling #setDisabled this way assumes this is mixed into an OO.ui.Widget
4726 OO
.ui
.Widget
.prototype.setDisabled
.call( this, disabled
);
4728 // During construction, #setDisabled is called before the OO.ui.mixin.GroupElement constructor
4730 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
4731 this.items
[ i
].updateDisabled();
4739 * Mixin for widgets used as items in widgets that mix in OO.ui.mixin.GroupWidget.
4741 * Item widgets have a reference to a OO.ui.mixin.GroupWidget while they are attached to the group. This
4742 * allows bidirectional communication.
4744 * Use together with OO.ui.mixin.GroupWidget to make disabled state inheritable.
4752 OO
.ui
.mixin
.ItemWidget
= function OoUiMixinItemWidget() {
4759 * Check if widget is disabled.
4761 * Checks parent if present, making disabled state inheritable.
4763 * @return {boolean} Widget is disabled
4765 OO
.ui
.mixin
.ItemWidget
.prototype.isDisabled = function () {
4766 return this.disabled
||
4767 ( this.elementGroup
instanceof OO
.ui
.Widget
&& this.elementGroup
.isDisabled() );
4771 * Set group element is in.
4773 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
4776 OO
.ui
.mixin
.ItemWidget
.prototype.setElementGroup = function ( group
) {
4778 // Note: Calling #setElementGroup this way assumes this is mixed into an OO.ui.Element
4779 OO
.ui
.Element
.prototype.setElementGroup
.call( this, group
);
4781 // Initialize item disabled states
4782 this.updateDisabled();
4788 * OptionWidgets are special elements that can be selected and configured with data. The
4789 * data is often unique for each option, but it does not have to be. OptionWidgets are used
4790 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
4791 * and examples, please see the [OOjs UI documentation on MediaWiki][1].
4793 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
4796 * @extends OO.ui.Widget
4797 * @mixins OO.ui.mixin.ItemWidget
4798 * @mixins OO.ui.mixin.LabelElement
4799 * @mixins OO.ui.mixin.FlaggedElement
4800 * @mixins OO.ui.mixin.AccessKeyedElement
4803 * @param {Object} [config] Configuration options
4805 OO
.ui
.OptionWidget
= function OoUiOptionWidget( config
) {
4806 // Configuration initialization
4807 config
= config
|| {};
4809 // Parent constructor
4810 OO
.ui
.OptionWidget
.parent
.call( this, config
);
4812 // Mixin constructors
4813 OO
.ui
.mixin
.ItemWidget
.call( this );
4814 OO
.ui
.mixin
.LabelElement
.call( this, config
);
4815 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
4816 OO
.ui
.mixin
.AccessKeyedElement
.call( this, config
);
4819 this.selected
= false;
4820 this.highlighted
= false;
4821 this.pressed
= false;
4825 .data( 'oo-ui-optionWidget', this )
4826 // Allow programmatic focussing (and by accesskey), but not tabbing
4827 .attr( 'tabindex', '-1' )
4828 .attr( 'role', 'option' )
4829 .attr( 'aria-selected', 'false' )
4830 .addClass( 'oo-ui-optionWidget' )
4831 .append( this.$label
);
4836 OO
.inheritClass( OO
.ui
.OptionWidget
, OO
.ui
.Widget
);
4837 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.ItemWidget
);
4838 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.LabelElement
);
4839 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.FlaggedElement
);
4840 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
4842 /* Static Properties */
4844 OO
.ui
.OptionWidget
.static.selectable
= true;
4846 OO
.ui
.OptionWidget
.static.highlightable
= true;
4848 OO
.ui
.OptionWidget
.static.pressable
= true;
4850 OO
.ui
.OptionWidget
.static.scrollIntoViewOnSelect
= false;
4855 * Check if the option can be selected.
4857 * @return {boolean} Item is selectable
4859 OO
.ui
.OptionWidget
.prototype.isSelectable = function () {
4860 return this.constructor.static.selectable
&& !this.isDisabled() && this.isVisible();
4864 * Check if the option can be highlighted. A highlight indicates that the option
4865 * may be selected when a user presses enter or clicks. Disabled items cannot
4868 * @return {boolean} Item is highlightable
4870 OO
.ui
.OptionWidget
.prototype.isHighlightable = function () {
4871 return this.constructor.static.highlightable
&& !this.isDisabled() && this.isVisible();
4875 * Check if the option can be pressed. The pressed state occurs when a user mouses
4876 * down on an item, but has not yet let go of the mouse.
4878 * @return {boolean} Item is pressable
4880 OO
.ui
.OptionWidget
.prototype.isPressable = function () {
4881 return this.constructor.static.pressable
&& !this.isDisabled() && this.isVisible();
4885 * Check if the option is selected.
4887 * @return {boolean} Item is selected
4889 OO
.ui
.OptionWidget
.prototype.isSelected = function () {
4890 return this.selected
;
4894 * Check if the option is highlighted. A highlight indicates that the
4895 * item may be selected when a user presses enter or clicks.
4897 * @return {boolean} Item is highlighted
4899 OO
.ui
.OptionWidget
.prototype.isHighlighted = function () {
4900 return this.highlighted
;
4904 * Check if the option is pressed. The pressed state occurs when a user mouses
4905 * down on an item, but has not yet let go of the mouse. The item may appear
4906 * selected, but it will not be selected until the user releases the mouse.
4908 * @return {boolean} Item is pressed
4910 OO
.ui
.OptionWidget
.prototype.isPressed = function () {
4911 return this.pressed
;
4915 * Set the option’s selected state. In general, all modifications to the selection
4916 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
4917 * method instead of this method.
4919 * @param {boolean} [state=false] Select option
4922 OO
.ui
.OptionWidget
.prototype.setSelected = function ( state
) {
4923 if ( this.constructor.static.selectable
) {
4924 this.selected
= !!state
;
4926 .toggleClass( 'oo-ui-optionWidget-selected', state
)
4927 .attr( 'aria-selected', state
.toString() );
4928 if ( state
&& this.constructor.static.scrollIntoViewOnSelect
) {
4929 this.scrollElementIntoView();
4931 this.updateThemeClasses();
4937 * Set the option’s highlighted state. In general, all programmatic
4938 * modifications to the highlight should be handled by the
4939 * SelectWidget’s {@link OO.ui.SelectWidget#highlightItem highlightItem( [item] )}
4940 * method instead of this method.
4942 * @param {boolean} [state=false] Highlight option
4945 OO
.ui
.OptionWidget
.prototype.setHighlighted = function ( state
) {
4946 if ( this.constructor.static.highlightable
) {
4947 this.highlighted
= !!state
;
4948 this.$element
.toggleClass( 'oo-ui-optionWidget-highlighted', state
);
4949 this.updateThemeClasses();
4955 * Set the option’s pressed state. In general, all
4956 * programmatic modifications to the pressed state should be handled by the
4957 * SelectWidget’s {@link OO.ui.SelectWidget#pressItem pressItem( [item] )}
4958 * method instead of this method.
4960 * @param {boolean} [state=false] Press option
4963 OO
.ui
.OptionWidget
.prototype.setPressed = function ( state
) {
4964 if ( this.constructor.static.pressable
) {
4965 this.pressed
= !!state
;
4966 this.$element
.toggleClass( 'oo-ui-optionWidget-pressed', state
);
4967 this.updateThemeClasses();
4973 * A SelectWidget is of a generic selection of options. The OOjs UI library contains several types of
4974 * select widgets, including {@link OO.ui.ButtonSelectWidget button selects},
4975 * {@link OO.ui.RadioSelectWidget radio selects}, and {@link OO.ui.MenuSelectWidget
4978 * This class should be used together with OO.ui.OptionWidget or OO.ui.DecoratedOptionWidget. For more
4979 * information, please see the [OOjs UI documentation on MediaWiki][1].
4982 * // Example of a select widget with three options
4983 * var select = new OO.ui.SelectWidget( {
4985 * new OO.ui.OptionWidget( {
4987 * label: 'Option One',
4989 * new OO.ui.OptionWidget( {
4991 * label: 'Option Two',
4993 * new OO.ui.OptionWidget( {
4995 * label: 'Option Three',
4999 * $( 'body' ).append( select.$element );
5001 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5005 * @extends OO.ui.Widget
5006 * @mixins OO.ui.mixin.GroupWidget
5009 * @param {Object} [config] Configuration options
5010 * @cfg {OO.ui.OptionWidget[]} [items] An array of options to add to the select.
5011 * Options are created with {@link OO.ui.OptionWidget OptionWidget} classes. See
5012 * the [OOjs UI documentation on MediaWiki] [2] for examples.
5013 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5015 OO
.ui
.SelectWidget
= function OoUiSelectWidget( config
) {
5016 // Configuration initialization
5017 config
= config
|| {};
5019 // Parent constructor
5020 OO
.ui
.SelectWidget
.parent
.call( this, config
);
5022 // Mixin constructors
5023 OO
.ui
.mixin
.GroupWidget
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
5026 this.pressed
= false;
5027 this.selecting
= null;
5028 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
5029 this.onMouseMoveHandler
= this.onMouseMove
.bind( this );
5030 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
5031 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
5032 this.keyPressBuffer
= '';
5033 this.keyPressBufferTimer
= null;
5034 this.blockMouseOverEvents
= 0;
5037 this.connect( this, {
5041 focusin
: this.onFocus
.bind( this ),
5042 mousedown
: this.onMouseDown
.bind( this ),
5043 mouseover
: this.onMouseOver
.bind( this ),
5044 mouseleave
: this.onMouseLeave
.bind( this )
5049 .addClass( 'oo-ui-selectWidget oo-ui-selectWidget-depressed' )
5050 .attr( 'role', 'listbox' );
5051 if ( Array
.isArray( config
.items
) ) {
5052 this.addItems( config
.items
);
5058 OO
.inheritClass( OO
.ui
.SelectWidget
, OO
.ui
.Widget
);
5059 OO
.mixinClass( OO
.ui
.SelectWidget
, OO
.ui
.mixin
.GroupWidget
);
5066 * A `highlight` event is emitted when the highlight is changed with the #highlightItem method.
5068 * @param {OO.ui.OptionWidget|null} item Highlighted item
5074 * A `press` event is emitted when the #pressItem method is used to programmatically modify the
5075 * pressed state of an option.
5077 * @param {OO.ui.OptionWidget|null} item Pressed item
5083 * A `select` event is emitted when the selection is modified programmatically with the #selectItem method.
5085 * @param {OO.ui.OptionWidget|null} item Selected item
5090 * A `choose` event is emitted when an item is chosen with the #chooseItem method.
5091 * @param {OO.ui.OptionWidget} item Chosen item
5097 * An `add` event is emitted when options are added to the select with the #addItems method.
5099 * @param {OO.ui.OptionWidget[]} items Added items
5100 * @param {number} index Index of insertion point
5106 * A `remove` event is emitted when options are removed from the select with the #clearItems
5107 * or #removeItems methods.
5109 * @param {OO.ui.OptionWidget[]} items Removed items
5115 * Handle focus events
5118 * @param {jQuery.Event} event
5120 OO
.ui
.SelectWidget
.prototype.onFocus = function ( event
) {
5122 if ( event
.target
=== this.$element
[ 0 ] ) {
5123 // This widget was focussed, e.g. by the user tabbing to it.
5124 // The styles for focus state depend on one of the items being selected.
5125 if ( !this.getSelectedItem() ) {
5126 item
= this.getFirstSelectableItem();
5129 // One of the options got focussed (and the event bubbled up here).
5130 // They can't be tabbed to, but they can be activated using accesskeys.
5131 item
= this.getTargetItem( event
);
5135 if ( item
.constructor.static.highlightable
) {
5136 this.highlightItem( item
);
5138 this.selectItem( item
);
5142 if ( event
.target
!== this.$element
[ 0 ] ) {
5143 this.$element
.focus();
5148 * Handle mouse down events.
5151 * @param {jQuery.Event} e Mouse down event
5153 OO
.ui
.SelectWidget
.prototype.onMouseDown = function ( e
) {
5156 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
5157 this.togglePressed( true );
5158 item
= this.getTargetItem( e
);
5159 if ( item
&& item
.isSelectable() ) {
5160 this.pressItem( item
);
5161 this.selecting
= item
;
5162 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
5163 this.getElementDocument().addEventListener( 'mousemove', this.onMouseMoveHandler
, true );
5170 * Handle mouse up events.
5173 * @param {MouseEvent} e Mouse up event
5175 OO
.ui
.SelectWidget
.prototype.onMouseUp = function ( e
) {
5178 this.togglePressed( false );
5179 if ( !this.selecting
) {
5180 item
= this.getTargetItem( e
);
5181 if ( item
&& item
.isSelectable() ) {
5182 this.selecting
= item
;
5185 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
&& this.selecting
) {
5186 this.pressItem( null );
5187 this.chooseItem( this.selecting
);
5188 this.selecting
= null;
5191 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
5192 this.getElementDocument().removeEventListener( 'mousemove', this.onMouseMoveHandler
, true );
5198 * Handle mouse move events.
5201 * @param {MouseEvent} e Mouse move event
5203 OO
.ui
.SelectWidget
.prototype.onMouseMove = function ( e
) {
5206 if ( !this.isDisabled() && this.pressed
) {
5207 item
= this.getTargetItem( e
);
5208 if ( item
&& item
!== this.selecting
&& item
.isSelectable() ) {
5209 this.pressItem( item
);
5210 this.selecting
= item
;
5216 * Handle mouse over events.
5219 * @param {jQuery.Event} e Mouse over event
5221 OO
.ui
.SelectWidget
.prototype.onMouseOver = function ( e
) {
5223 if ( this.blockMouseOverEvents
) {
5226 if ( !this.isDisabled() ) {
5227 item
= this.getTargetItem( e
);
5228 this.highlightItem( item
&& item
.isHighlightable() ? item
: null );
5234 * Handle mouse leave events.
5237 * @param {jQuery.Event} e Mouse over event
5239 OO
.ui
.SelectWidget
.prototype.onMouseLeave = function () {
5240 if ( !this.isDisabled() ) {
5241 this.highlightItem( null );
5247 * Handle key down events.
5250 * @param {KeyboardEvent} e Key down event
5252 OO
.ui
.SelectWidget
.prototype.onKeyDown = function ( e
) {
5255 currentItem
= this.getHighlightedItem() || this.getSelectedItem();
5257 if ( !this.isDisabled() && this.isVisible() ) {
5258 switch ( e
.keyCode
) {
5259 case OO
.ui
.Keys
.ENTER
:
5260 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
5261 // Was only highlighted, now let's select it. No-op if already selected.
5262 this.chooseItem( currentItem
);
5267 case OO
.ui
.Keys
.LEFT
:
5268 this.clearKeyPressBuffer();
5269 nextItem
= this.getRelativeSelectableItem( currentItem
, -1 );
5272 case OO
.ui
.Keys
.DOWN
:
5273 case OO
.ui
.Keys
.RIGHT
:
5274 this.clearKeyPressBuffer();
5275 nextItem
= this.getRelativeSelectableItem( currentItem
, 1 );
5278 case OO
.ui
.Keys
.ESCAPE
:
5279 case OO
.ui
.Keys
.TAB
:
5280 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
5281 currentItem
.setHighlighted( false );
5283 this.unbindKeyDownListener();
5284 this.unbindKeyPressListener();
5285 // Don't prevent tabbing away / defocusing
5291 if ( nextItem
.constructor.static.highlightable
) {
5292 this.highlightItem( nextItem
);
5294 this.chooseItem( nextItem
);
5296 this.scrollItemIntoView( nextItem
);
5301 e
.stopPropagation();
5307 * Bind key down listener.
5311 OO
.ui
.SelectWidget
.prototype.bindKeyDownListener = function () {
5312 this.getElementWindow().addEventListener( 'keydown', this.onKeyDownHandler
, true );
5316 * Unbind key down listener.
5320 OO
.ui
.SelectWidget
.prototype.unbindKeyDownListener = function () {
5321 this.getElementWindow().removeEventListener( 'keydown', this.onKeyDownHandler
, true );
5325 * Scroll item into view, preventing spurious mouse highlight actions from happening.
5327 * @param {OO.ui.OptionWidget} item Item to scroll into view
5329 OO
.ui
.SelectWidget
.prototype.scrollItemIntoView = function ( item
) {
5331 // Chromium's Blink engine will generate spurious 'mouseover' events during programmatic scrolling
5332 // and around 100-150 ms after it is finished.
5333 this.blockMouseOverEvents
++;
5334 item
.scrollElementIntoView().done( function () {
5335 setTimeout( function () {
5336 widget
.blockMouseOverEvents
--;
5342 * Clear the key-press buffer
5346 OO
.ui
.SelectWidget
.prototype.clearKeyPressBuffer = function () {
5347 if ( this.keyPressBufferTimer
) {
5348 clearTimeout( this.keyPressBufferTimer
);
5349 this.keyPressBufferTimer
= null;
5351 this.keyPressBuffer
= '';
5355 * Handle key press events.
5358 * @param {KeyboardEvent} e Key press event
5360 OO
.ui
.SelectWidget
.prototype.onKeyPress = function ( e
) {
5361 var c
, filter
, item
;
5363 if ( !e
.charCode
) {
5364 if ( e
.keyCode
=== OO
.ui
.Keys
.BACKSPACE
&& this.keyPressBuffer
!== '' ) {
5365 this.keyPressBuffer
= this.keyPressBuffer
.substr( 0, this.keyPressBuffer
.length
- 1 );
5370 if ( String
.fromCodePoint
) {
5371 c
= String
.fromCodePoint( e
.charCode
);
5373 c
= String
.fromCharCode( e
.charCode
);
5376 if ( this.keyPressBufferTimer
) {
5377 clearTimeout( this.keyPressBufferTimer
);
5379 this.keyPressBufferTimer
= setTimeout( this.clearKeyPressBuffer
.bind( this ), 1500 );
5381 item
= this.getHighlightedItem() || this.getSelectedItem();
5383 if ( this.keyPressBuffer
=== c
) {
5384 // Common (if weird) special case: typing "xxxx" will cycle through all
5385 // the items beginning with "x".
5387 item
= this.getRelativeSelectableItem( item
, 1 );
5390 this.keyPressBuffer
+= c
;
5393 filter
= this.getItemMatcher( this.keyPressBuffer
, false );
5394 if ( !item
|| !filter( item
) ) {
5395 item
= this.getRelativeSelectableItem( item
, 1, filter
);
5398 if ( this.isVisible() && item
.constructor.static.highlightable
) {
5399 this.highlightItem( item
);
5401 this.chooseItem( item
);
5403 this.scrollItemIntoView( item
);
5407 e
.stopPropagation();
5411 * Get a matcher for the specific string
5414 * @param {string} s String to match against items
5415 * @param {boolean} [exact=false] Only accept exact matches
5416 * @return {Function} function ( OO.ui.OptionItem ) => boolean
5418 OO
.ui
.SelectWidget
.prototype.getItemMatcher = function ( s
, exact
) {
5421 if ( s
.normalize
) {
5424 s
= exact
? s
.trim() : s
.replace( /^\s+/, '' );
5425 re
= '^\\s*' + s
.replace( /([\\{}()|.?*+\-\^$\[\]])/g, '\\$1' ).replace( /\s+/g, '\\s+' );
5429 re
= new RegExp( re
, 'i' );
5430 return function ( item
) {
5431 var l
= item
.getLabel();
5432 if ( typeof l
!== 'string' ) {
5433 l
= item
.$label
.text();
5435 if ( l
.normalize
) {
5438 return re
.test( l
);
5443 * Bind key press listener.
5447 OO
.ui
.SelectWidget
.prototype.bindKeyPressListener = function () {
5448 this.getElementWindow().addEventListener( 'keypress', this.onKeyPressHandler
, true );
5452 * Unbind key down listener.
5454 * If you override this, be sure to call this.clearKeyPressBuffer() from your
5459 OO
.ui
.SelectWidget
.prototype.unbindKeyPressListener = function () {
5460 this.getElementWindow().removeEventListener( 'keypress', this.onKeyPressHandler
, true );
5461 this.clearKeyPressBuffer();
5465 * Visibility change handler
5468 * @param {boolean} visible
5470 OO
.ui
.SelectWidget
.prototype.onToggle = function ( visible
) {
5472 this.clearKeyPressBuffer();
5477 * Get the closest item to a jQuery.Event.
5480 * @param {jQuery.Event} e
5481 * @return {OO.ui.OptionWidget|null} Outline item widget, `null` if none was found
5483 OO
.ui
.SelectWidget
.prototype.getTargetItem = function ( e
) {
5484 return $( e
.target
).closest( '.oo-ui-optionWidget' ).data( 'oo-ui-optionWidget' ) || null;
5488 * Get selected item.
5490 * @return {OO.ui.OptionWidget|null} Selected item, `null` if no item is selected
5492 OO
.ui
.SelectWidget
.prototype.getSelectedItem = function () {
5495 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5496 if ( this.items
[ i
].isSelected() ) {
5497 return this.items
[ i
];
5504 * Get highlighted item.
5506 * @return {OO.ui.OptionWidget|null} Highlighted item, `null` if no item is highlighted
5508 OO
.ui
.SelectWidget
.prototype.getHighlightedItem = function () {
5511 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5512 if ( this.items
[ i
].isHighlighted() ) {
5513 return this.items
[ i
];
5520 * Toggle pressed state.
5522 * Press is a state that occurs when a user mouses down on an item, but
5523 * has not yet let go of the mouse. The item may appear selected, but it will not be selected
5524 * until the user releases the mouse.
5526 * @param {boolean} pressed An option is being pressed
5528 OO
.ui
.SelectWidget
.prototype.togglePressed = function ( pressed
) {
5529 if ( pressed
=== undefined ) {
5530 pressed
= !this.pressed
;
5532 if ( pressed
!== this.pressed
) {
5534 .toggleClass( 'oo-ui-selectWidget-pressed', pressed
)
5535 .toggleClass( 'oo-ui-selectWidget-depressed', !pressed
);
5536 this.pressed
= pressed
;
5541 * Highlight an option. If the `item` param is omitted, no options will be highlighted
5542 * and any existing highlight will be removed. The highlight is mutually exclusive.
5544 * @param {OO.ui.OptionWidget} [item] Item to highlight, omit for no highlight
5548 OO
.ui
.SelectWidget
.prototype.highlightItem = function ( item
) {
5549 var i
, len
, highlighted
,
5552 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5553 highlighted
= this.items
[ i
] === item
;
5554 if ( this.items
[ i
].isHighlighted() !== highlighted
) {
5555 this.items
[ i
].setHighlighted( highlighted
);
5560 this.emit( 'highlight', item
);
5567 * Fetch an item by its label.
5569 * @param {string} label Label of the item to select.
5570 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
5571 * @return {OO.ui.Element|null} Item with equivalent label, `null` if none exists
5573 OO
.ui
.SelectWidget
.prototype.getItemFromLabel = function ( label
, prefix
) {
5575 len
= this.items
.length
,
5576 filter
= this.getItemMatcher( label
, true );
5578 for ( i
= 0; i
< len
; i
++ ) {
5579 item
= this.items
[ i
];
5580 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
5587 filter
= this.getItemMatcher( label
, false );
5588 for ( i
= 0; i
< len
; i
++ ) {
5589 item
= this.items
[ i
];
5590 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
5606 * Programmatically select an option by its label. If the item does not exist,
5607 * all options will be deselected.
5609 * @param {string} [label] Label of the item to select.
5610 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
5614 OO
.ui
.SelectWidget
.prototype.selectItemByLabel = function ( label
, prefix
) {
5615 var itemFromLabel
= this.getItemFromLabel( label
, !!prefix
);
5616 if ( label
=== undefined || !itemFromLabel
) {
5617 return this.selectItem();
5619 return this.selectItem( itemFromLabel
);
5623 * Programmatically select an option by its data. If the `data` parameter is omitted,
5624 * or if the item does not exist, all options will be deselected.
5626 * @param {Object|string} [data] Value of the item to select, omit to deselect all
5630 OO
.ui
.SelectWidget
.prototype.selectItemByData = function ( data
) {
5631 var itemFromData
= this.getItemFromData( data
);
5632 if ( data
=== undefined || !itemFromData
) {
5633 return this.selectItem();
5635 return this.selectItem( itemFromData
);
5639 * Programmatically select an option by its reference. If the `item` parameter is omitted,
5640 * all options will be deselected.
5642 * @param {OO.ui.OptionWidget} [item] Item to select, omit to deselect all
5646 OO
.ui
.SelectWidget
.prototype.selectItem = function ( item
) {
5647 var i
, len
, selected
,
5650 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5651 selected
= this.items
[ i
] === item
;
5652 if ( this.items
[ i
].isSelected() !== selected
) {
5653 this.items
[ i
].setSelected( selected
);
5658 this.emit( 'select', item
);
5667 * Press is a state that occurs when a user mouses down on an item, but has not
5668 * yet let go of the mouse. The item may appear selected, but it will not be selected until the user
5669 * releases the mouse.
5671 * @param {OO.ui.OptionWidget} [item] Item to press, omit to depress all
5675 OO
.ui
.SelectWidget
.prototype.pressItem = function ( item
) {
5676 var i
, len
, pressed
,
5679 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5680 pressed
= this.items
[ i
] === item
;
5681 if ( this.items
[ i
].isPressed() !== pressed
) {
5682 this.items
[ i
].setPressed( pressed
);
5687 this.emit( 'press', item
);
5696 * Note that ‘choose’ should never be modified programmatically. A user can choose
5697 * an option with the keyboard or mouse and it becomes selected. To select an item programmatically,
5698 * use the #selectItem method.
5700 * This method is identical to #selectItem, but may vary in subclasses that take additional action
5701 * when users choose an item with the keyboard or mouse.
5703 * @param {OO.ui.OptionWidget} item Item to choose
5707 OO
.ui
.SelectWidget
.prototype.chooseItem = function ( item
) {
5709 this.selectItem( item
);
5710 this.emit( 'choose', item
);
5717 * Get an option by its position relative to the specified item (or to the start of the option array,
5718 * if item is `null`). The direction in which to search through the option array is specified with a
5719 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
5720 * `null` if there are no options in the array.
5722 * @param {OO.ui.OptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
5723 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
5724 * @param {Function} [filter] Only consider items for which this function returns
5725 * true. Function takes an OO.ui.OptionWidget and returns a boolean.
5726 * @return {OO.ui.OptionWidget|null} Item at position, `null` if there are no items in the select
5728 OO
.ui
.SelectWidget
.prototype.getRelativeSelectableItem = function ( item
, direction
, filter
) {
5729 var currentIndex
, nextIndex
, i
,
5730 increase
= direction
> 0 ? 1 : -1,
5731 len
= this.items
.length
;
5733 if ( item
instanceof OO
.ui
.OptionWidget
) {
5734 currentIndex
= this.items
.indexOf( item
);
5735 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
5737 // If no item is selected and moving forward, start at the beginning.
5738 // If moving backward, start at the end.
5739 nextIndex
= direction
> 0 ? 0 : len
- 1;
5742 for ( i
= 0; i
< len
; i
++ ) {
5743 item
= this.items
[ nextIndex
];
5745 item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() &&
5746 ( !filter
|| filter( item
) )
5750 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
5756 * Get the next selectable item or `null` if there are no selectable items.
5757 * Disabled options and menu-section markers and breaks are not selectable.
5759 * @return {OO.ui.OptionWidget|null} Item, `null` if there aren't any selectable items
5761 OO
.ui
.SelectWidget
.prototype.getFirstSelectableItem = function () {
5762 return this.getRelativeSelectableItem( null, 1 );
5766 * Add an array of options to the select. Optionally, an index number can be used to
5767 * specify an insertion point.
5769 * @param {OO.ui.OptionWidget[]} items Items to add
5770 * @param {number} [index] Index to insert items after
5774 OO
.ui
.SelectWidget
.prototype.addItems = function ( items
, index
) {
5776 OO
.ui
.mixin
.GroupWidget
.prototype.addItems
.call( this, items
, index
);
5778 // Always provide an index, even if it was omitted
5779 this.emit( 'add', items
, index
=== undefined ? this.items
.length
- items
.length
- 1 : index
);
5785 * Remove the specified array of options from the select. Options will be detached
5786 * from the DOM, not removed, so they can be reused later. To remove all options from
5787 * the select, you may wish to use the #clearItems method instead.
5789 * @param {OO.ui.OptionWidget[]} items Items to remove
5793 OO
.ui
.SelectWidget
.prototype.removeItems = function ( items
) {
5796 // Deselect items being removed
5797 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
5799 if ( item
.isSelected() ) {
5800 this.selectItem( null );
5805 OO
.ui
.mixin
.GroupWidget
.prototype.removeItems
.call( this, items
);
5807 this.emit( 'remove', items
);
5813 * Clear all options from the select. Options will be detached from the DOM, not removed,
5814 * so that they can be reused later. To remove a subset of options from the select, use
5815 * the #removeItems method.
5820 OO
.ui
.SelectWidget
.prototype.clearItems = function () {
5821 var items
= this.items
.slice();
5824 OO
.ui
.mixin
.GroupWidget
.prototype.clearItems
.call( this );
5827 this.selectItem( null );
5829 this.emit( 'remove', items
);
5835 * DecoratedOptionWidgets are {@link OO.ui.OptionWidget options} that can be configured
5836 * with an {@link OO.ui.mixin.IconElement icon} and/or {@link OO.ui.mixin.IndicatorElement indicator}.
5837 * This class is used with OO.ui.SelectWidget to create a selection of mutually exclusive
5838 * options. For more information about options and selects, please see the
5839 * [OOjs UI documentation on MediaWiki][1].
5842 * // Decorated options in a select widget
5843 * var select = new OO.ui.SelectWidget( {
5845 * new OO.ui.DecoratedOptionWidget( {
5847 * label: 'Option with icon',
5850 * new OO.ui.DecoratedOptionWidget( {
5852 * label: 'Option with indicator',
5857 * $( 'body' ).append( select.$element );
5859 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5862 * @extends OO.ui.OptionWidget
5863 * @mixins OO.ui.mixin.IconElement
5864 * @mixins OO.ui.mixin.IndicatorElement
5867 * @param {Object} [config] Configuration options
5869 OO
.ui
.DecoratedOptionWidget
= function OoUiDecoratedOptionWidget( config
) {
5870 // Parent constructor
5871 OO
.ui
.DecoratedOptionWidget
.parent
.call( this, config
);
5873 // Mixin constructors
5874 OO
.ui
.mixin
.IconElement
.call( this, config
);
5875 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
5879 .addClass( 'oo-ui-decoratedOptionWidget' )
5880 .prepend( this.$icon
)
5881 .append( this.$indicator
);
5886 OO
.inheritClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.OptionWidget
);
5887 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IconElement
);
5888 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IndicatorElement
);
5891 * MenuOptionWidget is an option widget that looks like a menu item. The class is used with
5892 * OO.ui.MenuSelectWidget to create a menu of mutually exclusive options. Please see
5893 * the [OOjs UI documentation on MediaWiki] [1] for more information.
5895 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
5898 * @extends OO.ui.DecoratedOptionWidget
5901 * @param {Object} [config] Configuration options
5903 OO
.ui
.MenuOptionWidget
= function OoUiMenuOptionWidget( config
) {
5904 // Configuration initialization
5905 config
= $.extend( { icon
: 'check' }, config
);
5907 // Parent constructor
5908 OO
.ui
.MenuOptionWidget
.parent
.call( this, config
);
5912 .attr( 'role', 'menuitem' )
5913 .addClass( 'oo-ui-menuOptionWidget' );
5918 OO
.inheritClass( OO
.ui
.MenuOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
5920 /* Static Properties */
5922 OO
.ui
.MenuOptionWidget
.static.scrollIntoViewOnSelect
= true;
5925 * MenuSectionOptionWidgets are used inside {@link OO.ui.MenuSelectWidget menu select widgets} to group one or more related
5926 * {@link OO.ui.MenuOptionWidget menu options}. MenuSectionOptionWidgets cannot be highlighted or selected.
5929 * var myDropdown = new OO.ui.DropdownWidget( {
5932 * new OO.ui.MenuSectionOptionWidget( {
5935 * new OO.ui.MenuOptionWidget( {
5937 * label: 'Welsh Corgi'
5939 * new OO.ui.MenuOptionWidget( {
5941 * label: 'Standard Poodle'
5943 * new OO.ui.MenuSectionOptionWidget( {
5946 * new OO.ui.MenuOptionWidget( {
5953 * $( 'body' ).append( myDropdown.$element );
5956 * @extends OO.ui.DecoratedOptionWidget
5959 * @param {Object} [config] Configuration options
5961 OO
.ui
.MenuSectionOptionWidget
= function OoUiMenuSectionOptionWidget( config
) {
5962 // Parent constructor
5963 OO
.ui
.MenuSectionOptionWidget
.parent
.call( this, config
);
5966 this.$element
.addClass( 'oo-ui-menuSectionOptionWidget' );
5971 OO
.inheritClass( OO
.ui
.MenuSectionOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
5973 /* Static Properties */
5975 OO
.ui
.MenuSectionOptionWidget
.static.selectable
= false;
5977 OO
.ui
.MenuSectionOptionWidget
.static.highlightable
= false;
5980 * MenuSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains options and
5981 * is used together with OO.ui.MenuOptionWidget. It is designed be used as part of another widget.
5982 * See {@link OO.ui.DropdownWidget DropdownWidget}, {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget},
5983 * and {@link OO.ui.mixin.LookupElement LookupElement} for examples of widgets that contain menus.
5984 * MenuSelectWidgets themselves are not instantiated directly, rather subclassed
5985 * and customized to be opened, closed, and displayed as needed.
5987 * By default, menus are clipped to the visible viewport and are not visible when a user presses the
5988 * mouse outside the menu.
5990 * Menus also have support for keyboard interaction:
5992 * - Enter/Return key: choose and select a menu option
5993 * - Up-arrow key: highlight the previous menu option
5994 * - Down-arrow key: highlight the next menu option
5995 * - Esc key: hide the menu
5997 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
5998 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6001 * @extends OO.ui.SelectWidget
6002 * @mixins OO.ui.mixin.ClippableElement
6005 * @param {Object} [config] Configuration options
6006 * @cfg {OO.ui.TextInputWidget} [input] Text input used to implement option highlighting for menu items that match
6007 * the text the user types. This config is used by {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget}
6008 * and {@link OO.ui.mixin.LookupElement LookupElement}
6009 * @cfg {jQuery} [$input] Text input used to implement option highlighting for menu items that match
6010 * the text the user types. This config is used by {@link OO.ui.CapsuleMultiselectWidget CapsuleMultiselectWidget}
6011 * @cfg {OO.ui.Widget} [widget] Widget associated with the menu's active state. If the user clicks the mouse
6012 * anywhere on the page outside of this widget, the menu is hidden. For example, if there is a button
6013 * that toggles the menu's visibility on click, the menu will be hidden then re-shown when the user clicks
6014 * that button, unless the button (or its parent widget) is passed in here.
6015 * @cfg {boolean} [autoHide=true] Hide the menu when the mouse is pressed outside the menu.
6016 * @cfg {boolean} [filterFromInput=false] Filter the displayed options from the input
6018 OO
.ui
.MenuSelectWidget
= function OoUiMenuSelectWidget( config
) {
6019 // Configuration initialization
6020 config
= config
|| {};
6022 // Parent constructor
6023 OO
.ui
.MenuSelectWidget
.parent
.call( this, config
);
6025 // Mixin constructors
6026 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, { $clippable
: this.$group
} ) );
6029 this.autoHide
= config
.autoHide
=== undefined || !!config
.autoHide
;
6030 this.filterFromInput
= !!config
.filterFromInput
;
6031 this.$input
= config
.$input
? config
.$input
: config
.input
? config
.input
.$input
: null;
6032 this.$widget
= config
.widget
? config
.widget
.$element
: null;
6033 this.onDocumentMouseDownHandler
= this.onDocumentMouseDown
.bind( this );
6034 this.onInputEditHandler
= OO
.ui
.debounce( this.updateItemVisibility
.bind( this ), 100 );
6038 .addClass( 'oo-ui-menuSelectWidget' )
6039 .attr( 'role', 'menu' );
6041 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
6042 // that reference properties not initialized at that time of parent class construction
6043 // TODO: Find a better way to handle post-constructor setup
6044 this.visible
= false;
6045 this.$element
.addClass( 'oo-ui-element-hidden' );
6050 OO
.inheritClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.SelectWidget
);
6051 OO
.mixinClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.mixin
.ClippableElement
);
6056 * Handles document mouse down events.
6059 * @param {MouseEvent} e Mouse down event
6061 OO
.ui
.MenuSelectWidget
.prototype.onDocumentMouseDown = function ( e
) {
6063 !OO
.ui
.contains( this.$element
[ 0 ], e
.target
, true ) &&
6064 ( !this.$widget
|| !OO
.ui
.contains( this.$widget
[ 0 ], e
.target
, true ) )
6066 this.toggle( false );
6073 OO
.ui
.MenuSelectWidget
.prototype.onKeyDown = function ( e
) {
6074 var currentItem
= this.getHighlightedItem() || this.getSelectedItem();
6076 if ( !this.isDisabled() && this.isVisible() ) {
6077 switch ( e
.keyCode
) {
6078 case OO
.ui
.Keys
.LEFT
:
6079 case OO
.ui
.Keys
.RIGHT
:
6080 // Do nothing if a text field is associated, arrow keys will be handled natively
6081 if ( !this.$input
) {
6082 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
6085 case OO
.ui
.Keys
.ESCAPE
:
6086 case OO
.ui
.Keys
.TAB
:
6087 if ( currentItem
) {
6088 currentItem
.setHighlighted( false );
6090 this.toggle( false );
6091 // Don't prevent tabbing away, prevent defocusing
6092 if ( e
.keyCode
=== OO
.ui
.Keys
.ESCAPE
) {
6094 e
.stopPropagation();
6098 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
6105 * Update menu item visibility after input changes.
6109 OO
.ui
.MenuSelectWidget
.prototype.updateItemVisibility = function () {
6111 len
= this.items
.length
,
6112 showAll
= !this.isVisible(),
6113 filter
= showAll
? null : this.getItemMatcher( this.$input
.val() );
6115 for ( i
= 0; i
< len
; i
++ ) {
6116 item
= this.items
[ i
];
6117 if ( item
instanceof OO
.ui
.OptionWidget
) {
6118 item
.toggle( showAll
|| filter( item
) );
6122 // Reevaluate clipping
6129 OO
.ui
.MenuSelectWidget
.prototype.bindKeyDownListener = function () {
6130 if ( this.$input
) {
6131 this.$input
.on( 'keydown', this.onKeyDownHandler
);
6133 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyDownListener
.call( this );
6140 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyDownListener = function () {
6141 if ( this.$input
) {
6142 this.$input
.off( 'keydown', this.onKeyDownHandler
);
6144 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyDownListener
.call( this );
6151 OO
.ui
.MenuSelectWidget
.prototype.bindKeyPressListener = function () {
6152 if ( this.$input
) {
6153 if ( this.filterFromInput
) {
6154 this.$input
.on( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
6157 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyPressListener
.call( this );
6164 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyPressListener = function () {
6165 if ( this.$input
) {
6166 if ( this.filterFromInput
) {
6167 this.$input
.off( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
6168 this.updateItemVisibility();
6171 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyPressListener
.call( this );
6178 * When a user chooses an item, the menu is closed.
6180 * Note that ‘choose’ should never be modified programmatically. A user can choose an option with the keyboard
6181 * or mouse and it becomes selected. To select an item programmatically, use the #selectItem method.
6183 * @param {OO.ui.OptionWidget} item Item to choose
6186 OO
.ui
.MenuSelectWidget
.prototype.chooseItem = function ( item
) {
6187 OO
.ui
.MenuSelectWidget
.parent
.prototype.chooseItem
.call( this, item
);
6188 this.toggle( false );
6195 OO
.ui
.MenuSelectWidget
.prototype.addItems = function ( items
, index
) {
6197 OO
.ui
.MenuSelectWidget
.parent
.prototype.addItems
.call( this, items
, index
);
6199 // Reevaluate clipping
6208 OO
.ui
.MenuSelectWidget
.prototype.removeItems = function ( items
) {
6210 OO
.ui
.MenuSelectWidget
.parent
.prototype.removeItems
.call( this, items
);
6212 // Reevaluate clipping
6221 OO
.ui
.MenuSelectWidget
.prototype.clearItems = function () {
6223 OO
.ui
.MenuSelectWidget
.parent
.prototype.clearItems
.call( this );
6225 // Reevaluate clipping
6234 OO
.ui
.MenuSelectWidget
.prototype.toggle = function ( visible
) {
6237 visible
= ( visible
=== undefined ? !this.visible
: !!visible
) && !!this.items
.length
;
6238 change
= visible
!== this.isVisible();
6241 OO
.ui
.MenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
6245 this.bindKeyDownListener();
6246 this.bindKeyPressListener();
6248 this.toggleClipping( true );
6250 if ( this.getSelectedItem() ) {
6251 this.getSelectedItem().scrollElementIntoView( { duration
: 0 } );
6255 if ( this.autoHide
) {
6256 this.getElementDocument().addEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
6259 this.unbindKeyDownListener();
6260 this.unbindKeyPressListener();
6261 this.getElementDocument().removeEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
6262 this.toggleClipping( false );
6270 * DropdownWidgets are not menus themselves, rather they contain a menu of options created with
6271 * OO.ui.MenuOptionWidget. The DropdownWidget takes care of opening and displaying the menu so that
6272 * users can interact with it.
6274 * If you want to use this within a HTML form, such as a OO.ui.FormLayout, use
6275 * OO.ui.DropdownInputWidget instead.
6278 * // Example: A DropdownWidget with a menu that contains three options
6279 * var dropDown = new OO.ui.DropdownWidget( {
6280 * label: 'Dropdown menu: Select a menu option',
6283 * new OO.ui.MenuOptionWidget( {
6287 * new OO.ui.MenuOptionWidget( {
6291 * new OO.ui.MenuOptionWidget( {
6299 * $( 'body' ).append( dropDown.$element );
6301 * dropDown.getMenu().selectItemByData( 'b' );
6303 * dropDown.getMenu().getSelectedItem().getData(); // returns 'b'
6305 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
6307 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
6310 * @extends OO.ui.Widget
6311 * @mixins OO.ui.mixin.IconElement
6312 * @mixins OO.ui.mixin.IndicatorElement
6313 * @mixins OO.ui.mixin.LabelElement
6314 * @mixins OO.ui.mixin.TitledElement
6315 * @mixins OO.ui.mixin.TabIndexedElement
6318 * @param {Object} [config] Configuration options
6319 * @cfg {Object} [menu] Configuration options to pass to {@link OO.ui.FloatingMenuSelectWidget menu select widget}
6320 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
6321 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
6322 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
6324 OO
.ui
.DropdownWidget
= function OoUiDropdownWidget( config
) {
6325 // Configuration initialization
6326 config
= $.extend( { indicator
: 'down' }, config
);
6328 // Parent constructor
6329 OO
.ui
.DropdownWidget
.parent
.call( this, config
);
6331 // Properties (must be set before TabIndexedElement constructor call)
6332 this.$handle
= this.$( '<span>' );
6333 this.$overlay
= config
.$overlay
|| this.$element
;
6335 // Mixin constructors
6336 OO
.ui
.mixin
.IconElement
.call( this, config
);
6337 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
6338 OO
.ui
.mixin
.LabelElement
.call( this, config
);
6339 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
6340 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$handle
} ) );
6343 this.menu
= new OO
.ui
.FloatingMenuSelectWidget( $.extend( {
6345 $container
: this.$element
6350 click
: this.onClick
.bind( this ),
6351 keydown
: this.onKeyDown
.bind( this ),
6352 // Hack? Handle type-to-search when menu is not expanded and not handling its own events
6353 keypress
: this.menu
.onKeyPressHandler
,
6354 blur
: this.menu
.clearKeyPressBuffer
.bind( this.menu
)
6356 this.menu
.connect( this, { select
: 'onMenuSelect' } );
6360 .addClass( 'oo-ui-dropdownWidget-handle' )
6361 .append( this.$icon
, this.$label
, this.$indicator
);
6363 .addClass( 'oo-ui-dropdownWidget' )
6364 .append( this.$handle
);
6365 this.$overlay
.append( this.menu
.$element
);
6370 OO
.inheritClass( OO
.ui
.DropdownWidget
, OO
.ui
.Widget
);
6371 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IconElement
);
6372 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IndicatorElement
);
6373 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.LabelElement
);
6374 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TitledElement
);
6375 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TabIndexedElement
);
6382 * @return {OO.ui.MenuSelectWidget} Menu of widget
6384 OO
.ui
.DropdownWidget
.prototype.getMenu = function () {
6389 * Handles menu select events.
6392 * @param {OO.ui.MenuOptionWidget} item Selected menu item
6394 OO
.ui
.DropdownWidget
.prototype.onMenuSelect = function ( item
) {
6398 this.setLabel( null );
6402 selectedLabel
= item
.getLabel();
6404 // If the label is a DOM element, clone it, because setLabel will append() it
6405 if ( selectedLabel
instanceof jQuery
) {
6406 selectedLabel
= selectedLabel
.clone();
6409 this.setLabel( selectedLabel
);
6413 * Handle mouse click events.
6416 * @param {jQuery.Event} e Mouse click event
6418 OO
.ui
.DropdownWidget
.prototype.onClick = function ( e
) {
6419 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
6426 * Handle key down events.
6429 * @param {jQuery.Event} e Key down event
6431 OO
.ui
.DropdownWidget
.prototype.onKeyDown = function ( e
) {
6433 !this.isDisabled() &&
6435 e
.which
=== OO
.ui
.Keys
.ENTER
||
6437 !this.menu
.isVisible() &&
6439 e
.which
=== OO
.ui
.Keys
.SPACE
||
6440 e
.which
=== OO
.ui
.Keys
.UP
||
6441 e
.which
=== OO
.ui
.Keys
.DOWN
6452 * RadioOptionWidget is an option widget that looks like a radio button.
6453 * The class is used with OO.ui.RadioSelectWidget to create a selection of radio options.
6454 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
6456 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option
6459 * @extends OO.ui.OptionWidget
6462 * @param {Object} [config] Configuration options
6464 OO
.ui
.RadioOptionWidget
= function OoUiRadioOptionWidget( config
) {
6465 // Configuration initialization
6466 config
= config
|| {};
6468 // Properties (must be done before parent constructor which calls #setDisabled)
6469 this.radio
= new OO
.ui
.RadioInputWidget( { value
: config
.data
, tabIndex
: -1 } );
6471 // Parent constructor
6472 OO
.ui
.RadioOptionWidget
.parent
.call( this, config
);
6475 // Remove implicit role, we're handling it ourselves
6476 this.radio
.$input
.attr( 'role', 'presentation' );
6478 .addClass( 'oo-ui-radioOptionWidget' )
6479 .attr( 'role', 'radio' )
6480 .attr( 'aria-checked', 'false' )
6481 .removeAttr( 'aria-selected' )
6482 .prepend( this.radio
.$element
);
6487 OO
.inheritClass( OO
.ui
.RadioOptionWidget
, OO
.ui
.OptionWidget
);
6489 /* Static Properties */
6491 OO
.ui
.RadioOptionWidget
.static.highlightable
= false;
6493 OO
.ui
.RadioOptionWidget
.static.scrollIntoViewOnSelect
= true;
6495 OO
.ui
.RadioOptionWidget
.static.pressable
= false;
6497 OO
.ui
.RadioOptionWidget
.static.tagName
= 'label';
6504 OO
.ui
.RadioOptionWidget
.prototype.setSelected = function ( state
) {
6505 OO
.ui
.RadioOptionWidget
.parent
.prototype.setSelected
.call( this, state
);
6507 this.radio
.setSelected( state
);
6509 .attr( 'aria-checked', state
.toString() )
6510 .removeAttr( 'aria-selected' );
6518 OO
.ui
.RadioOptionWidget
.prototype.setDisabled = function ( disabled
) {
6519 OO
.ui
.RadioOptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
6521 this.radio
.setDisabled( this.isDisabled() );
6527 * RadioSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains radio
6528 * options and is used together with OO.ui.RadioOptionWidget. The RadioSelectWidget provides
6529 * an interface for adding, removing and selecting options.
6530 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
6532 * If you want to use this within a HTML form, such as a OO.ui.FormLayout, use
6533 * OO.ui.RadioSelectInputWidget instead.
6536 * // A RadioSelectWidget with RadioOptions.
6537 * var option1 = new OO.ui.RadioOptionWidget( {
6539 * label: 'Selected radio option'
6542 * var option2 = new OO.ui.RadioOptionWidget( {
6544 * label: 'Unselected radio option'
6547 * var radioSelect=new OO.ui.RadioSelectWidget( {
6548 * items: [ option1, option2 ]
6551 * // Select 'option 1' using the RadioSelectWidget's selectItem() method.
6552 * radioSelect.selectItem( option1 );
6554 * $( 'body' ).append( radioSelect.$element );
6556 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6560 * @extends OO.ui.SelectWidget
6561 * @mixins OO.ui.mixin.TabIndexedElement
6564 * @param {Object} [config] Configuration options
6566 OO
.ui
.RadioSelectWidget
= function OoUiRadioSelectWidget( config
) {
6567 // Parent constructor
6568 OO
.ui
.RadioSelectWidget
.parent
.call( this, config
);
6570 // Mixin constructors
6571 OO
.ui
.mixin
.TabIndexedElement
.call( this, config
);
6575 focus
: this.bindKeyDownListener
.bind( this ),
6576 blur
: this.unbindKeyDownListener
.bind( this )
6581 .addClass( 'oo-ui-radioSelectWidget' )
6582 .attr( 'role', 'radiogroup' );
6587 OO
.inheritClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.SelectWidget
);
6588 OO
.mixinClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.mixin
.TabIndexedElement
);
6591 * MultioptionWidgets are special elements that can be selected and configured with data. The
6592 * data is often unique for each option, but it does not have to be. MultioptionWidgets are used
6593 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
6594 * and examples, please see the [OOjs UI documentation on MediaWiki][1].
6596 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Multioptions
6599 * @extends OO.ui.Widget
6600 * @mixins OO.ui.mixin.ItemWidget
6601 * @mixins OO.ui.mixin.LabelElement
6604 * @param {Object} [config] Configuration options
6605 * @cfg {boolean} [selected=false] Whether the option is initially selected
6607 OO
.ui
.MultioptionWidget
= function OoUiMultioptionWidget( config
) {
6608 // Configuration initialization
6609 config
= config
|| {};
6611 // Parent constructor
6612 OO
.ui
.MultioptionWidget
.parent
.call( this, config
);
6614 // Mixin constructors
6615 OO
.ui
.mixin
.ItemWidget
.call( this );
6616 OO
.ui
.mixin
.LabelElement
.call( this, config
);
6619 this.selected
= null;
6623 .addClass( 'oo-ui-multioptionWidget' )
6624 .append( this.$label
);
6625 this.setSelected( config
.selected
);
6630 OO
.inheritClass( OO
.ui
.MultioptionWidget
, OO
.ui
.Widget
);
6631 OO
.mixinClass( OO
.ui
.MultioptionWidget
, OO
.ui
.mixin
.ItemWidget
);
6632 OO
.mixinClass( OO
.ui
.MultioptionWidget
, OO
.ui
.mixin
.LabelElement
);
6639 * A change event is emitted when the selected state of the option changes.
6641 * @param {boolean} selected Whether the option is now selected
6647 * Check if the option is selected.
6649 * @return {boolean} Item is selected
6651 OO
.ui
.MultioptionWidget
.prototype.isSelected = function () {
6652 return this.selected
;
6656 * Set the option’s selected state. In general, all modifications to the selection
6657 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
6658 * method instead of this method.
6660 * @param {boolean} [state=false] Select option
6663 OO
.ui
.MultioptionWidget
.prototype.setSelected = function ( state
) {
6665 if ( this.selected
!== state
) {
6666 this.selected
= state
;
6667 this.emit( 'change', state
);
6668 this.$element
.toggleClass( 'oo-ui-multioptionWidget-selected', state
);
6674 * MultiselectWidget allows selecting multiple options from a list.
6676 * For more information about menus and options, please see the [OOjs UI documentation on MediaWiki][1].
6678 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
6682 * @extends OO.ui.Widget
6683 * @mixins OO.ui.mixin.GroupWidget
6686 * @param {Object} [config] Configuration options
6687 * @cfg {OO.ui.MultioptionWidget[]} [items] An array of options to add to the multiselect.
6689 OO
.ui
.MultiselectWidget
= function OoUiMultiselectWidget( config
) {
6690 // Parent constructor
6691 OO
.ui
.MultiselectWidget
.parent
.call( this, config
);
6693 // Configuration initialization
6694 config
= config
|| {};
6696 // Mixin constructors
6697 OO
.ui
.mixin
.GroupWidget
.call( this, config
);
6700 this.aggregate( { change
: 'select' } );
6701 // This is mostly for compatibility with CapsuleMultiselectWidget... normally, 'change' is emitted
6702 // by GroupElement only when items are added/removed
6703 this.connect( this, { select
: [ 'emit', 'change' ] } );
6706 if ( config
.items
) {
6707 this.addItems( config
.items
);
6709 this.$group
.addClass( 'oo-ui-multiselectWidget-group' );
6710 this.$element
.addClass( 'oo-ui-multiselectWidget' )
6711 .append( this.$group
);
6716 OO
.inheritClass( OO
.ui
.MultiselectWidget
, OO
.ui
.Widget
);
6717 OO
.mixinClass( OO
.ui
.MultiselectWidget
, OO
.ui
.mixin
.GroupWidget
);
6724 * A change event is emitted when the set of items changes, or an item is selected or deselected.
6730 * A select event is emitted when an item is selected or deselected.
6736 * Get options that are selected.
6738 * @return {OO.ui.MultioptionWidget[]} Selected options
6740 OO
.ui
.MultiselectWidget
.prototype.getSelectedItems = function () {
6741 return this.items
.filter( function ( item
) {
6742 return item
.isSelected();
6747 * Get the data of options that are selected.
6749 * @return {Object[]|string[]} Values of selected options
6751 OO
.ui
.MultiselectWidget
.prototype.getSelectedItemsData = function () {
6752 return this.getSelectedItems().map( function ( item
) {
6758 * Select options by reference. Options not mentioned in the `items` array will be deselected.
6760 * @param {OO.ui.MultioptionWidget[]} items Items to select
6763 OO
.ui
.MultiselectWidget
.prototype.selectItems = function ( items
) {
6764 this.items
.forEach( function ( item
) {
6765 var selected
= items
.indexOf( item
) !== -1;
6766 item
.setSelected( selected
);
6772 * Select items by their data. Options not mentioned in the `datas` array will be deselected.
6774 * @param {Object[]|string[]} datas Values of items to select
6777 OO
.ui
.MultiselectWidget
.prototype.selectItemsByData = function ( datas
) {
6780 items
= datas
.map( function ( data
) {
6781 return widget
.getItemFromData( data
);
6783 this.selectItems( items
);
6788 * CheckboxMultioptionWidget is an option widget that looks like a checkbox.
6789 * The class is used with OO.ui.CheckboxMultiselectWidget to create a selection of checkbox options.
6790 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
6792 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option
6795 * @extends OO.ui.MultioptionWidget
6798 * @param {Object} [config] Configuration options
6800 OO
.ui
.CheckboxMultioptionWidget
= function OoUiCheckboxMultioptionWidget( config
) {
6801 // Configuration initialization
6802 config
= config
|| {};
6804 // Properties (must be done before parent constructor which calls #setDisabled)
6805 this.checkbox
= new OO
.ui
.CheckboxInputWidget();
6807 // Parent constructor
6808 OO
.ui
.CheckboxMultioptionWidget
.parent
.call( this, config
);
6811 this.checkbox
.on( 'change', this.onCheckboxChange
.bind( this ) );
6812 this.$element
.on( 'keydown', this.onKeyDown
.bind( this ) );
6816 .addClass( 'oo-ui-checkboxMultioptionWidget' )
6817 .prepend( this.checkbox
.$element
);
6822 OO
.inheritClass( OO
.ui
.CheckboxMultioptionWidget
, OO
.ui
.MultioptionWidget
);
6824 /* Static Properties */
6826 OO
.ui
.CheckboxMultioptionWidget
.static.tagName
= 'label';
6831 * Handle checkbox selected state change.
6835 OO
.ui
.CheckboxMultioptionWidget
.prototype.onCheckboxChange = function () {
6836 this.setSelected( this.checkbox
.isSelected() );
6842 OO
.ui
.CheckboxMultioptionWidget
.prototype.setSelected = function ( state
) {
6843 OO
.ui
.CheckboxMultioptionWidget
.parent
.prototype.setSelected
.call( this, state
);
6844 this.checkbox
.setSelected( state
);
6851 OO
.ui
.CheckboxMultioptionWidget
.prototype.setDisabled = function ( disabled
) {
6852 OO
.ui
.CheckboxMultioptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
6853 this.checkbox
.setDisabled( this.isDisabled() );
6860 OO
.ui
.CheckboxMultioptionWidget
.prototype.focus = function () {
6861 this.checkbox
.focus();
6865 * Handle key down events.
6868 * @param {jQuery.Event} e
6870 OO
.ui
.CheckboxMultioptionWidget
.prototype.onKeyDown = function ( e
) {
6872 element
= this.getElementGroup(),
6875 if ( e
.keyCode
=== OO
.ui
.Keys
.LEFT
|| e
.keyCode
=== OO
.ui
.Keys
.UP
) {
6876 nextItem
= element
.getRelativeFocusableItem( this, -1 );
6877 } else if ( e
.keyCode
=== OO
.ui
.Keys
.RIGHT
|| e
.keyCode
=== OO
.ui
.Keys
.DOWN
) {
6878 nextItem
= element
.getRelativeFocusableItem( this, 1 );
6888 * CheckboxMultiselectWidget is a {@link OO.ui.MultiselectWidget multiselect widget} that contains
6889 * checkboxes and is used together with OO.ui.CheckboxMultioptionWidget. The
6890 * CheckboxMultiselectWidget provides an interface for adding, removing and selecting options.
6891 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
6893 * If you want to use this within a HTML form, such as a OO.ui.FormLayout, use
6894 * OO.ui.CheckboxMultiselectInputWidget instead.
6897 * // A CheckboxMultiselectWidget with CheckboxMultioptions.
6898 * var option1 = new OO.ui.CheckboxMultioptionWidget( {
6901 * label: 'Selected checkbox'
6904 * var option2 = new OO.ui.CheckboxMultioptionWidget( {
6906 * label: 'Unselected checkbox'
6909 * var multiselect=new OO.ui.CheckboxMultiselectWidget( {
6910 * items: [ option1, option2 ]
6913 * $( 'body' ).append( multiselect.$element );
6915 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6918 * @extends OO.ui.MultiselectWidget
6921 * @param {Object} [config] Configuration options
6923 OO
.ui
.CheckboxMultiselectWidget
= function OoUiCheckboxMultiselectWidget( config
) {
6924 // Parent constructor
6925 OO
.ui
.CheckboxMultiselectWidget
.parent
.call( this, config
);
6928 this.$lastClicked
= null;
6931 this.$group
.on( 'click', this.onClick
.bind( this ) );
6935 .addClass( 'oo-ui-checkboxMultiselectWidget' );
6940 OO
.inheritClass( OO
.ui
.CheckboxMultiselectWidget
, OO
.ui
.MultiselectWidget
);
6945 * Get an option by its position relative to the specified item (or to the start of the option array,
6946 * if item is `null`). The direction in which to search through the option array is specified with a
6947 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
6948 * `null` if there are no options in the array.
6950 * @param {OO.ui.CheckboxMultioptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
6951 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
6952 * @return {OO.ui.CheckboxMultioptionWidget|null} Item at position, `null` if there are no items in the select
6954 OO
.ui
.CheckboxMultiselectWidget
.prototype.getRelativeFocusableItem = function ( item
, direction
) {
6955 var currentIndex
, nextIndex
, i
,
6956 increase
= direction
> 0 ? 1 : -1,
6957 len
= this.items
.length
;
6960 currentIndex
= this.items
.indexOf( item
);
6961 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
6963 // If no item is selected and moving forward, start at the beginning.
6964 // If moving backward, start at the end.
6965 nextIndex
= direction
> 0 ? 0 : len
- 1;
6968 for ( i
= 0; i
< len
; i
++ ) {
6969 item
= this.items
[ nextIndex
];
6970 if ( item
&& !item
.isDisabled() ) {
6973 nextIndex
= ( nextIndex
+ increase
+ len
) % len
;
6979 * Handle click events on checkboxes.
6981 * @param {jQuery.Event} e
6983 OO
.ui
.CheckboxMultiselectWidget
.prototype.onClick = function ( e
) {
6984 var $options
, checked
,
6985 $lastClicked
= this.$lastClicked
,
6986 $nowClicked
= $( e
.target
).closest( '.oo-ui-checkboxMultioptionWidget' )
6987 .not( '.oo-ui-widget-disabled' );
6989 // Allow selecting multiple options at once by Shift-clicking them
6990 if ( $lastClicked
&& $nowClicked
.length
&& e
.shiftKey
) {
6991 $options
= this.$group
.find( '.oo-ui-checkboxMultioptionWidget' );
6992 checked
= $nowClicked
.find( 'input' ).prop( 'checked' );
6996 Math
.min( $options
.index( $lastClicked
), $options
.index( $nowClicked
) ),
6997 Math
.max( $options
.index( $lastClicked
), $options
.index( $nowClicked
) ) + 1
7000 .filter( function () {
7001 return !this.disabled
;
7003 .prop( 'checked', checked
)
7004 .trigger( 'change' );
7007 if ( $nowClicked
.length
) {
7008 this.$lastClicked
= $nowClicked
;
7013 * Element that will stick under a specified container, even when it is inserted elsewhere in the
7014 * document (for example, in a OO.ui.Window's $overlay).
7016 * The elements's position is automatically calculated and maintained when window is resized or the
7017 * page is scrolled. If you reposition the container manually, you have to call #position to make
7018 * sure the element is still placed correctly.
7020 * As positioning is only possible when both the element and the container are attached to the DOM
7021 * and visible, it's only done after you call #togglePositioning. You might want to do this inside
7022 * the #toggle method to display a floating popup, for example.
7028 * @param {Object} [config] Configuration options
7029 * @cfg {jQuery} [$floatable] Node to position, assigned to #$floatable, omit to use #$element
7030 * @cfg {jQuery} [$floatableContainer] Node to position below
7032 OO
.ui
.mixin
.FloatableElement
= function OoUiMixinFloatableElement( config
) {
7033 // Configuration initialization
7034 config
= config
|| {};
7037 this.$floatable
= null;
7038 this.$floatableContainer
= null;
7039 this.$floatableWindow
= null;
7040 this.$floatableClosestScrollable
= null;
7041 this.onFloatableScrollHandler
= this.position
.bind( this );
7042 this.onFloatableWindowResizeHandler
= this.position
.bind( this );
7045 this.setFloatableContainer( config
.$floatableContainer
);
7046 this.setFloatableElement( config
.$floatable
|| this.$element
);
7052 * Set floatable element.
7054 * If an element is already set, it will be cleaned up before setting up the new element.
7056 * @param {jQuery} $floatable Element to make floatable
7058 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableElement = function ( $floatable
) {
7059 if ( this.$floatable
) {
7060 this.$floatable
.removeClass( 'oo-ui-floatableElement-floatable' );
7061 this.$floatable
.css( { left
: '', top
: '' } );
7064 this.$floatable
= $floatable
.addClass( 'oo-ui-floatableElement-floatable' );
7069 * Set floatable container.
7071 * The element will be always positioned under the specified container.
7073 * @param {jQuery|null} $floatableContainer Container to keep visible, or null to unset
7075 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableContainer = function ( $floatableContainer
) {
7076 this.$floatableContainer
= $floatableContainer
;
7077 if ( this.$floatable
) {
7083 * Toggle positioning.
7085 * Do not turn positioning on until after the element is attached to the DOM and visible.
7087 * @param {boolean} [positioning] Enable positioning, omit to toggle
7090 OO
.ui
.mixin
.FloatableElement
.prototype.togglePositioning = function ( positioning
) {
7091 var closestScrollableOfContainer
, closestScrollableOfFloatable
;
7093 positioning
= positioning
=== undefined ? !this.positioning
: !!positioning
;
7095 if ( this.positioning
!== positioning
) {
7096 this.positioning
= positioning
;
7098 closestScrollableOfContainer
= OO
.ui
.Element
.static.getClosestScrollableContainer( this.$floatableContainer
[ 0 ] );
7099 closestScrollableOfFloatable
= OO
.ui
.Element
.static.getClosestScrollableContainer( this.$floatable
[ 0 ] );
7100 this.needsCustomPosition
= closestScrollableOfContainer
!== closestScrollableOfFloatable
;
7101 // If the scrollable is the root, we have to listen to scroll events
7102 // on the window because of browser inconsistencies.
7103 if ( $( closestScrollableOfContainer
).is( 'html, body' ) ) {
7104 closestScrollableOfContainer
= OO
.ui
.Element
.static.getWindow( closestScrollableOfContainer
);
7107 if ( positioning
) {
7108 this.$floatableWindow
= $( this.getElementWindow() );
7109 this.$floatableWindow
.on( 'resize', this.onFloatableWindowResizeHandler
);
7111 this.$floatableClosestScrollable
= $( closestScrollableOfContainer
);
7112 this.$floatableClosestScrollable
.on( 'scroll', this.onFloatableScrollHandler
);
7114 // Initial position after visible
7117 if ( this.$floatableWindow
) {
7118 this.$floatableWindow
.off( 'resize', this.onFloatableWindowResizeHandler
);
7119 this.$floatableWindow
= null;
7122 if ( this.$floatableClosestScrollable
) {
7123 this.$floatableClosestScrollable
.off( 'scroll', this.onFloatableScrollHandler
);
7124 this.$floatableClosestScrollable
= null;
7127 this.$floatable
.css( { left
: '', top
: '' } );
7135 * Check whether the bottom edge of the given element is within the viewport of the given container.
7138 * @param {jQuery} $element
7139 * @param {jQuery} $container
7142 OO
.ui
.mixin
.FloatableElement
.prototype.isElementInViewport = function ( $element
, $container
) {
7143 var elemRect
, contRect
,
7144 topEdgeInBounds
= false,
7145 leftEdgeInBounds
= false,
7146 bottomEdgeInBounds
= false,
7147 rightEdgeInBounds
= false;
7149 elemRect
= $element
[ 0 ].getBoundingClientRect();
7150 if ( $container
[ 0 ] === window
) {
7154 right
: document
.documentElement
.clientWidth
,
7155 bottom
: document
.documentElement
.clientHeight
7158 contRect
= $container
[ 0 ].getBoundingClientRect();
7161 if ( elemRect
.top
>= contRect
.top
&& elemRect
.top
<= contRect
.bottom
) {
7162 topEdgeInBounds
= true;
7164 if ( elemRect
.left
>= contRect
.left
&& elemRect
.left
<= contRect
.right
) {
7165 leftEdgeInBounds
= true;
7167 if ( elemRect
.bottom
>= contRect
.top
&& elemRect
.bottom
<= contRect
.bottom
) {
7168 bottomEdgeInBounds
= true;
7170 if ( elemRect
.right
>= contRect
.left
&& elemRect
.right
<= contRect
.right
) {
7171 rightEdgeInBounds
= true;
7174 // We only care that any part of the bottom edge is visible
7175 return bottomEdgeInBounds
&& ( leftEdgeInBounds
|| rightEdgeInBounds
);
7179 * Position the floatable below its container.
7181 * This should only be done when both of them are attached to the DOM and visible.
7185 OO
.ui
.mixin
.FloatableElement
.prototype.position = function () {
7188 if ( !this.positioning
) {
7192 if ( !this.isElementInViewport( this.$floatableContainer
, this.$floatableClosestScrollable
) ) {
7193 this.$floatable
.addClass( 'oo-ui-floatableElement-hidden' );
7196 this.$floatable
.removeClass( 'oo-ui-floatableElement-hidden' );
7199 if ( !this.needsCustomPosition
) {
7203 pos
= OO
.ui
.Element
.static.getRelativePosition( this.$floatableContainer
, this.$floatable
.offsetParent() );
7205 // Position under container
7206 pos
.top
+= this.$floatableContainer
.height();
7207 this.$floatable
.css( pos
);
7209 // We updated the position, so re-evaluate the clipping state.
7210 // (ClippableElement does not listen to 'scroll' events on $floatableContainer's parent, and so
7211 // will not notice the need to update itself.)
7212 // TODO: This is terrible, we shouldn't need to know about ClippableElement at all here. Why does
7213 // it not listen to the right events in the right places?
7222 * FloatingMenuSelectWidget is a menu that will stick under a specified
7223 * container, even when it is inserted elsewhere in the document (for example,
7224 * in a OO.ui.Window's $overlay). This is sometimes necessary to prevent the
7225 * menu from being clipped too aggresively.
7227 * The menu's position is automatically calculated and maintained when the menu
7228 * is toggled or the window is resized.
7230 * See OO.ui.ComboBoxInputWidget for an example of a widget that uses this class.
7233 * @extends OO.ui.MenuSelectWidget
7234 * @mixins OO.ui.mixin.FloatableElement
7237 * @param {OO.ui.Widget} [inputWidget] Widget to provide the menu for.
7238 * Deprecated, omit this parameter and specify `$container` instead.
7239 * @param {Object} [config] Configuration options
7240 * @cfg {jQuery} [$container=inputWidget.$element] Element to render menu under
7242 OO
.ui
.FloatingMenuSelectWidget
= function OoUiFloatingMenuSelectWidget( inputWidget
, config
) {
7243 // Allow 'inputWidget' parameter and config for backwards compatibility
7244 if ( OO
.isPlainObject( inputWidget
) && config
=== undefined ) {
7245 config
= inputWidget
;
7246 inputWidget
= config
.inputWidget
;
7249 // Configuration initialization
7250 config
= config
|| {};
7252 // Parent constructor
7253 OO
.ui
.FloatingMenuSelectWidget
.parent
.call( this, config
);
7255 // Properties (must be set before mixin constructors)
7256 this.inputWidget
= inputWidget
; // For backwards compatibility
7257 this.$container
= config
.$container
|| this.inputWidget
.$element
;
7259 // Mixins constructors
7260 OO
.ui
.mixin
.FloatableElement
.call( this, $.extend( {}, config
, { $floatableContainer
: this.$container
} ) );
7263 this.$element
.addClass( 'oo-ui-floatingMenuSelectWidget' );
7264 // For backwards compatibility
7265 this.$element
.addClass( 'oo-ui-textInputMenuSelectWidget' );
7270 OO
.inheritClass( OO
.ui
.FloatingMenuSelectWidget
, OO
.ui
.MenuSelectWidget
);
7271 OO
.mixinClass( OO
.ui
.FloatingMenuSelectWidget
, OO
.ui
.mixin
.FloatableElement
);
7273 // For backwards compatibility
7274 OO
.ui
.TextInputMenuSelectWidget
= OO
.ui
.FloatingMenuSelectWidget
;
7281 OO
.ui
.FloatingMenuSelectWidget
.prototype.toggle = function ( visible
) {
7283 visible
= visible
=== undefined ? !this.isVisible() : !!visible
;
7284 change
= visible
!== this.isVisible();
7286 if ( change
&& visible
) {
7287 // Make sure the width is set before the parent method runs.
7288 this.setIdealSize( this.$container
.width() );
7292 // This will call this.clip(), which is nonsensical since we're not positioned yet...
7293 OO
.ui
.FloatingMenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
7296 this.togglePositioning( this.isVisible() );
7303 * InputWidget is the base class for all input widgets, which
7304 * include {@link OO.ui.TextInputWidget text inputs}, {@link OO.ui.CheckboxInputWidget checkbox inputs},
7305 * {@link OO.ui.RadioInputWidget radio inputs}, and {@link OO.ui.ButtonInputWidget button inputs}.
7306 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
7308 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7312 * @extends OO.ui.Widget
7313 * @mixins OO.ui.mixin.FlaggedElement
7314 * @mixins OO.ui.mixin.TabIndexedElement
7315 * @mixins OO.ui.mixin.TitledElement
7316 * @mixins OO.ui.mixin.AccessKeyedElement
7319 * @param {Object} [config] Configuration options
7320 * @cfg {string} [name=''] The value of the input’s HTML `name` attribute.
7321 * @cfg {string} [value=''] The value of the input.
7322 * @cfg {string} [dir] The directionality of the input (ltr/rtl).
7323 * @cfg {Function} [inputFilter] The name of an input filter function. Input filters modify the value of an input
7324 * before it is accepted.
7326 OO
.ui
.InputWidget
= function OoUiInputWidget( config
) {
7327 // Configuration initialization
7328 config
= config
|| {};
7330 // Parent constructor
7331 OO
.ui
.InputWidget
.parent
.call( this, config
);
7334 // See #reusePreInfuseDOM about config.$input
7335 this.$input
= config
.$input
|| this.getInputElement( config
);
7337 this.inputFilter
= config
.inputFilter
;
7339 // Mixin constructors
7340 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
7341 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$input
} ) );
7342 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
7343 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$input
} ) );
7346 this.$input
.on( 'keydown mouseup cut paste change input select', this.onEdit
.bind( this ) );
7350 .addClass( 'oo-ui-inputWidget-input' )
7351 .attr( 'name', config
.name
)
7352 .prop( 'disabled', this.isDisabled() );
7354 .addClass( 'oo-ui-inputWidget' )
7355 .append( this.$input
);
7356 this.setValue( config
.value
);
7358 this.setDir( config
.dir
);
7364 OO
.inheritClass( OO
.ui
.InputWidget
, OO
.ui
.Widget
);
7365 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.FlaggedElement
);
7366 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TabIndexedElement
);
7367 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TitledElement
);
7368 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
7370 /* Static Properties */
7372 OO
.ui
.InputWidget
.static.supportsSimpleLabel
= true;
7374 /* Static Methods */
7379 OO
.ui
.InputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
7380 config
= OO
.ui
.InputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
7381 // Reusing $input lets browsers preserve inputted values across page reloads (T114134)
7382 config
.$input
= $( node
).find( '.oo-ui-inputWidget-input' );
7389 OO
.ui
.InputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
7390 var state
= OO
.ui
.InputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
7391 if ( config
.$input
&& config
.$input
.length
) {
7392 state
.value
= config
.$input
.val();
7393 // Might be better in TabIndexedElement, but it's awkward to do there because mixins are awkward
7394 state
.focus
= config
.$input
.is( ':focus' );
7404 * A change event is emitted when the value of the input changes.
7406 * @param {string} value
7412 * Get input element.
7414 * Subclasses of OO.ui.InputWidget use the `config` parameter to produce different elements in
7415 * different circumstances. The element must have a `value` property (like form elements).
7418 * @param {Object} config Configuration options
7419 * @return {jQuery} Input element
7421 OO
.ui
.InputWidget
.prototype.getInputElement = function () {
7422 return $( '<input>' );
7426 * Handle potentially value-changing events.
7429 * @param {jQuery.Event} e Key down, mouse up, cut, paste, change, input, or select event
7431 OO
.ui
.InputWidget
.prototype.onEdit = function () {
7433 if ( !this.isDisabled() ) {
7434 // Allow the stack to clear so the value will be updated
7435 setTimeout( function () {
7436 widget
.setValue( widget
.$input
.val() );
7442 * Get the value of the input.
7444 * @return {string} Input value
7446 OO
.ui
.InputWidget
.prototype.getValue = function () {
7447 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
7448 // it, and we won't know unless they're kind enough to trigger a 'change' event.
7449 var value
= this.$input
.val();
7450 if ( this.value
!== value
) {
7451 this.setValue( value
);
7457 * Set the directionality of the input, either RTL (right-to-left) or LTR (left-to-right).
7459 * @deprecated since v0.13.1; use #setDir directly
7460 * @param {boolean} isRTL Directionality is right-to-left
7463 OO
.ui
.InputWidget
.prototype.setRTL = function ( isRTL
) {
7464 this.setDir( isRTL
? 'rtl' : 'ltr' );
7469 * Set the directionality of the input.
7471 * @param {string} dir Text directionality: 'ltr', 'rtl' or 'auto'
7474 OO
.ui
.InputWidget
.prototype.setDir = function ( dir
) {
7475 this.$input
.prop( 'dir', dir
);
7480 * Set the value of the input.
7482 * @param {string} value New value
7486 OO
.ui
.InputWidget
.prototype.setValue = function ( value
) {
7487 value
= this.cleanUpValue( value
);
7488 // Update the DOM if it has changed. Note that with cleanUpValue, it
7489 // is possible for the DOM value to change without this.value changing.
7490 if ( this.$input
.val() !== value
) {
7491 this.$input
.val( value
);
7493 if ( this.value
!== value
) {
7495 this.emit( 'change', this.value
);
7501 * Clean up incoming value.
7503 * Ensures value is a string, and converts undefined and null to empty string.
7506 * @param {string} value Original value
7507 * @return {string} Cleaned up value
7509 OO
.ui
.InputWidget
.prototype.cleanUpValue = function ( value
) {
7510 if ( value
=== undefined || value
=== null ) {
7512 } else if ( this.inputFilter
) {
7513 return this.inputFilter( String( value
) );
7515 return String( value
);
7520 * Simulate the behavior of clicking on a label bound to this input. This method is only called by
7521 * {@link OO.ui.LabelWidget LabelWidget} and {@link OO.ui.FieldLayout FieldLayout}. It should not be
7524 OO
.ui
.InputWidget
.prototype.simulateLabelClick = function () {
7525 if ( !this.isDisabled() ) {
7526 if ( this.$input
.is( ':checkbox, :radio' ) ) {
7527 this.$input
.click();
7529 if ( this.$input
.is( ':input' ) ) {
7530 this.$input
[ 0 ].focus();
7538 OO
.ui
.InputWidget
.prototype.setDisabled = function ( state
) {
7539 OO
.ui
.InputWidget
.parent
.prototype.setDisabled
.call( this, state
);
7540 if ( this.$input
) {
7541 this.$input
.prop( 'disabled', this.isDisabled() );
7551 OO
.ui
.InputWidget
.prototype.focus = function () {
7552 this.$input
[ 0 ].focus();
7561 OO
.ui
.InputWidget
.prototype.blur = function () {
7562 this.$input
[ 0 ].blur();
7569 OO
.ui
.InputWidget
.prototype.restorePreInfuseState = function ( state
) {
7570 OO
.ui
.InputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
7571 if ( state
.value
!== undefined && state
.value
!== this.getValue() ) {
7572 this.setValue( state
.value
);
7574 if ( state
.focus
) {
7580 * ButtonInputWidget is used to submit HTML forms and is intended to be used within
7581 * a OO.ui.FormLayout. If you do not need the button to work with HTML forms, you probably
7582 * want to use OO.ui.ButtonWidget instead. Button input widgets can be rendered as either an
7583 * HTML `<button/>` (the default) or an HTML `<input/>` tags. See the
7584 * [OOjs UI documentation on MediaWiki] [1] for more information.
7587 * // A ButtonInputWidget rendered as an HTML button, the default.
7588 * var button = new OO.ui.ButtonInputWidget( {
7589 * label: 'Input button',
7593 * $( 'body' ).append( button.$element );
7595 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs#Button_inputs
7598 * @extends OO.ui.InputWidget
7599 * @mixins OO.ui.mixin.ButtonElement
7600 * @mixins OO.ui.mixin.IconElement
7601 * @mixins OO.ui.mixin.IndicatorElement
7602 * @mixins OO.ui.mixin.LabelElement
7603 * @mixins OO.ui.mixin.TitledElement
7606 * @param {Object} [config] Configuration options
7607 * @cfg {string} [type='button'] The value of the HTML `'type'` attribute: 'button', 'submit' or 'reset'.
7608 * @cfg {boolean} [useInputTag=false] Use an `<input/>` tag instead of a `<button/>` tag, the default.
7609 * Widgets configured to be an `<input/>` do not support {@link #icon icons} and {@link #indicator indicators},
7610 * non-plaintext {@link #label labels}, or {@link #value values}. In general, useInputTag should only
7611 * be set to `true` when there’s need to support IE 6 in a form with multiple buttons.
7613 OO
.ui
.ButtonInputWidget
= function OoUiButtonInputWidget( config
) {
7614 // Configuration initialization
7615 config
= $.extend( { type
: 'button', useInputTag
: false }, config
);
7617 // See InputWidget#reusePreInfuseDOM about config.$input
7618 if ( config
.$input
) {
7619 config
.$input
.empty();
7622 // Properties (must be set before parent constructor, which calls #setValue)
7623 this.useInputTag
= config
.useInputTag
;
7625 // Parent constructor
7626 OO
.ui
.ButtonInputWidget
.parent
.call( this, config
);
7628 // Mixin constructors
7629 OO
.ui
.mixin
.ButtonElement
.call( this, $.extend( {}, config
, { $button
: this.$input
} ) );
7630 OO
.ui
.mixin
.IconElement
.call( this, config
);
7631 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
7632 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7633 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
7636 if ( !config
.useInputTag
) {
7637 this.$input
.append( this.$icon
, this.$label
, this.$indicator
);
7639 this.$element
.addClass( 'oo-ui-buttonInputWidget' );
7644 OO
.inheritClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.InputWidget
);
7645 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.ButtonElement
);
7646 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IconElement
);
7647 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
7648 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.LabelElement
);
7649 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.TitledElement
);
7651 /* Static Properties */
7654 * Disable generating `<label>` elements for buttons. One would very rarely need additional label
7655 * for a button, and it's already a big clickable target, and it causes unexpected rendering.
7657 OO
.ui
.ButtonInputWidget
.static.supportsSimpleLabel
= false;
7665 OO
.ui
.ButtonInputWidget
.prototype.getInputElement = function ( config
) {
7667 type
= [ 'button', 'submit', 'reset' ].indexOf( config
.type
) !== -1 ? config
.type
: 'button';
7668 return $( '<' + ( config
.useInputTag
? 'input' : 'button' ) + ' type="' + type
+ '">' );
7674 * If #useInputTag is `true`, the label is set as the `value` of the `<input/>` tag.
7676 * @param {jQuery|string|Function|null} label Label nodes, text, a function that returns nodes or
7677 * text, or `null` for no label
7680 OO
.ui
.ButtonInputWidget
.prototype.setLabel = function ( label
) {
7681 if ( typeof label
=== 'function' ) {
7682 label
= OO
.ui
.resolveMsg( label
);
7685 if ( this.useInputTag
) {
7686 // Discard non-plaintext labels
7687 if ( typeof label
!== 'string' ) {
7691 this.$input
.val( label
);
7694 return OO
.ui
.mixin
.LabelElement
.prototype.setLabel
.call( this, label
);
7698 * Set the value of the input.
7700 * This method is disabled for button inputs configured as {@link #useInputTag <input/> tags}, as
7701 * they do not support {@link #value values}.
7703 * @param {string} value New value
7706 OO
.ui
.ButtonInputWidget
.prototype.setValue = function ( value
) {
7707 if ( !this.useInputTag
) {
7708 OO
.ui
.ButtonInputWidget
.parent
.prototype.setValue
.call( this, value
);
7714 * CheckboxInputWidgets, like HTML checkboxes, can be selected and/or configured with a value.
7715 * Note that these {@link OO.ui.InputWidget input widgets} are best laid out
7716 * in {@link OO.ui.FieldLayout field layouts} that use the {@link OO.ui.FieldLayout#align inline}
7717 * alignment. For more information, please see the [OOjs UI documentation on MediaWiki][1].
7719 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
7722 * // An example of selected, unselected, and disabled checkbox inputs
7723 * var checkbox1=new OO.ui.CheckboxInputWidget( {
7727 * var checkbox2=new OO.ui.CheckboxInputWidget( {
7730 * var checkbox3=new OO.ui.CheckboxInputWidget( {
7734 * // Create a fieldset layout with fields for each checkbox.
7735 * var fieldset = new OO.ui.FieldsetLayout( {
7736 * label: 'Checkboxes'
7738 * fieldset.addItems( [
7739 * new OO.ui.FieldLayout( checkbox1, { label: 'Selected checkbox', align: 'inline' } ),
7740 * new OO.ui.FieldLayout( checkbox2, { label: 'Unselected checkbox', align: 'inline' } ),
7741 * new OO.ui.FieldLayout( checkbox3, { label: 'Disabled checkbox', align: 'inline' } ),
7743 * $( 'body' ).append( fieldset.$element );
7745 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7748 * @extends OO.ui.InputWidget
7751 * @param {Object} [config] Configuration options
7752 * @cfg {boolean} [selected=false] Select the checkbox initially. By default, the checkbox is not selected.
7754 OO
.ui
.CheckboxInputWidget
= function OoUiCheckboxInputWidget( config
) {
7755 // Configuration initialization
7756 config
= config
|| {};
7758 // Parent constructor
7759 OO
.ui
.CheckboxInputWidget
.parent
.call( this, config
);
7763 .addClass( 'oo-ui-checkboxInputWidget' )
7764 // Required for pretty styling in MediaWiki theme
7765 .append( $( '<span>' ) );
7766 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
7771 OO
.inheritClass( OO
.ui
.CheckboxInputWidget
, OO
.ui
.InputWidget
);
7773 /* Static Methods */
7778 OO
.ui
.CheckboxInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
7779 var state
= OO
.ui
.CheckboxInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
7780 state
.checked
= config
.$input
.prop( 'checked' );
7790 OO
.ui
.CheckboxInputWidget
.prototype.getInputElement = function () {
7791 return $( '<input>' ).attr( 'type', 'checkbox' );
7797 OO
.ui
.CheckboxInputWidget
.prototype.onEdit = function () {
7799 if ( !this.isDisabled() ) {
7800 // Allow the stack to clear so the value will be updated
7801 setTimeout( function () {
7802 widget
.setSelected( widget
.$input
.prop( 'checked' ) );
7808 * Set selection state of this checkbox.
7810 * @param {boolean} state `true` for selected
7813 OO
.ui
.CheckboxInputWidget
.prototype.setSelected = function ( state
) {
7815 if ( this.selected
!== state
) {
7816 this.selected
= state
;
7817 this.$input
.prop( 'checked', this.selected
);
7818 this.emit( 'change', this.selected
);
7824 * Check if this checkbox is selected.
7826 * @return {boolean} Checkbox is selected
7828 OO
.ui
.CheckboxInputWidget
.prototype.isSelected = function () {
7829 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
7830 // it, and we won't know unless they're kind enough to trigger a 'change' event.
7831 var selected
= this.$input
.prop( 'checked' );
7832 if ( this.selected
!== selected
) {
7833 this.setSelected( selected
);
7835 return this.selected
;
7841 OO
.ui
.CheckboxInputWidget
.prototype.restorePreInfuseState = function ( state
) {
7842 OO
.ui
.CheckboxInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
7843 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
7844 this.setSelected( state
.checked
);
7849 * DropdownInputWidget is a {@link OO.ui.DropdownWidget DropdownWidget} intended to be used
7850 * within a HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
7851 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
7852 * more information about input widgets.
7854 * A DropdownInputWidget always has a value (one of the options is always selected), unless there
7855 * are no options. If no `value` configuration option is provided, the first option is selected.
7856 * If you need a state representing no value (no option being selected), use a DropdownWidget.
7858 * This and OO.ui.RadioSelectInputWidget support the same configuration options.
7861 * // Example: A DropdownInputWidget with three options
7862 * var dropdownInput = new OO.ui.DropdownInputWidget( {
7864 * { data: 'a', label: 'First' },
7865 * { data: 'b', label: 'Second'},
7866 * { data: 'c', label: 'Third' }
7869 * $( 'body' ).append( dropdownInput.$element );
7871 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7874 * @extends OO.ui.InputWidget
7875 * @mixins OO.ui.mixin.TitledElement
7878 * @param {Object} [config] Configuration options
7879 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
7880 * @cfg {Object} [dropdown] Configuration options for {@link OO.ui.DropdownWidget DropdownWidget}
7882 OO
.ui
.DropdownInputWidget
= function OoUiDropdownInputWidget( config
) {
7883 // Configuration initialization
7884 config
= config
|| {};
7886 // See InputWidget#reusePreInfuseDOM about config.$input
7887 if ( config
.$input
) {
7888 config
.$input
.addClass( 'oo-ui-element-hidden' );
7891 // Properties (must be done before parent constructor which calls #setDisabled)
7892 this.dropdownWidget
= new OO
.ui
.DropdownWidget( config
.dropdown
);
7894 // Parent constructor
7895 OO
.ui
.DropdownInputWidget
.parent
.call( this, config
);
7897 // Mixin constructors
7898 OO
.ui
.mixin
.TitledElement
.call( this, config
);
7901 this.dropdownWidget
.getMenu().connect( this, { select
: 'onMenuSelect' } );
7904 this.setOptions( config
.options
|| [] );
7906 .addClass( 'oo-ui-dropdownInputWidget' )
7907 .append( this.dropdownWidget
.$element
);
7912 OO
.inheritClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.InputWidget
);
7913 OO
.mixinClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.mixin
.TitledElement
);
7921 OO
.ui
.DropdownInputWidget
.prototype.getInputElement = function () {
7922 return $( '<input>' ).attr( 'type', 'hidden' );
7926 * Handles menu select events.
7929 * @param {OO.ui.MenuOptionWidget} item Selected menu item
7931 OO
.ui
.DropdownInputWidget
.prototype.onMenuSelect = function ( item
) {
7932 this.setValue( item
.getData() );
7938 OO
.ui
.DropdownInputWidget
.prototype.setValue = function ( value
) {
7939 value
= this.cleanUpValue( value
);
7940 this.dropdownWidget
.getMenu().selectItemByData( value
);
7941 OO
.ui
.DropdownInputWidget
.parent
.prototype.setValue
.call( this, value
);
7948 OO
.ui
.DropdownInputWidget
.prototype.setDisabled = function ( state
) {
7949 this.dropdownWidget
.setDisabled( state
);
7950 OO
.ui
.DropdownInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
7955 * Set the options available for this input.
7957 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
7960 OO
.ui
.DropdownInputWidget
.prototype.setOptions = function ( options
) {
7962 value
= this.getValue(),
7965 // Rebuild the dropdown menu
7966 this.dropdownWidget
.getMenu()
7968 .addItems( options
.map( function ( opt
) {
7969 var optValue
= widget
.cleanUpValue( opt
.data
);
7970 return new OO
.ui
.MenuOptionWidget( {
7972 label
: opt
.label
!== undefined ? opt
.label
: optValue
7976 // Restore the previous value, or reset to something sensible
7977 if ( this.dropdownWidget
.getMenu().getItemFromData( value
) ) {
7978 // Previous value is still available, ensure consistency with the dropdown
7979 this.setValue( value
);
7981 // No longer valid, reset
7982 if ( options
.length
) {
7983 this.setValue( options
[ 0 ].data
);
7993 OO
.ui
.DropdownInputWidget
.prototype.focus = function () {
7994 this.dropdownWidget
.getMenu().toggle( true );
8001 OO
.ui
.DropdownInputWidget
.prototype.blur = function () {
8002 this.dropdownWidget
.getMenu().toggle( false );
8007 * RadioInputWidget creates a single radio button. Because radio buttons are usually used as a set,
8008 * in most cases you will want to use a {@link OO.ui.RadioSelectWidget radio select}
8009 * with {@link OO.ui.RadioOptionWidget radio options} instead of this class. For more information,
8010 * please see the [OOjs UI documentation on MediaWiki][1].
8012 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
8015 * // An example of selected, unselected, and disabled radio inputs
8016 * var radio1 = new OO.ui.RadioInputWidget( {
8020 * var radio2 = new OO.ui.RadioInputWidget( {
8023 * var radio3 = new OO.ui.RadioInputWidget( {
8027 * // Create a fieldset layout with fields for each radio button.
8028 * var fieldset = new OO.ui.FieldsetLayout( {
8029 * label: 'Radio inputs'
8031 * fieldset.addItems( [
8032 * new OO.ui.FieldLayout( radio1, { label: 'Selected', align: 'inline' } ),
8033 * new OO.ui.FieldLayout( radio2, { label: 'Unselected', align: 'inline' } ),
8034 * new OO.ui.FieldLayout( radio3, { label: 'Disabled', align: 'inline' } ),
8036 * $( 'body' ).append( fieldset.$element );
8038 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8041 * @extends OO.ui.InputWidget
8044 * @param {Object} [config] Configuration options
8045 * @cfg {boolean} [selected=false] Select the radio button initially. By default, the radio button is not selected.
8047 OO
.ui
.RadioInputWidget
= function OoUiRadioInputWidget( config
) {
8048 // Configuration initialization
8049 config
= config
|| {};
8051 // Parent constructor
8052 OO
.ui
.RadioInputWidget
.parent
.call( this, config
);
8056 .addClass( 'oo-ui-radioInputWidget' )
8057 // Required for pretty styling in MediaWiki theme
8058 .append( $( '<span>' ) );
8059 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
8064 OO
.inheritClass( OO
.ui
.RadioInputWidget
, OO
.ui
.InputWidget
);
8066 /* Static Methods */
8071 OO
.ui
.RadioInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8072 var state
= OO
.ui
.RadioInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8073 state
.checked
= config
.$input
.prop( 'checked' );
8083 OO
.ui
.RadioInputWidget
.prototype.getInputElement = function () {
8084 return $( '<input>' ).attr( 'type', 'radio' );
8090 OO
.ui
.RadioInputWidget
.prototype.onEdit = function () {
8091 // RadioInputWidget doesn't track its state.
8095 * Set selection state of this radio button.
8097 * @param {boolean} state `true` for selected
8100 OO
.ui
.RadioInputWidget
.prototype.setSelected = function ( state
) {
8101 // RadioInputWidget doesn't track its state.
8102 this.$input
.prop( 'checked', state
);
8107 * Check if this radio button is selected.
8109 * @return {boolean} Radio is selected
8111 OO
.ui
.RadioInputWidget
.prototype.isSelected = function () {
8112 return this.$input
.prop( 'checked' );
8118 OO
.ui
.RadioInputWidget
.prototype.restorePreInfuseState = function ( state
) {
8119 OO
.ui
.RadioInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8120 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
8121 this.setSelected( state
.checked
);
8126 * RadioSelectInputWidget is a {@link OO.ui.RadioSelectWidget RadioSelectWidget} intended to be used
8127 * within a HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
8128 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
8129 * more information about input widgets.
8131 * This and OO.ui.DropdownInputWidget support the same configuration options.
8134 * // Example: A RadioSelectInputWidget with three options
8135 * var radioSelectInput = new OO.ui.RadioSelectInputWidget( {
8137 * { data: 'a', label: 'First' },
8138 * { data: 'b', label: 'Second'},
8139 * { data: 'c', label: 'Third' }
8142 * $( 'body' ).append( radioSelectInput.$element );
8144 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8147 * @extends OO.ui.InputWidget
8150 * @param {Object} [config] Configuration options
8151 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
8153 OO
.ui
.RadioSelectInputWidget
= function OoUiRadioSelectInputWidget( config
) {
8154 // Configuration initialization
8155 config
= config
|| {};
8157 // Properties (must be done before parent constructor which calls #setDisabled)
8158 this.radioSelectWidget
= new OO
.ui
.RadioSelectWidget();
8160 // Parent constructor
8161 OO
.ui
.RadioSelectInputWidget
.parent
.call( this, config
);
8164 this.radioSelectWidget
.connect( this, { select
: 'onMenuSelect' } );
8167 this.setOptions( config
.options
|| [] );
8169 .addClass( 'oo-ui-radioSelectInputWidget' )
8170 .append( this.radioSelectWidget
.$element
);
8175 OO
.inheritClass( OO
.ui
.RadioSelectInputWidget
, OO
.ui
.InputWidget
);
8177 /* Static Properties */
8179 OO
.ui
.RadioSelectInputWidget
.static.supportsSimpleLabel
= false;
8181 /* Static Methods */
8186 OO
.ui
.RadioSelectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8187 var state
= OO
.ui
.RadioSelectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8188 state
.value
= $( node
).find( '.oo-ui-radioInputWidget .oo-ui-inputWidget-input:checked' ).val();
8195 OO
.ui
.RadioSelectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
8196 config
= OO
.ui
.RadioSelectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
8197 // Cannot reuse the `<input type=radio>` set
8198 delete config
.$input
;
8208 OO
.ui
.RadioSelectInputWidget
.prototype.getInputElement = function () {
8209 return $( '<input>' ).attr( 'type', 'hidden' );
8213 * Handles menu select events.
8216 * @param {OO.ui.RadioOptionWidget} item Selected menu item
8218 OO
.ui
.RadioSelectInputWidget
.prototype.onMenuSelect = function ( item
) {
8219 this.setValue( item
.getData() );
8225 OO
.ui
.RadioSelectInputWidget
.prototype.setValue = function ( value
) {
8226 value
= this.cleanUpValue( value
);
8227 this.radioSelectWidget
.selectItemByData( value
);
8228 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setValue
.call( this, value
);
8235 OO
.ui
.RadioSelectInputWidget
.prototype.setDisabled = function ( state
) {
8236 this.radioSelectWidget
.setDisabled( state
);
8237 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
8242 * Set the options available for this input.
8244 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
8247 OO
.ui
.RadioSelectInputWidget
.prototype.setOptions = function ( options
) {
8249 value
= this.getValue(),
8252 // Rebuild the radioSelect menu
8253 this.radioSelectWidget
8255 .addItems( options
.map( function ( opt
) {
8256 var optValue
= widget
.cleanUpValue( opt
.data
);
8257 return new OO
.ui
.RadioOptionWidget( {
8259 label
: opt
.label
!== undefined ? opt
.label
: optValue
8263 // Restore the previous value, or reset to something sensible
8264 if ( this.radioSelectWidget
.getItemFromData( value
) ) {
8265 // Previous value is still available, ensure consistency with the radioSelect
8266 this.setValue( value
);
8268 // No longer valid, reset
8269 if ( options
.length
) {
8270 this.setValue( options
[ 0 ].data
);
8278 * CheckboxMultiselectInputWidget is a
8279 * {@link OO.ui.CheckboxMultiselectWidget CheckboxMultiselectWidget} intended to be used within a
8280 * HTML form, such as a OO.ui.FormLayout. The selected values are synchronized with the value of
8281 * HTML `<input type=checkbox>` tags. Please see the [OOjs UI documentation on MediaWiki][1] for
8282 * more information about input widgets.
8285 * // Example: A CheckboxMultiselectInputWidget with three options
8286 * var multiselectInput = new OO.ui.CheckboxMultiselectInputWidget( {
8288 * { data: 'a', label: 'First' },
8289 * { data: 'b', label: 'Second'},
8290 * { data: 'c', label: 'Third' }
8293 * $( 'body' ).append( multiselectInput.$element );
8295 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8298 * @extends OO.ui.InputWidget
8301 * @param {Object} [config] Configuration options
8302 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
8304 OO
.ui
.CheckboxMultiselectInputWidget
= function OoUiCheckboxMultiselectInputWidget( config
) {
8305 // Configuration initialization
8306 config
= config
|| {};
8308 // Properties (must be done before parent constructor which calls #setDisabled)
8309 this.checkboxMultiselectWidget
= new OO
.ui
.CheckboxMultiselectWidget();
8311 // Parent constructor
8312 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.call( this, config
);
8315 this.inputName
= config
.name
;
8319 .addClass( 'oo-ui-checkboxMultiselectInputWidget' )
8320 .append( this.checkboxMultiselectWidget
.$element
);
8321 // We don't use this.$input, but rather the CheckboxInputWidgets inside each option
8322 this.$input
.detach();
8323 this.setOptions( config
.options
|| [] );
8324 // Have to repeat this from parent, as we need options to be set up for this to make sense
8325 this.setValue( config
.value
);
8330 OO
.inheritClass( OO
.ui
.CheckboxMultiselectInputWidget
, OO
.ui
.InputWidget
);
8332 /* Static Properties */
8334 OO
.ui
.CheckboxMultiselectInputWidget
.static.supportsSimpleLabel
= false;
8336 /* Static Methods */
8341 OO
.ui
.CheckboxMultiselectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8342 var state
= OO
.ui
.CheckboxMultiselectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8343 state
.value
= $( node
).find( '.oo-ui-checkboxInputWidget .oo-ui-inputWidget-input:checked' )
8344 .toArray().map( function ( el
) { return el
.value
; } );
8351 OO
.ui
.CheckboxMultiselectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
8352 config
= OO
.ui
.CheckboxMultiselectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
8353 // Cannot reuse the `<input type=checkbox>` set
8354 delete config
.$input
;
8364 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.getInputElement = function () {
8366 return $( '<div>' );
8372 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.getValue = function () {
8373 var value
= this.$element
.find( '.oo-ui-checkboxInputWidget .oo-ui-inputWidget-input:checked' )
8374 .toArray().map( function ( el
) { return el
.value
; } );
8375 if ( this.value
!== value
) {
8376 this.setValue( value
);
8384 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setValue = function ( value
) {
8385 value
= this.cleanUpValue( value
);
8386 this.checkboxMultiselectWidget
.selectItemsByData( value
);
8387 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.setValue
.call( this, value
);
8392 * Clean up incoming value.
8394 * @param {string[]} value Original value
8395 * @return {string[]} Cleaned up value
8397 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.cleanUpValue = function ( value
) {
8400 if ( !Array
.isArray( value
) ) {
8403 for ( i
= 0; i
< value
.length
; i
++ ) {
8405 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.cleanUpValue
.call( this, value
[ i
] );
8406 // Remove options that we don't have here
8407 if ( !this.checkboxMultiselectWidget
.getItemFromData( singleValue
) ) {
8410 cleanValue
.push( singleValue
);
8418 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setDisabled = function ( state
) {
8419 this.checkboxMultiselectWidget
.setDisabled( state
);
8420 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
8425 * Set the options available for this input.
8427 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
8430 OO
.ui
.CheckboxMultiselectInputWidget
.prototype.setOptions = function ( options
) {
8433 // Rebuild the checkboxMultiselectWidget menu
8434 this.checkboxMultiselectWidget
8436 .addItems( options
.map( function ( opt
) {
8439 OO
.ui
.CheckboxMultiselectInputWidget
.parent
.prototype.cleanUpValue
.call( widget
, opt
.data
);
8440 item
= new OO
.ui
.CheckboxMultioptionWidget( {
8442 label
: opt
.label
!== undefined ? opt
.label
: optValue
8444 // Set the 'name' and 'value' for form submission
8445 item
.checkbox
.$input
.attr( 'name', widget
.inputName
);
8446 item
.checkbox
.setValue( optValue
);
8450 // Re-set the value, checking the checkboxes as needed.
8451 // This will also get rid of any stale options that we just removed.
8452 this.setValue( this.getValue() );
8458 * TextInputWidgets, like HTML text inputs, can be configured with options that customize the
8459 * size of the field as well as its presentation. In addition, these widgets can be configured
8460 * with {@link OO.ui.mixin.IconElement icons}, {@link OO.ui.mixin.IndicatorElement indicators}, an optional
8461 * validation-pattern (used to determine if an input value is valid or not) and an input filter,
8462 * which modifies incoming values rather than validating them.
8463 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
8465 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
8468 * // Example of a text input widget
8469 * var textInput = new OO.ui.TextInputWidget( {
8470 * value: 'Text input'
8472 * $( 'body' ).append( textInput.$element );
8474 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
8477 * @extends OO.ui.InputWidget
8478 * @mixins OO.ui.mixin.IconElement
8479 * @mixins OO.ui.mixin.IndicatorElement
8480 * @mixins OO.ui.mixin.PendingElement
8481 * @mixins OO.ui.mixin.LabelElement
8484 * @param {Object} [config] Configuration options
8485 * @cfg {string} [type='text'] The value of the HTML `type` attribute: 'text', 'password', 'search',
8486 * 'email', 'url', 'date' or 'number'. Ignored if `multiline` is true.
8488 * Some values of `type` result in additional behaviors:
8490 * - `search`: implies `icon: 'search'` and `indicator: 'clear'`; when clicked, the indicator
8491 * empties the text field
8492 * @cfg {string} [placeholder] Placeholder text
8493 * @cfg {boolean} [autofocus=false] Use an HTML `autofocus` attribute to
8494 * instruct the browser to focus this widget.
8495 * @cfg {boolean} [readOnly=false] Prevent changes to the value of the text input.
8496 * @cfg {number} [maxLength] Maximum number of characters allowed in the input.
8497 * @cfg {boolean} [multiline=false] Allow multiple lines of text
8498 * @cfg {number} [rows] If multiline, number of visible lines in textarea. If used with `autosize`,
8499 * specifies minimum number of rows to display.
8500 * @cfg {boolean} [autosize=false] Automatically resize the text input to fit its content.
8501 * Use the #maxRows config to specify a maximum number of displayed rows.
8502 * @cfg {boolean} [maxRows] Maximum number of rows to display when #autosize is set to true.
8503 * Defaults to the maximum of `10` and `2 * rows`, or `10` if `rows` isn't provided.
8504 * @cfg {string} [labelPosition='after'] The position of the inline label relative to that of
8505 * the value or placeholder text: `'before'` or `'after'`
8506 * @cfg {boolean} [required=false] Mark the field as required. Implies `indicator: 'required'`.
8507 * @cfg {boolean} [autocomplete=true] Should the browser support autocomplete for this field
8508 * @cfg {RegExp|Function|string} [validate] Validation pattern: when string, a symbolic name of a
8509 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer'
8510 * (the value must contain only numbers); when RegExp, a regular expression that must match the
8511 * value for it to be considered valid; when Function, a function receiving the value as parameter
8512 * that must return true, or promise resolving to true, for it to be considered valid.
8514 OO
.ui
.TextInputWidget
= function OoUiTextInputWidget( config
) {
8515 // Configuration initialization
8516 config
= $.extend( {
8518 labelPosition
: 'after'
8520 if ( config
.type
=== 'search' ) {
8521 if ( config
.icon
=== undefined ) {
8522 config
.icon
= 'search';
8524 // indicator: 'clear' is set dynamically later, depending on value
8526 if ( config
.required
) {
8527 if ( config
.indicator
=== undefined ) {
8528 config
.indicator
= 'required';
8532 // Parent constructor
8533 OO
.ui
.TextInputWidget
.parent
.call( this, config
);
8535 // Mixin constructors
8536 OO
.ui
.mixin
.IconElement
.call( this, config
);
8537 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
8538 OO
.ui
.mixin
.PendingElement
.call( this, $.extend( {}, config
, { $pending
: this.$input
} ) );
8539 OO
.ui
.mixin
.LabelElement
.call( this, config
);
8542 this.type
= this.getSaneType( config
);
8543 this.readOnly
= false;
8544 this.multiline
= !!config
.multiline
;
8545 this.autosize
= !!config
.autosize
;
8546 this.minRows
= config
.rows
!== undefined ? config
.rows
: '';
8547 this.maxRows
= config
.maxRows
|| Math
.max( 2 * ( this.minRows
|| 0 ), 10 );
8548 this.validate
= null;
8549 this.styleHeight
= null;
8550 this.scrollWidth
= null;
8552 // Clone for resizing
8553 if ( this.autosize
) {
8554 this.$clone
= this.$input
8556 .insertAfter( this.$input
)
8557 .attr( 'aria-hidden', 'true' )
8558 .addClass( 'oo-ui-element-hidden' );
8561 this.setValidation( config
.validate
);
8562 this.setLabelPosition( config
.labelPosition
);
8566 keypress
: this.onKeyPress
.bind( this ),
8567 blur
: this.onBlur
.bind( this )
8570 focus
: this.onElementAttach
.bind( this )
8572 this.$icon
.on( 'mousedown', this.onIconMouseDown
.bind( this ) );
8573 this.$indicator
.on( 'mousedown', this.onIndicatorMouseDown
.bind( this ) );
8574 this.on( 'labelChange', this.updatePosition
.bind( this ) );
8575 this.connect( this, {
8577 disable
: 'onDisable'
8582 .addClass( 'oo-ui-textInputWidget oo-ui-textInputWidget-type-' + this.type
)
8583 .append( this.$icon
, this.$indicator
);
8584 this.setReadOnly( !!config
.readOnly
);
8585 this.updateSearchIndicator();
8586 if ( config
.placeholder
!== undefined ) {
8587 this.$input
.attr( 'placeholder', config
.placeholder
);
8589 if ( config
.maxLength
!== undefined ) {
8590 this.$input
.attr( 'maxlength', config
.maxLength
);
8592 if ( config
.autofocus
) {
8593 this.$input
.attr( 'autofocus', 'autofocus' );
8595 if ( config
.required
) {
8596 this.$input
.attr( 'required', 'required' );
8597 this.$input
.attr( 'aria-required', 'true' );
8599 if ( config
.autocomplete
=== false ) {
8600 this.$input
.attr( 'autocomplete', 'off' );
8601 // Turning off autocompletion also disables "form caching" when the user navigates to a
8602 // different page and then clicks "Back". Re-enable it when leaving. Borrowed from jQuery UI.
8604 beforeunload: function () {
8605 this.$input
.removeAttr( 'autocomplete' );
8607 pageshow: function () {
8608 // Browsers don't seem to actually fire this event on "Back", they instead just reload the
8609 // whole page... it shouldn't hurt, though.
8610 this.$input
.attr( 'autocomplete', 'off' );
8614 if ( this.multiline
&& config
.rows
) {
8615 this.$input
.attr( 'rows', config
.rows
);
8617 if ( this.label
|| config
.autosize
) {
8618 this.installParentChangeDetector();
8624 OO
.inheritClass( OO
.ui
.TextInputWidget
, OO
.ui
.InputWidget
);
8625 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IconElement
);
8626 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
8627 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.PendingElement
);
8628 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.LabelElement
);
8630 /* Static Properties */
8632 OO
.ui
.TextInputWidget
.static.validationPatterns
= {
8637 /* Static Methods */
8642 OO
.ui
.TextInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8643 var state
= OO
.ui
.TextInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8644 if ( config
.multiline
) {
8645 state
.scrollTop
= config
.$input
.scrollTop();
8653 * An `enter` event is emitted when the user presses 'enter' inside the text box.
8655 * Not emitted if the input is multiline.
8661 * A `resize` event is emitted when autosize is set and the widget resizes
8669 * Handle icon mouse down events.
8672 * @param {jQuery.Event} e Mouse down event
8674 OO
.ui
.TextInputWidget
.prototype.onIconMouseDown = function ( e
) {
8675 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
8676 this.$input
[ 0 ].focus();
8682 * Handle indicator mouse down events.
8685 * @param {jQuery.Event} e Mouse down event
8687 OO
.ui
.TextInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
8688 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
8689 if ( this.type
=== 'search' ) {
8690 // Clear the text field
8691 this.setValue( '' );
8693 this.$input
[ 0 ].focus();
8699 * Handle key press events.
8702 * @param {jQuery.Event} e Key press event
8703 * @fires enter If enter key is pressed and input is not multiline
8705 OO
.ui
.TextInputWidget
.prototype.onKeyPress = function ( e
) {
8706 if ( e
.which
=== OO
.ui
.Keys
.ENTER
&& !this.multiline
) {
8707 this.emit( 'enter', e
);
8712 * Handle blur events.
8715 * @param {jQuery.Event} e Blur event
8717 OO
.ui
.TextInputWidget
.prototype.onBlur = function () {
8718 this.setValidityFlag();
8722 * Handle element attach events.
8725 * @param {jQuery.Event} e Element attach event
8727 OO
.ui
.TextInputWidget
.prototype.onElementAttach = function () {
8728 // Any previously calculated size is now probably invalid if we reattached elsewhere
8729 this.valCache
= null;
8731 this.positionLabel();
8735 * Handle change events.
8737 * @param {string} value
8740 OO
.ui
.TextInputWidget
.prototype.onChange = function () {
8741 this.updateSearchIndicator();
8742 this.setValidityFlag();
8747 * Handle disable events.
8749 * @param {boolean} disabled Element is disabled
8752 OO
.ui
.TextInputWidget
.prototype.onDisable = function () {
8753 this.updateSearchIndicator();
8757 * Check if the input is {@link #readOnly read-only}.
8761 OO
.ui
.TextInputWidget
.prototype.isReadOnly = function () {
8762 return this.readOnly
;
8766 * Set the {@link #readOnly read-only} state of the input.
8768 * @param {boolean} state Make input read-only
8771 OO
.ui
.TextInputWidget
.prototype.setReadOnly = function ( state
) {
8772 this.readOnly
= !!state
;
8773 this.$input
.prop( 'readOnly', this.readOnly
);
8774 this.updateSearchIndicator();
8779 * Support function for making #onElementAttach work across browsers.
8781 * This whole function could be replaced with one line of code using the DOMNodeInsertedIntoDocument
8782 * event, but it's not supported by Firefox and allegedly deprecated, so we only use it as fallback.
8784 * Due to MutationObserver performance woes, #onElementAttach is only somewhat reliably called the
8785 * first time that the element gets attached to the documented.
8787 OO
.ui
.TextInputWidget
.prototype.installParentChangeDetector = function () {
8788 var mutationObserver
, onRemove
, topmostNode
, fakeParentNode
,
8789 MutationObserver
= window
.MutationObserver
|| window
.WebKitMutationObserver
|| window
.MozMutationObserver
,
8792 if ( MutationObserver
) {
8793 // The new way. If only it wasn't so ugly.
8795 if ( this.$element
.closest( 'html' ).length
) {
8796 // Widget is attached already, do nothing. This breaks the functionality of this function when
8797 // the widget is detached and reattached. Alas, doing this correctly with MutationObserver
8798 // would require observation of the whole document, which would hurt performance of other,
8799 // more important code.
8803 // Find topmost node in the tree
8804 topmostNode
= this.$element
[ 0 ];
8805 while ( topmostNode
.parentNode
) {
8806 topmostNode
= topmostNode
.parentNode
;
8809 // We have no way to detect the $element being attached somewhere without observing the entire
8810 // DOM with subtree modifications, which would hurt performance. So we cheat: we hook to the
8811 // parent node of $element, and instead detect when $element is removed from it (and thus
8812 // probably attached somewhere else). If there is no parent, we create a "fake" one. If it
8813 // doesn't get attached, we end up back here and create the parent.
8815 mutationObserver
= new MutationObserver( function ( mutations
) {
8816 var i
, j
, removedNodes
;
8817 for ( i
= 0; i
< mutations
.length
; i
++ ) {
8818 removedNodes
= mutations
[ i
].removedNodes
;
8819 for ( j
= 0; j
< removedNodes
.length
; j
++ ) {
8820 if ( removedNodes
[ j
] === topmostNode
) {
8821 setTimeout( onRemove
, 0 );
8828 onRemove = function () {
8829 // If the node was attached somewhere else, report it
8830 if ( widget
.$element
.closest( 'html' ).length
) {
8831 widget
.onElementAttach();
8833 mutationObserver
.disconnect();
8834 widget
.installParentChangeDetector();
8837 // Create a fake parent and observe it
8838 fakeParentNode
= $( '<div>' ).append( topmostNode
)[ 0 ];
8839 mutationObserver
.observe( fakeParentNode
, { childList
: true } );
8841 // Using the DOMNodeInsertedIntoDocument event is much nicer and less magical, and works for
8842 // detachment and reattachment, but it's not supported by Firefox and allegedly deprecated.
8843 this.$element
.on( 'DOMNodeInsertedIntoDocument', this.onElementAttach
.bind( this ) );
8848 * Automatically adjust the size of the text input.
8850 * This only affects #multiline inputs that are {@link #autosize autosized}.
8855 OO
.ui
.TextInputWidget
.prototype.adjustSize = function () {
8856 var scrollHeight
, innerHeight
, outerHeight
, maxInnerHeight
, measurementError
,
8857 idealHeight
, newHeight
, scrollWidth
, property
;
8859 if ( this.multiline
&& this.$input
.val() !== this.valCache
) {
8860 if ( this.autosize
) {
8862 .val( this.$input
.val() )
8863 .attr( 'rows', this.minRows
)
8864 // Set inline height property to 0 to measure scroll height
8865 .css( 'height', 0 );
8867 this.$clone
.removeClass( 'oo-ui-element-hidden' );
8869 this.valCache
= this.$input
.val();
8871 scrollHeight
= this.$clone
[ 0 ].scrollHeight
;
8873 // Remove inline height property to measure natural heights
8874 this.$clone
.css( 'height', '' );
8875 innerHeight
= this.$clone
.innerHeight();
8876 outerHeight
= this.$clone
.outerHeight();
8878 // Measure max rows height
8880 .attr( 'rows', this.maxRows
)
8881 .css( 'height', 'auto' )
8883 maxInnerHeight
= this.$clone
.innerHeight();
8885 // Difference between reported innerHeight and scrollHeight with no scrollbars present.
8886 // This is sometimes non-zero on Blink-based browsers, depending on zoom level.
8887 measurementError
= maxInnerHeight
- this.$clone
[ 0 ].scrollHeight
;
8888 idealHeight
= Math
.min( maxInnerHeight
, scrollHeight
+ measurementError
);
8890 this.$clone
.addClass( 'oo-ui-element-hidden' );
8892 // Only apply inline height when expansion beyond natural height is needed
8893 // Use the difference between the inner and outer height as a buffer
8894 newHeight
= idealHeight
> innerHeight
? idealHeight
+ ( outerHeight
- innerHeight
) : '';
8895 if ( newHeight
!== this.styleHeight
) {
8896 this.$input
.css( 'height', newHeight
);
8897 this.styleHeight
= newHeight
;
8898 this.emit( 'resize' );
8901 scrollWidth
= this.$input
[ 0 ].offsetWidth
- this.$input
[ 0 ].clientWidth
;
8902 if ( scrollWidth
!== this.scrollWidth
) {
8903 property
= this.$element
.css( 'direction' ) === 'rtl' ? 'left' : 'right';
8905 this.$label
.css( { right
: '', left
: '' } );
8906 this.$indicator
.css( { right
: '', left
: '' } );
8908 if ( scrollWidth
) {
8909 this.$indicator
.css( property
, scrollWidth
);
8910 if ( this.labelPosition
=== 'after' ) {
8911 this.$label
.css( property
, scrollWidth
);
8915 this.scrollWidth
= scrollWidth
;
8916 this.positionLabel();
8926 OO
.ui
.TextInputWidget
.prototype.getInputElement = function ( config
) {
8927 if ( config
.multiline
) {
8928 return $( '<textarea>' );
8929 } else if ( this.getSaneType( config
) === 'number' ) {
8930 return $( '<input>' )
8931 .attr( 'step', 'any' )
8932 .attr( 'type', 'number' );
8934 return $( '<input>' ).attr( 'type', this.getSaneType( config
) );
8939 * Get sanitized value for 'type' for given config.
8941 * @param {Object} config Configuration options
8942 * @return {string|null}
8945 OO
.ui
.TextInputWidget
.prototype.getSaneType = function ( config
) {
8946 var allowedTypes
= [
8955 return allowedTypes
.indexOf( config
.type
) !== -1 ? config
.type
: 'text';
8959 * Check if the input supports multiple lines.
8963 OO
.ui
.TextInputWidget
.prototype.isMultiline = function () {
8964 return !!this.multiline
;
8968 * Check if the input automatically adjusts its size.
8972 OO
.ui
.TextInputWidget
.prototype.isAutosizing = function () {
8973 return !!this.autosize
;
8977 * Focus the input and select a specified range within the text.
8979 * @param {number} from Select from offset
8980 * @param {number} [to] Select to offset, defaults to from
8983 OO
.ui
.TextInputWidget
.prototype.selectRange = function ( from, to
) {
8984 var isBackwards
, start
, end
,
8985 input
= this.$input
[ 0 ];
8989 isBackwards
= to
< from;
8990 start
= isBackwards
? to
: from;
8991 end
= isBackwards
? from : to
;
8996 input
.setSelectionRange( start
, end
, isBackwards
? 'backward' : 'forward' );
8998 // IE throws an exception if you call setSelectionRange on a unattached DOM node.
8999 // Rather than expensively check if the input is attached every time, just check
9000 // if it was the cause of an error being thrown. If not, rethrow the error.
9001 if ( this.getElementDocument().body
.contains( input
) ) {
9009 * Get an object describing the current selection range in a directional manner
9011 * @return {Object} Object containing 'from' and 'to' offsets
9013 OO
.ui
.TextInputWidget
.prototype.getRange = function () {
9014 var input
= this.$input
[ 0 ],
9015 start
= input
.selectionStart
,
9016 end
= input
.selectionEnd
,
9017 isBackwards
= input
.selectionDirection
=== 'backward';
9020 from: isBackwards
? end
: start
,
9021 to
: isBackwards
? start
: end
9026 * Get the length of the text input value.
9028 * This could differ from the length of #getValue if the
9029 * value gets filtered
9031 * @return {number} Input length
9033 OO
.ui
.TextInputWidget
.prototype.getInputLength = function () {
9034 return this.$input
[ 0 ].value
.length
;
9038 * Focus the input and select the entire text.
9042 OO
.ui
.TextInputWidget
.prototype.select = function () {
9043 return this.selectRange( 0, this.getInputLength() );
9047 * Focus the input and move the cursor to the start.
9051 OO
.ui
.TextInputWidget
.prototype.moveCursorToStart = function () {
9052 return this.selectRange( 0 );
9056 * Focus the input and move the cursor to the end.
9060 OO
.ui
.TextInputWidget
.prototype.moveCursorToEnd = function () {
9061 return this.selectRange( this.getInputLength() );
9065 * Insert new content into the input.
9067 * @param {string} content Content to be inserted
9070 OO
.ui
.TextInputWidget
.prototype.insertContent = function ( content
) {
9072 range
= this.getRange(),
9073 value
= this.getValue();
9075 start
= Math
.min( range
.from, range
.to
);
9076 end
= Math
.max( range
.from, range
.to
);
9078 this.setValue( value
.slice( 0, start
) + content
+ value
.slice( end
) );
9079 this.selectRange( start
+ content
.length
);
9084 * Insert new content either side of a selection.
9086 * @param {string} pre Content to be inserted before the selection
9087 * @param {string} post Content to be inserted after the selection
9090 OO
.ui
.TextInputWidget
.prototype.encapsulateContent = function ( pre
, post
) {
9092 range
= this.getRange(),
9093 offset
= pre
.length
;
9095 start
= Math
.min( range
.from, range
.to
);
9096 end
= Math
.max( range
.from, range
.to
);
9098 this.selectRange( start
).insertContent( pre
);
9099 this.selectRange( offset
+ end
).insertContent( post
);
9101 this.selectRange( offset
+ start
, offset
+ end
);
9106 * Set the validation pattern.
9108 * The validation pattern is either a regular expression, a function, or the symbolic name of a
9109 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer' (the
9110 * value must contain only numbers).
9112 * @param {RegExp|Function|string|null} validate Regular expression, function, or the symbolic name
9113 * of a pattern (either ‘integer’ or ‘non-empty’) defined by the class.
9115 OO
.ui
.TextInputWidget
.prototype.setValidation = function ( validate
) {
9116 if ( validate
instanceof RegExp
|| validate
instanceof Function
) {
9117 this.validate
= validate
;
9119 this.validate
= this.constructor.static.validationPatterns
[ validate
] || /.*/;
9124 * Sets the 'invalid' flag appropriately.
9126 * @param {boolean} [isValid] Optionally override validation result
9128 OO
.ui
.TextInputWidget
.prototype.setValidityFlag = function ( isValid
) {
9130 setFlag = function ( valid
) {
9132 widget
.$input
.attr( 'aria-invalid', 'true' );
9134 widget
.$input
.removeAttr( 'aria-invalid' );
9136 widget
.setFlags( { invalid
: !valid
} );
9139 if ( isValid
!== undefined ) {
9142 this.getValidity().then( function () {
9151 * Check if a value is valid.
9153 * This method returns a promise that resolves with a boolean `true` if the current value is
9154 * considered valid according to the supplied {@link #validate validation pattern}.
9156 * @deprecated since v0.12.3
9157 * @return {jQuery.Promise} A promise that resolves to a boolean `true` if the value is valid.
9159 OO
.ui
.TextInputWidget
.prototype.isValid = function () {
9162 if ( this.validate
instanceof Function
) {
9163 result
= this.validate( this.getValue() );
9164 if ( result
&& $.isFunction( result
.promise
) ) {
9165 return result
.promise();
9167 return $.Deferred().resolve( !!result
).promise();
9170 return $.Deferred().resolve( !!this.getValue().match( this.validate
) ).promise();
9175 * Get the validity of current value.
9177 * This method returns a promise that resolves if the value is valid and rejects if
9178 * it isn't. Uses the {@link #validate validation pattern} to check for validity.
9180 * @return {jQuery.Promise} A promise that resolves if the value is valid, rejects if not.
9182 OO
.ui
.TextInputWidget
.prototype.getValidity = function () {
9185 function rejectOrResolve( valid
) {
9187 return $.Deferred().resolve().promise();
9189 return $.Deferred().reject().promise();
9193 if ( this.validate
instanceof Function
) {
9194 result
= this.validate( this.getValue() );
9195 if ( result
&& $.isFunction( result
.promise
) ) {
9196 return result
.promise().then( function ( valid
) {
9197 return rejectOrResolve( valid
);
9200 return rejectOrResolve( result
);
9203 return rejectOrResolve( this.getValue().match( this.validate
) );
9208 * Set the position of the inline label relative to that of the value: `‘before’` or `‘after’`.
9210 * @param {string} labelPosition Label position, 'before' or 'after'
9213 OO
.ui
.TextInputWidget
.prototype.setLabelPosition = function ( labelPosition
) {
9214 this.labelPosition
= labelPosition
;
9216 // If there is no label and we only change the position, #updatePosition is a no-op,
9217 // but it takes really a lot of work to do nothing.
9218 this.updatePosition();
9224 * Update the position of the inline label.
9226 * This method is called by #setLabelPosition, and can also be called on its own if
9227 * something causes the label to be mispositioned.
9231 OO
.ui
.TextInputWidget
.prototype.updatePosition = function () {
9232 var after
= this.labelPosition
=== 'after';
9235 .toggleClass( 'oo-ui-textInputWidget-labelPosition-after', !!this.label
&& after
)
9236 .toggleClass( 'oo-ui-textInputWidget-labelPosition-before', !!this.label
&& !after
);
9238 this.valCache
= null;
9239 this.scrollWidth
= null;
9241 this.positionLabel();
9247 * Update the 'clear' indicator displayed on type: 'search' text fields, hiding it when the field is
9248 * already empty or when it's not editable.
9250 OO
.ui
.TextInputWidget
.prototype.updateSearchIndicator = function () {
9251 if ( this.type
=== 'search' ) {
9252 if ( this.getValue() === '' || this.isDisabled() || this.isReadOnly() ) {
9253 this.setIndicator( null );
9255 this.setIndicator( 'clear' );
9261 * Position the label by setting the correct padding on the input.
9266 OO
.ui
.TextInputWidget
.prototype.positionLabel = function () {
9267 var after
, rtl
, property
;
9270 // Clear old values if present
9272 'padding-right': '',
9277 this.$element
.append( this.$label
);
9279 this.$label
.detach();
9283 after
= this.labelPosition
=== 'after';
9284 rtl
= this.$element
.css( 'direction' ) === 'rtl';
9285 property
= after
=== rtl
? 'padding-left' : 'padding-right';
9287 this.$input
.css( property
, this.$label
.outerWidth( true ) + ( after
? this.scrollWidth
: 0 ) );
9295 OO
.ui
.TextInputWidget
.prototype.restorePreInfuseState = function ( state
) {
9296 OO
.ui
.TextInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
9297 if ( state
.scrollTop
!== undefined ) {
9298 this.$input
.scrollTop( state
.scrollTop
);
9303 * ComboBoxInputWidgets combine a {@link OO.ui.TextInputWidget text input} (where a value
9304 * can be entered manually) and a {@link OO.ui.MenuSelectWidget menu of options} (from which
9305 * a value can be chosen instead). Users can choose options from the combo box in one of two ways:
9307 * - by typing a value in the text input field. If the value exactly matches the value of a menu
9308 * option, that option will appear to be selected.
9309 * - by choosing a value from the menu. The value of the chosen option will then appear in the text
9312 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
9314 * For more information about menus and options, please see the [OOjs UI documentation on MediaWiki][1].
9317 * // Example: A ComboBoxInputWidget.
9318 * var comboBox = new OO.ui.ComboBoxInputWidget( {
9319 * label: 'ComboBoxInputWidget',
9320 * value: 'Option 1',
9323 * new OO.ui.MenuOptionWidget( {
9325 * label: 'Option One'
9327 * new OO.ui.MenuOptionWidget( {
9329 * label: 'Option Two'
9331 * new OO.ui.MenuOptionWidget( {
9333 * label: 'Option Three'
9335 * new OO.ui.MenuOptionWidget( {
9337 * label: 'Option Four'
9339 * new OO.ui.MenuOptionWidget( {
9341 * label: 'Option Five'
9346 * $( 'body' ).append( comboBox.$element );
9348 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
9351 * @extends OO.ui.TextInputWidget
9354 * @param {Object} [config] Configuration options
9355 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
9356 * @cfg {Object} [menu] Configuration options to pass to the {@link OO.ui.FloatingMenuSelectWidget menu select widget}.
9357 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
9358 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
9359 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
9361 OO
.ui
.ComboBoxInputWidget
= function OoUiComboBoxInputWidget( config
) {
9362 // Configuration initialization
9363 config
= $.extend( {
9367 // For backwards-compatibility with ComboBoxWidget config
9368 $.extend( config
, config
.input
);
9370 // Parent constructor
9371 OO
.ui
.ComboBoxInputWidget
.parent
.call( this, config
);
9374 this.$overlay
= config
.$overlay
|| this.$element
;
9375 this.menu
= new OO
.ui
.FloatingMenuSelectWidget( $.extend(
9379 $container
: this.$element
,
9380 disabled
: this.isDisabled()
9384 // For backwards-compatibility with ComboBoxWidget
9388 this.$indicator
.on( {
9389 click
: this.onIndicatorClick
.bind( this ),
9390 keypress
: this.onIndicatorKeyPress
.bind( this )
9392 this.connect( this, {
9393 change
: 'onInputChange',
9394 enter
: 'onInputEnter'
9396 this.menu
.connect( this, {
9397 choose
: 'onMenuChoose',
9398 add
: 'onMenuItemsChange',
9399 remove
: 'onMenuItemsChange'
9405 'aria-autocomplete': 'list'
9407 // Do not override options set via config.menu.items
9408 if ( config
.options
!== undefined ) {
9409 this.setOptions( config
.options
);
9411 // Extra class for backwards-compatibility with ComboBoxWidget
9412 this.$element
.addClass( 'oo-ui-comboBoxInputWidget oo-ui-comboBoxWidget' );
9413 this.$overlay
.append( this.menu
.$element
);
9414 this.onMenuItemsChange();
9419 OO
.inheritClass( OO
.ui
.ComboBoxInputWidget
, OO
.ui
.TextInputWidget
);
9424 * Get the combobox's menu.
9426 * @return {OO.ui.FloatingMenuSelectWidget} Menu widget
9428 OO
.ui
.ComboBoxInputWidget
.prototype.getMenu = function () {
9433 * Get the combobox's text input widget.
9435 * @return {OO.ui.TextInputWidget} Text input widget
9437 OO
.ui
.ComboBoxInputWidget
.prototype.getInput = function () {
9442 * Handle input change events.
9445 * @param {string} value New value
9447 OO
.ui
.ComboBoxInputWidget
.prototype.onInputChange = function ( value
) {
9448 var match
= this.menu
.getItemFromData( value
);
9450 this.menu
.selectItem( match
);
9451 if ( this.menu
.getHighlightedItem() ) {
9452 this.menu
.highlightItem( match
);
9455 if ( !this.isDisabled() ) {
9456 this.menu
.toggle( true );
9461 * Handle mouse click events.
9464 * @param {jQuery.Event} e Mouse click event
9466 OO
.ui
.ComboBoxInputWidget
.prototype.onIndicatorClick = function ( e
) {
9467 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
9469 this.$input
[ 0 ].focus();
9475 * Handle key press events.
9478 * @param {jQuery.Event} e Key press event
9480 OO
.ui
.ComboBoxInputWidget
.prototype.onIndicatorKeyPress = function ( e
) {
9481 if ( !this.isDisabled() && ( e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
) ) {
9483 this.$input
[ 0 ].focus();
9489 * Handle input enter events.
9493 OO
.ui
.ComboBoxInputWidget
.prototype.onInputEnter = function () {
9494 if ( !this.isDisabled() ) {
9495 this.menu
.toggle( false );
9500 * Handle menu choose events.
9503 * @param {OO.ui.OptionWidget} item Chosen item
9505 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuChoose = function ( item
) {
9506 this.setValue( item
.getData() );
9510 * Handle menu item change events.
9514 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuItemsChange = function () {
9515 var match
= this.menu
.getItemFromData( this.getValue() );
9516 this.menu
.selectItem( match
);
9517 if ( this.menu
.getHighlightedItem() ) {
9518 this.menu
.highlightItem( match
);
9520 this.$element
.toggleClass( 'oo-ui-comboBoxInputWidget-empty', this.menu
.isEmpty() );
9526 OO
.ui
.ComboBoxInputWidget
.prototype.setDisabled = function ( disabled
) {
9528 OO
.ui
.ComboBoxInputWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
9531 this.menu
.setDisabled( this.isDisabled() );
9538 * Set the options available for this input.
9540 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
9543 OO
.ui
.ComboBoxInputWidget
.prototype.setOptions = function ( options
) {
9546 .addItems( options
.map( function ( opt
) {
9547 return new OO
.ui
.MenuOptionWidget( {
9549 label
: opt
.label
!== undefined ? opt
.label
: opt
.data
9558 * @deprecated since 0.13.2; use OO.ui.ComboBoxInputWidget instead
9560 OO
.ui
.ComboBoxWidget
= OO
.ui
.ComboBoxInputWidget
;
9563 * FieldLayouts are used with OO.ui.FieldsetLayout. Each FieldLayout requires a field-widget,
9564 * which is a widget that is specified by reference before any optional configuration settings.
9566 * Field layouts can be configured with help text and/or labels. Labels are aligned in one of four ways:
9568 * - **left**: The label is placed before the field-widget and aligned with the left margin.
9569 * A left-alignment is used for forms with many fields.
9570 * - **right**: The label is placed before the field-widget and aligned to the right margin.
9571 * A right-alignment is used for long but familiar forms which users tab through,
9572 * verifying the current field with a quick glance at the label.
9573 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
9574 * that users fill out from top to bottom.
9575 * - **inline**: The label is placed after the field-widget and aligned to the left.
9576 * An inline-alignment is best used with checkboxes or radio buttons.
9578 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout.
9579 * Please see the [OOjs UI documentation on MediaWiki] [1] for examples and more information.
9581 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
9584 * @extends OO.ui.Layout
9585 * @mixins OO.ui.mixin.LabelElement
9586 * @mixins OO.ui.mixin.TitledElement
9589 * @param {OO.ui.Widget} fieldWidget Field widget
9590 * @param {Object} [config] Configuration options
9591 * @cfg {string} [align='left'] Alignment of the label: 'left', 'right', 'top' or 'inline'
9592 * @cfg {Array} [errors] Error messages about the widget, which will be displayed below the widget.
9593 * The array may contain strings or OO.ui.HtmlSnippet instances.
9594 * @cfg {Array} [notices] Notices about the widget, which will be displayed below the widget.
9595 * The array may contain strings or OO.ui.HtmlSnippet instances.
9596 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified, a "help" icon will appear
9597 * in the upper-right corner of the rendered field; clicking it will display the text in a popup.
9598 * For important messages, you are advised to use `notices`, as they are always shown.
9600 * @throws {Error} An error is thrown if no widget is specified
9602 OO
.ui
.FieldLayout
= function OoUiFieldLayout( fieldWidget
, config
) {
9603 var hasInputWidget
, div
;
9605 // Allow passing positional parameters inside the config object
9606 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
9607 config
= fieldWidget
;
9608 fieldWidget
= config
.fieldWidget
;
9611 // Make sure we have required constructor arguments
9612 if ( fieldWidget
=== undefined ) {
9613 throw new Error( 'Widget not found' );
9616 hasInputWidget
= fieldWidget
.constructor.static.supportsSimpleLabel
;
9618 // Configuration initialization
9619 config
= $.extend( { align
: 'left' }, config
);
9621 // Parent constructor
9622 OO
.ui
.FieldLayout
.parent
.call( this, config
);
9624 // Mixin constructors
9625 OO
.ui
.mixin
.LabelElement
.call( this, config
);
9626 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
9629 this.fieldWidget
= fieldWidget
;
9632 this.$field
= $( '<div>' );
9633 this.$messages
= $( '<ul>' );
9634 this.$body
= $( '<' + ( hasInputWidget
? 'label' : 'div' ) + '>' );
9636 if ( config
.help
) {
9637 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
9638 classes
: [ 'oo-ui-fieldLayout-help' ],
9644 if ( config
.help
instanceof OO
.ui
.HtmlSnippet
) {
9645 div
.html( config
.help
.toString() );
9647 div
.text( config
.help
);
9649 this.popupButtonWidget
.getPopup().$body
.append(
9650 div
.addClass( 'oo-ui-fieldLayout-help-content' )
9652 this.$help
= this.popupButtonWidget
.$element
;
9654 this.$help
= $( [] );
9658 if ( hasInputWidget
) {
9659 this.$label
.on( 'click', this.onLabelClick
.bind( this ) );
9661 this.fieldWidget
.connect( this, { disable
: 'onFieldDisable' } );
9665 .addClass( 'oo-ui-fieldLayout' )
9666 .append( this.$help
, this.$body
);
9667 this.$body
.addClass( 'oo-ui-fieldLayout-body' );
9668 this.$messages
.addClass( 'oo-ui-fieldLayout-messages' );
9670 .addClass( 'oo-ui-fieldLayout-field' )
9671 .toggleClass( 'oo-ui-fieldLayout-disable', this.fieldWidget
.isDisabled() )
9672 .append( this.fieldWidget
.$element
);
9674 this.setErrors( config
.errors
|| [] );
9675 this.setNotices( config
.notices
|| [] );
9676 this.setAlignment( config
.align
);
9681 OO
.inheritClass( OO
.ui
.FieldLayout
, OO
.ui
.Layout
);
9682 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.LabelElement
);
9683 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.TitledElement
);
9688 * Handle field disable events.
9691 * @param {boolean} value Field is disabled
9693 OO
.ui
.FieldLayout
.prototype.onFieldDisable = function ( value
) {
9694 this.$element
.toggleClass( 'oo-ui-fieldLayout-disabled', value
);
9698 * Handle label mouse click events.
9701 * @param {jQuery.Event} e Mouse click event
9703 OO
.ui
.FieldLayout
.prototype.onLabelClick = function () {
9704 this.fieldWidget
.simulateLabelClick();
9709 * Get the widget contained by the field.
9711 * @return {OO.ui.Widget} Field widget
9713 OO
.ui
.FieldLayout
.prototype.getField = function () {
9714 return this.fieldWidget
;
9719 * @param {string} kind 'error' or 'notice'
9720 * @param {string|OO.ui.HtmlSnippet} text
9723 OO
.ui
.FieldLayout
.prototype.makeMessage = function ( kind
, text
) {
9724 var $listItem
, $icon
, message
;
9725 $listItem
= $( '<li>' );
9726 if ( kind
=== 'error' ) {
9727 $icon
= new OO
.ui
.IconWidget( { icon
: 'alert', flags
: [ 'warning' ] } ).$element
;
9728 } else if ( kind
=== 'notice' ) {
9729 $icon
= new OO
.ui
.IconWidget( { icon
: 'info' } ).$element
;
9733 message
= new OO
.ui
.LabelWidget( { label
: text
} );
9735 .append( $icon
, message
.$element
)
9736 .addClass( 'oo-ui-fieldLayout-messages-' + kind
);
9741 * Set the field alignment mode.
9744 * @param {string} value Alignment mode, either 'left', 'right', 'top' or 'inline'
9747 OO
.ui
.FieldLayout
.prototype.setAlignment = function ( value
) {
9748 if ( value
!== this.align
) {
9749 // Default to 'left'
9750 if ( [ 'left', 'right', 'top', 'inline' ].indexOf( value
) === -1 ) {
9754 if ( value
=== 'inline' ) {
9755 this.$body
.append( this.$field
, this.$label
);
9757 this.$body
.append( this.$label
, this.$field
);
9759 // Set classes. The following classes can be used here:
9760 // * oo-ui-fieldLayout-align-left
9761 // * oo-ui-fieldLayout-align-right
9762 // * oo-ui-fieldLayout-align-top
9763 // * oo-ui-fieldLayout-align-inline
9765 this.$element
.removeClass( 'oo-ui-fieldLayout-align-' + this.align
);
9767 this.$element
.addClass( 'oo-ui-fieldLayout-align-' + value
);
9775 * Set the list of error messages.
9777 * @param {Array} errors Error messages about the widget, which will be displayed below the widget.
9778 * The array may contain strings or OO.ui.HtmlSnippet instances.
9781 OO
.ui
.FieldLayout
.prototype.setErrors = function ( errors
) {
9782 this.errors
= errors
.slice();
9783 this.updateMessages();
9788 * Set the list of notice messages.
9790 * @param {Array} notices Notices about the widget, which will be displayed below the widget.
9791 * The array may contain strings or OO.ui.HtmlSnippet instances.
9794 OO
.ui
.FieldLayout
.prototype.setNotices = function ( notices
) {
9795 this.notices
= notices
.slice();
9796 this.updateMessages();
9801 * Update the rendering of error and notice messages.
9805 OO
.ui
.FieldLayout
.prototype.updateMessages = function () {
9807 this.$messages
.empty();
9809 if ( this.errors
.length
|| this.notices
.length
) {
9810 this.$body
.after( this.$messages
);
9812 this.$messages
.remove();
9816 for ( i
= 0; i
< this.notices
.length
; i
++ ) {
9817 this.$messages
.append( this.makeMessage( 'notice', this.notices
[ i
] ) );
9819 for ( i
= 0; i
< this.errors
.length
; i
++ ) {
9820 this.$messages
.append( this.makeMessage( 'error', this.errors
[ i
] ) );
9825 * ActionFieldLayouts are used with OO.ui.FieldsetLayout. The layout consists of a field-widget, a button,
9826 * and an optional label and/or help text. The field-widget (e.g., a {@link OO.ui.TextInputWidget TextInputWidget}),
9827 * is required and is specified before any optional configuration settings.
9829 * Labels can be aligned in one of four ways:
9831 * - **left**: The label is placed before the field-widget and aligned with the left margin.
9832 * A left-alignment is used for forms with many fields.
9833 * - **right**: The label is placed before the field-widget and aligned to the right margin.
9834 * A right-alignment is used for long but familiar forms which users tab through,
9835 * verifying the current field with a quick glance at the label.
9836 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
9837 * that users fill out from top to bottom.
9838 * - **inline**: The label is placed after the field-widget and aligned to the left.
9839 * An inline-alignment is best used with checkboxes or radio buttons.
9841 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout when help
9842 * text is specified.
9845 * // Example of an ActionFieldLayout
9846 * var actionFieldLayout = new OO.ui.ActionFieldLayout(
9847 * new OO.ui.TextInputWidget( {
9848 * placeholder: 'Field widget'
9850 * new OO.ui.ButtonWidget( {
9854 * label: 'An ActionFieldLayout. This label is aligned top',
9856 * help: 'This is help text'
9860 * $( 'body' ).append( actionFieldLayout.$element );
9863 * @extends OO.ui.FieldLayout
9866 * @param {OO.ui.Widget} fieldWidget Field widget
9867 * @param {OO.ui.ButtonWidget} buttonWidget Button widget
9869 OO
.ui
.ActionFieldLayout
= function OoUiActionFieldLayout( fieldWidget
, buttonWidget
, config
) {
9870 // Allow passing positional parameters inside the config object
9871 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
9872 config
= fieldWidget
;
9873 fieldWidget
= config
.fieldWidget
;
9874 buttonWidget
= config
.buttonWidget
;
9877 // Parent constructor
9878 OO
.ui
.ActionFieldLayout
.parent
.call( this, fieldWidget
, config
);
9881 this.buttonWidget
= buttonWidget
;
9882 this.$button
= $( '<div>' );
9883 this.$input
= $( '<div>' );
9887 .addClass( 'oo-ui-actionFieldLayout' );
9889 .addClass( 'oo-ui-actionFieldLayout-button' )
9890 .append( this.buttonWidget
.$element
);
9892 .addClass( 'oo-ui-actionFieldLayout-input' )
9893 .append( this.fieldWidget
.$element
);
9895 .append( this.$input
, this.$button
);
9900 OO
.inheritClass( OO
.ui
.ActionFieldLayout
, OO
.ui
.FieldLayout
);
9903 * FieldsetLayouts are composed of one or more {@link OO.ui.FieldLayout FieldLayouts},
9904 * which each contain an individual widget and, optionally, a label. Each Fieldset can be
9905 * configured with a label as well. For more information and examples,
9906 * please see the [OOjs UI documentation on MediaWiki][1].
9909 * // Example of a fieldset layout
9910 * var input1 = new OO.ui.TextInputWidget( {
9911 * placeholder: 'A text input field'
9914 * var input2 = new OO.ui.TextInputWidget( {
9915 * placeholder: 'A text input field'
9918 * var fieldset = new OO.ui.FieldsetLayout( {
9919 * label: 'Example of a fieldset layout'
9922 * fieldset.addItems( [
9923 * new OO.ui.FieldLayout( input1, {
9924 * label: 'Field One'
9926 * new OO.ui.FieldLayout( input2, {
9927 * label: 'Field Two'
9930 * $( 'body' ).append( fieldset.$element );
9932 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
9935 * @extends OO.ui.Layout
9936 * @mixins OO.ui.mixin.IconElement
9937 * @mixins OO.ui.mixin.LabelElement
9938 * @mixins OO.ui.mixin.GroupElement
9941 * @param {Object} [config] Configuration options
9942 * @cfg {OO.ui.FieldLayout[]} [items] An array of fields to add to the fieldset. See OO.ui.FieldLayout for more information about fields.
9944 OO
.ui
.FieldsetLayout
= function OoUiFieldsetLayout( config
) {
9945 // Configuration initialization
9946 config
= config
|| {};
9948 // Parent constructor
9949 OO
.ui
.FieldsetLayout
.parent
.call( this, config
);
9951 // Mixin constructors
9952 OO
.ui
.mixin
.IconElement
.call( this, config
);
9953 OO
.ui
.mixin
.LabelElement
.call( this, config
);
9954 OO
.ui
.mixin
.GroupElement
.call( this, config
);
9956 if ( config
.help
) {
9957 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
9958 classes
: [ 'oo-ui-fieldsetLayout-help' ],
9963 this.popupButtonWidget
.getPopup().$body
.append(
9965 .text( config
.help
)
9966 .addClass( 'oo-ui-fieldsetLayout-help-content' )
9968 this.$help
= this.popupButtonWidget
.$element
;
9970 this.$help
= $( [] );
9975 .addClass( 'oo-ui-fieldsetLayout' )
9976 .prepend( this.$help
, this.$icon
, this.$label
, this.$group
);
9977 if ( Array
.isArray( config
.items
) ) {
9978 this.addItems( config
.items
);
9984 OO
.inheritClass( OO
.ui
.FieldsetLayout
, OO
.ui
.Layout
);
9985 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.IconElement
);
9986 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.LabelElement
);
9987 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.GroupElement
);
9990 * FormLayouts are used to wrap {@link OO.ui.FieldsetLayout FieldsetLayouts} when you intend to use browser-based
9991 * form submission for the fields instead of handling them in JavaScript. Form layouts can be configured with an
9992 * HTML form action, an encoding type, and a method using the #action, #enctype, and #method configs, respectively.
9993 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
9995 * Only widgets from the {@link OO.ui.InputWidget InputWidget} family support form submission. It
9996 * includes standard form elements like {@link OO.ui.CheckboxInputWidget checkboxes}, {@link
9997 * OO.ui.RadioInputWidget radio buttons} and {@link OO.ui.TextInputWidget text fields}, as well as
9998 * some fancier controls. Some controls have both regular and InputWidget variants, for example
9999 * OO.ui.DropdownWidget and OO.ui.DropdownInputWidget – only the latter support form submission and
10000 * often have simplified APIs to match the capabilities of HTML forms.
10001 * See the [OOjs UI Inputs documentation on MediaWiki] [2] for more information about InputWidgets.
10003 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Forms
10004 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
10007 * // Example of a form layout that wraps a fieldset layout
10008 * var input1 = new OO.ui.TextInputWidget( {
10009 * placeholder: 'Username'
10011 * var input2 = new OO.ui.TextInputWidget( {
10012 * placeholder: 'Password',
10015 * var submit = new OO.ui.ButtonInputWidget( {
10019 * var fieldset = new OO.ui.FieldsetLayout( {
10020 * label: 'A form layout'
10022 * fieldset.addItems( [
10023 * new OO.ui.FieldLayout( input1, {
10024 * label: 'Username',
10027 * new OO.ui.FieldLayout( input2, {
10028 * label: 'Password',
10031 * new OO.ui.FieldLayout( submit )
10033 * var form = new OO.ui.FormLayout( {
10034 * items: [ fieldset ],
10035 * action: '/api/formhandler',
10038 * $( 'body' ).append( form.$element );
10041 * @extends OO.ui.Layout
10042 * @mixins OO.ui.mixin.GroupElement
10045 * @param {Object} [config] Configuration options
10046 * @cfg {string} [method] HTML form `method` attribute
10047 * @cfg {string} [action] HTML form `action` attribute
10048 * @cfg {string} [enctype] HTML form `enctype` attribute
10049 * @cfg {OO.ui.FieldsetLayout[]} [items] Fieldset layouts to add to the form layout.
10051 OO
.ui
.FormLayout
= function OoUiFormLayout( config
) {
10054 // Configuration initialization
10055 config
= config
|| {};
10057 // Parent constructor
10058 OO
.ui
.FormLayout
.parent
.call( this, config
);
10060 // Mixin constructors
10061 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
10064 this.$element
.on( 'submit', this.onFormSubmit
.bind( this ) );
10066 // Make sure the action is safe
10067 action
= config
.action
;
10068 if ( action
!== undefined && !OO
.ui
.isSafeUrl( action
) ) {
10069 action
= './' + action
;
10074 .addClass( 'oo-ui-formLayout' )
10076 method
: config
.method
,
10078 enctype
: config
.enctype
10080 if ( Array
.isArray( config
.items
) ) {
10081 this.addItems( config
.items
);
10087 OO
.inheritClass( OO
.ui
.FormLayout
, OO
.ui
.Layout
);
10088 OO
.mixinClass( OO
.ui
.FormLayout
, OO
.ui
.mixin
.GroupElement
);
10093 * A 'submit' event is emitted when the form is submitted.
10098 /* Static Properties */
10100 OO
.ui
.FormLayout
.static.tagName
= 'form';
10105 * Handle form submit events.
10108 * @param {jQuery.Event} e Submit event
10111 OO
.ui
.FormLayout
.prototype.onFormSubmit = function () {
10112 if ( this.emit( 'submit' ) ) {
10118 * PanelLayouts expand to cover the entire area of their parent. They can be configured with scrolling, padding,
10119 * and a frame, and are often used together with {@link OO.ui.StackLayout StackLayouts}.
10122 * // Example of a panel layout
10123 * var panel = new OO.ui.PanelLayout( {
10127 * $content: $( '<p>A panel layout with padding and a frame.</p>' )
10129 * $( 'body' ).append( panel.$element );
10132 * @extends OO.ui.Layout
10135 * @param {Object} [config] Configuration options
10136 * @cfg {boolean} [scrollable=false] Allow vertical scrolling
10137 * @cfg {boolean} [padded=false] Add padding between the content and the edges of the panel.
10138 * @cfg {boolean} [expanded=true] Expand the panel to fill the entire parent element.
10139 * @cfg {boolean} [framed=false] Render the panel with a frame to visually separate it from outside content.
10141 OO
.ui
.PanelLayout
= function OoUiPanelLayout( config
) {
10142 // Configuration initialization
10143 config
= $.extend( {
10150 // Parent constructor
10151 OO
.ui
.PanelLayout
.parent
.call( this, config
);
10154 this.$element
.addClass( 'oo-ui-panelLayout' );
10155 if ( config
.scrollable
) {
10156 this.$element
.addClass( 'oo-ui-panelLayout-scrollable' );
10158 if ( config
.padded
) {
10159 this.$element
.addClass( 'oo-ui-panelLayout-padded' );
10161 if ( config
.expanded
) {
10162 this.$element
.addClass( 'oo-ui-panelLayout-expanded' );
10164 if ( config
.framed
) {
10165 this.$element
.addClass( 'oo-ui-panelLayout-framed' );
10171 OO
.inheritClass( OO
.ui
.PanelLayout
, OO
.ui
.Layout
);
10176 * Focus the panel layout
10178 * The default implementation just focuses the first focusable element in the panel
10180 OO
.ui
.PanelLayout
.prototype.focus = function () {
10181 OO
.ui
.findFocusable( this.$element
).focus();
10185 * HorizontalLayout arranges its contents in a single line (using `display: inline-block` for its
10186 * items), with small margins between them. Convenient when you need to put a number of block-level
10187 * widgets on a single line next to each other.
10189 * Note that inline elements, such as OO.ui.ButtonWidgets, do not need this wrapper.
10192 * // HorizontalLayout with a text input and a label
10193 * var layout = new OO.ui.HorizontalLayout( {
10195 * new OO.ui.LabelWidget( { label: 'Label' } ),
10196 * new OO.ui.TextInputWidget( { value: 'Text' } )
10199 * $( 'body' ).append( layout.$element );
10202 * @extends OO.ui.Layout
10203 * @mixins OO.ui.mixin.GroupElement
10206 * @param {Object} [config] Configuration options
10207 * @cfg {OO.ui.Widget[]|OO.ui.Layout[]} [items] Widgets or other layouts to add to the layout.
10209 OO
.ui
.HorizontalLayout
= function OoUiHorizontalLayout( config
) {
10210 // Configuration initialization
10211 config
= config
|| {};
10213 // Parent constructor
10214 OO
.ui
.HorizontalLayout
.parent
.call( this, config
);
10216 // Mixin constructors
10217 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
10220 this.$element
.addClass( 'oo-ui-horizontalLayout' );
10221 if ( Array
.isArray( config
.items
) ) {
10222 this.addItems( config
.items
);
10228 OO
.inheritClass( OO
.ui
.HorizontalLayout
, OO
.ui
.Layout
);
10229 OO
.mixinClass( OO
.ui
.HorizontalLayout
, OO
.ui
.mixin
.GroupElement
);