Extending Bokeh

Bokeh comes with a rich variety of built-in types that can be used to make sophisticated interactive visualizations and data applications in the browser. However, there are capabilities and features that users may desire, which may not make it into the core library, either because they are too specialized, or for lack of resources. Fortunately, it is possible to extend Bokeh by creating custom user extensions.

  • Modify the behavior of existing Bokeh models
  • Add new models to connect third-party JavaScript libraries to Python
  • Create highly specialized models for domain specific use-cases.

Custom extensions can be made and used with standard releases, and do not require setting up a development environment or building anything from source. They provide the easiest way to get involved in Bokeh development. By lowering the bar for extending Bokeh, users are afforded the ability to “try out” new features and functionality (which might some day be candidates for adding to the core library) without having to wait on the core team.

Structure of Bokeh Models

Python Models

For the most part, Python Bokeh models are completely declarative classes. Custom extensions are created by making a subclass Model (or one of its subclasses), and including special class attributes to declare the properties that are mirrored on the JavaScript side. All of the available property types are documented in the bokeh.core.properties section of the Reference Guide.

A small example that creates a Custom readout for a slider is presented below:

from bokeh.core.properties import String, Instance
from bokeh.models import LayoutDOM, Slider

class Custom(LayoutDOM):

    text = String(default="Custom text")

    range = Instance(Slider)

Since we would like to create a custom extension that can participate in DOM layout, we subclass from LayoutDOM. We also added two properties: a String to configure a text message for the readout, and an Instance that can hold a Slider. The JavaScript Slider object that corresponds to the Python Slider will be made available to use.

JavaScript Models and Views

While the Python side is mostly declarative, without much or any real code, the JavaScript side requires code to implement the model. When appropriate, code for a corresponding view must also be provided. Currently BokehJS models and views are subclasses of Models and View from the Backbone JavaScript library.

Below is an annotated JavaScript implementation for Custom and its CustomView. For built-in models, this code is included directly in the final bokeh.js library. We will see how to connect this code to custom extensions in the next section.

Note

BokehJS is largely written in CoffeeScript. Accordingly, the examples and guidance here are presented in CoffeeScript. However, custom extensions can be written in pure JavaScript as well.

# These are similar to python imports. BokehJS vendors its own versions
# of Underscore and JQuery. They are available as show here.
_ = require "underscore"
$ = require "jquery"

# The "core/properties" module has all the property types
p = require "core/properties"

# We will subclass in JavaScript from the same class that was subclassed
# from in Python
LayoutDOM = require "models/layouts/layout_dom"

# This model will actually need to render things, so we must provide
# view. The LayoutDOM model has a view already, so we will start with that
class CustomView extends LayoutDOM.View

  initialize: (options) ->
    super(options)

    @render()

    # Set Backbone listener so that when the Bokeh slider has a change
    # event, we can process the new data
    @listenTo(@model.slider, 'change', () => @render())

  render: () ->
    # Backbone Views create <div> elements by default, accessible as @$el.
    # Many Bokeh views ignore this default <div>, and instead do things
    # like draw to the HTML canvas. In this case though, we change the
    # contents of the <div>, based on the current slider value.
    @$el.html("<h1>#{ @model.text }: #{ @model.slider.value }</h1>")
    @$('h1').css({ 'color': '#686d8e', 'background-color': '#2a3153' })

class Custom extends LayoutDOM.Model

  # If there is an associated view, this is boilerplate.
  default_view: CustomView

  # The ``type`` class attribute should generally match exactly the name
  # of the corresponding Python class.
  type: "Custom"

  # The @define block adds corresponding "properties" to the JS model. These
  # should basically line up 1-1 with the Python model class. Most property
  # types have counterparts, e.g. bokeh.core.properties.String will be
  # p.String in the JS implementation. Where the JS type system is not yet
  # as rich, you can use p.Any as a "wildcard" property type.
  @define {
    text:   [ p.String ]
    slider: [ p.Any    ]
  }

# This is boilerplate. Every implementation should export a Model
# and (when applicable) also a View.
module.exports =
  Model: Custom
  View: CustomView

Putting it Together

For built-in Bokeh models, the implementation in BokehJS is automatically matched with the corresponding Python model by the build process. In order connect JavaScript implementations to Python models, one additional step is needed. The Python class should have have a class attribute called __implementation__ whose value is the JavaScript (or CoffeeScript) code that the defined the client-side model (and optional view).

Assuming the CoffeeScript code above was saved in a file custom.coffee, then the complete Python class might look like:

from bokeh.core.properties import String, Instance
from bokeh.models import LayoutDOM, Slider

class Custom(LayoutDOM):

    __implementation__ = "custom.coffee"

    text = String(default="Custom text")

    slider = Instance(Slider)

Then, if this class is defined in a Python module custom.py then the custom extension can now be used exactly like any built-in Bokeh model:

from bokeh.io import show
from bokeh.layouts import column
from bokeh.models import Slider

from custom import Custom

slider = Slider(start=0, end=10, step=0.1, value=0, title="value")

custom = Custom(text="Special Slider Display", slider=slider)

layout = column(slider, custom)

show(layout)

Which results in the output below. The JavaScript code for the implementation is automatically included in the rendered document. Scrub the slider to see the special header update as the slider moves:

Supplying External Resources

As part of implementing a custom model in Bokeh, there may be the need to include third-party javascript libraries or css resources. Bokeh supports supplying external resources through the Python class attributes __javascript__ and __css__ of custom models.

Including the URL paths to external resources will causes Bokeh to add the resources to the html document head, causing the Javascript library to be available in the global namespace and the custom CSS styling to be applied.

One example is including the JS and CSS files for KaTex (a Javascript-based typesetting library that supports LaTex) in order to create a LaTexLabel custom model.

class LatexLabel(Label):
    """A subclass of the Bokeh built-in `Label` that supports rendering
    LaTex using the KaTex typesetting library.
    """
    __javascript__ = "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/katex.min.js"
    __css__ = "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.6.0/katex.min.css"
    __implementation__ = """
    # do something here
    """

See the LaTex example in the extensions gallery below to see the full implementation and resulting output.

Integration with Bokeh Server

No special work or modification is needed to integrate custom user extensions with the Bokeh server. As for standalone documents, the JavaScript implementation is automatically included in the rendered application. Additionally the standard synchronization of Bokeh model properties that happens for all built-in models happens transparently for custom user extensions as well.

Examples

Here we present some complete examples to serve as a reference. It is hoped that the information in this section is a useful point of departure for anyone creating a custom extensions. However, creating extensions is a somewhat advanced topic. In many cases, it will be required to study the source code of the base classes in bokehjs/src/coffee/models.

For any questions that remain, please contact any of the sources in Learning More.Collaborating with the community will help make additions and improvements to this section for future users.

Specialized Axis Ticking
Subclass built-in Bokeh models for axis ticking to customize their behaviour.
A New Custom Tool
Make a completely new tool that can draw on a plot canvas.
Wrapping A JavaScript Library
Connect Python to a third-party JavaScript library by wrapping it with a Bokeh custom extension.
Creating Latex Labels
Include a third-party JavaScript library in order to render LaTex.
Adding A Custom Widget
Include a third-party JavaScript library in an extension widget.