fix(widgets): Add Simput.register_layout() (#15)

* fix(widgets): Add Simput.register_layout()
* docs(widgets): Add basic documentation for Simput widgets

Author: willdunklin

docs/api.md

@@ -12,7 +12,7 @@ widget or get your hand on its **proxymanager** to manage its proxies.
 
 ## Simput manager
 
-The simput manager instance let you do the following:
+The simput manager instance lets you do the following:
 - Access its linked **proxymanager**
 - Reset cached UI layout elements by calling **clear_ui()**
 - Load definitions, language and UI by calling one of the following methods
@@ -298,6 +298,72 @@ def hints(self):
     """Return a set of (level, message) when running the validation for the info level"""
 ```
 
+## UI Widgets
+
+### Simput Widget
+
+The `Simput` widget is a trame component that is used as the UI data management provider.
+This component must be registered as the root of the layout with the `register_layout(layout)` method (preferred method) or by setting `layout.root = simput_widget`.
+
+```python
+@property
+def helper(self):
+    """Simput helper object"""
+
+def apply(self, **kwargs):
+    """Flush modified properties so they can be pushed to their concrete objects"""
+
+def reset(self, **kwargs):
+    """Unapply properties"""
+
+def push(self, id=None, type=None, domains=None, proxy=None, **kwargs):
+    """Ask server to push data, ui, or constraints"""
+
+def update(self, change_set, **kwargs):
+    """
+    List of properties and value to update
+
+    >>> change_set = [
+    ... {"id":"12", "name":"Radius", "value": 0.75},
+    ... {"id": "12", "name":"Resolution", "value": 24}
+    ... ]
+    """
+
+def register_layout(self, layout):
+    """
+    Register self to the root of the layout and
+    clear any previously registered elements (to support hot reloading)
+    """
+
+def refresh(self, id=0, property="", **kwargs):
+    """Refresh the given id's property"""
+
+def reload(self, name):
+    """Reload the given name (data, ui, domain)"""
+
+@property
+def changeset(self):
+    """All unapplied changesets"""
+
+@property
+def has_changes(self):
+    """Does the changeset have content?"""
+
+@property
+def auto_update(self):
+    """Whether to automatically apply changes"""
+```
+
+### SimputItem Widget
+
+`SimputItem` is a trame component that is used to display a Simput item. This must be child of a Simput component to have access to Simput data.
+
+```python
+item_proxy = pxm.create("Item")
+# Create a SimputItem widget to display the item
+simput.SimputItem(item_id=f"{item_proxy.id}")
+```
+
 ## Domains
 
 ### Range

examples/00_AddressBook/app.py

@@ -100,7 +100,7 @@ def entry_ids(self):
 
 with SinglePageWithDrawerLayout(server) as layout:
     layout.title.set_text("SimPut Address Book")
-    layout.root = simput_widget
+    simput_widget.register_layout(layout)
 
     with layout.toolbar:
         vuetify.VSpacer()

examples/01_Widgets/app.py

@@ -58,7 +58,7 @@ def update_ui(use_xml_ui, **kwargs):
 # -----------------------------------------------------------------------------
 
 with SinglePageLayout(server) as layout:
-    layout.root = simput_widget
+    simput_widget.register_layout(layout)
 
     with layout.toolbar as toolbar:
         layout.title.set_text("SimPut Widgets")

examples/02_Hints/app.py

@@ -45,7 +45,7 @@
 # -----------------------------------------------------------------------------
 
 with SinglePageLayout(server) as layout:
-    layout.root = simput_widget
+    simput_widget.register_layout(layout)
 
     with layout.toolbar as toolbar:
         layout.title.set_text("SimPut Widgets")

examples/03_VTK/app.py

@@ -120,7 +120,7 @@ def import_file(import_file, **kwargs):
 ]
 
 with SinglePageWithDrawerLayout(server) as layout:
-    layout.root = simput_widget
+    simput_widget.register_layout(layout)
 
     with layout.drawer as drawer:
         with vuetify.VTabs(

examples/04_DynaDomain/app.py

@@ -72,7 +72,7 @@ def update_advanced(ui_advanced, **kwargs):
         ctrl.simput_apply = simput_widget.apply
         ctrl.simput_reset = simput_widget.reset
         ctrl.simput_reload_domain = simput_widget.reload_domain
-        layout.root = simput_widget
+        simput_widget.register_layout(layout)
 
     with layout.toolbar as toolbar:
         layout.title.set_text("SimPut Advanced view")

examples/05_ReadonlyDisabled/app.py

@@ -23,7 +23,7 @@
 # -----------------------------------------------------------------------------
 
 with SinglePageLayout(server) as layout:
-    layout.root = simput_widget
+    simput_widget.register_layout(layout)
 
     with layout.toolbar as toolbar:
         layout.title.set_text("Simput readonly and disabled example")

trame_simput/widgets/simput.py

@@ -12,7 +12,7 @@ def __init__(self, _elem_name, children=None, **kwargs):
 
 class Simput(HtmlElement):
     """
-    Simput data management component. This must be set as the root of a layout to provide children with Simput data.
+    Simput data management component. This must be registered as the root of a layout to provide children with Simput data.
 
     :param ui_manager: See simput docs |simput_link| for more info
     :param domains_manager: See simput docs |simput_link| for more info
@@ -23,7 +23,8 @@ class Simput(HtmlElement):
     :param children: The children nested within this element
     :type children:  str | list[trame.html.*] | trame.html.* | None
 
-    >>> layout.root = simput.Simput(ui_manager, prefix="myForm")
+    >>> simput_widget = simput.Simput(ui_manager, prefix="myForm")
+    >>> simput_widget.register_layout(layout)
     """
 
     def __init__(self, ui_manager, prefix=None, children=None, **kwargs):
@@ -77,6 +78,14 @@ def update(self, change_set, **kwargs):
         """
         self._helper.update(change_set)
 
+    def register_layout(self, layout):
+        """
+        Register self to the root of the layout and
+        clear any previously registered elements (to support hot reloading)
+        """
+        self.clear()
+        layout.root = self
+
     def refresh(self, id=0, property="", **kwargs):
         self._helper.refresh(id, property)