OO.ui.Toolbar

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:

Mixes in:

• OO.EventEmitter
• OO.ui.mixin.GroupElement

Source:

• Toolbar.js, line 284