element-web/README.md

163 lines
7.3 KiB
Markdown
Raw Normal View History

matrix-react-sdk
================
2015-07-08 12:35:40 +02:00
This is a react-based SDK for inserting a Matrix chat/voip client into a web page.
2015-06-24 17:33:53 +02:00
2016-07-11 19:26:16 +02:00
This package provides the React components needed to build a Matrix web client
using React. It is not useable in isolation, and instead must must be used from
a 'skin'. A skin provides:
* Customised implementations of presentation components.
* Custom CSS
* The containing application
2015-10-01 17:02:21 +02:00
* Zero or more 'modules' containing non-UI functionality
2018-09-09 19:38:21 +02:00
As of Aug 2018, the only skin that exists is `vector-im/riot-web`; it and
`matrix-org/matrix-react-sdk` should effectively
2016-07-11 19:26:16 +02:00
be considered as a single project (for instance, matrix-react-sdk bugs
2016-12-21 23:45:57 +01:00
are currently filed against vector-im/riot-web rather than this project).
2016-07-11 19:26:16 +02:00
Translation Status
==================
[![Translation status](https://translate.riot.im/widgets/riot-web/-/multi-auto.svg)](https://translate.riot.im/engage/riot-web/?utm_source=widget)
2016-07-11 19:26:16 +02:00
Developer Guide
===============
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.
All code lands on the `develop` branch - `master` is only used for stable releases.
**Please file PRs against `develop`!!**
Please follow the standard Matrix contributor's guide:
https://github.com/matrix-org/synapse/tree/master/CONTRIBUTING.rst
Please follow the Matrix JS/React code style as per:
2017-09-04 18:31:53 +02:00
https://github.com/matrix-org/matrix-react-sdk/blob/master/code_style.md
2016-07-11 19:26:16 +02:00
2018-09-09 19:38:21 +02:00
Code should be committed as follows:
2016-07-11 19:26:16 +02:00
* All new components: https://github.com/matrix-org/matrix-react-sdk/tree/master/src/components
2016-12-21 23:45:57 +01:00
* Riot-specific components: https://github.com/vector-im/riot-web/tree/master/src/components
2016-07-11 19:26:16 +02:00
* In practice, `matrix-react-sdk` is still evolving so fast that the maintenance
2016-12-21 23:45:57 +01:00
burden of customising and overriding these components for Riot can seriously
impede development. So right now, there should be very few (if any) customisations for Riot.
2018-09-09 19:38:21 +02:00
* CSS: https://github.com/vector-im/riot-web/tree/master/src/skins/vector/css/matrix-react-sdk
* Theme specific CSS & resources: https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes
2016-07-11 19:26:16 +02:00
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.
Good separation between the components is maintained by adopting various best
practices that anyone working with the SDK needs to be be aware of and uphold:
* Components are named with upper camel case (e.g. views/rooms/EventTile.js)
* They are organised in a typically two-level hierarchy - first whether the
component is a view or a structure, and then a broad functional grouping
(e.g. 'rooms' here)
* 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. view/rooms/MessageTile.css).
CSS for matrix-react-sdk currently resides in
2016-12-21 23:45:57 +01:00
https://github.com/vector-im/riot-web/tree/master/src/skins/vector/css/matrix-react-sdk.
* Per-view CSS is optional - it could choose to inherit all its styling from
2016-07-11 19:26:16 +02:00
the context of the rest of the app, although this is unusual for any but
2018-09-09 19:38:21 +02:00
* Theme specific CSS & resources: https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes
2016-07-11 19:26:16 +02:00
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.
'Stealing' styling information from other components (including parents)
is not cool, as it breaks the independence of the components.
* CSS classes are named with an app-specific namespacing prefix to try to avoid
CSS collisions. The base skin shipped by Matrix.org with the matrix-react-sdk
uses the naming prefix "mx_". A company called Yoyodyne Inc might use a
prefix like "yy_" for its app-specific classes.
* CSS classes use upper camel case when they describe React components - e.g.
.mx_MessageTile is the selector for the CSS applied to a MessageTile view.
* CSS classes for DOM elements within a view which aren't components are named
by appending a lower camel case identifier to the view's class name - e.g.
.mx_MessageTile_randomDiv is how you'd name the class of an arbitrary div
within the MessageTile view.
* 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
2016-07-11 19:26:16 +02:00
to use whatever floats their boat however. In future we'll start using
css-next to pull in features like CSS variable support.
2016-07-11 19:26:16 +02:00
* The CSS for a component can override the rules for child components.
For instance, .mx_RoomList .mx_RoomTile {} would be the selector to override
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
.mx_RoomTile {} in RoomList.css - only RoomTile.css is allowed to define its
own CSS. Instead, say .mx_RoomList .mx_RoomTile {} to scope the override
only to the context of RoomList views. N.B. overrides should be relatively
rare as in general CSS inheritence should be enough.
* Components should render only within the bounding box of their outermost DOM
element. Page-absolute positioning and negative CSS margins and similar are
generally not cool and stop the component from being reused easily in
different places.
2016-07-11 19:26:16 +02:00
Originally `matrix-react-sdk` followed the Atomic design pattern as per
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.
2016-07-11 19:26:16 +02:00
Github Issues
=============
2016-12-21 23:45:57 +01:00
All issues should be filed under https://github.com/vector-im/riot-web/issues
2016-07-11 19:26:16 +02:00
for now.
Development
===========
Ensure you have the latest stable Node JS runtime installed (v8.x is the best choice). Then check out
the code and pull in dependencies:
```bash
git clone https://github.com/matrix-org/matrix-react-sdk.git
cd matrix-react-sdk
git checkout develop
npm install
```
`matrix-react-sdk` depends on `matrix-js-sdk`. To make use of changes in the
latter and to ensure tests run against the develop branch of `matrix-js-sdk`,
you should run the following which will sync changes from the JS sdk here.
```bash
npm link ../matrix-js-sdk
```
Command assumes a checked out and installed `matrix-js-sdk` folder in parent
folder.
Running tests
=============
Ensure you've followed the above development instructions and then:
```bash
npm run test
```