examples/js_proxy example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# js_proxy\n",
    "\n",
    "The `js_proxy` widget implementation is meant to be the widget to end all widgets (sort of).\n",
    "\n",
    "To implement a Jupyter/Python/javascript widget you generally need a Python side implementation\n",
    "for the widget and a Javascript side for the widget which match up to eachother.  In general to\n",
    "add more features to the widget you need to modify both sides in matching ways.\n",
    "\n",
    "For high performance widgets writing a Javascript view and a Python widget\n",
    "specific to the underlying javascript functionality\n",
    "may be the right way to go because it allows you to maintain\n",
    "complex state on the Javascript side and handle high performance callbacks and other operations\n",
    "without requiring communication between the Python side and the Javascript side (which may\n",
    "be very important especially if the two sides are running on different computers over a network\n",
    "connection).\n",
    "\n",
    "However for widgets where the performance considerations are not so critical the widget framework\n",
    "can be cumbersome.  \n",
    "\n",
    "By using `js_proxy` by contrast you can often simply load a Javascript module which has\n",
    "not been designed to work with Jupyter and then use the\n",
    "javascript functionality by writing Python code which closely mirrors\n",
    "the Javascript api for the module.  There is no need to write a Javascript view\n",
    "for the module or a specific Python widget implementation for the module.\n",
    "Even when performance considerations are important `js_proxy` may provide\n",
    "a quick-and-dirty way to try out functionality in Jupyter before designing a full\n",
    "blown widget implementation.\n",
    "\n",
    "For example if I want to have jQueryUI dialog pop up I need to execute something\n",
    "along the lines of the following javascript:\n",
    "\n",
    "`$(DomElement).html(\"Hello from jQueryUI\").dialog()`\n",
    "\n",
    "Using the `js_proxy` mechanism you can do something like this that looks similar:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "\n",
       "// This is the javascript side to match js_proxy.py.\n",
       "// See js_proxy.py for an explanation of the command transfer\n",
       "// protocol.\n",
       "\n",
       "require([\"widgets/js/widget\", \"widgets/js/manager\", \"underscore\", \"jquery\"\n",
       "], function(widget, manager, _, $) {\n",
       "    //debugger;\n",
       "\n",
       "    var JSProxyView = widget.DOMWidgetView.extend({\n",
       "\n",
       "        render: function() {\n",
       "            var that = this;\n",
       "            that.on(\"displayed\", function() {\n",
       "                that.update();\n",
       "            });\n",
       "            // \"new\" keyword emulation\n",
       "            // http://stackoverflow.com/questions/17342497/dynamically-control-arguments-while-creating-objects-in-javascript\n",
       "            that.$el.New = function(klass, args) {\n",
       "                var obj = Object.create(klass.prototype);\n",
       "                return klass.apply(obj, args) || obj;\n",
       "            }\n",
       "        },\n",
       "\n",
       "        update: function(options) {\n",
       "            var that = this;\n",
       "            var commands = that.model.get(\"commands\");\n",
       "            if (commands.length >= 2) {\n",
       "                var command_counter = commands[0];\n",
       "                var command_list = commands[1];\n",
       "                var level = commands[2];\n",
       "                level = that.check_level(level);\n",
       "                var results = [];\n",
       "                _.each(command_list, function(command,i) {\n",
       "                    var result = that.execute_command(command);\n",
       "                    results[i] = that.json_safe(result, level);\n",
       "                });\n",
       "                that.model.set(\"commands\", []);\n",
       "                that.model.set(\"results\", [command_counter, results])\n",
       "                that.touch();\n",
       "            }\n",
       "        },\n",
       "\n",
       "        execute_command: function(command) {\n",
       "            var that = this;\n",
       "            var result = command;\n",
       "            if ($.isArray(command)) {\n",
       "                var indicator = command[0];\n",
       "                var remainder = command.slice();\n",
       "                remainder.shift();\n",
       "                if (indicator == \"element\") {\n",
       "                    result = that.$el;\n",
       "                } else if (indicator == \"window\") {\n",
       "                    result = window;\n",
       "                } else if (indicator == \"method\") {\n",
       "                    var target_desc = remainder.shift();\n",
       "                    var target = that.execute_command(target_desc);\n",
       "                    var name = remainder.shift();\n",
       "                    var args = remainder.map(that.execute_command, that);\n",
       "                    var method = target[name];\n",
       "                    if (method) {\n",
       "                        result = method.apply(target, args);\n",
       "                    } else {\n",
       "                        result = \"In \" + target + \" no such method \" + name;\n",
       "                    }\n",
       "                } else if (indicator == \"function\") {\n",
       "                    var function_desc = remainder.shift();\n",
       "                    var function_value = that.execute_command(function_desc);\n",
       "                    var args = remainder.map(that.execute_command, that);\n",
       "                    // Use \"that\" as the \"this\" value for function values?\n",
       "                    result = function_value.apply(that, args);\n",
       "                } else if (indicator == \"id\") {\n",
       "                    result = remainder[0];\n",
       "                } else if (indicator == \"list\") {\n",
       "                    result = remainder.map(that.execute_command, that);\n",
       "                } else if (indicator == \"dict\") {\n",
       "                    result = {}\n",
       "                    var desc = remainder[0];\n",
       "                    for (var key in desc) {\n",
       "                        var key_desc = desc[key];\n",
       "                        var val = that.execute_command(key_desc);\n",
       "                        result[key] = val;\n",
       "                    }\n",
       "                } else if (indicator == \"callback\") {\n",
       "                    var identifier = remainder.shift();\n",
       "                    var data = remainder.shift();\n",
       "                    var level = remainder.shift();\n",
       "                    // sanity check\n",
       "                    level = that.check_level(level);\n",
       "                    result = that.callback_factory(identifier, data, level);\n",
       "                } else if (indicator == \"get\") {\n",
       "                    var target_desc = remainder.shift();\n",
       "                    var target = that.execute_command(target_desc);\n",
       "                    var name = remainder.shift();\n",
       "                    result = target[name];\n",
       "                } else if (indicator == \"set\") {\n",
       "                    var target_desc = remainder.shift();\n",
       "                    var target = that.execute_command(target_desc);\n",
       "                    var name = remainder.shift();\n",
       "                    var value_desc = remainder.shift()\n",
       "                    var value = that.execute_command(value_desc);\n",
       "                    target[name] = value;\n",
       "                    result = target;\n",
       "                } else if (indicator == \"null\") {\n",
       "                    target_desc = remainder.shift();\n",
       "                    that.execute_command(target_desc);\n",
       "                    result = null;\n",
       "                } else {\n",
       "                    result = \"Unknown indicator \" + indicator;\n",
       "                }\n",
       "            }\n",
       "            return result;\n",
       "        },\n",
       "\n",
       "        check_level: function(level) {\n",
       "            if ((typeof level) != \"number\" || (level < 0)) {\n",
       "                level = 0;\n",
       "            } else if (level > 5) {\n",
       "                level = 5;\n",
       "            }\n",
       "            return level;\n",
       "        },\n",
       "\n",
       "        callback_factory: function(identifier, data, level) {\n",
       "            var that = this;\n",
       "            var handler = function () {\n",
       "                var payload = that.json_safe([identifier, data, arguments], level + 1);\n",
       "                that.model.set(\"callback_results\", payload);\n",
       "                that.touch();\n",
       "            };\n",
       "            return handler;\n",
       "        },\n",
       "\n",
       "        json_safe: function(val, depth) {\n",
       "            // maybe expand later as need arises\n",
       "            var that = this;\n",
       "            var ty = (typeof val);\n",
       "            if ((ty == \"number\") || (ty == \"string\") || (ty == \"boolean\")) {\n",
       "                return val;\n",
       "            }\n",
       "            if (!val) {\n",
       "                // translate all other falsies to None\n",
       "                return null;\n",
       "            }\n",
       "            if (((typeof depth) == \"number\") && (depth > 0)) {\n",
       "                if ($.isArray(val)) {\n",
       "                    var result = [];\n",
       "                    _.each(val, function(elt, i) {\n",
       "                        var r = that.json_safe(elt, depth-1);\n",
       "                        if (r != null) {\n",
       "                            result[i] = r;\n",
       "                        }\n",
       "                    });\n",
       "                    return result;\n",
       "                } else {\n",
       "                    var result = {};\n",
       "                    for (var key in val) {\n",
       "                        var jv = that.json_safe(val[key], depth-1);\n",
       "                        if (jv != null) {\n",
       "                            result[key] = jv;\n",
       "                        }\n",
       "                    }\n",
       "                    return result;\n",
       "                }\n",
       "            }\n",
       "            return null;\n",
       "        }\n",
       "\n",
       "    });\n",
       "\n",
       "    manager.WidgetManager.register_widget_view('JSProxyView', JSProxyView);\n",
       "});\n"
      ],
      "text/plain": [
       "<IPython.core.display.Javascript object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# First import needed modules and javascript support\n",
    "# allow import without install\n",
    "import sys\n",
    "if \"..\" not in sys.path:\n",
    "    sys.path.append(\"..\")\n",
    "\n",
    "from jp_gene_viz import js_proxy\n",
    "# this loads the proxy widget javascript \"view\" implementation\n",
    "js_proxy.load_javascript_support()\n",
    "from IPython.display import display"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<b id=\"my_dialog\">Hello from jQueryUI</b>\n"
     ]
    }
   ],
   "source": [
    "# Then create a \"proxy widget\" for the jQueryUI dialog.\n",
    "d = js_proxy.ProxyWidget()\n",
    "\n",
    "# Construct a command to make the widget into a jQueryUI dialog.\n",
    "command = d.element().html('<b id=\"my_dialog\">Hello from jQueryUI</b>').dialog()\n",
    "\n",
    "# Send the command to the widget view (javascript side).\n",
    "d.send(command)\n",
    "\n",
    "# Display the widget, which causes the command to also execute.\n",
    "display(d)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you execute the previous cell you should see a jQueryUI dialog pop up.\n",
    "Click the close button to make the dialog invisible.\n",
    "\n",
    "The following cell should make it appear again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, [['method', ['element'], 'dialog']], 1]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "make_visible = d.element().dialog()\n",
    "d.send(make_visible)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "The above illustrates that commands can be sent to the widget after it has been displayed.\n",
    "\n",
    "[It is important to note that no commands are executed before a widget is displayed, so\n",
    "until the widget is displayed you should only call `send` or `send_commands` (which sends\n",
    "multiple commands in one go) once, because only the commands from the last call will get\n",
    "executed.  After the widget is displayed multiple calls are allowed.]\n",
    "\n",
    "The proxy mechanism works by capturing interactions on the Python side, encoding those\n",
    "interactions as a JSON object, transferring the JSON object to the Javascript side, and then\n",
    "interpreting the JSON object as a sequence of actions on the Javascript side.\n",
    "\n",
    "The return value from `d.send(...)` is the Python object sent as JSON to the\n",
    "Javascript proxy widget view.  At the top level it consists of a sequence number,\n",
    "a command sequence, and a recursion depth for the return result (as explained below).\n",
    "This return value can be useful for debugging.\n",
    "\n",
    "In this case we did not need to load any special libraries to use `jQueryUI` because the\n",
    "Jupyter notebook already uses `jQueryUI`.  For other libraries we might need to load the\n",
    "supporting javascript to the browser context using \n",
    "`IPython.display.display(IPython.display.Javascript(filepath)` or similar methods.\n",
    "\n",
    "Results from the Javascript actions are also passed back to the Python side in the `results` \n",
    "trait of the Python side widget object after the actions have been asynchronously evaluated:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, [{u'jquery': u'2.0.3', u'length': 1, u'selector': u''}]]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "d.results  # The results from the last command are not particularly meaningful."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting values from Javascript\n",
    "\n",
    "The communication between the Python widget object and the Javascript view is asynchronous.\n",
    "To do something with the results generated by a javascript interaction you may associate a\n",
    "callback to process the results when they arrive."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# We want to put the html from the widget in this list\n",
    "save_list = []\n",
    "\n",
    "def save_command_result(result):\n",
    "    \"this is the callback we want to execute when the results arrive\"\n",
    "    #print (result)\n",
    "    save_list.append(result)\n",
    "\n",
    "# This \"action\" gets the html content of the widget.\n",
    "get_html = d.element().html()\n",
    "\n",
    "# Send the action to the javascript side for async execution.\n",
    "d.send(get_html, results_callback=save_command_result)\n",
    "\n",
    "# If we look at save_list now, it will probably be empty because the\n",
    "# javascript side has probably not responded yet.\n",
    "save_list"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[[u'<b id=\"my_dialog\">Hello from jQueryUI</b>']]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# But later we should see the HTML saved in the list.\n",
    "save_list"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The result returned to the callback shown above \n",
    "is the HTML for the widget inside a list.\n",
    "The result is in a list because in general the callback mechanism\n",
    "permits results for command sequences in addition to results of \n",
    "individual commands.\n",
    "\n",
    "If you need synchronous execution, the `evaluate` and `evaluate_commands`\n",
    "methods provide command execution analogous to `send` and `send_commands`\n",
    "except that those methods wait for the result to arrive and return\n",
    "the result.  The `evaluate` method will return the result of the single\n",
    "command (not wrapped in a list) and the `evaluate_commands` will return the\n",
    "result of the commands in a list.\n",
    "\n",
    "Note the following anomaly (at this writing):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "result = d.evaluate(get_html)\n",
    "# NOTE: Nothing prints.  I don't know why.\n",
    "print result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "Unfortunately at this writing the syncronous methods cause the current cell to\n",
    "behave strangely -- in particular the final value and any printed values are not\n",
    "shown in the notebook for that cell but are shown in the cell where the widget was\n",
    "displayed.  I don't understand why this happens and I'm\n",
    "hoping to fix it some day.\n",
    "\n",
    "In the cell above the print statement\n",
    "did not print anything for that cell.  \n",
    "However the next cell will execute the print statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<b id=\"my_dialog\">Hello from jQueryUI</b>\n"
     ]
    }
   ],
   "source": [
    "print result"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the `evaluate` methods use a timeout mechanism to wait for\n",
    "the javascript results.  If the timeout expires `evaluate` will `raise`\n",
    "a Python `Exception`.  For this reason the `evaluate` methods should not\n",
    "be used with Javascript operations which are slow or that may block.\n",
    "\n",
    "# Command result translation depth level\n",
    "\n",
    "Results of commands are translated to JSON compatible values using recursive traversal\n",
    "of Javascript arrays and objects truncated to a depth which defaults to 1.  To traverse\n",
    "deeper into the structures you may provide a `level` parameter for \n",
    "`send`, `send_commands`, `evaluate`, or `evaluate_commands`\n",
    "which allows recursive depth up to 5.  To prevent recursion into complex values\n",
    "set the `level` to `0`.\n",
    "\n",
    "Below we get a fairly large data structure from the HTML Document Object Model (DOM) tree\n",
    "by traversing the DOM element for the widget to 2 levels deep."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# get the DOM element associated with the widget from inside the JQuery container.\n",
    "get_dom_element = d.element().get(0)\n",
    "dom_element_json = d.evaluate(get_dom_element, level=2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "got 130 attributes\n",
      "lookupPrefix\n",
      "contentEditable\n",
      "parentElement\n",
      "focus\n",
      "childElementCount\n",
      "DOCUMENT_TYPE_NODE\n",
      "insertAdjacentHTML\n",
      "children\n",
      "isEqualNode\n",
      "style\n",
      "webkitMatchesSelector\n",
      "spellcheck\n",
      "...\n"
     ]
    }
   ],
   "source": [
    "# Print some info about the JSON for the dom_element sent from Javascript.\n",
    "print(\"got \" + repr(len(dom_element_json)) + \" attributes\")\n",
    "for (i, item) in enumerate(dom_element_json.keys()):\n",
    "    print(item)\n",
    "    if i > 10: break\n",
    "print(\"...\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Events\n",
    "\n",
    "The proxy widget method \n",
    "\n",
    "`w.callback(self, callback_function, data, level=1)`\n",
    "\n",
    "Sets up the infrastructure for a javascript callback which can communicate\n",
    "a callback event notification from Javascript to the Python interpreter.\n",
    "\n",
    "For example the following code creates an input element with\n",
    "\"calendar datepicker\" jQueryUI functionality and also associates\n",
    "a callback to be called when the input value changes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(u'dp has changed', u'12/29/2015')\n"
     ]
    }
   ],
   "source": [
    "# Create the widget.\n",
    "dp = js_proxy.ProxyWidget()\n",
    "\n",
    "# Command to populate the widget with an input element with id dp000.\n",
    "make_input = dp.element().html('<input type=\"text\" id=\"dp000\"/>')._null()\n",
    "\n",
    "# Command to make the input element into a datepicker and\n",
    "# fix the style so the datepicker sits on top of the notebook page.\n",
    "fix_style = (\n",
    "    dp.window().\n",
    "    jQuery(\"#dp000\").  # get the jQuery input element by id == \"dp\".\n",
    "    datepicker().   # make it a jQuery UI datepicker.\n",
    "    css(\"position\", \"relative\").\n",
    "    css(\"z-index\", \"10000\").  # put it on top\n",
    "    attr(\"size\", 55).  # make it big.\n",
    "    _null()   # we don't care about the command result, discard it.\n",
    "    )\n",
    "\n",
    "# Define a python function and data structures to capture\n",
    "# values sent to the callback when the datepicker input value changes.\n",
    "identifiers_list = []\n",
    "arguments_list = []\n",
    "\n",
    "def dp_change_handler(identifier, arguments):\n",
    "    \"Print the results and also store them in lists.\"\n",
    "    print (identifier, arguments['0']['target']['value'])\n",
    "    identifiers_list.append(identifier)\n",
    "    arguments_list.append(arguments)\n",
    "    \n",
    "# Command to create a \"proxy callback\" for the change event.\n",
    "# The proxy will translate values to JSON up to 3 levels deep\n",
    "# and also send the identifier data \"dp has changed\" to the handler.\n",
    "proxy_callback = dp.callback(dp_change_handler, data=\"dp has changed\", level=3)\n",
    "\n",
    "# Command to associate the proxy callback with the datepicker change event\n",
    "# using the standard $(x).change(callback) jQuery method.\n",
    "on_change_command = dp.window().jQuery(\"#dp000\").change(proxy_callback)\n",
    "\n",
    "# Send the commands to the Javascript view.\n",
    "dp.send_commands([make_input, fix_style, on_change_command])\n",
    "\n",
    "# display the widget\n",
    "display(dp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you change the value in the datepicker input box\n",
    "you should see print statements appear from the `dp_change_handler` callback.\n",
    "\n",
    "# Other notes\n",
    "\n",
    "The cell that created the datepicker above deserves additional explanation.\n",
    "\n",
    "* `x._null()` at the end of a chain of proxy commands indicates that the result of the command should be discarded.\n",
    "The result for that command sent back to Python will be `None`.  This is useful to prevent communication of\n",
    "large datastructures that are not needed.\n",
    "\n",
    "* The `dp.window()` proxy command corresponds to the browser window namespace.\n",
    "This allows the proxy widget access to global names in the browser environment such\n",
    "as `dp.window().jQuery` which identifies the jQuery object.\n",
    "\n",
    "* The `data` given to the proxy callback may be used to for cross referencing events\n",
    "with other data structures (without having to define a new callback for every event).\n",
    "\n",
    "* The `proxy_callback` is set to translate JSON values 3 levels deep because the\n",
    "arguments sent to the callback from javascript holds the changed input value\n",
    "`arguments['0']['target']['value']`, which is 3 levels deep.\n",
    "\n",
    "* Callbacks functions registered using `w.callback(callback_function)` are stored\n",
    "forever in an internal data structure `w.identifier_to_callback` unless the\n",
    "the callback function is explicitly deleted with `w.forget_callback(callback_function)`.\n",
    "\n",
    "* In the code we use `dp.window().JQuery(\"#dp000\")` multiple times for simplicity.  It is also\n",
    "possible to use a variable `dp000 = dp.window().JQuery(\"#dp000\")` as a shorthand.\n",
    "\n",
    "# Storing javascript values in the \"element\"\n",
    "\n",
    "It is often important to store data structures created in Javascript for later\n",
    "use.  Any javascript value which can be identified or created by the proxy mechanism\n",
    "can be stored into the `element` object using the `_set` method.  For example the following interaction\n",
    "creates a new `input` element and stores it in the `element` object namespace."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "document = dp.window().document\n",
    "new_input = document.createElement(\"input\")\n",
    "save_input = dp.element()._set(\"saved_input\", new_input)\n",
    "json_sent = dp.send(save_input)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# what is the type of the new input element?\n",
    "element_type = dp.evaluate(dp.element().saved_input.type)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "u'text'"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# apparently the default type for an input element is \"text\"\n",
    "element_type"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Emulating the \"new\" keyword\n",
    "\n",
    "The `new` keyword may be emulated by translating `new klass(*arguments)` to\n",
    "`widget.element().New(klass, argument)` as in the following example the\n",
    "following defines a javascript function to add two numbers using `new Function(...)`, stores\n",
    "the function in the `element` namespace and then calls the function with arguments\n",
    "`34` and `6`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "new = dp.element().New\n",
    "klass = dp.window().Function\n",
    "# from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function\n",
    "# emulate \"new Function('a', 'b', 'return a + b')\"\n",
    "add_function = new(klass, [\"a\", \"b\", \"return a + b;\"])\n",
    "save_function = dp.element()._set(\"my_function\", add_function)\n",
    "json_sent = dp.send(save_function)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "function_evaluation = dp.evaluate(dp.element().my_function(34, 6))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "40"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "function_evaluation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "# Conveniences\n",
    "\n",
    "Each widget maintains a buffer of unexecuted commands.  To place a command on the buffer\n",
    "use the call notation `widget(command)`.  To send all the commands in the buffer and clear\n",
    "the buffer use `widget.flush()`.  The `widget(command)` returns the command argument for\n",
    "possible future use."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "window = dp.window()\n",
    "ih = dp(window.innerWidth)\n",
    "dp(window.innerHeight)\n",
    "dp(ih)\n",
    "json_sent = dp.flush()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[6, [1398, 1050, 1398]]"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dp.results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is also useful to create objects and store them into the `element` namespace in one step.\n",
    "The `widget.save(name, reference)` method buffers a command to save the reference using the name\n",
    "in the `element` namespace emulating `element.name = reference;`\n",
    "and returns a reference to the element by name (`element.name`).  Below we create another\n",
    "`input` element and store it using the name `another_element` and then use the reference to get\n",
    "the type of the element."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "new_element_reference = dp.save(\"another_element\", document.createElement(\"input\"))\n",
    "json_sent = dp.flush()\n",
    "other_element_type = dp.evaluate(new_element_reference.type)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "u'text'"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "other_element_type"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `widget.save_new(name, constructor, arguments)` emulates the Javascript\n",
    "`element.name = new constructor(*args);` operation and returns a reference to\n",
    "`element.name`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "function_reference = dp.save_new(\"another_function\", klass, [\"a\", \"b\", \"return a * b;\"])\n",
    "json_sent = dp.flush()\n",
    "product = dp.evaluate(function_reference(5, 2.2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "11"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "product"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### Function creation conveniences\n",
    "\n",
    "There are short hands for some of the examples shown above that create Javascript functions.\n",
    "\n",
    "To create an anonymous Javascript function use `widget.function(arguments, body_string)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "division = dp.function([\"a\", \"b\"], \"return a / b;\")\n",
    "tenth = dp.evaluate(division(1.0, 10.0))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.1"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tenth"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To create a Javascript function and store it \n",
    "in the `element` name space by name use `widget.save_function(name, arguments, body_string)`.\n",
    "The return value for `save_function` is a reference to the function by name."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "js_div_mod = dp.save_function(\"div_mod\", [\"a\", \"b\"], \"return {div: Math.trunc(a / b), mod: a % b};\")\n",
    "dp.flush()\n",
    "d_23_10 = dp.evaluate(js_div_mod(23, 10))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{u'div': 2, u'mod': 3}"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# call the function using the returned reference\n",
    "d_23_10"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "# call the function explicitly via the element namespace.\n",
    "d_467_45 = dp.evaluate(dp.element().div_mod(467, 45))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{u'div': 10, u'mod': 17}"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "d_467_45"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### A Debugging trick\n",
    "\n",
    "To break into the Javascript debugger in Chrome to examine the \n",
    "javascript environment open \"developer tools\"\n",
    "and try this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "json_sent = dp.send(dp.function([\"element\"], \"debugger;\")(dp.element()))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As a convenience this functionality is provided as `widget.js_debug()`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[16,\n",
       " [['function',\n",
       "   ['method',\n",
       "    ['element'],\n",
       "    'New',\n",
       "    ['get', ['window'], 'Function'],\n",
       "    ['list', 'element', 'debugger;']],\n",
       "   ['element']]],\n",
       " 1]"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "dp.js_debug()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also pass \"command\" arguments to js_debug to examine the javascript\n",
    "objects they map represent in the Chrome debugger.\n",
    "\n",
    "# Next steps\n",
    "\n",
    "Please see \n",
    "\n",
    "- The [three.js using jsproxy](three.js%20using%20js_proxy.ipynb) notebook or\n",
    "\n",
    "- The [Highcharts using jsproxy](HighCharts%20using%20js_proxy.ipynb) notebook\n",
    "\n",
    "for examples of more sophisticated uses for `jsproxy`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}