created own sub doc page for generic events

with new demo of listening to custom events from js

main.py

@@ -336,8 +336,8 @@ def documentation_page() -> None:
 
 @ui.page('/documentation/{name}')
 async def documentation_page_more(name: str, client: Client) -> None:
-    if not hasattr(ui, name):
-        name = name.replace('_', '')  # NOTE: "AG Grid" leads to anchor name "ag_grid", but class is `ui.aggrid`
+    if name == 'ag_grid':
+        name = 'aggrid'  # NOTE: "AG Grid" leads to anchor name "ag_grid", but class is `ui.aggrid`
     module = importlib.import_module(f'website.more_documentation.{name}_documentation')
     more = getattr(module, 'more', None)
     if hasattr(ui, name):
@@ -352,7 +352,7 @@ async def documentation_page_more(name: str, client: Client) -> None:
     with side_menu() as menu:
         ui.markdown(f'[← back](/documentation#{create_anchor_name(back_link_target)})').classes('bold-links')
     with ui.column().classes('w-full p-8 lg:p-16 max-w-[1250px] mx-auto'):
-        section_heading('Documentation', f'ui.*{name}*' if hasattr(ui, name) else f'*{name.title()}*')
+        section_heading('Documentation', f'ui.*{name}*' if hasattr(ui, name) else f'*{name.replace("_", " ").title()}*')
         with menu:
             ui.markdown('**Demos**' if more else '**Demo**').classes('mt-4')
         element_demo(api)(getattr(module, 'main_demo'))

website/documentation.py

@@ -532,38 +532,7 @@ def create_full() -> None:
             ui.button('Add label', on_click=lambda: ui.label('Click!'))
             ui.timer(1.0, lambda: ui.label('Tick!'), once=True)
 
-    @text_demo('Generic Events', '''
-        Most UI elements come with predefined events.
-        For example, a `ui.button` like "A" in the demo has an `on_click` parameter that expects a coroutine or function.
-        But you can also use the `on` method to register a generic event handler like for "B".
-        This allows you to register handlers for any event that is supported by JavaScript and Quasar.
-
-        For example, you can register a handler for the `mousemove` event like for "C", even though there is no `on_mousemove` parameter for `ui.button`.
-        Some events, like `mousemove`, are fired very often.
-        To avoid performance issues, you can use the `throttle` parameter to only call the handler every `throttle` seconds ("D").
-
-        The generic event handler can be synchronous or asynchronous and optionally takes an event dictionary as argument ("E").
-        You can also specify which attributes of the JavaScript or Quasar event should be passed to the handler ("F").
-        This can reduce the amount of data that needs to be transferred between the server and the client.
-
-        You can also include [key modifiers](https://vuejs.org/guide/essentials/event-handling.html#key-modifiers) ("G"),
-        modifier combinations ("H"),
-        and [event modifiers](https://vuejs.org/guide/essentials/event-handling.html#mouse-button-modifiers) ("I").
-    ''')
-    def generic_events_demo():
-        with ui.row():
-            ui.button('A', on_click=lambda: ui.notify('You clicked the button A.'))
-            ui.button('B').on('click', lambda: ui.notify('You clicked the button B.'))
-        with ui.row():
-            ui.button('C').on('mousemove', lambda: ui.notify('You moved on button C.'))
-            ui.button('D').on('mousemove', lambda: ui.notify('You moved on button D.'), throttle=0.5)
-        with ui.row():
-            ui.button('E').on('mousedown', lambda e: ui.notify(str(e)))
-            ui.button('F').on('mousedown', lambda e: ui.notify(str(e)), ['ctrlKey', 'shiftKey'])
-        with ui.row():
-            ui.input('G').classes('w-12').on('keydown.space', lambda: ui.notify('You pressed space.'))
-            ui.input('H').classes('w-12').on('keydown.y.shift', lambda: ui.notify('You pressed Shift+Y'))
-            ui.input('I').classes('w-12').on('keydown.once', lambda: ui.notify('You started typing.'))
+    load_demo('generic_events')
 
     heading('Configuration')
 

website/documentation_tools.py

@@ -106,7 +106,7 @@ class element_demo:
 
 
 def load_demo(api: Union[type, Callable, str]) -> None:
-    name = pascal_to_snake(api if isinstance(api, str) else api.__name__)
+    name = api if isinstance(api, str) else pascal_to_snake(api.__name__)
     try:
         module = importlib.import_module(f'website.more_documentation.{name}_documentation')
     except ModuleNotFoundError:

website/more_documentation/generic_events_documentation.py

@@ -0,0 +1,64 @@
+from nicegui import globals, ui
+
+from ..documentation_tools import text_demo
+
+
+def main_demo() -> None:
+    """Generic Events
+
+    Most UI elements come with predefined events.
+    For example, a `ui.button` like "A" in the demo has an `on_click` parameter that expects a coroutine or function.
+    But you can also use the `on` method to register a generic event handler like for "B".
+    This allows you to register handlers for any event that is supported by JavaScript and Quasar.
+
+    For example, you can register a handler for the `mousemove` event like for "C", even though there is no `on_mousemove` parameter for `ui.button`.
+    Some events, like `mousemove`, are fired very often.
+    To avoid performance issues, you can use the `throttle` parameter to only call the handler every `throttle` seconds ("D").
+
+    The generic event handler can be synchronous or asynchronous and optionally takes an event dictionary as argument ("E").
+    You can also specify which attributes of the JavaScript or Quasar event should be passed to the handler ("F").
+    This can reduce the amount of data that needs to be transferred between the server and the client.
+
+    You can also include `key modifiers <https://vuejs.org/guide/essentials/event-handling.html#key-modifiers>`_ (shown in input "G"),
+    modifier combinations (shown in input "H"),
+    and `event modifiers <https://vuejs.org/guide/essentials/event-handling.html#mouse-button-modifiers>`_ (shown in input "I").
+"""
+    with ui.row():
+        ui.button('A', on_click=lambda: ui.notify('You clicked the button A.'))
+        ui.button('B').on('click', lambda: ui.notify('You clicked the button B.'))
+    with ui.row():
+        ui.button('C').on('mousemove', lambda: ui.notify('You moved on button C.'))
+        ui.button('D').on('mousemove', lambda: ui.notify('You moved on button D.'), throttle=0.5)
+    with ui.row():
+        ui.button('E').on('mousedown', lambda e: ui.notify(str(e)))
+        ui.button('F').on('mousedown', lambda e: ui.notify(str(e)), ['ctrlKey', 'shiftKey'])
+    with ui.row():
+        ui.input('G').classes('w-12').on('keydown.space', lambda: ui.notify('You pressed space.'))
+        ui.input('H').classes('w-12').on('keydown.y.shift', lambda: ui.notify('You pressed Shift+Y'))
+        ui.input('I').classes('w-12').on('keydown.once', lambda: ui.notify('You started typing.'))
+
+
+def more() -> None:
+
+    @text_demo('Custom events', '''
+        It's fairly easy to emit custom events from javascript which can be listened to with `element.on(...)`.
+        This can be useful if you want to call Python code when something happens in javascript.
+        Like in this example where we are listening to the `visibilitychange` event of the browser tab.
+    ''')
+    async def custom_events() -> None:
+        tabwatch = ui.checkbox('Watch browser tab re-entering') \
+            .on('tabvisible', lambda: ui.notify('welcome back') if tabwatch.value else None)
+        ui.add_head_html(f'''<script>
+        document.addEventListener('visibilitychange', function() {{
+            if (document.visibilityState === 'visible')
+                document.getElementById({tabwatch.id}).dispatchEvent(new CustomEvent('tabvisible'))
+        }});
+        </script>''')
+        # END OF DEMO
+        await globals.get_client().connected()
+        await ui.run_javascript(f'''
+            document.addEventListener('visibilitychange', function() {{
+                if (document.visibilityState === 'visible')
+                    document.getElementById({tabwatch.id}).dispatchEvent(new CustomEvent('tabvisible'))
+            }});
+        ''', respond=False)