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:
- 9954 Bytes
1 | # Haml and Sass |
2 | |
3 | Haml and Sass are templating engines |
4 | for the two most common types of documents on the web: |
5 | HTML and CSS, respectively. |
6 | They are designed to make it both easier and more pleasant |
7 | to code HTML and CSS documents, |
8 | by eliminating redundancy, |
9 | reflecting the underlying structure that the document represents, |
10 | and providing elegant, easily understandable, and powerful syntax. |
11 | |
12 | ## Using |
13 | |
14 | Haml and Sass can be used from the command line |
15 | or as part of a Ruby web framework. |
16 | The first step is to install the gem: |
17 | |
18 | gem install haml |
19 | |
20 | After you convert some HTML to Haml or some CSS to Sass, |
21 | you can run |
22 | |
23 | haml document.haml |
24 | sass style.sass |
25 | |
26 | to compile them. |
27 | For more information on these commands, check out |
28 | |
29 | haml --help |
30 | sass --help |
31 | |
32 | To install Haml and Sass as a Rails plugin, |
33 | just run `haml --rails path/to/rails/app` |
34 | and both Haml and Sass will be installed. |
35 | Views with the `.html.haml` extension will automatically use Haml. |
36 | Sass is a little more complicated; |
37 | `.sass` files should be placed in `public/stylesheets/sass`, |
38 | where they'll be automatically compiled |
39 | to corresponding CSS files in `public/stylesheets` when needed |
40 | (the Sass template directory is customizable... |
41 | see [the Sass reference](http://sass-lang.com/docs/yardoc/SASS_REFERENCE.md.html#template_location-option) for details). |
42 | |
43 | For Merb, `.html.haml` views will work without any further modification. |
44 | To enable Sass, you also need to add a dependency. |
45 | To do so, just add |
46 | |
47 | dependency "merb-haml" |
48 | |
49 | to `config/dependencies.rb` (or `config/init.rb` in a flat/very flat Merb application). |
50 | Then it'll work just like it does in Rails. |
51 | |
52 | Sass can also be used with any Rack-enabled web framework. |
53 | To do so, just add |
54 | |
55 | require 'sass/plugin/rack' |
56 | use Sass::Plugin::Rack |
57 | |
58 | to `config.ru`. |
59 | Then any Sass files in `public/stylesheets/sass` |
60 | will be compiled CSS files in `public/stylesheets` on every request. |
61 | |
62 | To use Haml and Sass programatically, |
63 | check out the [YARD documentation](http://haml-lang.com/docs/yardoc/). |
64 | |
65 | ## Formatting |
66 | |
67 | ### Haml |
68 | |
69 | The most basic element of Haml |
70 | is a shorthand for creating HTML: |
71 | |
72 | %tagname{:attr1 => 'value1', :attr2 => 'value2'} Contents |
73 | |
74 | No end-tag is needed; Haml handles that automatically. |
75 | If you prefer HTML-style attributes, you can also use: |
76 | |
77 | %tagname(attr1='value1' attr2='value2') Contents |
78 | |
79 | Adding `class` and `id` attributes is even easier. |
80 | Haml uses the same syntax as the CSS that styles the document: |
81 | |
82 | %tagname#id.class |
83 | |
84 | In fact, when you're using the `<div>` tag, |
85 | it becomes _even easier_. |
86 | Because `<div>` is such a common element, |
87 | a tag without a name defaults to a div. So |
88 | |
89 | #foo Hello! |
90 | |
91 | becomes |
92 | |
93 | <div id='foo'>Hello!</div> |
94 | |
95 | Haml uses indentation |
96 | to bring the individual elements to represent the HTML structure. |
97 | A tag's children are indented beneath than the parent tag. |
98 | Again, a closing tag is automatically added. |
99 | For example: |
100 | |
101 | %ul |
102 | %li Salt |
103 | %li Pepper |
104 | |
105 | becomes: |
106 | |
107 | <ul> |
108 | <li>Salt</li> |
109 | <li>Pepper</li> |
110 | </ul> |
111 | |
112 | You can also put plain text as a child of an element: |
113 | |
114 | %p |
115 | Hello, |
116 | World! |
117 | |
118 | It's also possible to embed Ruby code into Haml documents. |
119 | An equals sign, `=`, will output the result of the code. |
120 | A hyphen, `-`, will run the code but not output the result. |
121 | You can even use control statements |
122 | like `if` and `while`: |
123 | |
124 | %p |
125 | Date/Time: |
126 | - now = DateTime.now |
127 | %strong= now |
128 | - if now > DateTime.parse("December 31, 2006") |
129 | = "Happy new " + "year!" |
130 | |
131 | Haml provides far more tools than those presented here. |
132 | Check out the reference documentation in the Haml module. |
133 | |
134 | ### Sass |
135 | |
136 | At its most basic, |
137 | Sass is just another way of writing CSS. |
138 | Although it's very much like normal CSS, |
139 | the basic syntax offers a few helpful features: |
140 | indentation indicates the properties in a rule, |
141 | rather than non-DRY brackets; |
142 | and newlines indicate the end of a properties, |
143 | rather than a semicolon. |
144 | For example: |
145 | |
146 | #main |
147 | background-color: #f00 |
148 | width: 98% |
149 | |
150 | becomes: |
151 | |
152 | #main { |
153 | background-color: #f00; |
154 | width: 98% } |
155 | |
156 | However, Sass provides much more than a way to make CSS look nice. |
157 | In CSS, it's important to have accurate selectors, |
158 | so your styles don't just apply to everything. |
159 | However, in order to do this, |
160 | you need to use nested element selectors. |
161 | These get very ugly very quickly. |
162 | I'm sure everyone's had to write something like |
163 | "#main .sidebar .top p h1 a", |
164 | followed by |
165 | "#main .sidebar .top p h1 a:visited" and |
166 | "#main .sidebar .top p h1 a:hover". |
167 | Well, Sass gets rid of that. |
168 | Like Haml, it uses indentation to indicate the structure of the document. |
169 | So, what was: |
170 | |
171 | #main { |
172 | width: 90%; |
173 | } |
174 | #main p { |
175 | border-style: solid; |
176 | border-width: 1px; |
177 | border-color: #00f; |
178 | } |
179 | #main p a { |
180 | text-decoration: none; |
181 | font-weight: bold; |
182 | } |
183 | #main p a:hover { |
184 | text-decoration: underline; |
185 | } |
186 | |
187 | becomes: |
188 | |
189 | #main |
190 | width: 90% |
191 | p |
192 | border-style: solid |
193 | border-width: 1px |
194 | border-color: #00f |
195 | a |
196 | text-decoration: none |
197 | font-weight: bold |
198 | a:hover |
199 | text-decoration: underline |
200 | |
201 | Pretty nice, no? Well, it gets better. |
202 | One of the main complaints against CSS is that it doesn't allow variables. |
203 | What if have a color or a width you re-use all the time? |
204 | In CSS, you just have to re-type it each time, |
205 | which is a nightmare when you decide to change it later. |
206 | Not so for Sass! |
207 | You can use the `!` character to set variables. |
208 | Then, if you put `=` after your property name, |
209 | you can set it to a variable. |
210 | For example: |
211 | |
212 | !note_bg= #55aaff |
213 | |
214 | #main |
215 | width: 70% |
216 | .note |
217 | background-color = !note_bg |
218 | p |
219 | width: 5em |
220 | background-color = !note_bg |
221 | |
222 | becomes: |
223 | |
224 | #main { |
225 | width: 70%; } |
226 | #main .note { |
227 | background-color: #55aaff; } |
228 | #main p { |
229 | width: 5em; |
230 | background-color: #55aaff; } |
231 | |
232 | You can even do simple arithmetic operations with variables, |
233 | adding numbers and even colors together: |
234 | |
235 | !main_bg= #46ar12 |
236 | !main_width= 40em |
237 | |
238 | #main |
239 | background-color = !main_bg |
240 | width = !main_width |
241 | .sidebar |
242 | background-color = !main_bg + #333333 |
243 | width = !main_width - 25em |
244 | |
245 | becomes: |
246 | |
247 | #main { |
248 | background-color: #46a312; |
249 | width: 40em; } |
250 | #main .sidebar { |
251 | background-color: #79d645; |
252 | width: 15em; } |
253 | |
254 | Taking the idea of variables a bit further are mixins. |
255 | These let you group whole bunches of CSS properties into a single |
256 | directive and then include those anywhere you want: |
257 | |
258 | =blue-border |
259 | border: |
260 | color: blue |
261 | width: 2px |
262 | style: dotted |
263 | |
264 | .comment |
265 | +blue-border |
266 | padding: 2px |
267 | margin: 10px 0 |
268 | |
269 | .reply |
270 | +blue-border |
271 | |
272 | becomes: |
273 | |
274 | .comment { |
275 | border-color: blue; |
276 | border-width: 2px; |
277 | border-style: dotted; |
278 | padding: 2px; |
279 | margin: 10px 0; |
280 | } |
281 | |
282 | .reply { |
283 | border-color: blue; |
284 | border-width: 2px; |
285 | border-style: dotted; |
286 | } |
287 | |
288 | A comprehensive list of features is in |
289 | the documentation for the Sass module. |
290 | |
291 | ## Indentation |
292 | |
293 | Indentation can be made up of one or more tabs or spaces. |
294 | However, indentation must be consistent within a given document. |
295 | Hard tabs and spaces can't be mixed, |
296 | and the same number of tabs or spaces must be used throughout. |
297 | |
298 | ## Executables |
299 | |
300 | The Haml gem includes several executables that are useful |
301 | for dealing with Haml and Sass from the command line. |
302 | |
303 | ### `haml` |
304 | |
305 | The `haml` executable transforms a source Haml file into HTML. |
306 | See `haml --help` for further information and options. |
307 | |
308 | ### `sass` |
309 | |
310 | The `sass` executable transforms a source Sass file into CSS. |
311 | See `sass --help` for further information and options. |
312 | |
313 | ### `html2haml` |
314 | |
315 | The `html2haml` executable attempts to transform HTML, |
316 | optionally with ERB markup, into Haml code. |
317 | Since HTML is so variable, this transformation is not always perfect; |
318 | it's a good idea to have a human check the output of this tool. |
319 | See `html2haml --help` for further information and options. |
320 | |
321 | ### `css2sass` |
322 | |
323 | The `css2sass` executable attempts to transform CSS into Sass code. |
324 | This transformation attempts to use Sass nesting where possible. |
325 | See `css2sass --help` for further information and options. |
326 | |
327 | ## Authors |
328 | |
329 | Haml and Sass were created by [Hampton Catlin](http://hamptoncatlin.com) |
330 | (hcatlin) and he is the author of the original implementation. However, Hampton |
331 | doesn't even know his way around the code anymore and now occasionally consults |
332 | on the language issues. Hampton lives in Jacksonville, Florida and is the lead |
333 | mobile developer for Wikimedia. |
334 | |
335 | [Nathan Weizenbaum](http://nex-3.com) is the primary developer and architect of |
336 | the "modern" Ruby implementation of Haml. His hard work has kept the project |
337 | alive by endlessly answering forum posts, fixing bugs, refactoring, finding |
338 | speed improvements, writing documentation, implementing new features, and |
339 | getting Hampton coffee (a fitting task for a boy-genius). Nathan lives in |
340 | Seattle, Washington and while not being a student at the University of |
341 | Washington or working at an internship, he consults for Unspace Interactive. |
342 | |
343 | [Chris Eppstein](http://acts-as-architect.blogspot.com) is a core contributor to |
344 | Sass and the creator of Compass, the first Sass-based framework. Chris focuses |
345 | on making Sass more powerful, easy to use, and on ways to speed its adoption |
346 | through the web development community. Chris lives in San Jose, California with |
347 | his wife and daughter. He is the Software Architect for |
348 | [Caring.com](http://caring.com), a website devoted to the 34 Million caregivers |
349 | whose parents are sick or elderly, that uses Haml and Sass. |
350 | |
351 | If you use this software, you must pay Hampton a compliment. And |
352 | buy Nathan some jelly beans. Maybe pet a kitten. Yeah. Pet that kitty. |
353 | |
354 | Some of the work on Haml was supported by Unspace Interactive. |
355 | |
356 | Beyond that, the implementation is licensed under the MIT License. |
357 | Okay, fine, I guess that means compliments aren't __required__. |