Toolbar

The plugin implements an interactive toolbar component which can be populated with tools (Widget instances) that allow the user to interact with a JointJS diagram.

To learn more about the plugin, check out the Toolbar UI component section.

constructor

constructor(options?: Toolbar.Options);

The Toolbar constructor accepts several parameters:

autoToggle

autoToggle?: boolean

[optional] When set to true, all Widget instances switch their state (enabled/disabled) automatically based on the state of their references.

groups

groups?: { [key: string]: { index?: number, align?: Align } }

[optional] Split the Toolbar Widgets defined in ui.Toolbar.options.tools into groups. Groups can be aligned and ordered in the context of the Toolbar.

The keys of this object are strings that uniquely identify the groups and values are objects that contain properties for a given group:

• [optional] index is a number specifying the position of the group among other groups within the Toolbar,
• [optional] align is a string value from the Align enum ('left' or 'right') specifying the alignment of the group within the Toolbar.

references

references?: any

[optional] A key => value storage. Some Widget types require additional references for their functionality. Whenever you use such a Widget type as a Toolbar Widget, you need to pass the required reference into the Toolbar as well.

For example, the undo and redo Widgets require a reference to a CommandManager instance, while zoomIn and zoomOut Widgets require a reference to a PaperScroller instance.

Example usage:

const paperScroller = new ui.PaperScroller({
    paper: paper,
    autoResizePaper: true,
});

const commandManager = new dia.CommandManager({
    graph: graph,
});

const toolbar = new ui.Toolbar({
    tools: ['zoomIn', 'zoomOut', 'zoomToFit', 'zoomSlider', 'undo', 'redo'],
    references: {
        paperScroller: paperScroller,
        commandManager: commandManager,
    },
});

tools

tools?: Array<{ [key: string]: any } | string>

[optional] An array of tools defined as a plain JavasScript object.

The items of this array are objects that contain properties for each Widget to be added to the Toolbar. Toolbar Widgets of all Widget types can have the following properties specified:

• [required] type string identifies what kind of Widget will be added. All available built-in Widget types are listed in the Widget types section,
• [optional] name string is used to differentiate multiple Toolbar Widgets with the same type and has to be unique in the context of the Toolbar. Note that the Toolbar uses the name as a prefix for events triggered on individual Widget instances. More information can be found in the Toolbar events section,
• [optional] group string is the name of the group the Toolbar Widget belongs to,
• [optional] attrs object provides JointJS style attribute definition for a specific Toolbar Widget. Additional DOM element attributes can be defined here,
• [optional] theme string allows to override the global ui.Toolbar.options.theme for a specific Toolbar Widget.

In addition, each Widget type may accept additional type-specific options, as detailed in the Widget types section.

If the type is the only property that needs to be specified for a Toolbar Widget (e.g. you want to use a default separator), then it is enough to specify the item only via the type string (i.e. 'separator' instead of { type: 'separator' })

Example usage:

tools: [
    { type: 'checkbox' },
    { type: 'range', name: 'slider', min: 0, max: 10, step: 1 },
    { type: 'separator' },
    { type: 'toggle', name: 'toggle', label: ''},
    'separator',  // also possible, use defaults
    { type: 'inputText' },
    { type: 'button', name: 'ok', text: 'Ok' },
    { type: 'button', name: 'cancel', text: 'Cancel' },
    { type: 'separator' }
]

widgetNamespace

widgetNamespace?: { [name: string]: typeof Widget }

[optional] A namespace with all available Widget type definitions. It points to ui.widgets by default. See the Widget types section for a list of built-in Widget type definitions in the ui.widgets namespace.

Methods

getWidgetByName()

getWidgetByName(name: string): Widget;

getWidgetByName<T extends keyof ui.widgets.WidgetMap>(name: string): ui.widgets.WidgetMap[T];

Return a Widget instance with the matching name from the Toolbar.

You can use Widget API methods on the returned Widget instance, for example:

toolbar.getWidgetByName('ok').disable();

getWidgets()

getWidgets(): Array<Widget>;

Return the array of all Widget instances from the Toolbar.

You can use Widget API methods on the returned Widget instances, for example:

toolbar.getWidgets().forEach((widget) => widget.disable());

Events

The Toolbar acts as a proxy for events triggered by individual Widget instances. See the Toolbar events section for details.

Types

The plugin uses the following types:

Align

enum Align {
    Left = 'left',
    Right = 'right'
}

Options

interface Options extends mvc.ViewOptions<undefined> {
    tools?: Array<{ [key: string]: any } | string>,
    groups?: {
        [key: string]: {
            index?: number,
            align?: Align
        }
    }
    references?: any,
    autoToggle?: boolean,
    widgetNamespace?: { [name: string]: typeof Widget }
}