Class: Toolbar

.ui.Toolbar(toolFactory, toolGroupFactory, configopt)

new Toolbar(toolFactory, toolGroupFactory, configopt)

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.

The following is an example of a basic toolbar.

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.
position string <optional>
 'top'

Whether the toolbar is positioned above ('top') or below ('bottom') content.
Mixes In:
Source:
Examples
// Example of a toolbar
    // Create the toolbar
    var toolFactory = new OO.ui.ToolFactory();
    var toolGroupFactory = new OO.ui.ToolGroupFactory();
    var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );

    // We will be placing status text in this element when tools are used
    var $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.parent.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.parent.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.parent.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
    var frame = new OO.ui.PanelLayout( {
        expanded: false,
        framed: true
    } );
    var contentFrame = new OO.ui.PanelLayout( {
        expanded: false,
        padded: true
    } );
    frame.$element.append(
        toolbar.$element,
        contentFrame.$element.append( $area )
    );
    $( '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
    var toolFactory = new OO.ui.ToolFactory();
    var toolGroupFactory = new OO.ui.ToolGroupFactory();
    var toolbar = new OO.ui.Toolbar( toolFactory, toolGroupFactory );

    // We will be placing status text in this element when tools are used
    var $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.parent.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.parent.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.parent.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
    var frame = new OO.ui.PanelLayout( {
        expanded: false,
        framed: true
    } );
    var contentFrame = new OO.ui.PanelLayout( {
        expanded: false,
        padded: true
    } );
    frame.$element.append(
        toolbar.$element,
        contentFrame.$element.append( $area )
    );
    $( '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' );

Extends

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:

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

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

getToolAccelerator(name) → {string|undefined}

Get accelerator label for tool.

The OOjs UI 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

getToolFactory() → {OO.ui.ToolFactory}

Get the tool factory.

Source:
Returns:

Tool factory

Type
OO.ui.ToolFactory

getToolGroupFactory() → {OO.Factory}

Get the toolgroup factory.

Source:
Returns:

Toolgroup factory

Type
OO.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:

isElementAttached() → {boolean}

Check if the element is attached to the DOM

Inherited From:
Source:
Returns:

The element is attached to the DOM

Type
boolean

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

isVisible() → {boolean}

Check if element is visible.

Inherited From:
Source:
Returns:

element is visible

Type
boolean

releaseTool(tool)

Allow tool to be used again.

Parameters:
Name Type Description
tool OO.ui.Tool

Tool to release
Source:

reserveTool(tool)

Prevent tool from being used again.

Parameters:
Name Type Description
tool OO.ui.Tool

Tool to reserve
Source:

reset()

Remove all tools and toolgroups from the toolbar.

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:

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:

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

List of toolgroup configurations

Properties
Name Type Attributes Description
include Array | string <optional>

Tools to include in the toolgroup
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:

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

updateThemeClasses()

Update the theme-provided classes.

Inherited From:
Source: