Documentation on extended callbacks and an overview of how things work

Author: Mark Gibbs

README.md

@@ -1,13 +1,17 @@
 # django-plotly-dash
 
-Expose [plotly dash](https://plot.ly/products/dash/) apps as django tags.
+Expose [plotly dash](https://plot.ly/products/dash/) apps as [Django](https:://www.djangoproject.com/) tags. Multiple Dash apps can
+then be embedded into a single web page, persist and share internal state, and also have access to the
+current user and session variables.
 
 See the source for this project here:
 <https://github.com/GibbsConsulting/django-plotly-dash>
 
 This README file provides a short guide to installing and using the package, and also
 outlines how to run the demonstration application.
 
+
+
 More detailed information
 can be found in the online documentation at
 <https://readthedocs.org/projects/django-plotly-dash>

demo/demo/plotly_apps.py

@@ -39,7 +39,7 @@ def callback_size(dropdown_color, dropdown_size):
 a2 = DjangoDash("Ex2")
 a2.layout = html.Div([
     dcc.RadioItems(id="dropdown-one",options=[{'label':i,'value':j} for i,j in [
-    ("O2","Oxygen"),("N2","Nitrogen"),]
+    ("O2","Oxygen"),("N2","Nitrogen"),("CO2","Carbon Dioxide")]
     ],value="Oxygen"),
     html.Div(id="output-one")
     ])
@@ -50,5 +50,5 @@ def callback_size(dropdown_color, dropdown_size):
     )
 def callback_c(*args,**kwargs):
     da = kwargs['dash_app']
-    return "Args are %s and kwargs are %s" %("".join(*args),str(kwargs))
+    return "Args are [%s] and kwargs are %s" %(",".join(args),str(kwargs))
 

docs/extended_callbacks.rst

@@ -4,3 +4,47 @@ Extended callback syntax
 ========================
 
 The ``DjangoDash`` class allows callbacks to request extra arguments when registered.
+
+To do this, simply replace ``callback`` with ``expanded_callback`` when registering any callback. This will cause all of the callbacks
+registered with this application
+to receive extra ``kwargs`` in addition to the callback parameters.
+
+For example, the ``plotly_apps.py`` example contains this dash application::
+
+  a2 = DjangoDash("Ex2")
+
+  a2.layout = html.Div([
+      dcc.RadioItems(id="dropdown-one",options=[{'label':i,'value':j} for i,j in [
+      ("O2","Oxygen"),("N2","Nitrogen"),("CO2","Carbon Dioxide")]
+      ],value="Oxygen"),
+      html.Div(id="output-one")
+      ])
+
+  @a2.expanded_callback(
+      dash.dependencies.Output('output-one','children'),
+      [dash.dependencies.Input('dropdown-one','value')]
+      )
+
+  def callback_c(*args,**kwargs):
+      da = kwargs['dash_app']
+      return "Args are [%s] and kwargs are %s" %(",".join(args),str(kwargs))
+
+The additional arguments, which are reported as the ``kwargs`` content in this example, include
+
+:dash_app: For stateful applications, the ``DashApp`` model instance
+:dash_app_id: The application identifier. For stateless applications, this is the (slugified) name given to the ``DjangoDash`` constructor.
+              For stateful applications, it is the (slugified) unique identifier for the associated model instance.
+:session_state: A dictionary of information, unique to this user session. Any changes made to its content during the
+                callback are persisted as part of the Django session framework.
+:user: The Django User instance.
+
+The ``DashApp`` model instance can also be configured to persist itself on any change. This is discussed
+in the :ref:`models_and_state` section.
+
+
+.. _using_session_state:
+Using session state
+------------------
+
+Changes to the session state and other server-side objects are not automatically propagated to an application. Something in the front-end UI has to invoke a callaback; at this point the latest version of these objects will be provided to the callback. The same considerations as in other Dash `live updates <https://dash.plot.ly/live-updates>`_ apply.
+

docs/introduction.rst

@@ -3,7 +3,8 @@
 Introduction
 ============
 
-The purpose of django-plotly-dash is to enable Plotly Dash applications to be served up as part of a Django application, in order to provide
+The purpose of ``django-plotly-dash`` is to enable `Plotly Dash <https://dash.plot.ly>`_ applications
+to be served up as part of a `Django <https://www.djangoproject.com/>`_ application, in order to provide
 these features:
 
 * Multiple dash applications can be used on a single page
@@ -13,3 +14,18 @@ these features:
 
 There is nothing here that cannot be achieved through expanding the Flask app around Plotly Dash, or indeed by using an alternative web
 framework. The purpose of this project is to enable the above features, given that the choice to use Django has already been made.
+
+.. _overview:
+Overview
+--------
+
+``django_plotly_dash`` works by wrapping around the ``dash.Dash`` object. The http endpoints exposed by the
+``Dash`` application are mapped to Django ones, and an application is embedded into a webpage through the
+use of a template tag. Multiple ``Dash`` applications can be used in a single page.
+
+A subset of the internal state of a ``Dash`` application can be persisted as a standard Django model instance, and the application with this
+internal state is then available at its own URL. This can then be embedded into one or more pages in the same manner as described
+above for stateless applications.
+
+Also, an enhanced version of the ``Dash`` callback is provided, giving the callback access to the current User, the current session, and also
+the model instance associated with the application's internal state.