62 lines
2.9 KiB
Markdown
62 lines
2.9 KiB
Markdown
|
# Widget layout support
|
||
|
|
|
||
|
|
Rooms can have a default widget layout to auto-pin certain widgets, make the container different
|
||
|
|
sizes, etc. These are defined through the `io.element.widgets.layout` state event (empty state key).
|
||
|
|
|
||
|
|
Full example content:
|
||
|
|
```json5
|
||
|
|
{
|
||
|
|
"widgets": {
|
||
|
|
"first-widget-id": {
|
||
|
|
"container": "top",
|
||
|
|
"index": 0,
|
||
|
|
"width": 60,
|
||
|
|
"height": 40
|
||
|
|
},
|
||
|
|
"second-widget-id": {
|
||
|
|
"container": "right"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
As shown, there are two containers possible for widgets. These containers have different behaviour
|
||
|
|
and interpret the other options differently.
|
||
|
|
|
||
|
|
## `top` container
|
||
|
|
|
||
|
|
This is the "App Drawer" or any pinned widgets in a room. This is by far the most versatile container
|
||
|
|
though does introduce potential usability issues upon members of the room (widgets take up space and
|
||
|
|
therefore less messages can be shown).
|
||
|
|
|
||
|
|
The `index` for a widget determines which order the widgets show up in from left to right. Widgets
|
||
|
|
without an `index` will show up as the rightmost widgets. Tiebreaks (same `index` or multiple defined
|
||
|
|
without an `index`) are resolved by comparing widget IDs. A maximum of 3 widgets can be in the top
|
||
|
|
container - any which exceed this will be ignored. Smaller numbers represent leftmost widgets.
|
||
|
|
|
||
|
|
The `width` is relative width within the container in percentage points. This will be clamped to a
|
||
|
|
range of 0-100 (inclusive). The rightmost widget will have its percentage adjusted to fill the
|
||
|
|
container appropriately, shrinking and growing if required. For example, if three widgets are in the
|
||
|
|
top container at 40% width each then the 3rd widget will be shrunk to 20% because 120% > 100%.
|
||
|
|
Similarly, if all three widgets were set to 10% width each then the 3rd widget would grow to be 80%.
|
||
|
|
|
||
|
|
Note that the client may impose minimum widths on the widgets, such as a 10% minimum to avoid pinning
|
||
|
|
hidden widgets. In general, widgets defined in the 30-70% range each will be free of these restrictions.
|
||
|
|
|
||
|
|
The `height` is not in fact applied per-widget but is recorded per-widget for potential future
|
||
|
|
capabilities in future containers. The top container will take the tallest `height` and use that for
|
||
|
|
the height of the whole container, and thus all widgets in that container. The `height` is relative
|
||
|
|
to the container, like with `width`, meaning that 100% will consume as much space as the client is
|
||
|
|
willing to sacrifice to the widget container. Like with `width`, the client may impose minimums to avoid
|
||
|
|
the container being uselessly small. Heights in the 30-100% range are generally acceptable. The height
|
||
|
|
is also clamped to be within 0-100, inclusive.
|
||
|
|
|
||
|
|
## `right` container
|
||
|
|
|
||
|
|
This is the default container and has no special configuration. Widgets which overflow from the top
|
||
|
|
container will be put in this container instead. Putting a widget in the right container does not
|
||
|
|
automatically show it - it only mentions that widgets should not be in another container.
|
||
|
|
|
||
|
|
The behaviour of this container may change in the future.
|
||
|
|
|