Introduce API to build Single Page Applications (SPAs) #2811

Alyxion · 2024-04-03T07:39:39Z

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

Open ToDos/Topics we need to adress

Integrated single page app into Client.open so navigation to SPA pages is redirected. Fixed bug with forward and backwards navigation between SPA pages. Collecting data from original pages to able to apply the original page title.

Fixed a bug which could occur when open was called before the UI was set up

…s registry in Client. General clean-up Added titles to sample app Added docu to SPA

…the structure of the root page, the possibility to override the class and implement custom routing and to react to the creation of sessions. * Added samples for the single page router * Refactored the Login sample with the new possibilities and making use of Pydantic as an example for a cleaner code base

rodja · 2024-04-04T01:26:27Z

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.

…in the current Client instance - which in practice means "per browser tab".

Alyxion · 2024-04-04T08:27:50Z

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.

Moved context import to top of the file

…e/client_data

Alyxion · 2024-04-05T11:53:27Z

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 · 2025-02-03T04:37:58Z

And some more question/remarks:

Do we need the SinglePageTarget.valid property? I think Outlet.resolve_target should simply return None if it does not matches the routes.
Can we get rid of the route matching in SinglePageTarget and completely do it in the `Outlet? It would better suit their responsibilities.
Do we really need await ui.context.client.connected(30.0) # to ensure storage.tab and storage.client availability in Outlet.setup_page?
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 · 2025-02-03T10:59:14Z

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 · 2025-02-04T20:07:35Z

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 · 2025-02-10T16:55:53Z

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 · 2025-02-10T18:14:48Z

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:

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.

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.

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.

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.

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 · 2025-02-10T18:28:56Z

And some more question/remarks:

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.

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.

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.

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.

rodja

I fixed some formatting and made code compatible with our ruff rules. Also I looked through the tests and added comments/suggestions here and there.

rodja · 2025-02-22T05:12:28Z