JointJS+ SelectBox

ui.SelectBox

ui.SelectBox is a UI widget for displaying dropdowns. Items in the dropdown can contain arbitrary HTML. Because items in dropdowns often contain images, ui.SelectBox provides an easy way to add icons to your dropdown items. The ui.SelectBox also provides different open policies and support for keyboard navigation.

Installation

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

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

Usage

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

var selectBox = new joint.ui.SelectBox({
        width: 200,
        options: [
            { content: 'Amsterdam' },
            { content: 'Prague', selected: true },
            { content: 'London' },
            { content: 'San Francisco' },
            { content: 'New York' }
        ]
    });

    document.body.appendChild(selectBox.render().el);

ui.SelectBox with icons

var selectBox = new joint.ui.SelectBox({
        width: 250,
        options: [
            { icon: '/path/to/some-image.png', content: 'Some text content', selected: true },
            { icon: '/path/to/some-other-image.png', content: 'Some other text' }
        ]
    });

    document.body.appendChild(selectBox.render().el);

Configuration

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

width The width of the dropdown in pixels.

options

An array of items. Each item is an object with the following properties:

content	The content of the item. It can be either a string or an HTML.
value	The value of the item. It can be a string, a number or any other JavaScript object. If the value is not defined, the value is considered to be equal to the `content` property.
icon	A path to an image. The icon is prepended to the item and is given the `select-box-option-icon` CSS class.
selected	`true` if the item should be selected by default. If non of the items are selected, the first item is selected by default.

selected The index of the item which should be selected by default. If this value is undefined (which it is by default), the ui.SelectBox widget looks up the selected item from the options array (by using the selected boolean property). If nothing is selected, the first item in the options array is selected by default.

keyboardNavigation true (the default) if you want the ui.SelectBox to provide a keyboard navigation (up/down/left/right/enter/escape keys are supported).

selectBoxOptionsClass When the dropdown is opened, the ui.SelectBox generates an HTML container that contains all the items. This container is then appended to the document body (or target if provided). Sometimes, you want to provide custom styling to this dropdown container. selectBoxOptionsClass gives you a chance to define a CSS class that will be set on this container so that you can style it in your CSS.

target ui.SelectBox generates an HTML container that contains all the dropdown items. This container is by default appended to the document body. In some situations (e.g. if you want the dropdown to scroll with some other container), you want to append this container to a different DOM element. The target option is exactly for that. It accepts an HTML element that will be used as a container for the generated dropdown items.

openPolicy openPolicy determines how the dropdown will open when clicked. It can be one of 'auto', 'above', 'coverAbove', 'below', 'coverBelow' and 'selected'.

placeholder In some cases, you want to deselect the dropdown and show a placeholder in place of the selected item. This is when you don't want any of the items to be selected. In this case, set the selected index to -1 and the placeholder to any HTML you want to display in the selected item window. This placeholder has the selected-box-placeholder CSS class that you can use for further styling.

API

render()	Render the dropdown. Note that once you render the dropdown, 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(selectBox.el)`).
getSelection()	Get the current selection. The selection points to one of the items from the `options` array.
getSelectionValue()	Get the current selection value.
getSelectionIndex()	Get the index in the `options` array of the item that is currently selected.
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.
isOpen()	Returns `true` if the dropdown is currently opened. `false` otherwise.
toggle()	Programmatically toggle the dropdown.
open()	Programmatically open the dropdown.
close()	Programmatically close the dropdown.
remove()	Remove the dropdown from the DOM.
disable()	Disable the dropdown.
enable()	Enable the dropdown.
isDisabled()	Return `true` if the dropdown is disabled.
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`).

Events

The ui.SelectBox 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.
option:mouseout	Triggered when the user leaves an item with mouse cursor. The handler is passed an event object as the only argument.
close	Triggered when the dropdown gets closed.