Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document custom home view #21066

Merged
merged 3 commits into from
May 31, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,7 +193,7 @@ Starting with `branding`, the following subproperties are available:
`welcome.html` that ships with Element will be used instead.
2. `home_url`: A URL to an HTML page to show within the app as the "home" page. When the app doesn't have a room/screen to
show the user, it will use the home page instead. The home page is additionally accessible from the user menu. By default,
no home page is set and therefore a hardcoded landing screen is used.
no home page is set and therefore a hardcoded landing screen is used. More documentation and examples are [here](./custom-home.md).
3. `login_for_welcome`: When `true` (default `false`), the app will use the login form as a welcome page instead of the welcome
page itself. This disables use of `welcome_url` and all welcome page functionality.

Expand Down
65 changes: 65 additions & 0 deletions docs/custom-home.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Custom Home Page

The home page is shown whenever the user is logged in, but no room is selected.
A custom `home.html` replacing the default home page can be configured either in `.well-known/matrix/client` or `config.json`.
Such a custom home page can be used to communicate helpful information and important rules to the users.

## Configuration

To provide a custom home page for all element-web/desktop users of a homeserver, include the following in `.well-known/matrix/client`:

```
{
"io.element.embedded_pages": {
"home_url": "https://example.org/home.html"
}
}
```

The home page can be overridden in `config.json` to provide all users of an element-web installation with the same experience:

```
{
"embeddedPages": {
"homeUrl": "https://example.org/home.html"
}
}
```


## `home.html` Example

The following is a simple example for a custom `home.html`:

```
<style type="text/css">
.tos {
width: auto;
color: black;
background : #ffcccb;
font-weight: bold;
}
</style>

<h1>The example.org Matrix Server</h1>

<div class="tos">
<p>Behave appropriately.</p>
</div>

<h2>Start Chatting</h2>
<ul>
<li><a href="#/dm">Send a Direct Message</a></li>
<li><a href="#/directory">Explore Public Rooms</a></li>
<li><a href="#/new">Create a Group Chat</a></li>
</ul>
```

When choosing colors, be aware that the home page may be displayed in either light or dark mode.

It may be needed to set CORS headers for the `home.html` to enable element-desktop to fetch it, with e.g., the following nginx config:

```
add_header Access-Control-Allow-Origin *;
```