mirror of
https://github.com/vector-im/element-web.git
synced 2024-11-27 02:48:39 +08:00
c05c429803
Co-authored-by: github-merge-queue <118344674+github-merge-queue@users.noreply.github.com> Co-authored-by: github-merge-queue <github-merge-queue@users.noreply.github.com> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: Florian Duros <florian.duros@ormaz.fr> Co-authored-by: Kim Brose <kim.brose@nordeck.net> Co-authored-by: Florian Duros <florianduros@element.io> Co-authored-by: R Midhun Suresh <hi@midhun.dev> Co-authored-by: dbkr <986903+dbkr@users.noreply.github.com> Co-authored-by: ElementRobot <releases@riot.im> Co-authored-by: dbkr <dbkr@users.noreply.github.com> Co-authored-by: David Baker <dbkr@users.noreply.github.com> Co-authored-by: Michael Telatynski <7t3chguy@gmail.com> Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Co-authored-by: David Langley <davidl@element.io> Co-authored-by: Michael Weimann <michaelw@matrix.org> Co-authored-by: Timshel <Timshel@users.noreply.github.com> Co-authored-by: Sahil Silare <32628578+sahil9001@users.noreply.github.com> Co-authored-by: Will Hunt <will@half-shot.uk> Co-authored-by: Hubert Chathi <hubert@uhoreg.ca> Co-authored-by: Andrew Ferrazzutti <andrewf@element.io> Co-authored-by: Robin <robin@robin.town> Co-authored-by: Tulir Asokan <tulir@maunium.net>
62 lines
2.8 KiB
Markdown
62 lines
2.8 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 fewer 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 (placed into the `right` container). 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 widgets will attempt to scale to relative proportions when more than
|
|
100% space is allocated. For example, if 3 widgets are defined at 40% width each then the client will
|
|
attempt to show them at 33% width each.
|
|
|
|
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.
|