Live updating documentation

Mark Gibbs · Mark Gibbs · commit 54c52e3c880c · 2018-08-07T10:04:50.000-07:00
Documentation of the live updating feature, including the http endpoint and some comments on deployment.
Added a curl example.
Description of sending messages to Dash applications from within Django.
diff --git a/demo/demo/plotly_apps.py b/demo/demo/plotly_apps.py
@@ -190,7 +190,7 @@ def callback_liveIn_button_press(red_clicks, blue_clicks, green_clicks,
                      serve_locally=True)
 
 def _get_cache_key(state_uid):
-    return "demo-liveout-s4-%s" % state_uid
+    return "demo-liveout-s6-%s" % state_uid
 
 def generate_liveOut_layout():
     'Generate the layout per-app, generating each tine a new uuid for the state_uid argument'
@@ -244,6 +244,18 @@ def callback_liveOut_pipe_in(named_count, state_uid, **kwargs):
             colour_set = [(None, 0, 100) for i in range(5)]
 
         _, last_ts, prev = colour_set[-1]
+
+        # Loop over all existing timestamps and find the latest one
+        if not click_timestamp or click_timestamp < 1:
+            click_timestamp = 0
+
+            for _, the_colour_set in state.items():
+                _, lts, _ = the_colour_set[-1]
+                if lts > click_timestamp:
+                    click_timestamp = lts
+
+            click_timestamp = click_timestamp + 1000
+
         if click_timestamp > last_ts:
             colour_set.append((user, click_timestamp, prev * random.lognormvariate(0.0, 0.1)),)
             colour_set = colour_set[-100:]
@@ -270,23 +282,28 @@ def callback_show_timeseries(internal_state_string, state_uid, **kwargs):
 
     colour_series = {}
 
+    colors = {'red':'#FF0000',
+              'blue':'#0000FF',
+              'green':'#00FF00',
+              'yellow': '#FFFF00',
+              'cyan': '#00FFFF',
+              'magenta': '#FF00FF',
+              'black' : '#000000',
+             }
+
     for colour, values in state.items():
         timestamps = [datetime.fromtimestamp(int(0.001*ts)) for _, ts, _ in values if ts > 0]
         #users = [user for user, ts, _ in values if ts > 0]
         levels = [level for _, ts, level in values if ts > 0]
-        colour_series[colour] = pd.Series(levels, index=timestamps).groupby(level=0).first()
+        if colour in colors:
+            colour_series[colour] = pd.Series(levels, index=timestamps).groupby(level=0).first()
 
     df = pd.DataFrame(colour_series).fillna(method="ffill").reset_index()[-25:]
 
-    colors = {'red':'#FF0000',
-              'blue':'#0000FF',
-              'green':'#00FF00',
-             }
-
     traces = [go.Scatter(y=df[colour],
                          x=df['index'],
                          name=colour,
-                         line=dict(color=colors[colour]),
+                         line=dict(color=colors.get(colour,'#000000')),
                         ) for colour in colour_series]
 
     return {'data':traces,
diff --git a/demo/demo/templates/base.html b/demo/demo/templates/base.html
@@ -13,25 +13,20 @@
    <title>Django Plotly Dash Examples - {%block title%}{%endblock%}</title>
  </head>
  <body>
-   <header>
-     <nav class="navbar navbar-expand-lg navbar-dark bg-dark">
-       <div class="navbar-nav">
-         <a class="navbar-brand" href="#">
-           <img src="{%static "demo/logo.svg"%}" alt="Logo"/>
-         </a>
-         {%block demo_items%}
-         <a class="nav-item nav-link btn btn-lg" href="{%url "home"%}">Contents</a>
-         <a class="nav-item nav-link btn btn-lg" href="{%url "demo-one"%}">Demo One - Simple Use</a>
-         <a class="nav-item nav-link btn btn-lg" href="{%url "demo-two"%}">Demo Two - Initial State</a>
-         <a class="nav-item nav-link btn btn-lg" href="{%url "demo-three"%}">Demo Three - Enhanced Callbacks</a>
-         <a class="nav-item nav-link btn btn-lg" href="{%url "demo-four"%}">Demo Four - Live Updating</a>
-         {%endblock%}
-       </div>
-     </nav>
-   </header>
-   <main>
-     <div class="container">
-       {%block content%}{%endblock%}
+   <nav class="navbar navbar-expand-lg navbar-dark bg-dark">
+     <div class="navbar-nav">
+       <a class="navbar-brand" href="#">
+         <img src="{%static "demo/logo.svg"%}" alt="Logo"/>
+       </a>
+       <a class="nav-item nav-link btn btn-lg" href="{%url "home"%}">Contents</a>
+       <a class="nav-item nav-link btn btn-lg" href="{%url "demo-one"%}">Demo One - Simple Use</a>
+       <a class="nav-item nav-link btn btn-lg" href="{%url "demo-two"%}">Demo Two - Initial State</a>
+       <a class="nav-item nav-link btn btn-lg" href="{%url "demo-three"%}">Demo Three - Enhanced Callbacks</a>
+       <a class="nav-item nav-link btn btn-lg" href="{%url "demo-four"%}">Demo Four - Live Updating</a>
+
+       <a class="nav-item nav-link btn btn-lg"
+          target="_blank"
+          href="https://django-plotly-dash.readthedocs.io/en/latest/">Online Documentation</a>
      </div>
    </main>
    {%block footer%}
diff --git a/django_plotly_dash/urls.py b/django_plotly_dash/urls.py
@@ -31,6 +31,8 @@
 
 from .app_name import app_name, main_view_label
 
+from .views import add_to_session
+
 urlpatterns = [
     path('instance/<slug:ident>_dash-routes', routes, name="routes"),
     path('instance/<slug:ident>_dash-layout', layout, name="layout"),
@@ -50,4 +52,6 @@
     path('app/<slug:ident>', main_view, {'stateless':True}, name='app-%s'%main_view_label),
     path('app/<slug:ident>_dash-component-suites/<slug:component>/<resource>',
          component_suites, {'stateless':True}, name='app-component-suites'),
+
+    path('session', add_to_session, name="session-variable-example"),
     ]
diff --git a/django_plotly_dash/views.py b/django_plotly_dash/views.py
@@ -106,3 +106,17 @@ def component_suites(request, resource=None, component=None, **kwargs):
         redone_url = "/static/dash/%s/%s" %(component, resource)
 
     return HttpResponseRedirect(redirect_to=redone_url)
+
+
+from django.template.response import TemplateResponse
+
+def add_to_session(request, template_name="index.html", **kwargs):
+    'Add some info to a session in a place that django-plotly-dash can pass to a callback'
+
+    django_plotly_dash = request.session.get("django_plotly_dash", dict())
+
+    session_add_count = django_plotly_dash.get('add_counter',0)
+    django_plotly_dash['add_counter'] = session_add_count + 1
+    request.session['django_plotly_dash'] = django_plotly_dash
+
+    return TemplateResponse(request, template_name, {})
diff --git a/docs/updating.rst b/docs/updating.rst
@@ -12,6 +12,13 @@ The messages are constrained to be JSON serialisable, as that is how they are tr
 also be as small as possible given that they travel from the server, to each interested client, and then back to the
 server again as an argument to one or more callback functions.
 
+The round-trip of the message is a deliberate design choice, in order to enable the value within the message to be treated
+as much as possible like any other piece of data within a ``Dash`` application. This data is essentially stored
+on the client side of the client-server split, and passed to the server when each callback is invoked; note that this also
+encourages designs that keep the size of in-application data small. An
+alternative approach, such as directly invoking
+a callback in the server, would require the server to maintain its own copy of the application state.
+
 Live updating requires a server setup that is considerably more
 complex than the alternative, namely use of the built-in `Interval <https://dash.plot.ly/live-updates>`_ component. However, live
 updating can be used to reduce server load (as callbacks are only made when needed) and application latency (as callbacks are
@@ -64,10 +71,38 @@ introduces another indeterminacy.
 HTTP Endpoint
 -------------
 
-There is an HTTP endpoint that allows direct insertion of messages into a message channel.
+There is an HTTP endpoint, configured with
+the ``http_route`` option, that allows direct insertion of messages into a message channel. It is a
+direct equivalent of calling the ``send_to_pipe_channel`` function, and
+expects the ``channel_name``, ``label`` and ``value`` arguments to be provided in a JSON-encoded
+dictionary.
+
+.. code-block:: bash
+
+   curl -d '{"channel_name":"live_button_counter",
+             "label":"named_counts",
+             "value":{"click_colour":"cyan"}}'
+             http://localhost:8000/dpd/views/poke/
+
+This will cause the (JSON-encoded) ``value`` argument to be sent on the ``channel_name`` channel with
+the given ``label``.
+
+The provided endpoint skips any CSRF checks
+and does not perform any security checks such as authentication or authorisation, and should
+be regarded as a starting point for a more complete implementation if exposing this functionality is desired. On the
+other hand, if this endpoint is restricted so that it is only available from trusted sources such as the server
+itself, it does provide a mechanism for Django code running outside of the ASGI server, such as in a WSGI process or
+Celery worker, to push a message out to running applications.
 
 Deployment
 ----------
 
-Need redis and daphne.
+The live updating feature needs both Redis, as it is the only supported backend at present for v2.0 and up of
+Channels, and Daphne or any other ASGI server for production use. It is also good practise to place the server(s) behind
+a reverse proxy such as Nginx; this can then also be configured to serve Django's static files.
+
+A further consideration is the use of a WSGI server, such as Gunicorn, to serve the non-asynchronous subset of the http
+routes, albeit at the expense of having to separately manage ASGI and WSGI servers. This can be easily achieved through selective
+routing at the reverse proxy level, and is the driver behind the ``ws_route`` configuration option.
 
+In passing, note that the demo also uses Redis as the caching backend for Django.
