Extends
Constructor
new OO.ui.TagMultiselectWidget(config)
#
Hierarchy
Children
A basic tag multiselect widget, similar in concept to
combo box widget
that allows the user to add multiple values
that are displayed in a tag area.
This widget is a base widget; see MenuTagMultiselectWidget
and PopupTagMultiselectWidget
for the implementations
that use a menu and a popup respectively.
Example
// A TagMultiselectWidget.
const widget = new OO.ui.TagMultiselectWidget( {
inputPosition: 'outline',
allowedValues: [ 'Option 1', 'Option 2', 'Option 3' ],
selected: [ 'Option 1' ]
} );
$( document.body ).append( widget.$element );
Parameters:
Name | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
config |
Object | Configuration object Properties:
|
A basic tag multiselect widget, similar in concept to
combo box widget
that allows the user to add multiple values
that are displayed in a tag area.
Properties
allowedInputPositionsstatic
#
Allowed input positions.
- inline: The input is inside the tag list
- outline: The input is under the tag list
- none: There is no input
Properties:
Type | Description |
---|---|
Array |
- Source:
flags
#
Initial value to pass to setFlags if no value is provided in config.
Properties:
- Mixes in:
- Source:
icon
#
The symbolic name of the icon (e.g., ‘remove’ or ‘menu’), or a map of symbolic names. A map
is used for i18n purposes and contains a default
icon name and additional names keyed by
language code. The default
name is used when no icon is keyed by the user's language.
Example of an i18n map:
{ default: 'bold-a', en: 'bold-b', de: 'bold-f' }
Note: the static property will be overridden if the #icon configuration is used.
Properties:
Type | Description |
---|---|
Object | string |
- Mixes in:
- Source:
iconTitle
#
The icon title, displayed when users move the mouse over the icon. The value can be text, a
function that returns title text, or null
for no title.
The static property will be overridden if the #iconTitle configuration is used.
Properties:
Type | Description |
---|---|
string
|
function
|
null
|
- Mixes in:
- Source:
indicator
#
Symbolic name of the indicator (e.g. ‘required’ or ‘down’). The static property will be overridden if the #indicator configuration is used.
Properties:
Type | Description |
---|---|
string
|
null
|
- Mixes in:
- Source:
indicatorTitle
#
A text string used as the indicator title, a function that returns title text, or null
for no title. The static property will be overridden if the #indicatorTitle configuration is
used.
Properties:
Type | Description |
---|---|
string
|
function
|
null
|
- Mixes in:
- Source:
A text string used as the indicator title, a function that returns title text, or null
for no title.
title
#
The title text, a function that returns text, or null
for no title. The value of the static
property is overridden if the #title config option is used.
If the element has a default title (e.g. <input type=file>
), null
will allow that title to be
shown. Use empty string to suppress it.
Properties:
Type | Description |
---|---|
string
|
function
|
null
|
- Mixes in:
- Source:
null
for no title.
Methods
addAllowedValue(value)
#
Add a value to the allowed values list
Parameters:
Name | Type | Description |
---|---|---|
value |
any | Allowed data value |
- Source:
addTag(data, [label]) → {boolean}
#
Add tag to the display area.
Performs a validation check on the tag to be added.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
data |
any | Tag data |
||
label |
string | jQuery |
optional |
data | Tag label. If no label is provided, the stringified version of the data will be used instead. |
- Source:
Returns:
Item was added successfully
- Type
- boolean
addTagFromInput()
#
Add tag from input value
- Source:
checkValidity() → {boolean}
#
Check whether all items in the widget are valid
- Source:
Returns:
Widget is valid
- Type
- boolean
clearInput()
#
Clear the input
- Source:
createTagItemWidget(data, [label]) → {OO.ui.TagItemWidget}protected
#
Construct a OO.ui.TagItemWidget (or a subclass thereof) from given label and data.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
data |
any | Item data |
||
label |
string | jQuery |
optional |
data | The label text or JQuery collection. |
- Source:
Returns:
- Type
- OO.ui.TagItemWidget
doInputArrow(e, direction, [withMetaKey])
#
Perform an action after the Left/Right arrow key on the input, select the previous item from the input. See #getPreviousItem
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
e |
jQuery.Event | Event data |
|
direction |
string | Direction of the movement; forwards or backwards |
|
withMetaKey |
boolean |
optional |
Whether this key was pressed with a meta key like Control |
- Source:
Perform an action after the Left/Right arrow key on the input, select the previous item from the input.
doInputBackspace(e, [withMetaKey]) → {boolean}
#
Perform an action responding to the Backspace key on the input
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
e |
jQuery.Event | Event data |
|
withMetaKey |
boolean |
optional |
Whether this key was pressed with a meta key like Control |
- Source:
Returns:
Whether to prevent defaults
- Type
- boolean
doInputEnter(e, [withMetaKey]) → {boolean}
#
Perform an action after the Enter key on the input
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
e |
jQuery.Event | Event data |
|
withMetaKey |
boolean |
optional |
Whether this key was pressed with a meta key like Control |
- Source:
Returns:
Whether to prevent defaults
- Type
- boolean
doInputEscape(e)
#
Perform an action after the Escape key on the input
Parameters:
Name | Type | Description |
---|---|---|
e |
jQuery.Event | Event data |
- Source:
getAllowedValues() → {Array.<any>}
#
getClosestScrollableElementContainer() → {HTMLElement}
#
Get closest scrollable container.
- Inherited from:
- Source:
Returns:
Closest scrollable container
- Type
- HTMLElement
getData() → {any}
#
Get element data.
- Inherited from:
- Source:
Returns:
Element data
- Type
- any
getElementDocument() → {HTMLDocument}
#
getElementGroup() → {OO.ui.mixin.GroupElement|null
}
#
null
}
#
Get group element is in.
- Inherited from:
- Source:
Returns:
Group element, null if none
- Type
-
OO.ui.mixin.GroupElement
|
null
getElementId() → {string}
#
Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.
- Inherited from:
- Source:
Returns:
- Type
- string
Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.
getElementWindow() → {Window}
#
getInputId() → {string|null
}
#
null
}
#
Get an ID of a labelable node which is part of this widget, if any, to be used for <label for>
value.
If this function returns null, the widget should have a meaningful #simulateLabelClick method instead.
- Inherited from:
- Source:
Returns:
The ID of the labelable element
- Type
-
string
|
null
Get an ID of a labelable node which is part of this widget, if any, to be used for <label for>
value.
getNextItem([item]) → {OO.ui.Widget}protected
#
Given an item, returns the item after it. If the item is already the
last item, return this.input
. If no item is passed, returns the
very first item.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
item |
OO.ui.TagItemWidget |
optional |
Tag item |
- Source:
Returns:
The next widget available.
- Type
- OO.ui.Widget
getPreviousItem([item]) → {OO.ui.Widget}protected
#
Given an item, returns the item before it. If the item is already the
first item, return this.input
. If no item is passed, returns the
very last item.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
item |
OO.ui.TagItemWidget |
optional |
Tag item |
- Source:
Returns:
The previous widget available.
- Type
- OO.ui.Widget
getTagInfoFromInput() → {Object}
#
Get data and label for a new tag from the input value
- Source:
Returns:
The data and label for a tag
- Type
- Object
getTagName() → {string}
#
Get the HTML tag name.
Override this method to base the result on instance information.
- Inherited from:
- Source:
Returns:
HTML tag name
- Type
- string
getValue() → {Array.<any>}
#
Get the datas of the currently selected items
- Source:
Returns:
Datas of currently selected items
- Type
- Array.<any>
isAllowedData(data) → {boolean}
#
Check whether a given value is allowed to be added
Parameters:
Name | Type | Description |
---|---|---|
data |
any | Requested value |
- Source:
Returns:
Value is allowed
- Type
- boolean
isDisabled() → {boolean}
#
Check if the widget is disabled.
- Inherited from:
- Source:
Returns:
Widget is disabled
- Type
- boolean
isDuplicateData(data) → {boolean}
#
Check whether the given value is a duplicate of an existing tag already in the list.
Parameters:
Name | Type | Description |
---|---|---|
data |
any | Requested value |
- Source:
Returns:
Value is duplicate
- Type
- boolean
Check whether the given value is a duplicate of an existing tag already in the list.
isElementAttached() → {boolean}
#
Check if the element is attached to the DOM
- Inherited from:
- Source:
Returns:
The element is attached to the DOM
- Type
- boolean
isUnderLimit() → {boolean}
#
Check whether the number of current tags is within the limit.
- Source:
Returns:
True if current tag count is within the limit or if 'tagLimit' is not set
- Type
- boolean
isValid() → {boolean}
#
Get the current valid state of the widget
- Source:
Returns:
Widget is valid
- Type
- boolean
isVisible() → {boolean}
#
Check if element is visible.
- Inherited from:
- Source:
Returns:
element is visible
- Type
- boolean
onChangeTags()
#
Respond to change event, where items were added, removed, or cleared.
- Source:
onInputBlur()
#
Respond to input blur event
- Source:
onInputFocus()
#
Respond to input focus event
- Source:
onTagFixed(item)
#
Respond to item fixed state change
Parameters:
Name | Type | Description |
---|---|---|
item |
OO.ui.TagItemWidget | Selected item |
- Source:
onTagRemove(item)
#
Respond to tag remove event
Parameters:
Name | Type | Description |
---|---|---|
item |
OO.ui.TagItemWidget | Removed tag |
- Source:
onTagSelect(item)
#
Respond to item select event
Parameters:
Name | Type | Description |
---|---|---|
item |
OO.ui.TagItemWidget | Selected item |
- Source:
removeTagByData(data)
#
Remove tag by its data property.
Parameters:
Name | Type | Description |
---|---|---|
data |
string | Object | Tag data |
- Source:
restorePreInfuseState(state)protected
#
Restore the pre-infusion dynamic state for this widget.
This method is called after #$element has been inserted into DOM. The parameter is the return value of #gatherPreInfuseState.
Parameters:
Name | Type | Description |
---|---|---|
state |
Object |
- Inherited from:
- Source:
scrollElementIntoView([config]) → {jQuery.Promise}
#
Scroll element into view.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
config |
Object |
optional |
Configuration options |
- Inherited from:
- Source:
Returns:
Promise which resolves when the scroll is complete
- Type
- jQuery.Promise
setData(data) → {OO.ui.Element}chainable
#
Set element data.
Parameters:
Name | Type | Description |
---|---|---|
data |
any | Element data |
- Inherited from:
- Source:
Returns:
The element, for chaining
- Type
- OO.ui.Element
setDisabled([disabled]) → {OO.ui.Widget}chainable
#
Set the 'disabled' state of the widget.
When a widget is disabled, it cannot be used and its appearance is updated to reflect this state.
Parameters:
Name | Type | Attributes | Default | Description |
---|---|---|---|---|
disabled |
boolean |
optional |
false | Disable widget |
- Overrides:
- Source:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
setElementGroup(group) → {OO.ui.Element}chainable
#
Set group element is in.
Parameters:
Name | Type | Description |
---|---|---|
group |
OO.ui.mixin.GroupElement
|
null
|
Group element, null if none |
- Inherited from:
- Source:
Returns:
The element, for chaining
- Type
- OO.ui.Element
setElementId(id) → {OO.ui.Element}chainable
#
Set the element has an 'id' attribute.
Parameters:
Name | Type | Description |
---|---|---|
id |
string |
- Inherited from:
- Source:
Returns:
The element, for chaining
- Type
- OO.ui.Element
setLabelledBy(id)
#
Set the element with the given ID as a label for this widget.
Parameters:
Name | Type | Description |
---|---|---|
id |
string
|
null
|
- Inherited from:
- Source:
setValue(valueObject)
#
Set the value of this widget by datas.
Parameters:
Name | Type | Description |
---|---|---|
valueObject |
string | Array.<string> | Object | Array.<Object> | An object representing the data and label of the value. If the widget allows arbitrary values, the items will be added as-is. Otherwise, the data value will be checked against allowedValues. This object must contain at least a data key. Example: { data: 'foo', label: 'Foo item' } For multiple items, use an array of objects. For example: [ { data: 'foo', label: 'Foo item' }, { data: 'bar', label: 'Bar item' } ] Value can also be added with plaintext array, for example: [ 'foo', 'bar', 'bla' ] or a single string, like 'foo' |
- Source:
simulateLabelClick()
#
Simulate the behavior of clicking on a label (a HTML <label>
element) bound to this input.
HTML only allows <label>
to act on specific "labelable" elements; complex widgets might need to
override this method to provide intuitive, accessible behavior.
By default, this does nothing. OO.ui.mixin.TabIndexedElement overrides it for focusable widgets. Individual widgets may override it too.
This method is called by OO.ui.LabelWidget and OO.ui.FieldLayout. It should not be called directly.
- Inherited from:
- Source:
<label>
element) bound to this input.
supports(methods) → {boolean}
#
Check if element supports one or more methods.
Parameters:
Name | Type | Description |
---|---|---|
methods |
string | Array.<string> | Method or list of methods to check |
- Inherited from:
- Source:
Returns:
All methods are supported
- Type
- boolean
toggle([show]) → {OO.ui.Element}chainable
#
Toggle visibility of an element.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
show |
boolean |
optional |
Make element visible, omit to toggle visibility |
- Inherited from:
- Source:
Returns:
The element, for chaining
- Type
- OO.ui.Element
Fires:
toggleValid([valid])
#
Set the valid state of this item
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
valid |
boolean |
optional |
Item is valid, omit to toggle |
- Source:
Fires:
updateDisabled() → {OO.ui.Widget}chainable
#
Update the disabled state, in case of changes in parent widget.
- Inherited from:
- Source:
Returns:
The widget, for chaining
- Type
- OO.ui.Widget
updateThemeClasses()
#
Update the theme-provided classes.
This is called in element mixins and widget classes any time state changes. Updating is debounced, minimizing overhead of changing multiple attributes and guaranteeing that theme updates do not occur within an element's constructor
- Inherited from:
- Source:
Events
disable(disabled)
#
A 'disable' event is emitted when the disabled state of the widget changes (i.e. on disable and enable).
Parameters:
Name | Type | Description |
---|---|---|
disabled |
boolean | Widget is disabled |
- Inherited from:
- Source:
A 'disable' event is emitted when the disabled state of the widget changes (i.e.
toggle(visible)
#
A 'toggle' event is emitted when the visibility of the widget changes.
Parameters:
Name | Type | Description |
---|---|---|
visible |
boolean | Widget is visible |
- Inherited from:
- Source: