bokeh.embed¶
Provide functions to embed Bokeh models (e.g., plots, widget, layouts) in various different ways.
There are a number of different combinations of options when embedding Bokeh plots. The data for the plot can be contained in the document, or on a Bokeh server, or in a sidecar JavaScript file. Likewise, BokehJS may be inlined in the document, or loaded from CDN or a Bokeh server.
The functions in bokeh.embed
provide functionality to embed in all
these different cases.
-
autoload_server
(model, app_path='/', session_id=None, url='default')¶ Return a script tag that embeds the given model (or entire Document) from a Bokeh server session.
In a typical deployment, each browser tab connecting to a Bokeh application will have its own unique session ID. The session ID identifies a unique Document instance for each session (so the state of the Document can be different in every tab).
If you call
autoload_server(model=None)
, you’ll embed the entire Document for a freshly-generated session ID. Typically, you should callautoload_server()
again for each page load so that every new browser tab gets its own session.Sometimes when doodling around on a local machine, it’s fine to set
session_id
to something human-readable such as"default"
. That way you can easily reload the same session each time and keep your state. But don’t do this in production!In some applications, you may want to “set up” the session before you embed it. For example, you might
session = bokeh.client.pull_session()
to load up a session, modifysession.document
in some way (perhaps adding per-user data?), and then callautoload_server(model=None, session_id=session.id)
. The session ID obtained frompull_session()
can be passed toautoload_server()
.Parameters: - model (Model) – the object to render from the session, or None for entire document
- app_path (str, optional) – the server path to the app we want to load
- session_id (str, optional) – server session ID (default: None) If None, let the server autogenerate a random session ID. If you supply a specific model to render, you must also supply the session ID containing that model, though.
- url (str, optional) – server root URL (where static resources live, not where a specific app lives)
Returns: a
<script>
tag that will execute an autoload script loaded from the Bokeh ServerReturn type: tag
Note
It is a very bad idea to use the same
session_id
for every page load; you are likely to create scalability and security problems. Soautoload_server()
should be called again on each page load.
-
autoload_static
(model, resources, script_path)¶ Return JavaScript code and a script tag that can be used to embed Bokeh Plots.
The data for the plot is stored directly in the returned JavaScript code.
Parameters: Returns: JavaScript code to be saved at
script_path
and a<script>
tag to load itReturn type: (js, tag)
Raises: ValueError
-
components
(models, resources=None, wrap_script=True, wrap_plot_info=True)¶ Return HTML components to embed a Bokeh plot. The data for the plot is stored directly in the returned HTML.
An example can be found in examples/embed/embed_multiple.py
Note
The returned components assume that BokehJS resources are already loaded.
Parameters: - models (Model|list|dict|tuple) – A single Model, a list/tuple of Models, or a dictionary of keys and Models.
- resources – Deprecated argument
- wrap_script (boolean, optional) – If True, the returned javascript is wrapped in a script tag. (default: True)
- wrap_plot_info (boolean, optional) –
If True, returns
<div>
strings. Otherwise, return dicts that can be used to build your own divs. (default: True)If False, the returned dictionary contains the following information:
{ 'modelid': 'The model ID, used with Document.get_model_by_id', 'elementid': 'The css identifier the BokehJS will look for to target the plot', 'docid': 'Used by Bokeh to find the doc embedded in the returned script', }
Returns: UTF-8 encoded (script, div[s]) or (raw_script, plot_info[s])
Examples
With default wrapping parameter values:
components(plot) # => (script, plot_div) components((plot1, plot2)) # => (script, (plot1_div, plot2_div)) components({"Plot 1": plot1, "Plot 2": plot2}) # => (script, {"Plot 1": plot1_div, "Plot 2": plot2_div})
Examples
With wrapping parameters set to
False
:components(plot, wrap_script=False, wrap_plot_info=False) # => (javascript, plot_dict) components((plot1, plot2), wrap_script=False, wrap_plot_info=False) # => (javascript, (plot1_dict, plot2_dict)) components({"Plot 1": plot1, "Plot 2": plot2}, wrap_script=False, wrap_plot_info=False) # => (javascript, {"Plot 1": plot1_dict, "Plot 2": plot2_dict})
-
file_html
(models, resources, title=None, template=<Template 'file.html'>, template_variables={})¶ Return an HTML document that embeds Bokeh Model or Document objects.
The data for the plot is stored directly in the returned HTML.
This is an alias for standalone_html_page_for_models() which supports customizing the JS/CSS resources independently and customizing the jinja2 template.
Parameters: - models (Model or Document or list) – Bokeh object or objects to render typically a Model or Document
- resources (Resources or tuple(JSResources or None, CSSResources or None) – a resource configuration for Bokeh JS & CSS assets.
- title (str, optional) – a title for the HTML document
<title>
tags or None. (default: None) If None, attempt to automatically find the Document title from the given plot objects. - template (Template, optional) – HTML document template (default: FILE) A Jinja2 Template, see bokeh.core.templates.FILE for the required template parameters
- template_variables (dict, optional) – variables to be used in the Jinja2 template. If used, the following variable names will be overwritten: title, bokeh_js, bokeh_css, plot_script, plot_div
Returns: UTF-8 encoded HTML
-
notebook_div
(model, notebook_comms_target=None)¶ Return HTML for a div that will display a Bokeh plot in an IPython Notebook
The data for the plot is stored directly in the returned HTML.
Parameters: - model (Model) – Bokeh object to render
- notebook_comms_target (str, optional) – A target name for a Jupyter Comms object that can update the document that is rendered to this notebook div
Returns: UTF-8 encoded HTML text for a
<div>
Note
Assumes
load_notebook()
or the equivalent has already been executed.
-
standalone_html_page_for_models
(models, resources, title)¶ Return an HTML document that renders zero or more Bokeh documents or models.
The document for each model will be embedded directly in the HTML, so the resulting HTML file is standalone (does not require a server). Depending on the provided resources, the HTML file may be completely self-contained or may have to load JS and CSS from different files.
Parameters: Returns: UTF-8 encoded HTML