Fixes #157 add per-client view parameters via HTML query

Along with these per-client view parameters we add a `multiview`
widget that allows many elements to be dynamically and imperatively
added to an already mounted view

Author: rmorshea

examples/example_utils.py

@@ -1,23 +1,12 @@
 import os
 from IPython import display
-from typing import Mapping, Any, Optional, Callable, Tuple, Type
+from typing import Mapping, Any, Optional
 
-from idom.server.base import AbstractRenderServer
-from idom.server import imperative_server_mount
 
-
-def setup_example_server(
-    server: Type[AbstractRenderServer], host: str, port: int, shared: bool = False,
-) -> Tuple[str, AbstractRenderServer, Callable[..., Any]]:
+def example_server_url(host: str, port: int) -> str:
     localhost_idom_path = f"http://{host}:{port}"
     jupyterhub_idom_path = path_to_jupyterhub_proxy(port)
-    path_to_idom = jupyterhub_idom_path or localhost_idom_path
-
-    server_instance, mount = imperative_server_mount(
-        server, host, port, shared, {"cors": True}, {"access_log": False}
-    )
-
-    return path_to_idom, server_instance, mount
+    return jupyterhub_idom_path or localhost_idom_path
 
 
 def path_to_jupyterhub_proxy(port: int) -> Optional[str]:

examples/introduction.ipynb

@@ -69,14 +69,18 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "from idom.server import multiview_server\n",
     "from idom.server.sanic import PerClientState\n",
-    "from example_utils import setup_example_server, display_href, pretty_dict_string\n",
+    "from example_utils import display_href, example_server_url, pretty_dict_string\n",
     "\n",
-    "server_url, server, mount = setup_example_server(PerClientState, \"127.0.0.1\", 8765)\n",
+    "mount, server = multiview_server(\n",
+    "    PerClientState, \"127.0.0.1\", 8765, {\"cors\": True}, {\"access_log\": False}\n",
+    ")\n",
+    "server_url = example_server_url(\"127.0.0.1\", 8765)\n",
     "\n",
     "def display(element, *args, **kwargs):\n",
-    "    mount(element, *args, **kwargs)\n",
-    "    return idom.display(\"jupyter\", server_url)"
+    "    view_id = mount(element, *args, **kwargs)\n",
+    "    return idom.display(\"jupyter\", server_url, {\"view_id\": view_id})"
    ]
   },
   {
@@ -121,7 +125,8 @@
    "source": [
     "print(\"Try clicking the image! 🖱️\")\n",
     "\n",
-    "display(Slideshow)"
+    "slideshow_view = display(Slideshow)\n",
+    "slideshow_view"
    ]
   },
   {
@@ -139,7 +144,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "display_href(server_url + \"/client/index.html\")"
+    "display_href(server_url + f\"/client/index.html?{slideshow_view.query}\")"
    ]
   },
   {
@@ -699,7 +704,7 @@
     "\n",
     "display(\n",
     "    chart.ClickableChart,\n",
-    "    {\"onClick\": handle_event, \"style\": {\"parent\": {\"width\": \"500px\"}}},\n",
+    "    {\"onClick\": handle_event, \"style\": {\"parent\": {\"width\": \"500px\"}}}\n",
     ")"
    ]
   },
@@ -757,11 +762,13 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "from idom.server import hotswap_server\n",
     "from idom.server.sanic import SharedClientState\n",
-    "from example_utils import setup_example_server, display_href, pretty_dict_string\n",
+    "from example_utils import display_href, example_server_url, pretty_dict_string\n",
     "\n",
-    "shared_server_url, shared_server, mount_shared = setup_example_server(\n",
-    "    SharedClientState, \"127.0.0.1\", 5678, shared=True\n",
+    "shared_server_url = example_server_url(\"127.0.0.1\", 5678)\n",
+    "mount_shared, shared_server  = hotswap_server(\n",
+    "    SharedClientState, \"127.0.0.1\", 5678, {\"cors\": True}, {\"access_log\": False}\n",
     ")\n",
     "\n",
     "def display_shared(element, *args, **kwargs):\n",
@@ -773,7 +780,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## We Can Just Reuse the <a href=\"#Drag-and-Drop---Complex-Interface-Features\">Drap and Drop Example</a>"
+    "## We Can Just Reuse the <a href=\"#Slideshows---Basic-Interactivity\">Slideshow Example</a>"
    ]
   },
   {
@@ -782,7 +789,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "view = display_shared(DragDropBoxes)"
+    "view = display_shared(Slideshow)"
    ]
   },
   {

idom/client/index.html

@@ -21,7 +21,8 @@
       } else {
         protocol = "ws:";
       }
-      let endpoint = protocol + "//" + url.join("/");
+
+      let endpoint = protocol + "//" + url.join("/") + window.location.search;
 
       renderLayout(document.getElementById("app"), endpoint);
     </script>

idom/server/__init__.py

@@ -2,7 +2,7 @@
 from typing import Any, Callable, Dict, Optional, Tuple, Type, TypeVar
 
 from idom.core.element import ElementConstructor
-from idom.widgets.common import hotswap
+from idom.widgets.common import multiview, hotswap
 
 from .base import AbstractRenderServer
 
@@ -23,34 +23,65 @@
 _S = TypeVar("_S", bound=AbstractRenderServer[Any, Any])
 
 
-def imperative_server_mount(
+def multiview_server(
     server: Type[_S],
     host: str,
     port: int,
-    shared: bool = False,
     server_options: Optional[Any] = None,
     run_options: Optional[Dict[str, Any]] = None,
-) -> Tuple[_S, Callable[[ElementConstructor], None]]:
-    """Set up a server whose view can be swapped out on the fly.
+) -> Tuple[Callable[[ElementConstructor], int], _S]:
+    """Set up a server where views can be dynamically added.
+
+    In other words this allows the user to work with IDOM in an imperative manner.
+    Under the hood this uses the :func:`idom.widgets.common.multiview` function to
+    add the views on the fly.
+
+    Parameters:
+        server: The server type to start up as a daemon
+        host: The server hostname
+        port: The server port number
+        server_options: Value passed to :meth:`AbstractRenderServer.configure`
+        run_options: Keyword args passed to :meth:`AbstractRenderServer.daemon`
+
+    Returns:
+        The server instance and a function for adding views.
+        See :func:`idom.widgets.common.multiview` for details.
+    """
+    mount, element = multiview()
+    server_instance = server(element)
+    if server_options:
+        server_instance.configure(server_options)
+    server_instance.daemon(host, port, **(run_options or {}))
+    return mount, server_instance
+
+
+def hotswap_server(
+    server: Type[_S],
+    host: str,
+    port: int,
+    server_options: Optional[Any] = None,
+    run_options: Optional[Dict[str, Any]] = None,
+) -> Tuple[Callable[[ElementConstructor], None], _S]:
+    """Set up a server where views can be dynamically swapped out.
 
     In other words this allows the user to work with IDOM in an imperative manner.
     Under the hood this uses the :func:`idom.widgets.common.hotswap` function to
-    switch out views on the fly.
+    swap the views on the fly.
 
     Parameters:
         server: The server type to start up as a daemon
         host: The server hostname
         port: The server port number
-        shared: Whether or not all views from the server should be updated when swapping
         server_options: Value passed to :meth:`AbstractRenderServer.configure`
         run_options: Keyword args passed to :meth:`AbstractRenderServer.daemon`
 
     Returns:
-        The server instance and a function for swapping out the view.
+        The server instance and a function for swapping views.
+        See :func:`idom.widgets.common.hotswap` for details.
     """
-    mount, element = hotswap(shared)
+    mount, element = hotswap(shared=True)
     server_instance = server(element)
     if server_options:
         server_instance.configure(server_options)
     server_instance.daemon(host, port, **(run_options or {}))
-    return server_instance, mount
+    return mount, server_instance

idom/server/base.py

@@ -5,7 +5,11 @@
 
 from idom.core.element import ElementConstructor, AbstractElement
 from idom.core.layout import AbstractLayout, Layout
-from idom.core.render import AbstractRenderer
+from idom.core.render import (
+    AbstractRenderer,
+    SendCoroutine,
+    RecvCoroutine,
+)
 
 
 _App = TypeVar("_App", bound=Any)
@@ -89,7 +93,17 @@ def _setup_application(self, app: _App, config: _Config) -> None:
     def _run_application(
         self, app: _App, config: _Config, args: Tuple[Any, ...], kwargs: Dict[str, Any]
     ) -> Any:
-        ...
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    async def _run_renderer(
+        self,
+        send: SendCoroutine,
+        recv: RecvCoroutine,
+        parameters: Dict[str, Any],
+        loop: Optional[AbstractEventLoop] = None,
+    ) -> None:
+        raise NotImplementedError()
 
     def _update_config(self, old: _Config, new: _Config) -> _Config:
         """Return the new configuration options
@@ -101,14 +115,16 @@ def _update_config(self, old: _Config, new: _Config) -> _Config:
         return new
 
     def _make_renderer(
-        self, loop: Optional[AbstractEventLoop] = None
+        self, parameters: Dict[str, Any], loop: Optional[AbstractEventLoop] = None,
     ) -> AbstractRenderer:
-        return self._renderer_type(self._make_layout(loop))
+        return self._renderer_type(self._make_layout(parameters, loop))
 
-    def _make_layout(self, loop: Optional[AbstractEventLoop] = None) -> AbstractLayout:
-        return self._layout_type(self._make_root_element(), loop)
+    def _make_layout(
+        self, parameters: Dict[str, Any], loop: Optional[AbstractEventLoop] = None,
+    ) -> AbstractLayout:
+        return self._layout_type(self._make_root_element(parameters), loop)
 
-    def _make_root_element(self) -> AbstractElement:
+    def _make_root_element(self, parameters: Dict[str, Any]) -> AbstractElement:
         return self._root_element_constructor(
-            *self._root_element_args, **self._root_element_kwargs
+            *self._root_element_args, **{**self._root_element_kwargs, **parameters}
         )

idom/server/sanic.py

@@ -2,7 +2,7 @@
 import json
 import uuid
 
-from typing import Tuple, Any, Dict, Union
+from typing import Tuple, Any, Dict, Union, Optional
 
 from sanic import Sanic, request, response
 from sanic_cors import CORS
@@ -30,9 +30,6 @@ class Config(TypedDict, total=False):
 class SanicRenderServer(AbstractRenderServer[Sanic, Config]):
     """Base ``sanic`` extension."""
 
-    async def _run_renderer(self, send: SendCoroutine, recv: RecvCoroutine) -> None:
-        raise NotImplementedError()
-
     def _init_config(self) -> Config:
         return Config(cors=False, url_prefix="", webpage_route=True)
 
@@ -105,7 +102,8 @@ async def sock_send(data: Dict[str, Any]) -> None:
             message = {"header": {}, "body": {"render": data}}
             await socket.send(json.dumps(message, separators=(",", ":")))
 
-        await self._run_renderer(sock_send, sock_recv)
+        param_dict = {k: request.args.get(k) for k in request.args}
+        await self._run_renderer(sock_send, sock_recv, param_dict)
 
     async def _client_route(
         self, request: request.Request, path: str
@@ -121,8 +119,14 @@ class PerClientState(SanicRenderServer):
 
     _renderer_type = SingleStateRenderer
 
-    async def _run_renderer(self, send: SendCoroutine, recv: RecvCoroutine) -> None:
-        await self._make_renderer().run(send, recv, None)
+    async def _run_renderer(
+        self,
+        send: SendCoroutine,
+        recv: RecvCoroutine,
+        parameters: Dict[str, Any],
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+    ) -> None:
+        await self._make_renderer(parameters, loop).run(send, recv, None)
 
 
 class SharedClientState(SanicRenderServer):
@@ -137,7 +141,16 @@ def _setup_application(self, app: Sanic, config: Config) -> None:
     async def _setup_renderer(
         self, app: Sanic, loop: asyncio.AbstractEventLoop
     ) -> None:
-        self._renderer = self._make_renderer(loop)
-
-    async def _run_renderer(self, send: SendCoroutine, recv: RecvCoroutine) -> None:
+        self._renderer = self._make_renderer({}, loop)
+
+    async def _run_renderer(
+        self,
+        send: SendCoroutine,
+        recv: RecvCoroutine,
+        parameters: Dict[str, Any],
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+    ) -> None:
+        if parameters:
+            msg = f"SharedClientState server does not support per-client view parameters {parameters}"
+            raise ValueError(msg)
         await self._renderer.run(send, recv, uuid.uuid4().hex)

idom/widgets/__init__.py

@@ -1,4 +1,4 @@
-from .common import Import, define_module, hotswap
+from .common import Import, define_module, hotswap, multiview
 from .display import display
 from .inputs import Input
 from .images import Image
@@ -10,6 +10,7 @@
     "Image",
     "define_module",
     "hotswap",
+    "multiview",
     "html",
     "Input",
     "Import",