From 15c93b61aa12dda8e096246939ca64338f971927 Mon Sep 17 00:00:00 2001 From: Matthew Hodgson Date: Tue, 7 Jul 2015 17:46:06 +0100 Subject: [PATCH] try to write down the various naming & architectural conventions that the SDK adheres to... --- README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/README.md b/README.md index 96b287ecb8..270269a8f2 100644 --- a/README.md +++ b/README.md @@ -39,3 +39,86 @@ react from your app) you must be sure to: 2. If you `npm link` matrix-react-sdk, manually remove the 'react' directory from matrix-react-sdk's `node_modules` folder, otherwise browserify will pull in both copies of react which causes the app to break. + +How to customise the SDK +======================== + +The matrix-react-sdk has been built to be heavily customisable - letting +developers both create new skins by extending/overriding the CSS and View +classes provided in the base skin, as well as entirely replacing components as +required. + +The SDK uses the 'atomic' design pattern as seen at http://patternlab.io to +encourage a very modular and reusable architecture, making it as easy to +customise and use UI widgets independently of the rest of the SDK and your app. +In practice this means: + + * 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. + + 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) + + * The view's CSS file MUST have the same name (e.g. molecules/MessageTile.css) + + * 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 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 + to use whatever floats their boat however. + + * The CSS for a component can however 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. + + * We don't use the atomify library itself, as React already provides most + of the modularity requirements it brings to the table. + +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: TODO. For now, check out +the examples and work it out for yourself... \ No newline at end of file