matrix-react-sdk

This is a react-based SDK for inserting a Matrix chat client into a web page

Getting started with the trivial example

1. Install or update node.js so that your npm is at least at version 2.0.0
2. Clone the repo: git clone https://github.com/matrix-org/matrix-react-sdk.git
3. Switch to the SDK directory: cd matrix-react-sdk
4. Install the prerequisites: npm install
5. Switch to the example directory: cd examples/trivial
6. Install the example app prerequisites: npm install
7. Build the example and start a server: npm start

Now open http://127.0.0.1:8080/ in your browser to see your newly built Matrix client.

Using the example app for development

To work on the CSS and Javascript and have the bundle files update as you change the source files, you'll need to do two extra things:

1. Link the react sdk package into the example: cd matrix-react-sdk/examples/trivial; npm link ../../
2. Start a watcher for the CSS files: cd matrix-react-sdk; npm run start:css

Note that you may need to restart the CSS builder if you add a new file. Note that npm start builds debug versions of the the javascript and CSS, which are much larger than the production versions build by the npm run build commands.

IMPORTANT: If you customise components in your application (and hence require react from your app) you must be sure to:

1. Make your app depend on react directly
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 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.

• "Skins" refer to a suite of components (views and css) which define the look and feel of the Matrix UI used in the target app. We provide a 'base' skin in skins/base which provides generic plain UI for typical chat functions. To change the look and feel to embed the SDK into your own app, users can define a new skin which inherits from the base one, or override components in the app itself. TODO: spell out how.

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...