Anaconda Enterprise: Documentation

# Adding Widgets

Widgets are interactive controls that can be added to Bokeh applications to provide a front end user interface to a visualization. They can drive new computations, update plots, and connect to other programmatic functionality. When used with the Bokeh server, widgets can run arbitrary Python code, enabling complex applications. Widgets can also be used without the Bokeh server in standalone HTML documents through the browser’s Javascript runtime.

To use widgets, you must add them to your document and define their functionality. Widgets can be added directly to the document root or nested inside a layout. There are two ways to program a widget’s functionality:

> - Use the `CustomJS` callback (see JavaScript Callbacks). This will work in standalone HTML documents.
> - Use `bokeh serve` to start the Bokeh server and set up event handlers with `.on_change` (or for some widgets, `.on_click`).

Event handlers are user-defined Python functions that can be attached to widgets. These functions are then called when certain attributes on the widget are changed. The necessary function signature of event handlers is determined by how they are attached to widgets (whether they are passed through `.on_change` or `.on_click`).

All widgets have an `.on_change` method that takes an attribute name and one or more event handlers as parameters. These handlers are expected to have the function signature, `(attr, old, new)`, where `attr` refers to the changed attribute’s name, and `old` and `new` refer to the previous and updated values of the attribute. `.on_change` must be used when you need the previous value of an attribute.

    def my_text_input_handler(attr, old, new):
        print("Previous label: " + old)
        print("Updated label: " + new)

    text_input = TextInput(value="default", title="Label:")
    text_input.on_change("value", my_text_input_handler)

Additionally, some widgets, including the button, dropdown, and checkbox, have an `.on_click` method that takes an event handler as its only parameter. For the Button, this handler is called without parameters. For the other widgets with `.on_click`, the handler is passed the new attribute value.

    def my_radio_handler(new):
        print 'Radio button option ' + str(new) + ' selected.'

    radio_group = RadioGroup(
        labels=["Option 1", "Option 2", "Option 3"], active=0)
    radio_group.on_click(my_radio_handler)

Bokeh provides a simple default set of widgets, largely based off the Bootstrap JavaScript library. In the future, it will be possible for users to wrap and use other widget libraries, or their own custom widgets.

For more information about the attributes to watch using `.on_change` or whether `.on_click` is available, go to the Reference Guide. Widgets can be found under bokeh.models.

## Button

Bokeh provides a simple Button:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import Button

    output_file("button.html")

    button = Button(label="Foo", button_type="success")

    show(widgetbox(button))

## Checkbox Button Group

Bokeh also provides a checkbox button group, that can have multiple options selected simultaneously:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import CheckboxButtonGroup

    output_file("checkbox_button_group.html")

    checkbox_button_group = CheckboxButtonGroup(
            labels=["Option 1", "Option 2", "Option 3"], active=[0, 1])

    show(widgetbox(checkbox_button_group))

## Checkbox Group

A standard checkbox:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import CheckboxGroup

    output_file("checkbox_group.html")

    checkbox_group = CheckboxGroup(
            labels=["Option 1", "Option 2", "Option 3"], active=[0, 1])

    show(widgetbox(checkbox_group))

## Data Table

Bokeh provides a sophisticated data table widget based on SlickGrid. Note that since the table is configured with a data source object, any plots that share this data source will automatically have selections linked between the plot and the table (even in static HTML documents).

    from datetime import date
    from random import randint

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models import ColumnDataSource
    from bokeh.models.widgets import DataTable, DateFormatter, TableColumn

    output_file("data_table.html")

    data = dict(
            dates=[date(2014, 3, i+1) for i in range(10)],
            downloads=[randint(0, 100) for i in range(10)],
        )
    source = ColumnDataSource(data)

    columns = [
            TableColumn(field="dates", title="Date", formatter=DateFormatter()),
            TableColumn(field="downloads", title="Downloads"),
        ]
    data_table = DataTable(source=source, columns=columns, width=400, height=280)

    show(widgetbox(data_table))

## Dropdown Menu

It is also possible to include Dropdown menus:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import Dropdown

    output_file("dropdown.html")

    menu = [("Item 1", "item_1"), ("Item 2", "item_2"), None, ("Item 3", "item_3")]
    dropdown = Dropdown(label="Dropdown button", button_type="warning", menu=menu)

    show(widgetbox(dropdown))

## MultiSelect

A multi-select widget to present multiple available options:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import MultiSelect

    output_file("multi_select.html")

    multi_select = MultiSelect(title="Option:", value=["foo", "quux"],
                               options=[("foo", "Foo"), ("bar", "BAR"), ("baz", "bAz"), ("quux", "quux")])

    show(widgetbox(multi_select))

## Radio Button Group

A radio button group can have at most one selected button at at time:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import RadioButtonGroup

    output_file("radio_button_group.html")

    radio_button_group = RadioButtonGroup(
            labels=["Option 1", "Option 2", "Option 3"], active=0)

    show(widgetbox(radio_button_group))

## Radio Group

A radio group uses standard radio button appearance:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import RadioGroup

    output_file("radio_group.html")

    radio_group = RadioGroup(
            labels=["Option 1", "Option 2", "Option 3"], active=0)

    show(widgetbox(radio_group))

## Select

A single selection widget:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import Select

    output_file("select.html")

    select = Select(title="Option:", value="foo", options=["foo", "bar", "baz", "quux"])

    show(widgetbox(select))

## Slider

The Bokeh slider can be configured with `start` and `end` values, a `step` size, an initial `value` and a `title`:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import Slider

    output_file("slider.html")

    slider = Slider(start=0, end=10, value=1, step=.1, title="Stuff")

    show(widgetbox(slider))

## RangeSlider

The Bokeh range-slider can be configured with `start` and `end` values, a `step` size, an initial `range` and a `title`:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import RangeSlider

    output_file("range_slider.html")

    range_slider = RangeSlider(start=0, end=10, value=(1,9), step=.1, title="Stuff")

    show(widgetbox(range_slider))

## Tab Panes

Tab panes allow multiple plots or layouts to be show in selectable tabs:

    from bokeh.models.widgets import Panel, Tabs
    from bokeh.io import output_file, show
    from bokeh.plotting import figure

    output_file("slider.html")

    p1 = figure(plot_width=300, plot_height=300)
    p1.circle([1, 2, 3, 4, 5], [6, 7, 2, 4, 5], size=20, color="navy", alpha=0.5)
    tab1 = Panel(child=p1, title="circle")

    p2 = figure(plot_width=300, plot_height=300)
    p2.line([1, 2, 3, 4, 5], [6, 7, 2, 4, 5], line_width=3, color="navy", alpha=0.5)
    tab2 = Panel(child=p2, title="line")

    tabs = Tabs(tabs=[ tab1, tab2 ])

    show(tabs)

## TextInput

A widget for collecting a line of text from a user:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import TextInput

    output_file("text_input.html")

    text_input = TextInput(value="default", title="Label:")

    show(widgetbox(text_input))

## Toggle Button

The toggle button holds an on/off state:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import Toggle

    output_file("toggle.html")

    toggle = Toggle(label="Foo", button_type="success")

    show(widgetbox(toggle))

## Div

A widget for displaying text that can support HTML in a <div> tag:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import Div

    output_file("div.html")

    div = Div(text="""Your <a href="https://en.wikipedia.org/wiki/HTML">HTML</a>-supported text is initialized with the <b>text</b> argument.  The
    remaining div arguments are <b>width</b> and <b>height</b>. For this example, those values
    are <i>200</i> and <i>100</i> respectively.""",
    width=200, height=100)

    show(widgetbox(div))

## Paragraph

A widget for displaying a block of text in an HTML <p> tag:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import Paragraph

    output_file("div.html")

    p = Paragraph(text="""Your text is initialized with the 'text' argument.  The
    remaining Paragraph arguments are 'width' and 'height'. For this example, those values
    are 200 and 100 respectively.""",
    width=200, height=100)

    show(widgetbox(p))

## PreText

A widget for displaying a block of pre-formatted text in an HTML <pre> tag:

    from bokeh.io import output_file, show
    from bokeh.layouts import widgetbox
    from bokeh.models.widgets import PreText

    output_file("div.html")

    pre = PreText(text="""Your text is initialized with the 'text' argument.

    The remaining Paragraph arguments are 'width' and 'height'. For this example,
    those values are 500 and 100 respectively.""",
    width=500, height=100)

    show(widgetbox(pre))