clientside callback interface

CHANGELOG.md

@@ -1,10 +1,8 @@
 ## Unreleased
-
 ### Added
-
-- add `dev_tools_ui` in `<script id="_dash-config" type="application/json">`,
-  so renderer can know if it should enable the UI. [#676](https://github.com/plotly/dash/pull/676)
-
+- Support for "Clientside Callbacks" - an escape hatch to execute your callbacks in JavaScript instead of Python [#672](https://github.com/plotly/dash/pull/672)
+- Added `dev_tools_ui` config flag in `app.run_server` (serialized in `<script id="_dash-config" type="application/json">`)
+  to display or hide the forthcoming Dev Tools UI in Dash's front-end (dash-renderer). [#676](https://github.com/plotly/dash/pull/676)
 
 ## [0.40.0] - 2019-03-25
 ### Changed

dash/dash.py

@@ -633,6 +633,7 @@ def dependencies(self):
                 'output': k,
                 'inputs': v['inputs'],
                 'state': v['state'],
+                'clientside_function': v.get('clientside_function', None)
             } for k, v in self.callback_map.items()
         ])
 
@@ -936,6 +937,68 @@ def _validate_value(val, index=None):
         else:
             _validate_value(output_value)
 
+    # pylint: disable=dangerous-default-value
+    def clientside_callback(
+            self, clientside_function, output, inputs=[], state=[]):
+        """
+        Create a callback that updates the output by calling a clientside
+        (JavaScript) function instead of a Python function.
+
+        Unlike `@app.calllback`, `clientside_callback` is not a decorator:
+        it takes a
+        `dash.dependencies.ClientsideFunction(namespace, function_name)`
+        argument that describes which JavaScript function to call
+        (Dash will look for the JavaScript function at
+        `window[namespace][function_name]`).
+
+        For example:
+        ```
+        app.clientside_callback(
+            ClientsideFunction('my_clientside_library', 'my_function'),
+            Output('my-div' 'children'),
+            [Input('my-input', 'value'),
+             Input('another-input', 'value')]
+        )
+        ```
+
+        With this signature, Dash's front-end will call
+        `window.my_clientside_library.my_function` with the current
+        values of the `value` properties of the components
+        `my-input` and `another-input` whenever those values change.
+
+        Include a JavaScript file by including it your `assets/` folder.
+        The file can be named anything but you'll need to assign the
+        function's namespace to the `window`. For example, this file might
+        look like:
+        ```
+        window.my_clientside_library = {
+            my_function: function(input_value_1, input_value_2) {
+                return (
+                    parseFloat(input_value_1, 10) +
+                    parseFloat(input_value_2, 10)
+                );
+            }
+        }
+        ```
+        """
+        self._validate_callback(output, inputs, state)
+        callback_id = _create_callback_id(output)
+
+        self.callback_map[callback_id] = {
+            'inputs': [
+                {'id': c.component_id, 'property': c.component_property}
+                for c in inputs
+            ],
+            'state': [
+                {'id': c.component_id, 'property': c.component_property}
+                for c in state
+            ],
+            'clientside_function': {
+                'namespace': clientside_function.namespace,
+                'function_name': clientside_function.function_name
+            }
+        }
+
     # TODO - Update nomenclature.
     # "Parents" and "Children" should refer to the DOM tree
     # and not the dependency tree.
@@ -962,7 +1025,7 @@ def callback(self, output, inputs=[], state=[]):
             'state': [
                 {'id': c.component_id, 'property': c.component_property}
                 for c in state
-            ]
+            ],
         }
 
         def wrap_func(func):

dash/dependencies.py

@@ -1,4 +1,5 @@
 class DashDependency:
+    # pylint: disable=too-few-public-methods
     def __init__(self, component_id, component_property):
         self.component_id = component_id
         self.component_property = component_property
@@ -19,16 +20,26 @@ def __hash__(self):
         return hash(str(self))
 
 
-# pylint: disable=too-few-public-methods
-class Output(DashDependency):
+class Output(DashDependency):  # pylint: disable=too-few-public-methods
     """Output of a callback."""
 
 
-# pylint: disable=too-few-public-methods
-class Input(DashDependency):
+class Input(DashDependency):  # pylint: disable=too-few-public-methods
     """Input of callback trigger an update when it is updated."""
 
 
-# pylint: disable=too-few-public-methods
-class State(DashDependency):
+class State(DashDependency):  # pylint: disable=too-few-public-methods
     """Use the value of a state in a callback but don't trigger updates."""
+
+
+class ClientsideFunction:
+    # pylint: disable=too-few-public-methods
+    def __init__(self, namespace=None, function_name=None):
+        self.namespace = namespace
+        self.function_name = function_name
+
+    def __repr__(self):
+        return 'ClientsideFunction({}, {})'.format(
+            self.namespace,
+            self.function_name
+        )