major update to dev guidelines
Matthew Hodgson
parent
e00f3d9334
commit
a8677b52ad
172
README.md
172
README.md
|
|
@ -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 package provides the logic and 'controller' parts for the UI components. This
|
||||
forms one part of a complete matrix client, but it not useable in isolation. It
|
||||
must be used from a 'skin'. A skin provides:
|
||||
* The HTML for the UI components (in the form of React `render` methods)
|
||||
* The CSS for this HTML
|
||||
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
|
||||
* Zero or more 'modules' containing non-UI functionality
|
||||
|
||||
Skins are modules are exported from such a package in the `lib` directory.
|
||||
`lib/skins` contains one directory per-skin, named after the skin, and the
|
||||
`modules` directory contains modules as their javascript files.
|
||||
**WARNING: As of July 2016, the skinning abstraction is broken due to rapid
|
||||
development of `matrix-react-sdk` to meet the needs of Vector, the first app
|
||||
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
|
||||
a minimal application that instantiates the basic skin making a working matrix
|
||||
client.
|
||||
In the interim, `vector-im/vector-web` and `matrix-org/matrix-react-sdk` should
|
||||
be considered as a single project (for instance, matrix-react-sdk bugs
|
||||
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
|
||||
'views' for each UI component. To get started quickly, use matrix-react-skin.
|
||||
Developer Guide
|
||||
===============
|
||||
|
||||
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
|
||||
encourage a very modular and reusable architecture, making it easy to
|
||||
customise and use UI widgets independently of the rest of the SDK and your app.
|
||||
All code lands on the `develop` branch - `master` is only used for stable releases.
|
||||
**Please file PRs against `develop`!!**
|
||||
|
||||
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:
|
||||
* View object defined as a React javascript class containing embedded
|
||||
HTML expressed in React's JSX notation.
|
||||
* CSS file, which defines the styling specific to that component.
|
||||
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 loosely grouped into the 5 levels outlined by atomic design:
|
||||
* 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.
|
||||
* Components are named with upper camel case (e.g. views/rooms/EventTile.js)
|
||||
|
||||
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:
|
||||
* 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)
|
||||
|
||||
* 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
|
||||
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.
|
||||
'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
|
||||
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
|
||||
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
|
||||
|
|
@ -98,30 +119,36 @@ In practice this means:
|
|||
generally not cool and stop the component from being reused easily in
|
||||
different places.
|
||||
|
||||
* We don't use the atomify library itself, as React already provides most
|
||||
of the modularity requirements it brings to the table.
|
||||
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.
|
||||
|
||||
With all this in mind, here's how you go about skinning the react SDK UI
|
||||
components to embed a Matrix client into your app:
|
||||
Github Issues
|
||||
=============
|
||||
|
||||
* 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.
|
||||
All issues should be filed under https://github.com/vector-im/vector-web/issues
|
||||
for now.
|
||||
|
||||
OUTDATED: To Create Your Own Skin
|
||||
=================================
|
||||
|
||||
**This is ALL LIES currently, as skinning is currently broken - see the WARNING
|
||||
section at the top of this readme.**
|
||||
|
||||
Skins are modules are exported from such a package in the `lib` directory.
|
||||
`lib/skins` contains one directory per-skin, named after the skin, and the
|
||||
`modules` directory contains modules as their javascript files.
|
||||
|
||||
A basic skin is provided in the matrix-react-skin package. This also contains
|
||||
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
|
||||
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
|
||||
|
|
@ -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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue