Introduce API to build Single Page Applications (SPAs)

examples/authentication_spa/main.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+import html
+import uuid
+from typing import Optional, Union
+
+from nicegui import app, ui
+from nicegui.single_page_target import SinglePageTarget
+
+INDEX_URL = '/'
+SECRET_AREA_URL = '/secret_area'
+
+DUMMY_LOGINS = {"admin": "NicePass"}
+
+
+def portal_rerouting(url) -> str:
+    # automatically redirect to the secret area if the user is already logged in
+    if 'login_token' in app.storage.user:
+        return SECRET_AREA_URL
+    return url
+
+
+@ui.outlet('/', on_navigate=portal_rerouting)
+def main_layout():
+    with ui.header():
+        ui.link('SPA Login Example', '/').style('text-decoration: none; color: inherit;').classes('text-h3')
+    ui.query('.nicegui-content').classes('flex-center')
+    with ui.column().classes('m-12'):
+        yield
+
+
+@main_layout.view('/', title='Login Page')
+def main_app_index():
+    def handle_login():
+        username = username_input.value
+        password = password_input.value
+        if username in DUMMY_LOGINS and DUMMY_LOGINS[username] == password:
+            # NOTE you can also use app.storage.tab to ensure the login is only valid for the current tab
+            app.storage.user['login_token'] = uuid.uuid4().hex
+            app.storage.user['username'] = username
+            ui.navigate.to(SECRET_AREA_URL)
+        else:
+            password_input.props('error')
+
+    with ui.column().classes('w-96 mt-[40%] items-center'):
+        username_input = ui.input('Username').classes('w-full')\
+            .on('keydown.enter', lambda: password_input.run_method('focus'))
+        password_input = ui.input('Password', password=True, password_toggle_button=True) \
+            .classes('w-full').props('error-message="Invalid password!"') \
+            .on('keydown.enter', handle_login)
+        ui.button('Login').classes('w-48').on_click(handle_login)
+        ui.label(f'Hint: {DUMMY_LOGINS}').classes('text-grey mt-12')
+        ui.link('Try to access secret area without login', SECRET_AREA_URL).classes('text-grey mt-12')
+
+
+def logout():  # logs the user out and redirects to the login page
+    app.storage.user.clear()
+    ui.navigate.to(INDEX_URL)
+
+
+def check_login(url) -> Optional[Union[str, SinglePageTarget]]:
+    def error_page():
+        with ui.column().classes('w-96 mt-[40%] items-center'):
+            ui.label('⚠️').classes('text-6xl')
+            ui.label('You are not logged in!').classes('text-3xl')
+            ui.button('Go to login page').on_click(lambda: ui.navigate.to(INDEX_URL)).classes('w-48 mt-12')
+
+    if 'login_token' not in app.storage.user:  # check if the user is not logged in
+        return SinglePageTarget(url, builder=error_page, title='Not logged in')
+    return url  # default behavior
+
+
+@main_layout.outlet(SECRET_AREA_URL, on_navigate=check_login)
+def secret_area_layout():
+    yield
+
+
+@secret_area_layout.view('/', title='🔒 Secret Area')
+def secret_area_index():
+    username = app.storage.user['username']
+    ui.label(f'Hello {html.escape(username)}. Welcome to the secret area!').classes('text-3xl')
+    ui.button('Logout').on_click(logout).classes('w-48 mt-12')
+
+
+ui.run(storage_secret='secret', title='SPA Login')

examples/single_page_app_complex/cms_config.py

@@ -0,0 +1,28 @@
+import os
+from typing import Dict
+
+from pydantic import BaseModel, Field
+
+
+class SubServiceDefinition(BaseModel):
+    title: str = Field(..., description='The title of the sub-service', examples=['Digital Twin'])
+    emoji: str = Field(..., description='An emoji representing the sub-service', examples=['🤖'])
+    description: str = Field(..., description='A short description of the sub-service',
+                             examples=['Manage your digital twin'])
+
+
+class ServiceDefinition(BaseModel):
+    title: str = Field(..., description='The title of the cloud service', examples=['Virtual Machines'])
+    emoji: str = Field(..., description='An emoji representing the cloud service', examples=['💻'])
+    description: str = Field(..., description='A short description of the cloud service',
+                             examples=['Create and manage virtual machines'])
+    sub_services: Dict[str, SubServiceDefinition] = Field(...,
+                                                          description='The sub-services of the cloud service')
+
+
+class ServiceDefinitions(BaseModel):
+    services: Dict[str, ServiceDefinition] = Field(...,
+                                                   description='The cloud services provided by the cloud provider')
+
+
+services = ServiceDefinitions.parse_file(os.path.join(os.path.dirname(__file__), 'services.json')).services

examples/single_page_app_complex/main.py

@@ -0,0 +1,136 @@
+# Advanced demo showing how to use the ui.outlet and outlet.view decorators to create a nested multi-page app with a
+# static header, footer and menu which is shared across all pages and hidden when the user navigates to the root page.
+
+from nicegui import ui
+from nicegui.page_layout import LeftDrawer
+from nicegui.single_page_router import SinglePageRouter
+from nicegui.single_page_target import SinglePageTarget
+
+from examples.single_page_app_complex.cms_config import SubServiceDefinition, ServiceDefinition, services
+
+
+# --- Other app ---
+
+@ui.outlet('/other_app')  # Needs to be defined before the main outlet / to avoid conflicts
+def other_app_router():
+    ui.label('Other app header').classes('text-h2')
+    ui.html('<hr>')
+    yield
+    ui.html('<hr>')
+    ui.label('Other app footer')
+
+
+@other_app_router.view('/')
+def other_app_index():
+    ui.label('Welcome to the index page of the other application')
+
+
+# --- Main app ---
+
+@ui.outlet('/')  # main app outlet
+def main_router(url_path: str):
+    with ui.header():
+        with ui.link('', '/').style('text-decoration: none; color: inherit;') as lnk:
+            ui.html('<span style="color:white">Nice</span>'
+                    '<span style="color:black">CLOUD</span>').classes('text-h3')
+    menu_visible = '/services/' in url_path  # make instantly visible if the initial path is a service
+    menu_drawer = ui.left_drawer(bordered=True, value=menu_visible, fixed=True).classes('bg-primary')
+    with ui.footer():
+        with ui.element('a').props('href="/about"'):
+            ui.label('Copyright 2024 by NiceCLOUD Inc.').classes('text-h7')
+    with ui.element().classes('p-8'):
+        yield {'menu_drawer': menu_drawer}  # pass menu drawer to all sub elements (views and outlets)
+
+
+@main_router.view('/')
+def main_index(menu_drawer: LeftDrawer):  # main app index page
+    menu_drawer.clear()  # clear drawer
+    menu_drawer.hide()  # hide drawer
+    ui.label('Welcome to NiceCLOUD!').classes('text-3xl')
+    ui.html('<br>')
+    with ui.grid(columns=3) as grid:
+        grid.classes('gap-16')
+        for key, info in services.items():
+            link = f'/services/{key}'
+            with ui.element():
+                with ui.link(target=link) as lnk:
+                    with ui.row().classes('text-2xl'):
+                        ui.label(info.emoji)
+                        ui.label(info.title)
+                    lnk.style('text-decoration: none; color: inherit;')
+                ui.label(info.description)
+    ui.html('<br><br>')
+    # add a link to the other app
+    ui.markdown('Click [here](/other_app) to visit the other app.')
+
+
+@main_router.view('/about')
+def about_page(menu_drawer: LeftDrawer):
+    menu_drawer.clear()
+    menu_drawer.hide()
+    ui.label('About NiceCLOUD').classes('text-3xl')
+    ui.html('<br>')
+    ui.label('NiceCLOUD Inc.')
+    ui.label('1234 Nice Street')
+    ui.label('Nice City')
+    ui.label('Nice Country')
+
+
+@main_router.outlet('/services/{service_name}')  # service outlet
+def services_router(service_name: str, menu_drawer: LeftDrawer):
+    service: ServiceDefinition = services[service_name]
+    menu_drawer.clear()
+    with menu_drawer:
+        menu_drawer.show()
+        with ui.row() as row:
+            ui.label(service.emoji)
+            ui.label(service.title)
+            row.classes('text-h5 text-white').style('text-shadow: 2px 2px #00000070;')
+        ui.html('<br>')
+        menu_items = service.sub_services
+        for key, info in menu_items.items():
+            with ui.row() as service_element:
+                ui.label(info.emoji)
+                ui.label(info.title)
+                service_element.classes('text-white text-h6 bg-gray cursor-pointer')
+                service_element.style('text-shadow: 2px 2px #00000070;')
+                service_element.on('click', lambda url=f'/services/{service_name}/{key}': ui.navigate.to(url))
+    yield {'service': service}  # pass service object to all sub elements (views and outlets)
+
+
+def update_title(service: ServiceDefinition = None,
+                 sub_service: SubServiceDefinition = None):
+    # Is called for every page within the service_router and sub_service_router via the on_load callback
+    # and updates the title of each page
+    SinglePageRouter.current_router().target.title = \
+            'NiceCLOUD - ' + (f'{sub_service.title}' if sub_service else f'{service.title}')
+
+
+@services_router.view('/')  # service index page
+def show_index(service: ServiceDefinition):
+    update_title(service, None)
+    with ui.row() as row:
+        ui.label(service.emoji).classes('text-h4 vertical-middle')
+        with ui.column():
+            ui.label(service.title).classes('text-h2')
+            ui.label(service.description)
+    ui.html('<br>')
+
+
+@services_router.outlet('/{sub_service_name}')  # sub service outlet
+def sub_service_router(service: ServiceDefinition, sub_service_name: str):
+    sub_service: SubServiceDefinition = service.sub_services[sub_service_name]
+    ui.label(f'{service.title} > {sub_service.title}').classes('text-h4')
+    ui.html('<br>')
+    yield {'sub_service': sub_service}  # pass sub_service object to all sub elements (views and outlets)
+
+
+@sub_service_router.view('/')  # sub service index page
+def sub_service_index(service: ServiceDefinition, sub_service: SubServiceDefinition):
+    update_title(service, sub_service)
+    ui.label(sub_service.emoji).classes('text-h1')
+    ui.html('<br>')
+    ui.label(sub_service.description)
+
+
+ui.run(title='NiceCLOUD Portal', show=False)