@@ -10,145 +10,33 @@ Getting started
10102 . Clone the repo: ` git clone https://github.com/vector-im/vector-web.git `
11113 . Switch to the SDK directory: ` cd vector-web `
12124 . Install the prerequisites: ` npm install `
13- 5 . Switch to the example directory : ` cd examples/vector `
14- 6 . Install the example app prerequisites: ` npm install `
15- 7 . Build the example and start a server: ` npm start `
13+ 5 . Start the development builder and a testing server : ` npm start `
14+ 6 . Wait a few seconds for the initial build to finish.
15+ 7 . Open http://127.0.0.1:8080/ in your browser to see your newly built Vector.
1616
17- Now open http://127.0.0.1:8080/ in your browser to see your newly built
18- Vector.
17+ With ` npm start ` , any changes you make to the source files will cause a rebuild so
18+ your changes will show up when you refresh.
19+
20+ For production use, run ` npm run build ` to build all the necessary files
21+ into the ` vector ` directory and run your own server.
1922
2023Development
2124===========
22-
23- To work on the CSS and Javascript and have the bundle files update as you
24- change the source files , you'll need to do two extra things :
25+ You can work on any of the source files within Vector with the setup above,
26+ and your changes will cause an instant rebuild. If you also need to make
27+ changes to the react sdk , you can :
2528
26291 . Link the react sdk package into the example:
27- ` cd vector-web/examples/vector; npm link ../../ `
28- 2 . Start a watcher for the CSS files:
29- ` cd vector-web; npm run start:css `
30-
31- Note that you may need to restart the CSS builder if you add a new file. Note
32- that ` npm start ` builds debug versions of the javascript and CSS, which are
33- much larger than the production versions build by the ` npm run build ` commands.
30+ ` npm link path/to/your/react/sdk `
31+ 2 . Start the development rebuilder in your react SDK directory:
32+ ` npm start `
3433
35- IMPORTANT: If you customise components in your application (and hence require
36- react from your app) you must be sure to:
37-
38- 1 . Make your app depend on react directly
39- 2 . If you ` npm link ` matrix-react-sdk, manually remove the 'react' directory
40- from matrix-react-sdk's ` node_modules ` folder, otherwise browserify will
41- pull in both copies of react which causes the app to break.
34+ If you add or remove any components from the Vector skin, you will need to rebuild
35+ the skin's index by running, ` npm run reskindex ` .
4236
4337Deployment
4438==========
4539
46- Just run ` npm build ` in the ` examples/vector ` directory, and then mount the
47- ` examples/vector ` directory on your webserver to actually serve up the app,
48- which is entirely static content.
49-
50- How to customise the SDK
51- ========================
52-
53- The matrix-react-sdk provides well-defined reusable UI components which may be
54- customised/replaced by the developer to build into an app. A set of consistent
55- UI components (View + CSS classes) is called a 'skin' - currently the SDK
56- provides a very vanilla whitelabelled 'base skin'. In future the SDK could
57- provide alternative skins (probably by extending the base skin) that provide more
58- specific look and feels (e.g. "IRC-style", "Skype-style") etc. However, unlike
59- Wordpress themes and similar, we don't normally expect app developers to define
60- reusable skins. Instead you just go and incorporate your view customisations
61- into your actual app.
62-
63- The SDK uses the 'atomic' design pattern as seen at http://patternlab.io to
64- encourage a very modular and reusable architecture, making it easy to
65- customise and use UI widgets independently of the rest of the SDK and your app.
66- In practice this means:
67-
68- * The UI of the app is strictly split up into a hierarchy of components.
69-
70- * Each component has its own:
71- * View object defined as a React javascript class containing embedded
72- HTML expressed in React's JSX notation.
73- * CSS file, which defines the styling specific to that component.
74-
75- * Components are loosely grouped into the 5 levels outlined by atomic design:
76- * atoms: fundamental building blocks (e.g. a timestamp tag)
77- * molecules: "group of atoms which functions together as a unit"
78- (e.g. a message in a chat timeline)
79- * organisms: "groups of molecules (and atoms) which form a distinct section
80- of a UI" (e.g. a view of a chat room)
81- * templates: "a reusable configuration of organisms" - used to combine and
82- style organisms into a well-defined global look and feel
83- * pages: specific instances of templates.
84-
85- Good separation between the components is maintained by adopting various best
86- practices that anyone working with the SDK needs to be be aware of and uphold:
87-
88- * Views are named with upper camel case (e.g. molecules/MessageTile.js)
89-
90- * The view's CSS file MUST have the same name (e.g. molecules/MessageTile.css)
91-
92- * Per-view CSS is optional - it could choose to inherit all its styling from
93- the context of the rest of the app, although this is unusual for any but
94- the simplest atoms and molecules.
95-
96- * The view MUST * only* refer to the CSS rules defined in its own CSS file.
97- 'Stealing' styling information from other components (including parents)
98- is not cool, as it breaks the independence of the components.
99-
100- * CSS classes are named with an app-specific namespacing prefix to try to avoid
101- CSS collisions. The base skin shipped by Matrix.org with the matrix-react-sdk
102- uses the naming prefix "mx_ ". A company called Yoyodyne Inc might use a
103- prefix like "yy_ " for its app-specific classes.
104-
105- * CSS classes use upper camel case when they describe React components - e.g.
106- .mx_MessageTile is the selector for the CSS applied to a MessageTile view.
107-
108- * CSS classes for DOM elements within a view which aren't components are named
109- by appending a lower camel case identifier to the view's class name - e.g.
110- .mx_MessageTile_randomDiv is how you'd name the class of an arbitrary div
111- within the MessageTile view.
112-
113- * We deliberately use vanilla CSS 3.0 to avoid adding any more magic
114- dependencies into the mix than we already have. App developers are welcome
115- to use whatever floats their boat however.
116-
117- * The CSS for a component can however override the rules for child components.
118- For instance, .mx_RoomList .mx_RoomTile {} would be the selector to override
119- styles of RoomTiles when viewed in the context of a RoomList view.
120- Overrides * must* be scoped to the View's CSS class - i.e. don't just define
121- .mx_RoomTile {} in RoomList.css - only RoomTile.css is allowed to define its
122- own CSS. Instead, say .mx_RoomList .mx_RoomTile {} to scope the override
123- only to the context of RoomList views. N.B. overrides should be relatively
124- rare as in general CSS inheritence should be enough.
125-
126- * Components should render only within the bounding box of their outermost DOM
127- element. Page-absolute positioning and negative CSS margins and similar are
128- generally not cool and stop the component from being reused easily in
129- different places.
130-
131- * We don't use the atomify library itself, as React already provides most
132- of the modularity requirements it brings to the table.
133-
134- With all this in mind, here's how you go about skinning the react SDK UI
135- components to embed a Matrix client into your app:
136-
137- * Create a new NPM project. Be sure to directly depend on react, (otherwise
138- you can end up with two copies of react).
139- * Create an index.js file that sets up react. Add require statements for
140- React, the ComponentBroker and matrix-react-sdk and a call to Render
141- the root React element as in the examples.
142- * Create React classes for any custom components you wish to add. These
143- can be based off the files in ` views ` in the ` matrix-react-sdk ` package,
144- modifying the require() statement appropriately.
145- You only need to copy files you want to customise.
146- * Add a ComponentBroker.set() call for each of your custom components. These
147- must come * before* ` require("matrix-react-sdk") ` .
148- * Add a way to build your project: we suggest copying the browserify calls
149- from the example projects, but you could use grunt or gulp.
150- * Create an index.html file pulling in your compiled index.js file, the
151- CSS bundle from matrix-react-sdk.
40+ Just run ` npm build ` and then mount the ` vector ` directory on your webserver to
41+ actually serve up the app, which is entirely static content.
15242
153- For more specific detail on any of these steps, look at the ` custom ` example in
154- matrix-react-sdk/examples.
0 commit comments