mirror of
https://github.com/turt2live/matrix-dimension.git
synced 2024-10-01 01:05:53 -04:00
Riot -> Element
This commit is contained in:
Travis Ralston
parent
9e2393ceca
commit
76903e8c8c
@ -1,6 +1,6 @@
|
||||
# Dimension Development
|
||||
|
||||
Dimension is split into two layers: the frontend (web) and backend. The frontend is responsible for interacting with the client (Riot) directly and hands off any complex work to the backend for processing.
|
||||
Dimension is split into two layers: the frontend (web) and backend. The frontend is responsible for interacting with the client (Element) directly and hands off any complex work to the backend for processing.
|
||||
|
||||
**For help and support related to Dimension development, please visit:**
|
||||
[](https://matrix.to/#/#dimension:t2bot.io)
|
||||
@ -47,7 +47,7 @@ the bots can work well within their constraints.
|
||||
|
||||
## Frontend Architecture
|
||||
|
||||
The frontend app is split into two major parts: The Riot frontend and the admin section. The components are nested under
|
||||
The frontend app is split into two major parts: The Element frontend and the admin section. The components are nested under
|
||||
their respective categories and route. For example, the edit page for the Jitsi widget is under the Widgets directory.
|
||||
|
||||
The frontend is otherwise a fairly basic Angular 5 application: there's components, services, etc. The services should be
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
|
||||
[](https://travis-ci.org/turt2live/matrix-dimension)
|
||||
|
||||
An open source integration manager for matrix clients, like Riot. For help and support, please visit
|
||||
An open source integration manager for matrix clients, like Element. For help and support, please visit
|
||||
us in [#dimension:t2bot.io](https://matrix.to/#/#dimension:t2bot.io) on Matrix.
|
||||
|
||||
# Installing Dimension / Running your own
|
||||
@ -22,13 +22,13 @@ port. Dimension will use the first record it sees and will only communicate over
|
||||
3. **Verify the homeserver information in your configuration.** The name, access token, and client/
|
||||
server API URL all need to be set to point towards your homeserver. It may also be necessary to set the
|
||||
federation URL if you're running a private server.
|
||||
4. **Run the troubleshooter.** If you're on Riot 1.1.0 or higher, type `/addwidget https://dimension.t2bot.io/widgets/manager-test`
|
||||
4. **Run the troubleshooter.** If you're on Element, type `/addwidget https://dimension.t2bot.io/widgets/manager-test`
|
||||
in a private room then click the button.
|
||||
|
||||
# Do I need an integrations manager?
|
||||
|
||||
Integration managers aim to ease a user's interaction with the various services a homeserver may
|
||||
provide. Often times the integrations manager provided by Riot.im, named Modular, is more than suitable.
|
||||
provide. Often times the integrations manager provided by Element, is more than suitable.
|
||||
However, there are a few cases where running your own makes more sense:
|
||||
|
||||
* Wanting to self-host all aspects of your services (client, homeserver, and integrations)
|
||||
|
||||
@ -30,7 +30,7 @@ homeserver:
|
||||
accessToken: "something"
|
||||
|
||||
# These users can modify the integrations this Dimension supports.
|
||||
# To access the admin interface, open Dimension in Riot and click the settings icon.
|
||||
# To access the admin interface, open Dimension in Element and click the settings icon.
|
||||
admins:
|
||||
- "@someone:domain.com"
|
||||
|
||||
|
||||
@ -1,22 +1,22 @@
|
||||
## Installing Dimension
|
||||
|
||||
**Note**: Dimension is currently only capable of running with Riot Web or Desktop. The iOS and Android
|
||||
**Note**: Dimension is currently only capable of running with Element Web or Desktop. The iOS and Android
|
||||
apps are not directly supported without compiling your own versions. In future, this should be handled
|
||||
by [an integration manager specification](https://github.com/turt2live/matrix-dimension/issues/262).
|
||||
|
||||
There are several options for installing Dimension. The easiest is dependent on how you have Riot
|
||||
There are several options for installing Dimension. The easiest is dependent on how you have Element
|
||||
and your homeserver set up. If you're using [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy),
|
||||
there are already options for configuring Dimension.
|
||||
|
||||
### Step 0: Requirements
|
||||
|
||||
You will need a functioning homeserver (such as [Synapse](https://github.com/matrix-org/synapse)) and
|
||||
a client to access Dimension with. Currently, that means using [Riot Web or Desktop](https://riot.im).
|
||||
a client to access Dimension with. Currently, that means using [Element Web or Desktop](https://element.io).
|
||||
|
||||
Additionally, you will need to be able to host Dimension on a dedicated domain. If your homeserver
|
||||
is set up for example.org, we recommend using dimension.example.org for Dimension.
|
||||
|
||||
Finally, this guide assumes you are running nginx as a webserver for Riot, your homeserver, and
|
||||
Finally, this guide assumes you are running nginx as a webserver for Element, your homeserver, and
|
||||
Dimension. A basic configuration before setting up Dimension would be:
|
||||
|
||||
```conf
|
||||
@ -34,7 +34,7 @@ server {
|
||||
}
|
||||
|
||||
server {
|
||||
# Simple configuration for serving Riot
|
||||
# Simple configuration for serving Element
|
||||
server_name chat.example.org;
|
||||
listen 443 ssl;
|
||||
listen [::]:443 ssl;
|
||||
@ -134,11 +134,11 @@ Reload or restart nginx after creating the configuration.
|
||||
### Step 5: Final steps
|
||||
|
||||
If everything went according to plan, you should be able to visit `https://dimension.example.org`
|
||||
and see instructions for configuring Riot. If you don't, your configuration isn't working as
|
||||
and see instructions for configuring Element. If you don't, your configuration isn't working as
|
||||
intended - double check that all the configuration is set up and visit [#dimension:t2bot.io](https://matrix.to/#/#dimension:t2bot.io)
|
||||
for further help.
|
||||
|
||||
After configuring Riot, click the integrations button (4 squares in the top right of any room) and
|
||||
After configuring Element, click the integrations button (4 squares in the top right of any room) and
|
||||
then click the gear icon. If you don't see a gear icon, you're not an admin in the config. This is
|
||||
where you'll configure different integrations as Dimension doesn't ship with anything enabled by
|
||||
default - click around and start enabling things.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Riot Widgets
|
||||
# Element Widgets
|
||||
|
||||
Riot uses some special interaction with the integration manager to make for a clean user experience.
|
||||
Element uses some special interaction with the integration manager to make for a clean user experience.
|
||||
|
||||
|
||||
### Edit Widget button
|
||||
@ -1,13 +1,13 @@
|
||||
# Scalar Authentication / Registration
|
||||
|
||||
When the "Manage Integrations" button is first clicked by a user, Riot will try and register with the Integrations Manager
|
||||
When the "Manage Integrations" button is first clicked by a user, Element will try and register with the Integrations Manager
|
||||
to get a `scalar_token` that it then uses to authenticate all future requests with the manager.
|
||||
|
||||
## `$restUrl/register`
|
||||
|
||||
This ends up mapping to `/api/v1/scalar/register` when Dimension is correctly set up for a Riot instance.
|
||||
This ends up mapping to `/api/v1/scalar/register` when Dimension is correctly set up for a Element instance.
|
||||
|
||||
Riot will POST to this endpoint an OpenID object that looks similar to the following:
|
||||
Element will POST to this endpoint an OpenID object that looks similar to the following:
|
||||
```
|
||||
{
|
||||
"access_token": "ABCDEFGH",
|
||||
@ -39,4 +39,4 @@ following JSON is more than enough:
|
||||
}
|
||||
```
|
||||
|
||||
Riot will now use this token in future requests by hitting the `"integrations_ui_url"` with `?access_token=some_generated_string`.
|
||||
Element will now use this token in future requests by hitting the `"integrations_ui_url"` with `?access_token=some_generated_string`.
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
# Scalar API (Riot)
|
||||
# Scalar API (Element)
|
||||
|
||||
Scalar and Riot communicate using cross-origin messages in a defined format (described in this document). The full source for the messaging layer in Riot can be seen [here](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/ScalarMessaging.js). With this API, the integrations manager is able to invite users, get some basic state information, and interact with the room in a limited capacity. The API is intentionally restricted to ensure that misbehaving domains don't have full control over Riot.
|
||||
Scalar and Element communicate using cross-origin messages in a defined format (described in this document). The full source for the messaging layer in Element can be seen [here](https://github.com/matrix-org/matrix-react-sdk/blob/develop/src/ScalarMessaging.js). With this API, the integrations manager is able to invite users, get some basic state information, and interact with the room in a limited capacity. The API is intentionally restricted to ensure that misbehaving domains don't have full control over Element.
|
||||
|
||||
## Setting up communications
|
||||
|
||||
Riot will automatically open a channel for receiving messages. The integrations manager needs to do the same so it can speak to Riot. Here's some sample JavaScript that will do this for us:
|
||||
Element will automatically open a channel for receiving messages. The integrations manager needs to do the same so it can speak to Element. Here's some sample JavaScript that will do this for us:
|
||||
|
||||
```
|
||||
window.addEventListener("message", function(event) {
|
||||
@ -393,7 +393,7 @@ sendMessage("set_widget", "!curbf:matrix.org", null, {
|
||||
```
|
||||
|
||||
*Note*: Widgets are documented by the matrix.org team [on this Google Doc](https://docs.google.com/document/d/1TiWNDcEOULeRYQpkJHQDjgIW32ohIJSi5MKv9oRdzCo/edit). That document is the source of truth for the event structure and usage.
|
||||
*Note*: `scalar_token` will be appended to the query string if the widget's url matches the API URL of the integration manager (in Riot)
|
||||
*Note*: `scalar_token` will be appended to the query string if the widget's url matches the API URL of the integration manager (in Element)
|
||||
|
||||
### Getting the room's encryption status
|
||||
|
||||
|
||||
@ -709,25 +709,9 @@ None of these are officially documented, and are subject to change.
|
||||
"authenticated": true,
|
||||
"session": {
|
||||
"Repos": [
|
||||
{
|
||||
"name": "riot-welcome-page",
|
||||
"description": "A welcome page specific for tang.ents.ca (built for Riot)",
|
||||
"private": false,
|
||||
"html_url": "https:\/\/github.com\/ENTS-Source\/riot-welcome-page",
|
||||
"created_at": "2017-06-10T16:54:37Z",
|
||||
"updated_at": "2017-06-10T19:10:21Z",
|
||||
"pushed_at": "2017-06-10T18:15:07Z",
|
||||
"fork": false,
|
||||
"full_name": "ENTS-Source\/riot-welcome-page",
|
||||
"permissions": {
|
||||
"admin": true,
|
||||
"pull": true,
|
||||
"push": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "matrix-dimension",
|
||||
"description": "An alternative integrations manager for Riot",
|
||||
"description": "An alternative integrations manager for Element",
|
||||
"private": false,
|
||||
"html_url": "https:\/\/github.com\/turt2live\/matrix-dimension",
|
||||
"created_at": "2017-05-25T21:41:55Z",
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "matrix-dimension",
|
||||
"version": "1.0.0",
|
||||
"description": "An alternative integrations manager for Riot",
|
||||
"description": "An alternative integrations manager for Element",
|
||||
"main": "build/app/index.js",
|
||||
"license": "GPL-3.0",
|
||||
"scripts": {
|
||||
|
||||
@ -40,7 +40,7 @@ export default class Webserver {
|
||||
|
||||
// We register the default route last to make sure we don't override anything by accident.
|
||||
// We'll pass off all other requests to the web app
|
||||
this.app.get(/(widgets\/|riot\/|\/)*/, (_req, res) => {
|
||||
this.app.get(/(widgets\/|riot\/|element\/|\/)*/, (_req, res) => {
|
||||
res.sendFile(path.join(__dirname, "..", "..", "web", "index.html"));
|
||||
});
|
||||
|
||||
|
||||
@ -24,7 +24,7 @@ export class MatrixWellknownService {
|
||||
public async getIntegrations(): Promise<WellknownResponse> {
|
||||
const parsed = new URL(config.dimension.publicUrl);
|
||||
|
||||
parsed.pathname = '/riot';
|
||||
parsed.pathname = '/element';
|
||||
const uiUrl = parsed.toString();
|
||||
|
||||
parsed.pathname = '/api/v1/scalar';
|
||||
|
||||
@ -11,7 +11,7 @@ interface UrlPreviewResponse {
|
||||
page_title_cache_item: {
|
||||
expires: string; // "2017-12-18T04:20:04.001806738Z"
|
||||
cached_response_err: string;
|
||||
cached_title: string; // the actual thing riot uses
|
||||
cached_title: string; // the actual thing Element uses
|
||||
};
|
||||
error: {
|
||||
message: string;
|
||||
|
||||
@ -51,6 +51,7 @@ import { TermsWidgetWrapperComponent } from "./widget-wrappers/terms/terms.compo
|
||||
const routes: Routes = [
|
||||
{path: "", component: HomeComponent},
|
||||
{path: "riot", pathMatch: "full", redirectTo: "riot-app"},
|
||||
{path: "element", pathMatch: "full", redirectTo: "riot-app"},
|
||||
{
|
||||
path: "riot-app",
|
||||
component: RiotComponent,
|
||||
|
||||
@ -16,8 +16,8 @@
|
||||
<div class="info-box try-dimension shadowed">
|
||||
<h3>Try it out or <a href="https://github.com/turt2live/matrix-dimension#running-your-own" target="_blank">run your own</a></h3>
|
||||
<p>
|
||||
Visit <a href="https://t2bot.io/riot" target="_blank">t2bot.io/riot</a> and log in with your Matrix account
|
||||
or point your Riot <code>config.json</code> at our servers:
|
||||
Visit <a href="https://element.t2host.io" target="_blank">element.t2host.io</a> and log in with your Matrix account
|
||||
or point your Element <code>config.json</code> at our servers:
|
||||
</p>
|
||||
<pre>{{ integrationsConfig }}</pre>
|
||||
</div>
|
||||
@ -220,19 +220,19 @@
|
||||
for news and updates. Don't forget to star the repository on
|
||||
<a href="https://github.com/turt2live/matrix-dimension" target="_blank">GitHub</a>.
|
||||
</p>
|
||||
<p>Here's the configuration options you'll need to update in your Riot <code>config.json</code>:</p>
|
||||
<p>Here's the configuration options you'll need to update in your Element <code>config.json</code>:</p>
|
||||
<pre>{{ integrationsConfig }}</pre>
|
||||
|
||||
<h4>Configuring integrations</h4>
|
||||
<p>
|
||||
If everything is set up correctly, you'll be able to access the admin area of Dimension by clicking
|
||||
the 3x3 grid in the top right of any room in Riot. The gear icon (<i class="fa fa-cog"></i>) in the
|
||||
the 3x3 grid in the top right of any room in Element. The gear icon (<i class="fa fa-cog"></i>) in the
|
||||
top right is where you can configure your bots, bridges, and widgets.
|
||||
</p>
|
||||
|
||||
<h4>"Could not connect to integrations server" error</h4>
|
||||
<p>
|
||||
When Riot cannot reach Dimension or Dimension is unable to reach your homeserver an error saying "Could not
|
||||
When Element cannot reach Dimension or Dimension is unable to reach your homeserver an error saying "Could not
|
||||
contact integrations
|
||||
server" shows up in every room. Before visiting us in <a href="https://matrix.to/#/#dimension:t2bot.io" target="_blank">#dimension:t2bot.io</a>
|
||||
on Matrix, here's a few things to check:
|
||||
|
||||
@ -11,7 +11,7 @@ export class HomeComponent {
|
||||
public showPromoPage = this.hostname === "https://dimension.t2bot.io";
|
||||
|
||||
public integrationsConfig = `` +
|
||||
`"integrations_ui_url": "${this.hostname}/riot",\n` +
|
||||
`"integrations_ui_url": "${this.hostname}/element",\n` +
|
||||
`"integrations_rest_url": "${this.hostname}/api/v1/scalar",\n` +
|
||||
`"integrations_widgets_urls": ["${this.hostname}/widgets"],\n` +
|
||||
`"integrations_jitsi_widget_url": "${this.hostname}/widgets/jitsi",\n`;
|
||||
|
||||
@ -18,7 +18,7 @@
|
||||
<strong>Integrations are not encrypted!</strong>
|
||||
This means that some information about yourself and the
|
||||
room may be leaked to the bot, bridge, or widget. This information includes the room ID, your display
|
||||
name, your username, your avatar, information about Riot, and other similar details. Add integrations
|
||||
name, your username, your avatar, information about Element, and other similar details. Add integrations
|
||||
with caution.
|
||||
</div>
|
||||
<div class="alert alert-warning" *ngIf="!hasIntegrations() && isRoomEncrypted">
|
||||
|
||||
@ -77,7 +77,7 @@ export class RiotHomeComponent {
|
||||
console.error("No user returned for token. Is the token registered in Dimension?");
|
||||
this.isError = true;
|
||||
this.isLoading = false;
|
||||
this.errorMessage = "Could not verify your token. Please try logging out of Riot and back in. Be sure to back up your encryption keys!";
|
||||
this.errorMessage = "Could not verify your token. Please try logging out of Element and back in. Be sure to back up your encryption keys!";
|
||||
} else {
|
||||
this.userId = userId;
|
||||
console.log("Scalar token belongs to " + userId);
|
||||
@ -189,7 +189,7 @@ export class RiotHomeComponent {
|
||||
console.error(err);
|
||||
this.isError = true;
|
||||
this.isLoading = false;
|
||||
this.errorMessage = "Unable to set up Dimension. This version of Riot may not supported or there may be a problem with the server.";
|
||||
this.errorMessage = "Unable to set up Dimension. This version of Element may not supported or there may be a problem with the server.";
|
||||
});
|
||||
|
||||
this.stickerApi.getPacks().then(packs => {
|
||||
@ -265,7 +265,7 @@ export class RiotHomeComponent {
|
||||
case "publicRoom":
|
||||
return this.scalar.getJoinRule(this.roomId).then(payload => {
|
||||
if (!payload.response) {
|
||||
return Promise.reject("Could not communicate with Riot");
|
||||
return Promise.reject("Could not communicate with Element");
|
||||
}
|
||||
const isPublic = payload.response.join_rule === "public";
|
||||
if (isPublic !== requirement.expectedValue) {
|
||||
@ -278,7 +278,7 @@ export class RiotHomeComponent {
|
||||
if (response === true) return Promise.resolve();
|
||||
if (response.error || response.error.message)
|
||||
return Promise.reject("You cannot modify widgets in this room");
|
||||
return Promise.reject("Error communicating with Riot");
|
||||
return Promise.reject("Error communicating with Element");
|
||||
};
|
||||
|
||||
let promiseChain = Promise.resolve();
|
||||
|
||||
@ -68,7 +68,7 @@ export class ScalarWidgetApi {
|
||||
|
||||
public static sendSetAlwaysOnScreen(alwaysVisible: boolean): void {
|
||||
ScalarWidgetApi.callAction("set_always_on_screen", {
|
||||
// Send the value here and in data due to a Riot bug.
|
||||
// Send the value here and in data due to a Element bug.
|
||||
data: {
|
||||
value: alwaysVisible,
|
||||
},
|
||||
|
||||
@ -36,7 +36,7 @@ export class JitsiWidgetWrapperComponent extends CapableWidget implements OnInit
|
||||
this.conferenceId = params.conferenceId || params.confId;
|
||||
this.displayName = params.displayName;
|
||||
this.avatarUrl = params.avatarUrl;
|
||||
this.userId = params.userId || params.email; // Riot uses `email` when placing a conference call
|
||||
this.userId = params.userId || params.email; // Element uses `email` when placing a conference call
|
||||
|
||||
// Set the widget ID if we have it
|
||||
ScalarWidgetApi.widgetId = params.widgetId;
|
||||
@ -49,7 +49,7 @@ export class JitsiWidgetWrapperComponent extends CapableWidget implements OnInit
|
||||
$.getScript(widget.options.scriptUrl);
|
||||
|
||||
if (!this.domain) {
|
||||
// Always fall back to jitsi.riot.im to maintain compatibility with widgets created by Riot.
|
||||
// Always fall back to jitsi.riot.im to maintain compatibility with widgets created by Element.
|
||||
this.domain = widget.options.useDomainAsDefault ? widget.options.jitsiDomain : "jitsi.riot.im";
|
||||
}
|
||||
});
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// The CSS for the Riot breadcrumb is specified here to ensure that it's style can be overridden.
|
||||
// The CSS for the Element breadcrumb is specified here to ensure that it's style can be overridden.
|
||||
// In it's current position (as a component), the component-level stylesheet cannot access the
|
||||
// elements, so we specify it in a more generic location.
|
||||
@import "themes/themes";
|
||||
|
||||
Loading…
Reference in New Issue
Block a user