Expand all

OO.ui.Toolbar

Extends

Constructor

new OO.ui.Toolbar(toolFactory, toolGroupFactory, [config]) #

Toolbars are complex interface components that permit users to easily access a variety of tools (e.g., formatting commands) and actions, which are additional commands that are part of the toolbar, but not configured as tools.

Individual tools are customized and then registered with a tool factory, which creates the tools on demand. Each tool has a symbolic name (used when registering the tool), a title (e.g., ‘Insert image’), and an icon.

Individual tools are organized in toolgroups, which can be menus of tools, lists of tools, or a single bar of tools. The arrangement and order of the toolgroups is customized when the toolbar is set up. Tools can be presented in any order, but each can only appear once in the toolbar.

The toolbar can be synchronized with the state of the external "application", like a text editor's editing area, marking tools as active/inactive (e.g. a 'bold' tool would be shown as active when the text cursor was inside bolded text) or enabled/disabled (e.g. a table caption tool would be disabled while the user is not editing a table). A state change is signalled by emitting the 'updateState' event, which calls Tools' onUpdateState method.

Examples

The following is an example of a basic toolbar.

    // Example of a toolbar
    // Create the toolbar
    const toolFactory = new OO.ui.ToolFactory();
    const toolGroupFactory = new OO.ui.ToolGroupFactory();
    const toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );

    // We will be placing status text in this element when tools are used
    const $area = $( '<p>' ).text( 'Toolbar example' );

    // Define the tools that we're going to place in our toolbar

    // Create a class inheriting from OO.ui.Tool
    function SearchTool() {
        SearchTool.super.apply( this, arguments );
    }
    OO.inheritClass( SearchTool, OO.ui.Tool );
    // Each tool must have a 'name' (used as an internal identifier, see later) and at least one
    // of 'icon' and 'title' (displayed icon and text).
    SearchTool.static.name = 'search';
    SearchTool.static.icon = 'search';
    SearchTool.static.title = 'Search...';
    // Defines the action that will happen when this tool is selected (clicked).
    SearchTool.prototype.onSelect = function () {
        $area.text( 'Search tool clicked!' );
        // Never display this tool as "active" (selected).
        this.setActive( false );
    };
    SearchTool.prototype.onUpdateState = function () {};
    // Make this tool available in our toolFactory and thus our toolbar
    toolFactory.register( SearchTool );

    // Register two more tools, nothing interesting here
    function SettingsTool() {
        SettingsTool.super.apply( this, arguments );
    }
    OO.inheritClass( SettingsTool, OO.ui.Tool );
    SettingsTool.static.name = 'settings';
    SettingsTool.static.icon = 'settings';
    SettingsTool.static.title = 'Change settings';
    SettingsTool.prototype.onSelect = function () {
        $area.text( 'Settings tool clicked!' );
        this.setActive( false );
    };
    SettingsTool.prototype.onUpdateState = function () {};
    toolFactory.register( SettingsTool );

    // Register two more tools, nothing interesting here
    function StuffTool() {
        StuffTool.super.apply( this, arguments );
    }
    OO.inheritClass( StuffTool, OO.ui.Tool );
    StuffTool.static.name = 'stuff';
    StuffTool.static.icon = 'ellipsis';
    StuffTool.static.title = 'More stuff';
    StuffTool.prototype.onSelect = function () {
        $area.text( 'More stuff tool clicked!' );
        this.setActive( false );
    };
    StuffTool.prototype.onUpdateState = function () {};
    toolFactory.register( StuffTool );

    // This is a PopupTool. Rather than having a custom 'onSelect' action, it will display a
    // little popup window (a PopupWidget).
    function HelpTool( toolGroup, config ) {
        OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
            padded: true,
            label: 'Help',
            head: true
        } }, config ) );
        this.popup.$body.append( '<p>I am helpful!</p>' );
    }
    OO.inheritClass( HelpTool, OO.ui.PopupTool );
    HelpTool.static.name = 'help';
    HelpTool.static.icon = 'help';
    HelpTool.static.title = 'Help';
    toolFactory.register( HelpTool );

    // Finally define which tools and in what order appear in the toolbar. Each tool may only be
    // used once (but not all defined tools must be used).
    toolbar.setup( [
        {
            // 'bar' tool groups display tools' icons only, side-by-side.
            type: 'bar',
            include: [ 'search', 'help' ]
        },
        {
            // 'list' tool groups display both the titles and icons, in a dropdown list.
            type: 'list',
            indicator: 'down',
            label: 'More',
            include: [ 'settings', 'stuff' ]
        }
        // Note how the tools themselves are toolgroup-agnostic - the same tool can be displayed
        // either in a 'list' or a 'bar'. There is a 'menu' tool group too, not showcased here,
        // since it's more complicated to use. (See the next example snippet on this page.)
    ] );

    // Create some UI around the toolbar and place it in the document
    const frame = new OO.ui.PanelLayout( {
        expanded: false,
        framed: true
    } );
    const contentFrame = new OO.ui.PanelLayout( {
        expanded: false,
        padded: true
    } );
    frame.$element.append(
        toolbar.$element,
        contentFrame.$element.append( $area )
    );
    $( document.body ).append( frame.$element );

    // Here is where the toolbar is actually built. This must be done after inserting it into the
    // document.
    toolbar.initialize();
    toolbar.emit( 'updateState' );

    

The following example extends the previous one to illustrate 'menu' toolgroups and the usage of 'updateState' event.

    // Create the toolbar
    const toolFactory = new OO.ui.ToolFactory();
    const toolGroupFactory = new OO.ui.ToolGroupFactory();
    const toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );

    // We will be placing status text in this element when tools are used
    const $area = $( '<p>' ).text( 'Toolbar example' );

    // Define the tools that we're going to place in our toolbar

    // Create a class inheriting from OO.ui.Tool
    function SearchTool() {
        SearchTool.super.apply( this, arguments );
    }
    OO.inheritClass( SearchTool, OO.ui.Tool );
    // Each tool must have a 'name' (used as an internal identifier, see later) and at least one
    // of 'icon' and 'title' (displayed icon and text).
    SearchTool.static.name = 'search';
    SearchTool.static.icon = 'search';
    SearchTool.static.title = 'Search...';
    // Defines the action that will happen when this tool is selected (clicked).
    SearchTool.prototype.onSelect = function () {
        $area.text( 'Search tool clicked!' );
        // Never display this tool as "active" (selected).
        this.setActive( false );
    };
    SearchTool.prototype.onUpdateState = function () {};
    // Make this tool available in our toolFactory and thus our toolbar
    toolFactory.register( SearchTool );

    // Register two more tools, nothing interesting here
    function SettingsTool() {
        SettingsTool.super.apply( this, arguments );
        this.reallyActive = false;
    }
    OO.inheritClass( SettingsTool, OO.ui.Tool );
    SettingsTool.static.name = 'settings';
    SettingsTool.static.icon = 'settings';
    SettingsTool.static.title = 'Change settings';
    SettingsTool.prototype.onSelect = function () {
        $area.text( 'Settings tool clicked!' );
        // Toggle the active state on each click
        this.reallyActive = !this.reallyActive;
        this.setActive( this.reallyActive );
        // To update the menu label
        this.toolbar.emit( 'updateState' );
    };
    SettingsTool.prototype.onUpdateState = function () {};
    toolFactory.register( SettingsTool );

    // Register two more tools, nothing interesting here
    function StuffTool() {
        StuffTool.super.apply( this, arguments );
        this.reallyActive = false;
    }
    OO.inheritClass( StuffTool, OO.ui.Tool );
    StuffTool.static.name = 'stuff';
    StuffTool.static.icon = 'ellipsis';
    StuffTool.static.title = 'More stuff';
    StuffTool.prototype.onSelect = function () {
        $area.text( 'More stuff tool clicked!' );
        // Toggle the active state on each click
        this.reallyActive = !this.reallyActive;
        this.setActive( this.reallyActive );
        // To update the menu label
        this.toolbar.emit( 'updateState' );
    };
    StuffTool.prototype.onUpdateState = function () {};
    toolFactory.register( StuffTool );

    // This is a PopupTool. Rather than having a custom 'onSelect' action, it will display a
    // little popup window (a PopupWidget). 'onUpdateState' is also already implemented.
    function HelpTool( toolGroup, config ) {
        OO.ui.PopupTool.call( this, toolGroup, $.extend( { popup: {
            padded: true,
            label: 'Help',
            head: true
        } }, config ) );
        this.popup.$body.append( '<p>I am helpful!</p>' );
    }
    OO.inheritClass( HelpTool, OO.ui.PopupTool );
    HelpTool.static.name = 'help';
    HelpTool.static.icon = 'help';
    HelpTool.static.title = 'Help';
    toolFactory.register( HelpTool );

    // Finally define which tools and in what order appear in the toolbar. Each tool may only be
    // used once (but not all defined tools must be used).
    toolbar.setup( [
        {
            // 'bar' tool groups display tools' icons only, side-by-side.
            type: 'bar',
            include: [ 'search', 'help' ]
        },
        {
            // 'menu' tool groups display both the titles and icons, in a dropdown menu.
            // Menu label indicates which items are selected.
            type: 'menu',
            indicator: 'down',
            include: [ 'settings', 'stuff' ]
        }
    ] );

    // Create some UI around the toolbar and place it in the document
    const frame = new OO.ui.PanelLayout( {
        expanded: false,
        framed: true
    } );
    const contentFrame = new OO.ui.PanelLayout( {
        expanded: false,
        padded: true
    } );
    frame.$element.append(
        toolbar.$element,
        contentFrame.$element.append( $area )
    );
    $( document.body ).append( frame.$element );

    // Here is where the toolbar is actually built. This must be done after inserting it into the
    // document.
    toolbar.initialize();
    toolbar.emit( 'updateState' );

Parameters:

Name Type Attributes Description
toolFactory OO.ui.ToolFactory

Factory for creating tools

toolGroupFactory OO.ui.ToolGroupFactory

Factory for creating toolgroups

config Object optional

Configuration options

Properties:
Name Type Attributes Default Description
actions boolean optional

Add an actions section to the toolbar. Actions are commands that are included in the toolbar, but are not configured as tools. By default, actions are displayed on the right side of the toolbar. This feature is deprecated. It is suggested to use the ToolGroup 'align' property instead.

position string optional
'top'

Whether the toolbar is positioned above ('top') or below ('bottom') content.

$overlay jQuery optional

An overlay for the popup. See https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays.

Mixes in:
Source:

Toolbars are complex interface components that permit users to easily access a variety of tools (e.g., formatting commands) and actions, which are additional commands that are part of the toolbar, but not configured as tools.

Methods

destroy() #

Destroy the toolbar.

Destroying the toolbar removes all event handlers and DOM elements that constitute the toolbar. Call this method whenever you are done using a toolbar.

Source:
Destroy the toolbar.

getClosestScrollableElementContainer() → {HTMLElement} #

Get closest scrollable container.

Inherited from:
Source:

Returns:

Closest scrollable container

Type
HTMLElement
Get closest scrollable container.

getData() → {any} #

Get element data.

Inherited from:
Source:

Returns:

Element data

Type
any
Get element data.

getElementDocument() → {HTMLDocument} #

Get the DOM document.

Inherited from:
Source:

Returns:

Document object

Type
HTMLDocument
Get the DOM document.

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
Get group element is in.

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} #

Get the DOM window.

Inherited from:
Source:

Returns:

Window object

Type
Window
Get the DOM window.

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
Get the HTML tag name.

getToolAccelerator(name) → {string|undefined} #

Get accelerator label for tool.

The OOUI library does not contain an accelerator system, but this is the hook for one. To use an accelerator system, subclass the toolbar and override this method, which is meant to return a label that describes the accelerator keys for the tool passed (by symbolic name) to the method.

Parameters:

Name Type Description
name string

Symbolic name of tool

Source:

Returns:

Tool accelerator label if available

Type
string | undefined
Get accelerator label for tool.

getToolFactory() → {OO.ui.ToolFactory} #

Get the tool factory.

Source:

Returns:

Tool factory

Type
OO.ui.ToolFactory
Get the tool factory.

getToolGroupByName(name) → {OO.ui.ToolGroup|null} #

Get a toolgroup by name

Parameters:

Name Type Description
name string

Group name

Source:

Returns:

Tool group, or null if none found by that name

Type
OO.ui.ToolGroup | null
Get a toolgroup by name

getToolGroupFactory() → {OO.Factory} #

Get the toolgroup factory.

Source:

Returns:

Toolgroup factory

Type
OO.Factory
Get the toolgroup factory.

initialize() #

Sets up handles and preloads required information for the toolbar to work. This must be called after it is attached to a visible document and before doing anything else.

Source:
Sets up handles and preloads required information for the toolbar to work.

insertItemElements() #

Source:

isElementAttached() → {boolean} #

Check if the element is attached to the DOM

Inherited from:
Source:

Returns:

The element is attached to the DOM

Type
boolean
Check if the element is attached to the DOM

isNarrow() → {boolean} #

Check if the toolbar is in narrow mode

Source:

Returns:

Toolbar is in narrow mode

Type
boolean
Check if the toolbar is in narrow mode

isToolAvailable(name) → {boolean} #

Check if the tool is available.

Available tools are ones that have not yet been added to the toolbar.

Parameters:

Name Type Description
name string

Symbolic name of tool

Source:

Returns:

Tool is available

Type
boolean
Check if the tool is available.

isVisible() → {boolean} #

Check if element is visible.

Inherited from:
Source:

Returns:

element is visible

Type
boolean
Check if element is visible.

onToolGroupActive(active) #

Handle active events from tool groups

Parameters:

Name Type Description
active boolean

Tool group has become active, inactive if false

Source:

Fires:

Handle active events from tool groups

releaseTool(tool) #

Allow tool to be used again.

Parameters:

Name Type Description
tool OO.ui.Tool

Tool to release

Source:
Allow tool to be used again.

reserveTool(tool) #

Prevent tool from being used again.

Parameters:

Name Type Description
tool OO.ui.Tool

Tool to reserve

Source:
Prevent tool from being used again.

reset() #

Remove all tools and toolgroups from the toolbar.

Source:
Remove all tools and toolgroups from the toolbar.

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:
Restore the pre-infusion dynamic state for this widget.

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
Scroll element into view.

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
Set element data.

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
Set group element is in.

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
Set the element has an 'id' attribute.

setNarrow(narrow) #

Set the narrow mode flag

Parameters:

Name Type Description
narrow boolean

Toolbar is in narrow mode

Source:
Set the narrow mode flag

setup(groups) #

Set up the toolbar.

The toolbar is set up with a list of toolgroup configurations that specify the type of toolgroup (bar, menu, or list) to add and which tools to include, exclude, promote, or demote within that toolgroup. Please see toolgroups for more information about including tools in toolgroups.

Parameters:

Name Type Description
groups Array.<Object>

List of toolgroup configurations

Properties:
Name Type Attributes Description
name string

Symbolic name for this toolgroup

type string optional

Toolgroup type, e.g. "bar", "list", or "menu". Should exist in the OO.ui.ToolGroupFactory provided via the constructor. Defaults to "list" for catch-all groups where include='*', otherwise "bar".

include Array | string optional

Tools to include in the toolgroup, or "*" for catch-all, see OO.ui.ToolFactory#extract

exclude Array | string optional

Tools to exclude from the toolgroup

promote Array | string optional

Tools to promote to the beginning of the toolgroup

demote Array | string optional

Tools to demote to the end of the toolgroup

Source:
Set up the toolbar.

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
Check if element supports one or more methods.

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:

Toggle visibility of an element.

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:
Update the theme-provided classes.

Events

active(There) #

An 'active' event is emitted when the number of active toolgroups increases from 0, or returns to 0.

Parameters:

Name Type Description
There boolean

are active toolgroups in this toolbar

Source:

An 'active' event is emitted when the number of active toolgroups increases from 0, or returns to 0.

resize() #

Toolbar has resized to a point where narrow mode has changed

Source:
Toolbar has resized to a point where narrow mode has changed

updateState(…data) #

An 'updateState' event must be emitted on the Toolbar (by calling toolbar.emit( 'updateState' )) every time the state of the application using the toolbar changes, and an update to the state of tools is required.

Parameters:

Name Type Attributes Description
data any repeatable

Application-defined parameters

Source:

An 'updateState' event must be emitted on the Toolbar (by calling toolbar.emit( 'updateState' )) every time the state of the application using the toolbar changes, and an update to the state of tools is required.