mirrors/element-web
1
0
Fork 0
mirror of https://github.com/element-hq/element-web synced 2024-11-22 17:25:50 +03:00
Code Issues Projects Releases Packages Wiki Activity

major update to dev guidelines

Browse source
This commit is contained in:
Matthew Hodgson 2016-07-11 18:26:16 +01:00
parent e00f3d9334
commit a8677b52ad
1 changed files with 113 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

172
README.md
View file

@ -3,65 +3,85 @@ matrix-react-sdk
This is a react-based SDK for inserting a Matrix chat/voip client into a web page. This is a react-based SDK for inserting a Matrix chat/voip client into a web page.
This package provides the logic and 'controller' parts for the UI components. This This package provides the React components needed to build a Matrix web client
forms one part of a complete matrix client, but it not useable in isolation. It using React. It is not useable in isolation, and instead must must be used from
must be used from a 'skin'. A skin provides: a 'skin'. A skin provides:
* The HTML for the UI components (in the form of React `render` methods) * Customised implementations of presentation components.
* The CSS for this HTML * Custom CSS
* The containing application * The containing application
* Zero or more 'modules' containing non-UI functionality * Zero or more 'modules' containing non-UI functionality
Skins are modules are exported from such a package in the `lib` directory. **WARNING: As of July 2016, the skinning abstraction is broken due to rapid
`lib/skins` contains one directory per-skin, named after the skin, and the development of `matrix-react-sdk` to meet the needs of Vector, the first app
`modules` directory contains modules as their javascript files. to be built on top of the SDK** (https://github.com/vector-im/vector-web).
Right now `matrix-react-sdk` depends on some functionality from `vector-web`
(e.g. CSS), and `matrix-react-sdk` contains some Vector specific behaviour
(grep for 'vector'). This layering will be fixed asap once Vector development
has stabilised, but for now we do not advise trying to create new skins for
matrix-react-sdk until the layers are clearly separated again.
A basic skin is provided in the matrix-react-skin package. This also contains In the interim, `vector-im/vector-web` and `matrix-org/matrix-react-sdk` should
a minimal application that instantiates the basic skin making a working matrix be considered as a single project (for instance, matrix-react-sdk bugs
client. are currently filed against vector-im/vector-web rather than this project).
You can use matrix-react-sdk directly, but to do this you would have to provide Developer Guide
'views' for each UI component. To get started quickly, use matrix-react-skin. ===============
How to customise the SDK Platform Targets:
======================== * Chrome, Firefox and Safari.
* Edge should also work, but we're not testing it proactively.
* WebRTC features (VoIP and Video calling) are only available in Chrome & Firefox.
* Mobile Web is not currently a target platform - instead please use the native
iOS (https://github.com/matrix-org/matrix-ios-kit) and Android
(https://github.com/matrix-org/matrix-android-sdk) SDKs.
The SDK formerly used the 'atomic' design pattern as seen at http://patternlab.io to All code lands on the `develop` branch - `master` is only used for stable releases.
encourage a very modular and reusable architecture, making it easy to **Please file PRs against `develop`!!**
customise and use UI widgets independently of the rest of the SDK and your app.
So unfortunately at the moment this document does not describe how to customize your UI! Please follow the standard Matrix contributor's guide:
https://github.com/matrix-org/synapse/tree/master/CONTRIBUTING.rst
###This is the old description for the atomic design pattern: Please follow the Matrix JS/React code style as per:
https://github.com/matrix-org/matrix-react-sdk/tree/master/code_style.rst
In practice this means: Whilst the layering separation between matrix-react-sdk and Vector is broken
(as of July 2016), code should be committed as follows:
* All new components: https://github.com/matrix-org/matrix-react-sdk/tree/master/src/components
* Vector-specific components: https://github.com/vector-im/vector-web/tree/master/src/components
* In practice, `matrix-react-sdk` is still evolving so fast that the maintenance
burden of customising and overriding these components for Vector can seriously
impede development. So right now, there should be very few (if any) customisations for Vector.
* CSS for Matrix SDK components: https://github.com/vector-im/vector-web/tree/master/src/skins/vector/css/matrix-react-sdk
* CSS for Vector-specific overrides and components: https://github.com/vector-im/vector-web/tree/master/src/skins/vector/css/vector-web
* The UI of the app is strictly split up into a hierarchy of components. React components in matrix-react-sdk are come in two different flavours:
'structures' and 'views'. Structures are stateful components which handle the
more complicated business logic of the app, delegating their actual presentation
rendering to stateless 'view' components. For instance, the RoomView component
that orchestrates the act of visualising the contents of a given Matrix chat room
tracks lots of state for its child components which it passes into them for visual
rendering via props.
* Each component has its own: Good separation between the components is maintained by adopting various best
* View object defined as a React javascript class containing embedded practices that anyone working with the SDK needs to be be aware of and uphold:
HTML expressed in React's JSX notation.
* CSS file, which defines the styling specific to that component.
* Components are loosely grouped into the 5 levels outlined by atomic design: * Components are named with upper camel case (e.g. views/rooms/EventTile.js)
* atoms: fundamental building blocks (e.g. a timestamp tag)
* molecules: "group of atoms which functions together as a unit"
(e.g. a message in a chat timeline)
* organisms: "groups of molecules (and atoms) which form a distinct section
of a UI" (e.g. a view of a chat room)
* templates: "a reusable configuration of organisms" - used to combine and
style organisms into a well-defined global look and feel
* pages: specific instances of templates.
Good separation between the components is maintained by adopting various best * They are organised in a typically two-level hierarchy - first whether the
practices that anyone working with the SDK needs to be be aware of and uphold: component is a view or a structure, and then a broad functional grouping
(e.g. 'rooms' here)
* Views are named with upper camel case (e.g. molecules/MessageTile.js) * After creating a new component you must run `npm run reskindex` to regenerate
the `component-index.js` for the SDK (used in future for skinning)
* The view's CSS file MUST have the same name (e.g. molecules/MessageTile.css) * The view's CSS file MUST have the same name (e.g. view/rooms/MessageTile.css).
CSS for matrix-react-sdk currently resides in
https://github.com/vector-im/vector-web/tree/master/src/skins/vector/css/matrix-react-sdk.
* Per-view CSS is optional - it could choose to inherit all its styling from * Per-view CSS is optional - it could choose to inherit all its styling from
the context of the rest of the app, although this is unusual for any but the context of the rest of the app, although this is unusual for any but
the simplest atoms and molecules. structural components (lacking presentation logic) and the simplest view
components.
* The view MUST *only* refer to the CSS rules defined in its own CSS file. * The view MUST *only* refer to the CSS rules defined in its own CSS file.
'Stealing' styling information from other components (including parents) 'Stealing' styling information from other components (including parents)
@ -82,9 +102,10 @@ In practice this means:
* We deliberately use vanilla CSS 3.0 to avoid adding any more magic * We deliberately use vanilla CSS 3.0 to avoid adding any more magic
dependencies into the mix than we already have. App developers are welcome dependencies into the mix than we already have. App developers are welcome
to use whatever floats their boat however. to use whatever floats their boat however. In future we'll start using
css-next to pull in features like CSS variable support.
* The CSS for a component can however override the rules for child components. * The CSS for a component can override the rules for child components.
For instance, .mx_RoomList .mx_RoomTile {} would be the selector to override For instance, .mx_RoomList .mx_RoomTile {} would be the selector to override
styles of RoomTiles when viewed in the context of a RoomList view. styles of RoomTiles when viewed in the context of a RoomList view.
Overrides *must* be scoped to the View's CSS class - i.e. don't just define Overrides *must* be scoped to the View's CSS class - i.e. don't just define
@ -98,30 +119,36 @@ In practice this means:
generally not cool and stop the component from being reused easily in generally not cool and stop the component from being reused easily in
different places. different places.
* We don't use the atomify library itself, as React already provides most Originally `matrix-react-sdk` followed the Atomic design pattern as per
of the modularity requirements it brings to the table. http://patternlab.io to try to encourage a modular architecture. However, we
found that the grouping of components into atoms/molecules/organisms
made them harder to find relative to a functional split, and didn't emphasise
the distinction between 'structural' and 'view' components, so we backed away
from it.
With all this in mind, here's how you go about skinning the react SDK UI Github Issues
components to embed a Matrix client into your app: =============
* Create a new NPM project. Be sure to directly depend on react, (otherwise All issues should be filed under https://github.com/vector-im/vector-web/issues
you can end up with two copies of react). for now.
* Create an index.js file that sets up react. Add require statements for
React and matrix-react-sdk. Load a skin using the 'loadSkin' method on the OUTDATED: To Create Your Own Skin
SDK and call Render. This can be a skin provided by a separate package or =================================
a skin in the same package.
* Add a way to build your project: we suggest copying the scripts block **This is ALL LIES currently, as skinning is currently broken - see the WARNING
from matrix-react-skin (which uses babel and webpack). You could use section at the top of this readme.**
different tools but remember that at least the skins and modules of
your project should end up in plain (ie. non ES6, non JSX) javascript in Skins are modules are exported from such a package in the `lib` directory.
the lib directory at the end of the build process, as well as any `lib/skins` contains one directory per-skin, named after the skin, and the
packaging that you might do. `modules` directory contains modules as their javascript files.
* Create an index.html file pulling in your compiled javascript and the
CSS bundle from the skin you use. For now, you'll also need to manually A basic skin is provided in the matrix-react-skin package. This also contains
import CSS from any skins that your skin inherts from. a minimal application that instantiates the basic skin making a working matrix
client.
You can use matrix-react-sdk directly, but to do this you would have to provide
'views' for each UI component. To get started quickly, use matrix-react-skin.
To Create Your Own Skin
=======================
To actually change the look of a skin, you can create a base skin (which To actually change the look of a skin, you can create a base skin (which
does not use views from any other skin) or you can make a derived skin. does not use views from any other skin) or you can make a derived skin.
Note that derived skins are currently experimental: for example, the CSS Note that derived skins are currently experimental: for example, the CSS
@ -145,3 +172,22 @@ Now you have the basis of a skin, you need to generate a skindex.json file. The
you add an npm script to run this, as in matrix-react-skin. you add an npm script to run this, as in matrix-react-skin.
For more specific detail on any of these steps, look at matrix-react-skin. For more specific detail on any of these steps, look at matrix-react-skin.
Alternative instructions:
* Create a new NPM project. Be sure to directly depend on react, (otherwise
you can end up with two copies of react).
* Create an index.js file that sets up react. Add require statements for
React and matrix-react-sdk. Load a skin using the 'loadSkin' method on the
SDK and call Render. This can be a skin provided by a separate package or
a skin in the same package.
* Add a way to build your project: we suggest copying the scripts block
from matrix-react-skin (which uses babel and webpack). You could use
different tools but remember that at least the skins and modules of
your project should end up in plain (ie. non ES6, non JSX) javascript in
the lib directory at the end of the build process, as well as any
packaging that you might do.
* Create an index.html file pulling in your compiled javascript and the
CSS bundle from the skin you use. For now, you'll also need to manually
import CSS from any skins that your skin inherts from.