Skip to content
Newer
Older
100644 281 lines (192 sloc) 9.5 KB
292b400 @ndp more formatting README
authored Sep 11, 2010
1 # Csster
f531da7 @ndp update readme with the intent
authored Sep 10, 2010
2
bdbc77c @ndp add demos to the web
authored Sep 24, 2010
3 Concisely generate CSS style rules within Javascript. Features:
4
27ae3c6 @ndp add demos to the web
authored Sep 24, 2010
5 * standard "object literal"/JSON format with good editor support
bdbc77c @ndp add demos to the web
authored Sep 25, 2010
6 * nesting to DRY up stylesheets
27ae3c6 @ndp add demos to the web
authored Sep 25, 2010
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*.
4c0cb01 @ndp add comment about extensibility
authored Oct 30, 2010
9 * extension points for custom behavior or cross-browser support.
27ae3c6 @ndp add demos to the web
authored Sep 25, 2010
10 * and all the plain old Javascript behavior: functions, data structures, looping, Math operations, etc.
0bdd67f @ndp add demos to the web
authored Sep 24, 2010
11
a5e3820 @ndp link to slide show
authored Jul 22, 2011
12 Slideshow introduction: https://docs.google.com/present/view?id=dfm357b6_49c4d3fpdm&interval=15
13
0bdd67f @ndp add demos to the web
authored Sep 25, 2010
14
292b400 @ndp more formatting README
authored Sep 11, 2010
15 ## Usage
06de1e3 @ndp rename README and try to format
authored Sep 11, 2010
16
415732e @ndp try a gem for csster
authored May 25, 2012
17
18 ### Rails/Bundler Installation
19
20 Add this line to your application's Gemfile:
21
22 gem 'csster'
23
24 And then execute:
25
26 $ bundle
27
28 Or install it yourself as:
29
30 $ gem install csster
31
32
2f8b837 @ndp Add NPM package.json file, and add comments and build steps.
authored Jan 30, 2012
33 ### Node NPM Install
34
35 <pre>npm install csster</pre>
36
415732e @ndp try a gem for csster
authored May 26, 2012
37 ### Manual Install for Browser Client
2f8b837 @ndp Add NPM package.json file, and add comments and build steps.
authored Jan 31, 2012
38
de891fa @ndp add demos to the web
authored Sep 24, 2010
39 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 Sep 25, 2010
40
e1387e2 @ndp more formatting README
authored Sep 11, 2010
41 <pre>
42 require('csster.js'); // however you manage dependencies
43
67b54b4 @ndp figure out how to insert styles into the document
authored Sep 11, 2010
44 Csster.style({
e1387e2 @ndp more formatting README
authored Sep 11, 2010
45 h1: {
46 fontSize: 18,
47 color: 'red'
48 }
49 });
50
51 ...
52 </pre>
53
b6d72d8 @ndp update readme
authored Sep 13, 2010
54 Result, inserted in DOM automatically at the bottom of the &lt;head&gt; element:
55 <pre>
56 ...
e4cf475 @ndp update readme
authored Sep 13, 2010
57 &lt;style type="text/stylesheet"&gt;
b6d72d8 @ndp update readme
authored Sep 13, 2010
58 h1 {
59 font-size: 18px;
60 color: red;
61 }
e4cf475 @ndp update readme
authored Sep 13, 2010
62 &lt;/style&gt;
63 &lt;/head&gt;
b6d72d8 @ndp update readme
authored Sep 13, 2010
64 ...
65 </pre>
66
292b400 @ndp more formatting README
authored Sep 11, 2010
67 ### Format of CSS Rules
5b6d112 @ndp more formatting README
authored Sep 11, 2010
68
67b54b4 @ndp figure out how to insert styles into the document
authored Sep 11, 2010
69 The *style* method accepts CSS rules passed either as arrays or hashes, arrays just being
de5d869 @ndp add some example documentation
authored Sep 11, 2010
70 a way to order the hashes. For example:
71
72 <pre>
73 {
74 ul: {
cb8d55f @ndp update readme
authored Sep 18, 2010
75 margin: 5,
76 padding: 0,
de5d869 @ndp add some example documentation
authored Sep 11, 2010
77 }
5b6d112 @ndp more formatting README
authored Sep 11, 2010
78 'ul li:first': {
cb8d55f @ndp update readme
authored Sep 18, 2010
79 paddingLeft: 20px
de5d869 @ndp add some example documentation
authored Sep 11, 2010
80 }
81 }
94279b6 @ndp add some example documentation
authored Sep 11, 2010
82 </pre>
de5d869 @ndp add some example documentation
authored Sep 11, 2010
83
84 Note that
588af51 @ndp more formatting README
authored Sep 11, 2010
85
da7d664 @ndp update docs, move samples up,
authored Sep 27, 2010
86 * 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 Sep 24, 2010
87 * all raw numbers are assumed to be "pixels" (or "px"), and rendered as such.
292b400 @ndp more formatting README
authored Sep 11, 2010
88 * any sort of selectors are allowed... they are just passed through to the stylesheet.
89
90 #### Nesting
7726ab5 @ndp more formatting README
authored Sep 11, 2010
91 Csster supports nesting of rules to keep things more concise:
de5d869 @ndp add some example documentation
authored Sep 11, 2010
92 <pre>
93 {
94 ul: {
cb8d55f @ndp update readme
authored Sep 18, 2010
95 margin: 5,
de5d869 @ndp add some example documentation
authored Sep 11, 2010
96 li: {
80353b1 @ndp rename macro to has
authored Sep 18, 2010
97 paddingLeft: 20,
98 '&:hover': {
99 color: 'red'
100 }
de5d869 @ndp add some example documentation
authored Sep 11, 2010
101 }
102 }
103 }
94279b6 @ndp add some example documentation
authored Sep 11, 2010
104 </pre>
de5d869 @ndp add some example documentation
authored Sep 11, 2010
105
106 The "li" property in this case might be a selector or might be a property name. A list of valid
107 property names is used to identify properties right now, and otherwise it's considered a sub-selector.
108
80353b1 @ndp rename macro to has
authored Sep 18, 2010
109 Csster supports SASS's "&" operator, to indicate that the selector should be combined with the parent selector.
110 Instead of the default "any descendent" space character being inserted, no space is inserted.
111
da7d664 @ndp update docs, move samples up,
authored Sep 28, 2010
112 Combined rules (with commas) are expanded as expected, so nested rules with commas have their parents expanded.
113
114
115
116
1703d0a @ndp update readme
authored Sep 13, 2010
117 #### Functions
b50ec79 @ndp improve docs on functions
authored Sep 19, 2010
118 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 Sep 18, 2010
119
b50ec79 @ndp improve docs on functions
authored Sep 20, 2010
120 function/color.js contains SASS-like color functions:
8f276b6 @ndp update readme
authored Sep 18, 2010
121
b50ec79 @ndp improve docs on functions
authored Sep 20, 2010
122 * <code>"#ab342c".darken(%)</code> -- make color darker by given percent
123 * <code>"#ab342c".lighten(%)</code> -- make color lighter by given percent
124 * <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.
125
126 There are also color conversion routines if you want to build your own manipulation.
127
128 * <code>"#ab342c".toRGB()</code>
129 * <code>"#ab342c".toHSL()</code>
130 * <code>Csster.hslToHexColor(h,s,l)</code>
131
132 Opacity is currently not supported by the color model.
1703d0a @ndp update readme
authored Sep 13, 2010
133
80353b1 @ndp rename macro to has
authored Sep 18, 2010
134 #### Macros using "has" key
de5d869 @ndp add some example documentation
authored Sep 11, 2010
135
717a1e3 @ndp work on readme
authored Sep 24, 2010
136 There are a host of pre-made macros that may be useful:
137
138 * <code>roundedCorners(radius)</code> -- add rounded corners on all sides
139 * <code>roundedCorners(side, radius)</code> -- add rounded corners on specified side: <code>'top'</code>, <code>'left'</code>, <code>'bottom'</code> or <code>'right'</code>
140 * <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>
e93f710 @ndp Rename phark to imageReplacement, per Kevin Fitzpatrick.
authored Nov 14, 2010
141 * <code>imageReplacement(width, height, img, imgXPosition=0, imgYPosition=0)</code> -- phark image replacement with optional background image offset.
717a1e3 @ndp work on readme
authored Sep 25, 2010
142 * <code>boxShadow([xoffset, yoffset], radius, color)</code>
143 * <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 Sep 25, 2010
144 * <code>clearfix()</code> -- standard clearfix
de5d869 @ndp add some example documentation
authored Sep 11, 2010
145
80353b1 @ndp rename macro to has
authored Sep 18, 2010
146 To "mix these in", use the "has" key:
de5d869 @ndp add some example documentation
authored Sep 11, 2010
147
148 <pre>
149 {
150 'div#featured_box': {
cb8d55f @ndp update readme
authored Sep 18, 2010
151 backgroundColor: '#394c89',
152 has: roundedCorner(5)
de5d869 @ndp add some example documentation
authored Sep 11, 2010
153 }
154 }
5b6d112 @ndp more formatting README
authored Sep 11, 2010
155 </pre>
156
27ae3c6 @ndp add demos to the web
authored Sep 25, 2010
157 Multiple macros can be included by making that a list, eg. <code>has: [roundedCorners(5), dropShadow()]</code>.
80353b1 @ndp rename macro to has
authored Sep 18, 2010
158
717a1e3 @ndp work on readme
authored Sep 25, 2010
159 It's all Javascript, so macros and more complex functions are easy to write. To mix in a set of values, create a function
160 that returns a hash of values, for example:
161
162 <pre>
163 function roundedCorners(radius) {
164 return {
165 '-webkit-border-radius': radius,
166 '-moz-border-radius': radius,
167 'border-radius': radius
168 }
169 }
170 </pre>
171
27ae3c6 @ndp add demos to the web
authored Sep 25, 2010
172 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.
173
174
e764fbf @ndp add jQuery plugin
authored Dec 23, 2010
175 ## jQuery Integration
176
177 If jQuery is loaded first, Csster provides a "csster" method:
178
179 <pre>
180 $('.sidebar').csster({ border: '5px solid green', padding: 10 });
181 </pre>
182
183 As expected, this adds a rule to the document with the ".sidebar" selector.
184 In general, this can be called identically to the <code>css()</code> function.
185 This is useful is the DOM on the page is dynamic and when a rule is more efficient than applying
186 a style repeatedly to all the DOM nodes.
187
188 There are a few limitations: Currently a "context" is not supported.
189 And be careful, since not all jQuery selectors are valid CSS selectors--
190 nothing is done to convert or report unsupported selectors (just like regular CSS).
d883773 @ndp Add note about extending and contributing.
authored Oct 10, 2010
191
192 ## Extending Csster
193
194 Csster is built as an extensible system.
195
7bb35d1 @ndp formatting
authored Oct 10, 2010
196 ### Adding Custom Property Names
34efeab @ndp clarify docs
authored Oct 10, 2010
197 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 Oct 11, 2010
198
34efeab @ndp clarify docs
authored Oct 11, 2010
199 ### Pre-process rules
200 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 Oct 10, 2010
201
7bb35d1 @ndp formatting
authored Oct 11, 2010
202 ### Post-processing
34efeab @ndp clarify docs
authored Oct 11, 2010
203 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 Oct 11, 2010
204
89e7fb7 @ndp Pull out optional functionality.
authored Oct 18, 2010
205 A convenient built-in function is <code>compressSelectors</code>. Using this processor, rules with multiple '#'s are simplified. For example, '#a #b #c' becomes '#c'. Usually this is what you will want, so include it with <code>Csster.rulePostProcessors.push(Csster.compressSelectors);</code>.
206
e764fbf @ndp add jQuery plugin
authored Dec 24, 2010
207 This is used to write custom browser overrides. For example, this one makes opacity work for IE:
208
209 <pre>
210 Csster.rulesPostProcessors.push(function ieOpacity(rules) {
211 // http://www.smashingmagazine.com/2010/04/28/css3-solutions-for-internet-explorer/
212 if (Csster.browser.msie) {
6e58d7f @ndp formatting
authored Dec 23, 2010
213 for (var i = 0; i &lt; rules.length; i++) {
e764fbf @ndp add jQuery plugin
authored Dec 24, 2010
214 var rule = rules[i];
215 var value = rule.props['opacity']
216 if (value) {
217 value = Math.round(value * 100.0);
218 rules[i].props['filter'] = 'progid:DXImageTransform.Microsoft.Alpha(opacity=' + value + ')';
219 }
220 }
221 }
222 });
223 </pre>
89e7fb7 @ndp Pull out optional functionality.
authored Oct 18, 2010
224
7bb35d1 @ndp formatting
authored Oct 11, 2010
225 ### Inserting into the DOM
34efeab @ndp clarify docs
authored Oct 11, 2010
226 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 Oct 11, 2010
227
228 ## Contributing
229
415732e @ndp try a gem for csster
authored May 26, 2012
230 1. Fork it
231 2. Create your feature branch (`git checkout -b my-new-feature`)
232 3. Commit your changes (`git commit -am 'Add some feature'`)
233 4. Push to the branch (`git push origin my-new-feature`)
234 5. Create new Pull Request
d883773 @ndp Add note about extending and contributing.
authored Oct 11, 2010
235
236
69363d2 @ndp update links
authored Sep 27, 2010
237 ## Links
238
239 * [Demo of the color functions and macros](http://ndpsoftware.com/csster/demo.html)
240 * [Demo of using to build a chart](http://ndpsoftware.com/csster/demo_chart.html)
241 * [Blog post](http://ndpsoft.blogspot.com/2010/09/introducing-csster.html)
242
243
244
632baa2 @ndp add demos to the web
authored Sep 24, 2010
245
b5f9f8b @ndp add demos to the web
authored Sep 24, 2010
246 ## TDD
632baa2 @ndp add demos to the web
authored Sep 25, 2010
247
27ae3c6 @ndp add demos to the web
authored Sep 25, 2010
248 The design was driven by [the specs](http://ndpsoftware.com/csster/spec_runner.html).
80353b1 @ndp rename macro to has
authored Sep 18, 2010
249
de5d869 @ndp add some example documentation
authored Sep 11, 2010
250
292b400 @ndp more formatting README
authored Sep 11, 2010
251 ## Todo
de5d869 @ndp add some example documentation
authored Sep 11, 2010
252
c56959d @ndp add centering and clearfix
authored Sep 24, 2010
253 * decompile existing stylesheets
06de1e3 @ndp rename README and try to format
authored Sep 11, 2010
254
255
ee77c60 @ndp start to add color functions
authored Sep 13, 2010
256
292b400 @ndp more formatting README
authored Sep 11, 2010
257 ## Motivation
f531da7 @ndp update readme with the intent
authored Sep 11, 2010
258
259 This project comes from my frustration of trying to build standalone Javascript widgets. Web
260 projects always involve the combination of HTML DOM, CSS and Javascript. It's often simpler to
261 generate the necessary DOM within your Javascript, removing any coupling (and a simpler calling
262 convention) to a specific web page. But most widgets have certain style rules. To avoid
263 any coupling with the CSS at all, styles can be included inline, but these gets bulky
264 and hard to read. The "rule" nature of CSS is nice. So widgets then have a Javascript
265 and CSS component. Wouldn't it be nice, though, to remove that CSS component.
266
267 With the advent of SASS, the coupling is even more complicated, as now there's some other
268 tool completely unrelated to your component, written in some other language. Wouldn't
269 a unified approach be nice?
270
271
292b400 @ndp more formatting README
authored Sep 11, 2010
272 ## Similar projects
de5d869 @ndp add some example documentation
authored Sep 11, 2010
273
06de1e3 @ndp rename README and try to format
authored Sep 11, 2010
274 http://revnode.com/oss/css/
275
292b400 @ndp more formatting README
authored Sep 11, 2010
276 ## Legal
de5d869 @ndp add some example documentation
authored Sep 11, 2010
277
0f9d6dd @ndp add apache licensing
authored Jan 30, 2012
278 Copyright (c) 2010-2012 Andrew J. Peterson
279 [Apache License](https://github.com/ndp/csster/raw/master/LICENSE)
280
Something went wrong with that request. Please try again.