docs(website): Add more basic examples

docs/vitepress/.vitepress/config.mjs

@@ -92,6 +92,26 @@ export default defineConfig({
         },
       ],
       '/examples/':[
+        {
+          text: 'Core functionalities',
+          items: [
+            { text: 'Basics', link: '/examples/core/basics' },
+            { text: 'File management', link: '/examples/core/files' },
+            { text: 'Jupyter', link: '/examples/core/jupyter' },
+
+            // { text: 'CLI', link: 'https://github.com/Kitware/trame/blob/master/examples/00_howdoi/cli.py' },
+            // { text: 'File Upload', link: 'https://github.com/Kitware/trame/blob/master/examples/00_howdoi/upload.py' },
+            // { text: 'Router', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/10_router.py' },
+            // { text: 'Favicon', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/12_reserved_state.py' },
+            // { text: 'MouseTrap', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/16_mousetrap.py'},
+            // { text: 'Download text', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/22_download_server_content.py' },
+            // { text: 'Download binary', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/24_vtk_download_image.py' },
+            // { text: 'CSS', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/28_css.py' },
+            // { text: 'Class decorator', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/decorators/default_class_decorator.py' },
+            // { text: 'Panel comparison', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/panel' },
+            // { text: 'Docker', link: 'https://github.com/Kitware/trame/blob/master/examples/deploy/docker/SingleFile' },
+          ]
+        },
         {
           text: 'Applications',
           items: [
@@ -128,22 +148,6 @@ export default defineConfig({
             { text: 'State loader', link: '/examples/paraview/state' },
           ]
         },
-        {
-          text: 'Core functionalities',
-          items: [
-            { text: 'CLI', link: 'https://github.com/Kitware/trame/blob/master/examples/00_howdoi/cli.py' },
-            { text: 'File Upload', link: 'https://github.com/Kitware/trame/blob/master/examples/00_howdoi/upload.py' },
-            { text: 'Router', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/10_router.py' },
-            { text: 'Favicon', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/12_reserved_state.py' },
-            { text: 'MouseTrap', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/16_mousetrap.py'},
-            { text: 'Download text', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/22_download_server_content.py' },
-            { text: 'Download binary', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/24_vtk_download_image.py' },
-            { text: 'CSS', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/core/28_css.py' },
-            { text: 'Class decorator', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/decorators/default_class_decorator.py' },
-            { text: 'Panel comparison', link: 'https://github.com/Kitware/trame/blob/master/examples/validation/panel' },
-            { text: 'Docker', link: 'https://github.com/Kitware/trame/blob/master/examples/deploy/docker/SingleFile' },
-          ]
-        },
       ],
     },
 

docs/vitepress/examples/core/basics.md

@@ -0,0 +1,29 @@
+# Introduction
+
+The examples presented below are meant to be executed and explored so you can understand the basic mechanic of trame.
+
+## State management
+
+::: code-group
+
+<<< @/../../examples/core_features/state.py
+<<< @/../../examples/core_features/reserved_state.py
+
+:::
+
+## Events management
+
+<<< @/../../examples/core_features/events.py
+
+## User Interface
+
+::: code-group
+
+<<< @/../../examples/core_features/dynamic_layout.py
+<<< @/../../examples/core_features/multi_layout.py
+
+:::
+
+## Life Cycle 
+
+<<< @/../../examples/core_features/life_cycle.py

docs/vitepress/examples/core/files.md

@@ -0,0 +1,9 @@
+## Download
+
+
+## Upload
+
+
+## Browse
+
+<<< @/../../examples/core_features/sys_filebrowser.py

docs/vitepress/examples/core/jupyter.md

@@ -0,0 +1,3 @@
+## Exposing a trame application into Jupyter
+
+<<< @/../../examples/core_features/jupyter.py

examples/core_features/dynamic_layout.py

@@ -0,0 +1,44 @@
+from trame.app import get_server
+from trame.widgets import html
+from trame.ui.html import DivLayout
+
+# -----------------------------------------------------------------------------
+# Trame app
+# -----------------------------------------------------------------------------
+
+server = get_server()
+
+# -----------------------------------------------------------------------------
+# UI setup
+# -----------------------------------------------------------------------------
+
+line_count = 1
+
+
+def update_first_line():
+    global line_count
+    with server.ui.first_line:
+        server.ui.first_line.clear()
+        html.Div(f"First line: { line_count }")
+    line_count += 1
+
+
+# Start with some UI to control a
+with DivLayout(server) as layout:
+    server.ui.first_line(layout)  # Insert place holder
+
+    def add_line():
+        global line_count
+        with layout:
+            html.Div(f"Line: { line_count }")
+        line_count += 1
+
+    html.Button(f"Add line", click=add_line)
+    html.Button(f"Update first line", click=update_first_line)
+
+# -----------------------------------------------------------------------------
+# start server
+# -----------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    server.start()

examples/core_features/events.py

@@ -0,0 +1,71 @@
+from trame.app import get_server
+from trame.widgets import html
+from trame.ui.html import DivLayout
+
+# -----------------------------------------------------------------------------
+# Trame app
+# -----------------------------------------------------------------------------
+
+server = get_server()
+state, ctrl = server.state, server.controller
+
+# -----------------------------------------------------------------------------
+# State setup
+# -----------------------------------------------------------------------------
+
+state.a = 1
+
+# -----------------------------------------------------------------------------
+# Methods call
+# -----------------------------------------------------------------------------
+
+
+@ctrl.set("alias_1")
+def method_1(*args, **kwargs):
+    print(f"Server: method_1 {args=} {kwargs=}")
+    state.a += 1
+
+
+@ctrl.add("alias_2")
+def method_2(*args, **kwargs):
+    print(f"Server: method_2 {args=} {kwargs=}")
+    state.a += 2
+
+
+@ctrl.add("alias_2")
+def method_3(*args, **kwargs):
+    print(f"Server: method_3 {args=} {kwargs=}")
+    state.a += 3
+
+
+def method_4(*args, **kwargs):
+    print(f"Server: method_4 {args=} {kwargs=}")
+    state.a += 10
+
+
+ctrl.alias_3 = method_4
+
+# -----------------------------------------------------------------------------
+# UI setup
+# -----------------------------------------------------------------------------
+
+layout = DivLayout(server)
+
+with DivLayout(server):
+    html.Div(
+        "State a={{ a }}", style="padding: 20px; margin: 20px; border: solid 1px #333;"
+    )
+    html.Button(f"Method 1", click=method_1)
+    html.Button(f"Method 2", click=(method_2, "['hello', 'world']"))
+    html.Button(f"Method 3", click=(method_3, "[1, 2]", "{ x: 3, y: 4 }"))
+    html.Button(f"alias_1", click=(ctrl.alias_1, "[2]", "{ z: 4 }"))
+    html.Button(f"alias_2", click=(ctrl.alias_2, "[3]", "{ z: 5 }"))
+    html.Button(f"a+", click="a+=1")
+
+
+# -----------------------------------------------------------------------------
+# start server
+# -----------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    server.start()

examples/core_features/jupyter.py

@@ -0,0 +1,85 @@
+r"""
+Within Jupyter
+
+```
+import os
+os.environ["TRAME_DISABLE_V3_WARNING"] = "1"
+
+cone = Cone()
+await cone.ui.ready
+cone.ui
+```
+
+Another cell
+
+```
+cone.resolution = 4
+```
+
+"""
+
+
+from trame.app import get_server
+from trame.ui.vuetify import SinglePageLayout
+from trame.widgets import html, vuetify, vtk
+from trame.decorators import TrameApp, change
+
+
+@TrameApp()
+class Cone:
+    def __init__(self, name=None):
+        self.server = get_server(name)
+        self.server.client_type = "vue2"
+        self._ui = None
+
+        self.state.a = 0
+
+        # Build UI
+        self.ui
+
+    @property
+    def state(self):
+        return self.server.state
+
+    @property
+    def ctrl(self):
+        return self.server.controller
+
+    @property
+    def resolution(self):
+        return self.state.resolution
+
+    @resolution.setter
+    def resolution(self, v):
+        with self.state:
+            self.state.resolution = v
+
+    def reset_resolution(self):
+        self.resolution = 6
+
+    @change("resolution")
+    def _resolution_change(self, resolution, **kwargs):
+        self.state.a = resolution
+
+    @property
+    def ui(self):
+        if self._ui is None:
+            with SinglePageLayout(self.server) as layout:
+                self._ui = layout
+                with layout.toolbar:
+                    html.Div("a: {{ a }}")
+                    vuetify.VSpacer()
+                    vuetify.VSlider(
+                        v_model=("resolution", 6), min=3, max=60, hide_details=True
+                    )
+                    vuetify.VBtn("Reset", click=self.reset_resolution)
+                with layout.content:
+                    with vuetify.VContainer(fluid=True, classes="pa-0 fill-height"):
+                        with vtk.VtkView() as vtk_view:
+                            self.ctrl.reset_camera = vtk_view.reset_camera
+                            with vtk.VtkGeometryRepresentation():
+                                vtk.VtkAlgorithm(
+                                    vtkClass="vtkConeSource", state=("{ resolution }",)
+                                )
+
+        return self._ui

examples/core_features/life_cycle.py

@@ -0,0 +1,50 @@
+from trame.app import get_server
+from trame.ui.html import DivLayout
+
+# -----------------------------------------------------------------------------
+# Trame setup
+# -----------------------------------------------------------------------------
+
+server = get_server()
+ctrl = server.controller
+
+# Need a UI
+with DivLayout(server):
+    pass
+
+# -----------------------------------------------------------------------------
+# Life Cycle events
+# -----------------------------------------------------------------------------
+
+
+@ctrl.add("on_server_ready")
+def server_ready(**state):
+    print("on_server_ready")
+
+
+@ctrl.add("on_client_connected")
+def client_connected():
+    print("on_client_connected")
+
+
+@ctrl.add("on_client_unmounted")
+def client_unmounted():
+    print("on_client_unmounted")
+
+
+@ctrl.add("on_client_exited")
+def client_exited():
+    print("on_client_exited")
+
+
+@ctrl.add("on_server_exited")
+def server_exited(**state):
+    print("on_server_exited")
+
+
+# -----------------------------------------------------------------------------
+# start server
+# -----------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    server.start(timeout=1)

examples/core_features/multi_layout.py

@@ -0,0 +1,31 @@
+from trame.app import get_server
+from trame.widgets import html
+from trame.ui.html import DivLayout
+
+# -----------------------------------------------------------------------------
+# Trame app
+# -----------------------------------------------------------------------------
+
+server = get_server()
+
+# -----------------------------------------------------------------------------
+# UI setup
+# -----------------------------------------------------------------------------
+
+with DivLayout(server):
+    html.A("Open UI(a)", href="/?ui=a", target="_blank")
+    html.Br()
+    html.A("Open UI(b)", href="/?ui=b", target="_blank")
+
+with DivLayout(server, "a"):
+    html.Div("UI for A")
+
+with DivLayout(server, "b"):
+    html.Div("UI for B")
+
+# -----------------------------------------------------------------------------
+# start server
+# -----------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    server.start()