Iterate on the custom widget tutorial

Author: jtpio

docs/source/examples/Widget Custom.ipynb

@@ -141,7 +141,27 @@
     "jupyter nbextension enable --sys-prefix --py ipyemail\n",
     "```\n",
     "\n",
-    "You are now ready to implement the core functionality of the widget!"
+    "### Testing the installation\n",
+    "\n",
+    "At this point, you should be able to open a notebook and create a new `ExampleWidget`.\n",
+    "\n",
+    "To test it, execute the following in a terminal:\n",
+    "\n",
+    "```bash\n",
+    "# if you are using the classic notebook\n",
+    "jupyter notebook\n",
+    "\n",
+    "# if you are using JupyterLab\n",
+    "jupyter lab\n",
+    "```\n",
+    "\n",
+    "And open `examples/introduction.ipynb`.\n",
+    "\n",
+    "By default, the widget displays the string `Hello World` with a colored background:\n",
+    "\n",
+    "![hello-world](./images/custom-widget-hello.png)\n",
+    "\n",
+    "The next step will walk you through how to modify the existing code to transform the widget into an email widget."
    ]
   },
   {
@@ -152,7 +172,7 @@
     }
    },
    "source": [
-    "## Building a Custom Widget"
+    "## Implementing the widget"
    ]
   },
   {
@@ -203,24 +223,45 @@
    "source": [
     "Inheriting from the DOMWidget does not tell the widget framework what front end widget to associate with your back end widget.\n",
     "\n",
-    "Instead, you must tell it yourself by defining specially named trait attributes, `_view_name`, `_view_module`, and `_view_module_version` (as seen below) and optionally `_model_name` and `_model_module`."
+    "Instead, you must tell it yourself by defining specially named trait attributes, `_view_name`, `_view_module`, and `_view_module_version` (as seen below) and optionally `_model_name` and `_model_module`.\n",
+    "\n",
+    "\n",
+    "In `ipyemail/example.py`, replace the example code with the following:\n",
+    "\n",
+    "```python\n",
+    "from ipywidgets import DOMWidget, ValueWidget, register\n",
+    "from traitlets import Unicode, Bool, validate, TraitError\n",
+    "\n",
+    "from ._frontend import module_name, module_version\n",
+    "\n",
+    "\n",
+    "@register\n",
+    "class EmailWidget(DOMWidget, ValueWidget):\n",
+    "    _model_name = Unicode('EmailModel').tag(sync=True)\n",
+    "    _model_module = Unicode(module_name).tag(sync=True)\n",
+    "    _model_module_version = Unicode(module_version).tag(sync=True)\n",
+    "\n",
+    "    _view_name = Unicode('EmailView').tag(sync=True)\n",
+    "    _view_module = Unicode(module_name).tag(sync=True)\n",
+    "    _view_module_version = Unicode(module_version).tag(sync=True)\n",
+    "```"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "from traitlets import Unicode, Bool, validate, TraitError\n",
-    "from ipywidgets import DOMWidget, ValueWidget, register\n",
+    "In `ipyemail/__init__.py`, change the import from:\n",
     "\n",
+    "```python\n",
+    "from .example import ExampleWidget\n",
+    "```\n",
     "\n",
-    "@register\n",
-    "class Email(DOMWidget, ValueWidget):\n",
-    "    _view_name = Unicode('EmailView').tag(sync=True)\n",
-    "    _view_module = Unicode('email_widget').tag(sync=True)\n",
-    "    _view_module_version = Unicode('0.1.0').tag(sync=True)"
+    "To:\n",
+    "\n",
+    "```python\n",
+    "from .example import EmailWidget\n",
+    "```"
    ]
   },
   {
@@ -300,7 +341,7 @@
     }
    },
    "source": [
-    "## Front end (JavaScript)"
+    "## Front end (TypeScript)"
    ]
   },
   {
@@ -325,66 +366,52 @@
     }
    },
    "source": [
-    "### Import @jupyter-widgets/base"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "You first need to import the `@jupyter-widgets/base` module. To import modules, use the `define` method of [require.js](http://requirejs.org/) (as seen below)."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%%javascript\n",
-    "define('email_widget', [\"@jupyter-widgets/base\"], function(widgets) {\n",
-    "    \n",
-    "});"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {
-    "slideshow": {
-     "slide_type": "slide"
-    }
-   },
-   "source": [
-    "### Define the view"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Next, define your widget view class.  Inherit from the `DOMWidgetView` by using the `.extend` method."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%%javascript\n",
-    "require.undef('email_widget');\n",
-    "\n",
-    "define('email_widget', [\"@jupyter-widgets/base\"], function(widgets) {\n",
-    "    \n",
-    "    // Define the EmailView\n",
-    "    var EmailView = widgets.DOMWidgetView.extend({\n",
-    "        \n",
-    "    });\n",
+    "The TypeScript cookiecutter generates a file `src/widget.ts`. Open the file and rename `ExampleModel` to `EmailModel` and `ExampleView` to `EmailView`:\n",
+    "\n",
+    "```typescript\n",
+    "export\n",
+    "class EmailModel extends DOMWidgetModel {\n",
+    "  defaults() {\n",
+    "    return {...super.defaults(),\n",
+    "      _model_name: EmailModel.model_name,\n",
+    "      _model_module: EmailModel.model_module,\n",
+    "      _model_module_version: EmailModel.model_module_version,\n",
+    "      _view_name: EmailModel.view_name,\n",
+    "      _view_module: EmailModel.view_module,\n",
+    "      _view_module_version: EmailModel.view_module_version,\n",
+    "      value : 'Hello World'\n",
+    "    };\n",
+    "  }\n",
     "\n",
-    "    return {\n",
-    "        EmailView: EmailView\n",
+    "  static serializers: ISerializers = {\n",
+    "      ...DOMWidgetModel.serializers,\n",
+    "      // Add any extra serializers here\n",
     "    }\n",
-    "});"
+    "\n",
+    "  static model_name = 'EmailModel';\n",
+    "  static model_module = MODULE_NAME;\n",
+    "  static model_module_version = MODULE_VERSION;\n",
+    "  static view_name = 'EmailView';   // Set to null if no view\n",
+    "  static view_module = MODULE_NAME;   // Set to null if no view\n",
+    "  static view_module_version = MODULE_VERSION;\n",
+    "}\n",
+    "\n",
+    "\n",
+    "export\n",
+    "class EmailView extends DOMWidgetView {\n",
+    "  render() {\n",
+    "    this.el.classList.add('custom-widget');\n",
+    "\n",
+    "    this.value_changed();\n",
+    "    this.model.on('change:value', this.value_changed, this);\n",
+    "  }\n",
+    "\n",
+    "  value_changed() {\n",
+    "    this.el.textContent = this.model.get('value');\n",
+    "  }\n",
+    "}\n",
+    "\n",
+    "```"
    ]
   },
   {
@@ -402,37 +429,29 @@
    "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 DOM element can be acquired via `this.el`.  The `el` property is the DOM element associated with the view."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%%javascript\n",
-    "require.undef('email_widget');\n",
+    "Now, override the base `render` method of the view to define custom rendering logic.\n",
     "\n",
-    "define('email_widget', [\"@jupyter-widgets/base\"], function(widgets) {\n",
+    "A handle to the widget's default DOM element can be acquired via `this.el`.  The `el` property is the DOM element associated with the view.\n",
     "\n",
-    "    var EmailView = widgets.DOMWidgetView.extend({\n",
+    "In `src/widget.ts`, define the `email_input` attribute:\n",
     "\n",
-    "        // Render the view.\n",
-    "        render: function() { \n",
-    "            this.email_input = document.createElement('input');\n",
-    "            this.email_input.type = 'email';\n",
-    "            this.email_input.value = '[email protected]';\n",
-    "            this.email_input.disabled = true;\n",
+    "```typescript\n",
+    "export class EmailView extends DOMWidgetView {\n",
+    "  private _emailInput: HTMLInputElement;\n",
+    "}\n",
+    "```\n",
     "\n",
-    "            this.el.appendChild(this.email_input); \n",
-    "        },\n",
-    "    });\n",
+    "Then, add the following logic for the `render`:\n",
     "\n",
-    "    return {\n",
-    "        EmailView: EmailView\n",
-    "    };\n",
-    "});"
+    "```typescript\n",
+    "render: function() { \n",
+    "    this._emailInput = document.createElement('input');\n",
+    "    this._emailInput.type = 'email';\n",
+    "    this._emailInput.value = '[email protected]';\n",
+    "    this._emailInput.disabled = true;\n",
+    "    this.el.appendChild(this._emailInput);\n",
+    "},\n",
+    "```"
    ]
   },
   {
@@ -450,16 +469,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You should be able to display your widget just like any other widget now."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "Email()"
+    "You should be able to display your widget just like any other widget now:\n",
+    "\n",
+    "```python\n",
+    "from ipyemail import EmailWidget\n",
+    "\n",
+    "EmailWidget()\n",
+    "```"
    ]
   },
   {

docs/source/examples/Widget Styling.ipynb

@@ -1413,7 +1413,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.8"
+   "version": "3.8.1"
   }
  },
  "nbformat": 4,