Skip to content

Commit 6da74c1

Browse files
committed
update docs
1 parent c2458a4 commit 6da74c1

File tree

1 file changed

+90
-76
lines changed

1 file changed

+90
-76
lines changed

api.md

Lines changed: 90 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -247,7 +247,50 @@ var stylesheet = require('...').register({
247247

248248
Sections
249249
----------
250-
### Styleset Path Selectors
250+
### Usage
251+
#### Creating a stylesheet
252+
The [register](#project/jhudson8/react-css-builder/method/react-css-builder/register) method is used to create a new stylesheet that can be used.
253+
254+
```
255+
module.exports = require('react-css-builder').register('optional-namespace', {
256+
// include any stylesets
257+
myCssClass: {
258+
color: 'white'
259+
}
260+
```
261+
262+
#### Styleset Definitions
263+
We're using "styleset" as the term for attributes given to a specific CSS class. Stylesets can be implemented in 3 different ways
264+
265+
Standard attributes
266+
```
267+
myClass: {
268+
border: 'solid 1px #000'
269+
}
270+
```
271+
272+
Function returning standard attributes
273+
```
274+
// we might do this if we want to access variables
275+
myClass: function() {
276+
border: this.get('border')
277+
}
278+
```
279+
280+
Function which returns results from a [StyleContext](#project/jhudson8/react-css-builder/package/StyleContext)
281+
```
282+
// we might do this if we want to include other stylesets or use mixins
283+
myClass: function(css) {
284+
return css
285+
.mixin(...)
286+
.include(...)
287+
.attr(...)
288+
.val();
289+
}
290+
```
291+
292+
293+
#### Styleset Path Selectors
251294
Multiple stylesets can be included with a single styleset reference.
252295

253296
* Each styleset reference should be separated with a space or comma.
@@ -284,96 +327,67 @@ Matching a stylesheet like the following
284327
```
285328

286329

287-
### Examples
288-
289-
#### Registering mixins and variables
290-
```
291-
var css = require('react-css-builder');
330+
#### Mixins
331+
See [Mixins API](#project/jhudson8/react-css-builder/method/react-css-builder/mixin) to understand how to register mixins
292332

293-
// the mixin can have any number of arguments provided when the mixin is referenced
294-
css.mixin('vendor-prefix', function(name, value) {
333+
Mixins can return any number of attributes that should be applied to a styleset.
295334

296-
// for example only, a smarter impl would eval the user agent to include the appropriate prefix
297-
var rtn = {};
298-
// if you have underscore
299-
_.each(['O', 'Webkit', 'ms', 'Moz'], function(prefix) {
300-
rtn[prefix + name] = value;
301-
});
302-
rtn[name] = value;
303-
return rtn;
304-
});
335+
```
336+
var stylesheet = require('react-css-builder').register({
305337
306-
// add variables that can be referenced in stylesets using this.get("varName");
307-
css.vars({
308-
foo: 'bar'
338+
myClassUsingMixins: function(css) {
339+
return css
340+
.mixin('the-mixin-name', param1, param2, ...)
341+
.attr({
342+
// include any additional attributes
343+
})
344+
.val();
345+
}
309346
});
310347
```
311348

312-
#### Creating a stylesheet
313-
```
314-
module.exports = require('react-css-builder').register('my-namespace', {
315-
// use javascript-style humpback CSS here
316-
myCssClass: {
317-
color: 'white'
318-
},
319349

320-
fancierCssClass: function(css) {
321-
return css
322-
// include the attributes from the "myCssClass" (in this namespace / css file)
323-
.include('myCssClass')
324-
325-
// include the attributes from a class in another namespace (1st param to register method)
326-
.include('another-namespace.anotherCssClass')
327-
328-
// include attributes from a mixin (vendor-prefix example can be seen later)
329-
.mixin('vendor-prefix', 'border-radius', 3)
330-
331-
// add attitional styles
332-
.val({
333-
// you can reference global or class reference variables
334-
background-color: this.get('backgroundColor'),
335-
// or just use simple attributes
336-
backgroundImage: ...
337-
})
338-
},
350+
#### Variables
351+
See [Variables API](#project/jhudson8/react-css-builder/method/react-css-builder/vars) to understand how to register variables
339352

340-
simpleReferenceTimeExecutionClass: function() {
341-
// if don't need any registered variables or mixin use but just want to evaluate
342-
// something when the styleset is referenced
343-
return {
344-
height: window.innerHeight + 'px'
345-
};
346-
}
347-
})
353+
Variables can be referenced in a styleset definition using ```this.get("varName")```
348354
```
355+
var stylesheet = require('react-css-builder').register({
349356
350-
#### Using Class References
351-
```
352-
// eager fetch the styleset if possible
353-
var stylesheet = require('path/to/my/css/file');
357+
myClassUsingMixins: function() {
358+
return {
359+
border: this.get('border')
360+
}
361+
}
362+
});
354363
355-
// simple styleset reference with no variables or additional attributes
356-
var simpleStyleset = css.css('myCssClass');
364+
// variables can be set globally
365+
require('react-css-builder').vars({ border: 'solid 2px #000'});
357366
358-
// to provide variables and/or additional attributes (notice the method is "get" instead of "css")
359-
var advancedStyleset = stylesheet.get('fancierCssClass')
367+
// variables can be set on a specific stylesheet
368+
stylesheet.vars({ border: 'solid 2px #000'});
369+
370+
// variables can be set when referencing the styleset directly
371+
var myStyle = stylesheet.get('myClassUsingMixins').vars({ border: 'solid 2px #000'}).css();
372+
```
360373

361-
// add variables that can be referenced using this.get("varName")
362-
.vars({
363-
border: 1
364-
})
365374

366-
// add additional attributes defined here
367-
.attr({
368-
fontFamily: 'arial'
369-
})
375+
#### Includes
376+
It is possible to merge other styleset attributes using ```include```. Stylesets can be referenced in the current stylesheet or in another stylesheet if the styleset name is prefixed with a ```.```.
377+
```
378+
var stylesheet = require('react-css-builder').register({
370379
371-
// get the styleset (now we use the "css" function)
372-
.css();
380+
someOtherClass: {
381+
width: '100%'
382+
},
373383
374-
...
375-
render: function() {
376-
return <div style={advancedStyleset}>Hello</div>
384+
myClassWithIncludes: function(css) {
385+
return css
386+
.include('someOtherClass')
387+
.attr({
388+
// include any additional attributes
389+
})
390+
.val();
377391
}
378-
}
392+
});
379393
```

0 commit comments

Comments
 (0)