Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 218 lines (151 sloc) 7.733 kB
292b400 @ndp more formatting README
authored
1 # Csster
f531da7 @ndp update readme with the intent
authored
2
bdbc77c @ndp add demos to the web
authored
3 Concisely generate CSS style rules within Javascript. Features:
4
27ae3c6 @ndp add demos to the web
authored
5 * standard "object literal"/JSON format with good editor support
bdbc77c @ndp add demos to the web
authored
6 * nesting to DRY up stylesheets
27ae3c6 @ndp add demos to the web
authored
7 * color functions like <code>darken</code> and <code>saturate</code>
8 * built-in macros for common CSS idioms like *clearfix*, *rounded corners*, *drop shadows*.
9 * and all the plain old Javascript behavior: functions, data structures, looping, Math operations, etc.
0bdd67f @ndp add demos to the web
authored
10
11
292b400 @ndp more formatting README
authored
12 ## Usage
06de1e3 @ndp rename README and try to format
authored
13
de891fa @ndp add demos to the web
authored
14 All code is packaged into a single Javascript file download, [csster.js](http://ndpsoftware.com/csster/csster.js). There are no external dependencies. The project itself is hosted on [GitHub](http://github.com/ndp/csster).
bdbc77c @ndp add demos to the web
authored
15
e1387e2 @ndp more formatting README
authored
16 <pre>
17 require('csster.js'); // however you manage dependencies
18
67b54b4 @ndp figure out how to insert styles into the document
authored
19 Csster.style({
e1387e2 @ndp more formatting README
authored
20 h1: {
21 fontSize: 18,
22 color: 'red'
23 }
24 });
25
26 ...
27 </pre>
28
b6d72d8 @ndp update readme
authored
29 Result, inserted in DOM automatically at the bottom of the &lt;head&gt; element:
30 <pre>
31 ...
e4cf475 @ndp update readme
authored
32 &lt;style type="text/stylesheet"&gt;
b6d72d8 @ndp update readme
authored
33 h1 {
34 font-size: 18px;
35 color: red;
36 }
e4cf475 @ndp update readme
authored
37 &lt;/style&gt;
38 &lt;/head&gt;
b6d72d8 @ndp update readme
authored
39 ...
40 </pre>
41
292b400 @ndp more formatting README
authored
42 ### Format of CSS Rules
5b6d112 @ndp more formatting README
authored
43
67b54b4 @ndp figure out how to insert styles into the document
authored
44 The *style* method accepts CSS rules passed either as arrays or hashes, arrays just being
de5d869 @ndp add some example documentation
authored
45 a way to order the hashes. For example:
46
47 <pre>
48 {
49 ul: {
cb8d55f @ndp update readme
authored
50 margin: 5,
51 padding: 0,
de5d869 @ndp add some example documentation
authored
52 }
5b6d112 @ndp more formatting README
authored
53 'ul li:first': {
cb8d55f @ndp update readme
authored
54 paddingLeft: 20px
de5d869 @ndp add some example documentation
authored
55 }
56 }
94279b6 @ndp add some example documentation
authored
57 </pre>
de5d869 @ndp add some example documentation
authored
58
59 Note that
588af51 @ndp more formatting README
authored
60
da7d664 @ndp update docs, move samples up,
authored
61 * property names are automatically converted to hyphenated format from camelcase, so in many cases you can omit the quotation marks. ('float' needs to quoted since it's a reserved word.)
f99a96e @ndp work on readme
authored
62 * all raw numbers are assumed to be "pixels" (or "px"), and rendered as such.
292b400 @ndp more formatting README
authored
63 * any sort of selectors are allowed... they are just passed through to the stylesheet.
64
65 #### Nesting
7726ab5 @ndp more formatting README
authored
66 Csster supports nesting of rules to keep things more concise:
de5d869 @ndp add some example documentation
authored
67 <pre>
68 {
69 ul: {
cb8d55f @ndp update readme
authored
70 margin: 5,
de5d869 @ndp add some example documentation
authored
71 li: {
80353b1 @ndp rename macro to has
authored
72 paddingLeft: 20,
73 '&:hover': {
74 color: 'red'
75 }
de5d869 @ndp add some example documentation
authored
76 }
77 }
78 }
94279b6 @ndp add some example documentation
authored
79 </pre>
de5d869 @ndp add some example documentation
authored
80
81 The "li" property in this case might be a selector or might be a property name. A list of valid
82 property names is used to identify properties right now, and otherwise it's considered a sub-selector.
83
80353b1 @ndp rename macro to has
authored
84 Csster supports SASS's "&" operator, to indicate that the selector should be combined with the parent selector.
85 Instead of the default "any descendent" space character being inserted, no space is inserted.
86
da7d664 @ndp update docs, move samples up,
authored
87 Combined rules (with commas) are expanded as expected, so nested rules with commas have their parents expanded.
88
89 By default, rules with multiple '#'s are simplified. For example, '#a #b #c' becomes '#c'. Usually this is what you will want, but if you need the specificity you can turn this off with <code>Csster.shortCircuitIds = false</code>
90
91
92
1703d0a @ndp update readme
authored
93 #### Functions
b50ec79 @ndp improve docs on functions
authored
94 Most manipulations will fall into Javascript's language support, as far as any math or looping. Use Javascript to write necessary functions.
80353b1 @ndp rename macro to has
authored
95
b50ec79 @ndp improve docs on functions
authored
96 function/color.js contains SASS-like color functions:
8f276b6 @ndp update readme
authored
97
b50ec79 @ndp improve docs on functions
authored
98 * <code>"#ab342c".darken(%)</code> -- make color darker by given percent
99 * <code>"#ab342c".lighten(%)</code> -- make color lighter by given percent
100 * <code>"#ab342c".saturate(%)</code> -- make color more saturated by given percent. To *desaturate*, use negative values for the percent. Note that <code>"#ab342c".saturate(-100)</code> renders in grayscale.
101
102 There are also color conversion routines if you want to build your own manipulation.
103
104 * <code>"#ab342c".toRGB()</code>
105 * <code>"#ab342c".toHSL()</code>
106 * <code>Csster.hslToHexColor(h,s,l)</code>
107
108 Opacity is currently not supported by the color model.
1703d0a @ndp update readme
authored
109
80353b1 @ndp rename macro to has
authored
110 #### Macros using "has" key
de5d869 @ndp add some example documentation
authored
111
717a1e3 @ndp work on readme
authored
112 There are a host of pre-made macros that may be useful:
113
114 * <code>roundedCorners(radius)</code> -- add rounded corners on all sides
115 * <code>roundedCorners(side, radius)</code> -- add rounded corners on specified side: <code>'top'</code>, <code>'left'</code>, <code>'bottom'</code> or <code>'right'</code>
116 * <code>roundedCorners(corner, radius)</code> -- add rounded corners to a specified corner: <code>'tl'</code>, <code>'tr'</code>, <code>'bl'</code> or <code>'br'</code>
117 * <code>phark(width, height, img, imgXPosition=0, imgYPosition=0)</code> -- standard phark image replacement with optional background image offset.
118 * <code>boxShadow([xoffset, yoffset], radius, color)</code>
119 * <code>verticalCentering(height)</code> and <code>horizontalCentering(width)</code> -- center using the top 50% / margin-top -width/2 technique. See http://stackoverflow.com/questions/148251/css-centering-tricks
f99a96e @ndp work on readme
authored
120 * <code>clearfix()</code> -- standard clearfix
de5d869 @ndp add some example documentation
authored
121
80353b1 @ndp rename macro to has
authored
122 To "mix these in", use the "has" key:
de5d869 @ndp add some example documentation
authored
123
124 <pre>
125 {
126 'div#featured_box': {
cb8d55f @ndp update readme
authored
127 backgroundColor: '#394c89',
128 has: roundedCorner(5)
de5d869 @ndp add some example documentation
authored
129 }
130 }
5b6d112 @ndp more formatting README
authored
131 </pre>
132
27ae3c6 @ndp add demos to the web
authored
133 Multiple macros can be included by making that a list, eg. <code>has: [roundedCorners(5), dropShadow()]</code>.
80353b1 @ndp rename macro to has
authored
134
717a1e3 @ndp work on readme
authored
135 It's all Javascript, so macros and more complex functions are easy to write. To mix in a set of values, create a function
136 that returns a hash of values, for example:
137
138 <pre>
139 function roundedCorners(radius) {
140 return {
141 '-webkit-border-radius': radius,
142 '-moz-border-radius': radius,
143 'border-radius': radius
144 }
145 }
146 </pre>
147
27ae3c6 @ndp add demos to the web
authored
148 A macro's properties will be overwritten by properties within including selector (or later included macros), similar to how the cascade takes the last defined value.
149
150
d883773 @ndp Add note about extending and contributing.
authored
151
152 ## Extending Csster
153
154 Csster is built as an extensible system.
155
7bb35d1 @ndp formatting
authored
156 ### Adding Custom Property Names
34efeab @ndp clarify docs
authored
157 Use <code>Csster.addPropertyNames</code> to add any non-standard property names you'd like to be considered valid. The build-in tool rejects non-standard property names, although by default popular "-moz" and "-webkit" properties are added.
d883773 @ndp Add note about extending and contributing.
authored
158
34efeab @ndp clarify docs
authored
159 ### Pre-process rules
160 Functions called before properties are processed stored in <code>Csster.propertyPreprocessors</code>. Callback is provided a hash of properties to values, which it modifies in any way it wants. This is used to interpret macros.
effb732 @ndp Document extensibility.
authored
161
7bb35d1 @ndp formatting
authored
162 ### Post-processing
34efeab @ndp clarify docs
authored
163 Functions called after rules are processed stored in <code>Csster.rulesPostProcessors</code>. Called with an array of processed rules. Can be used to eliminate duplicates, modify selectors, etc. Standard list simplifies overly complex selectors with multiple IDs.
effb732 @ndp Document extensibility.
authored
164
7bb35d1 @ndp formatting
authored
165 ### Inserting into the DOM
34efeab @ndp clarify docs
authored
166 Function that outputs a set of rules into the DOM is <code>Csster.insertStylesheet</code> and can be replaced if desired.
d883773 @ndp Add note about extending and contributing.
authored
167
168 ## Contributing
169
170 Fork and submit changed back on Github.
171
172
69363d2 @ndp update links
authored
173 ## Links
174
175 * [Demo of the color functions and macros](http://ndpsoftware.com/csster/demo.html)
176 * [Demo of using to build a chart](http://ndpsoftware.com/csster/demo_chart.html)
177 * [Blog post](http://ndpsoft.blogspot.com/2010/09/introducing-csster.html)
178
179
180
632baa2 @ndp add demos to the web
authored
181
b5f9f8b @ndp add demos to the web
authored
182 ## TDD
632baa2 @ndp add demos to the web
authored
183
27ae3c6 @ndp add demos to the web
authored
184 The design was driven by [the specs](http://ndpsoftware.com/csster/spec_runner.html).
80353b1 @ndp rename macro to has
authored
185
de5d869 @ndp add some example documentation
authored
186
292b400 @ndp more formatting README
authored
187 ## Todo
de5d869 @ndp add some example documentation
authored
188
c56959d @ndp add centering and clearfix
authored
189 * decompile existing stylesheets
190 * jQuery rules
ee77c60 @ndp start to add color functions
authored
191 * Fix license
5b6d112 @ndp more formatting README
authored
192 * Better name
06de1e3 @ndp rename README and try to format
authored
193
194
ee77c60 @ndp start to add color functions
authored
195
292b400 @ndp more formatting README
authored
196 ## Motivation
f531da7 @ndp update readme with the intent
authored
197
198 This project comes from my frustration of trying to build standalone Javascript widgets. Web
199 projects always involve the combination of HTML DOM, CSS and Javascript. It's often simpler to
200 generate the necessary DOM within your Javascript, removing any coupling (and a simpler calling
201 convention) to a specific web page. But most widgets have certain style rules. To avoid
202 any coupling with the CSS at all, styles can be included inline, but these gets bulky
203 and hard to read. The "rule" nature of CSS is nice. So widgets then have a Javascript
204 and CSS component. Wouldn't it be nice, though, to remove that CSS component.
205
206 With the advent of SASS, the coupling is even more complicated, as now there's some other
207 tool completely unrelated to your component, written in some other language. Wouldn't
208 a unified approach be nice?
209
210
292b400 @ndp more formatting README
authored
211 ## Similar projects
de5d869 @ndp add some example documentation
authored
212
06de1e3 @ndp rename README and try to format
authored
213 http://revnode.com/oss/css/
214
292b400 @ndp more formatting README
authored
215 ## Legal
de5d869 @ndp add some example documentation
authored
216
06de1e3 @ndp rename README and try to format
authored
217 Copyright (c) 2010 Andrew J. Peterson
218 All Rights Reserved.
Something went wrong with that request. Please try again.