diff --git a/examples/Interactive Widgets/Custom Widget - Hello World.ipynb b/examples/Interactive Widgets/Custom Widget - Hello World.ipynb new file mode 100644 index 000000000..ea3dfdd49 --- /dev/null +++ b/examples/Interactive Widgets/Custom Widget - Hello World.ipynb @@ -0,0 +1,837 @@ +{ + "metadata": { + "name": "", + "signature": "sha256:1bcfb489c7d06f192acb47b6bbdecb16bb661cd695b6a2977221c17f521e81bb" + }, + "nbformat": 3, + "nbformat_minor": 0, + "worksheets": [ + { + "cells": [ + { + "cell_type": "code", + "collapsed": false, + "input": [ + "from __future__ import print_function # For py 2.7 compat" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 20 + }, + { + "cell_type": "heading", + "level": 1, + "metadata": {}, + "source": [ + "Building a Custom Widget" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The widget framework is built on top of the Comm framework (short for communication). The Comm framework is a framework that allows you send/recieve JSON messages to/from the front-end. To create a custom widget, you need to define the widget both in the back-end and in the front-end. " + ] + }, + { + "cell_type": "heading", + "level": 2, + "metadata": {}, + "source": [ + "Back-end (Python)" + ] + }, + { + "cell_type": "heading", + "level": 3, + "metadata": {}, + "source": [ + "DOMWidget and Widget" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To define a widget, you must inherit from the Widget or DOMWidget base class. If you intend for your widget to be displayed in the IPython notebook, you'll need to inherit from the DOMWidget. The DOMWidget class itself inherits from the Widget class. The Widget class is useful for cases in which the Widget isn't meant to be displayed directly in the notebook, but instead as a child of another rendering environment. For example, if you wanted to create a D3.js widget (a popular WebGL library), you would implement the rendering window as a DOMWidget and any 3D objects or lights meant to be rendered in that window as Widgets." + ] + }, + { + "cell_type": "heading", + "level": 3, + "metadata": {}, + "source": [ + "sync=True traitlets" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Inheriting from the DOMWidget doesn't tell the widget framework what front-end widget to associate with your back-end widget. Instead, you must tell it yourself by defining a specially named Traitlet, `_view_name` (as seen below)." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "from IPython.html import widgets\n", + "from IPython.utils.traitlets import Unicode\n", + "\n", + "class HelloWidget(widgets.DOMWidget):\n", + " _view_name = Unicode('HelloView', sync=True)" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 21 + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Traitlets is an IPython library for defining type-safe properties on configurable objects. For this tutorial you do not need to worry about the *configurable* piece of the traitlets machinery. The `sync=True` kwarg tells the widget framework to handle synchronizing that value to the front-end. Without `sync=True`, the front-end would have no knowlege of `_view_name`." + ] + }, + { + "cell_type": "heading", + "level": 3, + "metadata": {}, + "source": [ + "Other traitlet types" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Unicode is not the only Traitlet type, there are many more: \n", + "\n", + "- Any\n", + "- Bool\n", + "- Bytes\n", + "- CBool\n", + "- CBytes\n", + "- CComplex\n", + "- CFloat\n", + "- CInt\n", + "- CLong\n", + "- CRegExp\n", + "- CUnicode\n", + "- CaselessStrEnum\n", + "- Complex\n", + "- Dict\n", + "- DottedObjectName\n", + "- Enum\n", + "- Float\n", + "- FunctionType\n", + "- Instance\n", + "- InstanceType\n", + "- Int\n", + "- List\n", + "- Long\n", + "- Set\n", + "- TCPAddress\n", + "- Tuple\n", + "- Type\n", + "- Unicode\n", + "\n", + "Not all of these traitlets can be synchronized across the network, only the JSON-able traits and Widget instances will be synchronized." + ] + }, + { + "cell_type": "heading", + "level": 2, + "metadata": {}, + "source": [ + "Front-end (JavaScript)" + ] + }, + { + "cell_type": "heading", + "level": 3, + "metadata": {}, + "source": [ + "Models and views" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The IPython widget framework front-end relies heavily on [Backbone.js](http://backbonejs.org/). Backbone.js is an MVC (model view controller) framework. Widgets defined in the back-end are automatically synchronized with generic Backbone.js models in the front-end. The traitlets are added to the front-end instance automatically on first state push. The `_view_name` trait that you defined earlier is used by the widget framework to create the corresponding Backbone.js view and link that view to the generic model." + ] + }, + { + "cell_type": "heading", + "level": 3, + "metadata": {}, + "source": [ + "Defining a view" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You first need to import the WidgetManager. You will use it later to register your view by name (the same name you used in the backend). To import the widget manager, use the `require` method of [require.js](http://requirejs.org/) (as seen below)." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "%%javascript\n", + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){\n", + " \n", + "});" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "javascript": [ + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){\n", + " \n", + "});" + ], + "metadata": {}, + "output_type": "display_data", + "text": [ + "" + ] + } + ], + "prompt_number": 22 + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Next define your widget view class. Inherit from the `DOMWidgetView` by using the `.extend` method. Register the view class with the widget manager by calling `.register_widget_view`. The first parameter is the widget view name (`_view_name` that you defined earlier in Python) and the second is a handle to the class type." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "%%javascript\n", + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){\n", + " \n", + " // Define the HelloView\n", + " var HelloView = IPython.DOMWidgetView.extend({\n", + " \n", + " });\n", + " \n", + " // Register the HelloView with the widget manager.\n", + " WidgetManager.register_widget_view('HelloView', HelloView);\n", + "});" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "javascript": [ + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){\n", + " \n", + " // Define the HelloView\n", + " var HelloView = IPython.DOMWidgetView.extend({\n", + " \n", + " });\n", + " \n", + " // Register the HelloView with the widget manager.\n", + " WidgetManager.register_widget_view('HelloView', HelloView);\n", + "});" + ], + "metadata": {}, + "output_type": "display_data", + "text": [ + "" + ] + } + ], + "prompt_number": 23 + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Lastly, override the base `render` method of the view to define custom rendering logic. A handle to the widget's default div element can be aquired via `this.$el`. The `$el` property is a [jQuery](http://jquery.com/) object handle (which can be thought of as a supercharged version of the normal DOM element's handle)." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "%%javascript\n", + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){ \n", + " \n", + " var HelloView = IPython.DOMWidgetView.extend({\n", + " \n", + " // Render the view.\n", + " render: function(){ \n", + " this.$el.text('Hello World!'); \n", + " },\n", + " });\n", + " \n", + " WidgetManager.register_widget_view('HelloView', HelloView);\n", + "});" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "javascript": [ + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){ \n", + " \n", + " var HelloView = IPython.DOMWidgetView.extend({\n", + " \n", + " // Render the view.\n", + " render: function(){ \n", + " this.$el.text('Hello World!'); \n", + " },\n", + " });\n", + " \n", + " WidgetManager.register_widget_view('HelloView', HelloView);\n", + "});" + ], + "metadata": {}, + "output_type": "display_data", + "text": [ + "" + ] + } + ], + "prompt_number": 24 + }, + { + "cell_type": "heading", + "level": 2, + "metadata": {}, + "source": [ + "Test" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You should be able to display your widget just like any other widget now." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "HelloWidget()" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 25 + }, + { + "cell_type": "heading", + "level": 2, + "metadata": {}, + "source": [ + "Making the widget stateful" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "There isn't much that you can do with the above example that you can't do with the IPython display framework. To change this, you will make the widget stateful. Instead of displaying a static \"hello world\" message, it will display a string set by the backend. First you need to add the traitlet in the back-end. Use the name of `value` to stay consistent with the rest of the widget framework and to allow your widget to be used with interact." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "class HelloWidget(widgets.DOMWidget):\n", + " _view_name = Unicode('HelloView', sync=True)\n", + " value = Unicode('Hello World!', sync=True)" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 26 + }, + { + "cell_type": "heading", + "level": 3, + "metadata": {}, + "source": [ + "Backbone.js model" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To access the model associate with a view instance, use the `model` property of the view. `get` and `set` methods are used to interact with the Backbone model. `get` is trivial, however you have to be careful when using `set`. After calling the model `set` you need call the view's `touch` method. This associates the `set` operation with a particular view so output will be routed to the correct IPython cell. The model also has a `on` method which allows you to listen to events triggered by the model (like value changes)." + ] + }, + { + "cell_type": "heading", + "level": 3, + "metadata": {}, + "source": [ + "Rendering model contents" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "By replacing the string literal with a call to `model.get`, the view will now display the value of the back-end upon display. However, it will not update itself to a new value when the value changes." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "%%javascript\n", + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){ \n", + " \n", + " var HelloView = IPython.DOMWidgetView.extend({\n", + " \n", + " render: function(){ \n", + " this.$el.text(this.model.get('value')); \n", + " },\n", + " });\n", + " \n", + " WidgetManager.register_widget_view('HelloView', HelloView);\n", + "});" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "javascript": [ + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){ \n", + " \n", + " var HelloView = IPython.DOMWidgetView.extend({\n", + " \n", + " render: function(){ \n", + " this.$el.text(this.model.get('value')); \n", + " },\n", + " });\n", + " \n", + " WidgetManager.register_widget_view('HelloView', HelloView);\n", + "});" + ], + "metadata": {}, + "output_type": "display_data", + "text": [ + "" + ] + } + ], + "prompt_number": 27 + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To get the view to update itself dynamically, register a function to update the view's value when the model's `value` property changes. This can be done using the `model.on` method. The `on` method takes three parameters, an event name, callback handle, and callback context. The Backbone event named `change` will fire whenever the model changes. By appending `:value` to it, you tell Backbone to only listen to the change event of the `value` property (as seen below)." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "%%javascript\n", + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){ \n", + " \n", + " var HelloView = IPython.DOMWidgetView.extend({\n", + " \n", + " \n", + " render: function(){ \n", + " this.value_changed();\n", + " this.model.on('change:value', this.value_changed, this);\n", + " },\n", + " \n", + " value_changed: function() {\n", + " this.$el.text(this.model.get('value')); \n", + " },\n", + " });\n", + " \n", + " WidgetManager.register_widget_view('HelloView', HelloView);\n", + "});" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "javascript": [ + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){ \n", + " \n", + " var HelloView = IPython.DOMWidgetView.extend({\n", + " \n", + " \n", + " render: function(){ \n", + " this.value_changed();\n", + " this.model.on('change:value', this.value_changed, this);\n", + " },\n", + " \n", + " value_changed: function() {\n", + " this.$el.text(this.model.get('value')); \n", + " },\n", + " });\n", + " \n", + " WidgetManager.register_widget_view('HelloView', HelloView);\n", + "});" + ], + "metadata": {}, + "output_type": "display_data", + "text": [ + "" + ] + } + ], + "prompt_number": 38 + }, + { + "cell_type": "heading", + "level": 2, + "metadata": {}, + "source": [ + "Test" + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "w = HelloWidget()\n", + "w" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 39 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "w.value = 'test'" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 40 + }, + { + "cell_type": "heading", + "level": 2, + "metadata": {}, + "source": [ + "Bidirectional communication" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The examples above dump the value directly into the DOM. There is no way for you to interact with this dumped data in the front-end. To create an example that accepts input, you will have to do something more than blindly dumping the contents of value into the DOM. For this part of the tutorial, you will use a jQuery spinner to display and accept input in the front-end. IPython currently lacks a spinner implementation so this widget will be unique." + ] + }, + { + "cell_type": "heading", + "level": 3, + "metadata": {}, + "source": [ + "Update the Python code" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You will need to change the type of the value traitlet to `Int`. It also makes sense to change the name of the widget to something more appropriate, like `SpinnerWidget`." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "from IPython.utils.traitlets import CInt\n", + "class SpinnerWidget(widgets.DOMWidget):\n", + " _view_name = Unicode('SpinnerView', sync=True)\n", + " value = CInt(0, sync=True)" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 41 + }, + { + "cell_type": "heading", + "level": 3, + "metadata": {}, + "source": [ + "Updating the Javascript code" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The [jQuery docs for the spinner control](https://jqueryui.com/spinner/) say to use `.spinner` to create a spinner in an element. Calling `.spinner` on `$el` will create a spinner inside `$el`. Make sure to update the widget name here too so it's the same as `_view_name` in the back-end." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "%%javascript\n", + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){ \n", + " \n", + " var SpinnerView = IPython.DOMWidgetView.extend({\n", + " \n", + " render: function(){ \n", + " \n", + " // jQuery code to create a spinner and append it to $el\n", + " this.$input = $('');\n", + " this.$el.append(this.$input);\n", + " this.$spinner = this.$input.spinner({\n", + " change: function( event, ui ) {}\n", + " });\n", + " \n", + " this.value_changed();\n", + " this.model.on('change:value', this.value_changed, this);\n", + " },\n", + " \n", + " value_changed: function() {\n", + " \n", + " },\n", + " });\n", + " \n", + " WidgetManager.register_widget_view('SpinnerView', SpinnerView);\n", + "});" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "javascript": [ + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){ \n", + " \n", + " var SpinnerView = IPython.DOMWidgetView.extend({\n", + " \n", + " render: function(){ \n", + " this.$spinner = this.$el.spinner();\n", + " this.value_changed();\n", + " this.model.on('change:value', this.value_changed, this);\n", + " },\n", + " \n", + " value_changed: function() {\n", + " //this.$el.text(this.model.get('value')); \n", + " },\n", + " });\n", + " \n", + " WidgetManager.register_widget_view('SpinnerView', SpinnerView);\n", + "});" + ], + "metadata": {}, + "output_type": "display_data", + "text": [ + "" + ] + } + ], + "prompt_number": 44 + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To set the value of the spinner on update, you need to use jQuery's spinner API. `spinner.spinner('value', new)` will set the value of the spinner. Add that code to the `value_changed` method to make the spinner update with the value stored in the back-end. Using jQuery's spinner API, you can add a function to handle the spinner `change` event by passing it in when constructing the spinner. Inside the `change` event, call `model.set` to set the value and then `touch` to inform the framework that this view was the view that caused the change to the model. Note: The `var that = this;` is a JavaScript trick to pass the current context into closures." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "%%javascript\n", + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){ \n", + " \n", + " var SpinnerView = IPython.DOMWidgetView.extend({\n", + " \n", + " render: function(){ \n", + "\n", + " var that = this;\n", + " this.$input = $('');\n", + " this.$el.append(this.$input);\n", + " this.$spinner = this.$input.spinner({\n", + " change: function( event, ui ) {\n", + " that.handle_spin();\n", + " },\n", + " spin: function( event, ui ) {\n", + " that.handle_spin();\n", + " }\n", + " });\n", + " \n", + " this.value_changed();\n", + " this.model.on('change:value', this.value_changed, this);\n", + " },\n", + " \n", + " value_changed: function() {\n", + " this.$spinner.spinner('value', this.model.get('value'));\n", + " },\n", + " \n", + " handle_spin: function() {\n", + " this.model.set('value', this.$spinner.spinner('value'));\n", + " this.touch();\n", + " },\n", + " });\n", + " \n", + " WidgetManager.register_widget_view('SpinnerView', SpinnerView);\n", + "});" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "javascript": [ + "\n", + "require([\"widgets/js/widget\"], function(WidgetManager){ \n", + " \n", + " var SpinnerView = IPython.DOMWidgetView.extend({\n", + " \n", + " render: function(){ \n", + "\n", + " var that = this;\n", + " this.$input = $('');\n", + " this.$el.append(this.$input);\n", + " this.$spinner = this.$input.spinner({\n", + " change: function( event, ui ) {\n", + " that.handle_spin();\n", + " },\n", + " spin: function( event, ui ) {\n", + " that.handle_spin();\n", + " }\n", + " });\n", + " \n", + " this.value_changed();\n", + " this.model.on('change:value', this.value_changed, this);\n", + " },\n", + " \n", + " value_changed: function() {\n", + " this.$spinner.spinner('value', this.model.get('value'));\n", + " },\n", + " \n", + " handle_spin: function() {\n", + " this.model.set('value', this.$spinner.spinner('value'));\n", + " this.touch();\n", + " },\n", + " });\n", + " \n", + " WidgetManager.register_widget_view('SpinnerView', SpinnerView);\n", + "});" + ], + "metadata": {}, + "output_type": "display_data", + "text": [ + "" + ] + } + ], + "prompt_number": 74 + }, + { + "cell_type": "heading", + "level": 2, + "metadata": {}, + "source": [ + "Test" + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "w = SpinnerWidget(value=5)\n", + "w" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 75 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "w.value" + ], + "language": "python", + "metadata": {}, + "outputs": [ + { + "metadata": {}, + "output_type": "pyout", + "prompt_number": 76, + "text": [ + "5" + ] + } + ], + "prompt_number": 76 + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "w.value = 20" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 77 + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Trying to use the spinner with another widget." + ] + }, + { + "cell_type": "code", + "collapsed": false, + "input": [ + "w1 = SpinnerWidget(value=0)\n", + "w2 = widgets.IntSliderWidget()\n", + "display(w1,w2)\n", + "\n", + "from IPython.utils.traitlets import link\n", + "mylink = link((w1, 'value'), (w2, 'value'))" + ], + "language": "python", + "metadata": {}, + "outputs": [], + "prompt_number": 78 + } + ], + "metadata": {} + } + ] +} \ No newline at end of file