toyplot.html module¶
Functions to render the canonical HTML representation of a Toyplot figure.
- class toyplot.html.RenderContext(scenegraph, root)[source]¶
Bases:
object
Stores context data during rendering.
This is only of use for Toyplot developers and library developers who are implementing rendering code. It is not intended for end-users.
- already_rendered(o)[source]¶
Track whether an object has already been rendered.
Used to prevent objects that can be shared, such as
toyplot.coordinates.Axis
, from generating duplicate markup in the output HTML.- Parameters
o (any Python object, required) –
- Returns
rendered – If the given object hasn’t already been rendered, records it as rendered and returns False. Subsequent calls with the given object will always return True.
- Return type
Examples
The following checks to see if mark has already been rendered:
if not context.already_rendered(mark): # Render the mark
- property animation¶
Warning
property ‘toyplot.html.RenderContext.animation’ undocumented
- copy(parent)[source]¶
Copy the current
toyplot.html.RenderContext
.Creates a copy of the current render context that can be used to render children of the currently-rendered object.
- Parameters
parent (any Python object, required.) –
- Returns
context – The parent attribute will be set to the supplied parent object.
- Return type
- define(name, dependencies=None, factory=None, value=None)[source]¶
Define a Javascript module that can be embedded in the output markup.
The module will only be embedded in the output if it is listed as a dependency of another module, or code specified using
require()
.You must specify either factory or value.
- Parameters
name (string, required) – Module name. Any string is valid, but alphanumerics separated with slashes are recommended. Multiple calls to define with the same name argument will be silently ignored.
dependencies (sequence of strings, optional) – Names of modules that are dependencies of this module.
factory (string, optional) – Javascript code that will construct the module, which must be a function that takes the modules listed in dependencies, in-order, as arguments, and returns the initialized module.
value (Python object, optional) – Arbitrary value for this module, which must be compatible with
json.dumps()
.
- get_id(o)[source]¶
Return a globally unique identifier for an object.
The generated identifier is cached, so multiple lookups on the same object will return consistent results.
- Parameters
o (any Python object, required.) –
- Returns
id – Globally unique identifier that can be used in HTML markup as an identifier that can be targeted from Javascript code.
- Return type
- property parent¶
Current DOM node. Typical rendering code will append HTML content to this node.
- require(dependencies=None, arguments=None, code=None)[source]¶
Embed Javascript code and its dependencies into the output markup.
The given code will be unconditionally embedded in the output markup, along with any modules listed as dependencies (plus their dependencies, and-so-on).
- Parameters
dependencies (sequence of strings, optional) – Names of modules that are required by this code.
arguments (sequence of Python objects, optional) – Additional arguments to be passed to the Javascript code, which must be compatible with
json.dumps()
.code (string, required) – Javascript code to be embedded, which must be a function that accepts the modules listed in requirements in-order, followed by the values listed in arguments in-order, as arguments.
- property root¶
Top-level DOM node.
- property scenegraph¶
Warning
property ‘toyplot.html.RenderContext.scenegraph’ undocumented
- toyplot.html.apply_changes(html, changes)[source]¶
Warning
function ‘toyplot.html.apply_changes’ undocumented
- toyplot.html.dispatch(*types, **kwargs)¶
Decorator for registering custom rendering code.
This is only of use when creating your own custom Toyplot marks. It is not intended for end-users.
Example
To register your own rendering function:
@toyplot.html.dispatch(toyplot.coordinates.Cartesian, MyCustomMark, toyplot.html.RenderContext) def _render(axes, mark, context): # Rendering implementation here
- toyplot.html.render(canvas, fobj=None, animation=False, style=None)[source]¶
Convert a canvas to its HTML DOM representation.
Generates HTML markup with an embedded SVG representation of the canvas, plus JavaScript code for interactivity. If the canvas contains animation, the markup will include an HTML user interface to control playback.
- Parameters
canvas (
toyplot.canvas.Canvas
) – The canvas to be rendered.fobj (file-like object or string, optional) – The file to write. Use a string filepath to write data directly to disk. If None (the default), the HTML tree will be returned to the caller instead.
animation (boolean, optional) – If True, return a representation of the changes to be made to the HTML tree for animation.
style (dict, optional) – Dictionary of CSS styles that will be applied to the top-level output <div>.
- Returns
html (
xml.etree.ElementTree.Element
or None) – HTML representation of canvas, as a DOM tree, or None if the caller specifies the fobj parameter.changes (JSON-compatible data structure, or None) – JSON-compatible representation of the animated changes to canvas.
Notes
The output HTML is the “canonical” representation of a Toyplot canvas - the other toyplot backends operate by converting the output from toyplot.html.render() to the desired end target.
Note that the output HTML is a fragment wrapped in a <div>, suitable for embedding in a larger document. It is the caller’s responsibility to supply the <html>, <body> etc. if the result is intended as a standalone HTML document.
- toyplot.html.tostring(canvas, style=None)[source]¶
Convert a canvas to its HTML string representation.
Generates HTML markup with an embedded SVG representation of the canvas, plus JavaScript code for interactivity. If the canvas contains animation, the markup will include an HTML user interface to control playback.
- Parameters
canvas (
toyplot.canvas.Canvas
) – The canvas to be rendered.style (dict, optional) – Dictionary of CSS styles that will be applied to the top-level output <div>.
- Returns
html – HTML representation of canvas as a string.
- Return type
Notes
The output HTML is a fragment wrapped in a <div>, suitable for embedding in a larger document. It is the caller’s responsibility to supply the <html>, <body> etc. if the result is intended as a standalone HTML document.