Skip to content

Commit 15c93b6

Browse files
ara4nara4n
committed
try to write down the various naming & architectural conventions that the SDK adheres to...
1 parent 0b20785 commit 15c93b6

1 file changed

Lines changed: 83 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,86 @@ react from your app) you must be sure to:
3939
2. If you `npm link` matrix-react-sdk, manually remove the 'react' directory
4040
from matrix-react-sdk's `node_modules` folder, otherwise browserify will
4141
pull in both copies of react which causes the app to break.
42+
43+
How to customise the SDK
44+
========================
45+
46+
The matrix-react-sdk has been built to be heavily customisable - letting
47+
developers both create new skins by extending/overriding the CSS and View
48+
classes provided in the base skin, as well as entirely replacing components as
49+
required.
50+
51+
The SDK uses the 'atomic' design pattern as seen at http://patternlab.io to
52+
encourage a very modular and reusable architecture, making it as easy to
53+
customise and use UI widgets independently of the rest of the SDK and your app.
54+
In practice this means:
55+
56+
* The UI of the app is strictly split up into a hierarchy of components.
57+
58+
* Each component has its own:
59+
* View object defined as a React javascript class containing embedded
60+
HTML expressed in React's JSX notation.
61+
* CSS file, which defines the styling specific to that component.
62+
63+
* Components are loosely grouped into the 5 levels outlined by atomic design:
64+
* atoms: fundamental building blocks (e.g. a timestamp tag)
65+
* molecules: "group of atoms which functions together as a unit"
66+
(e.g. a message in a chat timeline)
67+
* organisms: "groups of molecules (and atoms) which form a distinct section
68+
of a UI" (e.g. a view of a chat room)
69+
* templates: "a reusable configuration of organisms" - used to combine and
70+
style organisms into a well-defined global look and feel
71+
* pages: specific instances of templates.
72+
73+
Good separation between the components is maintained by adopting various best
74+
practices that anyone working with the SDK needs to be be aware of and uphold:
75+
76+
* Views are named with upper camel case (e.g. molecules/MessageTile.js)
77+
78+
* The view's CSS file MUST have the same name (e.g. molecules/MessageTile.css)
79+
80+
* Per-view CSS is optional - it could choose to inherit all its styling from
81+
the context of the rest of the app, although this is unusual for any but
82+
the simplest atoms and molecules.
83+
84+
* The view MUST *only* refer to the CSS rules defined in its own CSS file.
85+
'Stealing' styling information from other components (including parents)
86+
is not cool, as it breaks the independence of the components.
87+
88+
* CSS classes are named with an app-specific namespacing prefix to try to avoid
89+
CSS collisions. The base skin shipped by Matrix.org with the matrix-react-sdk
90+
uses the naming prefix "mx_". A company called Yoyodyne Inc might use a
91+
prefix like "yy_" for its app-specific classes.
92+
93+
* CSS classes use upper camel case when they describe React components - e.g.
94+
.mx_MessageTile is the selector for the CSS applied to a MessageTile view.
95+
96+
* CSS classes for DOM elements within a view which aren't components are named
97+
by appending a lower camel case identifier to the view's class name - e.g.
98+
.mx_MessageTile_randomDiv is how you'd name the class of an arbitrary div
99+
within the MessageTile view.
100+
101+
* We deliberately use vanilla CSS 3.0 to avoid adding any more magic
102+
dependencies into the mix than we already have. App developers are welcome
103+
to use whatever floats their boat however.
104+
105+
* The CSS for a component can however override the rules for child components.
106+
For instance, .mx_RoomList .mx_RoomTile {} would be the selector to override
107+
styles of RoomTiles when viewed in the context of a RoomList view.
108+
Overrides *must* be scoped to the View's CSS class - i.e. don't just define
109+
.mx_RoomTile {} in RoomList.css - only RoomTile.css is allowed to define its
110+
own CSS. Instead, say .mx_RoomList .mx_RoomTile {} to scope the override
111+
only to the context of RoomList views. N.B. overrides should be relatively
112+
rare as in general CSS inheritence should be enough.
113+
114+
* Components should render only within the bounding box of their outermost DOM
115+
element. Page-absolute positioning and negative CSS margins and similar are
116+
generally not cool and stop the component from being reused easily in
117+
different places.
118+
119+
* We don't use the atomify library itself, as React already provides most
120+
of the modularity requirements it brings to the table.
121+
122+
With all this in mind, here's how you go about skinning the react SDK UI
123+
components to embed a Matrix client into your app: TODO. For now, check out
124+
the examples and work it out for yourself...

0 commit comments

Comments
 (0)