How can global callbacks/background processes access local ui elements?

[aranvir]

Question

Hi, I spent a couple of ours playing around with nicegui and I'm really impressed by the possibilities! However, I struggle a bit with translating the simple examples into the context of a multi-page application.

Elements defined in a function decorated with ui.page are private to the client. If I want to run something like the websocket example within a page it does not work correct.

The websocket server and the handle_connect hook have to be defined globally, but the elements that they are supposed to update are limited to the function scope. I also tried to put all of it in a class, and that works somewhat, but is a buggy solution with Client has been deleted but is still being used. messages popping up whenever I leave the page but continue to send messages via websocket.

So yea, hence the title question is: How can global callbacks/background processes access local ui elements?

I added my approach below which also includes an example. This works fine as long as the page is open. Once it's closed it wont work anymore, e.g.:

• Run app
• Navigate to /web-sockets
• Connect via a terminal and confirm responsiveness
• Navigate back to /
• Any message sent now will cause an error log
• Going back to web-sockets will allow to receive messages again but the connections counter will not be updated

import asyncio
from abc import abstractmethod
from typing import Set

import websockets
from websockets.server import WebSocketServerProtocol
from nicegui import ui, app


class WebsocketPage:
    def __init__(self):
        self.label = "Websocket Example"
        self.path = "/websocket-example"

        self.connections: Set[WebSocketServerProtocol] = set()
        self.ready = False
        self._connections_label = None
        self._messages = None
        app.on_startup(self.start_websocket_server)

    def create(self):
        ui.label('Websockets demo').classes('text-2xl')
        ui.label('Run this in the console to connect:')
        ui.code('python -m websockets ws://localhost:8765/').classes('pr-8 pt-1 h-12')
        with ui.row().classes('items-center'):
            self._connections_label = ui.label('0')
            ui.label('connections')
            ui.button('send hello', on_click=lambda: websockets.broadcast(self.connections, 'Hello!')).props('flat')
        ui.separator().classes('mt-6')
        ui.label('incoming messages:')
        self._messages = ui.column().classes('ml-4')
        self.ready = True

    async def handle_connect(self, websocket: WebSocketServerProtocol):
        """Register the new websocket connection, handle incoming messages and remove the connection when it is closed."""
        if not self.ready:
            await websocket.close(reason="App not ready.")
        this_connection = {websocket,}
        try:
            self.connections.add(websocket)
            self._connections_label.text = len(self.connections)
            async for data in websocket:
                with self._messages:
                    ui.label(str(data))
                    websockets.broadcast(self.connections.difference(this_connection), str(data))
        finally:
            self.connections.remove(websocket)
            self._connections_label.text = len(self.connections)

    async def start_websocket_server(self):
        async with websockets.serve(self.handle_connect, 'localhost', 8765):
            await asyncio.Future()


websocket_page = WebsocketPage()


@ui.page("/")
def landing_page():
    ui.link("Websocket Page", target="/web-sockets")


@ui.page("/web-sockets")
def make_page():
    ui.link("Landing Page", target="/")
    websocket_page.create()


ui.run(host="localhost")

[aranvir]

Wanted to add an afterthought: My best guess is that this needs a "Channels" solution, so a central exchange for data that can be made available via dependency injection. The websocket server callback then just pushes data to that exchange and forwards incoming messages to the connection.
This exchange would then also need the option to register a callback that shall be run whenever a message is received so we can then update the components owned by the page.

Does that make sense?

[falkoschindler]

Hi @aranvir,

One possibility that just came into my mind is to use the rather new ElementFilter to find UI elements from a background task:

import asyncio
import time
from nicegui import ElementFilter, app, ui

ui.label().mark('clock')

def update_clock():
    for element in ElementFilter(kind=ui.label, marker='clock'):
        element.text = time.strftime('%H:%M:%S')

async def run_clock():
    while True:
        update_clock()
        await asyncio.sleep(1)

ui.run()

[aranvir]

Sure, below I used your clock example with my "page wrapper" approach.

The update is not working: While the background task is running, the ElementFilter is not finding any elements to update. However, if adding an explicit container to the page (e.g., self.container = ui.column()) and using the element filter within that scope the updates do work! But opening multiple tabs will stop the update on the previous tab - since only one container is stored.

I'm new to nicegui but here is my suspicion: The element filter only works on public page elements. Since @ui.page() elements are private it will not find them unless a scope element from this page is provided. So, I did some more digging in your code and found client. I guess, a client serves one page and maintains its own root container. Thus, I modified the code to loop through all clients, and use the appropriate client as root container to run the updates. Then it works with all tabs! Of course, the more clients are connected the worse performance will get, but it's a start.

Without container

import asyncio
import time
from nicegui import ElementFilter, app, ui


class ClockPage:
    def __init__(self):
        self.label = "Clock Example"
        self.path = "/clock"

    def create(self):
        ui.label("Current time")
        ui.label(time.strftime('%H:%M:%S')).mark('clock')


clock_page = ClockPage()


def update_clock():
    for element in ElementFilter(kind=ui.label, marker='clock'):
        element.text = time.strftime('%H:%M:%S')


async def run_clock():
    while True:
        update_clock()
        await asyncio.sleep(1)


@ui.page("/")
def landing_page():
    ui.link(clock_page.label, target=clock_page.path)


@ui.page(clock_page.path)
def make_page():
    ui.link("Landing Page", target="/")
    clock_page.create()


app.on_startup(run_clock)
ui.run(host="localhost")

With client container

import asyncio
import time
from nicegui import ElementFilter, app, ui, client


class ClockPage:
    def __init__(self):
        self.label = "Clock Example"
        self.path = "/clock"

    def create(self):
        ui.label("Current time")
        ui.label(time.strftime('%H:%M:%S')).mark('clock')


clock_page = ClockPage()


def update_clock():
    for _client in client.Client.instances.values():
        if _client.page.path != clock_page.path:
            continue
        with _client.content:
            for element in ElementFilter(kind=ui.label, marker='clock'):
                element.text = time.strftime('%H:%M:%S')


async def run_clock():
    while True:
        update_clock()
        await asyncio.sleep(1)


@ui.page("/")
def landing_page():
    ui.link(clock_page.label, target=clock_page.path)


@ui.page(clock_page.path)
def make_page():
    ui.link("Landing Page", target="/")
    clock_page.create()


app.on_startup(run_clock)
ui.run(host="localhost")

[aranvir]

I think I came up with a good helper function to wrap this behavior and used it to get my websocket example to work.

from nicegui import client

def with_clients(path: str, fn: Callable):
    """Call a function within the scope of all clients connected to a certain page path.

    Args:
        path: Page path that shall serve the scope
        fn: Callable that shall be run within the page scope
    """
    for _client in client.Client.instances.values():
        if _client.page.path != path:
            continue
        with _client.content:
            fn()

And below the full websocket example: Now allowing multiple tabs open that will all show the same content and update live.

import asyncio
from typing import Set, Callable

import websockets
from websockets.server import WebSocketServerProtocol
from nicegui import ui, app, ElementFilter, client

CONNECTIONS: Set[WebSocketServerProtocol] = set()


class WebsocketPage:
    def __init__(self):
        self.label = "Websocket Example"
        self.path = "/websocket-example"

    def create(self):
        ui.label('Websockets demo').classes('text-2xl')
        ui.label('Run this in the console to connect:')
        ui.code('python -m websockets ws://localhost:8765/').classes('pr-8 pt-1 h-12')
        with ui.row().classes('items-center'):
            ui.label(str(len(CONNECTIONS))).mark("lb_conn")
            ui.label('connections')
            ui.button('send hello', on_click=lambda: websockets.broadcast(CONNECTIONS, 'Hello!')).props('flat')
        ui.separator().classes('mt-6')
        ui.label('incoming messages:')
        ui.column().classes('ml-4').mark("col_messages")


websocket_page = WebsocketPage()


def with_clients(path: str, fn: Callable):
    """Call a function within the scope of all clients connected to a certain page path.

    Args:
        path: Page path that shall serve the scope
        fn: Callable that shall be run within the page scope
    """
    for _client in client.Client.instances.values():
        if _client.page.path != path:
            continue
        with _client.content:
            fn()


def update_connection_label():
    for element in ElementFilter(kind=ui.label, marker="lb_conn"):
        element.text = len(CONNECTIONS)


def update_chat_history(data: str):
    def fun():
        for element in ElementFilter(kind=ui.column, marker="col_messages"):
            with element:
                ui.label(str(data))
    return fun


async def handle_connect(websocket: WebSocketServerProtocol):
    """Register the new websocket connection, handle incoming messages and remove the connection when it is closed."""
    this_connection = {websocket,}
    try:
        CONNECTIONS.add(websocket)
        with_clients(websocket_page.path, update_connection_label)
        async for data in websocket:
            websockets.broadcast(CONNECTIONS.difference(this_connection), str(data))
            with_clients(websocket_page.path, update_chat_history(data))
    finally:
        CONNECTIONS.remove(websocket)
        with_clients(websocket_page.path, update_connection_label)


async def start_websocket_server():
    async with websockets.serve(handle_connect, 'localhost', 8765):
        await asyncio.Future()


@ui.page("/")
def landing_page():
    ui.link(websocket_page.label, target=websocket_page.path)


@ui.page(websocket_page.path)
def make_page():
    ui.link("Landing Page", target="/")
    websocket_page.create()


app.on_startup(start_websocket_server)
ui.run(host="localhost")

[aranvir]

@falkoschindler do you think this with_clients() function is an appropriate approach? If so, I think it would be useful to add it to client either as a function or a classmethod for Client. I can start a PR, if you approve of the approach :)

[falkoschindler]

@aranvir I'm not 100% sure if this is the best way forward. Maybe you can start with a new feature request describing the problem and the proposed solution including a small demo. Then we can better discuss the API and namespace for the new function. Thanks!

[aranvir]

Posted! I'll be on vacation for a couple of weeks but I'm curious to get back into it afterwards!