JointJS+ SelectButtonGroup

ui.SelectButtonGroup

ui.SelectButtonGroup is a UI widget for displaying groups of buttons with both single and multi selection support. The buttons can contain arbitrary HTML.

Installation

Include joint.ui.selectButtonGroup.js and joint.ui.selectButtonGroup.css files to your HTML:

<link rel="stylesheet" type="text/css" href="joint.ui.selectButtonGroup.css">
<script src="joint.ui.selectButtonGroup.js"></script>

Usage

Create an object of ui.SelectButtonGroup type, render it with the render() method and append the generated HTML element anywhere in your DOM:

var buttonGroup = new joint.ui.SelectButtonGroup({
    multi: true,
    selected: [1, 3],
    options: [
        { value: 'line-through', content: 'S' },
        { value: 'underline', content: 'U' },
        { value: 'italic', content: 'I' },
        { value: 'bold', content: 'B' }
    ]
});
document.body.appendChild(buttonGroup.render().el);

More examples

`ui.SelectButtonGroup` with icons

Configuration

The following table lists options that you can pass to the ui.SelectButtonGroup constructor function:

options

Object[]

Optional. An array of items (the buttons). Each item is an object with the following properties:

content	string	Optional. The content of the item. It can be either a plain string or a string containing HTML code.
value	any	Optional. The value of the item. It can be a string, a number or any other JavaScript object. By default, the value is considered to be equal to the `content` property.
attrs	Object	Optional. A hierarchical object that adds styling to component HTML elements of the option. For example, the following `attrs` object would add a tooltip to the option: `{ '.select-button-group-button': { 'data-tooltip': 'My tooltip' } }`
selected	boolean	Optional. Should this item be selected by default? Default is `false`.
icon	string	Optional. A path to an image to be added to the option's button.
iconSelected	string	Optional. A path to an image to be added to the option's button when it is selected. By default, the selected state uses `icon` (if provided).
buttonWidth	number	Optional. The width of the button in pixels.
buttonHeight	number	Optional. The height of the button in pixels.
iconWidth	number	Optional. The width of `icon` in pixels (if provided).
iconHeight	number	Optional. The height of `icon` in pixels (if provided).

disabled boolean Optional. Is the user prevented from interacting with this ui.SelectButtonGroup? Default is false.

multi boolean Optional. Is this a multiple-choice set? (That is, is it allowed for multiple buttons to be selected at the same time?) Default is false.

selected number | number[] Optional. Which options should be selected by default?
If multi === false, expects a number - the index of the selected option.
If multi === true, expects an array of numbers - indices of all selected options.
By default, this property is undefined. In that case, the widget determines selected items according to individual options' selected property.

singleDeselect boolean Optional. If multi === false, is the user allowed to deselect the currently-selected icon by clicking on it? Default is false (radio-button-like behavior).

noSelectionValue any Optional. If nothing is selected, what value should be reported by the getSelectionValue() function? Default is undefined.

width number Optional. The width of the whole widget in pixels.

buttonWidth number Optional. The width of each button in pixels. Overridden by individual options' buttonWidth property (if provided).

buttonHeight number Optional. The height of each button in pixels. Overridden by individual options' buttonHeight property (if provided).

iconWidth number Optional. The width of each icon in pixels (for options with an icon property). Overridden by individual options' iconWidth property (if provided).

iconHeight number Optional. The height of each icon in pixels (for options with an icon property). Overridden by individual options' iconHeight property (if provided).

API

render()	Render the button group. Note that once you render the button group, you can use the `el` property that points to the container HTML element and append it anywhere in the DOM (e.g. `$(document.body).append(selectButtonGroup.el)`).
getSelection()	Get the current selection. The selection points to an item(s) from the `options` array.
getSelectionValue()	Get the current selection value(s). If nothing is selected, `noSelectionValue` is returned (default is `undefined`).
select(index, opt)	Select an item. `index` is the index to the `options` array. `opt` is optional and can be an arbitrary object that will be passed to the `option:select` event handler.
selectByValue(value)	Select an item by value. The selected item will be chosen based on a strict equality of the `value` passed an a `value` (`content`) of any of the items.
deselect()	Deselect all selected items.
remove()	Remove the button group from the DOM.
on(event, handler [, context])	Register a `handler` function that will be called whenever `event` is triggered. The optional `context` is an object that will be the context of the handler function (the `this`).
disable()	Prevent to the user's interactions.
enable()	Make the button group available to the user's interactions.
isDisabled()	Check if the button group is prevented to the user's interactions.

Events

The ui.SelectButtonGroup object triggers various events that you can react on. Events can be handled by using the on() method (see above).

option:hover	Triggered when the user hovers over one of the items. The handler is passed the option object and the index of the option in the `options` array.
option:select	Triggered when the user selects an item. The handler is passed the option object and the index of the option in the `options` array. If you selected the item with the `select(index, opt)` method, the third argument to the event handler will be your `opt` object.
mouseout	Triggered when the user leaves the entire button group with mouse cursor. The handler is passed an event object as the only argument.