Template tags are provided in the plotly_dash
library:
{%load plotly_dash%}
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.
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.
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 :ref:`header and footer <plotly_header_footer>` tags should also be added to the template. Note that these tags in turn have middleware requirements.
DjangoDash
allows you to inject directly the html generated by Dash
in
the DOM of the page without wrapping it in an iframe. To include the app CSS and JS, two tags
should be included in the template, namely plotly_header
and plotly_footer
, as
follows:
<!-- templates/base.html -->
<!DOCTYPE html>
<html>
<head>
...
{% load plotly_dash%}
...
{% plotly_header %}
...
</head>
<body>
...
{%plotly_direct name="SimpleExample"%}
...
</body>
...
{% plotly_footer %}
</html>
This part in mandatory if you want to use the :ref:`plotly_direct <plotly_direct>` tag, and these two tags can safely be included
on any page that has loaded the plotly_dash
template tag library with minimal overhead, making them
suitable for inclusion in a base template. Neither tag has
any arguments.
Note that if you are using any functionality that needs the use of these tags, then the associated middleware
should be added in settings.py
MIDDLEWARE = [
...
'django_plotly_dash.middleware.BaseMiddleware',
]
This middleware should appear low down the middleware list.
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 :ref:`Pipe <pipe_component>` 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.
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.
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.