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-05-24T22:46:32Z
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
, event
, 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 ( event
in this.aggregateItemEvents
) {
2241 events
[ event
] = [ 'emit', this.aggregateItemEvents
[ event
], 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
, remove
, 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 ) {
2282 item
.connect
&& item
.disconnect
&&
2283 !$.isEmptyObject( this.aggregateItemEvents
)
2286 if ( Object
.prototype.hasOwnProperty
.call( this.aggregateItemEvents
, itemEvent
) ) {
2287 remove
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2289 item
.disconnect( this, remove
);
2291 item
.setElementGroup( null );
2292 this.items
.splice( index
, 1 );
2293 item
.$element
.detach();
2297 this.emit( 'change', this.getItems() );
2302 * Clear all items from the group.
2304 * Cleared items are detached from the DOM, not removed, so that they may be reused.
2305 * To remove only a subset of items from a group, use the #removeItems method.
2309 OO
.ui
.mixin
.GroupElement
.prototype.clearItems = function () {
2310 var i
, len
, item
, remove
, itemEvent
;
2313 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
2314 item
= this.items
[ i
];
2316 item
.connect
&& item
.disconnect
&&
2317 !$.isEmptyObject( this.aggregateItemEvents
)
2320 if ( Object
.prototype.hasOwnProperty
.call( this.aggregateItemEvents
, itemEvent
) ) {
2321 remove
[ itemEvent
] = [ 'emit', this.aggregateItemEvents
[ itemEvent
], item
];
2323 item
.disconnect( this, remove
);
2325 item
.setElementGroup( null );
2326 item
.$element
.detach();
2329 this.emit( 'change', this.getItems() );
2335 * IconElement is often mixed into other classes to generate an icon.
2336 * Icons are graphics, about the size of normal text. They are used to aid the user
2337 * in locating a control or to convey information in a space-efficient way. See the
2338 * [OOjs UI documentation on MediaWiki] [1] for a list of icons
2339 * included in the library.
2341 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2347 * @param {Object} [config] Configuration options
2348 * @cfg {jQuery} [$icon] The icon element created by the class. If this configuration is omitted,
2349 * the icon element will use a generated `<span>`. To use a different HTML tag, or to specify that
2350 * the icon element be set to an existing icon instead of the one generated by this class, set a
2351 * value using a jQuery selection. For example:
2353 * // Use a <div> tag instead of a <span>
2355 * // Use an existing icon element instead of the one generated by the class
2356 * $icon: this.$element
2357 * // Use an icon element from a child widget
2358 * $icon: this.childwidget.$element
2359 * @cfg {Object|string} [icon=''] The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of
2360 * symbolic names. A map is used for i18n purposes and contains a `default` icon
2361 * name and additional names keyed by language code. The `default` name is used when no icon is keyed
2362 * by the user's language.
2364 * Example of an i18n map:
2366 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2367 * See the [OOjs UI documentation on MediaWiki] [2] for a list of icons included in the library.
2368 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
2369 * @cfg {string|Function} [iconTitle] A text string used as the icon title, or a function that returns title
2370 * text. The icon title is displayed when users move the mouse over the icon.
2372 OO
.ui
.mixin
.IconElement
= function OoUiMixinIconElement( config
) {
2373 // Configuration initialization
2374 config
= config
|| {};
2379 this.iconTitle
= null;
2382 this.setIcon( config
.icon
|| this.constructor.static.icon
);
2383 this.setIconTitle( config
.iconTitle
|| this.constructor.static.iconTitle
);
2384 this.setIconElement( config
.$icon
|| $( '<span>' ) );
2389 OO
.initClass( OO
.ui
.mixin
.IconElement
);
2391 /* Static Properties */
2394 * The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of symbolic names. A map is used
2395 * for i18n purposes and contains a `default` icon name and additional names keyed by
2396 * language code. The `default` name is used when no icon is keyed by the user's language.
2398 * Example of an i18n map:
2400 * { default: 'bold-a', en: 'bold-b', de: 'bold-f' }
2402 * Note: the static property will be overridden if the #icon configuration is used.
2406 * @property {Object|string}
2408 OO
.ui
.mixin
.IconElement
.static.icon
= null;
2411 * The icon title, displayed when users move the mouse over the icon. The value can be text, a
2412 * function that returns title text, or `null` for no title.
2414 * The static property will be overridden if the #iconTitle configuration is used.
2418 * @property {string|Function|null}
2420 OO
.ui
.mixin
.IconElement
.static.iconTitle
= null;
2425 * Set the icon element. This method is used to retarget an icon mixin so that its functionality
2426 * applies to the specified icon element instead of the one created by the class. If an icon
2427 * element is already set, the mixin’s effect on that element is removed. Generated CSS classes
2428 * and mixin methods will no longer affect the element.
2430 * @param {jQuery} $icon Element to use as icon
2432 OO
.ui
.mixin
.IconElement
.prototype.setIconElement = function ( $icon
) {
2435 .removeClass( 'oo-ui-iconElement-icon oo-ui-icon-' + this.icon
)
2436 .removeAttr( 'title' );
2440 .addClass( 'oo-ui-iconElement-icon' )
2441 .toggleClass( 'oo-ui-icon-' + this.icon
, !!this.icon
);
2442 if ( this.iconTitle
!== null ) {
2443 this.$icon
.attr( 'title', this.iconTitle
);
2446 this.updateThemeClasses();
2450 * Set icon by symbolic name (e.g., ‘remove’ or ‘menu’). Use `null` to remove an icon.
2451 * The icon parameter can also be set to a map of icon names. See the #icon config setting
2454 * @param {Object|string|null} icon A symbolic icon name, a {@link #icon map of icon names} keyed
2455 * by language code, or `null` to remove the icon.
2458 OO
.ui
.mixin
.IconElement
.prototype.setIcon = function ( icon
) {
2459 icon
= OO
.isPlainObject( icon
) ? OO
.ui
.getLocalValue( icon
, null, 'default' ) : icon
;
2460 icon
= typeof icon
=== 'string' && icon
.trim().length
? icon
.trim() : null;
2462 if ( this.icon
!== icon
) {
2464 if ( this.icon
!== null ) {
2465 this.$icon
.removeClass( 'oo-ui-icon-' + this.icon
);
2467 if ( icon
!== null ) {
2468 this.$icon
.addClass( 'oo-ui-icon-' + icon
);
2474 this.$element
.toggleClass( 'oo-ui-iconElement', !!this.icon
);
2475 this.updateThemeClasses();
2481 * Set the icon title. Use `null` to remove the title.
2483 * @param {string|Function|null} iconTitle A text string used as the icon title,
2484 * a function that returns title text, or `null` for no title.
2487 OO
.ui
.mixin
.IconElement
.prototype.setIconTitle = function ( iconTitle
) {
2488 iconTitle
= typeof iconTitle
=== 'function' ||
2489 ( typeof iconTitle
=== 'string' && iconTitle
.length
) ?
2490 OO
.ui
.resolveMsg( iconTitle
) : null;
2492 if ( this.iconTitle
!== iconTitle
) {
2493 this.iconTitle
= iconTitle
;
2495 if ( this.iconTitle
!== null ) {
2496 this.$icon
.attr( 'title', iconTitle
);
2498 this.$icon
.removeAttr( 'title' );
2507 * Get the symbolic name of the icon.
2509 * @return {string} Icon name
2511 OO
.ui
.mixin
.IconElement
.prototype.getIcon = function () {
2516 * Get the icon title. The title text is displayed when a user moves the mouse over the icon.
2518 * @return {string} Icon title text
2520 OO
.ui
.mixin
.IconElement
.prototype.getIconTitle = function () {
2521 return this.iconTitle
;
2525 * IndicatorElement is often mixed into other classes to generate an indicator.
2526 * Indicators are small graphics that are generally used in two ways:
2528 * - To draw attention to the status of an item. For example, an indicator might be
2529 * used to show that an item in a list has errors that need to be resolved.
2530 * - To clarify the function of a control that acts in an exceptional way (a button
2531 * that opens a menu instead of performing an action directly, for example).
2533 * For a list of indicators included in the library, please see the
2534 * [OOjs UI documentation on MediaWiki] [1].
2536 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2542 * @param {Object} [config] Configuration options
2543 * @cfg {jQuery} [$indicator] The indicator element created by the class. If this
2544 * configuration is omitted, the indicator element will use a generated `<span>`.
2545 * @cfg {string} [indicator] Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2546 * See the [OOjs UI documentation on MediaWiki][2] for a list of indicators included
2548 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
2549 * @cfg {string|Function} [indicatorTitle] A text string used as the indicator title,
2550 * or a function that returns title text. The indicator title is displayed when users move
2551 * the mouse over the indicator.
2553 OO
.ui
.mixin
.IndicatorElement
= function OoUiMixinIndicatorElement( config
) {
2554 // Configuration initialization
2555 config
= config
|| {};
2558 this.$indicator
= null;
2559 this.indicator
= null;
2560 this.indicatorTitle
= null;
2563 this.setIndicator( config
.indicator
|| this.constructor.static.indicator
);
2564 this.setIndicatorTitle( config
.indicatorTitle
|| this.constructor.static.indicatorTitle
);
2565 this.setIndicatorElement( config
.$indicator
|| $( '<span>' ) );
2570 OO
.initClass( OO
.ui
.mixin
.IndicatorElement
);
2572 /* Static Properties */
2575 * Symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2576 * The static property will be overridden if the #indicator configuration is used.
2580 * @property {string|null}
2582 OO
.ui
.mixin
.IndicatorElement
.static.indicator
= null;
2585 * A text string used as the indicator title, a function that returns title text, or `null`
2586 * for no title. The static property will be overridden if the #indicatorTitle configuration is used.
2590 * @property {string|Function|null}
2592 OO
.ui
.mixin
.IndicatorElement
.static.indicatorTitle
= null;
2597 * Set the indicator element.
2599 * If an element is already set, it will be cleaned up before setting up the new element.
2601 * @param {jQuery} $indicator Element to use as indicator
2603 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorElement = function ( $indicator
) {
2604 if ( this.$indicator
) {
2606 .removeClass( 'oo-ui-indicatorElement-indicator oo-ui-indicator-' + this.indicator
)
2607 .removeAttr( 'title' );
2610 this.$indicator
= $indicator
2611 .addClass( 'oo-ui-indicatorElement-indicator' )
2612 .toggleClass( 'oo-ui-indicator-' + this.indicator
, !!this.indicator
);
2613 if ( this.indicatorTitle
!== null ) {
2614 this.$indicator
.attr( 'title', this.indicatorTitle
);
2617 this.updateThemeClasses();
2621 * Set the indicator by its symbolic name: ‘alert’, ‘down’, ‘next’, ‘previous’, ‘required’, ‘up’. Use `null` to remove the indicator.
2623 * @param {string|null} indicator Symbolic name of indicator, or `null` for no indicator
2626 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicator = function ( indicator
) {
2627 indicator
= typeof indicator
=== 'string' && indicator
.length
? indicator
.trim() : null;
2629 if ( this.indicator
!== indicator
) {
2630 if ( this.$indicator
) {
2631 if ( this.indicator
!== null ) {
2632 this.$indicator
.removeClass( 'oo-ui-indicator-' + this.indicator
);
2634 if ( indicator
!== null ) {
2635 this.$indicator
.addClass( 'oo-ui-indicator-' + indicator
);
2638 this.indicator
= indicator
;
2641 this.$element
.toggleClass( 'oo-ui-indicatorElement', !!this.indicator
);
2642 this.updateThemeClasses();
2648 * Set the indicator title.
2650 * The title is displayed when a user moves the mouse over the indicator.
2652 * @param {string|Function|null} indicatorTitle Indicator title text, a function that returns text, or
2653 * `null` for no indicator title
2656 OO
.ui
.mixin
.IndicatorElement
.prototype.setIndicatorTitle = function ( indicatorTitle
) {
2657 indicatorTitle
= typeof indicatorTitle
=== 'function' ||
2658 ( typeof indicatorTitle
=== 'string' && indicatorTitle
.length
) ?
2659 OO
.ui
.resolveMsg( indicatorTitle
) : null;
2661 if ( this.indicatorTitle
!== indicatorTitle
) {
2662 this.indicatorTitle
= indicatorTitle
;
2663 if ( this.$indicator
) {
2664 if ( this.indicatorTitle
!== null ) {
2665 this.$indicator
.attr( 'title', indicatorTitle
);
2667 this.$indicator
.removeAttr( 'title' );
2676 * Get the symbolic name of the indicator (e.g., ‘alert’ or ‘down’).
2678 * @return {string} Symbolic name of indicator
2680 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicator = function () {
2681 return this.indicator
;
2685 * Get the indicator title.
2687 * The title is displayed when a user moves the mouse over the indicator.
2689 * @return {string} Indicator title text
2691 OO
.ui
.mixin
.IndicatorElement
.prototype.getIndicatorTitle = function () {
2692 return this.indicatorTitle
;
2696 * LabelElement is often mixed into other classes to generate a label, which
2697 * helps identify the function of an interface element.
2698 * See the [OOjs UI documentation on MediaWiki] [1] for more information.
2700 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2706 * @param {Object} [config] Configuration options
2707 * @cfg {jQuery} [$label] The label element created by the class. If this
2708 * configuration is omitted, the label element will use a generated `<span>`.
2709 * @cfg {jQuery|string|Function|OO.ui.HtmlSnippet} [label] The label text. The label can be specified
2710 * as a plaintext string, a jQuery selection of elements, or a function that will produce a string
2711 * in the future. See the [OOjs UI documentation on MediaWiki] [2] for examples.
2712 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Labels
2714 OO
.ui
.mixin
.LabelElement
= function OoUiMixinLabelElement( config
) {
2715 // Configuration initialization
2716 config
= config
|| {};
2723 this.setLabel( config
.label
|| this.constructor.static.label
);
2724 this.setLabelElement( config
.$label
|| $( '<span>' ) );
2729 OO
.initClass( OO
.ui
.mixin
.LabelElement
);
2734 * @event labelChange
2735 * @param {string} value
2738 /* Static Properties */
2741 * The label text. The label can be specified as a plaintext string, a function that will
2742 * produce a string in the future, or `null` for no label. The static value will
2743 * be overridden if a label is specified with the #label config option.
2747 * @property {string|Function|null}
2749 OO
.ui
.mixin
.LabelElement
.static.label
= null;
2751 /* Static methods */
2754 * Highlight the first occurrence of the query in the given text
2756 * @param {string} text Text
2757 * @param {string} query Query to find
2758 * @return {jQuery} Text with the first match of the query
2759 * sub-string wrapped in highlighted span
2761 OO
.ui
.mixin
.LabelElement
.static.highlightQuery = function ( text
, query
) {
2762 var $result
= $( '<span>' ),
2763 offset
= text
.toLowerCase().indexOf( query
.toLowerCase() );
2765 if ( !query
.length
|| offset
=== -1 ) {
2766 return $result
.text( text
);
2769 document
.createTextNode( text
.slice( 0, offset
) ),
2771 .addClass( 'oo-ui-labelElement-label-highlight' )
2772 .text( text
.slice( offset
, offset
+ query
.length
) ),
2773 document
.createTextNode( text
.slice( offset
+ query
.length
) )
2775 return $result
.contents();
2781 * Set the label element.
2783 * If an element is already set, it will be cleaned up before setting up the new element.
2785 * @param {jQuery} $label Element to use as label
2787 OO
.ui
.mixin
.LabelElement
.prototype.setLabelElement = function ( $label
) {
2788 if ( this.$label
) {
2789 this.$label
.removeClass( 'oo-ui-labelElement-label' ).empty();
2792 this.$label
= $label
.addClass( 'oo-ui-labelElement-label' );
2793 this.setLabelContent( this.label
);
2799 * An empty string will result in the label being hidden. A string containing only whitespace will
2800 * be converted to a single ` `.
2802 * @param {jQuery|string|OO.ui.HtmlSnippet|Function|null} label Label nodes; text; a function that returns nodes or
2803 * text; or null for no label
2806 OO
.ui
.mixin
.LabelElement
.prototype.setLabel = function ( label
) {
2807 label
= typeof label
=== 'function' ? OO
.ui
.resolveMsg( label
) : label
;
2808 label
= ( ( typeof label
=== 'string' || label
instanceof jQuery
) && label
.length
) || ( label
instanceof OO
.ui
.HtmlSnippet
&& label
.toString().length
) ? label
: null;
2810 if ( this.label
!== label
) {
2811 if ( this.$label
) {
2812 this.setLabelContent( label
);
2815 this.emit( 'labelChange' );
2818 this.$element
.toggleClass( 'oo-ui-labelElement', !!this.label
);
2824 * Set the label as plain text with a highlighted query
2826 * @param {string} text Text label to set
2827 * @param {string} query Substring of text to highlight
2830 OO
.ui
.mixin
.LabelElement
.prototype.setHighlightedQuery = function ( text
, query
) {
2831 return this.setLabel( this.constructor.static.highlightQuery( text
, query
) );
2837 * @return {jQuery|string|Function|null} Label nodes; text; a function that returns nodes or
2838 * text; or null for no label
2840 OO
.ui
.mixin
.LabelElement
.prototype.getLabel = function () {
2848 * @deprecated since 0.16.0
2850 OO
.ui
.mixin
.LabelElement
.prototype.fitLabel = function () {
2855 * Set the content of the label.
2857 * Do not call this method until after the label element has been set by #setLabelElement.
2860 * @param {jQuery|string|Function|null} label Label nodes; text; a function that returns nodes or
2861 * text; or null for no label
2863 OO
.ui
.mixin
.LabelElement
.prototype.setLabelContent = function ( label
) {
2864 if ( typeof label
=== 'string' ) {
2865 if ( label
.match( /^\s*$/ ) ) {
2866 // Convert whitespace only string to a single non-breaking space
2867 this.$label
.html( ' ' );
2869 this.$label
.text( label
);
2871 } else if ( label
instanceof OO
.ui
.HtmlSnippet
) {
2872 this.$label
.html( label
.toString() );
2873 } else if ( label
instanceof jQuery
) {
2874 this.$label
.empty().append( label
);
2876 this.$label
.empty();
2881 * The FlaggedElement class is an attribute mixin, meaning that it is used to add
2882 * additional functionality to an element created by another class. The class provides
2883 * a ‘flags’ property assigned the name (or an array of names) of styling flags,
2884 * which are used to customize the look and feel of a widget to better describe its
2885 * importance and functionality.
2887 * The library currently contains the following styling flags for general use:
2889 * - **progressive**: Progressive styling is applied to convey that the widget will move the user forward in a process.
2890 * - **destructive**: Destructive styling is applied to convey that the widget will remove something.
2891 * - **constructive**: Constructive styling is applied to convey that the widget will create something.
2893 * The flags affect the appearance of the buttons:
2896 * // FlaggedElement is mixed into ButtonWidget to provide styling flags
2897 * var button1 = new OO.ui.ButtonWidget( {
2898 * label: 'Constructive',
2899 * flags: 'constructive'
2901 * var button2 = new OO.ui.ButtonWidget( {
2902 * label: 'Destructive',
2903 * flags: 'destructive'
2905 * var button3 = new OO.ui.ButtonWidget( {
2906 * label: 'Progressive',
2907 * flags: 'progressive'
2909 * $( 'body' ).append( button1.$element, button2.$element, button3.$element );
2911 * {@link OO.ui.ActionWidget ActionWidgets}, which are a special kind of button that execute an action, use these flags: **primary** and **safe**.
2912 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
2914 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
2920 * @param {Object} [config] Configuration options
2921 * @cfg {string|string[]} [flags] The name or names of the flags (e.g., 'constructive' or 'primary') to apply.
2922 * Please see the [OOjs UI documentation on MediaWiki] [2] for more information about available flags.
2923 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Elements/Flagged
2924 * @cfg {jQuery} [$flagged] The flagged element. By default,
2925 * the flagged functionality is applied to the element created by the class ($element).
2926 * If a different element is specified, the flagged functionality will be applied to it instead.
2928 OO
.ui
.mixin
.FlaggedElement
= function OoUiMixinFlaggedElement( config
) {
2929 // Configuration initialization
2930 config
= config
|| {};
2934 this.$flagged
= null;
2937 this.setFlags( config
.flags
);
2938 this.setFlaggedElement( config
.$flagged
|| this.$element
);
2945 * A flag event is emitted when the #clearFlags or #setFlags methods are used. The `changes`
2946 * parameter contains the name of each modified flag and indicates whether it was
2949 * @param {Object.<string,boolean>} changes Object keyed by flag name. A Boolean `true` indicates
2950 * that the flag was added, `false` that the flag was removed.
2956 * Set the flagged element.
2958 * This method is used to retarget a flagged mixin so that its functionality applies to the specified element.
2959 * If an element is already set, the method will remove the mixin’s effect on that element.
2961 * @param {jQuery} $flagged Element that should be flagged
2963 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlaggedElement = function ( $flagged
) {
2964 var classNames
= Object
.keys( this.flags
).map( function ( flag
) {
2965 return 'oo-ui-flaggedElement-' + flag
;
2968 if ( this.$flagged
) {
2969 this.$flagged
.removeClass( classNames
);
2972 this.$flagged
= $flagged
.addClass( classNames
);
2976 * Check if the specified flag is set.
2978 * @param {string} flag Name of flag
2979 * @return {boolean} The flag is set
2981 OO
.ui
.mixin
.FlaggedElement
.prototype.hasFlag = function ( flag
) {
2982 // This may be called before the constructor, thus before this.flags is set
2983 return this.flags
&& ( flag
in this.flags
);
2987 * Get the names of all flags set.
2989 * @return {string[]} Flag names
2991 OO
.ui
.mixin
.FlaggedElement
.prototype.getFlags = function () {
2992 // This may be called before the constructor, thus before this.flags is set
2993 return Object
.keys( this.flags
|| {} );
3002 OO
.ui
.mixin
.FlaggedElement
.prototype.clearFlags = function () {
3003 var flag
, className
,
3006 classPrefix
= 'oo-ui-flaggedElement-';
3008 for ( flag
in this.flags
) {
3009 className
= classPrefix
+ flag
;
3010 changes
[ flag
] = false;
3011 delete this.flags
[ flag
];
3012 remove
.push( className
);
3015 if ( this.$flagged
) {
3016 this.$flagged
.removeClass( remove
.join( ' ' ) );
3019 this.updateThemeClasses();
3020 this.emit( 'flag', changes
);
3026 * Add one or more flags.
3028 * @param {string|string[]|Object.<string, boolean>} flags A flag name, an array of flag names,
3029 * or an object keyed by flag name with a boolean value that indicates whether the flag should
3030 * be added (`true`) or removed (`false`).
3034 OO
.ui
.mixin
.FlaggedElement
.prototype.setFlags = function ( flags
) {
3035 var i
, len
, flag
, className
,
3039 classPrefix
= 'oo-ui-flaggedElement-';
3041 if ( typeof flags
=== 'string' ) {
3042 className
= classPrefix
+ flags
;
3044 if ( !this.flags
[ flags
] ) {
3045 this.flags
[ flags
] = true;
3046 add
.push( className
);
3048 } else if ( Array
.isArray( flags
) ) {
3049 for ( i
= 0, len
= flags
.length
; i
< len
; i
++ ) {
3051 className
= classPrefix
+ flag
;
3053 if ( !this.flags
[ flag
] ) {
3054 changes
[ flag
] = true;
3055 this.flags
[ flag
] = true;
3056 add
.push( className
);
3059 } else if ( OO
.isPlainObject( flags
) ) {
3060 for ( flag
in flags
) {
3061 className
= classPrefix
+ flag
;
3062 if ( flags
[ flag
] ) {
3064 if ( !this.flags
[ flag
] ) {
3065 changes
[ flag
] = true;
3066 this.flags
[ flag
] = true;
3067 add
.push( className
);
3071 if ( this.flags
[ flag
] ) {
3072 changes
[ flag
] = false;
3073 delete this.flags
[ flag
];
3074 remove
.push( className
);
3080 if ( this.$flagged
) {
3082 .addClass( add
.join( ' ' ) )
3083 .removeClass( remove
.join( ' ' ) );
3086 this.updateThemeClasses();
3087 this.emit( 'flag', changes
);
3093 * TitledElement is mixed into other classes to provide a `title` attribute.
3094 * Titles are rendered by the browser and are made visible when the user moves
3095 * the mouse over the element. Titles are not visible on touch devices.
3098 * // TitledElement provides a 'title' attribute to the
3099 * // ButtonWidget class
3100 * var button = new OO.ui.ButtonWidget( {
3101 * label: 'Button with Title',
3102 * title: 'I am a button'
3104 * $( 'body' ).append( button.$element );
3110 * @param {Object} [config] Configuration options
3111 * @cfg {jQuery} [$titled] The element to which the `title` attribute is applied.
3112 * If this config is omitted, the title functionality is applied to $element, the
3113 * element created by the class.
3114 * @cfg {string|Function} [title] The title text or a function that returns text. If
3115 * this config is omitted, the value of the {@link #static-title static title} property is used.
3117 OO
.ui
.mixin
.TitledElement
= function OoUiMixinTitledElement( config
) {
3118 // Configuration initialization
3119 config
= config
|| {};
3122 this.$titled
= null;
3126 this.setTitle( config
.title
!== undefined ? config
.title
: this.constructor.static.title
);
3127 this.setTitledElement( config
.$titled
|| this.$element
);
3132 OO
.initClass( OO
.ui
.mixin
.TitledElement
);
3134 /* Static Properties */
3137 * The title text, a function that returns text, or `null` for no title. The value of the static property
3138 * is overridden if the #title config option is used.
3142 * @property {string|Function|null}
3144 OO
.ui
.mixin
.TitledElement
.static.title
= null;
3149 * Set the titled element.
3151 * This method is used to retarget a titledElement mixin so that its functionality applies to the specified element.
3152 * If an element is already set, the mixin’s effect on that element is removed before the new element is set up.
3154 * @param {jQuery} $titled Element that should use the 'titled' functionality
3156 OO
.ui
.mixin
.TitledElement
.prototype.setTitledElement = function ( $titled
) {
3157 if ( this.$titled
) {
3158 this.$titled
.removeAttr( 'title' );
3161 this.$titled
= $titled
;
3163 this.$titled
.attr( 'title', this.title
);
3170 * @param {string|Function|null} title Title text, a function that returns text, or `null` for no title
3173 OO
.ui
.mixin
.TitledElement
.prototype.setTitle = function ( title
) {
3174 title
= typeof title
=== 'function' ? OO
.ui
.resolveMsg( title
) : title
;
3175 title
= ( typeof title
=== 'string' && title
.length
) ? title
: null;
3177 if ( this.title
!== title
) {
3178 if ( this.$titled
) {
3179 if ( title
!== null ) {
3180 this.$titled
.attr( 'title', title
);
3182 this.$titled
.removeAttr( 'title' );
3194 * @return {string} Title string
3196 OO
.ui
.mixin
.TitledElement
.prototype.getTitle = function () {
3201 * AccessKeyedElement is mixed into other classes to provide an `accesskey` attribute.
3202 * Accesskeys allow an user to go to a specific element by using
3203 * a shortcut combination of a browser specific keys + the key
3207 * // AccessKeyedElement provides an 'accesskey' attribute to the
3208 * // ButtonWidget class
3209 * var button = new OO.ui.ButtonWidget( {
3210 * label: 'Button with Accesskey',
3213 * $( 'body' ).append( button.$element );
3219 * @param {Object} [config] Configuration options
3220 * @cfg {jQuery} [$accessKeyed] The element to which the `accesskey` attribute is applied.
3221 * If this config is omitted, the accesskey functionality is applied to $element, the
3222 * element created by the class.
3223 * @cfg {string|Function} [accessKey] The key or a function that returns the key. If
3224 * this config is omitted, no accesskey will be added.
3226 OO
.ui
.mixin
.AccessKeyedElement
= function OoUiMixinAccessKeyedElement( config
) {
3227 // Configuration initialization
3228 config
= config
|| {};
3231 this.$accessKeyed
= null;
3232 this.accessKey
= null;
3235 this.setAccessKey( config
.accessKey
|| null );
3236 this.setAccessKeyedElement( config
.$accessKeyed
|| this.$element
);
3241 OO
.initClass( OO
.ui
.mixin
.AccessKeyedElement
);
3243 /* Static Properties */
3246 * The access key, a function that returns a key, or `null` for no accesskey.
3250 * @property {string|Function|null}
3252 OO
.ui
.mixin
.AccessKeyedElement
.static.accessKey
= null;
3257 * Set the accesskeyed element.
3259 * This method is used to retarget a AccessKeyedElement mixin so that its functionality applies to the specified element.
3260 * If an element is already set, the mixin's effect on that element is removed before the new element is set up.
3262 * @param {jQuery} $accessKeyed Element that should use the 'accesskeyes' functionality
3264 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKeyedElement = function ( $accessKeyed
) {
3265 if ( this.$accessKeyed
) {
3266 this.$accessKeyed
.removeAttr( 'accesskey' );
3269 this.$accessKeyed
= $accessKeyed
;
3270 if ( this.accessKey
) {
3271 this.$accessKeyed
.attr( 'accesskey', this.accessKey
);
3278 * @param {string|Function|null} accessKey Key, a function that returns a key, or `null` for no accesskey
3281 OO
.ui
.mixin
.AccessKeyedElement
.prototype.setAccessKey = function ( accessKey
) {
3282 accessKey
= typeof accessKey
=== 'string' ? OO
.ui
.resolveMsg( accessKey
) : null;
3284 if ( this.accessKey
!== accessKey
) {
3285 if ( this.$accessKeyed
) {
3286 if ( accessKey
!== null ) {
3287 this.$accessKeyed
.attr( 'accesskey', accessKey
);
3289 this.$accessKeyed
.removeAttr( 'accesskey' );
3292 this.accessKey
= accessKey
;
3301 * @return {string} accessKey string
3303 OO
.ui
.mixin
.AccessKeyedElement
.prototype.getAccessKey = function () {
3304 return this.accessKey
;
3308 * ButtonWidget is a generic widget for buttons. A wide variety of looks,
3309 * feels, and functionality can be customized via the class’s configuration options
3310 * and methods. Please see the [OOjs UI documentation on MediaWiki] [1] for more information
3313 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Buttons_and_Switches
3316 * // A button widget
3317 * var button = new OO.ui.ButtonWidget( {
3318 * label: 'Button with Icon',
3320 * iconTitle: 'Remove'
3322 * $( 'body' ).append( button.$element );
3324 * NOTE: HTML form buttons should use the OO.ui.ButtonInputWidget class.
3327 * @extends OO.ui.Widget
3328 * @mixins OO.ui.mixin.ButtonElement
3329 * @mixins OO.ui.mixin.IconElement
3330 * @mixins OO.ui.mixin.IndicatorElement
3331 * @mixins OO.ui.mixin.LabelElement
3332 * @mixins OO.ui.mixin.TitledElement
3333 * @mixins OO.ui.mixin.FlaggedElement
3334 * @mixins OO.ui.mixin.TabIndexedElement
3335 * @mixins OO.ui.mixin.AccessKeyedElement
3338 * @param {Object} [config] Configuration options
3339 * @cfg {boolean} [active=false] Whether button should be shown as active
3340 * @cfg {string} [href] Hyperlink to visit when the button is clicked.
3341 * @cfg {string} [target] The frame or window in which to open the hyperlink.
3342 * @cfg {boolean} [noFollow] Search engine traversal hint (default: true)
3344 OO
.ui
.ButtonWidget
= function OoUiButtonWidget( config
) {
3345 // Configuration initialization
3346 config
= config
|| {};
3348 // Parent constructor
3349 OO
.ui
.ButtonWidget
.parent
.call( this, config
);
3351 // Mixin constructors
3352 OO
.ui
.mixin
.ButtonElement
.call( this, config
);
3353 OO
.ui
.mixin
.IconElement
.call( this, config
);
3354 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
3355 OO
.ui
.mixin
.LabelElement
.call( this, config
);
3356 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$button
} ) );
3357 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
3358 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$button
} ) );
3359 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$button
} ) );
3364 this.noFollow
= false;
3367 this.connect( this, { disable
: 'onDisable' } );
3370 this.$button
.append( this.$icon
, this.$label
, this.$indicator
);
3372 .addClass( 'oo-ui-buttonWidget' )
3373 .append( this.$button
);
3374 this.setActive( config
.active
);
3375 this.setHref( config
.href
);
3376 this.setTarget( config
.target
);
3377 this.setNoFollow( config
.noFollow
);
3382 OO
.inheritClass( OO
.ui
.ButtonWidget
, OO
.ui
.Widget
);
3383 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.ButtonElement
);
3384 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IconElement
);
3385 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.IndicatorElement
);
3386 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.LabelElement
);
3387 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TitledElement
);
3388 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.FlaggedElement
);
3389 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.TabIndexedElement
);
3390 OO
.mixinClass( OO
.ui
.ButtonWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
3397 OO
.ui
.ButtonWidget
.prototype.onMouseDown = function ( e
) {
3398 if ( !this.isDisabled() ) {
3399 // Remove the tab-index while the button is down to prevent the button from stealing focus
3400 this.$button
.removeAttr( 'tabindex' );
3403 return OO
.ui
.mixin
.ButtonElement
.prototype.onMouseDown
.call( this, e
);
3409 OO
.ui
.ButtonWidget
.prototype.onMouseUp = function ( e
) {
3410 if ( !this.isDisabled() ) {
3411 // Restore the tab-index after the button is up to restore the button's accessibility
3412 this.$button
.attr( 'tabindex', this.tabIndex
);
3415 return OO
.ui
.mixin
.ButtonElement
.prototype.onMouseUp
.call( this, e
);
3419 * Get hyperlink location.
3421 * @return {string} Hyperlink location
3423 OO
.ui
.ButtonWidget
.prototype.getHref = function () {
3428 * Get hyperlink target.
3430 * @return {string} Hyperlink target
3432 OO
.ui
.ButtonWidget
.prototype.getTarget = function () {
3437 * Get search engine traversal hint.
3439 * @return {boolean} Whether search engines should avoid traversing this hyperlink
3441 OO
.ui
.ButtonWidget
.prototype.getNoFollow = function () {
3442 return this.noFollow
;
3446 * Set hyperlink location.
3448 * @param {string|null} href Hyperlink location, null to remove
3450 OO
.ui
.ButtonWidget
.prototype.setHref = function ( href
) {
3451 href
= typeof href
=== 'string' ? href
: null;
3452 if ( href
!== null && !OO
.ui
.isSafeUrl( href
) ) {
3456 if ( href
!== this.href
) {
3465 * Update the `href` attribute, in case of changes to href or
3471 OO
.ui
.ButtonWidget
.prototype.updateHref = function () {
3472 if ( this.href
!== null && !this.isDisabled() ) {
3473 this.$button
.attr( 'href', this.href
);
3475 this.$button
.removeAttr( 'href' );
3482 * Handle disable events.
3485 * @param {boolean} disabled Element is disabled
3487 OO
.ui
.ButtonWidget
.prototype.onDisable = function () {
3492 * Set hyperlink target.
3494 * @param {string|null} target Hyperlink target, null to remove
3496 OO
.ui
.ButtonWidget
.prototype.setTarget = function ( target
) {
3497 target
= typeof target
=== 'string' ? target
: null;
3499 if ( target
!== this.target
) {
3500 this.target
= target
;
3501 if ( target
!== null ) {
3502 this.$button
.attr( 'target', target
);
3504 this.$button
.removeAttr( 'target' );
3512 * Set search engine traversal hint.
3514 * @param {boolean} noFollow True if search engines should avoid traversing this hyperlink
3516 OO
.ui
.ButtonWidget
.prototype.setNoFollow = function ( noFollow
) {
3517 noFollow
= typeof noFollow
=== 'boolean' ? noFollow
: true;
3519 if ( noFollow
!== this.noFollow
) {
3520 this.noFollow
= noFollow
;
3522 this.$button
.attr( 'rel', 'nofollow' );
3524 this.$button
.removeAttr( 'rel' );
3531 // Override method visibility hints from ButtonElement
3540 * A ButtonGroupWidget groups related buttons and is used together with OO.ui.ButtonWidget and
3541 * its subclasses. Each button in a group is addressed by a unique reference. Buttons can be added,
3542 * removed, and cleared from the group.
3545 * // Example: A ButtonGroupWidget with two buttons
3546 * var button1 = new OO.ui.PopupButtonWidget( {
3547 * label: 'Select a category',
3550 * $content: $( '<p>List of categories...</p>' ),
3555 * var button2 = new OO.ui.ButtonWidget( {
3558 * var buttonGroup = new OO.ui.ButtonGroupWidget( {
3559 * items: [button1, button2]
3561 * $( 'body' ).append( buttonGroup.$element );
3564 * @extends OO.ui.Widget
3565 * @mixins OO.ui.mixin.GroupElement
3568 * @param {Object} [config] Configuration options
3569 * @cfg {OO.ui.ButtonWidget[]} [items] Buttons to add
3571 OO
.ui
.ButtonGroupWidget
= function OoUiButtonGroupWidget( config
) {
3572 // Configuration initialization
3573 config
= config
|| {};
3575 // Parent constructor
3576 OO
.ui
.ButtonGroupWidget
.parent
.call( this, config
);
3578 // Mixin constructors
3579 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
3582 this.$element
.addClass( 'oo-ui-buttonGroupWidget' );
3583 if ( Array
.isArray( config
.items
) ) {
3584 this.addItems( config
.items
);
3590 OO
.inheritClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.Widget
);
3591 OO
.mixinClass( OO
.ui
.ButtonGroupWidget
, OO
.ui
.mixin
.GroupElement
);
3594 * IconWidget is a generic widget for {@link OO.ui.mixin.IconElement icons}. In general, IconWidgets should be used with OO.ui.LabelWidget,
3595 * which creates a label that identifies the icon’s function. See the [OOjs UI documentation on MediaWiki] [1]
3596 * for a list of icons included in the library.
3599 * // An icon widget with a label
3600 * var myIcon = new OO.ui.IconWidget( {
3604 * // Create a label.
3605 * var iconLabel = new OO.ui.LabelWidget( {
3608 * $( 'body' ).append( myIcon.$element, iconLabel.$element );
3610 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Icons
3613 * @extends OO.ui.Widget
3614 * @mixins OO.ui.mixin.IconElement
3615 * @mixins OO.ui.mixin.TitledElement
3616 * @mixins OO.ui.mixin.FlaggedElement
3619 * @param {Object} [config] Configuration options
3621 OO
.ui
.IconWidget
= function OoUiIconWidget( config
) {
3622 // Configuration initialization
3623 config
= config
|| {};
3625 // Parent constructor
3626 OO
.ui
.IconWidget
.parent
.call( this, config
);
3628 // Mixin constructors
3629 OO
.ui
.mixin
.IconElement
.call( this, $.extend( {}, config
, { $icon
: this.$element
} ) );
3630 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3631 OO
.ui
.mixin
.FlaggedElement
.call( this, $.extend( {}, config
, { $flagged
: this.$element
} ) );
3634 this.$element
.addClass( 'oo-ui-iconWidget' );
3639 OO
.inheritClass( OO
.ui
.IconWidget
, OO
.ui
.Widget
);
3640 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.IconElement
);
3641 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.TitledElement
);
3642 OO
.mixinClass( OO
.ui
.IconWidget
, OO
.ui
.mixin
.FlaggedElement
);
3644 /* Static Properties */
3646 OO
.ui
.IconWidget
.static.tagName
= 'span';
3649 * IndicatorWidgets create indicators, which are small graphics that are generally used to draw
3650 * attention to the status of an item or to clarify the function of a control. For a list of
3651 * indicators included in the library, please see the [OOjs UI documentation on MediaWiki][1].
3654 * // Example of an indicator widget
3655 * var indicator1 = new OO.ui.IndicatorWidget( {
3656 * indicator: 'alert'
3659 * // Create a fieldset layout to add a label
3660 * var fieldset = new OO.ui.FieldsetLayout();
3661 * fieldset.addItems( [
3662 * new OO.ui.FieldLayout( indicator1, { label: 'An alert indicator:' } )
3664 * $( 'body' ).append( fieldset.$element );
3666 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Icons,_Indicators,_and_Labels#Indicators
3669 * @extends OO.ui.Widget
3670 * @mixins OO.ui.mixin.IndicatorElement
3671 * @mixins OO.ui.mixin.TitledElement
3674 * @param {Object} [config] Configuration options
3676 OO
.ui
.IndicatorWidget
= function OoUiIndicatorWidget( config
) {
3677 // Configuration initialization
3678 config
= config
|| {};
3680 // Parent constructor
3681 OO
.ui
.IndicatorWidget
.parent
.call( this, config
);
3683 // Mixin constructors
3684 OO
.ui
.mixin
.IndicatorElement
.call( this, $.extend( {}, config
, { $indicator
: this.$element
} ) );
3685 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$element
} ) );
3688 this.$element
.addClass( 'oo-ui-indicatorWidget' );
3693 OO
.inheritClass( OO
.ui
.IndicatorWidget
, OO
.ui
.Widget
);
3694 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.IndicatorElement
);
3695 OO
.mixinClass( OO
.ui
.IndicatorWidget
, OO
.ui
.mixin
.TitledElement
);
3697 /* Static Properties */
3699 OO
.ui
.IndicatorWidget
.static.tagName
= 'span';
3702 * LabelWidgets help identify the function of interface elements. Each LabelWidget can
3703 * be configured with a `label` option that is set to a string, a label node, or a function:
3705 * - String: a plaintext string
3706 * - jQuery selection: a jQuery selection, used for anything other than a plaintext label, e.g., a
3707 * label that includes a link or special styling, such as a gray color or additional graphical elements.
3708 * - Function: a function that will produce a string in the future. Functions are used
3709 * in cases where the value of the label is not currently defined.
3711 * In addition, the LabelWidget can be associated with an {@link OO.ui.InputWidget input widget}, which
3712 * will come into focus when the label is clicked.
3715 * // Examples of LabelWidgets
3716 * var label1 = new OO.ui.LabelWidget( {
3717 * label: 'plaintext label'
3719 * var label2 = new OO.ui.LabelWidget( {
3720 * label: $( '<a href="default.html">jQuery label</a>' )
3722 * // Create a fieldset layout with fields for each example
3723 * var fieldset = new OO.ui.FieldsetLayout();
3724 * fieldset.addItems( [
3725 * new OO.ui.FieldLayout( label1 ),
3726 * new OO.ui.FieldLayout( label2 )
3728 * $( 'body' ).append( fieldset.$element );
3731 * @extends OO.ui.Widget
3732 * @mixins OO.ui.mixin.LabelElement
3735 * @param {Object} [config] Configuration options
3736 * @cfg {OO.ui.InputWidget} [input] {@link OO.ui.InputWidget Input widget} that uses the label.
3737 * Clicking the label will focus the specified input field.
3739 OO
.ui
.LabelWidget
= function OoUiLabelWidget( config
) {
3740 // Configuration initialization
3741 config
= config
|| {};
3743 // Parent constructor
3744 OO
.ui
.LabelWidget
.parent
.call( this, config
);
3746 // Mixin constructors
3747 OO
.ui
.mixin
.LabelElement
.call( this, $.extend( {}, config
, { $label
: this.$element
} ) );
3748 OO
.ui
.mixin
.TitledElement
.call( this, config
);
3751 this.input
= config
.input
;
3754 if ( this.input
instanceof OO
.ui
.InputWidget
) {
3755 this.$element
.on( 'click', this.onClick
.bind( this ) );
3759 this.$element
.addClass( 'oo-ui-labelWidget' );
3764 OO
.inheritClass( OO
.ui
.LabelWidget
, OO
.ui
.Widget
);
3765 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.LabelElement
);
3766 OO
.mixinClass( OO
.ui
.LabelWidget
, OO
.ui
.mixin
.TitledElement
);
3768 /* Static Properties */
3770 OO
.ui
.LabelWidget
.static.tagName
= 'span';
3775 * Handles label mouse click events.
3778 * @param {jQuery.Event} e Mouse click event
3780 OO
.ui
.LabelWidget
.prototype.onClick = function () {
3781 this.input
.simulateLabelClick();
3786 * PendingElement is a mixin that is used to create elements that notify users that something is happening
3787 * and that they should wait before proceeding. The pending state is visually represented with a pending
3788 * texture that appears in the head of a pending {@link OO.ui.ProcessDialog process dialog} or in the input
3789 * field of a {@link OO.ui.TextInputWidget text input widget}.
3791 * Currently, {@link OO.ui.ActionWidget Action widgets}, which mix in this class, can also be marked as pending, but only when
3792 * used in {@link OO.ui.MessageDialog message dialogs}. The behavior is not currently supported for action widgets used
3793 * in process dialogs.
3796 * function MessageDialog( config ) {
3797 * MessageDialog.parent.call( this, config );
3799 * OO.inheritClass( MessageDialog, OO.ui.MessageDialog );
3801 * MessageDialog.static.actions = [
3802 * { action: 'save', label: 'Done', flags: 'primary' },
3803 * { label: 'Cancel', flags: 'safe' }
3806 * MessageDialog.prototype.initialize = function () {
3807 * MessageDialog.parent.prototype.initialize.apply( this, arguments );
3808 * this.content = new OO.ui.PanelLayout( { $: this.$, padded: true } );
3809 * 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>' );
3810 * this.$body.append( this.content.$element );
3812 * MessageDialog.prototype.getBodyHeight = function () {
3815 * MessageDialog.prototype.getActionProcess = function ( action ) {
3816 * var dialog = this;
3817 * if ( action === 'save' ) {
3818 * dialog.getActions().get({actions: 'save'})[0].pushPending();
3819 * return new OO.ui.Process()
3821 * .next( function () {
3822 * dialog.getActions().get({actions: 'save'})[0].popPending();
3825 * return MessageDialog.parent.prototype.getActionProcess.call( this, action );
3828 * var windowManager = new OO.ui.WindowManager();
3829 * $( 'body' ).append( windowManager.$element );
3831 * var dialog = new MessageDialog();
3832 * windowManager.addWindows( [ dialog ] );
3833 * windowManager.openWindow( dialog );
3839 * @param {Object} [config] Configuration options
3840 * @cfg {jQuery} [$pending] Element to mark as pending, defaults to this.$element
3842 OO
.ui
.mixin
.PendingElement
= function OoUiMixinPendingElement( config
) {
3843 // Configuration initialization
3844 config
= config
|| {};
3848 this.$pending
= null;
3851 this.setPendingElement( config
.$pending
|| this.$element
);
3856 OO
.initClass( OO
.ui
.mixin
.PendingElement
);
3861 * Set the pending element (and clean up any existing one).
3863 * @param {jQuery} $pending The element to set to pending.
3865 OO
.ui
.mixin
.PendingElement
.prototype.setPendingElement = function ( $pending
) {
3866 if ( this.$pending
) {
3867 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
3870 this.$pending
= $pending
;
3871 if ( this.pending
> 0 ) {
3872 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
3877 * Check if an element is pending.
3879 * @return {boolean} Element is pending
3881 OO
.ui
.mixin
.PendingElement
.prototype.isPending = function () {
3882 return !!this.pending
;
3886 * Increase the pending counter. The pending state will remain active until the counter is zero
3887 * (i.e., the number of calls to #pushPending and #popPending is the same).
3891 OO
.ui
.mixin
.PendingElement
.prototype.pushPending = function () {
3892 if ( this.pending
=== 0 ) {
3893 this.$pending
.addClass( 'oo-ui-pendingElement-pending' );
3894 this.updateThemeClasses();
3902 * Decrease the pending counter. The pending state will remain active until the counter is zero
3903 * (i.e., the number of calls to #pushPending and #popPending is the same).
3907 OO
.ui
.mixin
.PendingElement
.prototype.popPending = function () {
3908 if ( this.pending
=== 1 ) {
3909 this.$pending
.removeClass( 'oo-ui-pendingElement-pending' );
3910 this.updateThemeClasses();
3912 this.pending
= Math
.max( 0, this.pending
- 1 );
3918 * Element that can be automatically clipped to visible boundaries.
3920 * Whenever the element's natural height changes, you have to call
3921 * {@link OO.ui.mixin.ClippableElement#clip} to make sure it's still
3922 * clipping correctly.
3924 * The dimensions of #$clippableContainer will be compared to the boundaries of the
3925 * nearest scrollable container. If #$clippableContainer is too tall and/or too wide,
3926 * then #$clippable will be given a fixed reduced height and/or width and will be made
3927 * scrollable. By default, #$clippable and #$clippableContainer are the same element,
3928 * but you can build a static footer by setting #$clippableContainer to an element that contains
3929 * #$clippable and the footer.
3935 * @param {Object} [config] Configuration options
3936 * @cfg {jQuery} [$clippable] Node to clip, assigned to #$clippable, omit to use #$element
3937 * @cfg {jQuery} [$clippableContainer] Node to keep visible, assigned to #$clippableContainer,
3938 * omit to use #$clippable
3940 OO
.ui
.mixin
.ClippableElement
= function OoUiMixinClippableElement( config
) {
3941 // Configuration initialization
3942 config
= config
|| {};
3945 this.$clippable
= null;
3946 this.$clippableContainer
= null;
3947 this.clipping
= false;
3948 this.clippedHorizontally
= false;
3949 this.clippedVertically
= false;
3950 this.$clippableScrollableContainer
= null;
3951 this.$clippableScroller
= null;
3952 this.$clippableWindow
= null;
3953 this.idealWidth
= null;
3954 this.idealHeight
= null;
3955 this.onClippableScrollHandler
= this.clip
.bind( this );
3956 this.onClippableWindowResizeHandler
= this.clip
.bind( this );
3959 if ( config
.$clippableContainer
) {
3960 this.setClippableContainer( config
.$clippableContainer
);
3962 this.setClippableElement( config
.$clippable
|| this.$element
);
3968 * Set clippable element.
3970 * If an element is already set, it will be cleaned up before setting up the new element.
3972 * @param {jQuery} $clippable Element to make clippable
3974 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableElement = function ( $clippable
) {
3975 if ( this.$clippable
) {
3976 this.$clippable
.removeClass( 'oo-ui-clippableElement-clippable' );
3977 this.$clippable
.css( { width
: '', height
: '', overflowX
: '', overflowY
: '' } );
3978 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
3981 this.$clippable
= $clippable
.addClass( 'oo-ui-clippableElement-clippable' );
3986 * Set clippable container.
3988 * This is the container that will be measured when deciding whether to clip. When clipping,
3989 * #$clippable will be resized in order to keep the clippable container fully visible.
3991 * If the clippable container is unset, #$clippable will be used.
3993 * @param {jQuery|null} $clippableContainer Container to keep visible, or null to unset
3995 OO
.ui
.mixin
.ClippableElement
.prototype.setClippableContainer = function ( $clippableContainer
) {
3996 this.$clippableContainer
= $clippableContainer
;
3997 if ( this.$clippable
) {
4005 * Do not turn clipping on until after the element is attached to the DOM and visible.
4007 * @param {boolean} [clipping] Enable clipping, omit to toggle
4010 OO
.ui
.mixin
.ClippableElement
.prototype.toggleClipping = function ( clipping
) {
4011 clipping
= clipping
=== undefined ? !this.clipping
: !!clipping
;
4013 if ( this.clipping
!== clipping
) {
4014 this.clipping
= clipping
;
4016 this.$clippableScrollableContainer
= $( this.getClosestScrollableElementContainer() );
4017 // If the clippable container is the root, we have to listen to scroll events and check
4018 // jQuery.scrollTop on the window because of browser inconsistencies
4019 this.$clippableScroller
= this.$clippableScrollableContainer
.is( 'html, body' ) ?
4020 $( OO
.ui
.Element
.static.getWindow( this.$clippableScrollableContainer
) ) :
4021 this.$clippableScrollableContainer
;
4022 this.$clippableScroller
.on( 'scroll', this.onClippableScrollHandler
);
4023 this.$clippableWindow
= $( this.getElementWindow() )
4024 .on( 'resize', this.onClippableWindowResizeHandler
);
4025 // Initial clip after visible
4028 this.$clippable
.css( { width
: '', height
: '', overflowX
: '', overflowY
: '' } );
4029 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4031 this.$clippableScrollableContainer
= null;
4032 this.$clippableScroller
.off( 'scroll', this.onClippableScrollHandler
);
4033 this.$clippableScroller
= null;
4034 this.$clippableWindow
.off( 'resize', this.onClippableWindowResizeHandler
);
4035 this.$clippableWindow
= null;
4043 * Check if the element will be clipped to fit the visible area of the nearest scrollable container.
4045 * @return {boolean} Element will be clipped to the visible area
4047 OO
.ui
.mixin
.ClippableElement
.prototype.isClipping = function () {
4048 return this.clipping
;
4052 * Check if the bottom or right of the element is being clipped by the nearest scrollable container.
4054 * @return {boolean} Part of the element is being clipped
4056 OO
.ui
.mixin
.ClippableElement
.prototype.isClipped = function () {
4057 return this.clippedHorizontally
|| this.clippedVertically
;
4061 * Check if the right of the element is being clipped by the nearest scrollable container.
4063 * @return {boolean} Part of the element is being clipped
4065 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedHorizontally = function () {
4066 return this.clippedHorizontally
;
4070 * Check if the bottom of the element is being clipped by the nearest scrollable container.
4072 * @return {boolean} Part of the element is being clipped
4074 OO
.ui
.mixin
.ClippableElement
.prototype.isClippedVertically = function () {
4075 return this.clippedVertically
;
4079 * Set the ideal size. These are the dimensions the element will have when it's not being clipped.
4081 * @param {number|string} [width] Width as a number of pixels or CSS string with unit suffix
4082 * @param {number|string} [height] Height as a number of pixels or CSS string with unit suffix
4084 OO
.ui
.mixin
.ClippableElement
.prototype.setIdealSize = function ( width
, height
) {
4085 this.idealWidth
= width
;
4086 this.idealHeight
= height
;
4088 if ( !this.clipping
) {
4089 // Update dimensions
4090 this.$clippable
.css( { width
: width
, height
: height
} );
4092 // While clipping, idealWidth and idealHeight are not considered
4096 * Clip element to visible boundaries and allow scrolling when needed. You should call this method
4097 * when the element's natural height changes.
4099 * Element will be clipped the bottom or right of the element is within 10px of the edge of, or
4100 * overlapped by, the visible area of the nearest scrollable container.
4102 * Because calling clip() when the natural height changes isn't always possible, we also set
4103 * max-height when the element isn't being clipped. This means that if the element tries to grow
4104 * beyond the edge, something reasonable will happen before clip() is called.
4108 OO
.ui
.mixin
.ClippableElement
.prototype.clip = function () {
4109 var $container
, extraHeight
, extraWidth
, ccOffset
,
4110 $scrollableContainer
, scOffset
, scHeight
, scWidth
,
4111 ccWidth
, scrollerIsWindow
, scrollTop
, scrollLeft
,
4112 desiredWidth
, desiredHeight
, allotedWidth
, allotedHeight
,
4113 naturalWidth
, naturalHeight
, clipWidth
, clipHeight
,
4114 buffer
= 7; // Chosen by fair dice roll
4116 if ( !this.clipping
) {
4117 // this.$clippableScrollableContainer and this.$clippableWindow are null, so the below will fail
4121 $container
= this.$clippableContainer
|| this.$clippable
;
4122 extraHeight
= $container
.outerHeight() - this.$clippable
.outerHeight();
4123 extraWidth
= $container
.outerWidth() - this.$clippable
.outerWidth();
4124 ccOffset
= $container
.offset();
4125 $scrollableContainer
= this.$clippableScrollableContainer
.is( 'html, body' ) ?
4126 this.$clippableWindow
: this.$clippableScrollableContainer
;
4127 scOffset
= $scrollableContainer
.offset() || { top
: 0, left
: 0 };
4128 scHeight
= $scrollableContainer
.innerHeight() - buffer
;
4129 scWidth
= $scrollableContainer
.innerWidth() - buffer
;
4130 ccWidth
= $container
.outerWidth() + buffer
;
4131 scrollerIsWindow
= this.$clippableScroller
[ 0 ] === this.$clippableWindow
[ 0 ];
4132 scrollTop
= scrollerIsWindow
? this.$clippableScroller
.scrollTop() : 0;
4133 scrollLeft
= scrollerIsWindow
? this.$clippableScroller
.scrollLeft() : 0;
4134 desiredWidth
= ccOffset
.left
< 0 ?
4135 ccWidth
+ ccOffset
.left
:
4136 ( scOffset
.left
+ scrollLeft
+ scWidth
) - ccOffset
.left
;
4137 desiredHeight
= ( scOffset
.top
+ scrollTop
+ scHeight
) - ccOffset
.top
;
4138 // It should never be desirable to exceed the dimensions of the browser viewport... right?
4139 desiredWidth
= Math
.min( desiredWidth
, document
.documentElement
.clientWidth
);
4140 desiredHeight
= Math
.min( desiredHeight
, document
.documentElement
.clientHeight
);
4141 allotedWidth
= Math
.ceil( desiredWidth
- extraWidth
);
4142 allotedHeight
= Math
.ceil( desiredHeight
- extraHeight
);
4143 naturalWidth
= this.$clippable
.prop( 'scrollWidth' );
4144 naturalHeight
= this.$clippable
.prop( 'scrollHeight' );
4145 clipWidth
= allotedWidth
< naturalWidth
;
4146 clipHeight
= allotedHeight
< naturalHeight
;
4149 this.$clippable
.css( {
4150 overflowX
: 'scroll',
4151 width
: Math
.max( 0, allotedWidth
),
4155 this.$clippable
.css( {
4157 width
: this.idealWidth
? this.idealWidth
- extraWidth
: '',
4158 maxWidth
: Math
.max( 0, allotedWidth
)
4162 this.$clippable
.css( {
4163 overflowY
: 'scroll',
4164 height
: Math
.max( 0, allotedHeight
),
4168 this.$clippable
.css( {
4170 height
: this.idealHeight
? this.idealHeight
- extraHeight
: '',
4171 maxHeight
: Math
.max( 0, allotedHeight
)
4175 // If we stopped clipping in at least one of the dimensions
4176 if ( ( this.clippedHorizontally
&& !clipWidth
) || ( this.clippedVertically
&& !clipHeight
) ) {
4177 OO
.ui
.Element
.static.reconsiderScrollbars( this.$clippable
[ 0 ] );
4180 this.clippedHorizontally
= clipWidth
;
4181 this.clippedVertically
= clipHeight
;
4187 * PopupWidget is a container for content. The popup is overlaid and positioned absolutely.
4188 * By default, each popup has an anchor that points toward its origin.
4189 * Please see the [OOjs UI documentation on Mediawiki] [1] for more information and examples.
4192 * // A popup widget.
4193 * var popup = new OO.ui.PopupWidget( {
4194 * $content: $( '<p>Hi there!</p>' ),
4199 * $( 'body' ).append( popup.$element );
4200 * // To display the popup, toggle the visibility to 'true'.
4201 * popup.toggle( true );
4203 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups
4206 * @extends OO.ui.Widget
4207 * @mixins OO.ui.mixin.LabelElement
4208 * @mixins OO.ui.mixin.ClippableElement
4211 * @param {Object} [config] Configuration options
4212 * @cfg {number} [width=320] Width of popup in pixels
4213 * @cfg {number} [height] Height of popup in pixels. Omit to use the automatic height.
4214 * @cfg {boolean} [anchor=true] Show anchor pointing to origin of popup
4215 * @cfg {string} [align='center'] Alignment of the popup: `center`, `force-left`, `force-right`, `backwards` or `forwards`.
4216 * If the popup is forced-left the popup body is leaning towards the left. For force-right alignment, the body of the
4217 * popup is leaning towards the right of the screen.
4218 * Using 'backwards' is a logical direction which will result in the popup leaning towards the beginning of the sentence
4219 * in the given language, which means it will flip to the correct positioning in right-to-left languages.
4220 * Using 'forward' will also result in a logical alignment where the body of the popup leans towards the end of the
4221 * sentence in the given language.
4222 * @cfg {jQuery} [$container] Constrain the popup to the boundaries of the specified container.
4223 * See the [OOjs UI docs on MediaWiki][3] for an example.
4224 * [3]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#containerExample
4225 * @cfg {number} [containerPadding=10] Padding between the popup and its container, specified as a number of pixels.
4226 * @cfg {jQuery} [$content] Content to append to the popup's body
4227 * @cfg {jQuery} [$footer] Content to append to the popup's footer
4228 * @cfg {boolean} [autoClose=false] Automatically close the popup when it loses focus.
4229 * @cfg {jQuery} [$autoCloseIgnore] Elements that will not close the popup when clicked.
4230 * This config option is only relevant if #autoClose is set to `true`. See the [OOjs UI docs on MediaWiki][2]
4232 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Popups#autocloseExample
4233 * @cfg {boolean} [head=false] Show a popup header that contains a #label (if specified) and close
4235 * @cfg {boolean} [padded=false] Add padding to the popup's body
4237 OO
.ui
.PopupWidget
= function OoUiPopupWidget( config
) {
4238 // Configuration initialization
4239 config
= config
|| {};
4241 // Parent constructor
4242 OO
.ui
.PopupWidget
.parent
.call( this, config
);
4244 // Properties (must be set before ClippableElement constructor call)
4245 this.$body
= $( '<div>' );
4246 this.$popup
= $( '<div>' );
4248 // Mixin constructors
4249 OO
.ui
.mixin
.LabelElement
.call( this, config
);
4250 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, {
4251 $clippable
: this.$body
,
4252 $clippableContainer
: this.$popup
4256 this.$anchor
= $( '<div>' );
4257 // If undefined, will be computed lazily in updateDimensions()
4258 this.$container
= config
.$container
;
4259 this.containerPadding
= config
.containerPadding
!== undefined ? config
.containerPadding
: 10;
4260 this.autoClose
= !!config
.autoClose
;
4261 this.$autoCloseIgnore
= config
.$autoCloseIgnore
;
4262 this.transitionTimeout
= null;
4264 this.width
= config
.width
!== undefined ? config
.width
: 320;
4265 this.height
= config
.height
!== undefined ? config
.height
: null;
4266 this.setAlignment( config
.align
);
4267 this.onMouseDownHandler
= this.onMouseDown
.bind( this );
4268 this.onDocumentKeyDownHandler
= this.onDocumentKeyDown
.bind( this );
4271 this.toggleAnchor( config
.anchor
=== undefined || config
.anchor
);
4272 this.$body
.addClass( 'oo-ui-popupWidget-body' );
4273 this.$anchor
.addClass( 'oo-ui-popupWidget-anchor' );
4275 .addClass( 'oo-ui-popupWidget-popup' )
4276 .append( this.$body
);
4278 .addClass( 'oo-ui-popupWidget' )
4279 .append( this.$popup
, this.$anchor
);
4280 // Move content, which was added to #$element by OO.ui.Widget, to the body
4281 // FIXME This is gross, we should use '$body' or something for the config
4282 if ( config
.$content
instanceof jQuery
) {
4283 this.$body
.append( config
.$content
);
4286 if ( config
.padded
) {
4287 this.$body
.addClass( 'oo-ui-popupWidget-body-padded' );
4290 if ( config
.head
) {
4291 this.closeButton
= new OO
.ui
.ButtonWidget( { framed
: false, icon
: 'close' } );
4292 this.closeButton
.connect( this, { click
: 'onCloseButtonClick' } );
4293 this.$head
= $( '<div>' )
4294 .addClass( 'oo-ui-popupWidget-head' )
4295 .append( this.$label
, this.closeButton
.$element
);
4296 this.$popup
.prepend( this.$head
);
4299 if ( config
.$footer
) {
4300 this.$footer
= $( '<div>' )
4301 .addClass( 'oo-ui-popupWidget-footer' )
4302 .append( config
.$footer
);
4303 this.$popup
.append( this.$footer
);
4306 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
4307 // that reference properties not initialized at that time of parent class construction
4308 // TODO: Find a better way to handle post-constructor setup
4309 this.visible
= false;
4310 this.$element
.addClass( 'oo-ui-element-hidden' );
4315 OO
.inheritClass( OO
.ui
.PopupWidget
, OO
.ui
.Widget
);
4316 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.LabelElement
);
4317 OO
.mixinClass( OO
.ui
.PopupWidget
, OO
.ui
.mixin
.ClippableElement
);
4322 * Handles mouse down events.
4325 * @param {MouseEvent} e Mouse down event
4327 OO
.ui
.PopupWidget
.prototype.onMouseDown = function ( e
) {
4330 !$.contains( this.$element
[ 0 ], e
.target
) &&
4331 ( !this.$autoCloseIgnore
|| !this.$autoCloseIgnore
.has( e
.target
).length
)
4333 this.toggle( false );
4338 * Bind mouse down listener.
4342 OO
.ui
.PopupWidget
.prototype.bindMouseDownListener = function () {
4343 // Capture clicks outside popup
4344 this.getElementWindow().addEventListener( 'mousedown', this.onMouseDownHandler
, true );
4348 * Handles close button click events.
4352 OO
.ui
.PopupWidget
.prototype.onCloseButtonClick = function () {
4353 if ( this.isVisible() ) {
4354 this.toggle( false );
4359 * Unbind mouse down listener.
4363 OO
.ui
.PopupWidget
.prototype.unbindMouseDownListener = function () {
4364 this.getElementWindow().removeEventListener( 'mousedown', this.onMouseDownHandler
, true );
4368 * Handles key down events.
4371 * @param {KeyboardEvent} e Key down event
4373 OO
.ui
.PopupWidget
.prototype.onDocumentKeyDown = function ( e
) {
4375 e
.which
=== OO
.ui
.Keys
.ESCAPE
&&
4378 this.toggle( false );
4380 e
.stopPropagation();
4385 * Bind key down listener.
4389 OO
.ui
.PopupWidget
.prototype.bindKeyDownListener = function () {
4390 this.getElementWindow().addEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
4394 * Unbind key down listener.
4398 OO
.ui
.PopupWidget
.prototype.unbindKeyDownListener = function () {
4399 this.getElementWindow().removeEventListener( 'keydown', this.onDocumentKeyDownHandler
, true );
4403 * Show, hide, or toggle the visibility of the anchor.
4405 * @param {boolean} [show] Show anchor, omit to toggle
4407 OO
.ui
.PopupWidget
.prototype.toggleAnchor = function ( show
) {
4408 show
= show
=== undefined ? !this.anchored
: !!show
;
4410 if ( this.anchored
!== show
) {
4412 this.$element
.addClass( 'oo-ui-popupWidget-anchored' );
4414 this.$element
.removeClass( 'oo-ui-popupWidget-anchored' );
4416 this.anchored
= show
;
4421 * Check if the anchor is visible.
4423 * @return {boolean} Anchor is visible
4425 OO
.ui
.PopupWidget
.prototype.hasAnchor = function () {
4432 OO
.ui
.PopupWidget
.prototype.toggle = function ( show
) {
4434 show
= show
=== undefined ? !this.isVisible() : !!show
;
4436 change
= show
!== this.isVisible();
4439 OO
.ui
.PopupWidget
.parent
.prototype.toggle
.call( this, show
);
4443 if ( this.autoClose
) {
4444 this.bindMouseDownListener();
4445 this.bindKeyDownListener();
4447 this.updateDimensions();
4448 this.toggleClipping( true );
4450 this.toggleClipping( false );
4451 if ( this.autoClose
) {
4452 this.unbindMouseDownListener();
4453 this.unbindKeyDownListener();
4462 * Set the size of the popup.
4464 * Changing the size may also change the popup's position depending on the alignment.
4466 * @param {number} width Width in pixels
4467 * @param {number} height Height in pixels
4468 * @param {boolean} [transition=false] Use a smooth transition
4471 OO
.ui
.PopupWidget
.prototype.setSize = function ( width
, height
, transition
) {
4473 this.height
= height
!== undefined ? height
: null;
4474 if ( this.isVisible() ) {
4475 this.updateDimensions( transition
);
4480 * Update the size and position.
4482 * Only use this to keep the popup properly anchored. Use #setSize to change the size, and this will
4483 * be called automatically.
4485 * @param {boolean} [transition=false] Use a smooth transition
4488 OO
.ui
.PopupWidget
.prototype.updateDimensions = function ( transition
) {
4489 var popupOffset
, originOffset
, containerLeft
, containerWidth
, containerRight
,
4490 popupLeft
, popupRight
, overlapLeft
, overlapRight
, anchorWidth
,
4494 if ( !this.$container
) {
4495 // Lazy-initialize $container if not specified in constructor
4496 this.$container
= $( this.getClosestScrollableElementContainer() );
4499 // Set height and width before measuring things, since it might cause our measurements
4500 // to change (e.g. due to scrollbars appearing or disappearing)
4503 height
: this.height
!== null ? this.height
: 'auto'
4506 // If we are in RTL, we need to flip the alignment, unless it is center
4507 if ( align
=== 'forwards' || align
=== 'backwards' ) {
4508 if ( this.$container
.css( 'direction' ) === 'rtl' ) {
4509 align
= ( { forwards
: 'force-left', backwards
: 'force-right' } )[ this.align
];
4511 align
= ( { forwards
: 'force-right', backwards
: 'force-left' } )[ this.align
];
4516 // Compute initial popupOffset based on alignment
4517 popupOffset
= this.width
* ( { 'force-left': -1, center
: -0.5, 'force-right': 0 } )[ align
];
4519 // Figure out if this will cause the popup to go beyond the edge of the container
4520 originOffset
= this.$element
.offset().left
;
4521 containerLeft
= this.$container
.offset().left
;
4522 containerWidth
= this.$container
.innerWidth();
4523 containerRight
= containerLeft
+ containerWidth
;
4524 popupLeft
= popupOffset
- this.containerPadding
;
4525 popupRight
= popupOffset
+ this.containerPadding
+ this.width
+ this.containerPadding
;
4526 overlapLeft
= ( originOffset
+ popupLeft
) - containerLeft
;
4527 overlapRight
= containerRight
- ( originOffset
+ popupRight
);
4529 // Adjust offset to make the popup not go beyond the edge, if needed
4530 if ( overlapRight
< 0 ) {
4531 popupOffset
+= overlapRight
;
4532 } else if ( overlapLeft
< 0 ) {
4533 popupOffset
-= overlapLeft
;
4536 // Adjust offset to avoid anchor being rendered too close to the edge
4537 // $anchor.width() doesn't work with the pure CSS anchor (returns 0)
4538 // TODO: Find a measurement that works for CSS anchors and image anchors
4539 anchorWidth
= this.$anchor
[ 0 ].scrollWidth
* 2;
4540 if ( popupOffset
+ this.width
< anchorWidth
) {
4541 popupOffset
= anchorWidth
- this.width
;
4542 } else if ( -popupOffset
< anchorWidth
) {
4543 popupOffset
= -anchorWidth
;
4546 // Prevent transition from being interrupted
4547 clearTimeout( this.transitionTimeout
);
4549 // Enable transition
4550 this.$element
.addClass( 'oo-ui-popupWidget-transitioning' );
4553 // Position body relative to anchor
4554 this.$popup
.css( 'margin-left', popupOffset
);
4557 // Prevent transitioning after transition is complete
4558 this.transitionTimeout
= setTimeout( function () {
4559 widget
.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
4562 // Prevent transitioning immediately
4563 this.$element
.removeClass( 'oo-ui-popupWidget-transitioning' );
4566 // Reevaluate clipping state since we've relocated and resized the popup
4573 * Set popup alignment
4575 * @param {string} align Alignment of the popup, `center`, `force-left`, `force-right`,
4576 * `backwards` or `forwards`.
4578 OO
.ui
.PopupWidget
.prototype.setAlignment = function ( align
) {
4579 // Validate alignment and transform deprecated values
4580 if ( [ 'left', 'right', 'force-left', 'force-right', 'backwards', 'forwards', 'center' ].indexOf( align
) > -1 ) {
4581 this.align
= { left
: 'force-right', right
: 'force-left' }[ align
] || align
;
4583 this.align
= 'center';
4588 * Get popup alignment
4590 * @return {string} align Alignment of the popup, `center`, `force-left`, `force-right`,
4591 * `backwards` or `forwards`.
4593 OO
.ui
.PopupWidget
.prototype.getAlignment = function () {
4598 * PopupElement is mixed into other classes to generate a {@link OO.ui.PopupWidget popup widget}.
4599 * A popup is a container for content. It is overlaid and positioned absolutely. By default, each
4600 * popup has an anchor, which is an arrow-like protrusion that points toward the popup’s origin.
4601 * See {@link OO.ui.PopupWidget PopupWidget} for an example.
4607 * @param {Object} [config] Configuration options
4608 * @cfg {Object} [popup] Configuration to pass to popup
4609 * @cfg {boolean} [popup.autoClose=true] Popup auto-closes when it loses focus
4611 OO
.ui
.mixin
.PopupElement
= function OoUiMixinPopupElement( config
) {
4612 // Configuration initialization
4613 config
= config
|| {};
4616 this.popup
= new OO
.ui
.PopupWidget( $.extend(
4617 { autoClose
: true },
4619 { $autoCloseIgnore
: this.$element
}
4628 * @return {OO.ui.PopupWidget} Popup widget
4630 OO
.ui
.mixin
.PopupElement
.prototype.getPopup = function () {
4635 * PopupButtonWidgets toggle the visibility of a contained {@link OO.ui.PopupWidget PopupWidget},
4636 * which is used to display additional information or options.
4639 * // Example of a popup button.
4640 * var popupButton = new OO.ui.PopupButtonWidget( {
4641 * label: 'Popup button with options',
4644 * $content: $( '<p>Additional options here.</p>' ),
4646 * align: 'force-left'
4649 * // Append the button to the DOM.
4650 * $( 'body' ).append( popupButton.$element );
4653 * @extends OO.ui.ButtonWidget
4654 * @mixins OO.ui.mixin.PopupElement
4657 * @param {Object} [config] Configuration options
4659 OO
.ui
.PopupButtonWidget
= function OoUiPopupButtonWidget( config
) {
4660 // Parent constructor
4661 OO
.ui
.PopupButtonWidget
.parent
.call( this, config
);
4663 // Mixin constructors
4664 OO
.ui
.mixin
.PopupElement
.call( this, config
);
4667 this.connect( this, { click
: 'onAction' } );
4671 .addClass( 'oo-ui-popupButtonWidget' )
4672 .attr( 'aria-haspopup', 'true' )
4673 .append( this.popup
.$element
);
4678 OO
.inheritClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.ButtonWidget
);
4679 OO
.mixinClass( OO
.ui
.PopupButtonWidget
, OO
.ui
.mixin
.PopupElement
);
4684 * Handle the button action being triggered.
4688 OO
.ui
.PopupButtonWidget
.prototype.onAction = function () {
4689 this.popup
.toggle();
4693 * Mixin for OO.ui.Widget subclasses to provide OO.ui.mixin.GroupElement.
4695 * Use together with OO.ui.mixin.ItemWidget to make disabled state inheritable.
4700 * @extends OO.ui.mixin.GroupElement
4703 * @param {Object} [config] Configuration options
4705 OO
.ui
.mixin
.GroupWidget
= function OoUiMixinGroupWidget( config
) {
4706 // Parent constructor
4707 OO
.ui
.mixin
.GroupWidget
.parent
.call( this, config
);
4712 OO
.inheritClass( OO
.ui
.mixin
.GroupWidget
, OO
.ui
.mixin
.GroupElement
);
4717 * Set the disabled state of the widget.
4719 * This will also update the disabled state of child widgets.
4721 * @param {boolean} disabled Disable widget
4724 OO
.ui
.mixin
.GroupWidget
.prototype.setDisabled = function ( disabled
) {
4728 // Note: Calling #setDisabled this way assumes this is mixed into an OO.ui.Widget
4729 OO
.ui
.Widget
.prototype.setDisabled
.call( this, disabled
);
4731 // During construction, #setDisabled is called before the OO.ui.mixin.GroupElement constructor
4733 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
4734 this.items
[ i
].updateDisabled();
4742 * Mixin for widgets used as items in widgets that mix in OO.ui.mixin.GroupWidget.
4744 * Item widgets have a reference to a OO.ui.mixin.GroupWidget while they are attached to the group. This
4745 * allows bidirectional communication.
4747 * Use together with OO.ui.mixin.GroupWidget to make disabled state inheritable.
4755 OO
.ui
.mixin
.ItemWidget
= function OoUiMixinItemWidget() {
4762 * Check if widget is disabled.
4764 * Checks parent if present, making disabled state inheritable.
4766 * @return {boolean} Widget is disabled
4768 OO
.ui
.mixin
.ItemWidget
.prototype.isDisabled = function () {
4769 return this.disabled
||
4770 ( this.elementGroup
instanceof OO
.ui
.Widget
&& this.elementGroup
.isDisabled() );
4774 * Set group element is in.
4776 * @param {OO.ui.mixin.GroupElement|null} group Group element, null if none
4779 OO
.ui
.mixin
.ItemWidget
.prototype.setElementGroup = function ( group
) {
4781 // Note: Calling #setElementGroup this way assumes this is mixed into an OO.ui.Element
4782 OO
.ui
.Element
.prototype.setElementGroup
.call( this, group
);
4784 // Initialize item disabled states
4785 this.updateDisabled();
4791 * OptionWidgets are special elements that can be selected and configured with data. The
4792 * data is often unique for each option, but it does not have to be. OptionWidgets are used
4793 * with OO.ui.SelectWidget to create a selection of mutually exclusive options. For more information
4794 * and examples, please see the [OOjs UI documentation on MediaWiki][1].
4796 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
4799 * @extends OO.ui.Widget
4800 * @mixins OO.ui.mixin.ItemWidget
4801 * @mixins OO.ui.mixin.LabelElement
4802 * @mixins OO.ui.mixin.FlaggedElement
4803 * @mixins OO.ui.mixin.AccessKeyedElement
4806 * @param {Object} [config] Configuration options
4808 OO
.ui
.OptionWidget
= function OoUiOptionWidget( config
) {
4809 // Configuration initialization
4810 config
= config
|| {};
4812 // Parent constructor
4813 OO
.ui
.OptionWidget
.parent
.call( this, config
);
4815 // Mixin constructors
4816 OO
.ui
.mixin
.ItemWidget
.call( this );
4817 OO
.ui
.mixin
.LabelElement
.call( this, config
);
4818 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
4819 OO
.ui
.mixin
.AccessKeyedElement
.call( this, config
);
4822 this.selected
= false;
4823 this.highlighted
= false;
4824 this.pressed
= false;
4828 .data( 'oo-ui-optionWidget', this )
4829 // Allow programmatic focussing (and by accesskey), but not tabbing
4830 .attr( 'tabindex', '-1' )
4831 .attr( 'role', 'option' )
4832 .attr( 'aria-selected', 'false' )
4833 .addClass( 'oo-ui-optionWidget' )
4834 .append( this.$label
);
4839 OO
.inheritClass( OO
.ui
.OptionWidget
, OO
.ui
.Widget
);
4840 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.ItemWidget
);
4841 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.LabelElement
);
4842 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.FlaggedElement
);
4843 OO
.mixinClass( OO
.ui
.OptionWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
4845 /* Static Properties */
4847 OO
.ui
.OptionWidget
.static.selectable
= true;
4849 OO
.ui
.OptionWidget
.static.highlightable
= true;
4851 OO
.ui
.OptionWidget
.static.pressable
= true;
4853 OO
.ui
.OptionWidget
.static.scrollIntoViewOnSelect
= false;
4858 * Check if the option can be selected.
4860 * @return {boolean} Item is selectable
4862 OO
.ui
.OptionWidget
.prototype.isSelectable = function () {
4863 return this.constructor.static.selectable
&& !this.isDisabled() && this.isVisible();
4867 * Check if the option can be highlighted. A highlight indicates that the option
4868 * may be selected when a user presses enter or clicks. Disabled items cannot
4871 * @return {boolean} Item is highlightable
4873 OO
.ui
.OptionWidget
.prototype.isHighlightable = function () {
4874 return this.constructor.static.highlightable
&& !this.isDisabled() && this.isVisible();
4878 * Check if the option can be pressed. The pressed state occurs when a user mouses
4879 * down on an item, but has not yet let go of the mouse.
4881 * @return {boolean} Item is pressable
4883 OO
.ui
.OptionWidget
.prototype.isPressable = function () {
4884 return this.constructor.static.pressable
&& !this.isDisabled() && this.isVisible();
4888 * Check if the option is selected.
4890 * @return {boolean} Item is selected
4892 OO
.ui
.OptionWidget
.prototype.isSelected = function () {
4893 return this.selected
;
4897 * Check if the option is highlighted. A highlight indicates that the
4898 * item may be selected when a user presses enter or clicks.
4900 * @return {boolean} Item is highlighted
4902 OO
.ui
.OptionWidget
.prototype.isHighlighted = function () {
4903 return this.highlighted
;
4907 * Check if the option is pressed. The pressed state occurs when a user mouses
4908 * down on an item, but has not yet let go of the mouse. The item may appear
4909 * selected, but it will not be selected until the user releases the mouse.
4911 * @return {boolean} Item is pressed
4913 OO
.ui
.OptionWidget
.prototype.isPressed = function () {
4914 return this.pressed
;
4918 * Set the option’s selected state. In general, all modifications to the selection
4919 * should be handled by the SelectWidget’s {@link OO.ui.SelectWidget#selectItem selectItem( [item] )}
4920 * method instead of this method.
4922 * @param {boolean} [state=false] Select option
4925 OO
.ui
.OptionWidget
.prototype.setSelected = function ( state
) {
4926 if ( this.constructor.static.selectable
) {
4927 this.selected
= !!state
;
4929 .toggleClass( 'oo-ui-optionWidget-selected', state
)
4930 .attr( 'aria-selected', state
.toString() );
4931 if ( state
&& this.constructor.static.scrollIntoViewOnSelect
) {
4932 this.scrollElementIntoView();
4934 this.updateThemeClasses();
4940 * Set the option’s highlighted state. In general, all programmatic
4941 * modifications to the highlight should be handled by the
4942 * SelectWidget’s {@link OO.ui.SelectWidget#highlightItem highlightItem( [item] )}
4943 * method instead of this method.
4945 * @param {boolean} [state=false] Highlight option
4948 OO
.ui
.OptionWidget
.prototype.setHighlighted = function ( state
) {
4949 if ( this.constructor.static.highlightable
) {
4950 this.highlighted
= !!state
;
4951 this.$element
.toggleClass( 'oo-ui-optionWidget-highlighted', state
);
4952 this.updateThemeClasses();
4958 * Set the option’s pressed state. In general, all
4959 * programmatic modifications to the pressed state should be handled by the
4960 * SelectWidget’s {@link OO.ui.SelectWidget#pressItem pressItem( [item] )}
4961 * method instead of this method.
4963 * @param {boolean} [state=false] Press option
4966 OO
.ui
.OptionWidget
.prototype.setPressed = function ( state
) {
4967 if ( this.constructor.static.pressable
) {
4968 this.pressed
= !!state
;
4969 this.$element
.toggleClass( 'oo-ui-optionWidget-pressed', state
);
4970 this.updateThemeClasses();
4976 * A SelectWidget is of a generic selection of options. The OOjs UI library contains several types of
4977 * select widgets, including {@link OO.ui.ButtonSelectWidget button selects},
4978 * {@link OO.ui.RadioSelectWidget radio selects}, and {@link OO.ui.MenuSelectWidget
4981 * This class should be used together with OO.ui.OptionWidget or OO.ui.DecoratedOptionWidget. For more
4982 * information, please see the [OOjs UI documentation on MediaWiki][1].
4985 * // Example of a select widget with three options
4986 * var select = new OO.ui.SelectWidget( {
4988 * new OO.ui.OptionWidget( {
4990 * label: 'Option One',
4992 * new OO.ui.OptionWidget( {
4994 * label: 'Option Two',
4996 * new OO.ui.OptionWidget( {
4998 * label: 'Option Three',
5002 * $( 'body' ).append( select.$element );
5004 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5008 * @extends OO.ui.Widget
5009 * @mixins OO.ui.mixin.GroupWidget
5012 * @param {Object} [config] Configuration options
5013 * @cfg {OO.ui.OptionWidget[]} [items] An array of options to add to the select.
5014 * Options are created with {@link OO.ui.OptionWidget OptionWidget} classes. See
5015 * the [OOjs UI documentation on MediaWiki] [2] for examples.
5016 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5018 OO
.ui
.SelectWidget
= function OoUiSelectWidget( config
) {
5019 // Configuration initialization
5020 config
= config
|| {};
5022 // Parent constructor
5023 OO
.ui
.SelectWidget
.parent
.call( this, config
);
5025 // Mixin constructors
5026 OO
.ui
.mixin
.GroupWidget
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
5029 this.pressed
= false;
5030 this.selecting
= null;
5031 this.onMouseUpHandler
= this.onMouseUp
.bind( this );
5032 this.onMouseMoveHandler
= this.onMouseMove
.bind( this );
5033 this.onKeyDownHandler
= this.onKeyDown
.bind( this );
5034 this.onKeyPressHandler
= this.onKeyPress
.bind( this );
5035 this.keyPressBuffer
= '';
5036 this.keyPressBufferTimer
= null;
5037 this.blockMouseOverEvents
= 0;
5040 this.connect( this, {
5044 focusin
: this.onFocus
.bind( this ),
5045 mousedown
: this.onMouseDown
.bind( this ),
5046 mouseover
: this.onMouseOver
.bind( this ),
5047 mouseleave
: this.onMouseLeave
.bind( this )
5052 .addClass( 'oo-ui-selectWidget oo-ui-selectWidget-depressed' )
5053 .attr( 'role', 'listbox' );
5054 if ( Array
.isArray( config
.items
) ) {
5055 this.addItems( config
.items
);
5061 OO
.inheritClass( OO
.ui
.SelectWidget
, OO
.ui
.Widget
);
5063 // Need to mixin base class as well
5064 OO
.mixinClass( OO
.ui
.SelectWidget
, OO
.ui
.mixin
.GroupElement
);
5065 OO
.mixinClass( OO
.ui
.SelectWidget
, OO
.ui
.mixin
.GroupWidget
);
5068 OO
.ui
.SelectWidget
.static.passAllFilter = function () {
5077 * A `highlight` event is emitted when the highlight is changed with the #highlightItem method.
5079 * @param {OO.ui.OptionWidget|null} item Highlighted item
5085 * A `press` event is emitted when the #pressItem method is used to programmatically modify the
5086 * pressed state of an option.
5088 * @param {OO.ui.OptionWidget|null} item Pressed item
5094 * A `select` event is emitted when the selection is modified programmatically with the #selectItem method.
5096 * @param {OO.ui.OptionWidget|null} item Selected item
5101 * A `choose` event is emitted when an item is chosen with the #chooseItem method.
5102 * @param {OO.ui.OptionWidget} item Chosen item
5108 * An `add` event is emitted when options are added to the select with the #addItems method.
5110 * @param {OO.ui.OptionWidget[]} items Added items
5111 * @param {number} index Index of insertion point
5117 * A `remove` event is emitted when options are removed from the select with the #clearItems
5118 * or #removeItems methods.
5120 * @param {OO.ui.OptionWidget[]} items Removed items
5126 * Handle focus events
5129 * @param {jQuery.Event} event
5131 OO
.ui
.SelectWidget
.prototype.onFocus = function ( event
) {
5132 if ( event
.target
=== this.$element
[ 0 ] ) {
5133 // This widget was focussed, e.g. by the user tabbing to it.
5134 // The styles for focus state depend on one of the items being selected.
5135 if ( !this.getSelectedItem() ) {
5136 this.selectItem( this.getFirstSelectableItem() );
5139 // One of the options got focussed (and the event bubbled up here).
5140 // They can't be tabbed to, but they can be activated using accesskeys.
5141 this.selectItem( this.getTargetItem( event
) );
5142 this.$element
.focus();
5147 * Handle mouse down events.
5150 * @param {jQuery.Event} e Mouse down event
5152 OO
.ui
.SelectWidget
.prototype.onMouseDown = function ( e
) {
5155 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
5156 this.togglePressed( true );
5157 item
= this.getTargetItem( e
);
5158 if ( item
&& item
.isSelectable() ) {
5159 this.pressItem( item
);
5160 this.selecting
= item
;
5161 this.getElementDocument().addEventListener( 'mouseup', this.onMouseUpHandler
, true );
5162 this.getElementDocument().addEventListener( 'mousemove', this.onMouseMoveHandler
, true );
5169 * Handle mouse up events.
5172 * @param {MouseEvent} e Mouse up event
5174 OO
.ui
.SelectWidget
.prototype.onMouseUp = function ( e
) {
5177 this.togglePressed( false );
5178 if ( !this.selecting
) {
5179 item
= this.getTargetItem( e
);
5180 if ( item
&& item
.isSelectable() ) {
5181 this.selecting
= item
;
5184 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
&& this.selecting
) {
5185 this.pressItem( null );
5186 this.chooseItem( this.selecting
);
5187 this.selecting
= null;
5190 this.getElementDocument().removeEventListener( 'mouseup', this.onMouseUpHandler
, true );
5191 this.getElementDocument().removeEventListener( 'mousemove', this.onMouseMoveHandler
, true );
5197 * Handle mouse move events.
5200 * @param {MouseEvent} e Mouse move event
5202 OO
.ui
.SelectWidget
.prototype.onMouseMove = function ( e
) {
5205 if ( !this.isDisabled() && this.pressed
) {
5206 item
= this.getTargetItem( e
);
5207 if ( item
&& item
!== this.selecting
&& item
.isSelectable() ) {
5208 this.pressItem( item
);
5209 this.selecting
= item
;
5215 * Handle mouse over events.
5218 * @param {jQuery.Event} e Mouse over event
5220 OO
.ui
.SelectWidget
.prototype.onMouseOver = function ( e
) {
5222 if ( this.blockMouseOverEvents
) {
5225 if ( !this.isDisabled() ) {
5226 item
= this.getTargetItem( e
);
5227 this.highlightItem( item
&& item
.isHighlightable() ? item
: null );
5233 * Handle mouse leave events.
5236 * @param {jQuery.Event} e Mouse over event
5238 OO
.ui
.SelectWidget
.prototype.onMouseLeave = function () {
5239 if ( !this.isDisabled() ) {
5240 this.highlightItem( null );
5246 * Handle key down events.
5249 * @param {KeyboardEvent} e Key down event
5251 OO
.ui
.SelectWidget
.prototype.onKeyDown = function ( e
) {
5254 currentItem
= this.getHighlightedItem() || this.getSelectedItem();
5256 if ( !this.isDisabled() && this.isVisible() ) {
5257 switch ( e
.keyCode
) {
5258 case OO
.ui
.Keys
.ENTER
:
5259 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
5260 // Was only highlighted, now let's select it. No-op if already selected.
5261 this.chooseItem( currentItem
);
5266 case OO
.ui
.Keys
.LEFT
:
5267 this.clearKeyPressBuffer();
5268 nextItem
= this.getRelativeSelectableItem( currentItem
, -1 );
5271 case OO
.ui
.Keys
.DOWN
:
5272 case OO
.ui
.Keys
.RIGHT
:
5273 this.clearKeyPressBuffer();
5274 nextItem
= this.getRelativeSelectableItem( currentItem
, 1 );
5277 case OO
.ui
.Keys
.ESCAPE
:
5278 case OO
.ui
.Keys
.TAB
:
5279 if ( currentItem
&& currentItem
.constructor.static.highlightable
) {
5280 currentItem
.setHighlighted( false );
5282 this.unbindKeyDownListener();
5283 this.unbindKeyPressListener();
5284 // Don't prevent tabbing away / defocusing
5290 if ( nextItem
.constructor.static.highlightable
) {
5291 this.highlightItem( nextItem
);
5293 this.chooseItem( nextItem
);
5295 this.scrollItemIntoView( nextItem
);
5300 e
.stopPropagation();
5306 * Bind key down listener.
5310 OO
.ui
.SelectWidget
.prototype.bindKeyDownListener = function () {
5311 this.getElementWindow().addEventListener( 'keydown', this.onKeyDownHandler
, true );
5315 * Unbind key down listener.
5319 OO
.ui
.SelectWidget
.prototype.unbindKeyDownListener = function () {
5320 this.getElementWindow().removeEventListener( 'keydown', this.onKeyDownHandler
, true );
5324 * Scroll item into view, preventing spurious mouse highlight actions from happening.
5326 * @param {OO.ui.OptionWidget} item Item to scroll into view
5328 OO
.ui
.SelectWidget
.prototype.scrollItemIntoView = function ( item
) {
5330 // Chromium's Blink engine will generate spurious 'mouseover' events during programmatic scrolling
5331 // and around 100-150 ms after it is finished.
5332 this.blockMouseOverEvents
++;
5333 item
.scrollElementIntoView().done( function () {
5334 setTimeout( function () {
5335 widget
.blockMouseOverEvents
--;
5341 * Clear the key-press buffer
5345 OO
.ui
.SelectWidget
.prototype.clearKeyPressBuffer = function () {
5346 if ( this.keyPressBufferTimer
) {
5347 clearTimeout( this.keyPressBufferTimer
);
5348 this.keyPressBufferTimer
= null;
5350 this.keyPressBuffer
= '';
5354 * Handle key press events.
5357 * @param {KeyboardEvent} e Key press event
5359 OO
.ui
.SelectWidget
.prototype.onKeyPress = function ( e
) {
5360 var c
, filter
, item
;
5362 if ( !e
.charCode
) {
5363 if ( e
.keyCode
=== OO
.ui
.Keys
.BACKSPACE
&& this.keyPressBuffer
!== '' ) {
5364 this.keyPressBuffer
= this.keyPressBuffer
.substr( 0, this.keyPressBuffer
.length
- 1 );
5369 if ( String
.fromCodePoint
) {
5370 c
= String
.fromCodePoint( e
.charCode
);
5372 c
= String
.fromCharCode( e
.charCode
);
5375 if ( this.keyPressBufferTimer
) {
5376 clearTimeout( this.keyPressBufferTimer
);
5378 this.keyPressBufferTimer
= setTimeout( this.clearKeyPressBuffer
.bind( this ), 1500 );
5380 item
= this.getHighlightedItem() || this.getSelectedItem();
5382 if ( this.keyPressBuffer
=== c
) {
5383 // Common (if weird) special case: typing "xxxx" will cycle through all
5384 // the items beginning with "x".
5386 item
= this.getRelativeSelectableItem( item
, 1 );
5389 this.keyPressBuffer
+= c
;
5392 filter
= this.getItemMatcher( this.keyPressBuffer
, false );
5393 if ( !item
|| !filter( item
) ) {
5394 item
= this.getRelativeSelectableItem( item
, 1, filter
);
5397 if ( item
.constructor.static.highlightable
) {
5398 this.highlightItem( item
);
5400 this.chooseItem( item
);
5402 this.scrollItemIntoView( item
);
5406 e
.stopPropagation();
5410 * Get a matcher for the specific string
5413 * @param {string} s String to match against items
5414 * @param {boolean} [exact=false] Only accept exact matches
5415 * @return {Function} function ( OO.ui.OptionItem ) => boolean
5417 OO
.ui
.SelectWidget
.prototype.getItemMatcher = function ( s
, exact
) {
5420 if ( s
.normalize
) {
5423 s
= exact
? s
.trim() : s
.replace( /^\s+/, '' );
5424 re
= '^\\s*' + s
.replace( /([\\{}()|.?*+\-\^$\[\]])/g, '\\$1' ).replace( /\s+/g, '\\s+' );
5428 re
= new RegExp( re
, 'i' );
5429 return function ( item
) {
5430 var l
= item
.getLabel();
5431 if ( typeof l
!== 'string' ) {
5432 l
= item
.$label
.text();
5434 if ( l
.normalize
) {
5437 return re
.test( l
);
5442 * Bind key press listener.
5446 OO
.ui
.SelectWidget
.prototype.bindKeyPressListener = function () {
5447 this.getElementWindow().addEventListener( 'keypress', this.onKeyPressHandler
, true );
5451 * Unbind key down listener.
5453 * If you override this, be sure to call this.clearKeyPressBuffer() from your
5458 OO
.ui
.SelectWidget
.prototype.unbindKeyPressListener = function () {
5459 this.getElementWindow().removeEventListener( 'keypress', this.onKeyPressHandler
, true );
5460 this.clearKeyPressBuffer();
5464 * Visibility change handler
5467 * @param {boolean} visible
5469 OO
.ui
.SelectWidget
.prototype.onToggle = function ( visible
) {
5471 this.clearKeyPressBuffer();
5476 * Get the closest item to a jQuery.Event.
5479 * @param {jQuery.Event} e
5480 * @return {OO.ui.OptionWidget|null} Outline item widget, `null` if none was found
5482 OO
.ui
.SelectWidget
.prototype.getTargetItem = function ( e
) {
5483 return $( e
.target
).closest( '.oo-ui-optionWidget' ).data( 'oo-ui-optionWidget' ) || null;
5487 * Get selected item.
5489 * @return {OO.ui.OptionWidget|null} Selected item, `null` if no item is selected
5491 OO
.ui
.SelectWidget
.prototype.getSelectedItem = function () {
5494 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5495 if ( this.items
[ i
].isSelected() ) {
5496 return this.items
[ i
];
5503 * Get highlighted item.
5505 * @return {OO.ui.OptionWidget|null} Highlighted item, `null` if no item is highlighted
5507 OO
.ui
.SelectWidget
.prototype.getHighlightedItem = function () {
5510 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5511 if ( this.items
[ i
].isHighlighted() ) {
5512 return this.items
[ i
];
5519 * Toggle pressed state.
5521 * Press is a state that occurs when a user mouses down on an item, but
5522 * has not yet let go of the mouse. The item may appear selected, but it will not be selected
5523 * until the user releases the mouse.
5525 * @param {boolean} pressed An option is being pressed
5527 OO
.ui
.SelectWidget
.prototype.togglePressed = function ( pressed
) {
5528 if ( pressed
=== undefined ) {
5529 pressed
= !this.pressed
;
5531 if ( pressed
!== this.pressed
) {
5533 .toggleClass( 'oo-ui-selectWidget-pressed', pressed
)
5534 .toggleClass( 'oo-ui-selectWidget-depressed', !pressed
);
5535 this.pressed
= pressed
;
5540 * Highlight an option. If the `item` param is omitted, no options will be highlighted
5541 * and any existing highlight will be removed. The highlight is mutually exclusive.
5543 * @param {OO.ui.OptionWidget} [item] Item to highlight, omit for no highlight
5547 OO
.ui
.SelectWidget
.prototype.highlightItem = function ( item
) {
5548 var i
, len
, highlighted
,
5551 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5552 highlighted
= this.items
[ i
] === item
;
5553 if ( this.items
[ i
].isHighlighted() !== highlighted
) {
5554 this.items
[ i
].setHighlighted( highlighted
);
5559 this.emit( 'highlight', item
);
5566 * Fetch an item by its label.
5568 * @param {string} label Label of the item to select.
5569 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
5570 * @return {OO.ui.Element|null} Item with equivalent label, `null` if none exists
5572 OO
.ui
.SelectWidget
.prototype.getItemFromLabel = function ( label
, prefix
) {
5574 len
= this.items
.length
,
5575 filter
= this.getItemMatcher( label
, true );
5577 for ( i
= 0; i
< len
; i
++ ) {
5578 item
= this.items
[ i
];
5579 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
5586 filter
= this.getItemMatcher( label
, false );
5587 for ( i
= 0; i
< len
; i
++ ) {
5588 item
= this.items
[ i
];
5589 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && filter( item
) ) {
5605 * Programmatically select an option by its label. If the item does not exist,
5606 * all options will be deselected.
5608 * @param {string} [label] Label of the item to select.
5609 * @param {boolean} [prefix=false] Allow a prefix match, if only a single item matches
5613 OO
.ui
.SelectWidget
.prototype.selectItemByLabel = function ( label
, prefix
) {
5614 var itemFromLabel
= this.getItemFromLabel( label
, !!prefix
);
5615 if ( label
=== undefined || !itemFromLabel
) {
5616 return this.selectItem();
5618 return this.selectItem( itemFromLabel
);
5622 * Programmatically select an option by its data. If the `data` parameter is omitted,
5623 * or if the item does not exist, all options will be deselected.
5625 * @param {Object|string} [data] Value of the item to select, omit to deselect all
5629 OO
.ui
.SelectWidget
.prototype.selectItemByData = function ( data
) {
5630 var itemFromData
= this.getItemFromData( data
);
5631 if ( data
=== undefined || !itemFromData
) {
5632 return this.selectItem();
5634 return this.selectItem( itemFromData
);
5638 * Programmatically select an option by its reference. If the `item` parameter is omitted,
5639 * all options will be deselected.
5641 * @param {OO.ui.OptionWidget} [item] Item to select, omit to deselect all
5645 OO
.ui
.SelectWidget
.prototype.selectItem = function ( item
) {
5646 var i
, len
, selected
,
5649 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5650 selected
= this.items
[ i
] === item
;
5651 if ( this.items
[ i
].isSelected() !== selected
) {
5652 this.items
[ i
].setSelected( selected
);
5657 this.emit( 'select', item
);
5666 * Press is a state that occurs when a user mouses down on an item, but has not
5667 * yet let go of the mouse. The item may appear selected, but it will not be selected until the user
5668 * releases the mouse.
5670 * @param {OO.ui.OptionWidget} [item] Item to press, omit to depress all
5674 OO
.ui
.SelectWidget
.prototype.pressItem = function ( item
) {
5675 var i
, len
, pressed
,
5678 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5679 pressed
= this.items
[ i
] === item
;
5680 if ( this.items
[ i
].isPressed() !== pressed
) {
5681 this.items
[ i
].setPressed( pressed
);
5686 this.emit( 'press', item
);
5695 * Note that ‘choose’ should never be modified programmatically. A user can choose
5696 * an option with the keyboard or mouse and it becomes selected. To select an item programmatically,
5697 * use the #selectItem method.
5699 * This method is identical to #selectItem, but may vary in subclasses that take additional action
5700 * when users choose an item with the keyboard or mouse.
5702 * @param {OO.ui.OptionWidget} item Item to choose
5706 OO
.ui
.SelectWidget
.prototype.chooseItem = function ( item
) {
5708 this.selectItem( item
);
5709 this.emit( 'choose', item
);
5716 * Get an option by its position relative to the specified item (or to the start of the option array,
5717 * if item is `null`). The direction in which to search through the option array is specified with a
5718 * number: -1 for reverse (the default) or 1 for forward. The method will return an option, or
5719 * `null` if there are no options in the array.
5721 * @param {OO.ui.OptionWidget|null} item Item to describe the start position, or `null` to start at the beginning of the array.
5722 * @param {number} direction Direction to move in: -1 to move backward, 1 to move forward
5723 * @param {Function} filter Only consider items for which this function returns
5724 * true. Function takes an OO.ui.OptionWidget and returns a boolean.
5725 * @return {OO.ui.OptionWidget|null} Item at position, `null` if there are no items in the select
5727 OO
.ui
.SelectWidget
.prototype.getRelativeSelectableItem = function ( item
, direction
, filter
) {
5728 var currentIndex
, nextIndex
, i
,
5729 increase
= direction
> 0 ? 1 : -1,
5730 len
= this.items
.length
;
5732 if ( !$.isFunction( filter
) ) {
5733 filter
= OO
.ui
.SelectWidget
.static.passAllFilter
;
5736 if ( item
instanceof OO
.ui
.OptionWidget
) {
5737 currentIndex
= this.items
.indexOf( item
);
5738 nextIndex
= ( currentIndex
+ increase
+ len
) % len
;
5740 // If no item is selected and moving forward, start at the beginning.
5741 // If moving backward, start at the end.
5742 nextIndex
= direction
> 0 ? 0 : len
- 1;
5745 for ( i
= 0; i
< len
; i
++ ) {
5746 item
= this.items
[ nextIndex
];
5747 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() && 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 () {
5764 for ( i
= 0, len
= this.items
.length
; i
< len
; i
++ ) {
5765 item
= this.items
[ i
];
5766 if ( item
instanceof OO
.ui
.OptionWidget
&& item
.isSelectable() ) {
5775 * Add an array of options to the select. Optionally, an index number can be used to
5776 * specify an insertion point.
5778 * @param {OO.ui.OptionWidget[]} items Items to add
5779 * @param {number} [index] Index to insert items after
5783 OO
.ui
.SelectWidget
.prototype.addItems = function ( items
, index
) {
5785 OO
.ui
.mixin
.GroupWidget
.prototype.addItems
.call( this, items
, index
);
5787 // Always provide an index, even if it was omitted
5788 this.emit( 'add', items
, index
=== undefined ? this.items
.length
- items
.length
- 1 : index
);
5794 * Remove the specified array of options from the select. Options will be detached
5795 * from the DOM, not removed, so they can be reused later. To remove all options from
5796 * the select, you may wish to use the #clearItems method instead.
5798 * @param {OO.ui.OptionWidget[]} items Items to remove
5802 OO
.ui
.SelectWidget
.prototype.removeItems = function ( items
) {
5805 // Deselect items being removed
5806 for ( i
= 0, len
= items
.length
; i
< len
; i
++ ) {
5808 if ( item
.isSelected() ) {
5809 this.selectItem( null );
5814 OO
.ui
.mixin
.GroupWidget
.prototype.removeItems
.call( this, items
);
5816 this.emit( 'remove', items
);
5822 * Clear all options from the select. Options will be detached from the DOM, not removed,
5823 * so that they can be reused later. To remove a subset of options from the select, use
5824 * the #removeItems method.
5829 OO
.ui
.SelectWidget
.prototype.clearItems = function () {
5830 var items
= this.items
.slice();
5833 OO
.ui
.mixin
.GroupWidget
.prototype.clearItems
.call( this );
5836 this.selectItem( null );
5838 this.emit( 'remove', items
);
5844 * DecoratedOptionWidgets are {@link OO.ui.OptionWidget options} that can be configured
5845 * with an {@link OO.ui.mixin.IconElement icon} and/or {@link OO.ui.mixin.IndicatorElement indicator}.
5846 * This class is used with OO.ui.SelectWidget to create a selection of mutually exclusive
5847 * options. For more information about options and selects, please see the
5848 * [OOjs UI documentation on MediaWiki][1].
5851 * // Decorated options in a select widget
5852 * var select = new OO.ui.SelectWidget( {
5854 * new OO.ui.DecoratedOptionWidget( {
5856 * label: 'Option with icon',
5859 * new OO.ui.DecoratedOptionWidget( {
5861 * label: 'Option with indicator',
5866 * $( 'body' ).append( select.$element );
5868 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
5871 * @extends OO.ui.OptionWidget
5872 * @mixins OO.ui.mixin.IconElement
5873 * @mixins OO.ui.mixin.IndicatorElement
5876 * @param {Object} [config] Configuration options
5878 OO
.ui
.DecoratedOptionWidget
= function OoUiDecoratedOptionWidget( config
) {
5879 // Parent constructor
5880 OO
.ui
.DecoratedOptionWidget
.parent
.call( this, config
);
5882 // Mixin constructors
5883 OO
.ui
.mixin
.IconElement
.call( this, config
);
5884 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
5888 .addClass( 'oo-ui-decoratedOptionWidget' )
5889 .prepend( this.$icon
)
5890 .append( this.$indicator
);
5895 OO
.inheritClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.OptionWidget
);
5896 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IconElement
);
5897 OO
.mixinClass( OO
.ui
.DecoratedOptionWidget
, OO
.ui
.mixin
.IndicatorElement
);
5900 * MenuOptionWidget is an option widget that looks like a menu item. The class is used with
5901 * OO.ui.MenuSelectWidget to create a menu of mutually exclusive options. Please see
5902 * the [OOjs UI documentation on MediaWiki] [1] for more information.
5904 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
5907 * @extends OO.ui.DecoratedOptionWidget
5910 * @param {Object} [config] Configuration options
5912 OO
.ui
.MenuOptionWidget
= function OoUiMenuOptionWidget( config
) {
5913 // Configuration initialization
5914 config
= $.extend( { icon
: 'check' }, config
);
5916 // Parent constructor
5917 OO
.ui
.MenuOptionWidget
.parent
.call( this, config
);
5921 .attr( 'role', 'menuitem' )
5922 .addClass( 'oo-ui-menuOptionWidget' );
5927 OO
.inheritClass( OO
.ui
.MenuOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
5929 /* Static Properties */
5931 OO
.ui
.MenuOptionWidget
.static.scrollIntoViewOnSelect
= true;
5934 * MenuSectionOptionWidgets are used inside {@link OO.ui.MenuSelectWidget menu select widgets} to group one or more related
5935 * {@link OO.ui.MenuOptionWidget menu options}. MenuSectionOptionWidgets cannot be highlighted or selected.
5938 * var myDropdown = new OO.ui.DropdownWidget( {
5941 * new OO.ui.MenuSectionOptionWidget( {
5944 * new OO.ui.MenuOptionWidget( {
5946 * label: 'Welsh Corgi'
5948 * new OO.ui.MenuOptionWidget( {
5950 * label: 'Standard Poodle'
5952 * new OO.ui.MenuSectionOptionWidget( {
5955 * new OO.ui.MenuOptionWidget( {
5962 * $( 'body' ).append( myDropdown.$element );
5965 * @extends OO.ui.DecoratedOptionWidget
5968 * @param {Object} [config] Configuration options
5970 OO
.ui
.MenuSectionOptionWidget
= function OoUiMenuSectionOptionWidget( config
) {
5971 // Parent constructor
5972 OO
.ui
.MenuSectionOptionWidget
.parent
.call( this, config
);
5975 this.$element
.addClass( 'oo-ui-menuSectionOptionWidget' );
5980 OO
.inheritClass( OO
.ui
.MenuSectionOptionWidget
, OO
.ui
.DecoratedOptionWidget
);
5982 /* Static Properties */
5984 OO
.ui
.MenuSectionOptionWidget
.static.selectable
= false;
5986 OO
.ui
.MenuSectionOptionWidget
.static.highlightable
= false;
5989 * MenuSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains options and
5990 * is used together with OO.ui.MenuOptionWidget. It is designed be used as part of another widget.
5991 * See {@link OO.ui.DropdownWidget DropdownWidget}, {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget},
5992 * and {@link OO.ui.mixin.LookupElement LookupElement} for examples of widgets that contain menus.
5993 * MenuSelectWidgets themselves are not instantiated directly, rather subclassed
5994 * and customized to be opened, closed, and displayed as needed.
5996 * By default, menus are clipped to the visible viewport and are not visible when a user presses the
5997 * mouse outside the menu.
5999 * Menus also have support for keyboard interaction:
6001 * - Enter/Return key: choose and select a menu option
6002 * - Up-arrow key: highlight the previous menu option
6003 * - Down-arrow key: highlight the next menu option
6004 * - Esc key: hide the menu
6006 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
6007 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6010 * @extends OO.ui.SelectWidget
6011 * @mixins OO.ui.mixin.ClippableElement
6014 * @param {Object} [config] Configuration options
6015 * @cfg {OO.ui.TextInputWidget} [input] Text input used to implement option highlighting for menu items that match
6016 * the text the user types. This config is used by {@link OO.ui.ComboBoxInputWidget ComboBoxInputWidget}
6017 * and {@link OO.ui.mixin.LookupElement LookupElement}
6018 * @cfg {jQuery} [$input] Text input used to implement option highlighting for menu items that match
6019 * the text the user types. This config is used by {@link OO.ui.CapsuleMultiselectWidget CapsuleMultiselectWidget}
6020 * @cfg {OO.ui.Widget} [widget] Widget associated with the menu's active state. If the user clicks the mouse
6021 * anywhere on the page outside of this widget, the menu is hidden. For example, if there is a button
6022 * that toggles the menu's visibility on click, the menu will be hidden then re-shown when the user clicks
6023 * that button, unless the button (or its parent widget) is passed in here.
6024 * @cfg {boolean} [autoHide=true] Hide the menu when the mouse is pressed outside the menu.
6025 * @cfg {boolean} [filterFromInput=false] Filter the displayed options from the input
6027 OO
.ui
.MenuSelectWidget
= function OoUiMenuSelectWidget( config
) {
6028 // Configuration initialization
6029 config
= config
|| {};
6031 // Parent constructor
6032 OO
.ui
.MenuSelectWidget
.parent
.call( this, config
);
6034 // Mixin constructors
6035 OO
.ui
.mixin
.ClippableElement
.call( this, $.extend( {}, config
, { $clippable
: this.$group
} ) );
6038 this.autoHide
= config
.autoHide
=== undefined || !!config
.autoHide
;
6039 this.filterFromInput
= !!config
.filterFromInput
;
6040 this.$input
= config
.$input
? config
.$input
: config
.input
? config
.input
.$input
: null;
6041 this.$widget
= config
.widget
? config
.widget
.$element
: null;
6042 this.onDocumentMouseDownHandler
= this.onDocumentMouseDown
.bind( this );
6043 this.onInputEditHandler
= OO
.ui
.debounce( this.updateItemVisibility
.bind( this ), 100 );
6047 .addClass( 'oo-ui-menuSelectWidget' )
6048 .attr( 'role', 'menu' );
6050 // Initially hidden - using #toggle may cause errors if subclasses override toggle with methods
6051 // that reference properties not initialized at that time of parent class construction
6052 // TODO: Find a better way to handle post-constructor setup
6053 this.visible
= false;
6054 this.$element
.addClass( 'oo-ui-element-hidden' );
6059 OO
.inheritClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.SelectWidget
);
6060 OO
.mixinClass( OO
.ui
.MenuSelectWidget
, OO
.ui
.mixin
.ClippableElement
);
6065 * Handles document mouse down events.
6068 * @param {MouseEvent} e Mouse down event
6070 OO
.ui
.MenuSelectWidget
.prototype.onDocumentMouseDown = function ( e
) {
6072 !OO
.ui
.contains( this.$element
[ 0 ], e
.target
, true ) &&
6073 ( !this.$widget
|| !OO
.ui
.contains( this.$widget
[ 0 ], e
.target
, true ) )
6075 this.toggle( false );
6082 OO
.ui
.MenuSelectWidget
.prototype.onKeyDown = function ( e
) {
6083 var currentItem
= this.getHighlightedItem() || this.getSelectedItem();
6085 if ( !this.isDisabled() && this.isVisible() ) {
6086 switch ( e
.keyCode
) {
6087 case OO
.ui
.Keys
.LEFT
:
6088 case OO
.ui
.Keys
.RIGHT
:
6089 // Do nothing if a text field is associated, arrow keys will be handled natively
6090 if ( !this.$input
) {
6091 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
6094 case OO
.ui
.Keys
.ESCAPE
:
6095 case OO
.ui
.Keys
.TAB
:
6096 if ( currentItem
) {
6097 currentItem
.setHighlighted( false );
6099 this.toggle( false );
6100 // Don't prevent tabbing away, prevent defocusing
6101 if ( e
.keyCode
=== OO
.ui
.Keys
.ESCAPE
) {
6103 e
.stopPropagation();
6107 OO
.ui
.MenuSelectWidget
.parent
.prototype.onKeyDown
.call( this, e
);
6114 * Update menu item visibility after input changes.
6118 OO
.ui
.MenuSelectWidget
.prototype.updateItemVisibility = function () {
6120 len
= this.items
.length
,
6121 showAll
= !this.isVisible(),
6122 filter
= showAll
? null : this.getItemMatcher( this.$input
.val() );
6124 for ( i
= 0; i
< len
; i
++ ) {
6125 item
= this.items
[ i
];
6126 if ( item
instanceof OO
.ui
.OptionWidget
) {
6127 item
.toggle( showAll
|| filter( item
) );
6131 // Reevaluate clipping
6138 OO
.ui
.MenuSelectWidget
.prototype.bindKeyDownListener = function () {
6139 if ( this.$input
) {
6140 this.$input
.on( 'keydown', this.onKeyDownHandler
);
6142 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyDownListener
.call( this );
6149 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyDownListener = function () {
6150 if ( this.$input
) {
6151 this.$input
.off( 'keydown', this.onKeyDownHandler
);
6153 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyDownListener
.call( this );
6160 OO
.ui
.MenuSelectWidget
.prototype.bindKeyPressListener = function () {
6161 if ( this.$input
) {
6162 if ( this.filterFromInput
) {
6163 this.$input
.on( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
6166 OO
.ui
.MenuSelectWidget
.parent
.prototype.bindKeyPressListener
.call( this );
6173 OO
.ui
.MenuSelectWidget
.prototype.unbindKeyPressListener = function () {
6174 if ( this.$input
) {
6175 if ( this.filterFromInput
) {
6176 this.$input
.off( 'keydown mouseup cut paste change input select', this.onInputEditHandler
);
6177 this.updateItemVisibility();
6180 OO
.ui
.MenuSelectWidget
.parent
.prototype.unbindKeyPressListener
.call( this );
6187 * When a user chooses an item, the menu is closed.
6189 * Note that ‘choose’ should never be modified programmatically. A user can choose an option with the keyboard
6190 * or mouse and it becomes selected. To select an item programmatically, use the #selectItem method.
6192 * @param {OO.ui.OptionWidget} item Item to choose
6195 OO
.ui
.MenuSelectWidget
.prototype.chooseItem = function ( item
) {
6196 OO
.ui
.MenuSelectWidget
.parent
.prototype.chooseItem
.call( this, item
);
6197 this.toggle( false );
6204 OO
.ui
.MenuSelectWidget
.prototype.addItems = function ( items
, index
) {
6206 OO
.ui
.MenuSelectWidget
.parent
.prototype.addItems
.call( this, items
, index
);
6208 // Reevaluate clipping
6217 OO
.ui
.MenuSelectWidget
.prototype.removeItems = function ( items
) {
6219 OO
.ui
.MenuSelectWidget
.parent
.prototype.removeItems
.call( this, items
);
6221 // Reevaluate clipping
6230 OO
.ui
.MenuSelectWidget
.prototype.clearItems = function () {
6232 OO
.ui
.MenuSelectWidget
.parent
.prototype.clearItems
.call( this );
6234 // Reevaluate clipping
6243 OO
.ui
.MenuSelectWidget
.prototype.toggle = function ( visible
) {
6246 visible
= ( visible
=== undefined ? !this.visible
: !!visible
) && !!this.items
.length
;
6247 change
= visible
!== this.isVisible();
6250 OO
.ui
.MenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
6254 this.bindKeyDownListener();
6255 this.bindKeyPressListener();
6257 this.toggleClipping( true );
6259 if ( this.getSelectedItem() ) {
6260 this.getSelectedItem().scrollElementIntoView( { duration
: 0 } );
6264 if ( this.autoHide
) {
6265 this.getElementDocument().addEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
6268 this.unbindKeyDownListener();
6269 this.unbindKeyPressListener();
6270 this.getElementDocument().removeEventListener( 'mousedown', this.onDocumentMouseDownHandler
, true );
6271 this.toggleClipping( false );
6279 * DropdownWidgets are not menus themselves, rather they contain a menu of options created with
6280 * OO.ui.MenuOptionWidget. The DropdownWidget takes care of opening and displaying the menu so that
6281 * users can interact with it.
6283 * If you want to use this within a HTML form, such as a OO.ui.FormLayout, use
6284 * OO.ui.DropdownInputWidget instead.
6287 * // Example: A DropdownWidget with a menu that contains three options
6288 * var dropDown = new OO.ui.DropdownWidget( {
6289 * label: 'Dropdown menu: Select a menu option',
6292 * new OO.ui.MenuOptionWidget( {
6296 * new OO.ui.MenuOptionWidget( {
6300 * new OO.ui.MenuOptionWidget( {
6308 * $( 'body' ).append( dropDown.$element );
6310 * dropDown.getMenu().selectItemByData( 'b' );
6312 * dropDown.getMenu().getSelectedItem().getData(); // returns 'b'
6314 * For more information, please see the [OOjs UI documentation on MediaWiki] [1].
6316 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
6319 * @extends OO.ui.Widget
6320 * @mixins OO.ui.mixin.IconElement
6321 * @mixins OO.ui.mixin.IndicatorElement
6322 * @mixins OO.ui.mixin.LabelElement
6323 * @mixins OO.ui.mixin.TitledElement
6324 * @mixins OO.ui.mixin.TabIndexedElement
6327 * @param {Object} [config] Configuration options
6328 * @cfg {Object} [menu] Configuration options to pass to {@link OO.ui.FloatingMenuSelectWidget menu select widget}
6329 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
6330 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
6331 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
6333 OO
.ui
.DropdownWidget
= function OoUiDropdownWidget( config
) {
6334 // Configuration initialization
6335 config
= $.extend( { indicator
: 'down' }, config
);
6337 // Parent constructor
6338 OO
.ui
.DropdownWidget
.parent
.call( this, config
);
6340 // Properties (must be set before TabIndexedElement constructor call)
6341 this.$handle
= this.$( '<span>' );
6342 this.$overlay
= config
.$overlay
|| this.$element
;
6344 // Mixin constructors
6345 OO
.ui
.mixin
.IconElement
.call( this, config
);
6346 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
6347 OO
.ui
.mixin
.LabelElement
.call( this, config
);
6348 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
6349 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$handle
} ) );
6352 this.menu
= new OO
.ui
.FloatingMenuSelectWidget( $.extend( {
6354 $container
: this.$element
6359 click
: this.onClick
.bind( this ),
6360 keydown
: this.onKeyDown
.bind( this )
6362 this.menu
.connect( this, { select
: 'onMenuSelect' } );
6366 .addClass( 'oo-ui-dropdownWidget-handle' )
6367 .append( this.$icon
, this.$label
, this.$indicator
);
6369 .addClass( 'oo-ui-dropdownWidget' )
6370 .append( this.$handle
);
6371 this.$overlay
.append( this.menu
.$element
);
6376 OO
.inheritClass( OO
.ui
.DropdownWidget
, OO
.ui
.Widget
);
6377 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IconElement
);
6378 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.IndicatorElement
);
6379 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.LabelElement
);
6380 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TitledElement
);
6381 OO
.mixinClass( OO
.ui
.DropdownWidget
, OO
.ui
.mixin
.TabIndexedElement
);
6388 * @return {OO.ui.MenuSelectWidget} Menu of widget
6390 OO
.ui
.DropdownWidget
.prototype.getMenu = function () {
6395 * Handles menu select events.
6398 * @param {OO.ui.MenuOptionWidget} item Selected menu item
6400 OO
.ui
.DropdownWidget
.prototype.onMenuSelect = function ( item
) {
6404 this.setLabel( null );
6408 selectedLabel
= item
.getLabel();
6410 // If the label is a DOM element, clone it, because setLabel will append() it
6411 if ( selectedLabel
instanceof jQuery
) {
6412 selectedLabel
= selectedLabel
.clone();
6415 this.setLabel( selectedLabel
);
6419 * Handle mouse click events.
6422 * @param {jQuery.Event} e Mouse click event
6424 OO
.ui
.DropdownWidget
.prototype.onClick = function ( e
) {
6425 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
6432 * Handle key down events.
6435 * @param {jQuery.Event} e Key down event
6437 OO
.ui
.DropdownWidget
.prototype.onKeyDown = function ( e
) {
6439 !this.isDisabled() &&
6441 e
.which
=== OO
.ui
.Keys
.ENTER
||
6443 !this.menu
.isVisible() &&
6445 e
.which
=== OO
.ui
.Keys
.SPACE
||
6446 e
.which
=== OO
.ui
.Keys
.UP
||
6447 e
.which
=== OO
.ui
.Keys
.DOWN
6458 * RadioOptionWidget is an option widget that looks like a radio button.
6459 * The class is used with OO.ui.RadioSelectWidget to create a selection of radio options.
6460 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information.
6462 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Button_selects_and_option
6465 * @extends OO.ui.OptionWidget
6468 * @param {Object} [config] Configuration options
6470 OO
.ui
.RadioOptionWidget
= function OoUiRadioOptionWidget( config
) {
6471 // Configuration initialization
6472 config
= config
|| {};
6474 // Properties (must be done before parent constructor which calls #setDisabled)
6475 this.radio
= new OO
.ui
.RadioInputWidget( { value
: config
.data
, tabIndex
: -1 } );
6477 // Parent constructor
6478 OO
.ui
.RadioOptionWidget
.parent
.call( this, config
);
6481 // Remove implicit role, we're handling it ourselves
6482 this.radio
.$input
.attr( 'role', 'presentation' );
6484 .addClass( 'oo-ui-radioOptionWidget' )
6485 .attr( 'role', 'radio' )
6486 .attr( 'aria-checked', 'false' )
6487 .removeAttr( 'aria-selected' )
6488 .prepend( this.radio
.$element
);
6493 OO
.inheritClass( OO
.ui
.RadioOptionWidget
, OO
.ui
.OptionWidget
);
6495 /* Static Properties */
6497 OO
.ui
.RadioOptionWidget
.static.highlightable
= false;
6499 OO
.ui
.RadioOptionWidget
.static.scrollIntoViewOnSelect
= true;
6501 OO
.ui
.RadioOptionWidget
.static.pressable
= false;
6503 OO
.ui
.RadioOptionWidget
.static.tagName
= 'label';
6510 OO
.ui
.RadioOptionWidget
.prototype.setSelected = function ( state
) {
6511 OO
.ui
.RadioOptionWidget
.parent
.prototype.setSelected
.call( this, state
);
6513 this.radio
.setSelected( state
);
6515 .attr( 'aria-checked', state
.toString() )
6516 .removeAttr( 'aria-selected' );
6524 OO
.ui
.RadioOptionWidget
.prototype.setDisabled = function ( disabled
) {
6525 OO
.ui
.RadioOptionWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
6527 this.radio
.setDisabled( this.isDisabled() );
6533 * RadioSelectWidget is a {@link OO.ui.SelectWidget select widget} that contains radio
6534 * options and is used together with OO.ui.RadioOptionWidget. The RadioSelectWidget provides
6535 * an interface for adding, removing and selecting options.
6536 * Please see the [OOjs UI documentation on MediaWiki][1] for more information.
6538 * If you want to use this within a HTML form, such as a OO.ui.FormLayout, use
6539 * OO.ui.RadioSelectInputWidget instead.
6542 * // A RadioSelectWidget with RadioOptions.
6543 * var option1 = new OO.ui.RadioOptionWidget( {
6545 * label: 'Selected radio option'
6548 * var option2 = new OO.ui.RadioOptionWidget( {
6550 * label: 'Unselected radio option'
6553 * var radioSelect=new OO.ui.RadioSelectWidget( {
6554 * items: [ option1, option2 ]
6557 * // Select 'option 1' using the RadioSelectWidget's selectItem() method.
6558 * radioSelect.selectItem( option1 );
6560 * $( 'body' ).append( radioSelect.$element );
6562 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options
6566 * @extends OO.ui.SelectWidget
6567 * @mixins OO.ui.mixin.TabIndexedElement
6570 * @param {Object} [config] Configuration options
6572 OO
.ui
.RadioSelectWidget
= function OoUiRadioSelectWidget( config
) {
6573 // Parent constructor
6574 OO
.ui
.RadioSelectWidget
.parent
.call( this, config
);
6576 // Mixin constructors
6577 OO
.ui
.mixin
.TabIndexedElement
.call( this, config
);
6581 focus
: this.bindKeyDownListener
.bind( this ),
6582 blur
: this.unbindKeyDownListener
.bind( this )
6587 .addClass( 'oo-ui-radioSelectWidget' )
6588 .attr( 'role', 'radiogroup' );
6593 OO
.inheritClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.SelectWidget
);
6594 OO
.mixinClass( OO
.ui
.RadioSelectWidget
, OO
.ui
.mixin
.TabIndexedElement
);
6597 * Element that will stick under a specified container, even when it is inserted elsewhere in the
6598 * document (for example, in a OO.ui.Window's $overlay).
6600 * The elements's position is automatically calculated and maintained when window is resized or the
6601 * page is scrolled. If you reposition the container manually, you have to call #position to make
6602 * sure the element is still placed correctly.
6604 * As positioning is only possible when both the element and the container are attached to the DOM
6605 * and visible, it's only done after you call #togglePositioning. You might want to do this inside
6606 * the #toggle method to display a floating popup, for example.
6612 * @param {Object} [config] Configuration options
6613 * @cfg {jQuery} [$floatable] Node to position, assigned to #$floatable, omit to use #$element
6614 * @cfg {jQuery} [$floatableContainer] Node to position below
6616 OO
.ui
.mixin
.FloatableElement
= function OoUiMixinFloatableElement( config
) {
6617 // Configuration initialization
6618 config
= config
|| {};
6621 this.$floatable
= null;
6622 this.$floatableContainer
= null;
6623 this.$floatableWindow
= null;
6624 this.$floatableClosestScrollable
= null;
6625 this.onFloatableScrollHandler
= this.position
.bind( this );
6626 this.onFloatableWindowResizeHandler
= this.position
.bind( this );
6629 this.setFloatableContainer( config
.$floatableContainer
);
6630 this.setFloatableElement( config
.$floatable
|| this.$element
);
6636 * Set floatable element.
6638 * If an element is already set, it will be cleaned up before setting up the new element.
6640 * @param {jQuery} $floatable Element to make floatable
6642 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableElement = function ( $floatable
) {
6643 if ( this.$floatable
) {
6644 this.$floatable
.removeClass( 'oo-ui-floatableElement-floatable' );
6645 this.$floatable
.css( { left
: '', top
: '' } );
6648 this.$floatable
= $floatable
.addClass( 'oo-ui-floatableElement-floatable' );
6653 * Set floatable container.
6655 * The element will be always positioned under the specified container.
6657 * @param {jQuery|null} $floatableContainer Container to keep visible, or null to unset
6659 OO
.ui
.mixin
.FloatableElement
.prototype.setFloatableContainer = function ( $floatableContainer
) {
6660 this.$floatableContainer
= $floatableContainer
;
6661 if ( this.$floatable
) {
6667 * Toggle positioning.
6669 * Do not turn positioning on until after the element is attached to the DOM and visible.
6671 * @param {boolean} [positioning] Enable positioning, omit to toggle
6674 OO
.ui
.mixin
.FloatableElement
.prototype.togglePositioning = function ( positioning
) {
6675 var closestScrollableOfContainer
, closestScrollableOfFloatable
;
6677 positioning
= positioning
=== undefined ? !this.positioning
: !!positioning
;
6679 if ( this.positioning
!== positioning
) {
6680 this.positioning
= positioning
;
6682 closestScrollableOfContainer
= OO
.ui
.Element
.static.getClosestScrollableContainer( this.$floatableContainer
[ 0 ] );
6683 closestScrollableOfFloatable
= OO
.ui
.Element
.static.getClosestScrollableContainer( this.$floatable
[ 0 ] );
6684 this.needsCustomPosition
= closestScrollableOfContainer
!== closestScrollableOfFloatable
;
6685 // If the scrollable is the root, we have to listen to scroll events
6686 // on the window because of browser inconsistencies.
6687 if ( $( closestScrollableOfContainer
).is( 'html, body' ) ) {
6688 closestScrollableOfContainer
= OO
.ui
.Element
.static.getWindow( closestScrollableOfContainer
);
6691 if ( positioning
) {
6692 this.$floatableWindow
= $( this.getElementWindow() );
6693 this.$floatableWindow
.on( 'resize', this.onFloatableWindowResizeHandler
);
6695 this.$floatableClosestScrollable
= $( closestScrollableOfContainer
);
6696 this.$floatableClosestScrollable
.on( 'scroll', this.onFloatableScrollHandler
);
6698 // Initial position after visible
6701 if ( this.$floatableWindow
) {
6702 this.$floatableWindow
.off( 'resize', this.onFloatableWindowResizeHandler
);
6703 this.$floatableWindow
= null;
6706 if ( this.$floatableClosestScrollable
) {
6707 this.$floatableClosestScrollable
.off( 'scroll', this.onFloatableScrollHandler
);
6708 this.$floatableClosestScrollable
= null;
6711 this.$floatable
.css( { left
: '', top
: '' } );
6719 * Check whether the bottom edge of the given element is within the viewport of the given container.
6722 * @param {jQuery} $element
6723 * @param {jQuery} $container
6726 OO
.ui
.mixin
.FloatableElement
.prototype.isElementInViewport = function ( $element
, $container
) {
6727 var elemRect
, contRect
,
6728 topEdgeInBounds
= false,
6729 leftEdgeInBounds
= false,
6730 bottomEdgeInBounds
= false,
6731 rightEdgeInBounds
= false;
6733 elemRect
= $element
[ 0 ].getBoundingClientRect();
6734 if ( $container
[ 0 ] === window
) {
6738 right
: document
.documentElement
.clientWidth
,
6739 bottom
: document
.documentElement
.clientHeight
6742 contRect
= $container
[ 0 ].getBoundingClientRect();
6745 if ( elemRect
.top
>= contRect
.top
&& elemRect
.top
<= contRect
.bottom
) {
6746 topEdgeInBounds
= true;
6748 if ( elemRect
.left
>= contRect
.left
&& elemRect
.left
<= contRect
.right
) {
6749 leftEdgeInBounds
= true;
6751 if ( elemRect
.bottom
>= contRect
.top
&& elemRect
.bottom
<= contRect
.bottom
) {
6752 bottomEdgeInBounds
= true;
6754 if ( elemRect
.right
>= contRect
.left
&& elemRect
.right
<= contRect
.right
) {
6755 rightEdgeInBounds
= true;
6758 // We only care that any part of the bottom edge is visible
6759 return bottomEdgeInBounds
&& ( leftEdgeInBounds
|| rightEdgeInBounds
);
6763 * Position the floatable below its container.
6765 * This should only be done when both of them are attached to the DOM and visible.
6769 OO
.ui
.mixin
.FloatableElement
.prototype.position = function () {
6772 if ( !this.positioning
) {
6776 if ( !this.isElementInViewport( this.$floatableContainer
, this.$floatableClosestScrollable
) ) {
6777 this.$floatable
.addClass( 'oo-ui-floatableElement-hidden' );
6780 this.$floatable
.removeClass( 'oo-ui-floatableElement-hidden' );
6783 if ( !this.needsCustomPosition
) {
6787 pos
= OO
.ui
.Element
.static.getRelativePosition( this.$floatableContainer
, this.$floatable
.offsetParent() );
6789 // Position under container
6790 pos
.top
+= this.$floatableContainer
.height();
6791 this.$floatable
.css( pos
);
6793 // We updated the position, so re-evaluate the clipping state.
6794 // (ClippableElement does not listen to 'scroll' events on $floatableContainer's parent, and so
6795 // will not notice the need to update itself.)
6796 // TODO: This is terrible, we shouldn't need to know about ClippableElement at all here. Why does
6797 // it not listen to the right events in the right places?
6806 * FloatingMenuSelectWidget is a menu that will stick under a specified
6807 * container, even when it is inserted elsewhere in the document (for example,
6808 * in a OO.ui.Window's $overlay). This is sometimes necessary to prevent the
6809 * menu from being clipped too aggresively.
6811 * The menu's position is automatically calculated and maintained when the menu
6812 * is toggled or the window is resized.
6814 * See OO.ui.ComboBoxInputWidget for an example of a widget that uses this class.
6817 * @extends OO.ui.MenuSelectWidget
6818 * @mixins OO.ui.mixin.FloatableElement
6821 * @param {OO.ui.Widget} [inputWidget] Widget to provide the menu for.
6822 * Deprecated, omit this parameter and specify `$container` instead.
6823 * @param {Object} [config] Configuration options
6824 * @cfg {jQuery} [$container=inputWidget.$element] Element to render menu under
6826 OO
.ui
.FloatingMenuSelectWidget
= function OoUiFloatingMenuSelectWidget( inputWidget
, config
) {
6827 // Allow 'inputWidget' parameter and config for backwards compatibility
6828 if ( OO
.isPlainObject( inputWidget
) && config
=== undefined ) {
6829 config
= inputWidget
;
6830 inputWidget
= config
.inputWidget
;
6833 // Configuration initialization
6834 config
= config
|| {};
6836 // Parent constructor
6837 OO
.ui
.FloatingMenuSelectWidget
.parent
.call( this, config
);
6839 // Properties (must be set before mixin constructors)
6840 this.inputWidget
= inputWidget
; // For backwards compatibility
6841 this.$container
= config
.$container
|| this.inputWidget
.$element
;
6843 // Mixins constructors
6844 OO
.ui
.mixin
.FloatableElement
.call( this, $.extend( {}, config
, { $floatableContainer
: this.$container
} ) );
6847 this.$element
.addClass( 'oo-ui-floatingMenuSelectWidget' );
6848 // For backwards compatibility
6849 this.$element
.addClass( 'oo-ui-textInputMenuSelectWidget' );
6854 OO
.inheritClass( OO
.ui
.FloatingMenuSelectWidget
, OO
.ui
.MenuSelectWidget
);
6855 OO
.mixinClass( OO
.ui
.FloatingMenuSelectWidget
, OO
.ui
.mixin
.FloatableElement
);
6857 // For backwards compatibility
6858 OO
.ui
.TextInputMenuSelectWidget
= OO
.ui
.FloatingMenuSelectWidget
;
6865 OO
.ui
.FloatingMenuSelectWidget
.prototype.toggle = function ( visible
) {
6867 visible
= visible
=== undefined ? !this.isVisible() : !!visible
;
6868 change
= visible
!== this.isVisible();
6870 if ( change
&& visible
) {
6871 // Make sure the width is set before the parent method runs.
6872 this.setIdealSize( this.$container
.width() );
6876 // This will call this.clip(), which is nonsensical since we're not positioned yet...
6877 OO
.ui
.FloatingMenuSelectWidget
.parent
.prototype.toggle
.call( this, visible
);
6880 this.togglePositioning( this.isVisible() );
6887 * InputWidget is the base class for all input widgets, which
6888 * include {@link OO.ui.TextInputWidget text inputs}, {@link OO.ui.CheckboxInputWidget checkbox inputs},
6889 * {@link OO.ui.RadioInputWidget radio inputs}, and {@link OO.ui.ButtonInputWidget button inputs}.
6890 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
6892 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
6896 * @extends OO.ui.Widget
6897 * @mixins OO.ui.mixin.FlaggedElement
6898 * @mixins OO.ui.mixin.TabIndexedElement
6899 * @mixins OO.ui.mixin.TitledElement
6900 * @mixins OO.ui.mixin.AccessKeyedElement
6903 * @param {Object} [config] Configuration options
6904 * @cfg {string} [name=''] The value of the input’s HTML `name` attribute.
6905 * @cfg {string} [value=''] The value of the input.
6906 * @cfg {string} [dir] The directionality of the input (ltr/rtl).
6907 * @cfg {Function} [inputFilter] The name of an input filter function. Input filters modify the value of an input
6908 * before it is accepted.
6910 OO
.ui
.InputWidget
= function OoUiInputWidget( config
) {
6911 // Configuration initialization
6912 config
= config
|| {};
6914 // Parent constructor
6915 OO
.ui
.InputWidget
.parent
.call( this, config
);
6918 // See #reusePreInfuseDOM about config.$input
6919 this.$input
= config
.$input
|| this.getInputElement( config
);
6921 this.inputFilter
= config
.inputFilter
;
6923 // Mixin constructors
6924 OO
.ui
.mixin
.FlaggedElement
.call( this, config
);
6925 OO
.ui
.mixin
.TabIndexedElement
.call( this, $.extend( {}, config
, { $tabIndexed
: this.$input
} ) );
6926 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
6927 OO
.ui
.mixin
.AccessKeyedElement
.call( this, $.extend( {}, config
, { $accessKeyed
: this.$input
} ) );
6930 this.$input
.on( 'keydown mouseup cut paste change input select', this.onEdit
.bind( this ) );
6934 .addClass( 'oo-ui-inputWidget-input' )
6935 .attr( 'name', config
.name
)
6936 .prop( 'disabled', this.isDisabled() );
6938 .addClass( 'oo-ui-inputWidget' )
6939 .append( this.$input
);
6940 this.setValue( config
.value
);
6942 this.setDir( config
.dir
);
6948 OO
.inheritClass( OO
.ui
.InputWidget
, OO
.ui
.Widget
);
6949 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.FlaggedElement
);
6950 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TabIndexedElement
);
6951 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.TitledElement
);
6952 OO
.mixinClass( OO
.ui
.InputWidget
, OO
.ui
.mixin
.AccessKeyedElement
);
6954 /* Static Properties */
6956 OO
.ui
.InputWidget
.static.supportsSimpleLabel
= true;
6958 /* Static Methods */
6963 OO
.ui
.InputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
6964 config
= OO
.ui
.InputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
6965 // Reusing $input lets browsers preserve inputted values across page reloads (T114134)
6966 config
.$input
= $( node
).find( '.oo-ui-inputWidget-input' );
6973 OO
.ui
.InputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
6974 var state
= OO
.ui
.InputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
6975 if ( config
.$input
&& config
.$input
.length
) {
6976 state
.value
= config
.$input
.val();
6977 // Might be better in TabIndexedElement, but it's awkward to do there because mixins are awkward
6978 state
.focus
= config
.$input
.is( ':focus' );
6988 * A change event is emitted when the value of the input changes.
6990 * @param {string} value
6996 * Get input element.
6998 * Subclasses of OO.ui.InputWidget use the `config` parameter to produce different elements in
6999 * different circumstances. The element must have a `value` property (like form elements).
7002 * @param {Object} config Configuration options
7003 * @return {jQuery} Input element
7005 OO
.ui
.InputWidget
.prototype.getInputElement = function () {
7006 return $( '<input>' );
7010 * Handle potentially value-changing events.
7013 * @param {jQuery.Event} e Key down, mouse up, cut, paste, change, input, or select event
7015 OO
.ui
.InputWidget
.prototype.onEdit = function () {
7017 if ( !this.isDisabled() ) {
7018 // Allow the stack to clear so the value will be updated
7019 setTimeout( function () {
7020 widget
.setValue( widget
.$input
.val() );
7026 * Get the value of the input.
7028 * @return {string} Input value
7030 OO
.ui
.InputWidget
.prototype.getValue = function () {
7031 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
7032 // it, and we won't know unless they're kind enough to trigger a 'change' event.
7033 var value
= this.$input
.val();
7034 if ( this.value
!== value
) {
7035 this.setValue( value
);
7041 * Set the directionality of the input, either RTL (right-to-left) or LTR (left-to-right).
7043 * @deprecated since v0.13.1; use #setDir directly
7044 * @param {boolean} isRTL Directionality is right-to-left
7047 OO
.ui
.InputWidget
.prototype.setRTL = function ( isRTL
) {
7048 this.setDir( isRTL
? 'rtl' : 'ltr' );
7053 * Set the directionality of the input.
7055 * @param {string} dir Text directionality: 'ltr', 'rtl' or 'auto'
7058 OO
.ui
.InputWidget
.prototype.setDir = function ( dir
) {
7059 this.$input
.prop( 'dir', dir
);
7064 * Set the value of the input.
7066 * @param {string} value New value
7070 OO
.ui
.InputWidget
.prototype.setValue = function ( value
) {
7071 value
= this.cleanUpValue( value
);
7072 // Update the DOM if it has changed. Note that with cleanUpValue, it
7073 // is possible for the DOM value to change without this.value changing.
7074 if ( this.$input
.val() !== value
) {
7075 this.$input
.val( value
);
7077 if ( this.value
!== value
) {
7079 this.emit( 'change', this.value
);
7085 * Clean up incoming value.
7087 * Ensures value is a string, and converts undefined and null to empty string.
7090 * @param {string} value Original value
7091 * @return {string} Cleaned up value
7093 OO
.ui
.InputWidget
.prototype.cleanUpValue = function ( value
) {
7094 if ( value
=== undefined || value
=== null ) {
7096 } else if ( this.inputFilter
) {
7097 return this.inputFilter( String( value
) );
7099 return String( value
);
7104 * Simulate the behavior of clicking on a label bound to this input. This method is only called by
7105 * {@link OO.ui.LabelWidget LabelWidget} and {@link OO.ui.FieldLayout FieldLayout}. It should not be
7108 OO
.ui
.InputWidget
.prototype.simulateLabelClick = function () {
7109 if ( !this.isDisabled() ) {
7110 if ( this.$input
.is( ':checkbox, :radio' ) ) {
7111 this.$input
.click();
7113 if ( this.$input
.is( ':input' ) ) {
7114 this.$input
[ 0 ].focus();
7122 OO
.ui
.InputWidget
.prototype.setDisabled = function ( state
) {
7123 OO
.ui
.InputWidget
.parent
.prototype.setDisabled
.call( this, state
);
7124 if ( this.$input
) {
7125 this.$input
.prop( 'disabled', this.isDisabled() );
7135 OO
.ui
.InputWidget
.prototype.focus = function () {
7136 this.$input
[ 0 ].focus();
7145 OO
.ui
.InputWidget
.prototype.blur = function () {
7146 this.$input
[ 0 ].blur();
7153 OO
.ui
.InputWidget
.prototype.restorePreInfuseState = function ( state
) {
7154 OO
.ui
.InputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
7155 if ( state
.value
!== undefined && state
.value
!== this.getValue() ) {
7156 this.setValue( state
.value
);
7158 if ( state
.focus
) {
7164 * ButtonInputWidget is used to submit HTML forms and is intended to be used within
7165 * a OO.ui.FormLayout. If you do not need the button to work with HTML forms, you probably
7166 * want to use OO.ui.ButtonWidget instead. Button input widgets can be rendered as either an
7167 * HTML `<button/>` (the default) or an HTML `<input/>` tags. See the
7168 * [OOjs UI documentation on MediaWiki] [1] for more information.
7171 * // A ButtonInputWidget rendered as an HTML button, the default.
7172 * var button = new OO.ui.ButtonInputWidget( {
7173 * label: 'Input button',
7177 * $( 'body' ).append( button.$element );
7179 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs#Button_inputs
7182 * @extends OO.ui.InputWidget
7183 * @mixins OO.ui.mixin.ButtonElement
7184 * @mixins OO.ui.mixin.IconElement
7185 * @mixins OO.ui.mixin.IndicatorElement
7186 * @mixins OO.ui.mixin.LabelElement
7187 * @mixins OO.ui.mixin.TitledElement
7190 * @param {Object} [config] Configuration options
7191 * @cfg {string} [type='button'] The value of the HTML `'type'` attribute: 'button', 'submit' or 'reset'.
7192 * @cfg {boolean} [useInputTag=false] Use an `<input/>` tag instead of a `<button/>` tag, the default.
7193 * Widgets configured to be an `<input/>` do not support {@link #icon icons} and {@link #indicator indicators},
7194 * non-plaintext {@link #label labels}, or {@link #value values}. In general, useInputTag should only
7195 * be set to `true` when there’s need to support IE 6 in a form with multiple buttons.
7197 OO
.ui
.ButtonInputWidget
= function OoUiButtonInputWidget( config
) {
7198 // Configuration initialization
7199 config
= $.extend( { type
: 'button', useInputTag
: false }, config
);
7201 // See InputWidget#reusePreInfuseDOM about config.$input
7202 if ( config
.$input
) {
7203 config
.$input
.empty();
7206 // Properties (must be set before parent constructor, which calls #setValue)
7207 this.useInputTag
= config
.useInputTag
;
7209 // Parent constructor
7210 OO
.ui
.ButtonInputWidget
.parent
.call( this, config
);
7212 // Mixin constructors
7213 OO
.ui
.mixin
.ButtonElement
.call( this, $.extend( {}, config
, { $button
: this.$input
} ) );
7214 OO
.ui
.mixin
.IconElement
.call( this, config
);
7215 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
7216 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7217 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$input
} ) );
7220 if ( !config
.useInputTag
) {
7221 this.$input
.append( this.$icon
, this.$label
, this.$indicator
);
7223 this.$element
.addClass( 'oo-ui-buttonInputWidget' );
7228 OO
.inheritClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.InputWidget
);
7229 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.ButtonElement
);
7230 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IconElement
);
7231 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
7232 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.LabelElement
);
7233 OO
.mixinClass( OO
.ui
.ButtonInputWidget
, OO
.ui
.mixin
.TitledElement
);
7235 /* Static Properties */
7238 * Disable generating `<label>` elements for buttons. One would very rarely need additional label
7239 * for a button, and it's already a big clickable target, and it causes unexpected rendering.
7241 OO
.ui
.ButtonInputWidget
.static.supportsSimpleLabel
= false;
7249 OO
.ui
.ButtonInputWidget
.prototype.getInputElement = function ( config
) {
7251 type
= [ 'button', 'submit', 'reset' ].indexOf( config
.type
) !== -1 ? config
.type
: 'button';
7252 return $( '<' + ( config
.useInputTag
? 'input' : 'button' ) + ' type="' + type
+ '">' );
7258 * If #useInputTag is `true`, the label is set as the `value` of the `<input/>` tag.
7260 * @param {jQuery|string|Function|null} label Label nodes, text, a function that returns nodes or
7261 * text, or `null` for no label
7264 OO
.ui
.ButtonInputWidget
.prototype.setLabel = function ( label
) {
7265 if ( typeof label
=== 'function' ) {
7266 label
= OO
.ui
.resolveMsg( label
);
7269 if ( this.useInputTag
) {
7270 // Discard non-plaintext labels
7271 if ( typeof label
!== 'string' ) {
7275 this.$input
.val( label
);
7278 return OO
.ui
.mixin
.LabelElement
.prototype.setLabel
.call( this, label
);
7282 * Set the value of the input.
7284 * This method is disabled for button inputs configured as {@link #useInputTag <input/> tags}, as
7285 * they do not support {@link #value values}.
7287 * @param {string} value New value
7290 OO
.ui
.ButtonInputWidget
.prototype.setValue = function ( value
) {
7291 if ( !this.useInputTag
) {
7292 OO
.ui
.ButtonInputWidget
.parent
.prototype.setValue
.call( this, value
);
7298 * CheckboxInputWidgets, like HTML checkboxes, can be selected and/or configured with a value.
7299 * Note that these {@link OO.ui.InputWidget input widgets} are best laid out
7300 * in {@link OO.ui.FieldLayout field layouts} that use the {@link OO.ui.FieldLayout#align inline}
7301 * alignment. For more information, please see the [OOjs UI documentation on MediaWiki][1].
7303 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
7306 * // An example of selected, unselected, and disabled checkbox inputs
7307 * var checkbox1=new OO.ui.CheckboxInputWidget( {
7311 * var checkbox2=new OO.ui.CheckboxInputWidget( {
7314 * var checkbox3=new OO.ui.CheckboxInputWidget( {
7318 * // Create a fieldset layout with fields for each checkbox.
7319 * var fieldset = new OO.ui.FieldsetLayout( {
7320 * label: 'Checkboxes'
7322 * fieldset.addItems( [
7323 * new OO.ui.FieldLayout( checkbox1, { label: 'Selected checkbox', align: 'inline' } ),
7324 * new OO.ui.FieldLayout( checkbox2, { label: 'Unselected checkbox', align: 'inline' } ),
7325 * new OO.ui.FieldLayout( checkbox3, { label: 'Disabled checkbox', align: 'inline' } ),
7327 * $( 'body' ).append( fieldset.$element );
7329 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7332 * @extends OO.ui.InputWidget
7335 * @param {Object} [config] Configuration options
7336 * @cfg {boolean} [selected=false] Select the checkbox initially. By default, the checkbox is not selected.
7338 OO
.ui
.CheckboxInputWidget
= function OoUiCheckboxInputWidget( config
) {
7339 // Configuration initialization
7340 config
= config
|| {};
7342 // Parent constructor
7343 OO
.ui
.CheckboxInputWidget
.parent
.call( this, config
);
7347 .addClass( 'oo-ui-checkboxInputWidget' )
7348 // Required for pretty styling in MediaWiki theme
7349 .append( $( '<span>' ) );
7350 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
7355 OO
.inheritClass( OO
.ui
.CheckboxInputWidget
, OO
.ui
.InputWidget
);
7357 /* Static Methods */
7362 OO
.ui
.CheckboxInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
7363 var state
= OO
.ui
.CheckboxInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
7364 state
.checked
= config
.$input
.prop( 'checked' );
7374 OO
.ui
.CheckboxInputWidget
.prototype.getInputElement = function () {
7375 return $( '<input>' ).attr( 'type', 'checkbox' );
7381 OO
.ui
.CheckboxInputWidget
.prototype.onEdit = function () {
7383 if ( !this.isDisabled() ) {
7384 // Allow the stack to clear so the value will be updated
7385 setTimeout( function () {
7386 widget
.setSelected( widget
.$input
.prop( 'checked' ) );
7392 * Set selection state of this checkbox.
7394 * @param {boolean} state `true` for selected
7397 OO
.ui
.CheckboxInputWidget
.prototype.setSelected = function ( state
) {
7399 if ( this.selected
!== state
) {
7400 this.selected
= state
;
7401 this.$input
.prop( 'checked', this.selected
);
7402 this.emit( 'change', this.selected
);
7408 * Check if this checkbox is selected.
7410 * @return {boolean} Checkbox is selected
7412 OO
.ui
.CheckboxInputWidget
.prototype.isSelected = function () {
7413 // Resynchronize our internal data with DOM data. Other scripts executing on the page can modify
7414 // it, and we won't know unless they're kind enough to trigger a 'change' event.
7415 var selected
= this.$input
.prop( 'checked' );
7416 if ( this.selected
!== selected
) {
7417 this.setSelected( selected
);
7419 return this.selected
;
7425 OO
.ui
.CheckboxInputWidget
.prototype.restorePreInfuseState = function ( state
) {
7426 OO
.ui
.CheckboxInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
7427 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
7428 this.setSelected( state
.checked
);
7433 * DropdownInputWidget is a {@link OO.ui.DropdownWidget DropdownWidget} intended to be used
7434 * within a HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
7435 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
7436 * more information about input widgets.
7438 * A DropdownInputWidget always has a value (one of the options is always selected), unless there
7439 * are no options. If no `value` configuration option is provided, the first option is selected.
7440 * If you need a state representing no value (no option being selected), use a DropdownWidget.
7442 * This and OO.ui.RadioSelectInputWidget support the same configuration options.
7445 * // Example: A DropdownInputWidget with three options
7446 * var dropdownInput = new OO.ui.DropdownInputWidget( {
7448 * { data: 'a', label: 'First' },
7449 * { data: 'b', label: 'Second'},
7450 * { data: 'c', label: 'Third' }
7453 * $( 'body' ).append( dropdownInput.$element );
7455 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7458 * @extends OO.ui.InputWidget
7459 * @mixins OO.ui.mixin.TitledElement
7462 * @param {Object} [config] Configuration options
7463 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
7464 * @cfg {Object} [dropdown] Configuration options for {@link OO.ui.DropdownWidget DropdownWidget}
7466 OO
.ui
.DropdownInputWidget
= function OoUiDropdownInputWidget( config
) {
7467 // Configuration initialization
7468 config
= config
|| {};
7470 // See InputWidget#reusePreInfuseDOM about config.$input
7471 if ( config
.$input
) {
7472 config
.$input
.addClass( 'oo-ui-element-hidden' );
7475 // Properties (must be done before parent constructor which calls #setDisabled)
7476 this.dropdownWidget
= new OO
.ui
.DropdownWidget( config
.dropdown
);
7478 // Parent constructor
7479 OO
.ui
.DropdownInputWidget
.parent
.call( this, config
);
7481 // Mixin constructors
7482 OO
.ui
.mixin
.TitledElement
.call( this, config
);
7485 this.dropdownWidget
.getMenu().connect( this, { select
: 'onMenuSelect' } );
7488 this.setOptions( config
.options
|| [] );
7490 .addClass( 'oo-ui-dropdownInputWidget' )
7491 .append( this.dropdownWidget
.$element
);
7496 OO
.inheritClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.InputWidget
);
7497 OO
.mixinClass( OO
.ui
.DropdownInputWidget
, OO
.ui
.mixin
.TitledElement
);
7505 OO
.ui
.DropdownInputWidget
.prototype.getInputElement = function () {
7506 return $( '<input>' ).attr( 'type', 'hidden' );
7510 * Handles menu select events.
7513 * @param {OO.ui.MenuOptionWidget} item Selected menu item
7515 OO
.ui
.DropdownInputWidget
.prototype.onMenuSelect = function ( item
) {
7516 this.setValue( item
.getData() );
7522 OO
.ui
.DropdownInputWidget
.prototype.setValue = function ( value
) {
7523 value
= this.cleanUpValue( value
);
7524 this.dropdownWidget
.getMenu().selectItemByData( value
);
7525 OO
.ui
.DropdownInputWidget
.parent
.prototype.setValue
.call( this, value
);
7532 OO
.ui
.DropdownInputWidget
.prototype.setDisabled = function ( state
) {
7533 this.dropdownWidget
.setDisabled( state
);
7534 OO
.ui
.DropdownInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
7539 * Set the options available for this input.
7541 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
7544 OO
.ui
.DropdownInputWidget
.prototype.setOptions = function ( options
) {
7546 value
= this.getValue(),
7549 // Rebuild the dropdown menu
7550 this.dropdownWidget
.getMenu()
7552 .addItems( options
.map( function ( opt
) {
7553 var optValue
= widget
.cleanUpValue( opt
.data
);
7554 return new OO
.ui
.MenuOptionWidget( {
7556 label
: opt
.label
!== undefined ? opt
.label
: optValue
7560 // Restore the previous value, or reset to something sensible
7561 if ( this.dropdownWidget
.getMenu().getItemFromData( value
) ) {
7562 // Previous value is still available, ensure consistency with the dropdown
7563 this.setValue( value
);
7565 // No longer valid, reset
7566 if ( options
.length
) {
7567 this.setValue( options
[ 0 ].data
);
7577 OO
.ui
.DropdownInputWidget
.prototype.focus = function () {
7578 this.dropdownWidget
.getMenu().toggle( true );
7585 OO
.ui
.DropdownInputWidget
.prototype.blur = function () {
7586 this.dropdownWidget
.getMenu().toggle( false );
7591 * RadioInputWidget creates a single radio button. Because radio buttons are usually used as a set,
7592 * in most cases you will want to use a {@link OO.ui.RadioSelectWidget radio select}
7593 * with {@link OO.ui.RadioOptionWidget radio options} instead of this class. For more information,
7594 * please see the [OOjs UI documentation on MediaWiki][1].
7596 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
7599 * // An example of selected, unselected, and disabled radio inputs
7600 * var radio1 = new OO.ui.RadioInputWidget( {
7604 * var radio2 = new OO.ui.RadioInputWidget( {
7607 * var radio3 = new OO.ui.RadioInputWidget( {
7611 * // Create a fieldset layout with fields for each radio button.
7612 * var fieldset = new OO.ui.FieldsetLayout( {
7613 * label: 'Radio inputs'
7615 * fieldset.addItems( [
7616 * new OO.ui.FieldLayout( radio1, { label: 'Selected', align: 'inline' } ),
7617 * new OO.ui.FieldLayout( radio2, { label: 'Unselected', align: 'inline' } ),
7618 * new OO.ui.FieldLayout( radio3, { label: 'Disabled', align: 'inline' } ),
7620 * $( 'body' ).append( fieldset.$element );
7622 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7625 * @extends OO.ui.InputWidget
7628 * @param {Object} [config] Configuration options
7629 * @cfg {boolean} [selected=false] Select the radio button initially. By default, the radio button is not selected.
7631 OO
.ui
.RadioInputWidget
= function OoUiRadioInputWidget( config
) {
7632 // Configuration initialization
7633 config
= config
|| {};
7635 // Parent constructor
7636 OO
.ui
.RadioInputWidget
.parent
.call( this, config
);
7640 .addClass( 'oo-ui-radioInputWidget' )
7641 // Required for pretty styling in MediaWiki theme
7642 .append( $( '<span>' ) );
7643 this.setSelected( config
.selected
!== undefined ? config
.selected
: false );
7648 OO
.inheritClass( OO
.ui
.RadioInputWidget
, OO
.ui
.InputWidget
);
7650 /* Static Methods */
7655 OO
.ui
.RadioInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
7656 var state
= OO
.ui
.RadioInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
7657 state
.checked
= config
.$input
.prop( 'checked' );
7667 OO
.ui
.RadioInputWidget
.prototype.getInputElement = function () {
7668 return $( '<input>' ).attr( 'type', 'radio' );
7674 OO
.ui
.RadioInputWidget
.prototype.onEdit = function () {
7675 // RadioInputWidget doesn't track its state.
7679 * Set selection state of this radio button.
7681 * @param {boolean} state `true` for selected
7684 OO
.ui
.RadioInputWidget
.prototype.setSelected = function ( state
) {
7685 // RadioInputWidget doesn't track its state.
7686 this.$input
.prop( 'checked', state
);
7691 * Check if this radio button is selected.
7693 * @return {boolean} Radio is selected
7695 OO
.ui
.RadioInputWidget
.prototype.isSelected = function () {
7696 return this.$input
.prop( 'checked' );
7702 OO
.ui
.RadioInputWidget
.prototype.restorePreInfuseState = function ( state
) {
7703 OO
.ui
.RadioInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
7704 if ( state
.checked
!== undefined && state
.checked
!== this.isSelected() ) {
7705 this.setSelected( state
.checked
);
7710 * RadioSelectInputWidget is a {@link OO.ui.RadioSelectWidget RadioSelectWidget} intended to be used
7711 * within a HTML form, such as a OO.ui.FormLayout. The selected value is synchronized with the value
7712 * of a hidden HTML `input` tag. Please see the [OOjs UI documentation on MediaWiki][1] for
7713 * more information about input widgets.
7715 * This and OO.ui.DropdownInputWidget support the same configuration options.
7718 * // Example: A RadioSelectInputWidget with three options
7719 * var radioSelectInput = new OO.ui.RadioSelectInputWidget( {
7721 * { data: 'a', label: 'First' },
7722 * { data: 'b', label: 'Second'},
7723 * { data: 'c', label: 'Third' }
7726 * $( 'body' ).append( radioSelectInput.$element );
7728 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7731 * @extends OO.ui.InputWidget
7734 * @param {Object} [config] Configuration options
7735 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
7737 OO
.ui
.RadioSelectInputWidget
= function OoUiRadioSelectInputWidget( config
) {
7738 // Configuration initialization
7739 config
= config
|| {};
7741 // Properties (must be done before parent constructor which calls #setDisabled)
7742 this.radioSelectWidget
= new OO
.ui
.RadioSelectWidget();
7744 // Parent constructor
7745 OO
.ui
.RadioSelectInputWidget
.parent
.call( this, config
);
7748 this.radioSelectWidget
.connect( this, { select
: 'onMenuSelect' } );
7751 this.setOptions( config
.options
|| [] );
7753 .addClass( 'oo-ui-radioSelectInputWidget' )
7754 .append( this.radioSelectWidget
.$element
);
7759 OO
.inheritClass( OO
.ui
.RadioSelectInputWidget
, OO
.ui
.InputWidget
);
7761 /* Static Properties */
7763 OO
.ui
.RadioSelectInputWidget
.static.supportsSimpleLabel
= false;
7765 /* Static Methods */
7770 OO
.ui
.RadioSelectInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
7771 var state
= OO
.ui
.RadioSelectInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
7772 state
.value
= $( node
).find( '.oo-ui-radioInputWidget .oo-ui-inputWidget-input:checked' ).val();
7779 OO
.ui
.RadioSelectInputWidget
.static.reusePreInfuseDOM = function ( node
, config
) {
7780 config
= OO
.ui
.RadioSelectInputWidget
.parent
.static.reusePreInfuseDOM( node
, config
);
7781 // Cannot reuse the `<input type=radio>` set
7782 delete config
.$input
;
7792 OO
.ui
.RadioSelectInputWidget
.prototype.getInputElement = function () {
7793 return $( '<input>' ).attr( 'type', 'hidden' );
7797 * Handles menu select events.
7800 * @param {OO.ui.RadioOptionWidget} item Selected menu item
7802 OO
.ui
.RadioSelectInputWidget
.prototype.onMenuSelect = function ( item
) {
7803 this.setValue( item
.getData() );
7809 OO
.ui
.RadioSelectInputWidget
.prototype.setValue = function ( value
) {
7810 value
= this.cleanUpValue( value
);
7811 this.radioSelectWidget
.selectItemByData( value
);
7812 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setValue
.call( this, value
);
7819 OO
.ui
.RadioSelectInputWidget
.prototype.setDisabled = function ( state
) {
7820 this.radioSelectWidget
.setDisabled( state
);
7821 OO
.ui
.RadioSelectInputWidget
.parent
.prototype.setDisabled
.call( this, state
);
7826 * Set the options available for this input.
7828 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
7831 OO
.ui
.RadioSelectInputWidget
.prototype.setOptions = function ( options
) {
7833 value
= this.getValue(),
7836 // Rebuild the radioSelect menu
7837 this.radioSelectWidget
7839 .addItems( options
.map( function ( opt
) {
7840 var optValue
= widget
.cleanUpValue( opt
.data
);
7841 return new OO
.ui
.RadioOptionWidget( {
7843 label
: opt
.label
!== undefined ? opt
.label
: optValue
7847 // Restore the previous value, or reset to something sensible
7848 if ( this.radioSelectWidget
.getItemFromData( value
) ) {
7849 // Previous value is still available, ensure consistency with the radioSelect
7850 this.setValue( value
);
7852 // No longer valid, reset
7853 if ( options
.length
) {
7854 this.setValue( options
[ 0 ].data
);
7862 * TextInputWidgets, like HTML text inputs, can be configured with options that customize the
7863 * size of the field as well as its presentation. In addition, these widgets can be configured
7864 * with {@link OO.ui.mixin.IconElement icons}, {@link OO.ui.mixin.IndicatorElement indicators}, an optional
7865 * validation-pattern (used to determine if an input value is valid or not) and an input filter,
7866 * which modifies incoming values rather than validating them.
7867 * Please see the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
7869 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
7872 * // Example of a text input widget
7873 * var textInput = new OO.ui.TextInputWidget( {
7874 * value: 'Text input'
7876 * $( 'body' ).append( textInput.$element );
7878 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
7881 * @extends OO.ui.InputWidget
7882 * @mixins OO.ui.mixin.IconElement
7883 * @mixins OO.ui.mixin.IndicatorElement
7884 * @mixins OO.ui.mixin.PendingElement
7885 * @mixins OO.ui.mixin.LabelElement
7888 * @param {Object} [config] Configuration options
7889 * @cfg {string} [type='text'] The value of the HTML `type` attribute: 'text', 'password', 'search',
7890 * 'email', 'url', 'date' or 'number'. Ignored if `multiline` is true.
7892 * Some values of `type` result in additional behaviors:
7894 * - `search`: implies `icon: 'search'` and `indicator: 'clear'`; when clicked, the indicator
7895 * empties the text field
7896 * @cfg {string} [placeholder] Placeholder text
7897 * @cfg {boolean} [autofocus=false] Use an HTML `autofocus` attribute to
7898 * instruct the browser to focus this widget.
7899 * @cfg {boolean} [readOnly=false] Prevent changes to the value of the text input.
7900 * @cfg {number} [maxLength] Maximum number of characters allowed in the input.
7901 * @cfg {boolean} [multiline=false] Allow multiple lines of text
7902 * @cfg {number} [rows] If multiline, number of visible lines in textarea. If used with `autosize`,
7903 * specifies minimum number of rows to display.
7904 * @cfg {boolean} [autosize=false] Automatically resize the text input to fit its content.
7905 * Use the #maxRows config to specify a maximum number of displayed rows.
7906 * @cfg {boolean} [maxRows] Maximum number of rows to display when #autosize is set to true.
7907 * Defaults to the maximum of `10` and `2 * rows`, or `10` if `rows` isn't provided.
7908 * @cfg {string} [labelPosition='after'] The position of the inline label relative to that of
7909 * the value or placeholder text: `'before'` or `'after'`
7910 * @cfg {boolean} [required=false] Mark the field as required. Implies `indicator: 'required'`.
7911 * @cfg {boolean} [autocomplete=true] Should the browser support autocomplete for this field
7912 * @cfg {RegExp|Function|string} [validate] Validation pattern: when string, a symbolic name of a
7913 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer'
7914 * (the value must contain only numbers); when RegExp, a regular expression that must match the
7915 * value for it to be considered valid; when Function, a function receiving the value as parameter
7916 * that must return true, or promise resolving to true, for it to be considered valid.
7918 OO
.ui
.TextInputWidget
= function OoUiTextInputWidget( config
) {
7919 // Configuration initialization
7920 config
= $.extend( {
7922 labelPosition
: 'after'
7924 if ( config
.type
=== 'search' ) {
7925 if ( config
.icon
=== undefined ) {
7926 config
.icon
= 'search';
7928 // indicator: 'clear' is set dynamically later, depending on value
7930 if ( config
.required
) {
7931 if ( config
.indicator
=== undefined ) {
7932 config
.indicator
= 'required';
7936 // Parent constructor
7937 OO
.ui
.TextInputWidget
.parent
.call( this, config
);
7939 // Mixin constructors
7940 OO
.ui
.mixin
.IconElement
.call( this, config
);
7941 OO
.ui
.mixin
.IndicatorElement
.call( this, config
);
7942 OO
.ui
.mixin
.PendingElement
.call( this, $.extend( {}, config
, { $pending
: this.$input
} ) );
7943 OO
.ui
.mixin
.LabelElement
.call( this, config
);
7946 this.type
= this.getSaneType( config
);
7947 this.readOnly
= false;
7948 this.multiline
= !!config
.multiline
;
7949 this.autosize
= !!config
.autosize
;
7950 this.minRows
= config
.rows
!== undefined ? config
.rows
: '';
7951 this.maxRows
= config
.maxRows
|| Math
.max( 2 * ( this.minRows
|| 0 ), 10 );
7952 this.validate
= null;
7953 this.styleHeight
= null;
7954 this.scrollWidth
= null;
7956 // Clone for resizing
7957 if ( this.autosize
) {
7958 this.$clone
= this.$input
7960 .insertAfter( this.$input
)
7961 .attr( 'aria-hidden', 'true' )
7962 .addClass( 'oo-ui-element-hidden' );
7965 this.setValidation( config
.validate
);
7966 this.setLabelPosition( config
.labelPosition
);
7970 keypress
: this.onKeyPress
.bind( this ),
7971 blur
: this.onBlur
.bind( this )
7974 focus
: this.onElementAttach
.bind( this )
7976 this.$icon
.on( 'mousedown', this.onIconMouseDown
.bind( this ) );
7977 this.$indicator
.on( 'mousedown', this.onIndicatorMouseDown
.bind( this ) );
7978 this.on( 'labelChange', this.updatePosition
.bind( this ) );
7979 this.connect( this, {
7981 disable
: 'onDisable'
7986 .addClass( 'oo-ui-textInputWidget oo-ui-textInputWidget-type-' + this.type
)
7987 .append( this.$icon
, this.$indicator
);
7988 this.setReadOnly( !!config
.readOnly
);
7989 this.updateSearchIndicator();
7990 if ( config
.placeholder
!== undefined ) {
7991 this.$input
.attr( 'placeholder', config
.placeholder
);
7993 if ( config
.maxLength
!== undefined ) {
7994 this.$input
.attr( 'maxlength', config
.maxLength
);
7996 if ( config
.autofocus
) {
7997 this.$input
.attr( 'autofocus', 'autofocus' );
7999 if ( config
.required
) {
8000 this.$input
.attr( 'required', 'required' );
8001 this.$input
.attr( 'aria-required', 'true' );
8003 if ( config
.autocomplete
=== false ) {
8004 this.$input
.attr( 'autocomplete', 'off' );
8005 // Turning off autocompletion also disables "form caching" when the user navigates to a
8006 // different page and then clicks "Back". Re-enable it when leaving. Borrowed from jQuery UI.
8008 beforeunload: function () {
8009 this.$input
.removeAttr( 'autocomplete' );
8011 pageshow: function () {
8012 // Browsers don't seem to actually fire this event on "Back", they instead just reload the
8013 // whole page... it shouldn't hurt, though.
8014 this.$input
.attr( 'autocomplete', 'off' );
8018 if ( this.multiline
&& config
.rows
) {
8019 this.$input
.attr( 'rows', config
.rows
);
8021 if ( this.label
|| config
.autosize
) {
8022 this.installParentChangeDetector();
8028 OO
.inheritClass( OO
.ui
.TextInputWidget
, OO
.ui
.InputWidget
);
8029 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IconElement
);
8030 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.IndicatorElement
);
8031 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.PendingElement
);
8032 OO
.mixinClass( OO
.ui
.TextInputWidget
, OO
.ui
.mixin
.LabelElement
);
8034 /* Static Properties */
8036 OO
.ui
.TextInputWidget
.static.validationPatterns
= {
8041 /* Static Methods */
8046 OO
.ui
.TextInputWidget
.static.gatherPreInfuseState = function ( node
, config
) {
8047 var state
= OO
.ui
.TextInputWidget
.parent
.static.gatherPreInfuseState( node
, config
);
8048 if ( config
.multiline
) {
8049 state
.scrollTop
= config
.$input
.scrollTop();
8057 * An `enter` event is emitted when the user presses 'enter' inside the text box.
8059 * Not emitted if the input is multiline.
8065 * A `resize` event is emitted when autosize is set and the widget resizes
8073 * Handle icon mouse down events.
8076 * @param {jQuery.Event} e Mouse down event
8078 OO
.ui
.TextInputWidget
.prototype.onIconMouseDown = function ( e
) {
8079 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
8080 this.$input
[ 0 ].focus();
8086 * Handle indicator mouse down events.
8089 * @param {jQuery.Event} e Mouse down event
8091 OO
.ui
.TextInputWidget
.prototype.onIndicatorMouseDown = function ( e
) {
8092 if ( e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
8093 if ( this.type
=== 'search' ) {
8094 // Clear the text field
8095 this.setValue( '' );
8097 this.$input
[ 0 ].focus();
8103 * Handle key press events.
8106 * @param {jQuery.Event} e Key press event
8107 * @fires enter If enter key is pressed and input is not multiline
8109 OO
.ui
.TextInputWidget
.prototype.onKeyPress = function ( e
) {
8110 if ( e
.which
=== OO
.ui
.Keys
.ENTER
&& !this.multiline
) {
8111 this.emit( 'enter', e
);
8116 * Handle blur events.
8119 * @param {jQuery.Event} e Blur event
8121 OO
.ui
.TextInputWidget
.prototype.onBlur = function () {
8122 this.setValidityFlag();
8126 * Handle element attach events.
8129 * @param {jQuery.Event} e Element attach event
8131 OO
.ui
.TextInputWidget
.prototype.onElementAttach = function () {
8132 // Any previously calculated size is now probably invalid if we reattached elsewhere
8133 this.valCache
= null;
8135 this.positionLabel();
8139 * Handle change events.
8141 * @param {string} value
8144 OO
.ui
.TextInputWidget
.prototype.onChange = function () {
8145 this.updateSearchIndicator();
8146 this.setValidityFlag();
8151 * Handle disable events.
8153 * @param {boolean} disabled Element is disabled
8156 OO
.ui
.TextInputWidget
.prototype.onDisable = function () {
8157 this.updateSearchIndicator();
8161 * Check if the input is {@link #readOnly read-only}.
8165 OO
.ui
.TextInputWidget
.prototype.isReadOnly = function () {
8166 return this.readOnly
;
8170 * Set the {@link #readOnly read-only} state of the input.
8172 * @param {boolean} state Make input read-only
8175 OO
.ui
.TextInputWidget
.prototype.setReadOnly = function ( state
) {
8176 this.readOnly
= !!state
;
8177 this.$input
.prop( 'readOnly', this.readOnly
);
8178 this.updateSearchIndicator();
8183 * Support function for making #onElementAttach work across browsers.
8185 * This whole function could be replaced with one line of code using the DOMNodeInsertedIntoDocument
8186 * event, but it's not supported by Firefox and allegedly deprecated, so we only use it as fallback.
8188 * Due to MutationObserver performance woes, #onElementAttach is only somewhat reliably called the
8189 * first time that the element gets attached to the documented.
8191 OO
.ui
.TextInputWidget
.prototype.installParentChangeDetector = function () {
8192 var mutationObserver
, onRemove
, topmostNode
, fakeParentNode
,
8193 MutationObserver
= window
.MutationObserver
|| window
.WebKitMutationObserver
|| window
.MozMutationObserver
,
8196 if ( MutationObserver
) {
8197 // The new way. If only it wasn't so ugly.
8199 if ( this.$element
.closest( 'html' ).length
) {
8200 // Widget is attached already, do nothing. This breaks the functionality of this function when
8201 // the widget is detached and reattached. Alas, doing this correctly with MutationObserver
8202 // would require observation of the whole document, which would hurt performance of other,
8203 // more important code.
8207 // Find topmost node in the tree
8208 topmostNode
= this.$element
[ 0 ];
8209 while ( topmostNode
.parentNode
) {
8210 topmostNode
= topmostNode
.parentNode
;
8213 // We have no way to detect the $element being attached somewhere without observing the entire
8214 // DOM with subtree modifications, which would hurt performance. So we cheat: we hook to the
8215 // parent node of $element, and instead detect when $element is removed from it (and thus
8216 // probably attached somewhere else). If there is no parent, we create a "fake" one. If it
8217 // doesn't get attached, we end up back here and create the parent.
8219 mutationObserver
= new MutationObserver( function ( mutations
) {
8220 var i
, j
, removedNodes
;
8221 for ( i
= 0; i
< mutations
.length
; i
++ ) {
8222 removedNodes
= mutations
[ i
].removedNodes
;
8223 for ( j
= 0; j
< removedNodes
.length
; j
++ ) {
8224 if ( removedNodes
[ j
] === topmostNode
) {
8225 setTimeout( onRemove
, 0 );
8232 onRemove = function () {
8233 // If the node was attached somewhere else, report it
8234 if ( widget
.$element
.closest( 'html' ).length
) {
8235 widget
.onElementAttach();
8237 mutationObserver
.disconnect();
8238 widget
.installParentChangeDetector();
8241 // Create a fake parent and observe it
8242 fakeParentNode
= $( '<div>' ).append( topmostNode
)[ 0 ];
8243 mutationObserver
.observe( fakeParentNode
, { childList
: true } );
8245 // Using the DOMNodeInsertedIntoDocument event is much nicer and less magical, and works for
8246 // detachment and reattachment, but it's not supported by Firefox and allegedly deprecated.
8247 this.$element
.on( 'DOMNodeInsertedIntoDocument', this.onElementAttach
.bind( this ) );
8252 * Automatically adjust the size of the text input.
8254 * This only affects #multiline inputs that are {@link #autosize autosized}.
8259 OO
.ui
.TextInputWidget
.prototype.adjustSize = function () {
8260 var scrollHeight
, innerHeight
, outerHeight
, maxInnerHeight
, measurementError
,
8261 idealHeight
, newHeight
, scrollWidth
, property
;
8263 if ( this.multiline
&& this.$input
.val() !== this.valCache
) {
8264 if ( this.autosize
) {
8266 .val( this.$input
.val() )
8267 .attr( 'rows', this.minRows
)
8268 // Set inline height property to 0 to measure scroll height
8269 .css( 'height', 0 );
8271 this.$clone
.removeClass( 'oo-ui-element-hidden' );
8273 this.valCache
= this.$input
.val();
8275 scrollHeight
= this.$clone
[ 0 ].scrollHeight
;
8277 // Remove inline height property to measure natural heights
8278 this.$clone
.css( 'height', '' );
8279 innerHeight
= this.$clone
.innerHeight();
8280 outerHeight
= this.$clone
.outerHeight();
8282 // Measure max rows height
8284 .attr( 'rows', this.maxRows
)
8285 .css( 'height', 'auto' )
8287 maxInnerHeight
= this.$clone
.innerHeight();
8289 // Difference between reported innerHeight and scrollHeight with no scrollbars present.
8290 // This is sometimes non-zero on Blink-based browsers, depending on zoom level.
8291 measurementError
= maxInnerHeight
- this.$clone
[ 0 ].scrollHeight
;
8292 idealHeight
= Math
.min( maxInnerHeight
, scrollHeight
+ measurementError
);
8294 this.$clone
.addClass( 'oo-ui-element-hidden' );
8296 // Only apply inline height when expansion beyond natural height is needed
8297 // Use the difference between the inner and outer height as a buffer
8298 newHeight
= idealHeight
> innerHeight
? idealHeight
+ ( outerHeight
- innerHeight
) : '';
8299 if ( newHeight
!== this.styleHeight
) {
8300 this.$input
.css( 'height', newHeight
);
8301 this.styleHeight
= newHeight
;
8302 this.emit( 'resize' );
8305 scrollWidth
= this.$input
[ 0 ].offsetWidth
- this.$input
[ 0 ].clientWidth
;
8306 if ( scrollWidth
!== this.scrollWidth
) {
8307 property
= this.$element
.css( 'direction' ) === 'rtl' ? 'left' : 'right';
8309 this.$label
.css( { right
: '', left
: '' } );
8310 this.$indicator
.css( { right
: '', left
: '' } );
8312 if ( scrollWidth
) {
8313 this.$indicator
.css( property
, scrollWidth
);
8314 if ( this.labelPosition
=== 'after' ) {
8315 this.$label
.css( property
, scrollWidth
);
8319 this.scrollWidth
= scrollWidth
;
8320 this.positionLabel();
8330 OO
.ui
.TextInputWidget
.prototype.getInputElement = function ( config
) {
8331 if ( config
.multiline
) {
8332 return $( '<textarea>' );
8333 } else if ( this.getSaneType( config
) === 'number' ) {
8334 return $( '<input>' )
8335 .attr( 'step', 'any' )
8336 .attr( 'type', 'number' );
8338 return $( '<input>' ).attr( 'type', this.getSaneType( config
) );
8343 * Get sanitized value for 'type' for given config.
8345 * @param {Object} config Configuration options
8346 * @return {string|null}
8349 OO
.ui
.TextInputWidget
.prototype.getSaneType = function ( config
) {
8350 var allowedTypes
= [
8359 return allowedTypes
.indexOf( config
.type
) !== -1 ? config
.type
: 'text';
8363 * Check if the input supports multiple lines.
8367 OO
.ui
.TextInputWidget
.prototype.isMultiline = function () {
8368 return !!this.multiline
;
8372 * Check if the input automatically adjusts its size.
8376 OO
.ui
.TextInputWidget
.prototype.isAutosizing = function () {
8377 return !!this.autosize
;
8381 * Focus the input and select a specified range within the text.
8383 * @param {number} from Select from offset
8384 * @param {number} [to] Select to offset, defaults to from
8387 OO
.ui
.TextInputWidget
.prototype.selectRange = function ( from, to
) {
8388 var isBackwards
, start
, end
,
8389 input
= this.$input
[ 0 ];
8393 isBackwards
= to
< from;
8394 start
= isBackwards
? to
: from;
8395 end
= isBackwards
? from : to
;
8400 input
.setSelectionRange( start
, end
, isBackwards
? 'backward' : 'forward' );
8402 // IE throws an exception if you call setSelectionRange on a unattached DOM node.
8403 // Rather than expensively check if the input is attached every time, just check
8404 // if it was the cause of an error being thrown. If not, rethrow the error.
8405 if ( this.getElementDocument().body
.contains( input
) ) {
8413 * Get an object describing the current selection range in a directional manner
8415 * @return {Object} Object containing 'from' and 'to' offsets
8417 OO
.ui
.TextInputWidget
.prototype.getRange = function () {
8418 var input
= this.$input
[ 0 ],
8419 start
= input
.selectionStart
,
8420 end
= input
.selectionEnd
,
8421 isBackwards
= input
.selectionDirection
=== 'backward';
8424 from: isBackwards
? end
: start
,
8425 to
: isBackwards
? start
: end
8430 * Get the length of the text input value.
8432 * This could differ from the length of #getValue if the
8433 * value gets filtered
8435 * @return {number} Input length
8437 OO
.ui
.TextInputWidget
.prototype.getInputLength = function () {
8438 return this.$input
[ 0 ].value
.length
;
8442 * Focus the input and select the entire text.
8446 OO
.ui
.TextInputWidget
.prototype.select = function () {
8447 return this.selectRange( 0, this.getInputLength() );
8451 * Focus the input and move the cursor to the start.
8455 OO
.ui
.TextInputWidget
.prototype.moveCursorToStart = function () {
8456 return this.selectRange( 0 );
8460 * Focus the input and move the cursor to the end.
8464 OO
.ui
.TextInputWidget
.prototype.moveCursorToEnd = function () {
8465 return this.selectRange( this.getInputLength() );
8469 * Insert new content into the input.
8471 * @param {string} content Content to be inserted
8474 OO
.ui
.TextInputWidget
.prototype.insertContent = function ( content
) {
8476 range
= this.getRange(),
8477 value
= this.getValue();
8479 start
= Math
.min( range
.from, range
.to
);
8480 end
= Math
.max( range
.from, range
.to
);
8482 this.setValue( value
.slice( 0, start
) + content
+ value
.slice( end
) );
8483 this.selectRange( start
+ content
.length
);
8488 * Insert new content either side of a selection.
8490 * @param {string} pre Content to be inserted before the selection
8491 * @param {string} post Content to be inserted after the selection
8494 OO
.ui
.TextInputWidget
.prototype.encapsulateContent = function ( pre
, post
) {
8496 range
= this.getRange(),
8497 offset
= pre
.length
;
8499 start
= Math
.min( range
.from, range
.to
);
8500 end
= Math
.max( range
.from, range
.to
);
8502 this.selectRange( start
).insertContent( pre
);
8503 this.selectRange( offset
+ end
).insertContent( post
);
8505 this.selectRange( offset
+ start
, offset
+ end
);
8510 * Set the validation pattern.
8512 * The validation pattern is either a regular expression, a function, or the symbolic name of a
8513 * pattern defined by the class: 'non-empty' (the value cannot be an empty string) or 'integer' (the
8514 * value must contain only numbers).
8516 * @param {RegExp|Function|string|null} validate Regular expression, function, or the symbolic name
8517 * of a pattern (either ‘integer’ or ‘non-empty’) defined by the class.
8519 OO
.ui
.TextInputWidget
.prototype.setValidation = function ( validate
) {
8520 if ( validate
instanceof RegExp
|| validate
instanceof Function
) {
8521 this.validate
= validate
;
8523 this.validate
= this.constructor.static.validationPatterns
[ validate
] || /.*/;
8528 * Sets the 'invalid' flag appropriately.
8530 * @param {boolean} [isValid] Optionally override validation result
8532 OO
.ui
.TextInputWidget
.prototype.setValidityFlag = function ( isValid
) {
8534 setFlag = function ( valid
) {
8536 widget
.$input
.attr( 'aria-invalid', 'true' );
8538 widget
.$input
.removeAttr( 'aria-invalid' );
8540 widget
.setFlags( { invalid
: !valid
} );
8543 if ( isValid
!== undefined ) {
8546 this.getValidity().then( function () {
8555 * Check if a value is valid.
8557 * This method returns a promise that resolves with a boolean `true` if the current value is
8558 * considered valid according to the supplied {@link #validate validation pattern}.
8560 * @deprecated since v0.12.3
8561 * @return {jQuery.Promise} A promise that resolves to a boolean `true` if the value is valid.
8563 OO
.ui
.TextInputWidget
.prototype.isValid = function () {
8566 if ( this.validate
instanceof Function
) {
8567 result
= this.validate( this.getValue() );
8568 if ( result
&& $.isFunction( result
.promise
) ) {
8569 return result
.promise();
8571 return $.Deferred().resolve( !!result
).promise();
8574 return $.Deferred().resolve( !!this.getValue().match( this.validate
) ).promise();
8579 * Get the validity of current value.
8581 * This method returns a promise that resolves if the value is valid and rejects if
8582 * it isn't. Uses the {@link #validate validation pattern} to check for validity.
8584 * @return {jQuery.Promise} A promise that resolves if the value is valid, rejects if not.
8586 OO
.ui
.TextInputWidget
.prototype.getValidity = function () {
8589 function rejectOrResolve( valid
) {
8591 return $.Deferred().resolve().promise();
8593 return $.Deferred().reject().promise();
8597 if ( this.validate
instanceof Function
) {
8598 result
= this.validate( this.getValue() );
8599 if ( result
&& $.isFunction( result
.promise
) ) {
8600 return result
.promise().then( function ( valid
) {
8601 return rejectOrResolve( valid
);
8604 return rejectOrResolve( result
);
8607 return rejectOrResolve( this.getValue().match( this.validate
) );
8612 * Set the position of the inline label relative to that of the value: `‘before’` or `‘after’`.
8614 * @param {string} labelPosition Label position, 'before' or 'after'
8617 OO
.ui
.TextInputWidget
.prototype.setLabelPosition = function ( labelPosition
) {
8618 this.labelPosition
= labelPosition
;
8620 // If there is no label and we only change the position, #updatePosition is a no-op,
8621 // but it takes really a lot of work to do nothing.
8622 this.updatePosition();
8628 * Update the position of the inline label.
8630 * This method is called by #setLabelPosition, and can also be called on its own if
8631 * something causes the label to be mispositioned.
8635 OO
.ui
.TextInputWidget
.prototype.updatePosition = function () {
8636 var after
= this.labelPosition
=== 'after';
8639 .toggleClass( 'oo-ui-textInputWidget-labelPosition-after', !!this.label
&& after
)
8640 .toggleClass( 'oo-ui-textInputWidget-labelPosition-before', !!this.label
&& !after
);
8642 this.valCache
= null;
8643 this.scrollWidth
= null;
8645 this.positionLabel();
8651 * Update the 'clear' indicator displayed on type: 'search' text fields, hiding it when the field is
8652 * already empty or when it's not editable.
8654 OO
.ui
.TextInputWidget
.prototype.updateSearchIndicator = function () {
8655 if ( this.type
=== 'search' ) {
8656 if ( this.getValue() === '' || this.isDisabled() || this.isReadOnly() ) {
8657 this.setIndicator( null );
8659 this.setIndicator( 'clear' );
8665 * Position the label by setting the correct padding on the input.
8670 OO
.ui
.TextInputWidget
.prototype.positionLabel = function () {
8671 var after
, rtl
, property
;
8674 // Clear old values if present
8676 'padding-right': '',
8681 this.$element
.append( this.$label
);
8683 this.$label
.detach();
8687 after
= this.labelPosition
=== 'after';
8688 rtl
= this.$element
.css( 'direction' ) === 'rtl';
8689 property
= after
=== rtl
? 'padding-left' : 'padding-right';
8691 this.$input
.css( property
, this.$label
.outerWidth( true ) + ( after
? this.scrollWidth
: 0 ) );
8699 OO
.ui
.TextInputWidget
.prototype.restorePreInfuseState = function ( state
) {
8700 OO
.ui
.TextInputWidget
.parent
.prototype.restorePreInfuseState
.call( this, state
);
8701 if ( state
.scrollTop
!== undefined ) {
8702 this.$input
.scrollTop( state
.scrollTop
);
8707 * ComboBoxInputWidgets combine a {@link OO.ui.TextInputWidget text input} (where a value
8708 * can be entered manually) and a {@link OO.ui.MenuSelectWidget menu of options} (from which
8709 * a value can be chosen instead). Users can choose options from the combo box in one of two ways:
8711 * - by typing a value in the text input field. If the value exactly matches the value of a menu
8712 * option, that option will appear to be selected.
8713 * - by choosing a value from the menu. The value of the chosen option will then appear in the text
8716 * This widget can be used inside a HTML form, such as a OO.ui.FormLayout.
8718 * For more information about menus and options, please see the [OOjs UI documentation on MediaWiki][1].
8721 * // Example: A ComboBoxInputWidget.
8722 * var comboBox = new OO.ui.ComboBoxInputWidget( {
8723 * label: 'ComboBoxInputWidget',
8724 * value: 'Option 1',
8727 * new OO.ui.MenuOptionWidget( {
8729 * label: 'Option One'
8731 * new OO.ui.MenuOptionWidget( {
8733 * label: 'Option Two'
8735 * new OO.ui.MenuOptionWidget( {
8737 * label: 'Option Three'
8739 * new OO.ui.MenuOptionWidget( {
8741 * label: 'Option Four'
8743 * new OO.ui.MenuOptionWidget( {
8745 * label: 'Option Five'
8750 * $( 'body' ).append( comboBox.$element );
8752 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Selects_and_Options#Menu_selects_and_options
8755 * @extends OO.ui.TextInputWidget
8758 * @param {Object} [config] Configuration options
8759 * @cfg {Object[]} [options=[]] Array of menu options in the format `{ data: …, label: … }`
8760 * @cfg {Object} [menu] Configuration options to pass to the {@link OO.ui.FloatingMenuSelectWidget menu select widget}.
8761 * @cfg {jQuery} [$overlay] Render the menu into a separate layer. This configuration is useful in cases where
8762 * the expanded menu is larger than its containing `<div>`. The specified overlay layer is usually on top of the
8763 * containing `<div>` and has a larger area. By default, the menu uses relative positioning.
8765 OO
.ui
.ComboBoxInputWidget
= function OoUiComboBoxInputWidget( config
) {
8766 // Configuration initialization
8767 config
= $.extend( {
8771 // For backwards-compatibility with ComboBoxWidget config
8772 $.extend( config
, config
.input
);
8774 // Parent constructor
8775 OO
.ui
.ComboBoxInputWidget
.parent
.call( this, config
);
8778 this.$overlay
= config
.$overlay
|| this.$element
;
8779 this.menu
= new OO
.ui
.FloatingMenuSelectWidget( $.extend(
8783 $container
: this.$element
,
8784 disabled
: this.isDisabled()
8788 // For backwards-compatibility with ComboBoxWidget
8792 this.$indicator
.on( {
8793 click
: this.onIndicatorClick
.bind( this ),
8794 keypress
: this.onIndicatorKeyPress
.bind( this )
8796 this.connect( this, {
8797 change
: 'onInputChange',
8798 enter
: 'onInputEnter'
8800 this.menu
.connect( this, {
8801 choose
: 'onMenuChoose',
8802 add
: 'onMenuItemsChange',
8803 remove
: 'onMenuItemsChange'
8809 'aria-autocomplete': 'list'
8811 // Do not override options set via config.menu.items
8812 if ( config
.options
!== undefined ) {
8813 this.setOptions( config
.options
);
8815 // Extra class for backwards-compatibility with ComboBoxWidget
8816 this.$element
.addClass( 'oo-ui-comboBoxInputWidget oo-ui-comboBoxWidget' );
8817 this.$overlay
.append( this.menu
.$element
);
8818 this.onMenuItemsChange();
8823 OO
.inheritClass( OO
.ui
.ComboBoxInputWidget
, OO
.ui
.TextInputWidget
);
8828 * Get the combobox's menu.
8830 * @return {OO.ui.FloatingMenuSelectWidget} Menu widget
8832 OO
.ui
.ComboBoxInputWidget
.prototype.getMenu = function () {
8837 * Get the combobox's text input widget.
8839 * @return {OO.ui.TextInputWidget} Text input widget
8841 OO
.ui
.ComboBoxInputWidget
.prototype.getInput = function () {
8846 * Handle input change events.
8849 * @param {string} value New value
8851 OO
.ui
.ComboBoxInputWidget
.prototype.onInputChange = function ( value
) {
8852 var match
= this.menu
.getItemFromData( value
);
8854 this.menu
.selectItem( match
);
8855 if ( this.menu
.getHighlightedItem() ) {
8856 this.menu
.highlightItem( match
);
8859 if ( !this.isDisabled() ) {
8860 this.menu
.toggle( true );
8865 * Handle mouse click events.
8868 * @param {jQuery.Event} e Mouse click event
8870 OO
.ui
.ComboBoxInputWidget
.prototype.onIndicatorClick = function ( e
) {
8871 if ( !this.isDisabled() && e
.which
=== OO
.ui
.MouseButtons
.LEFT
) {
8873 this.$input
[ 0 ].focus();
8879 * Handle key press events.
8882 * @param {jQuery.Event} e Key press event
8884 OO
.ui
.ComboBoxInputWidget
.prototype.onIndicatorKeyPress = function ( e
) {
8885 if ( !this.isDisabled() && ( e
.which
=== OO
.ui
.Keys
.SPACE
|| e
.which
=== OO
.ui
.Keys
.ENTER
) ) {
8887 this.$input
[ 0 ].focus();
8893 * Handle input enter events.
8897 OO
.ui
.ComboBoxInputWidget
.prototype.onInputEnter = function () {
8898 if ( !this.isDisabled() ) {
8899 this.menu
.toggle( false );
8904 * Handle menu choose events.
8907 * @param {OO.ui.OptionWidget} item Chosen item
8909 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuChoose = function ( item
) {
8910 this.setValue( item
.getData() );
8914 * Handle menu item change events.
8918 OO
.ui
.ComboBoxInputWidget
.prototype.onMenuItemsChange = function () {
8919 var match
= this.menu
.getItemFromData( this.getValue() );
8920 this.menu
.selectItem( match
);
8921 if ( this.menu
.getHighlightedItem() ) {
8922 this.menu
.highlightItem( match
);
8924 this.$element
.toggleClass( 'oo-ui-comboBoxInputWidget-empty', this.menu
.isEmpty() );
8930 OO
.ui
.ComboBoxInputWidget
.prototype.setDisabled = function ( disabled
) {
8932 OO
.ui
.ComboBoxInputWidget
.parent
.prototype.setDisabled
.call( this, disabled
);
8935 this.menu
.setDisabled( this.isDisabled() );
8942 * Set the options available for this input.
8944 * @param {Object[]} options Array of menu options in the format `{ data: …, label: … }`
8947 OO
.ui
.ComboBoxInputWidget
.prototype.setOptions = function ( options
) {
8950 .addItems( options
.map( function ( opt
) {
8951 return new OO
.ui
.MenuOptionWidget( {
8953 label
: opt
.label
!== undefined ? opt
.label
: opt
.data
8962 * @deprecated since 0.13.2; use OO.ui.ComboBoxInputWidget instead
8964 OO
.ui
.ComboBoxWidget
= OO
.ui
.ComboBoxInputWidget
;
8967 * FieldLayouts are used with OO.ui.FieldsetLayout. Each FieldLayout requires a field-widget,
8968 * which is a widget that is specified by reference before any optional configuration settings.
8970 * Field layouts can be configured with help text and/or labels. Labels are aligned in one of four ways:
8972 * - **left**: The label is placed before the field-widget and aligned with the left margin.
8973 * A left-alignment is used for forms with many fields.
8974 * - **right**: The label is placed before the field-widget and aligned to the right margin.
8975 * A right-alignment is used for long but familiar forms which users tab through,
8976 * verifying the current field with a quick glance at the label.
8977 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
8978 * that users fill out from top to bottom.
8979 * - **inline**: The label is placed after the field-widget and aligned to the left.
8980 * An inline-alignment is best used with checkboxes or radio buttons.
8982 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout.
8983 * Please see the [OOjs UI documentation on MediaWiki] [1] for examples and more information.
8985 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
8988 * @extends OO.ui.Layout
8989 * @mixins OO.ui.mixin.LabelElement
8990 * @mixins OO.ui.mixin.TitledElement
8993 * @param {OO.ui.Widget} fieldWidget Field widget
8994 * @param {Object} [config] Configuration options
8995 * @cfg {string} [align='left'] Alignment of the label: 'left', 'right', 'top' or 'inline'
8996 * @cfg {Array} [errors] Error messages about the widget, which will be displayed below the widget.
8997 * The array may contain strings or OO.ui.HtmlSnippet instances.
8998 * @cfg {Array} [notices] Notices about the widget, which will be displayed below the widget.
8999 * The array may contain strings or OO.ui.HtmlSnippet instances.
9000 * @cfg {string|OO.ui.HtmlSnippet} [help] Help text. When help text is specified, a "help" icon will appear
9001 * in the upper-right corner of the rendered field; clicking it will display the text in a popup.
9002 * For important messages, you are advised to use `notices`, as they are always shown.
9004 * @throws {Error} An error is thrown if no widget is specified
9006 OO
.ui
.FieldLayout
= function OoUiFieldLayout( fieldWidget
, config
) {
9007 var hasInputWidget
, div
;
9009 // Allow passing positional parameters inside the config object
9010 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
9011 config
= fieldWidget
;
9012 fieldWidget
= config
.fieldWidget
;
9015 // Make sure we have required constructor arguments
9016 if ( fieldWidget
=== undefined ) {
9017 throw new Error( 'Widget not found' );
9020 hasInputWidget
= fieldWidget
.constructor.static.supportsSimpleLabel
;
9022 // Configuration initialization
9023 config
= $.extend( { align
: 'left' }, config
);
9025 // Parent constructor
9026 OO
.ui
.FieldLayout
.parent
.call( this, config
);
9028 // Mixin constructors
9029 OO
.ui
.mixin
.LabelElement
.call( this, config
);
9030 OO
.ui
.mixin
.TitledElement
.call( this, $.extend( {}, config
, { $titled
: this.$label
} ) );
9033 this.fieldWidget
= fieldWidget
;
9036 this.$field
= $( '<div>' );
9037 this.$messages
= $( '<ul>' );
9038 this.$body
= $( '<' + ( hasInputWidget
? 'label' : 'div' ) + '>' );
9040 if ( config
.help
) {
9041 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
9042 classes
: [ 'oo-ui-fieldLayout-help' ],
9048 if ( config
.help
instanceof OO
.ui
.HtmlSnippet
) {
9049 div
.html( config
.help
.toString() );
9051 div
.text( config
.help
);
9053 this.popupButtonWidget
.getPopup().$body
.append(
9054 div
.addClass( 'oo-ui-fieldLayout-help-content' )
9056 this.$help
= this.popupButtonWidget
.$element
;
9058 this.$help
= $( [] );
9062 if ( hasInputWidget
) {
9063 this.$label
.on( 'click', this.onLabelClick
.bind( this ) );
9065 this.fieldWidget
.connect( this, { disable
: 'onFieldDisable' } );
9069 .addClass( 'oo-ui-fieldLayout' )
9070 .append( this.$help
, this.$body
);
9071 this.$body
.addClass( 'oo-ui-fieldLayout-body' );
9072 this.$messages
.addClass( 'oo-ui-fieldLayout-messages' );
9074 .addClass( 'oo-ui-fieldLayout-field' )
9075 .toggleClass( 'oo-ui-fieldLayout-disable', this.fieldWidget
.isDisabled() )
9076 .append( this.fieldWidget
.$element
);
9078 this.setErrors( config
.errors
|| [] );
9079 this.setNotices( config
.notices
|| [] );
9080 this.setAlignment( config
.align
);
9085 OO
.inheritClass( OO
.ui
.FieldLayout
, OO
.ui
.Layout
);
9086 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.LabelElement
);
9087 OO
.mixinClass( OO
.ui
.FieldLayout
, OO
.ui
.mixin
.TitledElement
);
9092 * Handle field disable events.
9095 * @param {boolean} value Field is disabled
9097 OO
.ui
.FieldLayout
.prototype.onFieldDisable = function ( value
) {
9098 this.$element
.toggleClass( 'oo-ui-fieldLayout-disabled', value
);
9102 * Handle label mouse click events.
9105 * @param {jQuery.Event} e Mouse click event
9107 OO
.ui
.FieldLayout
.prototype.onLabelClick = function () {
9108 this.fieldWidget
.simulateLabelClick();
9113 * Get the widget contained by the field.
9115 * @return {OO.ui.Widget} Field widget
9117 OO
.ui
.FieldLayout
.prototype.getField = function () {
9118 return this.fieldWidget
;
9123 * @param {string} kind 'error' or 'notice'
9124 * @param {string|OO.ui.HtmlSnippet} text
9127 OO
.ui
.FieldLayout
.prototype.makeMessage = function ( kind
, text
) {
9128 var $listItem
, $icon
, message
;
9129 $listItem
= $( '<li>' );
9130 if ( kind
=== 'error' ) {
9131 $icon
= new OO
.ui
.IconWidget( { icon
: 'alert', flags
: [ 'warning' ] } ).$element
;
9132 } else if ( kind
=== 'notice' ) {
9133 $icon
= new OO
.ui
.IconWidget( { icon
: 'info' } ).$element
;
9137 message
= new OO
.ui
.LabelWidget( { label
: text
} );
9139 .append( $icon
, message
.$element
)
9140 .addClass( 'oo-ui-fieldLayout-messages-' + kind
);
9145 * Set the field alignment mode.
9148 * @param {string} value Alignment mode, either 'left', 'right', 'top' or 'inline'
9151 OO
.ui
.FieldLayout
.prototype.setAlignment = function ( value
) {
9152 if ( value
!== this.align
) {
9153 // Default to 'left'
9154 if ( [ 'left', 'right', 'top', 'inline' ].indexOf( value
) === -1 ) {
9158 if ( value
=== 'inline' ) {
9159 this.$body
.append( this.$field
, this.$label
);
9161 this.$body
.append( this.$label
, this.$field
);
9163 // Set classes. The following classes can be used here:
9164 // * oo-ui-fieldLayout-align-left
9165 // * oo-ui-fieldLayout-align-right
9166 // * oo-ui-fieldLayout-align-top
9167 // * oo-ui-fieldLayout-align-inline
9169 this.$element
.removeClass( 'oo-ui-fieldLayout-align-' + this.align
);
9171 this.$element
.addClass( 'oo-ui-fieldLayout-align-' + value
);
9179 * Set the list of error messages.
9181 * @param {Array} errors Error messages about the widget, which will be displayed below the widget.
9182 * The array may contain strings or OO.ui.HtmlSnippet instances.
9185 OO
.ui
.FieldLayout
.prototype.setErrors = function ( errors
) {
9186 this.errors
= errors
.slice();
9187 this.updateMessages();
9192 * Set the list of notice messages.
9194 * @param {Array} notices Notices about the widget, which will be displayed below the widget.
9195 * The array may contain strings or OO.ui.HtmlSnippet instances.
9198 OO
.ui
.FieldLayout
.prototype.setNotices = function ( notices
) {
9199 this.notices
= notices
.slice();
9200 this.updateMessages();
9205 * Update the rendering of error and notice messages.
9209 OO
.ui
.FieldLayout
.prototype.updateMessages = function () {
9211 this.$messages
.empty();
9213 if ( this.errors
.length
|| this.notices
.length
) {
9214 this.$body
.after( this.$messages
);
9216 this.$messages
.remove();
9220 for ( i
= 0; i
< this.notices
.length
; i
++ ) {
9221 this.$messages
.append( this.makeMessage( 'notice', this.notices
[ i
] ) );
9223 for ( i
= 0; i
< this.errors
.length
; i
++ ) {
9224 this.$messages
.append( this.makeMessage( 'error', this.errors
[ i
] ) );
9229 * ActionFieldLayouts are used with OO.ui.FieldsetLayout. The layout consists of a field-widget, a button,
9230 * and an optional label and/or help text. The field-widget (e.g., a {@link OO.ui.TextInputWidget TextInputWidget}),
9231 * is required and is specified before any optional configuration settings.
9233 * Labels can be aligned in one of four ways:
9235 * - **left**: The label is placed before the field-widget and aligned with the left margin.
9236 * A left-alignment is used for forms with many fields.
9237 * - **right**: The label is placed before the field-widget and aligned to the right margin.
9238 * A right-alignment is used for long but familiar forms which users tab through,
9239 * verifying the current field with a quick glance at the label.
9240 * - **top**: The label is placed above the field-widget. A top-alignment is used for brief forms
9241 * that users fill out from top to bottom.
9242 * - **inline**: The label is placed after the field-widget and aligned to the left.
9243 * An inline-alignment is best used with checkboxes or radio buttons.
9245 * Help text is accessed via a help icon that appears in the upper right corner of the rendered field layout when help
9246 * text is specified.
9249 * // Example of an ActionFieldLayout
9250 * var actionFieldLayout = new OO.ui.ActionFieldLayout(
9251 * new OO.ui.TextInputWidget( {
9252 * placeholder: 'Field widget'
9254 * new OO.ui.ButtonWidget( {
9258 * label: 'An ActionFieldLayout. This label is aligned top',
9260 * help: 'This is help text'
9264 * $( 'body' ).append( actionFieldLayout.$element );
9267 * @extends OO.ui.FieldLayout
9270 * @param {OO.ui.Widget} fieldWidget Field widget
9271 * @param {OO.ui.ButtonWidget} buttonWidget Button widget
9273 OO
.ui
.ActionFieldLayout
= function OoUiActionFieldLayout( fieldWidget
, buttonWidget
, config
) {
9274 // Allow passing positional parameters inside the config object
9275 if ( OO
.isPlainObject( fieldWidget
) && config
=== undefined ) {
9276 config
= fieldWidget
;
9277 fieldWidget
= config
.fieldWidget
;
9278 buttonWidget
= config
.buttonWidget
;
9281 // Parent constructor
9282 OO
.ui
.ActionFieldLayout
.parent
.call( this, fieldWidget
, config
);
9285 this.buttonWidget
= buttonWidget
;
9286 this.$button
= $( '<div>' );
9287 this.$input
= $( '<div>' );
9291 .addClass( 'oo-ui-actionFieldLayout' );
9293 .addClass( 'oo-ui-actionFieldLayout-button' )
9294 .append( this.buttonWidget
.$element
);
9296 .addClass( 'oo-ui-actionFieldLayout-input' )
9297 .append( this.fieldWidget
.$element
);
9299 .append( this.$input
, this.$button
);
9304 OO
.inheritClass( OO
.ui
.ActionFieldLayout
, OO
.ui
.FieldLayout
);
9307 * FieldsetLayouts are composed of one or more {@link OO.ui.FieldLayout FieldLayouts},
9308 * which each contain an individual widget and, optionally, a label. Each Fieldset can be
9309 * configured with a label as well. For more information and examples,
9310 * please see the [OOjs UI documentation on MediaWiki][1].
9313 * // Example of a fieldset layout
9314 * var input1 = new OO.ui.TextInputWidget( {
9315 * placeholder: 'A text input field'
9318 * var input2 = new OO.ui.TextInputWidget( {
9319 * placeholder: 'A text input field'
9322 * var fieldset = new OO.ui.FieldsetLayout( {
9323 * label: 'Example of a fieldset layout'
9326 * fieldset.addItems( [
9327 * new OO.ui.FieldLayout( input1, {
9328 * label: 'Field One'
9330 * new OO.ui.FieldLayout( input2, {
9331 * label: 'Field Two'
9334 * $( 'body' ).append( fieldset.$element );
9336 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Fields_and_Fieldsets
9339 * @extends OO.ui.Layout
9340 * @mixins OO.ui.mixin.IconElement
9341 * @mixins OO.ui.mixin.LabelElement
9342 * @mixins OO.ui.mixin.GroupElement
9345 * @param {Object} [config] Configuration options
9346 * @cfg {OO.ui.FieldLayout[]} [items] An array of fields to add to the fieldset. See OO.ui.FieldLayout for more information about fields.
9348 OO
.ui
.FieldsetLayout
= function OoUiFieldsetLayout( config
) {
9349 // Configuration initialization
9350 config
= config
|| {};
9352 // Parent constructor
9353 OO
.ui
.FieldsetLayout
.parent
.call( this, config
);
9355 // Mixin constructors
9356 OO
.ui
.mixin
.IconElement
.call( this, config
);
9357 OO
.ui
.mixin
.LabelElement
.call( this, config
);
9358 OO
.ui
.mixin
.GroupElement
.call( this, config
);
9360 if ( config
.help
) {
9361 this.popupButtonWidget
= new OO
.ui
.PopupButtonWidget( {
9362 classes
: [ 'oo-ui-fieldsetLayout-help' ],
9367 this.popupButtonWidget
.getPopup().$body
.append(
9369 .text( config
.help
)
9370 .addClass( 'oo-ui-fieldsetLayout-help-content' )
9372 this.$help
= this.popupButtonWidget
.$element
;
9374 this.$help
= $( [] );
9379 .addClass( 'oo-ui-fieldsetLayout' )
9380 .prepend( this.$help
, this.$icon
, this.$label
, this.$group
);
9381 if ( Array
.isArray( config
.items
) ) {
9382 this.addItems( config
.items
);
9388 OO
.inheritClass( OO
.ui
.FieldsetLayout
, OO
.ui
.Layout
);
9389 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.IconElement
);
9390 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.LabelElement
);
9391 OO
.mixinClass( OO
.ui
.FieldsetLayout
, OO
.ui
.mixin
.GroupElement
);
9394 * FormLayouts are used to wrap {@link OO.ui.FieldsetLayout FieldsetLayouts} when you intend to use browser-based
9395 * form submission for the fields instead of handling them in JavaScript. Form layouts can be configured with an
9396 * HTML form action, an encoding type, and a method using the #action, #enctype, and #method configs, respectively.
9397 * See the [OOjs UI documentation on MediaWiki] [1] for more information and examples.
9399 * Only widgets from the {@link OO.ui.InputWidget InputWidget} family support form submission. It
9400 * includes standard form elements like {@link OO.ui.CheckboxInputWidget checkboxes}, {@link
9401 * OO.ui.RadioInputWidget radio buttons} and {@link OO.ui.TextInputWidget text fields}, as well as
9402 * some fancier controls. Some controls have both regular and InputWidget variants, for example
9403 * OO.ui.DropdownWidget and OO.ui.DropdownInputWidget – only the latter support form submission and
9404 * often have simplified APIs to match the capabilities of HTML forms.
9405 * See the [OOjs UI Inputs documentation on MediaWiki] [2] for more information about InputWidgets.
9407 * [1]: https://www.mediawiki.org/wiki/OOjs_UI/Layouts/Forms
9408 * [2]: https://www.mediawiki.org/wiki/OOjs_UI/Widgets/Inputs
9411 * // Example of a form layout that wraps a fieldset layout
9412 * var input1 = new OO.ui.TextInputWidget( {
9413 * placeholder: 'Username'
9415 * var input2 = new OO.ui.TextInputWidget( {
9416 * placeholder: 'Password',
9419 * var submit = new OO.ui.ButtonInputWidget( {
9423 * var fieldset = new OO.ui.FieldsetLayout( {
9424 * label: 'A form layout'
9426 * fieldset.addItems( [
9427 * new OO.ui.FieldLayout( input1, {
9428 * label: 'Username',
9431 * new OO.ui.FieldLayout( input2, {
9432 * label: 'Password',
9435 * new OO.ui.FieldLayout( submit )
9437 * var form = new OO.ui.FormLayout( {
9438 * items: [ fieldset ],
9439 * action: '/api/formhandler',
9442 * $( 'body' ).append( form.$element );
9445 * @extends OO.ui.Layout
9446 * @mixins OO.ui.mixin.GroupElement
9449 * @param {Object} [config] Configuration options
9450 * @cfg {string} [method] HTML form `method` attribute
9451 * @cfg {string} [action] HTML form `action` attribute
9452 * @cfg {string} [enctype] HTML form `enctype` attribute
9453 * @cfg {OO.ui.FieldsetLayout[]} [items] Fieldset layouts to add to the form layout.
9455 OO
.ui
.FormLayout
= function OoUiFormLayout( config
) {
9458 // Configuration initialization
9459 config
= config
|| {};
9461 // Parent constructor
9462 OO
.ui
.FormLayout
.parent
.call( this, config
);
9464 // Mixin constructors
9465 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
9468 this.$element
.on( 'submit', this.onFormSubmit
.bind( this ) );
9470 // Make sure the action is safe
9471 action
= config
.action
;
9472 if ( action
!== undefined && !OO
.ui
.isSafeUrl( action
) ) {
9473 action
= './' + action
;
9478 .addClass( 'oo-ui-formLayout' )
9480 method
: config
.method
,
9482 enctype
: config
.enctype
9484 if ( Array
.isArray( config
.items
) ) {
9485 this.addItems( config
.items
);
9491 OO
.inheritClass( OO
.ui
.FormLayout
, OO
.ui
.Layout
);
9492 OO
.mixinClass( OO
.ui
.FormLayout
, OO
.ui
.mixin
.GroupElement
);
9497 * A 'submit' event is emitted when the form is submitted.
9502 /* Static Properties */
9504 OO
.ui
.FormLayout
.static.tagName
= 'form';
9509 * Handle form submit events.
9512 * @param {jQuery.Event} e Submit event
9515 OO
.ui
.FormLayout
.prototype.onFormSubmit = function () {
9516 if ( this.emit( 'submit' ) ) {
9522 * PanelLayouts expand to cover the entire area of their parent. They can be configured with scrolling, padding,
9523 * and a frame, and are often used together with {@link OO.ui.StackLayout StackLayouts}.
9526 * // Example of a panel layout
9527 * var panel = new OO.ui.PanelLayout( {
9531 * $content: $( '<p>A panel layout with padding and a frame.</p>' )
9533 * $( 'body' ).append( panel.$element );
9536 * @extends OO.ui.Layout
9539 * @param {Object} [config] Configuration options
9540 * @cfg {boolean} [scrollable=false] Allow vertical scrolling
9541 * @cfg {boolean} [padded=false] Add padding between the content and the edges of the panel.
9542 * @cfg {boolean} [expanded=true] Expand the panel to fill the entire parent element.
9543 * @cfg {boolean} [framed=false] Render the panel with a frame to visually separate it from outside content.
9545 OO
.ui
.PanelLayout
= function OoUiPanelLayout( config
) {
9546 // Configuration initialization
9547 config
= $.extend( {
9554 // Parent constructor
9555 OO
.ui
.PanelLayout
.parent
.call( this, config
);
9558 this.$element
.addClass( 'oo-ui-panelLayout' );
9559 if ( config
.scrollable
) {
9560 this.$element
.addClass( 'oo-ui-panelLayout-scrollable' );
9562 if ( config
.padded
) {
9563 this.$element
.addClass( 'oo-ui-panelLayout-padded' );
9565 if ( config
.expanded
) {
9566 this.$element
.addClass( 'oo-ui-panelLayout-expanded' );
9568 if ( config
.framed
) {
9569 this.$element
.addClass( 'oo-ui-panelLayout-framed' );
9575 OO
.inheritClass( OO
.ui
.PanelLayout
, OO
.ui
.Layout
);
9580 * Focus the panel layout
9582 * The default implementation just focuses the first focusable element in the panel
9584 OO
.ui
.PanelLayout
.prototype.focus = function () {
9585 OO
.ui
.findFocusable( this.$element
).focus();
9589 * HorizontalLayout arranges its contents in a single line (using `display: inline-block` for its
9590 * items), with small margins between them. Convenient when you need to put a number of block-level
9591 * widgets on a single line next to each other.
9593 * Note that inline elements, such as OO.ui.ButtonWidgets, do not need this wrapper.
9596 * // HorizontalLayout with a text input and a label
9597 * var layout = new OO.ui.HorizontalLayout( {
9599 * new OO.ui.LabelWidget( { label: 'Label' } ),
9600 * new OO.ui.TextInputWidget( { value: 'Text' } )
9603 * $( 'body' ).append( layout.$element );
9606 * @extends OO.ui.Layout
9607 * @mixins OO.ui.mixin.GroupElement
9610 * @param {Object} [config] Configuration options
9611 * @cfg {OO.ui.Widget[]|OO.ui.Layout[]} [items] Widgets or other layouts to add to the layout.
9613 OO
.ui
.HorizontalLayout
= function OoUiHorizontalLayout( config
) {
9614 // Configuration initialization
9615 config
= config
|| {};
9617 // Parent constructor
9618 OO
.ui
.HorizontalLayout
.parent
.call( this, config
);
9620 // Mixin constructors
9621 OO
.ui
.mixin
.GroupElement
.call( this, $.extend( {}, config
, { $group
: this.$element
} ) );
9624 this.$element
.addClass( 'oo-ui-horizontalLayout' );
9625 if ( Array
.isArray( config
.items
) ) {
9626 this.addItems( config
.items
);
9632 OO
.inheritClass( OO
.ui
.HorizontalLayout
, OO
.ui
.Layout
);
9633 OO
.mixinClass( OO
.ui
.HorizontalLayout
, OO
.ui
.mixin
.GroupElement
);