panel.reactive module#
Declares Syncable and Reactive classes which provides baseclasses for Panel components which sync their state with one or more bokeh models rendered on the frontend.
- class panel.reactive.Reactive(refs=None, **params)[source]#
Bases:
Syncable
,Viewable
Reactive is a Viewable object that also supports syncing between the objects parameters and the underlying bokeh model either via the defined pyviz_comms.Comm type or using bokeh server.
In addition it defines various methods which make it easy to link the parameters to other objects.
Methods
controls
([parameters,Ā jslink])Creates a set of widgets which allow manipulating the parameters on this instance.
jscallback
([args])Allows defining a JS callback to be triggered when a property changes on the source object.
jslink
(target[,Ā code,Ā args,Ā bidirectional])Links properties on the this Reactive object to those on the target Reactive object in JS code.
link
(target[,Ā callbacks,Ā bidirectional])Links the parameters on this Reactive object to attributes on the target Parameterized object.
Parameter Definitions
Parameters inherited from:
panel.viewable.Layoutable
: align, aspect_ratio, css_classes, design, height, min_width, min_height, max_width, max_height, margin, styles, stylesheets, tags, width, width_policy, height_policy, sizing_mode, visiblepanel.viewable.Viewable
: loading- controls(parameters: list[str] = [], jslink: bool = True, **kwargs) BasePanel [source]#
Creates a set of widgets which allow manipulating the parameters on this instance. By default all parameters which support linking are exposed, but an explicit list of parameters can be provided.
- Parameters:
- parameters: list(str)
An explicit list of parameters to return controls for.
- jslink: bool
Whether to use jslinks instead of Python based links. This does not allow using all types of parameters.
- kwargs: dict
Additional kwargs to pass to the Param pane(s) used to generate the controls widgets.
- Returns:
- A layout of the controls
- jscallback(args: dict[str, Any] = {}, **callbacks: str) Callback [source]#
Allows defining a JS callback to be triggered when a property changes on the source object. The keyword arguments define the properties that trigger a callback and the JS code that gets executed.
- Parameters:
- args: dict
A mapping of objects to make available to the JS callback
- callbacks: dict
A mapping between properties on the source model and the code to execute when that property changes
- Returns:
- callback: Callback
The Callback which can be used to disable the callback.
- jslink(target: JSLinkTarget, code: dict[str, str] | None = None, args: dict | None = None, bidirectional: bool = False, **links: str) Link [source]#
Links properties on the this Reactive object to those on the target Reactive object in JS code.
Supports two modes, either specify a mapping between the source and target model properties as keywords or provide a dictionary of JS code snippets which maps from the source parameter to a JS code snippet which is executed when the property changes.
- Parameters:
- target: panel.viewable.Viewable | bokeh.model.Model | holoviews.core.dimension.Dimensioned
The target to link the value to.
- code: dict
Custom code which will be executed when the widget value changes.
- args: dict
A mapping of objects to make available to the JS callback
- bidirectional: boolean
Whether to link source and target bi-directionally
- links: dict
A mapping between properties on the source model and the target model property to link it to.
- Returns:
- link: GenericLink
The GenericLink which can be used unlink the widget and the target model.
- link(target: Parameterized, callbacks: dict[str, str | Callable] | None = None, bidirectional: bool = False, **links: str) Watcher [source]#
Links the parameters on this Reactive object to attributes on the target Parameterized object.
Supports two modes, either specify a mapping between the source and target object parameters as keywords or provide a dictionary of callbacks which maps from the source parameter to a callback which is triggered when the parameter changes.
- Parameters:
- target: param.Parameterized
The target object of the link.
- callbacks: dict | None
Maps from a parameter in the source object to a callback.
- bidirectional: bool
Whether to link source and target bi-directionally
- links: dict
Maps between parameters on this object to the parameters on the supplied object.
- class panel.reactive.ReactiveData(*, selection, loading, align, aspect_ratio, css_classes, design, height, height_policy, margin, max_height, max_width, min_height, min_width, sizing_mode, styles, stylesheets, tags, visible, width, width_policy, name)[source]#
Bases:
SyncableData
An extension of SyncableData which bi-directionally syncs a data parameter between frontend and backend using a ColumnDataSource.
Parameter Definitions
Parameters inherited from:
panel.viewable.Layoutable
: align, aspect_ratio, css_classes, design, height, min_width, min_height, max_width, max_height, margin, styles, stylesheets, tags, width, width_policy, height_policy, sizing_mode, visiblepanel.viewable.Viewable
: loadingpanel.reactive.SyncableData
: selection
- class panel.reactive.ReactiveHTML(*, loading, align, aspect_ratio, css_classes, design, height, height_policy, margin, max_height, max_width, min_height, min_width, sizing_mode, styles, stylesheets, tags, visible, width, width_policy, name)[source]#
Bases:
ReactiveCustomBase
The ReactiveHTML class enables you to create custom Panel components using HTML, CSS and/ or Javascript and without the complexities of Javascript build tools.
A ReactiveHTML subclass provides bi-directional syncing of its parameters with arbitrary HTML elements, attributes and properties. The key part of the subclass is the _template variable. This is the HTML template that gets rendered and declares how to link parameters on the subclass to HTML.
>>> import panel as pn >>> import param >>> class CustomComponent(pn.reactive.ReactiveHTML): ... ... index = param.Integer(default=0) ... ... _template = '<img id="slideshow" src="https://picsum.photos/800/300?image=${index}" onclick="${_img_click}"></img>' ... ... def _img_click(self, event): ... self.index += 1 >>> CustomComponent(width=500, height=200).servable()
HTML templates#
A ReactiveHTML component is declared by providing an HTML template on the _template attribute on the class. Parameters are synced by inserting them as template variables of the form ${parameter_name}, e.g.:
<div class=ā${parameter_1}ā>${parameter_2}</div>
will interpolate the parameter1 parameter on the class. In addition to providing attributes we can also provide children to an HTML tag. By default any parameter referenced as a child will be treated as a Panel components to be rendered into the containing HTML. This makes it possible to use ReactiveHTML to lay out other components.
Children#
As mentioned above parameters may be referenced as children of a DOM node and will, by default, be treated as Panel components to insert on the DOM node. However by declaring a _child_config we can control how the DOM nodes are treated. The _child_config is indexed by parameter name and may declare one of three rendering modes:
model (default): Create child and render child as a Panel component into it.
literal: Create child and set child as its innerHTML.
template: Set child as innerHTML of the container.
If the type is ātemplateā the parameter will be inserted as is and the DOM nodeās innerHTML will be synced with the child parameter.
DOM Events#
In certain cases it is necessary to explicitly declare event listeners on the DOM node to ensure that changes in their properties are synced when an event is fired. To make this possible the HTML element in question must be given a unique id, e.g.:
<input id=āinput_elā></input>
Now we can use this name to declare set of _dom_events to subscribe to. The following will subscribe to change DOM events on the input element:
{āinput_elā: [āchangeā]}
Once subscribed the class may also define a method following the _{node}_{event} naming convention which will fire when the DOM event triggers, e.g. we could define a _input_el_change method. Any such callback will be given a DOMEvent object as the first and only argument. The DOMEvent contains information about the event on the .data attribute and declares the type of event on the .type attribute.
Inline callbacks#
Instead of declaring explicit DOM events Python callbacks can also be declared inline, e.g.:
<input id=āinput_elā onchange=ā${_input_change}ā></input>
will look for an _input_change method on the ReactiveHTML component and call it when the event is fired.
Additionally we can invoke pure JS scripts defined on the class, e.g.:
<input id=āinput_elā onchange=ā${script(āsome_scriptā)}ā></input>
This will invoke the following script if it is defined on the class:
- _scripts = {
āsome_scriptā: āconsole.log(model, data, input_el, view)ā
}
Scripts#
In addition to declaring callbacks in Python it is also possible to declare Javascript callbacks to execute when any synced attribute changes. Let us say we have declared an input element with a synced value parameter:
<input id=āinput_elā value=ā${value}ā></input>
We can now declare a set of _scripts, which will fire whenever the value updates:
- _scripts = {
āvalueā: āconsole.log(model, data, input_el)ā
}
The Javascript is provided multiple objects in its namespace including:
- dataThe data model holds the current values of the synced
parameters, e.g. data.value will reflect the current value of the input_el node.
- model: The ReactiveHTML model which holds layout information
and information about the children and events.
- state: An empty state dictionary which scripts can use to
store state for the lifetime of the view.
- view: The Bokeh View class responsible for rendering the
component. This provides access to method like invalidate_layout and run_script which allows invoking other scripts.
- <node>: All named DOM nodes in the HTML template, e.g. the
input_el node in the example above.
Methods
on_event
(node,Ā event,Ā callback)Registers a callback to be executed when the specified DOM event is triggered on the named node.
Parameter Definitions
Parameters inherited from:
panel.viewable.Layoutable
: align, aspect_ratio, css_classes, design, height, min_width, min_height, max_width, max_height, margin, styles, stylesheets, tags, width, width_policy, height_policy, sizing_mode, visiblepanel.viewable.Viewable
: loading- on_event(node: str, event: str, callback: Callable) None [source]#
Registers a callback to be executed when the specified DOM event is triggered on the named node. Note that the named node must be declared in the HTML. To create a named node you must give it an id of the form id=ānameā, where name will be the node identifier.
- Parameters:
- node: str
Named node in the HTML identifiable via id of the form id=ānameā.
- event: str
Name of the DOM event to add an event listener to.
- callback: callable
A callable which will be given the DOMEvent object.