Creating a Single Page Application (SPA) with NiceGUI

[Diegiwg]

Example.of.the.System.Working.mp4

• I would like to update only a certain part of my application, keeping the menu layout intact, as it is always the same on all 'pages'.
• For that, I tried to find a method to force the full rendering of a specific component, but I didn't find anything in the NiceGUI API.
• Then, looking a little further, I understood where the 'elements' are stored, and how I could transfer the responsibility of these arguments to another Element.

Using that as a base, I created the following module:

routes.py

from dataclasses import dataclass
from typing import Callable
from nicegui.element import Element


@dataclass
class Route:
    path: str
    title: str
    handler: Callable


class RouteManager:
    routes: dict[str, Route]
    current_route: Route

    def __init__(self) -> None:
        self.routes = dict()

    def register_route(self, route: Route):
        self.routes[route.path] = route

    def set_route(self, route_path: str):
        self.current_route = self.routes[route_path]

    async def run_route(self):
        return await self.current_route.handler()


route_manager = RouteManager()


@dataclass
class State:
    root: Element
    element: Element


state = State(root=Element(""), element=Element(""))


@dataclass
class Redirect:
    route_path: str

    async def run(self):
        route_manager.set_route(self.route_path)
        temp: Element = await route_manager.run_route()

        state.element.clear()
        state.element.slots = temp.slots
        state.root.remove(temp)

        state.element.style(add="width: 100%; height: 95vh;")

Note: it will always report an error when changing pages, because the Temporary Element no longer exists, but the rendering loop will still try to render it. This does not break anything in the application.

To use the system, just define some pages, like the examples below:

sales.py

from nicegui import ui
from nicegui.page import globals

import components
import routes


async def page():
    with ui.column().style(add="width: 100%; height: 95vh;") as element:
        globals.title = routes.route_manager.current_route.title
        components.page_title(routes.route_manager.current_route.title)

        ui.label("WIP").classes(add="text-center w-full")

    return element


sales_route = routes.Route("sales", "Vendas", page)
routes.route_manager.register_route(sales_route)

Note: always remember to structure the first element as ui.column, as it is the element with the closest behavior to the base @ui.page.

And in the main of your application, define the root page “/”, with the following initial structure:

main.py

from nicegui import Client, app, ui

import components
import pages
import routes

routes.route_manager.set_route("sales")


@ui.page("/")
async def render(client: Client):
    with ui.card().style(add="width: 100%; height: 95vh;"):
        client.on_connect(components.render_layout)

        with ui.column().style(add="width: 100%; height: 95vh;") as root:
            element = await routes.route_manager.run_route()

        routes.state.root = root
        routes.state.element = element


app.add_static_files("/static", "static")
ui.run(binding_refresh_interval=0.5, uvicorn_logging_level="")

That's it, now with buttons like the ones below, you can easily navigate between your pages, updating only the necessary components:

layout.py

from nicegui import ui

from routes import Redirect
from components import clock

def menu_button(text: str, path: str):
    return ui.button(text, on_click=Redirect(path).run).style(add="width: 100%;")


async def render():
    with ui.left_drawer():
        with ui.column():
            with ui.row().style(
                add="display: flex; align-items: center; justify-content: center; width: 100%;"
            ):
                ui.image(source="/static/logo.png").props(add="width='50px'")
                ui.label("QUEIROZ LUBRIFICANTES").style(add="")
            ui.separator()

            with ui.column().style(
                add="width: 100%; height: 85vh; display: grid; align-content: space-between;"
            ):
                with ui.column().style(add="width: 100%;"):
                    menu_button("Vendas", "sales")
                    menu_button("Produtos", "products")
                    menu_button("Estoque", "stock")

                await clock()

It's not perfect, but it gives an implementation idea for rendering all children of a component via update.
Remembering, I don't know if this update system exists in the NiceGUI API. If there is, let me know.

[rodja]

Very nice. Build-in SPA support is surely a good thing for NiceGUI in the long run. Your code shows a first implementation. I like the introduction of Route and RouteManager as it adds some tooling support. Whenever we need SPA like functionality we currently do it this way:

from nicegui import ui

def show_one():
    content.clear()
    with content:
        ui.label('Content One').classes('text-2xl')


def show_two():
    content.clear()
    with content:
        ui.label('Content Two').classes('text-2xl')


def show_three():
    content.clear()
    with content:
        ui.label('Content Three').classes('text-2xl')


with ui.row():
    ui.button('One', on_click=show_one)
    ui.button('Two', on_click=show_two)
    ui.button('Three', on_click=show_three)

content = ui.column()
show_one()

ui.run()

While it works nicely and is also quite short, it has by no means any framework to support history, location path updates and other things which can easily be integrated in your solution. Maybe the build-in support can be based on your code? Another approach would be to look at Vue.js router and use that as foundation...

[Diegiwg]

Damn, I didn't know you could do with Elementor and get the context of the element.

I used it as a base here, and I rewrote the Redirect.run function.

No more errors now, thank you.

Link to GIST with complete example code

[Diegiwg]

Example Code:

from dataclasses import dataclass
from typing import Callable
from nicegui.element import Element
from nicegui import ui, Client


#### ROUTES.PY ####
@dataclass
class Route:
    path: str
    title: str
    handler: Callable


class RouteManager:
    routes: dict[str, Route]
    current_route: Route

    def __init__(self) -> None:
        self.routes = dict()

    def register_route(self, route: Route):
        self.routes[route.path] = route

    def set_route(self, route_path: str):
        self.current_route = self.routes[route_path]

    async def run_route(self):
        await self.current_route.handler()


route_manager = RouteManager()


@dataclass
class State:
    element: Element


state = State(element=Element(""))


@dataclass
class Redirect:
    route_path: str

    async def run(self):
        route_manager.set_route(self.route_path)
        return await route_manager.run_route()


#### LAYOUT.PY ####
def menu_button(text: str, path: str):
    return ui.button(text, on_click=Redirect(path).run).style(add="width: 100%;")


async def layout_render():
    with ui.left_drawer():
        with ui.column():
            with ui.row().style(
                add="display: flex; align-items: center; justify-content: center; width: 100%;"
            ):
                ui.label("MENU")
            ui.separator()

            with ui.column().style(
                add="width: 100%; height: 85vh; display: grid; align-content: space-between;"
            ):
                with ui.column().style(add="width: 100%;"):
                    menu_button("Page 01", "page-1")
                    menu_button("Page 02", "page-2")


#### PAGE_01.PY ####
async def page_01():
    state.element.clear()
    with state.element:
        ui.label("Page 01")


page_01_route = Route("page-1", "Page 01", page_01)
route_manager.register_route(page_01_route)


#### PAGE_02.PY ####
async def page_02():
    state.element.clear()
    with state.element:
        ui.label("Page 02")


page_02_route = Route("page-2", "Page 02", page_02)
route_manager.register_route(page_02_route)

#### MAIN.PY ####
route_manager.set_route("page-1")


@ui.page("/")
async def render(client: Client):
    client.on_connect(layout_render)
    state.element = ui.card().style(add="width: 100%; height: 95vh; background: grey;")
    await route_manager.run_route()


ui.run(dark=True)

[rodja]

Nice!

[rodja]

We just merged an very simple SPA example into main: https://github.com/zauberzeug/nicegui/tree/main/examples/single_page_app

[ghost]

This SPA example is very clever, but I think it's limited by popstate with the URL-liked SPA route string, with this method, there is only one RouteFrame object exist which is the container for context, I can't create more than one RouteFrame object to split the context into multi sub-contexts just bucause the URL-liked SPA route ONLY one can appear to maintain the brower history record, and this method causes a conflict between SPA Router(javascript event trigger) and FastAPI‘s Router(HTTP trigger) because both use URL string. So how about use another syntax for SPA route which different from HTTP URL? the advatages about the new syntax SPA route are: 1) can free split the context into sub-contexts to reflesh sub-contexts Independently or reflesh the whole context because the SPA route is internal used no matter consider the browser history record (if needed, there can do a translation in JavaScript event). 2) Can be mixed SPA with MPA.

[rodja]

Sure. It's only an example. And we are still not sure how the API should be. Maybe your points should be discussed in #1066...

[aisha0801]

Hello, I'm relatively new to coding and NiceGUI, and I'm attempting to learn by dissecting your code. I've replicated the files you've provided here, but upon running the code, I encountered an error: ModuleNotFoundError: No module named 'components'. Could someone please guide me on how to troubleshoot this issue? Is 'components' supposed to be another module, or is it something that needs to be installed via the terminal?

[rodja]

Have you tried https://github.com/zauberzeug/nicegui/tree/main/examples/single_page_app? The code directly provided in this old discussion may not work anymore due to changes made over the time in NiceGUI. We only update the official examples.

[rotrigoh]

Ficou muito massa, mano! Parabéns pelo trabalho. Sabes me dizer se você ainda continua utilizando o nicegui para criar essas ferramentas? Te atende bem?

[falkoschindler]

@rotrigoh Please use English language when posting to this repository, e.g. by using an online translation tool. Otherwise we need to do the translation ourselves and can't be sure the result is what you meant.

[rotrigoh]

Sorry... I ended up realizing that our friend in the topic was Brazilian, so I decided to speak in our language. Anyway, I'll pay attention next time.

[v479038280]

beautiful example ,

[rodja]

Just for reference: in #2811 @Alyxion created a beautiful pull-request to provide direct API support for SPAs in NiceGUI. Hopefully it will be merged in the next few weeks.

[Alyxion]

Definitely. Was the last weeks on the road due to work w/ quite long days and if you have at 9 in the evening the choice between hotel spa 🧖‍♂️ and evening beer 🍺 or working on a 13 inch laptop 📓 in the hotel room - choice is easy - but will be back on Monday and continue where I stopped. PR should latest be finished by mid May, so stay tuned. 😎

[me21]

What's the difference between SPA and regular NiceGUI workflow when you just remove some elements from the page and create others?

[falkoschindler]

See https://en.wikipedia.org/wiki/Single-page_application. With the mentioned pull request we try to find an API for cleverly adding and removing elements so that it feels like navigating the app, even though the browser tab never has to reload the page. Of course, you can add and remove elements yourself, but for a large application it is useful to hide away the details.