Introduce API to build Single Page Applications (SPAs)

[Alyxion]

NiceGUI is for us at Lechler a really awesome solution and step forward from Streamlit in regards of the visualization of live and streaming data as it puts the dev far more in control of which sub elements and page regions are updated when.

On the other hand it is still lacking three for us very crucial features Streamlit offers:

• A persistent WebSocket connection for the whole user session (per tab)
• A data storage possibility per tab to enable the user to create multiple app instances.
• In-memory storage of complex objects (e.g. pandas data tables)

This (still work in progress) pull request tries to resolve at least most of the points above. It shall not yet resolve the situation that a user has an unstable internet connection and thus looses the connection to a server completely and needs to reconnect.

Persistent connection

In a scenario where you want to serve your NiceGUI solution not to hundreds of users there is after a certain point no way around scaling the solution over multiple processes, CPUs or over multiple servers.

If you need to load/keep alive large amounts of data per user w/o involving an external database this requires that the whole user session, even between page changes, is bound to one single process on one specific server. Streamlits uses a SPA approach here thus it creates a WebSockets connection once and all follow-up page and tab changes are just virtual thus changing the URL and browser history in the browser using pushstate but never really loading a new page using GET.

As discussed in the Add app.storage.tab or similar (1308) and in Discord there are several use cases where this is crucial to retain in-memory data on a "per session" basis, see below, which consequently requires that there is such a session in the first place.

Per tab storage

A data storage possibility per tab is cruicial to enable the user to create multiple app instances with different login credentials, configurations and views on a per tab basis. This is on purpose volatile so that user-credentials, critical business data etc. are gone once the browser tab was closed and the connection timed out. This shall match the current behavior of st.session_state.

In-memory storage of complex objects

The possibility to store living, non-JSON compatible objects such as Pandas tables, ML model weights etc. on a "per tab" basis and make them as easy accessible among different pages, global helper classes etc. as currently app.storage.user.

Update: Extracted the app.storage.session feature into a separate pull request 2820

[rodja]

Thank you @Alyxion. There are a lot of interesting things in here. While you are right that a certain kind of applications my want to combine SPA and "per tab storage", it would make review and discussions simpler if you could create two separate pull requests for these features.

[Alyxion]

Hello @rodja, sure. As this Pull Request here is anyway just a draft yet and the amount of changes of the per-tab data was manageable I extracted the lines into the separate request #2820 and added a unit test to it. As this one is dependent on the other I will keep it the way it is for now.

[Alyxion]

Added support for query and URL path parameters such as required by the modularization example.

https://github.com/Alyxion/nicegui/blob/feature/client_data/examples/modularization/main.py works really like a charm now in regards of user experience when switching pages.

At the moment it still throws a "Found top level layout element "Header" inside element "SinglePageRouterFrame". Top level layout elements should not be nested but must be direct children of the page content. This will be raising an exception in NiceGUI 1.5" warning due to the fact that it does not know yet that it actually is in the page content in that case.

Update: Fixed the warning. PageLayout now also accepts the SPA root as valid parent for top level elements.

[rodja]

Yes, we really want to merge this. I still need to find the time for another round of review. Especially we need to make a decision about the separation between view and outlet.

[whoamiafterall]

Hi, i just wanted to state that i'm also really looking forward to this - but dont want to put pressure on you :)

[Alyxion]

We are actually intensively testing this already with a larger user base in our company since a couple of weeks, overall it seems quite stable. We fond one minor bug (loosing query params when using the back button) which we will fix this week and sync again with the main branch.

Also looking forward to see it branched as it enables some very neat features such as dynamic, volatile per-connection - practically "app instance" - data.

[Mte90]

I was checking this PR that maybe resolve my issue #4119 but I think that the documentation is not good enough as we have a new decorator outlet and other stuff that is not documented in this PR.

[Alyxion]

Thanks @Mte90 . Actually it is documented since a couple of weeks, see the commit message directly above your comment ;-), though some more detail and refinement would definitely not hurt. But due to r/l reasons very limited time resources. Just run the main.py of the PR to run the docu, you can find it in the Pages & Routing section.

[Mte90]

Thanks!

I am not sure if with this feature it is possible to reference an element per user, at the end I implemented in this way #4119 (comment)

[Alyxion]

Thanks!

I am not sure if with this feature it is possible to reference an element per user, at the end I implemented in this way #4119 (comment)

Yes, it is. We are actually building a kinda complex SPA on it already with several different screens and many parallel users, no issues. Conceptual its like this:

from nicegui import ui
from pydantic import BaseModel, Field


class User(BaseModel):
    counter: int = Field(0, description="Count of times user clicked the button.")


class HomeScreen:
    def __init__(self, user: User):
        self.user = user

    async def build(self):
        ui.button("Click me").on_click(self.on_inc_button_click)
        ui.link("Go to other page", other_page)

    def on_inc_button_click(self):
        self.user.counter += 1
        ui.notification(f"You have clicked {self.user.counter} times.")


class OtherScreen:
    def __init__(self, user: User):
        self.user = user

    async def build(self):
        ui.label(f"Counter is currently at {self.user.counter}")


@ui.outlet("/")
def main_layout():
    user = User()  # actual code could e.g. try to fetch last session data from REDIS here.
    with ui.header(fixed=True):
        ui.label("Sample App")
    yield {"user": user}


@main_layout.view("/")
async def home(user: User):
    await HomeScreen(user).build()


@main_layout.view("/other")
async def other_page(user: User):
    await OtherScreen(user).build()


ui.run()

The outlet is run per user when he/she connects. There one can create per-user instance data. This data is then passed to individual page builders. On top of that we still synch the data w/ REDIS based upon the tab_id but that would exceed the sample here now.

[Mte90]

Cool so I am waiting for this PR to get approval and in meantime I will use what I developed. In the future we willrefactor for this :-D

Maybe also a guide/doc about how to migrate a normal nicegui app to this new solution can be helpful to understand the differences.

[rodja]

Hi @Alyxion, I found a bit time to further look into the pull request. While by no means complete or well structured, I have some questions and remarks:

1. The test_routing_url is failing. I could not quickly figure out why the url path is not updated anymore. Maybe you have an idea?
2. Why is the instance of the SinglePageRouter in outlet called content? Would not router be a better name?
3. The overwrite parameter in outlet.setup_page looks like a code smell -- can you add a test where it is required to be set to True? That would help me to understand the requirements better.
4. Could you rename SinglePageRouter.current_router to SinglePageRouter.current_frame? Also I think there is a mix of responsibilities between SinglePageRouter and RouterFrame. Why not call it simply Frame and let it only provide the UI slot which contains sub-outlets/views?
5. You already explained the user_data concept a bit in Introduce API to build Single Page Applications (SPAs) #2811 (comment). But I still don't fully get it. Do you have some examples? Why can we not do it in a similar manner as with app.storage.tab?

Also I still think we can simplify the API by allowing ui.outlet to have no yield statement (see #2811 (comment)). My test was quite successful when adding the following block to Outlet.build_page_template after getting the frame:

if inspect.iscoroutine(frame):
    frame = await frame
if frame is None:
    return  # if outlet builder is not a generator, run_safe already added all content

[rodja]

And some more question/remarks:

6. Do we need the SinglePageTarget.valid property? I think Outlet.resolve_target should simply return None if it does not matches the routes.
7. Can we get rid of the route matching in SinglePageTarget and completely do it in the `Outlet? It would better suit their responsibilities.
8. Do we really need await ui.context.client.connected(30.0) # to ensure storage.tab and storage.client availability in Outlet.setup_page?
9. Can you list all the features you implemented? Or even better: write up the tests to ensure the features are working? In dc6185d I started with the obvious ones. But there is so much more. Path matching, user_data, setting titles, ... while I was looking through the code I could barely change anything without fear of breaking it.

[Alyxion]

Hello Rodja,

thank you for the the detailed review. I think many of the points you mentioned should be resolvable quite quickly, others will take some time. Will get back to your points next week.

[whoamiafterall]

Hey, may be a little off-topic here, but regarding point 8 it might be helpful.
We're currently using this example in our code:
https://github.com/zauberzeug/nicegui/tree/main/examples/single_page_app

And we run into navigation issues (buttons not working and so on) all the time if we don't put await ui.context.client.connected() in the first line of every "view" which i guess refers to "outlet.page" in this PR's terminology.
We still do run into issues sometimes even with it added though and can't really figure out why.

If you think it helps i can provide the corresponding error logs (Timeout errors from router mainly) and code snippets.
Or do you think i should open an issue on the current SPA_example (Haven't done that because i'm waiting for this to be merged)?

[Alyxion]

Hey, may be a little off-topic here, but regarding point 8 it might be helpful. We're currently using this example in our code: https://github.com/zauberzeug/nicegui/tree/main/examples/single_page_app

And we run into navigation issues (buttons not working and so on) all the time if we don't put await ui.context.client.connected() in the first line of every "view" which i guess refers to "outlet.page" in this PR's terminology. We still do run into issues sometimes even with it added though and can't really figure out why.

If you think it helps i can provide the corresponding error logs (Timeout errors from router mainly) and code snippets. Or do you think i should open an issue on the current SPA_example (Haven't done that because i'm waiting for this to be merged)?

Thank you @whoamiafterall . Actually the original SPA sample when I started this PR (meanwhile nearly a year ago) had some issues with the back button, though 4 months ago something has been patched. But its diverged soooo far to this PR now.

Regarding the ui.context.client.connected(): My first guess is that if you wait for being connected, you can also be sure that the JavaScripts where loaded and thus the window.addEventListener("popstate", (event) is in place.

This PR actually even enforces the ui.context.client.connected() under the hood so you at least would not have to add it to every method again.

[Alyxion]

First of all sorry for the delay, but at the moment I'm quite busy. Thanks for your detailed review once again.

Hi @Alyxion, I found a bit time to further look into the pull request. While by no means complete or well structured, I have some questions and remarks:

1. The test_routing_url is failing. I could not quickly figure out why the url path is not updated anymore. Maybe you have an idea?

I just verified the code again, it should be correct. Before a navigation execution is actually executed first the callback is checked, than the "config" (ex "SinglePageRouterConfig", now Outlet, I just fixed that as well in the code). It defines the final path which is opened. All of this works fine for the test. It returns main and navigates there. If one runs the inner code as single app all also looks correct, will investigate further, may be just a missing sleep.

UPDATE: Just verified the code, there is a check for the browser URL at the end of the check though the behavior currently does/shall just influence the internal routing defining "Which page shall be actually rendered", in theory it can even return content w/o an URL at all. For everything else the user can/should use ui.navigate.to. I added a second unit test, one with real forwarding, one with internal forwarding. Both tests work now.

2. Why is the instance of the SinglePageRouter in outlet called content? Would not router be a better name?

Becauuuuuuuse of this author ;-)....

Just with the difference that we have an additional class layer in between now, but thats the origin. Of course we can rename it if desired.

3. The overwrite parameter in outlet.setup_page looks like a code smell -- can you add a test where it is required to be set to True? That would help me to understand the requirements better.

I removed it, it actually had no effect anymore anyway as it continued at the end of the for-loop. There is still a bug though we need to keep in mind that if you actually really share a base path, e.g. ui.page(/my_target) is defined first and then an SPA is defined at / not all functions respect this yet such as navigate.to and rather than doing a real browser navigation they try to load the page as Outlet view.

4. Could you rename SinglePageRouter.current_router to SinglePageRouter.current_frame? Also I think there is a mix of responsibilities between SinglePageRouter and RouterFrame. Why not call it simply Frame and let it only provide the UI slot which contains sub-outlets/views?

Sure.

5. You already explained the user_data concept a bit in Introduce API to build Single Page Applications (SPAs) #2811 (comment). But I still don't fully get it. Do you have some examples? Why can we not do it in a similar manner as with app.storage.tab?

I think the name user_data might be an unlucky / misleading choice.
What it does in a nutshell is basically transporting local variables from the outlet to the views. Our from outlets to suboutlets.
This can be references to ui.elements, but obviously also other per-user session data, e.g. caches etc.
The complex example uses is for the menu_drawer but see example below:

@ui.page('/')
def my_page()
   header = ui.header()
   ...
   def my_sub_func():
      ... can access header as its a local var ...

@ui.outet('/')
def my_outlet()
    header = ui.header()
    yield {"header": header}
    
@my_outlet.view()
def my_other_function_which_cannot_access_the_local_variables_anymore(header):
    header.hide_show_what_ever()

As it refers living / arbritrary objects it can not be serealized. It could in theory me merged with the client_storage though, the lifetime is the same as both are connection bound.

Also I still think we can simplify the API by allowing ui.outlet to have no yield statement (see #2811 (comment)). My test was quite successful when adding the following block to Outlet.build_page_template after getting the frame:

if inspect.iscoroutine(frame):
    frame = await frame
if frame is None:
    return  # if outlet builder is not a generator, run_safe already added all content

Didnt work for me back then for several functions of the NiceCloud app, would need to be investigated, the inner functions failed then. Actually I still like the clean way of definitions between "this is a template" and "this is the actual content we store in the frame".

[Alyxion]

And some more question/remarks:

6. Do we need the SinglePageTarget.valid property? I think Outlet.resolve_target should simply return None if it does not matches the routes.

After reviewing the code: Actually its always True if either a builder was assigned and/or the fragment.
Thus yes, we can convert this to a function or an actual @property.

7. Can we get rid of the route matching in SinglePageTarget and completely do it in the `Outlet? It would better suit their responsibilities.

Not for more complex applications, it can e.g. individualize the title, the fragment etc, the builder being called when using on_navigate. The name could / should be updated though and in general a cleanup might not hurt before merging it into main.

8. Do we really need await ui.context.client.connected(30.0) # to ensure storage.tab and storage.client availability in Outlet.setup_page?

I have to reinvestigate. This PR is so aged mean-while but I think back then there we side effects if the client was not connected yet.

9. Can you list all the features you implemented? Or even better: write up the tests to ensure the features are working? In dc6185d I started with the obvious ones. But there is so much more. Path matching, user_data, setting titles, ... while I was looking through the code I could barely change anything without fear of breaking it.

Yes, of course. Can not promise though when yet, quite intense releases ongoing atm and then two weeks offroad in the US, but for sure till end of March.