docs: layout overview #1120
docs: layout overview #1120
Conversation
|
ui docs preview (Available for 14 days) |
|
ui docs preview (Available for 14 days) |
| - [`panel`](../components/panel.md) is a `flex` container that is presented as individual tabs that can be moved to different positions by dragging the tabs. | ||
| - [`dashboard`](../components/dashboard.md) is a page layout that arranges a collection of `panels` if rows, columns, and stacks. |
There was a problem hiding this comment.
panel and dashboard should perhaps appear in a separate list...
This is something I think we struggle with due to our limitations with golden-layout, and I have difficulty explaining it concisely. Basically you can't nest a panel within a panel, or a dashboard within a panel; but you can nest a flex in a grid and vice-versa.
So saying panel is a flex container I think is a little misleading. It has a flex container inside it as the default layout, but the panel itself does not behave like a flex (in that you wouldn't be able to nest a panel within a flex, for example.
Some thoughts:
- I think ultimately what it comes down to - when you're laying out a dashboard, is when you would use
panel,row, andcolumn. When you're laying out a component, you should useflex,grid. - Differentiating between a dashboard and a component...
- Dashboard is comprised of panels and stacks of panels, which the user can re-arrange. Panels cannot nest within other panels, dashboards cannot nest within other dashboards or panels.
- A component layout does not allow for the user to re-size/re-arrange the layout.
There was a problem hiding this comment.
Made some changes. Tried to convey the difference. I ended up calling dashboards and panels "containers", but I am not sure if this is a good name.
| @ui.component | ||
| def ui_panel(): | ||
| text = ui.text_field() | ||
|
|
||
| return ui.panel(text, title="Text Field") | ||
|
|
||
|
|
||
| my_panel = ui_panel() |
There was a problem hiding this comment.
I think I'd steer away from these examples, where we're returning a panel from within a component... I know we do it in a few places, and it works, but by returning a panel from a component, that component can no longer be nested within other components - it can only be used within a dashboard; which means that you can't just "re-use" any component. I also find it slightly confusing when a component just returns/opens multiple panels - there's no visual boundary to that "component".
Pretty much I would just encourage using panel like you are in the example below, within a dashboard.
| ## View | ||
|
|
||
| The [`view`](../components/view.md) component is a general purpose container with no specific semantics that can be used for custom styling purposes. It supports Deephaven UI style props to ensure consistency with other components and is analogous to an HTML `<div>`. | ||
|
|
||
| ```python | ||
| from deephaven import ui | ||
|
|
||
| view = ui.view( | ||
| ui.text_field(label="Name"), | ||
| border_width="thin", | ||
| border_color="accent-400", | ||
| background_color="seafoam-500", | ||
| border_radius="medium", | ||
| padding="size-250", | ||
| ) |
There was a problem hiding this comment.
Group this with flex and grid.
We should show an example with scrolling as well (overflow set).
Co-authored-by: Mike Bender <[email protected]>
|
ui docs preview (Available for 14 days) |
|
ui docs preview (Available for 14 days) |
| ## Containers | ||
|
|
||
| - [`dashboard`](../components/dashboard.md) is a full page top level container comprised of panels and stacks of panels, which the user can re-arrange. Dashboards cannot nest within other dashboards or panels. | ||
| - [`panel`](../components/panel.md) is a container that is presented as individual tabs in a `dashboard` that can be moved to different positions by dragging the tabs. A `panel` contains components and arranges them using layouts. Panels cannot nest within other panels. | ||
|
|
||
| ## Dashboard | ||
|
|
||
| The [`dashboard`](../components/dashboard.md) component allows you to create a page layout containing a collection of components. The user can move and resize panels within the dashboard. |
There was a problem hiding this comment.
I'd combine these two sections... not sure we really need the Containers section above.
| - **Row**: A container used to group elements horizontally. Each element is placed to the right of the previous one. | ||
| - **Column**: A container used to group elements vertically. Each element is placed below the previous one. | ||
| - **Stack**: A container used to group elements into a stack of tabs. Each element gets its own tab, with only one element visible at a time. | ||
| - **Panel**: A container used to group and label elements. |
There was a problem hiding this comment.
I'd add the links for each of these, to the API doc page for them, e.g. https://salmon.deephaven.io/core/ui/docs/components/dashboard/#row-api-reference
Co-authored-by: margaretkennedy <[email protected]>
|
ui docs preview (Available for 14 days) |
1 similar comment
|
ui docs preview (Available for 14 days) |
|
ui docs preview (Available for 14 days) |
https://deephaven.atlassian.net/browse/DOC-469