Merge pull request #3338 from agnat/docs_explain_resolveUrl

Documentation: Custom Widgets – Passing URLs

Author: jasongrout

docs/source/examples/Widget Custom.ipynb

@@ -768,6 +768,51 @@
     "![end-result](./images/custom-widget-result.png)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Passing URLs\n",
+    "\n",
+    "In the example above we have seen how to pass simple unicode strings to a HTML input element. However,\n",
+    "certain HTML elements, like e.g. `<img/>`, `<iframe/>` or `<script/>` require URLs as input. Consider\n",
+    "a widget embedding an `<iframe/>`. The widget has a `src` property that is connected to the `src`\n",
+    "attribute of the `<iframe/>`. It is the ipywidget version of the built-in `IPython.display.IFrame(...)`.\n",
+    "Like the built-in we'd like to support two forms:\n",
+    "\n",
+    "```python\n",
+    "from ipyiframe import IFrame\n",
+    "\n",
+    "remote_url = IFrame(src='https://jupyter.org') # full HTTP URL\n",
+    "local_file = IFrame(src='./local_file.html')   # local file\n",
+    "```\n",
+    "\n",
+    "Note, that the _second_ form is a path relative to the notebook file. Using this string as the `src`\n",
+    "attribute of the `<iframe/>` is not going to work, because the browser will interpret it as a relative\n",
+    "URL, relative to the browsers address bar. To transform the relative path into a valid file URL we use\n",
+    "the utility funtion `resolveUrl(...)` in our javascript view class:\n",
+    "\n",
+    "```js\n",
+    "export class IFrameView extends DOMWidgetView {\n",
+    "  render() {\n",
+    "    this.$iframe = document.createElement('iframe');\n",
+    "    this.el.appendChild(this.$iframe);\n",
+    "    this.src_changed();\n",
+    "    this.model.on('change:src', this.src_changed, this);\n",
+    "  }\n",
+    "\n",
+    "  src_changed() {\n",
+    "    const url = this.model.get('src'); \n",
+    "    this.model.widget_manager.resolveUrl(url).then(resolvedUrl => { \n",
+    "        this.$iframe.src = resolvedUrl;\n",
+    "    }); \n",
+    "  }\n",
+    "}\n",
+    "```\n",
+    "\n",
+    "Invoking `this.model.widget_manager.resolveUrl(...)` returns a promise that resolves to the correct URL."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -803,7 +848,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -817,7 +862,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.1"
+   "version": "3.9.9"
   }
  },
  "nbformat": 4,