Introduce API to build Single Page Applications (SPAs)

examples/authentication_spa/main.py

@@ -0,0 +1,103 @@
+import html
+import uuid
+from typing import Optional, Union
+
+from nicegui import ui, app
+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 '/' == INDEX_URL:
+        if 'login_token' in app.storage.tab:
+            return SECRET_AREA_URL
+    return url
+
+
+@ui.outlet('/', on_navigate=portal_rerouting)
+def main_router():
+    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')
+    with ui.element() as border:
+        border.style('margin: 20pt;')
+        yield
+
+
+@main_router.view('/', title='🚪 NiceCLOUD Login')
+def main_app_index():
+    def handle_login():
+        username = input_field.value
+        password = pw.value
+        inv_pw.clear()
+        if username in DUMMY_LOGINS and DUMMY_LOGINS[username] == password:
+            app.storage.tab['login_token'] = uuid.uuid4().hex
+            app.storage.tab['username'] = username
+            ui.navigate.to(SECRET_AREA_URL)
+        else:
+            with inv_pw:
+                ui.label('Invalid password!').style('color: red;')
+
+    # login page
+    with ui.column() as col:
+        ui.label('Login to NiceCLOUD!').classes('text-3xl')
+        ui.html('<br>')
+        input_field = ui.input('Username').style('width: 100%').on('keydown.enter', lambda: pw.focus())
+        pw = ui.input('Password', password=True,
+                      password_toggle_button=True).style('width: 100%').on('keydown.enter', handle_login)
+        col.style('width: 300pt; top: 40%; left: 50%; transform: translate(-50%, -50%); position: absolute;')
+        # horizontally centered button
+        with ui.row().style('justify-content: center;'):
+            ui.button('Login').style('width: 100pt; left: 50%; '
+                                     'transform: translate(-50%, 0); position: absolute;').on_click(handle_login)
+        inv_pw = ui.row()
+        # give user and password hint
+        ui.html('<br>')
+        ui.label('Hint: admin/NicePass').style('color: gray;')
+        # provide link to try to access secret page w/o login
+        ui.html('<br>')
+        ui.link('Try to access secret area without login', SECRET_AREA_URL).style('color: gray;')
+
+
+def logout():  # logs the user out and redirects to the login page
+    del app.storage.tab['login_token']
+    app.storage.tab.clear()
+    ui.navigate.to(INDEX_URL)
+
+
+def check_login(url) -> Optional[Union[str, SinglePageTarget]]:
+    def error_page():
+        with ui.column().style('align-items: center; justify-content: center; left: 50%; top: 50%; '
+                               'transform: translate(-50%, -50%); position: absolute;'):
+            ui.label('⚠️').classes('text-6xl')
+            ui.label('You are not logged in!').classes('text-3xl')
+            ui.html('<br>')
+            ui.button('🚪 Go to login page').on_click(lambda: ui.navigate.to(INDEX_URL)).style('width: 200pt;')
+
+    if 'login_token' not in app.storage.tab:  # check if the user is not logged in
+        return SinglePageTarget(url, builder=error_page, title='Not logged in')
+    return url  # default behavior
+
+
+@main_router.outlet(SECRET_AREA_URL, on_navigate=check_login)
+def secret_area_router():
+    yield
+
+
+@secret_area_router.view('/', title='🔒 Secret Area')
+def secret_area_index():
+    with ui.column():
+        user_name = app.storage.tab['username']
+        esc_name = html.escape(user_name)
+        ui.html(f'Welcome to the secret area <b>{esc_name}</b>!<br><br>').classes('text-3xl')
+        ui.html('You chose the right place, we have cookies! 🍪<br><br>').classes('text-2xl')
+        ui.button('Logout').on_click(logout)
+
+
+ui.run(storage_secret='secret', title='NiceCLOUD')

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)