User guide examples for bokeh server and django (#60)

doc/user_guide/index.rst

@@ -7,17 +7,22 @@ Contents:
 * `Introduction <Introduction.html>`_
    What is ParamBokeh, and how to use it?
 
-* `Usage in Bokeh Apps <Bokeh_App.html>`_
-   How to use ParamBokeh in a Bokeh application.
-
 * `ViewParameters <View_Parameters.html>`_
    Dynamically control some visual output.
 
+* `Bokeh Apps <Bokeh_App.html>`_
+   How to use ParamBokeh in a Bokeh server application.
+
+* `Django Apps <Django_App.html>`_
+   How to use ParamBokeh in a Django application.
+
+
 
 .. toctree::
     :titlesonly:
     :maxdepth: 2
 
     Introduction
-    Bokeh Apps <Bokeh_App>
     View Parameters <View_Parameters>
+    Bokeh Apps <Bokeh_Apps>
+    Django Apps <Django_Apps>

examples/apps/bokeh/simple.py

@@ -0,0 +1,34 @@
+##### existing parameterized class
+
+import param
+import datetime as dt
+
+class Example(param.Parameterized):
+    """Example Parameterized class"""
+    log = []
+    x            = param.Number(default=1.0,bounds=(0,100),precedence=0,doc="X position")
+    write_to_log = param.Action(lambda obj: obj.log.append((dt.datetime.now(),obj.x)), 
+                                doc="""Record value of x and timestamp.""",precedence=1)
+
+##### create a properties frame for Example
+
+import parambokeh
+w = parambokeh.Widgets(Example, mode='server')
+
+
+##### display value of Example.log in bokeh app
+
+from bokeh.io import curdoc
+from bokeh.layouts import layout
+from bokeh.models import Div
+
+log = Div()
+
+def update_log():
+    log.text = "<br />".join(["%s -- %s"%(t[0].strftime('%H:%M:%S.%f'),t[1]) for t in Example.log])
+
+curdoc().add_periodic_callback(update_log, 200)
+
+layout = layout([log])
+curdoc().add_root(layout)
+curdoc().title = "simple parambokeh + bokeh server example"

examples/user_guide/Bokeh_Apps.ipynb

@@ -0,0 +1,164 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In the [Introduction](Introduction.ipynb), we showed how to use parambokeh, using the Jupyter notebook to host our example. However, parambokeh widgets can also be used in other contexts. Here we show how parambokeh can be used in a bokeh server app."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We'll create a simple bokeh app that displays a log of every time a button has been pressed:\n",
+    "\n",
+    "![screenshot of simple app](simple.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In a python script, [examples/app/bokeh/simple.py](../apps/bokeh/simple.py), we first declare a sample Parameterized class to use as a demonstration object:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```python\n",
+    "# existing parameterized class\n",
+    "\n",
+    "import param\n",
+    "import datetime as dt\n",
+    "\n",
+    "class Example(param.Parameterized):\n",
+    "    \"\"\"Example Parameterized class\"\"\"\n",
+    "    log = []\n",
+    "    x            = param.Number(default=1.0,bounds=(0,100),precedence=0,doc=\"X position\")\n",
+    "    write_to_log = param.Action(lambda obj: obj.log.append((dt.datetime.now(),obj.x)), \n",
+    "                                doc=\"\"\"Record value of x and timestamp.\"\"\",precedence=1)\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Whenever `Example.write_to_log` is called, the current time and value of `x` are stored in `Example.log`.\n",
+    "\n",
+    "We now create a properties frame, just as in the [Introduction](Introduction.ipynb), but this time specifying `mode='server'`:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```python\n",
+    "# create a properties frame for Example\n",
+    "\n",
+    "import parambokeh\n",
+    "w = parambokeh.Widgets(Example, mode='server')\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally, we write a simple bokeh app that periodically updates a display showing the value of `Example.log`:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```python\n",
+    "# display value of Example.log in bokeh app\n",
+    "\n",
+    "from bokeh.io import curdoc\n",
+    "from bokeh.layouts import layout\n",
+    "from bokeh.models import Div\n",
+    "\n",
+    "log = Div()\n",
+    "\n",
+    "def update_log():\n",
+    "    log.text = \"<br />\".join([\"%s -- %s\"%(t[0].strftime('%H:%M:%S.%f'),t[1]) for t in Example.log])\n",
+    "\n",
+    "curdoc().add_periodic_callback(update_log, 200)\n",
+    "\n",
+    "layout = layout([log])\n",
+    "curdoc().add_root(layout)\n",
+    "curdoc().title = \"simple parambokeh + bokeh server example\"\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The app can be launched using `bokeh serve simple.py`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "-----\n",
+    "\n",
+    "The example code used here is in [examples/app/bokeh/simple.py](../apps/bokeh/simple.py). For reference, the entire file is reproduced below:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```python\n",
+    "##### existing parameterized class\n",
+    "\n",
+    "import param\n",
+    "import datetime as dt\n",
+    "\n",
+    "class Example(param.Parameterized):\n",
+    "    \"\"\"Example Parameterized class\"\"\"\n",
+    "    log = []\n",
+    "    x            = param.Number(default=1.0,bounds=(0,100),precedence=0,doc=\"X position\")\n",
+    "    write_to_log = param.Action(lambda obj: obj.log.append((dt.datetime.now(),obj.x)), \n",
+    "                                doc=\"\"\"Record value of x and timestamp.\"\"\",precedence=1)\n",
+    "\n",
+    "##### create a properties frame for Example\n",
+    "\n",
+    "import parambokeh\n",
+    "w = parambokeh.Widgets(Example, mode='server')\n",
+    "\n",
+    "\n",
+    "##### display value of Example.log in bokeh app\n",
+    "\n",
+    "from bokeh.io import curdoc\n",
+    "from bokeh.layouts import layout\n",
+    "from bokeh.models import Div\n",
+    "\n",
+    "log = Div()\n",
+    "\n",
+    "def update_log():\n",
+    "    log.text = \"<br />\".join([\"%s -- %s\"%(t[0].strftime('%H:%M:%S.%f'),t[1]) for t in Example.log])\n",
+    "\n",
+    "curdoc().add_periodic_callback(update_log, 200)\n",
+    "\n",
+    "layout = layout([log])\n",
+    "curdoc().add_root(layout)\n",
+    "curdoc().title = \"simple parambokeh + bokeh server example\"\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}