From 7793f07c814a44151ca8e8d6701380dce22d903e Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Thu, 15 Oct 2020 18:01:38 +0100 Subject: [PATCH 1/3] Document customisation points https://github.com/matrix-org/matrix-react-sdk/pull/5327 adds a concept of "customisation points" to keep custom functionality contained. This adds some general guidance on how to use them. --- docs/customisations.md | 34 ++++++++++++++++++++++++++++++++++ src/customisations/README.md | 1 + 2 files changed, 35 insertions(+) create mode 100644 docs/customisations.md create mode 120000 src/customisations/README.md diff --git a/docs/customisations.md b/docs/customisations.md new file mode 100644 index 0000000000..cea95af478 --- /dev/null +++ b/docs/customisations.md @@ -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.js` +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 end of the `plugins` 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. diff --git a/src/customisations/README.md b/src/customisations/README.md new file mode 120000 index 0000000000..d2cbdd09d6 --- /dev/null +++ b/src/customisations/README.md @@ -0,0 +1 @@ +docs/customisations.md \ No newline at end of file From f37b63a6cb9bac0f2078ed265a739551633ee4e6 Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Fri, 16 Oct 2020 11:22:28 +0100 Subject: [PATCH 2/3] Fix file extension Co-authored-by: Travis Ralston --- docs/customisations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/customisations.md b/docs/customisations.md index cea95af478..2c36b54f9b 100644 --- a/docs/customisations.md +++ b/docs/customisations.md @@ -13,7 +13,7 @@ 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.js` + `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 From 4053d598f81216596793d628c587ff77929e4ae6 Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Fri, 16 Oct 2020 11:32:57 +0100 Subject: [PATCH 3/3] Update README.md link --- src/customisations/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/customisations/README.md b/src/customisations/README.md index d2cbdd09d6..cacf116604 120000 --- a/src/customisations/README.md +++ b/src/customisations/README.md @@ -1 +1 @@ -docs/customisations.md \ No newline at end of file +../../docs/customisations.md \ No newline at end of file