Class: TagMultiselectWidget

.ui.TagMultiselectWidget(config)

new TagMultiselectWidget(config)

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.

Parameters:
Name Type Description
config Object

Configuration object

Properties
Name Type Attributes Default Description
input Object <optional>

Configuration options for the input widget
inputWidget OO.ui.InputWidget <optional>

An optional input widget. If given, it will replace the input widget used in the TagMultiselectWidget. If not given, TagMultiselectWidget creates its own.
inputPosition boolean <optional>
 'inline'

Position of the input. Options are:

- inline: The input is invisible, but exists inside the tag list, so
    the user types into the tag groups to add tags.
- outline: The input is underneath the tag area.
- none: No input supplied
allowEditTags boolean <optional>
 true

Allow editing of the tags by clicking them
allowArbitrary boolean <optional>
 false

Allow data items to be added even if not present in the menu.
allowedValues Array.<Object> <optional>

An array representing the allowed items by their datas.
allowDuplicates boolean <optional>
 false

Allow duplicate items to be added
allowDisplayInvalidTags boolean <optional>
 false

Allow the display of invalid tags. These tags will display with an invalid state, and the widget as a whole will have an invalid state if any invalid tags are present.
allowReordering boolean <optional>
 true

Allow reordering of the items
selected Array.<Object> | Array.<String> <optional>

A set of selected tags. If given, these will appear in the tag list on initialization, as long as they pass the validity tests.
Mixes In:
Source:
Example
// Example: A basic TagMultiselectWidget.
    var widget = new OO.ui.TagMultiselectWidget( {
        inputPosition: 'outline',
        allowedValues: [ 'Option 1', 'Option 2', 'Option 3' ],
        selected: [ 'Option 1' ]
    } );
    $( 'body' ).append( widget.$element );

Extends

Methods

addAllowedValue(value)

Add a value to the allowed values list

Parameters:
Name Type Description
value string

Allowed data value
Source:

addTag(data, labelopt) → {boolean}

Add tag to the display area

Parameters:
Name Type Attributes Description
data string | Object

Tag data
label string <optional>

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:

(protected) createTagItemWidget(data, label) → {OO.ui.TagItemWidget}

Construct a OO.ui.TagItemWidget (or a subclass thereof) from given label and data.

Parameters:
Name Type Description
data string

Item data
label string

The label text.
Source:
Returns:
Type
OO.ui.TagItemWidget

doInputArrow(e, direction, withMetaKeyopt)

Perform an action after the arrow key on the input, select the previous or next item from the input. See #getPreviousItem and #getNextItem

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 'ctrl'
Source:

doInputBackspace(e, withMetaKeyopt) → {boolean}

Perform an action responding to 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 'ctrl'
Source:
Returns:

Whether to prevent defaults

Type
boolean

doInputEnter(e, withMetaKeyopt) → {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 'ctrl'
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.<string>}

Get the allowed values list

Source:
Returns:

Allowed data values

Type
Array.<string>

getClosestScrollableElementContainer() → {HTMLElement}

Get closest scrollable container.

Inherited From:
Source:
Returns:

Closest scrollable container

Type
HTMLElement

getData() → {Mixed}

Get element data.

Inherited From:
Source:
Returns:

Element data

Type
Mixed

getElementDocument() → {HTMLDocument}

Get the DOM document.

Inherited From:
Source:
Returns:

Document object

Type
HTMLDocument

getElementGroup() → {OO.ui.mixin.GroupElement|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

getElementWindow() → {Window}

Get the DOM window.

Inherited From:
Source:
Returns:

Window object

Type
Window

getInputId() → {string|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

(protected) getNextItem(itemopt) → {OO.ui.Widget}

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

(protected) getPreviousItem(itemopt) → {OO.ui.Widget}

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

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.<string>|Array.<Object>}

Get the datas of the currently selected items

Source:
Returns:

Datas of currently selected items

Type
Array.<string> | Array.<Object>

isAllowedData(data) → {boolean}

Check whether a given value is allowed to be added

Parameters:
Name Type Description
data string | Object

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 string | Object

Requested value
Source:
Returns:

Value is duplicate

Type
boolean

isElementAttached() → {boolean}

Check if the element is attached to the DOM

Inherited From:
Source:
Returns:

The element is attached to the DOM

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:

onTagNavigate(item, direction)

Respond to navigate event on the tag

Parameters:
Name Type Description
item OO.ui.TagItemWidget

Removed tag
direction string

Direction of movement; 'forwards' or 'backwards'
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:

(protected) restorePreInfuseState(state)

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(configopt) → {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)

Set element data.

Parameters:
Name Type Description
data Mixed

Element data
Inherited From:
Source:

setDisabled(disabled)

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 Description
disabled boolean

Disable widget
Overrides:
Source:

setElementGroup(group)

Set group element is in.

Parameters:
Name Type Description
group OO.ui.mixin.GroupElement | null

Group element, null if none
Inherited From:
Source:

setElementId(id)

Set the element has an 'id' attribute.

Parameters:
Name Type Description
id string
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:

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(showopt)

Toggle visibility of an element.

Parameters:
Name Type Attributes Description
show boolean <optional>

Make element visible, omit to toggle visibility
Inherited From:
Source:
Fires:
  • event:visible

toggleValid(validopt)

Set the valid state of this item

Parameters:
Name Type Attributes Description
valid boolean <optional>

Item is valid
Source:
Fires:

updateDisabled()

Update the disabled state, in case of changes in parent widget.

Inherited From:
Source:

updateThemeClasses()

Update the theme-provided classes.

Inherited From:
Source: