Added model documentation

Author: Mark Gibbs

django_plotly_dash/models.py

@@ -69,6 +69,11 @@ def update_current_state(self, wid, key, value):
                 setattr(self,'_current_state_hydrated_changed',True)
 
     def current_state(self):
+        '''
+        Return the current internal state of the model instance.
+
+        This is not necessarily the same as the persisted state stored in the self.base_state variable.
+        '''
         cs = getattr(self,'_current_state_hydrated',None)
         if not cs:
             cs = json.loads(self.base_state)

docs/extended_callbacks.rst

@@ -9,7 +9,15 @@ To do this, simply replace ``callback`` with ``expanded_callback`` when register
 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::
+For example, the ``plotly_apps.py`` example contains this dash application:
+
+.. code-block:: python
+
+  import dash
+  import dash_core_components as dcc
+  import dash_html_components as html
+
+  from django_plotly_dash import DjangoDash
 
   a2 = DjangoDash("Ex2")
 

docs/models_and_state.rst

@@ -2,3 +2,52 @@
 
 Django models and application state
 ================
+
+The ``django_plotly_dash`` application defines a ``DashApp`` model. This represents an instance of application state.
+
+.. code-block:: python
+
+    class DashApp(models.Model):
+        '''
+        An instance of this model represents a Dash application and its internal state
+        '''
+        app_name = models.CharField(max_length=100, blank=False, null=False, unique=False)
+        instance_name = models.CharField(max_length=100, unique=True, blank=True, null=False)
+        slug = models.SlugField(max_length=110, unique=True, blank=True)
+        base_state = models.TextField(null=False, default="{}")
+        creation = models.DateTimeField(auto_now_add=True)
+        update = models.DateTimeField(auto_now=True)
+        save_on_change = models.BooleanField(null=False,default=False)
+
+        ... methods, mainly for managing the Dash application state ...
+
+        def current_state(self):
+            '''
+            Return the current internal state of the model instance
+            '''
+
+        def update_current_state(self, wid, key, value):
+            '''
+            Update the current internal state, ignorning non-tracked objects
+            '''
+
+        def populate_values(self):
+            '''
+            Add values from the underlying dash layout configuration
+            '''
+
+The ``app_name`` corresponds to an application registered through the instantiation of a ``DjangoDash`` object. The ``slug`` field provides a unique identifier
+that is used in URLs to identify the instance of an application, and also its associated server-side state.
+
+The persisted state of the instance is contained, serialised as JSON, in the ``base_state`` variable. This is an arbitrary subset of the internal state of the
+object. Whenever a ``Dash`` application requests its state (through the ``<app slug>_dash-layout`` url), any values from the underlying application that are present in
+``base_state``  are overwritten with the persisted values.
+
+The ``populate_values`` member function can be used to insert all possible initial values into ``base_state``. This functionality is also exposed in the Django
+admin for these model instances, as a ``Populate app`` action.
+
+From callback code, the ``update_current_state`` method can be called to change the initial value of any variable tracked within the ``base_state``. Variables not tracked
+will be ignored. This function is automatically called for any callback argument and return value.
+
+Finally, after any callback has finished, and after any result stored through ``update_current_state``, then the application model instance will be persisted by means
+of a call to its ``save`` method, if any changes have been detected and the ``save_on_change`` flag is ``True``.

docs/simple_use.rst

@@ -6,7 +6,9 @@ Simple usage
 To use existing dash applications, first register them using the ``DjangoDash`` class. This
 replaces the ``Dash`` class from the ``dash`` package.
 
-Taking a simple example inspired by the excellent `getting started <https://dash.plot.ly/getting-started-part-2>`_ guide::
+Taking a simple example inspired by the excellent `getting started <https://dash.plot.ly/getting-started-part-2>`_ guide:
+
+.. code-block:: python
 
   import dash
   import dash_core_components as dcc