From 7793f07c814a44151ca8e8d6701380dce22d903e Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Thu, 15 Oct 2020 18:01:38 +0100 Subject: [PATCH] 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