Template tags¶
Template tags are provided in the plotly_dash
library:
{%load plotly_dash%}
The plotly_app
template tag¶
Importing the plotly_dash
library provides the plotly_app
template tag:
{%load plotly_dash%}
{%plotly_app name="SimpleExample"%}
This tag inserts
a DjangoDash
app within a page as a responsive iframe
element.
The tag arguments are:
name = None: | The name of the application, as passed to a DjangoDash constructor. |
---|---|
slug = None: | The slug of an existing DashApp instance. |
da = None: | An existing django_plotly_dash.models.DashApp model instance. |
ratio = 0.1: | The ratio of height to width. The container will inherit its width as 100% of its parent, and then rely on this ratio to set its height. |
use_frameborder = “0”: | |
HTML element property of the iframe containing the application. | |
initial_arguments = None: | |
Initial arguments overriding app defaults and saved state. |
At least one of da
, slug
or name
must be provided. An object identified by slug
will always be used, otherwise any
identified by name
will be. If either of these arguments are provided, they must resolve to valid objects even if
not used. If neither are provided, then the model instance in da
will be used.
The initial_arguments
are specified as a python dictionary. This can be the actual dict
object, or
a JSON-encoded string representation. Each entry in the dictionary has the id
as key, and the corresponding
value is a dictionary mapping property
name keys to initial values.
The plotly_app_bootstrap
template tag¶
This is a variant of the plotly_app
template for use with responsive layouts using the Bootstrap library
{%load plotly_dash%}
{%plotly_app_bootstrap name="SimpleExample" aspect="16by9"%}
The tag arguments are similar to the plotly_app
ones:
name = None: | The name of the application, as passed to a DjangoDash constructor. |
---|---|
slug = None: | The slug of an existing DashApp instance. |
da = None: | An existing django_plotly_dash.models.DashApp model instance. |
aspect= “4by3”: | The aspect ratio of the app. Should be one of 21by9, 16by9, 4by3 or 1by1. |
initial_arguments = None: | |
Initial arguments overriding app defaults and saved state. |
At least one of da
, slug
or name
must be provided. An object identified by slug
will always be used, otherwise any
identified by name
will be. If either of these arguments are provided, they must resolve to valid objects even if
not used. If neither are provided, then the model instance in da
will be used.
The aspect ratio has to be one of the available ones from the Bootstrap framework.
The initial_arguments
are specified as a python dictionary. This can be the actual dict
object, or
a JSON-encoded string representation. Each entry in the dictionary has the id
as key, and the corresponding
value is a dictionary mapping property
name keys to initial values.
The plotly_direct
template tag¶
This template tag allows the direct insertion of html into a template, instead of embedding it in an iframe.
{%load plotly_dash%}
{%plotly_direct name="SimpleExample"%}
The tag arguments are:
name = None: | The name of the application, as passed to a DjangoDash constructor. |
---|---|
slug = None: | The slug of an existing DashApp instance. |
da = None: | An existing django_plotly_dash.models.DashApp model instance. |
These arguments are equivalent to the same ones for the plotly_app
template tag. Note
that initial_arguments
are not currently supported, and as the app is directly injected into
the page there are no arguments to control the size of the iframe.
This tag should not appear more than once on a page. This rule however is not enforced at present.
If this tag is used, then the header and footer tags should also be added to the template. Note that these tags in turn have middleware requirements.
The plotly_message_pipe
template tag¶
This template tag has to be inserted on every page that uses live updating:
{%load plotly_dash%}
{%plotly_app ... DjangoDash instances using live updating ... %}
{%plotly_message_pipe%}
The tag inserts javascript needed for the Pipe component to operate. It can be inserted anywhere
on the page, and its ordering relative to the Dash
instances using updating is not important, so placing it in
the page footer - to avoid delaying the main page load - along
with other scripts is generally advisable.
The plotly_app_identifier
template tag¶
This tag provides an identifier for an app, in a form that is suitable for use as a classname or identifier in HTML:
{%load plotly_dash%}
{%plotly_app_identifier name="SimpleExample"%}
{%plotly_app_identifier slug="liveoutput-2" postfix="A"%}
The identifier, if the tag is not passed a slug
, is the result of passing the identifier of the app through
the django.utils.text.slugify
function.
The tag arguments are:
name = None: | The name of the application, as passed to a DjangoDash constructor. |
---|---|
slug = None: | The slug of an existing DashApp instance. |
da = None: | An existing django_plotly_dash.models.DashApp model instance. |
postfix = None: | An optional string; if specified it is appended to the identifier with a hyphen. |
The validity rules for these arguments are the same as those for the plotly_app
template tag. If
supplied, the postfix
argument
should already be in a slug-friendly form, as no processing is performed on it.
The plotly_class
template tag¶
Generate a string of class names, suitable for a div
or other element that wraps around django-plotly-dash
template content.
{%load plotly_dash%}
<div class="{%plotly_class slug="liveoutput-2" postfix="A"%}">
{%plotly_app slug="liveoutput-2" ratio="0.5" %}
</div>
The identifier, if the tag is not passed a slug
, is the result of passing the identifier of the app through
the django.utils.text.slugify
function.
The tag arguments are:
name = None: | The name of the application, as passed to a DjangoDash constructor. |
---|---|
slug = None: | The slug of an existing DashApp instance. |
da = None: | An existing django_plotly_dash.models.DashApp model instance. |
prefix = None: | Optional prefix to use in place of the text django-plotly-dash in each class name |
postfix = None: | An optional string; if specified it is appended to the app-specific identifier with a hyphen. |
template_type = None: | |
Optional text to use in place of iframe in the template-specific class name |
The tag inserts a string with three class names in it. One is just the prefix
argument, one
has the template_type
appended, and the final one has the app identifier (as generated
by the plotly_app_identifier
tag) and any postfix
appended.
The validity rules for these arguments are the same as those for the plotly_app
and plotly_app_identifier
template tags. Note
that none of the prefix
, postfix
and template_type
arguments are modified and they should
already be in a slug-friendly form, or otherwise fit for their intended purpose.