From a8677b52adb6e30dfc3eb35d48e9eb758425b32e Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Mon, 11 Jul 2016 18:26:16 +0100 Subject: [PATCH] major update to dev guidelines --- README.md | 180 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 113 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index ae1cd17c9a..dfc1a6e6ec 100644 --- a/README.md +++ b/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 - * The containing application +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. - - * 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. - - * 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. +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: +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: - * Views are named with upper camel case (e.g. molecules/MessageTile.js) + * Components are named with upper camel case (e.g. views/rooms/EventTile.js) - * The view's CSS file MUST have the same name (e.g. molecules/MessageTile.css) + * 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 + 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. + the context of the rest of the app, although this is unusual for any but + 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. +