-
-
Notifications
You must be signed in to change notification settings - Fork 829
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
611 changed files
with
10,316 additions
and
5,649 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,6 @@ | ||
| src/component-index.js | ||
| test/end-to-end-tests/node_modules/ | ||
| test/end-to-end-tests/element/ | ||
| test/end-to-end-tests/synapse/ | ||
| test/end-to-end-tests/lib/ | ||
| # Legacy skinning file that some people might still have | ||
| src/component-index.js |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,71 +1,18 @@ | ||
| # Skinning | ||
|
|
||
| The react-sdk can be skinned to replace presentation components, CSS, or | ||
| other relevant parts of the SDK. Typically consumers will replace entire | ||
| components and get the ability for custom CSS as a result. | ||
|
|
||
| This doc isn't exhaustive on how skinning works, though it should cover | ||
| some of the more complicated parts such as component replacement. | ||
|
|
||
| ## Loading a skin | ||
|
|
||
| 1. Generate a `component-index.js` (preferably using the tools that the react-sdk | ||
| exposes). This can typically be done with a npm script like `"reskindex -h src/header"`. | ||
| 2. In your app's entry point, add something like this code: | ||
| ```javascript | ||
| import {loadSkin} from "matrix-react-sdk"; | ||
| loadSkin(import("component-index").components); | ||
| // The rest of your imports go under this. | ||
| ``` | ||
| 3. Import the remainder of the SDK and bootstrap your app. | ||
|
|
||
| It is extremely important that you **do not** import anything else from the | ||
| SDK prior to loading your skin as otherwise the skin might not work. Loading | ||
| the skin should be one of the first things your app does, if not the very | ||
| first thing. | ||
|
|
||
| Additionally, **do not** provide `loadSkin` with the react-sdk components | ||
| themselves otherwise the app might explode. The SDK is already aware of its | ||
| components and doesn't need to be told. | ||
|
|
||
| ## Replacing components | ||
|
|
||
| Components that replace the react-sdk ones MUST have a `replaces` static | ||
| key on the component's class to describe which component it overrides. For | ||
| example, if your `VectorAuthPage` component is meant to replace the react-sdk | ||
| `AuthPage` component then you'd add `static replaces = 'views.auth.AuthPage';` | ||
| to the `VectorAuthPage` class. | ||
|
|
||
| Other than that, the skin just needs to be loaded normally as mentioned above. | ||
| Consumers of the SDK likely will not be interested in the rest of this section. | ||
|
|
||
| ### SDK developer notes | ||
|
|
||
| Components in the react-sdk MUST be decorated with the `@replaceableComponent` | ||
| function. For components that can't use the decorator, they must use a | ||
| variation that provides similar functionality. The decorator gives consumers | ||
| an opportunity to load skinned components by abusing import ordering and | ||
| behaviour. | ||
|
|
||
| Decorators are executed at import time which is why we can abuse the import | ||
| ordering behaviour: importing `loadSkin` doesn't trigger any components to | ||
| be imported, allowing the consumer to specify a skin. When the consumer does | ||
| import a component (for example, `MatrixChat`), it starts to pull in all the | ||
| components via `import` statements. When the components get pulled in the | ||
| decorator checks with the skinned components to see if it should be replacing | ||
| the component being imported. The decorator then effectively replaces the | ||
| components when needed by specifying the skinned component as an override for | ||
| the SDK's component, which should in theory override critical functions like | ||
| `render()` and lifecycle event handlers. | ||
|
|
||
| The decorator also means that older usage of `getComponent()` is no longer | ||
| required because components should be replaced by the decorator. Eventually | ||
| the react-sdk should only have one usage of `getComponent()`: the decorator. | ||
|
|
||
| The decorator assumes that if `getComponent()` returns null that there is | ||
| no skinned version of the component and continues on using the SDK's component. | ||
| In previous versions of the SDK, the function would throw an error instead | ||
| because it also expected the skin to list the SDK's components as well, however | ||
| that is no longer possible due to the above. | ||
|
|
||
| In short, components should always be `import`ed. | ||
| Skinning in the context of the react-sdk is component replacement rather than CSS. This means you can override (replace) | ||
| any accessible component in the project to implement custom behaviour, look & feel, etc. Depending on your approach, | ||
| overriding CSS classes to apply custom styling is also possible, though harder to do. | ||
|
|
||
| At present, the react-sdk offers no stable interface for components - this means properties and state can and do change | ||
| at any time without notice. Once we determine the react-sdk to be stable enough to use as a proper SDK, we will adjust | ||
| this policy. In the meantime, skinning is done completely at your own risk. | ||
|
|
||
| The approach you take is up to you - we suggest using a module replacement plugin, as found in | ||
| [webpack](https://webpack.js.org/plugins/normal-module-replacement-plugin/), though you're free to use whichever build | ||
| system works for you. The react-sdk does not have any particular functions to call to load skins, so simply replace or | ||
| extend the components/stores/etc you're after and build. As a reminder though, this is done completely at your own risk | ||
| as we cannot guarantee a stable interface at this time. | ||
|
|
||
| Taking a look at [element-web](https://github.com/vector-im/element-web)'s approach to skinning may be worthwhile, as it | ||
| overrides some relatively simple components. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.