Refactor code and add documentation

Author: Mark Gibbs

README.md

@@ -5,9 +5,14 @@ Expose [plotly dash](https://plot.ly/products/dash/) apps as django tags.
 See the source for this project here:
 <https://github.com/GibbsConsulting/django-plotly-dash>
 
-Online documentation can be found here:
+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>
 
+
 ## Installation
 
 First, install the package. This will also install plotly and some dash packages if they are not already present.

dev_requirements.txt

@@ -10,7 +10,6 @@ dash-html-components==0.10.1
 dash-renderer==0.12.1
 decorator==4.3.0
 Django==2.0.5
--e git+https://github.com/delsim/django-plotly-dash.git@293b454ee8965422155a971d9e417878dc89ce82#egg=django_plotly_dash
 docopt==0.6.2
 docutils==0.14
 Flask==1.0.2

django_plotly_dash/app_name.py

@@ -0,0 +1 @@
+app_name = "the_django_plotly_dash"

django_plotly_dash/dash_wrapper.py

@@ -3,18 +3,44 @@
 
 from django.urls import reverse
 
+from .app_name import app_name
+
 uid_counter = 0
 
 usable_apps = {}
 app_instances = {}
 nd_apps = {}
 
 def get_app_by_name(name):
+    '''
+    Locate a registered dash app by name, and return a DelayedDash instance encapsulating the app.
+    '''
     return usable_apps.get(name,None)
 
 def get_app_instance_by_id(id):
+    '''
+    Locate an instance of a dash app by identifier, or return None if one does not exist
+    '''
     return nd_apps.get(id,None)
 
+def get_or_form_app(id, name, **kwargs):
+    '''
+    Locate an instance of a dash app by identifier, loading or creating a new instance if needed
+    '''
+    app = get_app_instance_by_id(id)
+    if app:
+        return app
+    dd = get_app_by_name(name)
+    return dd.form_dash_instance()
+
+class Holder:
+    def __init__(self):
+        self.items = []
+    def append_css(self, stylesheet):
+        self.items.append(stylesheet)
+    def append_script(self, script):
+        self.items.append(script)
+
 class DelayedDash:
     def __init__(self, name=None, **kwargs):
         if name is None:
@@ -24,27 +50,27 @@ def __init__(self, name=None, **kwargs):
         else:
             self._uid = name
         self.layout = None
-        self._rep_dash = None
         self._callback_sets = []
 
+        self.css = Holder()
+        self.scripts = Holder()
+
         global usable_apps
         usable_apps[self._uid] = self
 
-    def _RepDash(self):
-        if self._rep_dash is None:
-            self._rep_dash = self._form_repdash()
-        return self._rep_dash
-
-    def _form_repdash(self):
+    def form_dash_instance(self):
         rd = NotDash(name_root=self._uid,
-                     app_pathname="django_plotly_dash:main")
+                     app_pathname="%s:main" % app_name)
         rd.layout = self.layout
+
         for cb, func in self._callback_sets:
             rd.callback(**cb)(func)
-        return rd
+        for s in self.css.items:
+            rd.css.append_css(s)
+        for s in self.scripts.items:
+            rd.scripts.append_script(s)
 
-    def base_url(self):
-        return self._RepDash().base_url()
+        return rd
 
     def callback(self, output, inputs=[], state=[], events=[]):
         callback_set = {'output':output,
@@ -92,12 +118,12 @@ def __init__(self, name_root, app_pathname, **kwargs):
 
         kwargs['url_base_pathname'] = self._base_pathname
         kwargs['server'] = self._notflask
+
         super(NotDash, self).__init__(**kwargs)
         global nd_apps
         nd_apps[self._uid] = self
-        if False: # True for some debug info and a load of errors...
-            self.css.config.serve_locally = True
-            self.scripts.config.serve_locally = True
+
+        self._adjust_id = False
 
     def flask_app(self):
         return self._flask_app
@@ -123,10 +149,13 @@ def locate_endpoint_function(self, name=None):
 
     @Dash.layout.setter
     def layout(self, value):
-        self._fix_component_id(value)
+
+        if self._adjust_id:
+            self._fix_component_id(value)
         return Dash.layout.fset(self, value)
 
     def _fix_component_id(self, component):
+
         theID = getattr(component,"id",None)
         if theID is not None:
             setattr(component,"id",self._fix_id(theID))
@@ -137,6 +166,8 @@ def _fix_component_id(self, component):
             pass
 
     def _fix_id(self, name):
+        if not self._adjust_id:
+            return name
         return "%s_-_%s" %(self._uid,
                            name)
 

django_plotly_dash/templates/django_plotly_dash/plotly_item.html

@@ -1,3 +1,3 @@
 <div>
-  <iframe src="{{url}}"></iframe>
+  <iframe src="{{app.base_url}}"></iframe>
 </div>

django_plotly_dash/templatetags/plotly_dash.py

@@ -2,12 +2,11 @@
 
 register = template.Library()
 
-from django_plotly_dash.dash_wrapper import get_app_by_name
+from django_plotly_dash.dash_wrapper import get_or_form_app
 
 @register.inclusion_tag("django_plotly_dash/plotly_item.html", takes_context=True)
 def plotly_item(context, app_name):
 
-    app = get_app_by_name(app_name)
-    url = app.base_url()
+    app = get_or_form_app(app_name, app_name)
 
     return locals()

django_plotly_dash/urls.py

@@ -3,7 +3,7 @@
 
 from .views import routes, layout, dependencies, update, main_view
 
-app_name = "django_plotly_dash"
+from .app_name import app_name
 
 urlpatterns = [
     path('<slug:id>_dash-routes', routes, name="routes"),

django_plotly_dash/views.py

@@ -3,7 +3,7 @@
 import flask
 import json
 
-from .dash_wrapper import get_app_instance_by_id
+from .dash_wrapper import get_app_instance_by_id, get_or_form_app
 from django.http import HttpResponse
 
 def routes(*args,**kwargs):
@@ -37,7 +37,7 @@ def update(request, id, **kwargs):
                         content_type=resp.mimetype)
 
 def main_view(request, id, **kwargs):
-    app = get_app_instance_by_id(id)
+    app = get_or_form_app(id, id)
     mFunc = app.locate_endpoint_function()
     resp = mFunc()
     return HttpResponse(resp)

docs/index.rst

@@ -3,15 +3,18 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to django-plotly-dash's documentation!
-==============================================
+django-plotly-dash
+==================
+
+`Plotly Dash <https://dash.plot.ly/>`_ applications served up in Django templates using tags.
 
 Contents
 --------
 
 .. toctree::
    :maxdepth: 2
 
+   introduction
    installation
    simple_use
 

docs/introduction.rst

@@ -0,0 +1,15 @@
+.. _introduction:
+
+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
+these features:
+
+* Multiple dash applications can be used on a single page
+* Separate instances of a dash application can persist along with internal state
+* Leverage user management and access control and other parts of the Django infrastructure
+* Consolidate into a single server process to simplify scaling
+
+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.