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
- 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¶
For the most part, Python Bokeh models are completely declarative classes.
Custom extensions are created by making a subclass
(or one of its subclasses), and including special class attributes to
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
that can hold a
Slider object that corresponds to the Python
Slider will be made
available to use.
Custom and its
CustomView. For built-in models, this code is included directly in the
bokeh.js library. We will see how to connect this code to custom
extensions in the next section.
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
is needed. The Python class should have have a class attribute called
that the defined the client-side model (and optional view).
Assuming the CoffeeScript code above was saved in a file
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)
Supplying External Resources¶
As part of implementing a custom model in Bokeh, there may be the need to
supplying external resources through the Python class attributes
__css__ of custom models.
One example is including the JS and CSS files for KaTex (a
LaTexLabel custom model.
See the LaTex example in the extensions gallery below to see the full implementation and resulting output.
Integration with Bokeh Server¶
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.
- Creating Latex Labels
- Adding A Custom Widget