|
| 1 | +# Architecture |
| 2 | + |
| 3 | +deephaven.ui is a flexible and extensible [React-like](https://react.dev/learn/thinking-in-react) UI framework that can create complex UIs in Python. You can create UIs using only the components provided by deephaven.ui, or you can create your own components using the `@ui.component` decorator. |
| 4 | + |
| 5 | +## Components |
| 6 | + |
| 7 | +Components are reusable pieces of UI that can be combined to create complex UIs. Each component defines its own logic and appearance. Components can be simple, like a button, or complex, like a table with controls for filtering and sorting. Components can also be composed of other components, allowing for complex UIs to be built up from simpler pieces. |
| 8 | + |
| 9 | +Components are created using the `@ui.component` decorator. This decorator takes a function that returns a list of components, and returns a new function that can be called to render the component. The function returned by the decorator is called a "component function". Calling the function and assigning it to a variable will create an "element" that can be rendered by the client. |
| 10 | + |
| 11 | +```python |
| 12 | +from deephaven import ui |
| 13 | + |
| 14 | + |
| 15 | +@ui.component |
| 16 | +def my_button(): |
| 17 | + return ui.button("Click me!") |
| 18 | + |
| 19 | + |
| 20 | +btn = my_button() |
| 21 | +``` |
| 22 | + |
| 23 | +Once you have declared a component, you can nest it into another component. |
| 24 | + |
| 25 | +```python |
| 26 | +@ui.component |
| 27 | +def my_app(): |
| 28 | + return ui.flex(ui.text("Hello, world!"), my_button(), direction="column") |
| 29 | + |
| 30 | + |
| 31 | +app = my_app() |
| 32 | +``` |
| 33 | + |
| 34 | +## Rendering |
| 35 | + |
| 36 | +When you call a function decorated by `@ui.component`, it will return an `Element` object that references the function it is decorated by; that is to say, the function does _not_ run immediately. The function runs when the `Element` is rendered by the client, and the result is sent back to the client. This allows the `@ui.component` decorator to execute the function with the appropriate rendering context. The client must also set the initial state before rendering, allowing the client to persist the state and re-render in the future. |
| 37 | + |
| 38 | +Let's say we execute the following, where a table is filtered based on the value of a text input: |
| 39 | + |
| 40 | +```python |
| 41 | +from deephaven import ui |
| 42 | +import deephaven.plot.express as dx |
| 43 | + |
| 44 | + |
| 45 | +@ui.component |
| 46 | +def text_filter_table(source, column, initial_value=""): |
| 47 | + value, set_value = ui.use_state(initial_value) |
| 48 | + ti = ui.text_field(value=value, on_change=set_value) |
| 49 | + tt = source.where(f"{column}=`{value}`") |
| 50 | + return [ti, tt] |
| 51 | + |
| 52 | + |
| 53 | +# This will render two panels, one filtering the table by Sym, and the other by Exchange |
| 54 | +@ui.component |
| 55 | +def double_text_filter_table(source): |
| 56 | + tft1 = text_filter_table(source, "Sym", "CAT") |
| 57 | + tft2 = text_filter_table(source, "Exchange", "PETX") |
| 58 | + return ui.panel(tft1, title="Sym"), ui.panel(tft2, title="Exchange") |
| 59 | + |
| 60 | + |
| 61 | +_stocks = dx.data.stocks() |
| 62 | + |
| 63 | +tft = double_text_filter_table(_stocks) |
| 64 | +``` |
| 65 | + |
| 66 | +This should result in a UI like: |
| 67 | + |
| 68 | + |
| 69 | + |
| 70 | +How does that look when the notebook is executed? When does each code block execute? |
| 71 | + |
| 72 | +```mermaid |
| 73 | +sequenceDiagram |
| 74 | + participant U as User |
| 75 | + participant W as Web UI |
| 76 | + participant UIP as UI Plugin |
| 77 | + participant C as Core |
| 78 | + participant SP as Server Plugin |
| 79 | +
|
| 80 | + U->>W: Run notebook |
| 81 | + W->>C: Execute code |
| 82 | + C->>SP: is_type(object) |
| 83 | + SP-->>C: Matching plugin |
| 84 | + C-->>W: VariableChanges(added=[t, tft]) |
| 85 | +
|
| 86 | + W->>UIP: Open tft |
| 87 | + activate UIP |
| 88 | + UIP->>C: Fetch tft |
| 89 | + C-->>UIP: Export tft (Element) |
| 90 | +
|
| 91 | + Note over UIP: UI knows about object tft<br/>double_text_filter_table not executed yet |
| 92 | +
|
| 93 | + UIP->>SP: Render tft (initialState) |
| 94 | + SP->>SP: Run double_text_filter_table |
| 95 | + Note over SP: double_text_filter_table executes, running text_filter_table twice |
| 96 | + SP-->>UIP: Result (document=[panel(tft1), pane(tft2)], exported_objects=[tft1, tft2]) |
| 97 | + UIP-->>W: Display Result |
| 98 | + deactivate UIP |
| 99 | +
|
| 100 | + U->>UIP: Change text input 1 |
| 101 | + activate UIP |
| 102 | + UIP->>SP: Change state |
| 103 | + SP->>SP: Run double_text_filter_table |
| 104 | + Note over SP: double_text_filter_table executes, text_filter_table only <br/>runs once for the one changed input<br/>only exports the new table, as client already has previous tables |
| 105 | + SP-->>UIP: Result (document=[panel(tft1'), panel(tft2)], <br/>state={}, exported_objects=[tft1']) |
| 106 | + UIP-->>W: Display Result |
| 107 | + deactivate UIP |
| 108 | +``` |
| 109 | + |
| 110 | +### Threads and rendering |
| 111 | + |
| 112 | +When a component is rendered, the render task is [submitted to the Deephaven server as a "concurrent" task](https://deephaven.io/core/pydoc/code/deephaven.server.executors.html#deephaven.server.executors.submit_task). This ensures that rendering one component does not block another component from rendering. A lock is then held on that component instance to ensure it can only be rendered by one thread at a time. After the lock is acquired, a root [render context](#render-context) is set in the thread-local data, and the component is rendered. |
| 113 | + |
| 114 | +### Render context |
| 115 | + |
| 116 | +Each component renders in its own render context, which helps keep track of state and side effects. While rendering components, "hooks" are used to manage state and other side effects. The magic part of hooks is they work based on the order they are called within a component. When a component is rendered, a new context is set, replacing the existing context. When the component is done rendering, the context is reset to the previous context. This allows for nested components to have their own state and side effects, and for the parent component to manage the state of the child components, re-using the same context when re-rendering a child component. |
| 117 | + |
| 118 | +## Communication/Callbacks |
| 119 | + |
| 120 | +When the document is first rendered, it will pass the entire document to the client. When the client makes a callback, it needs to send a message to the server indicating which callback it wants to trigger, and with which parameters. For this, we use [JSON-RPC](https://www.jsonrpc.org/specification). When the client opens the message stream to the server, the communication looks like: |
| 121 | + |
| 122 | +```mermaid |
| 123 | +sequenceDiagram |
| 124 | + participant UIP as UI Plugin |
| 125 | + participant SP as Server Plugin |
| 126 | +
|
| 127 | + Note over UIP, SP: Uses JSON-RPC |
| 128 | + UIP->>SP: setState(initialState) |
| 129 | + SP-->>UIP: documentUpdated(Document, State) |
| 130 | +
|
| 131 | + loop Callback |
| 132 | + UIP->>SP: foo(params) |
| 133 | + SP-->>UIP: foo result |
| 134 | + opt Update sent if callback modified state |
| 135 | + SP->>UIP: documentUpdated(Document, State) |
| 136 | + end |
| 137 | + Note over UIP: Client can store State to restore the same state later |
| 138 | + end |
| 139 | +``` |
| 140 | + |
| 141 | +## Communication Layers |
| 142 | + |
| 143 | +A component that is created on the server side runs through a few steps before it is rendered on the client side: |
| 144 | + |
| 145 | +1. [Element](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/elements/Element.py) - The basis for all UI components. Generally, a [FunctionElement](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/elements/FunctionElement.py) created by a script using the [@ui.component](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/components/make_component.py) decorator that does not run the function until it is rendered. The result can change depending on the context that it is rendered in (e.g., what "state" is set). |
| 146 | +2. [ElementMessageStream](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/object_types/ElementMessageStream.py) - The `ElementMessageStream` is responsible for rendering one instance of an element in a specific rendering context and handling the server-client communication. The element is rendered to create a [RenderedNode](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/renderer/RenderedNode.py), which is an immutable representation of a rendered document. The `RenderedNode` is then encoded into JSON using [NodeEncoder](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/deephaven/ui/renderer/NodeEncoder.py), which pulls out all the non-serializable objects (such as Tables) and maps them to exported objects, and all the callables to be mapped to commands that JSON-RPC can accept. This is the final representation of the document sent to the client and ultimately handled by the `WidgetHandler`. |
| 147 | +3. [DashboardPlugin](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/js/src/DashboardPlugin.tsx) - Client-side `DashboardPlugin` that listens for when a widget of type `Element` is opened and manages the `WidgetHandler` instances that are created for each widget. |
| 148 | +4. [WidgetHandler](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/js/src/WidgetHandler.tsx) - Uses JSON-RPC communication with an `ElementMessageStream` instance to set the initial state, then load the initial rendered document and associated exported objects. Listens for any changes and updates the document accordingly. |
| 149 | +5. [DocumentHandler](https://github.com/deephaven/deephaven-plugins/blob/main/plugins/ui/src/js/src/DocumentHandler.tsx) - Handles the root of a rendered document, laying out the appropriate panels or dashboard specified. |
0 commit comments