nikrozman/element-web
1
0
Fork 0
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge branch 'develop' into travis/inline-widgets

Browse Source
This commit is contained in:
Travis Ralston
2021-03-15 16:37:40 -06:00
parent b06de25898 ba28c6d57a
commit e13cb66e32
262 changed files with 12056 additions and 9954 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
docs/app-load.md Normal file
View File

@@ -0,0 +1,81 @@
# App load order
Old slow flow:
![image](https://user-images.githubusercontent.com/2403652/73848963-00a2a080-4821-11ea-97d4-1200fc2638f3.png)
Current more parallel flow:
![image](https://user-images.githubusercontent.com/2403652/83146440-303a2900-a0ee-11ea-806b-4f53f039b957.png)
<details><summary>Code</summary>
<p>
<pre><code>
digraph G {
node [shape=box];
subgraph cluster_0 {
color=orange;
node [style=filled];
label = "index.ts";
entrypoint, s0, ready [shape=point];
rageshake, config, i18n, theme, skin, olm [shape=parallelogram];
mobile [shape=diamond, label="mobile"];
modernizr [shape=diamond];
redirect, incompatible [shape=egg];
entrypoint -> rageshake;
rageshake -> mobile [color=blue];
mobile -> s0 [label="No"];
mobile -> redirect [label="Yes"];
s0 -> platform;
s0 -> olm;
platform -> config;
config -> i18n [color=blue];
config -> theme [color=blue];
config -> skin [color=blue];
i18n -> modernizr [color=blue];
theme -> modernizr [color=blue];
skin -> modernizr [color=blue];
modernizr -> ready [label="Yes"];
modernizr -> incompatible [label="No"];
incompatible -> ready [label="user ignore"];
olm -> ready [color=red];
config -> ready [color=red];
skin -> ready [color=red];
theme -> ready [color=red];
i18n -> ready [color=red];
}
subgraph cluster_1 {
color = green;
node [style=filled];
label = "init.tsx";
ready -> loadApp;
loadApp -> matrixchat;
}
}
</code></pre>
</p>
</details>
Key:
+ Parallelogram: async/await task
+ Box: sync task
+ Diamond: conditional branch
+ Egg: user interaction
+ Blue arrow: async task is allowed to settle but allowed to fail
+ Red arrow: async task success is asserted
Notes:
+ A task begins when all its dependencies (arrows going into it) are fulfilled.
+ The success of setting up rageshake is never asserted, element-web has a fallback path for running without IDB (and thus rageshake).
+ Everything is awaited to be settled before the Modernizr check, to allow it to make use of things like i18n if they are successful.
Underlying dependencies:
![image](https://user-images.githubusercontent.com/2403652/73848977-08624500-4821-11ea-9830-bb0317c41086.png)

52
docs/conferencing.md
View File

@@ -1,52 +0,0 @@
# VoIP Conferencing
This is a draft proposal for a naive voice/video conferencing implementation for
Matrix clients. There are many possible conferencing architectures possible for
Matrix (Multipoint Conferencing Unit (MCU); Stream Forwarding Unit (SFU); Peer-
to-Peer mesh (P2P), etc; events shared in the group room; events shared 1:1;
possibly even out-of-band signalling).
This is a starting point for a naive MCU implementation which could provide one
possible Matrix-wide solution in future, which retains backwards compatibility
with standard 1:1 calling.
* A client chooses to initiate a conference for a given room by starting a
voice or video call with a 'conference focus' user. This is a virtual user
(typically Application Service) which implements a conferencing bridge. It
isn't defined how the client discovers or selects this user.
* The conference focus user MUST join the room in which the client has
initiated the conference - this may require the client to invite the
conference focus user to the room, depending on the room's `join_rules`. The
conference focus user needs to be in the room to let the bridge eject users
from the conference who have left the room in which it was initiated, and aid
discovery of the conference by other users in the room. The bridge
identifies the room to join based on the user ID by which it was invited.
The format of this identifier is implementation dependent for now.
* If a client leaves the group chat room, they MUST be ejected from the
conference. If a client leaves the 1:1 room with the conference focus user,
they SHOULD be ejected from the conference.
* For now, rooms can contain multiple conference focus users - it's left to
user or client implementation to select which to converge on. In future this
could be mediated using a state event (e.g. `im.vector.call.mcu`), but we
can't do that right now as by default normal users can't set arbitrary state
events on a room.
* To participate in the conference, other clients initiates a standard 1:1
voice or video call to the conference focus user.
* For best UX, clients SHOULD show the ongoing voice/video call in the UI
context of the group room rather than 1:1 with the focus user. If a client
recognises a conference user present in the room, it MAY chose to highlight
this in the UI (e.g. with a "conference ongoing" notification, to aid
discovery). Clients MAY hide the 1:1 room with the focus user (although in
future this room could be used for floor control or other direct
communication with the conference focus)
* When all users have left the conference, the 'conference focus' user SHOULD
leave the room.
* If a conference focus user joins a room but does not receive a 1:1 voice or
video call, it SHOULD time out after a period of time and leave the room.

136
docs/config.md
View File

@@ -4,13 +4,13 @@ Configuration
You can configure the app by copying `config.sample.json` to
`config.json` and customising it:
For a good example, see https://riot.im/develop/config.json.
For a good example, see https://develop.element.io/config.json.
1. `default_server_config` sets the default homeserver and identity server URL for
Riot to use. The object is the same as returned by [https://<server_name>/.well-known/matrix/client](https://matrix.org/docs/spec/client_server/latest.html#get-well-known-matrix-client),
Element to use. The object is the same as returned by [https://<server_name>/.well-known/matrix/client](https://matrix.org/docs/spec/client_server/latest.html#get-well-known-matrix-client),
with added support for a `server_name` under the `m.homeserver` section to display
a custom homeserver name. Alternatively, the config can contain a `default_server_name`
instead which is where Riot will go to get that same object, although this option is
instead which is where Element will go to get that same object, although this option is
deprecated - see the `.well-known` link above for more information on using this option.
Note that the `default_server_name` is used to get a complete server configuration
whereas the `server_name` in the `default_server_config` is for display purposes only.
@@ -18,21 +18,21 @@ For a good example, see https://riot.im/develop/config.json.
`default_is_url`, however these are deprecated. They are maintained for backwards
compatibility with older configurations. `default_is_url` is respected only
if `default_hs_url` is used.
* Riot will fail to load if a mix of `default_server_config`, `default_server_name`, or
* Element will fail to load if a mix of `default_server_config`, `default_server_name`, or
`default_hs_url` is specified. When multiple sources are specified, it is unclear
which should take priority and therefore the application cannot continue.
* As of Riot 1.4.0, identity servers are optional. See [Identity servers](#identity-servers) below.
1. `features`: Lookup of optional features that may be `enable`d, `disable`d, or
exposed to the user in the `labs` section of settings. The available
optional experimental features vary from release to release and are [documented](labs.md). The feature flag process is
[documented](feature-flags.md) as well.
1. `showLabsSettings`: Shows the "labs" tab of user settings even when no `features` are enabled
or present. Useful for getting at settings which may be otherwise hidden.
* As of Element 1.4.0, identity servers are optional. See [Identity servers](#identity-servers) below.
1. `features`: Lookup of optional features that may be force-enabled (`true`) or force-disabled (`false`).
When features are not listed here, their defaults will be used, and users can turn them on/off if `showLabsSettings`
allows them to. The available optional experimental features vary from release to release and are
[documented](labs.md). The feature flag process is [documented](feature-flags.md) as well.
1. `showLabsSettings`: Shows the "labs" tab of user settings. Useful to allow users to turn on experimental features
they might not otherwise have access to.
1. `brand`: String to pass to your homeserver when configuring email notifications, to let the
homeserver know what email template to use when talking to you.
1. `branding`: Configures various branding and logo details, such as:
1. `welcomeBackgroundUrl`: An image to use as a wallpaper outside the app
during authentication flows
during authentication flows. If an array is passed, an image is chosen randomly for each visit.
1. `authHeaderLogoUrl`: An logo image that is shown in the header during
authentication flows
1. `authFooterLinks`: a list of links to show in the authentication page footer:
@@ -42,13 +42,13 @@ For a good example, see https://riot.im/develop/config.json.
1. `adminMessageMD`: An extra message to show on the reporting dialog to
mention homeserver-specific policies. Accepts Markdown.
1. `integrations_ui_url`: URL to the web interface for the integrations server. The integrations
server is not Riot and normally not your homeserver either. The integration server settings
server is not Element and normally not your homeserver either. The integration server settings
may be left blank to disable integrations.
1. `integrations_rest_url`: URL to the REST interface for the integrations server.
1. `integrations_widgets_urls`: list of URLs to the REST interface for the widget integrations server.
1. `bug_report_endpoint_url`: endpoint to send bug reports to (must be running a
https://github.com/matrix-org/rageshake server). Bug reports are sent when a user clicks
"Send Logs" within the application. Bug reports can be disabled by leaving the
"Send Logs" within the application. Bug reports can be disabled/hidden by leaving the
`bug_report_endpoint_url` out of your config file.
1. `roomDirectory`: config for the public room directory. This section is optional.
1. `roomDirectory.servers`: List of other homeservers' directories to include in the drop
@@ -65,10 +65,10 @@ For a good example, see https://riot.im/develop/config.json.
1. `whitelistedISUrls`: a list of IS URLs to not redact from the analytics
1. `siteId`: The Piwik Site ID to use when sending analytics to the Piwik server configured above
1. `welcomeUserId`: the user ID of a bot to invite whenever users register that can give them a tour
1. `embeddedPages`: Configures the pages displayed in portions of Riot that
1. `embeddedPages`: Configures the pages displayed in portions of Element that
embed static files, such as:
1. `welcomeUrl`: Initial content shown on the outside of the app when not
logged in. Defaults to `welcome.html` supplied with Riot.
logged in. Defaults to `welcome.html` supplied with Element.
1. `homeUrl`: Content shown on the inside of the app when a specific room is
not selected. By default, no home page is configured. If one is set, a
button to access it will be shown in the top left menu.
@@ -80,20 +80,52 @@ For a good example, see https://riot.im/develop/config.json.
is special cased to the `default_theme` in the config file).
1. `disable_custom_urls`: disallow the user to change the
default homeserver when signing up or logging in.
1. `permalinkPrefix`: Used to change the URL that Riot generates permalinks with.
1. `permalinkPrefix`: Used to change the URL that Element generates permalinks with.
By default, this is "https://matrix.to" to generate matrix.to (spec) permalinks.
Set this to your Riot instance URL if you run an unfederated server (eg:
"https://riot.example.org").
Set this to your Element instance URL if you run an unfederated server (eg:
"https://element.example.org").
1. `jitsi`: Used to change the default conference options. Learn more about the
Jitsi options at [jitsi.md](./jitsi.md).
1. `preferredDomain`: The domain name of the preferred Jitsi instance. Defaults
to `jitsi.riot.im`. This is used whenever a user clicks on the voice/video
call buttons - integration managers may use a different domain.
1. `enable_presence_by_hs_url`: The property key should be the URL of the homeserver
and its value defines whether to enable/disable the presence status display
from that homeserver. If no options are configured, presence is shown for all
homeservers.
1. `disable_guests`: Disables guest access tokens and auto-guest registrations.
Defaults to false (guests are allowed).
1. `disable_login_language_selector`: Disables the login language selector. Defaults
to false (language selector is shown).
1. `disable_3pid_login`: Disables 3rd party identity options on login and registration form
Defaults to false (3rd party identity options are shown).
1. `default_federate`: Default option for room federation when creating a room
Defaults to true (room federation enabled).
1. `desktopBuilds`: Used to alter promotional links to the desktop app. By default
the builds are considered available and accessible from https://element.io. This
config option is typically used in the context of encouraging encrypted message
search capabilities (Seshat). All the options listed below are required if this
option is specified.
1. `available`: When false, the desktop app will not be promoted to the user.
1. `logo`: An HTTP URL to the avatar for the desktop build. Should be 24x24, ideally
an SVG.
1. `url`: An HTTP URL for where to send the user to download the desktop build.
1. `mobileGuideToast`: Whether to show a toast a startup which nudges users on
iOS and Android towards the native mobile apps. The toast redirects to the
mobile guide if they accept. Defaults to false.
1. `audioStreamUrl`: If supplied, show an option on Jitsi widgets to stream
audio using Jitsi's live streaming feature. This option is experimental and
may be removed at any time without notice.
Note that `index.html` also has an og:image meta tag that is set to an image
hosted on riot.im. This is the image used if links to your copy of Riot
appear in some websites like Facebook, and indeed Riot itself. This has to be
hosted on riot.im. This is the image used if links to your copy of Element
appear in some websites like Facebook, and indeed Element itself. This has to be
static in the HTML and an absolute URL (and HTTP rather than HTTPS), so it's
not possible for this to be an option in config.json. If you'd like to change
it, you can build Riot, but run
it, you can build Element, but run
`RIOT_OG_IMAGE_URL="http://example.com/logo.png" yarn build`.
Alternatively, you can edit the `og:image` meta tag in `index.html` directly
each time you download a new version of Riot.
each time you download a new version of Element.
Identity servers
================
@@ -102,10 +134,10 @@ The identity server is used for inviting other users to a room via third party
identifiers like emails and phone numbers. It is not used to store your password
or account information.
As of Riot 1.4.0, all identity server functions are optional and you are
As of Element 1.4.0, all identity server functions are optional and you are
prompted to agree to terms before data is sent to the identity server.
Riot will check multiple sources when looking for an identity server to use in
Element will check multiple sources when looking for an identity server to use in
the following order of preference:
1. The identity server set in the user's account data
@@ -115,28 +147,56 @@ the following order of preference:
login
3. The identity server provided by the Riot config file
If none of these sources have an identity server set, then Riot will prompt the
If none of these sources have an identity server set, then Element will prompt the
user to set an identity server first when attempting to use features that
require one.
Currently the only two public identity servers are https://vector.im and
Currently, the only two public identity servers are https://vector.im and
https://matrix.org, however in the future identity servers will be
decentralised.
Desktop app configuration
=========================
To run multiple instances of the desktop app for different accounts, you can
launch the executable with the `--profile` argument followed by a unique
identifier, e.g `riot-web --profile Work` for it to run a separate profile and
not interfere with the default one.
See https://github.com/vector-im/element-desktop#user-specified-configjson
Alternatively, a custom location for the profile data can be specified using the
`--profile-dir` flag followed by the desired path.
UI Features
===========
+ `%APPDATA%\$NAME\config.json` on Windows
+ `$XDG_CONFIG_HOME\$NAME\config.json` or `~/.config/$NAME/config.json` on Linux
+ `~Library/Application Support/$NAME/config.json` on macOS
Parts of the UI can be disabled using UI features. These are settings which appear
under `settingDefaults` and can only be `true` (default) or `false`. When `false`,
parts of the UI relating to that feature will be disabled regardless of the user's
preferences.
In the paths above, `$NAME` is typically `Riot`, unless you use `--profile
$PROFILE` in which case it becomes `Riot-$PROFILE`.
Currently, the following UI feature flags are supported:
* `UIFeature.urlPreviews` - Whether URL previews are enabled across the entire application.
* `UIFeature.feedback` - Whether prompts to supply feedback are shown.
* `UIFeature.voip` - Whether or not VoIP is shown readily to the user. When disabled,
Jitsi widgets will still work though they cannot easily be added.
* `UIFeature.widgets` - Whether or not widgets will be shown.
* `UIFeature.flair` - Whether or not community flair is shown in rooms.
* `UIFeature.communities` - Whether or not to show any UI related to communities. Implicitly
disables `UIFeature.flair` when disabled.
* `UIFeature.advancedSettings` - Whether or not sections titled "advanced" in room and
user settings are shown to the user.
* `UIFeature.shareQrCode` - Whether or not the QR code on the share room/event dialog
is shown.
* `UIFeature.shareSocial` - Whether or not the social icons on the share room/event dialog
are shown.
* `UIFeature.identityServer` - Whether or not functionality requiring an identity server
is shown. When disabled, the user will not be able to interact with the identity
server (sharing email addresses, 3PID invites, etc).
* `UIFeature.thirdPartyId` - Whether or not UI relating to third party identifiers (3PIDs)
is shown. Typically this is considered "contact information" on the homeserver, and is
not directly related to the identity server.
* `UIFeature.registration` - Whether or not the registration page is accessible. Typically
useful if accounts are managed externally.
* `UIFeature.passwordReset` - Whether or not the password reset page is accessible. Typically
useful if accounts are managed externally.
* `UIFeature.deactivate` - Whether or not the deactivate account button is accessible. Typically
useful if accounts are managed externally.
* `UIFeature.advancedEncryption` - Whether or not advanced encryption options are shown to the
user.
* `UIFeature.roomHistorySettings` - Whether or not the room history settings are shown to the user.
This should only be used if the room history visibility options are managed by the server.

34
docs/customisations.md Normal file
View File

@@ -0,0 +1,34 @@
# Customisations
Element Web and the React SDK support "customisation points" that can be used to
easily add custom logic specific to a particular deployment of Element Web.
An example of this is the [security customisations
module](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/customisations/Security.ts).
This module in the React SDK only defines some empty functions and their types:
it does not do anything by default.
To make use of these customisation points, you will first need to fork Element
Web so that you can add your own code. Even though the default module is part of
the React SDK, you can still override it from the Element Web layer:
1. Copy the default customisation module to
`element-web/src/customisations/YourNameSecurity.ts`
2. Edit customisations points and make sure export the ones you actually want to
activate
3. Tweak the Element build process to use the customised module instead of the
default by adding this to the `additionalPlugins` array in `webpack.config.js`:
```js
new webpack.NormalModuleReplacementPlugin(
/src[\/\\]customisations[\/\\]Security\.ts/,
path.resolve(__dirname, 'src/customisations/YourNameSecurity.ts'),
),
```
If we add more customisation modules in the future, we'll likely improve these
steps to remove the need for build changes like the above.
By isolating customisations to their own module, this approach should remove the
chance of merge conflicts when updating your fork, and thus simplify ongoing
maintenance.

63
docs/e2ee.md Normal file
View File

@@ -0,0 +1,63 @@
# End to end encryption by default
By default, Element will create encrypted DM rooms if the user you are chatting with has keys uploaded on their account.
For private room creation, Element will default to encryption on but give you the choice to opt-out.
## Disabling encryption by default
Set the following on your homeserver's
`/.well-known/matrix/client` config:
```json
{
"io.element.e2ee": {
"default": false
}
}
```
# Secure backup
By default, Element strongly encourages (but does not require) users to set up
Secure Backup so that cross-signing identity key and message keys can be
recovered in case of a disaster where you lose access to all active devices.
## Requiring secure backup
To require Secure Backup to be configured before Element can be used, set the
following on your homeserver's `/.well-known/matrix/client` config:
```json
{
"io.element.e2ee": {
"secure_backup_required": true
}
}
```
## Preferring setup methods
By default, Element offers users a choice of a random key or user-chosen
passphrase when setting up Secure Backup. If a homeserver admin would like to
only offer one of these, you can signal this via the
`/.well-known/matrix/client` config, for example:
```json
{
"io.element.e2ee": {
"secure_backup_setup_methods": ["passphrase"]
}
}
```
The field `secure_backup_setup_methods` is an array listing the methods the
client should display. Supported values currently include `key` and
`passphrase`. If the `secure_backup_setup_methods` field is not present or
exists but does not contain any supported methods, Element will fallback to the
default value of: `["key", "passphrase"]`.
# Compatibility
The settings above were first proposed under a `im.vector.riot.e2ee` key, which
is now deprecated. Element will check for either key, preferring
`io.element.e2ee` if both exist.

85
docs/feature-flags.md
View File

@@ -1,6 +1,6 @@
# Feature flags
When developing new features for Riot, we use feature flags to give us more
When developing new features for Element, we use feature flags to give us more
flexibility and control over when and where those features are enabled.
For example, flags make the following things possible:
@@ -8,7 +8,7 @@ For example, flags make the following things possible:
* Extended testing of a feature via labs on develop
* Enabling features when ready instead of the first moment the code is released
* Testing a feature with a specific set of users (by enabling only on a specific
Riot instance)
Element instance)
The size of the feature controlled by a feature flag may vary widely: it could
be a large project like reactions or a smaller change to an existing algorithm.
@@ -35,7 +35,7 @@ clients commit to doing the associated clean up work once a feature stabilises.
When starting work on a feature, we should create a matching feature flag:
1. Add a new
[setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.js)
[setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.ts)
of the form:
```js
"feature_cats": {
@@ -47,66 +47,61 @@ When starting work on a feature, we should create a matching feature flag:
```
2. Check whether the feature is enabled as appropriate:
```js
SettingsStore.isFeatureEnabled("feature_cats")
SettingsStore.getValue("feature_cats")
```
3. Add the feature to the [set of labs on develop](https://github.com/vector-im/riot-web/blob/develop/riot.im/develop/config.json):
```json
"features": {
"feature_cats": "labs"
},
```
4. Document the feature in the [labs documentation](https://github.com/vector-im/riot-web/blob/develop/docs/labs.md)
3. Document the feature in the [labs documentation](https://github.com/vector-im/element-web/blob/develop/docs/labs.md)
With these steps completed, the feature is disabled by default, but can be
enabled on develop by interested users for testing.
enabled on develop and nightly by interested users for testing.
Different features may have different deployment plans for when to enable where.
The following lists a few common options.
## Enabling by default on develop
## Enabling by default on develop and nightly
Set the feature to `enable` in the [develop config](https://github.com/vector-im/riot-web/blob/develop/riot.im/develop/config.json):
Set the feature to `true` in the
[develop](https://github.com/vector-im/element-web/blob/develop/element.io/develop/config.json)
and
[nightly](https://github.com/vector-im/element-desktop/blob/develop/element.io/nightly/config.json)
configs:
```json
"features": {
"feature_cats": "enable"
"feature_cats": true
},
```
## Enabling by default on staging and app
## Enabling by default on staging, app, and release
Set the feature to `enable` in the [app
config](https://github.com/vector-im/riot-web/blob/develop/riot.im/app/config.json).
Set the feature to `true` in the
[staging / app](https://github.com/vector-im/element-web/blob/develop/element.io/app/config.json)
and
[release](https://github.com/vector-im/element-desktop/blob/develop/element.io/release/config.json)
configs.
**Note:** The above will only enable the feature for https://app.element.io and official Element
Desktop builds. It will not be enabled for self-hosted installed, custom desktop builds, etc. To
cover these cases, change the setting's `default` in `Settings.ts` to `true`.
## Feature deployed successfully
Once we're confident that a feature is working well, we should remove the flag:
Once we're confident that a feature is working well, we should remove or convert the flag.
1. Remove the [setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.js)
2. Remove all `isFeatureEnabled` lines that test for the feature's setting
3. Remove the feature from the [labs documentation](https://github.com/vector-im/riot-web/blob/develop/docs/labs.md)
4. Remove feature state from
[develop](https://github.com/vector-im/riot-web/blob/develop/riot.im/develop/config.json)
and [app](https://github.com/vector-im/riot-web/blob/develop/riot.im/app/config.json)
If the feature is meant to be turned off/on by the user:
1. Remove `isFeature` from the [setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.ts)
2. Change the `default` to `true` (if desired).
3. Remove the feature from the [labs documentation](https://github.com/vector-im/element-web/blob/develop/docs/labs.md)
4. Celebrate! 🥳
If the feature is meant to be forced on (non-configurable):
1. Remove the [setting](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.ts)
2. Remove all `getValue` lines that test for the feature.
3. Remove the feature from the [labs documentation](https://github.com/vector-im/element-web/blob/develop/docs/labs.md)
4. If applicable, remove the feature state from
[develop](https://github.com/vector-im/element-web/blob/develop/element.io/develop/config.json),
[nightly](https://github.com/vector-im/element-desktop/blob/develop/element.io/nightly/config.json),
[staging / app](https://github.com/vector-im/element-web/blob/develop/element.io/app/config.json),
and
[release](https://github.com/vector-im/element-desktop/blob/develop/element.io/release/config.json)
configs
5. Celebrate! 🥳
## Convert to a regular setting (optional)
Sometimes we decide a feature should always be user-controllable as a setting
even after it has been fully deployed. In that case, we would craft a new,
regular setting:
1. Remove the feature flag from
[settings](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/settings/Settings.js)
and add a regular setting with the appropriate levels for your feature
2. Replace the `isFeatureEnabled` lines with `getValue` or similar calls
according to the [settings
docs](https://github.com/matrix-org/matrix-react-sdk/blob/develop/docs/settings.md)
(checking carefully, as we may want a different mix of code paths when the
feature is always present but gated by a setting)
3. Remove the feature from the [labs documentation](https://github.com/vector-im/riot-web/blob/develop/docs/labs.md)
4. Remove feature state from
[develop](https://github.com/vector-im/riot-web/blob/develop/riot.im/develop/config.json)
and [app](https://github.com/vector-im/riot-web/blob/develop/riot.im/app/config.json)
configs

BIN
docs/img/pr-checks.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 155 KiB

100
docs/jitsi-dev.md Normal file
View File

@@ -0,0 +1,100 @@
# Jitsi wrapper developer docs
*If you're looking for information on how to set up Jitsi in your Element, see
[jitsi.md](./jitsi.md) instead.*
These docs are for developers wondering how the different conference buttons work
within Element. If you're not a developer, you're probably looking for [jitsi.md](./jitsi.md).
## Brief introduction to widgets
Widgets are embedded web applications in a room, controlled through state events, and
have a `url` property. They are largely specified by [MSC1236](https://github.com/matrix-org/matrix-doc/issues/1236)
and have extensions proposed under [MSC1286](https://github.com/matrix-org/matrix-doc/issues/1286).
The `url` is typically something we shove into an iframe with sandboxing (see `AppTile`
in the react-sdk), though for some widgets special integration can be done. v2 widgets
have a `data` object which helps achieve that special integration, though v1 widgets
are best iframed and left alone.
Widgets have a `postMessage` API they can use to interact with Element, which also allows
Element to interact with them. Typically this is most used by the sticker picker (an
account-level widget), though widgets like the Jitsi widget will request permissions to
get 'stuck' into the room list during a conference.
Widgets can be added with the `/addwidget <url>` command.
## Brief introduction to integration managers
Integration managers (like Scalar and Dimension) are accessible via the 4 squares in
the top right of the room and provide a simple UI over top of bridges, bots, and other
stuff to plug into a room. They are a separate service to Element and are thus iframed
in a dialog as well. They also have a `postMessage` API they can use to interact with
the client to create things like widgets, give permissions to bridges, and generally
set everything up for the integration the user is working with.
Integration managers do not currently have a spec associated with them, though efforts
are underway in [MSC1286](https://github.com/matrix-org/matrix-doc/issues/1286).
## Widgets configured by integration managers
Integration managers will often "wrap" a widget by using a widget `url` which points
to the integration manager instead of to where the user requested the widget be. For
example, a custom widget added in an integration manager for https://matrix.org will
end up creating a widget with a URL like `https://integrations.example.org?widgetUrl=https%3A%2F%2Fmatrix.org`.
The integration manager's wrapper will typically have another iframe to isolate the
widget from the client by yet another layer. The wrapper often provides other functionality
which might not be available on the embedded site, such as a fullscreen button or the
communication layer with the client (all widgets *should* be talking to the client
over `postMessage`, even if they aren't going to be using the widget APIs).
Widgets added with the `/addwidget` command will *not* be wrapped as they are not going
through an integration manager. The widgets themselves *should* also work outside of
Element. Widgets currently have a "pop out" button which opens them in a new tab and
therefore have no connection back to Riot.
## Jitsi widgets from integration managers
Integration managers will create an entire widget event and send it over `postMessage`
for the client to add to the room. This means that the integration manager gets to
decide the conference domain, conference name, and other aspects of the widget. As
a result, users can end up with a Jitsi widget that does not use the same conference
server they specified in their config.json - this is expected.
Some integration managers allow the user to change the conference name while others
will generate one for the user.
## Jitsi widgets generated by Element itself
When the user clicks on the call buttons by the composer, the integration manager is
not involved in the slightest. Instead, Element itself generates a widget event, this time
using the config.json parameters, and publishes that to the room. If there's only two
people in the room, a plain WebRTC call is made instead of using a widget at all - these
are defined in the Matrix specification.
The Jitsi widget created by Element uses a local `jitsi.html` wrapper (or one hosted by
`https://app.element.io` for desktop users or those on non-https domains) as the widget
`url`. The wrapper has some basic functionality for talking to Element to ensure the
required `postMessage` calls are fulfilled.
**Note**: Per [jitsi.md](./jitsi.md) the `preferredDomain` can also come from the server's
client .well-known data.
## The Jitsi wrapper in Element
Whenever Element sees a Jitsi widget, it ditches the `url` and instead replaces it with
its local wrapper, much like what it would do when creating a widget. However, instead
of using one from [app.element.io](https://app.element.io), it will use one local to the client instead.
The wrapper is used to provide a consistent experience to users, as well as being faster
and less risky to load. The local wrapper URL is populated with the conference information
from the original widget (which could be a v1 or v2 widget) so the user joins the right
call.
Critically, when the widget URL is reconstructed it does *not* take into account the
config.json's `preferredDomain` for Jitsi. If it did this, users would end up on different
conference servers and therefore different calls entirely.
**Note**: Per [jitsi.md](./jitsi.md) the `preferredDomain` can also come from the server's
client .well-known data.

73
docs/jitsi.md Normal file
View File

@@ -0,0 +1,73 @@
# Jitsi in Element
Element uses [Jitsi](https://jitsi.org/) for conference calls, which provides options for
self-hosting your own server and supports most major platforms.
1:1 calls, or calls between you and one other person, do not use Jitsi. Instead, those
calls work directly between clients or via TURN servers configured on the respective
homeservers.
There's a number of ways to start a Jitsi call: the easiest way is to click on the
voice or video buttons near the message composer in a room with more than 2 people. This
will add a Jitsi widget which allows anyone in the room to join.
Integration managers (available through the 4 squares in the top right of the room) may
provide their own approaches for adding Jitsi widgets.
## Configuring Element to use your self-hosted Jitsi server
Element will use the Jitsi server that is embedded in the widget, even if it is not the
one you configured. This is because conference calls must be held on a single Jitsi
server and cannot be split over multiple servers.
However, you can configure Element to *start* a conference with your Jitsi server by adding
to your [config](./config.md) the following:
```json
{
"jitsi": {
"preferredDomain": "your.jitsi.example.org"
}
}
```
The default is `jitsi.riot.im` (a free service offered by Element), and the demo site for
Jitsi uses `meet.jit.si` (also free).
Once you've applied the config change, refresh Element and press the call button. This
should start a new conference on your Jitsi server.
**Note**: The widget URL will point to a `jitsi.html` page hosted by Element. The Jitsi
domain will appear later in the URL as a configuration parameter.
**Hint**: If you want everyone on your homeserver to use the same Jitsi server by
default, and you are using element-web 1.6 or newer, set the following on your homeserver's
`/.well-known/matrix/client` config:
```json
{
"im.vector.riot.jitsi": {
"preferredDomain": "your.jitsi.example.org"
}
}
```
## Element Android
Element Android (1.0.5+) supports custom Jitsi domains, similar to Element Web above.
1:1 calls, or calls between you and one other person, do not use Jitsi. Instead, those
calls work directly between clients or via TURN servers configured on the respective
homeservers.
For rooms with more than 2 joined members, when creating a Jitsi conference via call/video buttons of the toolbar (not via integration manager), Element Android will create a widget using the [wrapper](https://github.com/vector-im/element-web/blob/develop/docs/jitsi-dev.md) hosted on `app.element.io`.
The domain used is the one specified by the `/.well-known/matrix/client` endpoint, and if not present it uses the fallback defined in `config.xml` (jitsi.riot.im)
For active Jitsi widgets in the room, a native Jitsi widget UI is created and points to the instance specified in the `domain` key of the widget content data.
Element Android manages allowed native widgets permissions a bit differently than web widgets (as the data shared are different and never shared with the widget URL). For Jitsi widgets, permissions are requested only once per domain (consent saved in account data).
## Element iOS
Currently the Element mobile apps do not support custom Jitsi servers and will instead
use the default `jitsi.riot.im` server. When users on the mobile apps join the call,
they will be joining a different conference which has the same name, but not the same
participants. This is a known bug and which needs to be fixed.

70
docs/labs.md
View File

@@ -1,11 +1,28 @@
# Labs features
Some notes on the features you can enable by going to `Settings->Labs`. Not exhaustive, chat in
[#riot-web:matrix.org](https://matrix.to/#/#riot-web:matrix.org) for more information.
If Labs is enabled in the [Element config](config.md), you can enable some of these features by going
to `Settings->Labs`. This list is non-exhaustive and subject to change, chat in
[#element-web:matrix.org](https://matrix.to/#/#element-web:matrix.org) for more information.
**Be warned! Labs features are not finalised, they may be fragile, they may change, they may be
dropped. Ask in the room if you are unclear about any details here.**
## Matrix Spaces [MSC1772](https://github.com/matrix-org/matrix-doc/pull/1772) support (`feature_spaces`)
Enables showing, using, creating, and managing spaces. Create Spaces from the all new Space Panel (to left of Room List).
Incompatible with (will disable) `feature_custom_tags`, `feature_communities_v2_prototypes` and stable Communities/Groups support.
Still in heavy development.
## Render LaTeX maths in messages (`feature_latex_maths`)
Enables rendering of LaTeX maths in messages using [KaTeX](https://katex.org/). LaTeX between single dollar-signs is interpreted as inline maths and double dollar-signs as display maths (i.e. centred on its own line).
## New spinner design (`feature_new_spinner`)
Replaces the old spinner image with a new, svg-based one featuring a sleeker design.
## Message pinning (`feature_pinning`)
Allows you to pin messages in the room. To pin a message, use the 3 dots to the right of the message
@@ -21,7 +38,7 @@ your avatar next to the message composer.
An experimental approach for dealing with custom tags. Custom tags will appear in the bottom portion
of the community filter panel.
Setting custom tags is not supported by Riot.
Setting custom tags is not supported by Element.
## Render simple counters in room header (`feature_state_counters`)
@@ -48,7 +65,7 @@ That's it. Now should see your new counter under the header.
## Multiple integration managers (`feature_many_integration_managers`)
Exposes a way to access all the integration managers known to Riot. This is an implementation of [MSC1957](https://github.com/matrix-org/matrix-doc/pull/1957).
Exposes a way to access all the integration managers known to Element. This is an implementation of [MSC1957](https://github.com/matrix-org/matrix-doc/pull/1957).
## New ways to ignore people (`feature_mjolnir`)
@@ -73,21 +90,8 @@ An implementation of [MSC2241](https://github.com/matrix-org/matrix-doc/pull/224
This also includes a new implementation of the user & member info panel, designed to share more code between showing community members & room members. Built on top of this new panel is also a new UX for verification from the member panel.
## Cross-signing (in development) (`feature_cross_signing`)
Cross-signing ([MSC1756](https://github.com/matrix-org/matrix-doc/pull/1756))
improves the device verification experience by allowing you to verify a user
instead of verifying each of their devices.
This feature is still in development and will be landing in several chunks.
## Event indexing and E2EE search support using Seshat (`feature_event_indexing`)
Adds support for search in E2E encrypted rooms. This enables an event indexer
that downloads, stores, and indexes room messages for E2E encrypted rooms.
The existing search will transparently work for encrypted rooms just like it
does for non-encrypted.
The setting will be removed in a future release, enabling it non-optionally for
all users.
## Bridge info tab (`feature_bridge_state`)
@@ -101,16 +105,28 @@ tab as the single source of truth just yet.
This adds a presence indicator in the room list next to DM rooms where the other
person is online.
## Show padlocks on invite only rooms (`feature_invite_only_padlocks`)
This adds padlocks to room list tiles and room header for invite only rooms.
This feature flag (unlike most) is enabled by default.
## Custom themes (`feature_custom_themes`)
Custom themes are possible through Riot's [theme support](./theming.md), though
normally these themes need to be defined in the config for Riot. This labs flag
Custom themes are possible through Element's [theme support](./theming.md), though
normally these themes need to be defined in the config for Element. This labs flag
adds an ability for end users to add themes themselves by using a URL to the JSON
theme definition.
For some sample themes, check out [aaronraimist/riot-web-themes](https://github.com/aaronraimist/riot-web-themes).
For some sample themes, check out [aaronraimist/element-themes](https://github.com/aaronraimist/element-themes).
## Message preview tweaks
To enable message previews for reactions in all rooms, enable `feature_roomlist_preview_reactions_all`.
To enable message previews for reactions in DMs, enable `feature_roomlist_preview_reactions_dms`, ignored when it is enabled for all rooms.
## Communities v2 prototyping (`feature_communities_v2_prototypes`) [In Development]
**This is a highly experimental implementation for parts of the communities v2 experience.** It does not
represent what communities v2 will look/feel like and can/will change without notice. Due to the early
stages this feature is in and the requirement for a compatible homeserver, we will not be accepting issues
or feedback for this functionality at this time.
## Dehydrated devices (`feature_dehydration`)
Allows users to receive encrypted messages by creating a device that is stored
encrypted on the server, as described in [MSC2697](https://github.com/matrix-org/matrix-doc/pull/2697).

10
docs/memory-profiles-and-leaks.md
View File

@@ -1,6 +1,6 @@
## Memory leaks
Riot usually emits slow behaviour just before it is about to crash. Getting a
Element usually emits slow behaviour just before it is about to crash. Getting a
memory snapshot (below) just before that happens is ideal in figuring out what
is going wrong.
@@ -14,14 +14,14 @@ this happens though so we can try and narrow down what might have gone wrong.
## Memory profiles/snapshots
When investigating memory leaks/problems it's usually important to compare snapshots
from different points in the Riot session lifecycle. Most importantly, a snapshot
from different points in the Element session lifecycle. Most importantly, a snapshot
to establish the baseline or "normal" memory usage is useful. Taking a snapshot
roughly 30-60 minutes after starting Riot is a good time to establish "normal"
roughly 30-60 minutes after starting Element is a good time to establish "normal"
memory usage for the app - anything after that is at risk of hiding the memory leak
and anything newer is still in the warmup stages of the app.
**Memory profiles can contain sensitive information.** If you are submitting a memory
profile to us for debugging purposes, please pick the appropriate Riot developer and
profile to us for debugging purposes, please pick the appropriate Element developer and
send them over an encrypted private message. *Do not share your memory profile in
public channels or with people you do not trust.*
@@ -42,7 +42,7 @@ While the profile is in progress, the tab might be frozen or unresponsive.
1. Press CTRL+SHIFT+I (I as in eye).
2. Click the Memory tab.
3. Select "Heap Snapshot" and the riot.im VM instance (not the indexeddb one).
3. Select "Heap Snapshot" and the app.element.io VM instance (not the indexeddb one).
4. Click "Take Snapshot".
5. Wait a bit (coffee is a good option).
6. When the save button appears on the left side of the panel, click it to save the

14
docs/native-node-modules.md
View File

@@ -1,24 +1,24 @@
# Native Node Modules
For some features, the desktop version of Riot can make use of native Node
For some features, the desktop version of Element can make use of native Node
modules. These allow Riot to integrate with the desktop in ways that a browser
cannot.
While native modules enable powerful new features, they must be complied for
each operating system. For official Riot releases, we will always build these
each operating system. For official Element releases, we will always build these
modules from source to ensure we can trust the compiled output. In the future,
we may offer a pre-compiled path for those who want to use these features in a
custom build of Riot without installing the various build tools required.
custom build of Element without installing the various build tools required.
Do note that compiling a module for a particular operating system
(Linux/macOS/Windows) will need to be done on that operating system.
Cross-compiling from a host OS for a different target OS may be possible, but
we don't support this flow with Riot dependencies at this time.
we don't support this flow with Element dependencies at this time.
At the moment, we need to make some changes to the Riot release process before
At the moment, we need to make some changes to the Element release process before
we can support native Node modules at release time, so these features are
currently disabled by default until that is resolved. The following sections
explain the manual steps you can use with a custom build of Riot to enable
explain the manual steps you can use with a custom build of Element to enable
these features if you'd like to try them out.
## Adding Seshat for search in E2E encrypted rooms
@@ -53,7 +53,7 @@ Please make sure to include all the `--` as well as the `--release` command line
switch at the end. Modify your electron version accordingly depending on the
version that is installed on your system.
After this is done the Electron version of Riot can be run from the main folder
After this is done the Electron version of Element can be run from the main folder
as usual using:
yarn electron

33
docs/pr-previews.md Normal file
View File

@@ -0,0 +1,33 @@
# Pull Request Previews
Pull requests to the React SDK layer (and in the future other layers as well)
automatically set up a preview site with a full deployment of Element with the
changes from the pull request added in so that anyone can easily test and review
them. This is especially useful for checking visual and interactive changes.
To access the preview site, scroll down to the bottom of the PR where the
various CI results are displayed:
![Pull request: checks section](./img/pr-checks.png)
The checks section could be collapsed at first, so you may need to click "Show
all checks" to reveal them. Look for an entry that mentions `deploy-preview`. It
may be at the end of the list, so you may need scroll a bit to see it. To access
the preview site, click the "Details" link in the deploy preview row.
**Important:** Please always use test accounts when logging into preview sites,
as they may contain unreviewed and potentially dangerous code that could damage
your account, exfiltrate encryption keys, etc.
## FAQs
### Are preview sites created for pull requests from contributors?
Yes, they are created for all PRs from any author.
### Do preview sites expire after some time period?
No, there is no expiry date, so they should remain accessible indefinitely, but
of course they obviously aren't meant to live beyond the development workflow,
so please don't rely on them for anything important. They may disappear at any
time without notice.

83
docs/review.md Normal file
View File

@@ -0,0 +1,83 @@
# Review Guidelines
The following summarises review guidelines that we follow for pull requests in
Element Web and other supporting repos. These are just guidelines (not strict
rules) and may be updated over time.
## Code Review
When reviewing code, here are some things we look for and also things we avoid:
### We review for
* Correctness
* Performance
* Accessibility
* Security
* Quality via automated and manual testing
* Comments and documentation where needed
* Sharing knowledge of different areas among the team
* Ensuring it's something we're comfortable maintaining for the long term
* Progress indicators and local echo where appropriate with network activity
### We should avoid
* Style nits that are already handled by the linter
* Dramatically increasing scope
### Good practices
* Use empathetic language
* See also [Mindful Communication in Code
Reviews](https://kickstarter.engineering/a-guide-to-mindful-communication-in-code-reviews-48aab5282e5e)
and [How to Do Code Reviews Like a Human](https://mtlynch.io/human-code-reviews-1/)
* Authors should prefer smaller commits for easier reviewing and bisection
* Reviewers should be explicit about required versus optional changes
* Reviews are conversations and the PR author should feel comfortable
discussing and pushing back on changes before making them
* Reviewers are encouraged to ask for tests where they believe it is reasonable
* Core team should lead by example through their tone and language
* Take the time to thank and point out good code changes
* Using softer language like "please" and "what do you think?" goes a long way
towards making others feel like colleagues working towards a common goal
### Workflow
* Authors should request review from the element-web team by default (if someone on
the team is clearly the expert in an area, a direct review request to them may
be more appropriate)
* Reviewers should remove the team review request and request review from
themselves when starting a review to avoid double review
* If there are multiple related PRs authors should reference each of the PRs in
the others before requesting review. Reviewers might start reviewing from
different places and could miss other required PRs.
* Avoid force pushing to a PR after the first round of review
* Use the GitHub default of merge commits when landing (avoid alternate options
like squash or rebase)
* PR author merges after review (assuming they have write access)
* Assign issues only when in progress to indicate to others what can be picked
up
## Design and Product Review
We want to ensure that all changes to Element fit with our design and product
vision. We often request review from those teams so they can provide their
perspective.
In more detail, our usual process for changes that affect the UI or alter user
functionality is:
* For changes that will go live when merged, always flag Design and Product
teams as appropriate
* For changes guarded by a feature flag, Design and Product review is not
required (though may still be useful) since we can continue tweaking
As it can be difficult to review design work from looking at just the changed
files in a PR, a [preview site](./pr-previews.md) that includes your changes
will be added automatically so that anyone who's interested can try them out
easily.
Before starting work on a feature, it's best to ensure your plan aligns well
with our vision for Element. Please chat with the team in
[#element-dev:matrix.org](https://matrix.to/#/#element-dev:matrix.org) before you
start so we can ensure it's something we'd be willing to merge.

15
docs/shortcuts.md
View File

@@ -1,15 +0,0 @@
# Keyboard Shortcuts
The modifier is <kbd>Ctrl</kbd> on Windows & Linux and <kbd>⌘</kbd> on Mac.
- <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>m</kbd> - toggle markdown
- <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>d</kbd> - toggle mic mute
- <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>e</kbd> - toggle video on/off
- <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>k</kbd> - jump to named room
- <kbd>↑</kbd>/<kbd>↓</kbd> - navigate old messages to edit when the composer is in focus
- <kbd>↑</kbd>/<kbd>↓</kbd> - next/prev room when focus in room list
- <kbd>Alt</kbd>+<kbd>↑</kbd>/<kbd>↓</kbd> - resend previous messages when the composer is in focus
- <kbd>PageUp</kbd>/<kbd>PageDown</kbd> - scroll timeline up/down
- <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>Home</kbd>/<kbd>End</kbd> - jump to
start/end of the composer when focused, otherwise jump to timeline start/end
- <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>`</kbd> - toggle the top left menu

16
docs/skinning thoughts.md
View File

@@ -5,14 +5,14 @@ matrix-react-sdk
- base CSS
- all the components needed to build a workable app (including the top layer)
riot-web: the riot skin
- riot-specific classes (e.g. login header/footer)
- riot-specific themes
element-web: the Element skin
- Element-specific classes (e.g. login header/footer)
- Element-specific themes
- light
- dark
i.e. the only things which should go into riot-web are bits which apply vector-specific skinning
specifically "Stuff that any other brand would not want to use. (e.g. riot logos, links, T&Cs)"
i.e. the only things which should go into element-web are bits which apply vector-specific skinning
specifically "Stuff that any other brand would not want to use. (e.g. Element logos, links, T&Cs)"
- Questions:
- Electron app? (should probably be a separate repo in its own right? but might as well go here for now)
- index.html & index.js? (should be in matrix-react-sdk, given the SDK is useless without them?)
@@ -21,7 +21,7 @@ ideally matrix-react-sdk itself should ship with a default skin which actually w
status skin (can go in the same app for now)
- has status theme
- which inherits from riot light theme
- which inherits from Element light theme
- how do we share graphics between skins?
- shove them into react-sdk, or...
- guess we do ../../vector/img
@@ -52,7 +52,7 @@ other changes:
- skins/vector/themes/foo/css
- skins/vector/themes/foo/img
- skins/vector/themes/foo/fonts
- ideally riot-web would contain almost nothing but skins/vector directory.
- ideally element-web would contain almost nothing but skins/vector directory.
- ability to entirely replace CSS rather than override it for a given theme
- e.g. if we replace `Login.js` with `StatusLogin.js`, then we should similarly be able to replace `_Login.scss` with `_StatusLogin.scss`.
@@ -64,5 +64,5 @@ random thoughts;
-----------------
Immediate plan for Status:
* Implement it as a theme for the riot skin
* Implement it as a theme for the Element skin
* Ideally move skins to a sensible level (possibly even including src?)

30
docs/theming.md
View File

@@ -1,14 +1,14 @@
Theming Riot
Theming Element
============
Themes are a very basic way of providing simple alternative look & feels to the
riot-web app via CSS & custom imagery.
Element app via CSS & custom imagery.
They are *NOT* co be confused with 'skins', which describe apps which sit on top
of matrix-react-sdk - e.g. in theory Riot itself is a react-sdk skin.
As of Jan 2017, skins are not fully supported; riot is the only available skin.
of matrix-react-sdk - e.g. in theory Element itself is a react-sdk skin.
As of Jan 2017, skins are not fully supported; Element is the only available skin.
To define a theme for Riot:
To define a theme for Element:
1. Pick a name, e.g. `teal`. at time of writing we have `light` and `dark`.
2. Fork `src/skins/vector/css/themes/dark.scss` to be `teal.scss`
@@ -41,6 +41,16 @@ eg. in config.json:
{
"name": "Electric Blue",
"is_dark": false,
"fonts": {
"faces": [
{
"font-family": "Inter",
"src": [{"url": "/fonts/Inter.ttf", "format": "ttf"}]
}
],
"general": "Inter, sans",
"monospace": "'Courier New'"
},
"colors": {
"accent-color": "#3596fc",
"primary-color": "#368bd6",
@@ -54,7 +64,9 @@ eg. in config.json:
"timeline-background-color": "#ffffff",
"timeline-text-color": "#2e2f32",
"timeline-text-secondary-color": "#61708b",
"timeline-highlights-color": "#f3f8fd"
"timeline-highlights-color": "#f3f8fd",
"username-colors": ["#ff0000", ...]
"avatar-background-colors": ["#cc0000", ...]
}
}, {
"name": "Deep Purple",
@@ -78,3 +90,9 @@ eg. in config.json:
]
}
```
`username-colors` is expected to contain 8 colors. `avatar-background-colors` is expected to contain 3 colors. Both values are optional and have fallbacks from the built-in theme.
These are exposed as `--username-colors_0`, ... and `--avatar-background-colors_0`, ... respectively in CSS.
All properties in `fonts` are optional, and will default to the standard Riot fonts.

4
docs/translating-dev.md
View File

@@ -1,4 +1,4 @@
# How to translate riot-web (Dev Guide)
# How to translate Element (Dev Guide)
## Requirements
@@ -6,7 +6,7 @@
- Including up-to-date versions of matrix-react-sdk and matrix-js-sdk
- Latest LTS version of Node.js installed
- Be able to understand English
- Be able to understand the language you want to translate riot-web into
- Be able to understand the language you want to translate Element into
## Translating strings vs. marking strings for translation

22
docs/translating.md
View File

@@ -1,32 +1,32 @@
# How to translate riot-web
# How to translate Element
## Requirements
- Web Browser
- Be able to understand English
- Be able to understand the language you want to translate riot-web into
- Be able to understand the language you want to translate Element into
## Step 0: Join #riotweb-translations:matrix.org
## Step 0: Join #element-translations:matrix.org
1. Come and join https://matrix.to/#/#riotweb-translations:matrix.org
1. Come and join https://matrix.to/#/#element-translations:matrix.org
2. Read scrollback and/or ask if anyone else is working on your language, and co-ordinate if needed. In general little-or-no coordination is needed though :)
## Step 1: Preparing your Weblate Profile
1. Head to https://translate.riot.im and register either via Github or email
1. Head to https://translate.element.io and register either via Github or email
2. After registering check if you got an email to verify your account and click the link (if there is none head to step 1.4)
3. Log into weblate
4. Head to https://translate.riot.im/accounts/profile/ and select the languages you know and maybe another language you know too.
6. Head to https://translate.riot.im/accounts/profile/#subscriptions and select Riot Web as Project
4. Head to https://translate.element.io/accounts/profile/ and select the languages you know and maybe another language you know too.
6. Head to https://translate.element.io/accounts/profile/#subscriptions and select Element Web as Project
## How to check if your language already is being translated
Go to https://translate.riot.im/projects/riot-web/ and visit the 2 sub-projects.
Go to https://translate.element.io/projects/element-web/ and visit the 2 sub-projects.
If your language is listed go to Step 2a and if not go to Step 2b
## Step 2a: Helping on existing languages.
1. Head to one of the projects listed https://translate.riot.im/projects/riot-web/
1. Head to one of the projects listed https://translate.element.io/projects/element-web/
2. Click on the ``translate`` button on the right side of your language
3. Fill in the translations in the writeable field. You will see the original English string and the string of your second language above.
@@ -34,7 +34,7 @@ Head to the explanations under Steb 2b
## Step 2b: Adding a new language
1. Go to one of the projects listed https://translate.riot.im/projects/riot-web/
1. Go to one of the projects listed https://translate.element.io/projects/element-web/
2. Click the ``Start new translation`` button at the bottom
3. Select a language
4. Start translating like in 2a.3
@@ -50,7 +50,7 @@ The yellow button has to be used if you are unsure about the translation but you
### What are "%(something)s"?
These things are variables that are expanded when displayed by Riot. They can be room names, usernames or similar. If you find one, you can move to the right place for your language, but not delete it as the variable will be missing if you do.
These things are variables that are expanded when displayed by Element. They can be room names, usernames or similar. If you find one, you can move to the right place for your language, but not delete it as the variable will be missing if you do.
A special case is `%(urlStart)s` and `%(urlEnd)s` which are used to mark the beginning of a hyperlink (i.e. `<a href="/somewhere">` and `</a>`. You must keep these markers surrounding the equivalent string in your language that needs to be hyperlinked.