Changesets can be listed by changeset number.
The Git repository is here.
- Revision:
- 373
- Log:
Initial import of Radiant 0.9.1, which is now packaged as a gem. This is an
import of the tagged 0.9.1 source checked out from GitHub, which isn't quite
the same as the gem distribution - but it doesn't seem to be available in an
archived form and the installed gem already has modifications, so this is
the closest I can get.
- Author:
- rool
- Date:
- Mon Mar 21 13:40:05 +0000 2011
- Size:
- 28706 Bytes
1 | # Sass (Syntactically Awesome StyleSheets) |
2 | |
3 | * Table of contents |
4 | {:toc} |
5 | |
6 | Sass is a meta-language on top of CSS |
7 | that's used to describe the style of a document |
8 | cleanly and structurally, |
9 | with more power than flat CSS allows. |
10 | Sass both provides a simpler, more elegant syntax for CSS |
11 | and implements various features that are useful |
12 | for creating manageable stylesheets. |
13 | |
14 | ## Features |
15 | |
16 | * Whitespace active |
17 | * Well-formatted output |
18 | * Elegant input |
19 | * Feature-rich |
20 | |
21 | ## Using Sass |
22 | |
23 | Sass can be used in three ways: |
24 | as a command-line tool, |
25 | as a standalone Ruby module, |
26 | and as a plugin for any Rack-enabled framework, |
27 | including Ruby on Rails and Merb. |
28 | Sass is bundled with Haml, |
29 | so if the Haml plugin or RubyGem is installed, |
30 | Sass will already be installed as a plugin or gem, respectively. |
31 | The first step for all of these is to install the Haml gem: |
32 | |
33 | gem install haml |
34 | |
35 | To run Sass from the command line, just use |
36 | |
37 | sass input.sass output.css |
38 | |
39 | Use `sass --help` for full documentation. |
40 | At the moment, the command-line tool doesn't support |
41 | updating everything in a directory |
42 | or automatically updating the CSS file when the Sass file changes. |
43 | To do that, check out the [Compass](http://compass-style.org/) Sass framework. |
44 | |
45 | Using Sass in Ruby code is very simple. |
46 | After installing the Haml gem, |
47 | you can use it by running `require "sass"` |
48 | and using Sass::Engine like so: |
49 | |
50 | engine = Sass::Engine.new("#main\n background-color: #0000ff") |
51 | engine.render #=> "#main { background-color: #0000ff; }\n" |
52 | |
53 | ### Rack/Rails/Merb Plugin |
54 | |
55 | To enable Sass as a Rails plugin, run |
56 | |
57 | haml --rails path/to/rails/app |
58 | |
59 | To enable Sass in Merb, |
60 | add |
61 | |
62 | dependency "merb-haml" |
63 | |
64 | to `config/dependencies.rb`. |
65 | |
66 | To enable Sass in a Rack application, |
67 | add |
68 | |
69 | require 'sass/plugin/rack' |
70 | use Sass::Plugin::Rack |
71 | |
72 | to `config.ru`. |
73 | |
74 | Sass stylesheets don't work the same as views. |
75 | They don't contain dynamic content, |
76 | so the CSS only needs to be generated when the Sass file has been updated. |
77 | By default, ".sass" files are placed in public/stylesheets/sass |
78 | (this can be customized with the [`:template_location`](#template_location-option) option). |
79 | Then, whenever necessary, they're compiled into corresponding CSS files in public/stylesheets. |
80 | For instance, public/stylesheets/sass/main.sass would be compiled to public/stylesheets/main.css. |
81 | |
82 | ### Caching |
83 | |
84 | By default, Sass caches compiled templates and [partials](#partials). |
85 | This dramatically speeds up re-compilation of large collections of Sass files, |
86 | and works best if the Sass templates are split up into separate files |
87 | that are all [`@import`](#import)ed into one large file. |
88 | |
89 | Without a framework, Sass puts the cached templates in the `.sass-cache` directory. |
90 | In Rails and Merb, they go in `tmp/sass-cache`. |
91 | The directory can be customized with the [`:cache_location`](#cache_location-option) option. |
92 | If you don't want Sass to use caching at all, |
93 | set the [`:cache`](#cache-option) option to `false`. |
94 | |
95 | ### Options |
96 | |
97 | Options can be set by setting the {Sass::Plugin#options Sass::Plugin.options} hash |
98 | in `environment.rb` in Rails or `config.ru` in Rack... |
99 | |
100 | Sass::Plugin.options[:style] = :compact |
101 | |
102 | ...or by setting the `Merb::Plugin.config[:sass]` hash in `init.rb` in Merb... |
103 | |
104 | Merb::Plugin.config[:sass][:style] = :compact |
105 | |
106 | ...or by passing an options hash to {Sass::Engine#initialize}. |
107 | Available options are: |
108 | |
109 | {#style-option} `:style` |
110 | : Sets the style of the CSS output. |
111 | See [Output Style](#output_style). |
112 | |
113 | {#property_syntax-option} `:property_syntax` |
114 | : Forces the document to use one syntax for properties. |
115 | If the correct syntax isn't used, an error is thrown. |
116 | `:new` forces the use of a colon or equals sign |
117 | after the property name. |
118 | For example: `color: #0f3` |
119 | or `width = !main_width`. |
120 | `:old` forces the use of a colon |
121 | before the property name. |
122 | For example: `:color #0f3` |
123 | or `:width = !main_width`. |
124 | By default, either syntax is valid. |
125 | |
126 | {#cache-option} `:cache` |
127 | : Whether parsed Sass files should be cached, |
128 | allowing greater speed. Defaults to true. |
129 | |
130 | {#never_update-option} `:never_update` |
131 | : Whether the CSS files should never be updated, |
132 | even if the template file changes. |
133 | Setting this to true may give small performance gains. |
134 | It always defaults to false. |
135 | Only has meaning within Rack, Ruby on Rails, or Merb. |
136 | |
137 | {#always_update-option} `:always_update` |
138 | : Whether the CSS files should be updated every |
139 | time a controller is accessed, |
140 | as opposed to only when the template has been modified. |
141 | Defaults to false. |
142 | Only has meaning within Rack, Ruby on Rails,x or Merb. |
143 | |
144 | {#always_check-option} `:always_check` |
145 | : Whether a Sass template should be checked for updates every |
146 | time a controller is accessed, |
147 | as opposed to only when the server starts. |
148 | If a Sass template has been updated, |
149 | it will be recompiled and will overwrite the corresponding CSS file. |
150 | Defaults to false in production mode, true otherwise. |
151 | Only has meaning within Rack, Ruby on Rails, or Merb. |
152 | |
153 | {#full_exception-option} `:full_exception` |
154 | : Whether an error in the Sass code |
155 | should cause Sass to provide a detailed description |
156 | within the generated CSS file. |
157 | If set to true, the error will be displayed |
158 | along with a line number and source snippet |
159 | both as a comment in the CSS file |
160 | and at the top of the page (in supported browsers). |
161 | Otherwise, an exception will be raised in the Ruby code. |
162 | Defaults to false in production mode, true otherwise. |
163 | Only has meaning within Rack, Ruby on Rails, or Merb. |
164 | |
165 | {#template_location-option} `:template_location` |
166 | : A path to the root sass template directory for your application. |
167 | If a hash, `:css_location` is ignored and this option designates |
168 | a mapping between input and output directories. |
169 | May also be given a list of 2-element lists, instead of a hash. |
170 | Defaults to `css_location + "/sass"`. |
171 | Only has meaning within Rack, Ruby on Rails, or Merb. |
172 | Note that if multiple template locations are specified, all |
173 | of them are placed in the import path, allowing you to import |
174 | between them. |
175 | |
176 | {#css_location-option} `:css_location` |
177 | : The path where CSS output should be written to. |
178 | This option is ignored when `:template_location` is a Hash. |
179 | Defaults to `"./public/stylesheets"`. |
180 | Only has meaning within Rack, Ruby on Rails, or Merb. |
181 | |
182 | {#cache_location-option} `:cache_location` |
183 | : The path where the cached `sassc` files should be written to. |
184 | Defaults to `"./tmp/sass-cache"` in Rails and Merb, |
185 | or `"./.sass-cache"` otherwise. |
186 | |
187 | {#unix_newlines-option} `:unix_newlines` |
188 | : If true, use Unix-style newlines when writing files. |
189 | Only has meaning on Windows, and only when Sass is writing the files |
190 | (in Rack, Rails, or Merb, or when using {Sass::Plugin} directly). |
191 | |
192 | {#filename-option} `:filename` |
193 | : The filename of the file being rendered. |
194 | This is used solely for reporting errors, |
195 | and is automatically set when using Rack, Rails, or Merb. |
196 | |
197 | {#line-option} `:line` |
198 | : The number of the first line of the Sass template. |
199 | Used for reporting line numbers for errors. |
200 | This is useful to set if the Sass template is embedded in a Ruby file. |
201 | |
202 | {#load_paths-option} `:load_paths` |
203 | : An array of filesystem paths which should be searched |
204 | for Sass templates imported with the [`@import`](#import) directive. |
205 | This defaults to the working directory and, in Rack, Rails, or Merb, |
206 | whatever `:template_location` is. |
207 | |
208 | {#line_numbers-option} `:line_numbers` |
209 | : When set to true, causes the line number and file |
210 | where a selector is defined to be emitted into the compiled CSS |
211 | as a comment. Useful for debugging especially when using imports |
212 | and mixins. |
213 | This option may also be called `:line_comments`. |
214 | |
215 | {#custom-option} `:custom` |
216 | : An option that's available for individual applications to set |
217 | to make data available to {Sass::Script::Functions custom Sass functions}. |
218 | |
219 | ## CSS Rules |
220 | |
221 | Rules in flat CSS have two elements: |
222 | the selector (e.g. `#main`, `div p`, `li a:hover`) |
223 | and the properties (e.g. `color: #00ff00;`, `width: 5em;`). |
224 | Sass has both of these, |
225 | as well as one additional element: nested rules. |
226 | |
227 | ### Rules and Selectors |
228 | |
229 | However, some of the syntax is a little different. |
230 | The syntax for selectors is the same, |
231 | but instead of using brackets to delineate the properties that belong to a particular rule, |
232 | Sass uses indentation. |
233 | For example: |
234 | |
235 | #main p |
236 | <property> |
237 | <property> |
238 | ... |
239 | |
240 | Like CSS, you can stretch selectors over multiple lines. |
241 | However, unlike CSS, you can only do this if each line but the last |
242 | ends with a comma. |
243 | For example: |
244 | |
245 | .users #userTab, |
246 | .posts #postsTab |
247 | <property> |
248 | |
249 | ### Properties |
250 | |
251 | There are two different ways to write CSS properties. |
252 | The first is very similar to the how you're used to writing them: |
253 | with a colon between the name and the value. |
254 | However, Sass properties don't have semicolons at the end; |
255 | each property is on its own line, so they aren't necessary. |
256 | For example: |
257 | |
258 | #main p |
259 | color: #00ff00 |
260 | width: 97% |
261 | |
262 | is compiled to: |
263 | |
264 | #main p { |
265 | color: #00ff00; |
266 | width: 97% } |
267 | |
268 | The second syntax for properties is slightly different. |
269 | The colon is at the beginning of the property, |
270 | rather than between the name and the value, |
271 | so it's easier to tell what elements are properties just by glancing at them. |
272 | For example: |
273 | |
274 | #main p |
275 | :color #00ff00 |
276 | :width 97% |
277 | |
278 | is compiled to: |
279 | |
280 | #main p { |
281 | color: #00ff00; |
282 | width: 97% } |
283 | |
284 | By default, either property syntax may be used. |
285 | If you want to force one or the other, |
286 | see the [`:property_syntax`](#property_syntax-option) option. |
287 | |
288 | ### Nested Rules |
289 | |
290 | Rules can also be nested within each other. |
291 | This signifies that the inner rule's selector is a child of the outer selector. |
292 | For example: |
293 | |
294 | #main p |
295 | color: #00ff00 |
296 | width: 97% |
297 | |
298 | .redbox |
299 | background-color: #ff0000 |
300 | color: #000000 |
301 | |
302 | is compiled to: |
303 | |
304 | #main p { |
305 | color: #00ff00; |
306 | width: 97%; } |
307 | #main p .redbox { |
308 | background-color: #ff0000; |
309 | color: #000000; } |
310 | |
311 | This makes insanely complicated CSS layouts with lots of nested selectors very simple: |
312 | |
313 | #main |
314 | width: 97% |
315 | |
316 | p, div |
317 | font-size: 2em |
318 | a |
319 | font-weight: bold |
320 | |
321 | pre |
322 | font-size: 3em |
323 | |
324 | is compiled to: |
325 | |
326 | #main { |
327 | width: 97%; } |
328 | #main p, #main div { |
329 | font-size: 2em; } |
330 | #main p a, #main div a { |
331 | font-weight: bold; } |
332 | #main pre { |
333 | font-size: 3em; } |
334 | |
335 | ### Referencing Parent Selectors: `&` |
336 | |
337 | In addition to the default behavior of inserting the parent selector |
338 | as a CSS parent of the current selector |
339 | (e.g. above, `#main` is the parent of `p`), |
340 | you can have more fine-grained control over what's done with the parent selector |
341 | by using the ampersand character `&` in your selectors. |
342 | |
343 | The ampersand is automatically replaced by the parent selector, |
344 | instead of having it prepended. |
345 | This allows you to cleanly create pseudo-classes: |
346 | |
347 | a |
348 | font-weight: bold |
349 | text-decoration: none |
350 | &:hover |
351 | text-decoration: underline |
352 | &:visited |
353 | font-weight: normal |
354 | |
355 | Which would become: |
356 | |
357 | a { |
358 | font-weight: bold; |
359 | text-decoration: none; } |
360 | a:hover { |
361 | text-decoration: underline; } |
362 | a:visited { |
363 | font-weight: normal; } |
364 | |
365 | It also allows you to add selectors at the base of the hierarchy, |
366 | which can be useuful for targeting certain styles to certain browsers: |
367 | |
368 | #main |
369 | width: 90% |
370 | #sidebar |
371 | float: left |
372 | margin-left: 20% |
373 | .ie6 & |
374 | margin-left: 40% |
375 | |
376 | Which would become: |
377 | |
378 | #main { |
379 | width: 90%; } |
380 | #main #sidebar { |
381 | float: left; |
382 | margin-left: 20%; } |
383 | .ie6 #main #sidebar { |
384 | margin-left: 40%; } |
385 | |
386 | ### Property Namespaces |
387 | |
388 | CSS has quite a few properties that are in "namespaces;" |
389 | for instance, `font-family`, `font-size`, and `font-weight` |
390 | are all in the `font` namespace. |
391 | In CSS, if you want to set a bunch of properties in the same namespace, |
392 | you have to type it out each time. |
393 | Sass offers a shortcut for this: |
394 | just write the namespace one, |
395 | then indent each of the sub-properties within it. |
396 | For example: |
397 | |
398 | .funky |
399 | font: |
400 | family: fantasy |
401 | size: 30em |
402 | weight: bold |
403 | |
404 | is compiled to: |
405 | |
406 | .funky { |
407 | font-family: fantasy; |
408 | font-size: 30em; |
409 | font-weight: bold; } |
410 | |
411 | ### Selector Escaping: `\` |
412 | |
413 | In case, for whatever reason, you need to write a selector |
414 | that begins with a Sass-meaningful character, |
415 | you can escape it with a backslash (`\`). |
416 | For example: |
417 | |
418 | #main |
419 | \+div |
420 | clear: both |
421 | |
422 | is compiled to: |
423 | |
424 | #main +div { |
425 | clear: both; } |
426 | |
427 | ## Directives |
428 | |
429 | Directives allow the author to directly issue instructions to the Sass compiler. |
430 | They're prefixed with an at sign, `@`, |
431 | followed by the name of the directive, |
432 | a space, and any arguments to it - |
433 | just like CSS directives. |
434 | For example: |
435 | |
436 | @import red.sass |
437 | |
438 | Some directives can also control whether or how many times |
439 | a chunk of Sass is output. |
440 | Those are documented under Control Directives. |
441 | |
442 | ### `@import` {#import} |
443 | |
444 | The `@import` directive works in a very similar way to the CSS import directive. |
445 | It can either compile to a literal CSS `@import` directive for a CSS file, |
446 | or it can import a Sass file. |
447 | If it imports a Sass file, |
448 | not only are the rules from that file included, |
449 | but all variables in that file are made available in the current file. |
450 | |
451 | Sass looks for other Sass files in the working directory, |
452 | and the Sass file directory under Rack, Rails, or Merb. |
453 | Additional search directories may be specified |
454 | using the [`:load_paths`](#load_paths-option) option. |
455 | |
456 | `@import` takes a filename with or without an extension. |
457 | If an extension isn't provided, |
458 | Sass will try to find a Sass file with the given basename in the load paths. |
459 | |
460 | For example, |
461 | |
462 | @import foo.sass |
463 | |
464 | or |
465 | |
466 | @import foo |
467 | |
468 | would compile to |
469 | |
470 | .foo { |
471 | color: #f00; } |
472 | |
473 | whereas |
474 | |
475 | @import foo.css |
476 | |
477 | would compile to |
478 | |
479 | @import "foo.css"; |
480 | |
481 | #### Partials {#partials} |
482 | |
483 | If you have a Sass file that you want to import |
484 | but don't want to compile to a CSS file, |
485 | you can add an underscore to the beginning of the filename. |
486 | This will tell Sass not to compile it to a normal CSS file. |
487 | You can then refer to these files without using the underscore. |
488 | |
489 | For example, you might have `_colors.sass`. |
490 | Then no `_colors.css` file would be created, |
491 | and you can do |
492 | |
493 | @import colors.sass |
494 | |
495 | ### `@debug` |
496 | |
497 | The `@debug` directive prints the value of a SassScript expression |
498 | to standard error. |
499 | It's useful for debugging Sass files |
500 | that have complicated SassScript going on. |
501 | For example: |
502 | |
503 | @debug 10em + 12em |
504 | |
505 | outputs: |
506 | |
507 | Line 1 DEBUG: 22em |
508 | |
509 | ### `@font-face`, `@media`, etc. |
510 | |
511 | Sass behaves as you'd expect for normal CSS @-directives. |
512 | For example: |
513 | |
514 | @font-face |
515 | font-family: "Bitstream Vera Sans" |
516 | src: url(http://foo.bar/bvs) |
517 | |
518 | compiles to: |
519 | |
520 | @font-face { |
521 | font-family: "Bitstream Vera Sans"; |
522 | src: url(http://foo.bar/bvs); } |
523 | |
524 | and |
525 | |
526 | @media print |
527 | #sidebar |
528 | display: none |
529 | |
530 | #main |
531 | background-color: white |
532 | |
533 | compiles to: |
534 | |
535 | @media print { |
536 | #sidebar { |
537 | display: none; } |
538 | |
539 | #main { |
540 | background-color: white; } } |
541 | |
542 | ## Control Directives |
543 | |
544 | SassScript supports basic control directives for looping and conditional evaluation. |
545 | |
546 | ### `@if` |
547 | |
548 | The `@if` statement takes a SassScript expression |
549 | and prints the code nested beneath it if the expression returns |
550 | anything other than `false`: |
551 | |
552 | p |
553 | @if 1 + 1 == 2 |
554 | border: 1px solid |
555 | @if 5 < 3 |
556 | border: 2px dotted |
557 | |
558 | is compiled to: |
559 | |
560 | p { |
561 | border: 1px solid; } |
562 | |
563 | The `@if` statement can be followed by several `@else if` statements |
564 | and one `@else` statement. |
565 | If the `@if` statement fails, |
566 | the `@else if` statements are tried in order |
567 | until one succeeds or the `@else` is reached. |
568 | For example: |
569 | |
570 | !type = "monster" |
571 | p |
572 | @if !type == "ocean" |
573 | color: blue |
574 | @else if !type == "matador" |
575 | color: red |
576 | @else if !type == "monster" |
577 | color: green |
578 | @else |
579 | color: black |
580 | |
581 | is compiled to: |
582 | |
583 | p { |
584 | color: green; } |
585 | |
586 | ### `@for` |
587 | |
588 | The `@for` statement has two forms: |
589 | `@for <var> from <start> to <end>` or |
590 | `@for <var> from <start> through <end>`. |
591 | `<var>` is a variable name, like `!i`, |
592 | and `<start>` and `<end>` are SassScript expressions |
593 | that should return integers. |
594 | |
595 | The `@for` statement sets `<var>` to each number |
596 | from `<start>` to `<end>`, |
597 | including `<end>` if `through` is used. |
598 | For example: |
599 | |
600 | @for !i from 1 through 3 |
601 | .item-#{!i} |
602 | width = 2em * !i |
603 | |
604 | is compiled to: |
605 | |
606 | .item-1 { |
607 | width: 2em; } |
608 | .item-2 { |
609 | width: 4em; } |
610 | .item-3 { |
611 | width: 6em; } |
612 | |
613 | ### `@while` |
614 | |
615 | The `@while` statement repeatedly loops over the nested |
616 | block until the statement evaluates to `false`. This can |
617 | be used to achieve more complex looping than the `@for` |
618 | statement is capable of. |
619 | For example: |
620 | |
621 | !i = 6 |
622 | @while !i > 0 |
623 | .item-#{!i} |
624 | width = 2em * !i |
625 | !i = !i - 2 |
626 | |
627 | is compiled to: |
628 | |
629 | .item-6 { |
630 | width: 12em; } |
631 | |
632 | .item-4 { |
633 | width: 8em; } |
634 | |
635 | .item-2 { |
636 | width: 4em; } |
637 | |
638 | ## SassScript |
639 | |
640 | In addition to the declarative templating system, |
641 | Sass supports a simple language known as SassScript |
642 | for dynamically computing CSS values and controlling |
643 | the styles and selectors that get emitted. |
644 | |
645 | SassScript can be used as the value for a property |
646 | by using `=` instead of `:`. |
647 | For example: |
648 | |
649 | color = #123 + #234 |
650 | |
651 | is compiled to: |
652 | |
653 | color: #357; |
654 | |
655 | For old-style properties, the `=` is added but the `:` is retained. |
656 | For example: |
657 | |
658 | :color = #123 + #234 |
659 | |
660 | is compiled to: |
661 | |
662 | color: #357; |
663 | |
664 | ### Interactive Shell |
665 | |
666 | You can easily experiment with SassScript using the interactive shell. |
667 | To launch the shell run the sass command-line with the `-i` option. At the |
668 | prompt, enter any legal SassScript expression to have it evaluated |
669 | and the result printed out for you: |
670 | |
671 | $ sass -i |
672 | >> "Hello, Sassy World!" |
673 | "Hello, Sassy World!" |
674 | >> 1px + 1px + 1px |
675 | 3px |
676 | >> #777 + #777 |
677 | #eeeeee |
678 | >> #777 + #888 |
679 | white |
680 | |
681 | ### Variables: `!` |
682 | |
683 | The most straightforward way to use SassScript |
684 | is to set and reference variables. |
685 | Variables begin with exclamation marks, |
686 | and are set like so: |
687 | |
688 | !width = 5em |
689 | |
690 | You can then refer to them by putting an equals sign |
691 | after your properties: |
692 | |
693 | #main |
694 | width = !width |
695 | |
696 | Variables that are first defined in a scoped context are only |
697 | available in that context. |
698 | |
699 | ### Data Types |
700 | |
701 | SassScript supports four data types: |
702 | * numbers (e.g. `1.2`, `13`, `10px`) |
703 | * strings of text (e.g. `"foo"`, `"bar"`) |
704 | * colors (e.g. `blue`, `#04a3f9`) |
705 | * booleans (e.g. `true`, `false`) |
706 | |
707 | Any text that doesn't fit into one of those types |
708 | in a SassScript context will cause an error: |
709 | |
710 | p |
711 | !width = 5em |
712 | // This will cause an error |
713 | border = !width solid blue |
714 | // Use one of the following forms instead: |
715 | border = "#{!width} solid blue" |
716 | border = !width "solid" "blue" |
717 | |
718 | is compiled to: |
719 | |
720 | p { |
721 | border: 5em solid blue; |
722 | border: 5em solid blue; } |
723 | |
724 | |
725 | ### Operations |
726 | |
727 | SassScript supports the standard arithmetic operations on numbers |
728 | (`+`, `-`, `*`, `/`, `%`), |
729 | and will automatically convert between units if it can: |
730 | |
731 | p |
732 | width = 1in + 8pt |
733 | |
734 | is compiled to: |
735 | |
736 | p { |
737 | width: 1.111in; } |
738 | |
739 | Relational operators |
740 | (`<`, `>`, `<=`, `>=`) |
741 | are also supported for numbers, |
742 | and equality operators |
743 | (`==`, `!=`) |
744 | are supported for all types. |
745 | |
746 | All arithmetic operations are supported for color values, |
747 | where they work piecewise. |
748 | This means that the operation is performed |
749 | on the red, green, and blue components in turn. |
750 | For example: |
751 | |
752 | p |
753 | color = #010203 + #040506 |
754 | |
755 | computes `01 + 04 = 05`, `02 + 05 = 07`, and `03 + 06 = 09`, |
756 | and is compiled to: |
757 | |
758 | p { |
759 | color: #050709; } |
760 | |
761 | Arithmetic operations even work between numbers and colors, |
762 | also piecewise. |
763 | For example: |
764 | |
765 | p |
766 | color = #010203 * 2 |
767 | |
768 | computes `01 * 2 = 02`, `02 * 2 = 04`, and `03 * 2 = 06`, |
769 | and is compiled to: |
770 | |
771 | p { |
772 | color: #020406; } |
773 | |
774 | The `+` operation can be used to concatenate strings: |
775 | |
776 | p |
777 | cursor = "e" + "-resize" |
778 | |
779 | is compiled to: |
780 | |
781 | p { |
782 | cursor: e-resize; } |
783 | |
784 | By default, if two values are placed next to one another, |
785 | they are concatenated with a space: |
786 | |
787 | p |
788 | margin = 3px + 4px "auto" |
789 | |
790 | is compiled to: |
791 | |
792 | p { |
793 | margin: 7px auto; } |
794 | |
795 | Within a string of text, #{} style interpolation can be used to |
796 | place dynamic values within the string: |
797 | |
798 | p |
799 | border = "#{5px + 10px} solid #ccc" |
800 | |
801 | Finally, SassScript supports `and`, `or`, and `not` operators |
802 | for boolean values. |
803 | |
804 | ### Parentheses |
805 | |
806 | Parentheses can be used to affect the order of operations: |
807 | |
808 | p |
809 | width = 1em + (2em * 3) |
810 | |
811 | is compiled to: |
812 | |
813 | p { |
814 | width: 7em; } |
815 | |
816 | ### Functions |
817 | |
818 | SassScript defines some useful functions |
819 | that are called using the normal CSS function syntax: |
820 | |
821 | p |
822 | color = hsl(0, 100%, 50%) |
823 | |
824 | is compiled to: |
825 | |
826 | #main { |
827 | color: #ff0000; } |
828 | |
829 | The following functions are provided: `hsl`, `percentage`, `round`, `ceil`, `floor`, and `abs`. |
830 | You can define additional functions in ruby. |
831 | |
832 | See {Sass::Script::Functions} for more information. |
833 | |
834 | ### Interpolation: `#{}` |
835 | |
836 | You can also use SassScript variables in selectors |
837 | and property names using #{} interpolation syntax: |
838 | |
839 | !name = foo |
840 | !attr = border |
841 | p.#{!name} |
842 | #{!attr}-color: blue |
843 | |
844 | is compiled to: |
845 | |
846 | p.foo { |
847 | border-color: blue; } |
848 | |
849 | ### Optional Assignment: `||=` |
850 | |
851 | You can assign to variables if they aren't already assigned |
852 | using the `||=` assignment operator. This means that if the |
853 | variable has already been assigned to, it won't be re-assigned, |
854 | but if it doesn't have a value yet, it will be given one. |
855 | |
856 | For example: |
857 | |
858 | !content = "First content" |
859 | !content ||= "Second content?" |
860 | !new_content ||= "First time reference" |
861 | |
862 | #main |
863 | content = !content |
864 | new-content = !new_content |
865 | |
866 | is compiled to: |
867 | |
868 | #main { |
869 | content: First content; |
870 | new-content: First time reference; } |
871 | |
872 | ## Mixins |
873 | |
874 | Mixins enable you to define groups of CSS properties and |
875 | then include them inline in any number of selectors |
876 | throughout the document. This allows you to keep your |
877 | stylesheets DRY and also avoid placing presentation |
878 | classes in your markup. |
879 | |
880 | ### Defining a Mixin: `=` |
881 | |
882 | To define a mixin you use a slightly modified form of selector syntax. |
883 | For example the `large-text` mixin is defined as follows: |
884 | |
885 | =large-text |
886 | font: |
887 | family: Arial |
888 | size: 20px |
889 | weight: bold |
890 | color: #ff0000 |
891 | |
892 | The initial `=` marks this as a mixin rather than a standard selector. |
893 | The CSS rules that follow won't be included until the mixin is referenced later on. |
894 | Anything you can put into a standard selector, |
895 | you can put into a mixin definition. |
896 | For example: |
897 | |
898 | =clearfix |
899 | display: inline-block |
900 | &:after |
901 | content: "." |
902 | display: block |
903 | height: 0 |
904 | clear: both |
905 | visibility: hidden |
906 | * html & |
907 | height: 1px |
908 | |
909 | ### Mixing It In: `+` |
910 | |
911 | Inlining a defined mixin is simple, |
912 | just prepend a `+` symbol to the name of a mixin defined earlier in the document. |
913 | So to inline the `large-text` defined earlier, |
914 | we include the statment `+large-text` in our selector definition thus: |
915 | |
916 | .page-title |
917 | +large-text |
918 | padding: 4px |
919 | margin: |
920 | top: 10px |
921 | |
922 | This will produce the following CSS output: |
923 | |
924 | .page-title { |
925 | font-family: Arial; |
926 | font-size: 20px; |
927 | font-weight: bold; |
928 | color: #ff0000; |
929 | padding: 4px; |
930 | margin-top: 10px; } |
931 | |
932 | Any number of mixins may be defined and there is no limit on |
933 | the number that can be included in a particular selector. |
934 | |
935 | Mixin definitions can also include references to other mixins. |
936 | For example: |
937 | |
938 | =compound |
939 | +highlighted-background |
940 | +header-text |
941 | |
942 | =highlighted-background |
943 | background: |
944 | color: #fc0 |
945 | =header-text |
946 | font: |
947 | size: 20px |
948 | |
949 | Mixins that only define descendent selectors, can be safely mixed |
950 | into the top most level of a document. |
951 | |
952 | ### Arguments |
953 | |
954 | Mixins can take arguments which can be used with SassScript: |
955 | |
956 | =sexy-border(!color) |
957 | border: |
958 | color = !color |
959 | width: 1in |
960 | style: dashed |
961 | p |
962 | +sexy-border("blue") |
963 | |
964 | is compiled to: |
965 | |
966 | p { |
967 | border-color: #0000ff; |
968 | border-width: 1in; |
969 | border-style: dashed; } |
970 | |
971 | Mixins can also specify default values for their arguments: |
972 | |
973 | =sexy-border(!color, !width = 1in) |
974 | border: |
975 | color = !color |
976 | width = !width |
977 | style: dashed |
978 | p |
979 | +sexy-border("blue") |
980 | |
981 | is compiled to: |
982 | |
983 | p { |
984 | border-color: #0000ff; |
985 | border-width: 1in; |
986 | border-style: dashed; } |
987 | |
988 | ## Comments |
989 | |
990 | Sass supports two sorts of comments: |
991 | those that show up in the CSS output |
992 | and those that don't. |
993 | |
994 | ### CSS Comments: `/*` |
995 | |
996 | "Loud" comments are just as easy as silent ones. |
997 | These comments output to the document as CSS comments, |
998 | and thus use the same opening sequence: `/*`. |
999 | For example: |
1000 | |
1001 | /* A very awesome rule. |
1002 | #awesome.rule |
1003 | /* An equally awesome property. |
1004 | awesomeness: very |
1005 | |
1006 | becomes |
1007 | |
1008 | /* A very awesome rule. */ |
1009 | #awesome.rule { |
1010 | /* An equally awesome property. */ |
1011 | awesomeness: very; } |
1012 | |
1013 | You can also nest content beneath loud comments. For example: |
1014 | |
1015 | #pbj |
1016 | /* This rule describes |
1017 | the styling of the element |
1018 | that represents |
1019 | a peanut butter and jelly sandwich. |
1020 | background-image: url(/images/pbj.png) |
1021 | color: red |
1022 | |
1023 | becomes |
1024 | |
1025 | #pbj { |
1026 | /* This rule describes |
1027 | * the styling of the element |
1028 | * that represents |
1029 | * a peanut butter and jelly sandwich. */ |
1030 | background-image: url(/images/pbj.png); |
1031 | color: red; } |
1032 | |
1033 | ### Sass Comments: `//` |
1034 | |
1035 | It's simple to add "silent" comments, |
1036 | which don't output anything to the CSS document, |
1037 | to a Sass document. |
1038 | Simply use the familiar C-style notation for a one-line comment, `//`, |
1039 | at the normal indentation level and all text following it won't be output. |
1040 | For example: |
1041 | |
1042 | // A very awesome rule. |
1043 | #awesome.rule |
1044 | // An equally awesome property. |
1045 | awesomeness: very |
1046 | |
1047 | becomes |
1048 | |
1049 | #awesome.rule { |
1050 | awesomeness: very; } |
1051 | |
1052 | You can also nest text beneath a comment to comment out a whole block. |
1053 | For example: |
1054 | |
1055 | // A very awesome rule |
1056 | #awesome.rule |
1057 | // Don't use these properties |
1058 | color: green |
1059 | font-size: 10em |
1060 | color: red |
1061 | |
1062 | becomes |
1063 | |
1064 | #awesome.rule { |
1065 | color: red; } |
1066 | |
1067 | ## Output Style |
1068 | |
1069 | Although the default CSS style that Sass outputs is very nice, |
1070 | and reflects the structure of the document in a similar way that Sass does, |
1071 | sometimes it's good to have other formats available. |
1072 | |
1073 | Sass allows you to choose between four different output styles |
1074 | by setting the `:style` option. |
1075 | In Rack, Rails, and Merb, this is done by setting `Sass::Plugin.options[:style]`; |
1076 | otherwise, it's done by passing an options hash with `:style` set. |
1077 | |
1078 | ### `:nested` |
1079 | |
1080 | Nested style is the default Sass style, |
1081 | because it reflects the structure of the document |
1082 | in much the same way Sass does. |
1083 | Each property has its own line, |
1084 | but the indentation isn't constant. |
1085 | Each rule is indented based on how deeply it's nested. |
1086 | For example: |
1087 | |
1088 | #main { |
1089 | color: #fff; |
1090 | background-color: #000; } |
1091 | #main p { |
1092 | width: 10em; } |
1093 | |
1094 | .huge { |
1095 | font-size: 10em; |
1096 | font-weight: bold; |
1097 | text-decoration: underline; } |
1098 | |
1099 | Nested style is very useful when looking at large CSS files |
1100 | for the same reason Sass is useful for making them: |
1101 | it allows you to very easily grasp the structure of the file |
1102 | without actually reading anything. |
1103 | |
1104 | ### `:expanded` |
1105 | |
1106 | Expanded is the typical human-made CSS style, |
1107 | with each property and rule taking up one line. |
1108 | Properties are indented within the rules, |
1109 | but the rules aren't indented in any special way. |
1110 | For example: |
1111 | |
1112 | #main { |
1113 | color: #fff; |
1114 | background-color: #000; |
1115 | } |
1116 | #main p { |
1117 | width: 10em; |
1118 | } |
1119 | |
1120 | .huge { |
1121 | font-size: 10em; |
1122 | font-weight: bold; |
1123 | text-decoration: underline; |
1124 | } |
1125 | |
1126 | ### `:compact` |
1127 | |
1128 | Compact style, as the name would imply, |
1129 | takes up less space than Nested or Expanded. |
1130 | However, it's also harder to read. |
1131 | Each CSS rule takes up only one line, |
1132 | with every property defined on that line. |
1133 | Nested rules are placed next to each other with no newline, |
1134 | while groups of rules have newlines between them. |
1135 | For example: |
1136 | |
1137 | #main { color: #fff; background-color: #000; } |
1138 | #main p { width: 10em; } |
1139 | |
1140 | .huge { font-size: 10em; font-weight: bold; text-decoration: underline; } |
1141 | |
1142 | ### `:compressed` |
1143 | |
1144 | Compressed style takes up the minimum amount of space possible, |
1145 | having no whitespace except that necessary to separate selectors |
1146 | and a newline at the end of the file. |
1147 | It's not meant to be human-readable. |
1148 | For example: |
1149 | |
1150 | #main{color:#fff;background-color:#000}#main p{width:10em}.huge{font-size:10em;font-weight:bold;text-decoration:underline} |