Changesets can be listed by changeset number.
The Git repository is here.
- Revision:
- 193
- Log:
First stage commit of Typo 4.1, modified for the ROOL site.
Includes all local modifications but a final pass needs to be
made to delete any files left over from earlier Typo versions
that shouldn't be here anymore. See the 'tags' section of the
repository for a clean Typo 4.1 tree.Note that symlinks to shared files in the RISC OS Open theme
directory have been deliberately included this time around; I
decided that on balance it was better to leave them in as
placeholders, since unlike symlinks in app/views/shared, the
Typo theme structure is not a standard Rails concept.
- Author:
- rool
- Date:
- Wed Apr 04 18:51:02 +0100 2007
- Size:
- 15083 Bytes
1 | = Haml (XHTML Abstraction Markup Language) |
2 | |
3 | Haml is a markup language |
4 | that's used to cleanly and simply describe the XHTML of any web document, |
5 | without the use of inline code. |
6 | Haml functions as a replacement |
7 | for inline page templating systems such as PHP, RHTML, and ASP. |
8 | However, Haml avoids the need for explicitly coding XHTML into the template, |
9 | because it is actually an abstract description of the XHTML, |
10 | with some code to generate dynamic content. |
11 | |
12 | == Features |
13 | |
14 | * Whitespace active |
15 | * Well-formatted markup |
16 | * DRY |
17 | * Follows CSS conventions |
18 | * Interpolates Ruby code |
19 | * Implements Rails templates with the .haml extension |
20 | |
21 | == Authors |
22 | |
23 | Haml was originally created by Hampton Catlin (hcatlin). |
24 | Help with the Ruby On Rails implementation and much of the documentation |
25 | by Jeff Hardy (packagethief). |
26 | |
27 | Nathan Weizenbaum (Nex3) contributed the buffered-engine code, |
28 | along with many other enhancements |
29 | (including the silent-line syntax: "-"). |
30 | |
31 | If you use this software, you must pay Hampton a compliment. |
32 | Say something nice about it. |
33 | Beyond that, the implementation is licensed under the MIT License. |
34 | Ok, fine, I guess that means compliments aren't *required*. |
35 | |
36 | == Formatting |
37 | |
38 | Haml is sensitive to spacing and indentation; |
39 | it uses nesting to convey structure. |
40 | When you want an element to have children, |
41 | indent the lines below it using two spaces. |
42 | Remember, spaces are not the same as tabs. |
43 | For example: |
44 | |
45 | #contact |
46 | %h1 Eugene Mumbai |
47 | %ul.info |
48 | %li.login eugene |
49 | %li.email eugene@example.com |
50 | |
51 | is compiled to: |
52 | |
53 | <div id='contact'> |
54 | <h1>Eugene Mumbai</h1> |
55 | <ul class='info'> |
56 | <li class='login'>eugene</li> |
57 | <li class='email'>eugene@example.com</li> |
58 | </ul> |
59 | </div> |
60 | |
61 | == Characters with meaning to Haml |
62 | |
63 | Various characters, when placed at a certain point in a line, |
64 | instruct Haml to render different types of things. |
65 | |
66 | === XHTML Tags |
67 | |
68 | These characters render XHTML tags. |
69 | |
70 | ==== % |
71 | |
72 | |
73 | This element is placed at the beginning of a line. |
74 | It's followed immediately by the name of an element, |
75 | then optionally by modifiers (see below), a space, |
76 | and text to be rendered inside the element. |
77 | It creates an element in the form of <tt><element></element></tt>. |
78 | For example: |
79 | |
80 | %one |
81 | %two |
82 | %three Hey there |
83 | |
84 | is compiled to: |
85 | |
86 | <one> |
87 | <two> |
88 | <three>Hey there</three> |
89 | </two> |
90 | </one> |
91 | |
92 | Any string is a valid element name; |
93 | Haml will automatically generate opening and closing tags for any element. |
94 | |
95 | ==== {} |
96 | |
97 | Brackets represent a Ruby hash |
98 | that is used for specifying the attributes of an element. |
99 | It is literally evaluated as a Ruby hash, |
100 | so logic will work in it and local variables may be used. |
101 | Quote characters within the attribute |
102 | will be replaced by appropriate escape sequences. |
103 | The hash is placed after the tag is defined. |
104 | For example: |
105 | |
106 | %head{ :name => "doc_head" } |
107 | %script{ 'type' => "text/" + "javascript", |
108 | :src => "javascripts/script_#{2 + 7}" } |
109 | |
110 | is compiled to: |
111 | |
112 | <head name="doc_head"> |
113 | <script src='javascripts/script_9' type='text/javascript'> |
114 | </script> |
115 | </head> |
116 | |
117 | ==== [] |
118 | |
119 | Square brackets follow a tag definition and contain a Ruby object |
120 | that is used to set the class and id of that tag. |
121 | The class is set to the object's class |
122 | (transformed to use underlines rather than camel case) |
123 | and the id is set to the object's class, followed by its id. |
124 | Because the id of an object is normally an obscure implementation detail, |
125 | this is most useful for elements that represent instances of Models. |
126 | For example: |
127 | |
128 | # file: app/controllers/users_controller.rb |
129 | |
130 | def show |
131 | @user = CrazyUser.find(15) |
132 | end |
133 | |
134 | # file: app/views/users/show.haml |
135 | |
136 | %div[@user] |
137 | %bar[290]/ |
138 | Hello! |
139 | |
140 | is compiled to: |
141 | |
142 | <div class="crazy_user" id="crazy_user_15"> |
143 | <bar class="fixnum" id="fixnum_581" /> |
144 | Hello! |
145 | </div> |
146 | |
147 | This is based off of DHH's SimplyHelpful syntax, |
148 | as presented at RailsConf Europe 2006. |
149 | |
150 | ==== / |
151 | |
152 | The forward slash character, when placed at the end of a tag definition, |
153 | causes the tag to be self-closed. |
154 | For example: |
155 | |
156 | %br/ |
157 | %meta{:http-equiv => 'Content-Type', :content => 'text/html'}/ |
158 | |
159 | is compiled to: |
160 | |
161 | <br /> |
162 | <meta http-equiv='Content-Type' content='text/html' /> |
163 | |
164 | ==== . and # |
165 | |
166 | The period and pound sign are borrowed from CSS. |
167 | They are used as shortcuts to specify the <tt>class</tt> |
168 | and <tt>id</tt> attributes of an element, respectively. |
169 | Multiple class names can be specified in a similar way to CSS, |
170 | by chaining the class names together with periods. |
171 | They are placed immediately after the tag and before an attributes hash. |
172 | For example: |
173 | |
174 | div#things |
175 | %span#rice Chicken Fried |
176 | %p.beans{ :food => 'true' } The magical fruit |
177 | %h1.class.otherclass#id La La La |
178 | |
179 | is compiled to: |
180 | |
181 | <div id='things'> |
182 | <span id='rice'>Chicken Fried</span> |
183 | <p class='beans' food='true'>The magical fruit</p> |
184 | <h1 class='class' id='id'>La La La</h1> |
185 | </div> |
186 | |
187 | And, |
188 | |
189 | #content |
190 | .articles |
191 | .article.title |
192 | Doogie Howser Comes Out |
193 | .article.date |
194 | 2006-11-05 |
195 | .article.entry |
196 | Neil Patrick Harris would like to dispel any rumors that he is straight |
197 | |
198 | is compiled to: |
199 | |
200 | <div id="content"> |
201 | <div class="articles"> |
202 | <div class="article title">Doogie Howser Comes Out</div> |
203 | <div class="article date">2006-11-05</div> |
204 | <div class="article entry"> |
205 | Neil Patrick Harris would like to dispel any rumors that he is straight |
206 | </div> |
207 | </div> |
208 | </div> |
209 | |
210 | ==== Implicit Div Elements |
211 | |
212 | Because the div element is used so often, it is the default element. |
213 | If you only define a class and/or id using the <tt>.</tt> or <tt>#</tt> syntax, |
214 | a div element is automatically used. |
215 | For example: |
216 | |
217 | #collection |
218 | .item |
219 | .description What a cool item! |
220 | |
221 | is the same as: |
222 | |
223 | %div{:id => collection} |
224 | %div{:class => 'item'} |
225 | %div{:class => 'description'} What a cool item! |
226 | |
227 | and is compiled to: |
228 | |
229 | <div id='collection'> |
230 | <div class='item'>Broken record album</div> |
231 | <div class='description'>What a cool item!</div> |
232 | </div> |
233 | |
234 | ==== = and ~ |
235 | |
236 | <tt>=</tt> and <tt>~</tt> are placed at the end of a tag definition, |
237 | after class, id, and attribute declarations. |
238 | They're just shortcuts for inserting Ruby code into an element. |
239 | They work the same as <tt>=</tt> and <tt>~</tt> without a tag; |
240 | see below for documentation of those. |
241 | However, if the result is short enough, |
242 | it is displayed entirely on one line. |
243 | For example: |
244 | |
245 | %p= "hello" |
246 | %h1~ 1 + 2 |
247 | |
248 | is not quite the same as: |
249 | |
250 | %p |
251 | = "hello" |
252 | %h1 |
253 | ~ 1 + 2 |
254 | |
255 | It's compiled to: |
256 | |
257 | <p>hello</p> |
258 | <h1>3</h1> |
259 | |
260 | === XHTML Helpers |
261 | |
262 | ==== No Special Character |
263 | |
264 | If no special character appears at the beginning of a line, |
265 | the line is rendered as plain text. |
266 | For example: |
267 | |
268 | %gee |
269 | %whiz |
270 | Wow this is cool! |
271 | |
272 | is compiled to: |
273 | |
274 | <gee> |
275 | <whiz> |
276 | Wow this is cool! |
277 | </whiz> |
278 | </gee> |
279 | |
280 | ==== !!! |
281 | |
282 | When describing XHTML documents with Haml, |
283 | you can have a document type or XML prolog generated automatically |
284 | by including the characters <tt>!!!</tt>. |
285 | For example: |
286 | |
287 | !!! XML |
288 | !!! |
289 | %html |
290 | %head |
291 | %title Myspace |
292 | %body |
293 | %h1 I am the international space station |
294 | %p Sign my guestbook |
295 | |
296 | is compiled to: |
297 | |
298 | <?xml version="1.0" encoding="utf-8" ?> |
299 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
300 | <html> |
301 | <head> |
302 | <title>Myspace</title> |
303 | </head> |
304 | <body> |
305 | <h1>I am the international space station</h1> |
306 | <p>Sign my guestbook</p> |
307 | </body> |
308 | </html> |
309 | |
310 | You can also specify the version and type of XHTML after the <tt>!!!</tt>. |
311 | XHTML 1.0 Strict, Transitional, and Frameset and XHTML 1.1 are supported. |
312 | The default version is 1.0 and the default type is Transitional. |
313 | For example: |
314 | |
315 | !!! 1.1 |
316 | |
317 | is compiled to: |
318 | |
319 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> |
320 | |
321 | and |
322 | |
323 | !!! Strict |
324 | |
325 | is compiled to: |
326 | |
327 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
328 | |
329 | If you're not using the UTF-8 characterset for your document, |
330 | you can specify which encoding should appear |
331 | in the XML prolog in a similar way. |
332 | For example: |
333 | |
334 | !!! XML iso-8859-1 |
335 | |
336 | is compiled to: |
337 | |
338 | <?xml version="1.0" encoding="iso-8859-1" ?> |
339 | |
340 | ==== / |
341 | |
342 | The forward slash character, when placed at the beginning of a line, |
343 | wraps all text after it in an HTML comment. |
344 | For example: |
345 | |
346 | %billabong |
347 | / This is the billabong element |
348 | I like billabongs! |
349 | |
350 | is compiled to: |
351 | |
352 | <billabong> |
353 | <!-- This is the billabong element --> |
354 | I like billabongs! |
355 | </billabong> |
356 | |
357 | The forward slash can also wrap indented sections of code. For example: |
358 | |
359 | / |
360 | %p This doesn't render... |
361 | %div |
362 | %h1 Because it's commented out! |
363 | |
364 | is compiled to: |
365 | |
366 | <!-- |
367 | <p>This doesn't render...</p> |
368 | <div> |
369 | <h1>Because it's commented out!</h1> |
370 | </div> |
371 | --> |
372 | |
373 | You can also use Internet Explorer conditional comments |
374 | (about)[http://www.quirksmode.org/css/condcom.html] |
375 | by enclosing the condition in square brackets after the <tt>/</tt>. |
376 | For example: |
377 | |
378 | /[if IE] |
379 | %a{ :href => 'http://www.mozilla.com/en-US/firefox/' } |
380 | %h1 Get Firefox |
381 | |
382 | is compiled to: |
383 | |
384 | <!--[if IE]> |
385 | <a href='http://www.mozilla.com/en-US/firefox/'> |
386 | <h1>Get Firefox</h1> |
387 | </a> |
388 | <![endif]--> |
389 | |
390 | ==== \ |
391 | |
392 | The backslash character escapes the first character of a line, |
393 | allowing use of otherwise interpreted characters as plain text. |
394 | For example: |
395 | |
396 | %title |
397 | = @title |
398 | \- MySite |
399 | |
400 | is compiled to: |
401 | |
402 | <title> |
403 | MyPage |
404 | - MySite |
405 | </title> |
406 | |
407 | ==== | |
408 | |
409 | The pipe character designates a multiline string. |
410 | It's placed at the end of a line |
411 | and means that all following lines that end with <tt>|</tt> |
412 | will be evaluated as though they were on the same line. |
413 | For example: |
414 | |
415 | %whoo |
416 | %hoo I think this might get | |
417 | pretty long so I should | |
418 | probably make it | |
419 | multiline so it doesn't | |
420 | look awful. | |
421 | %p This is short. |
422 | |
423 | is compiled to: |
424 | |
425 | %hoo I think this might get | |
426 | pretty long so I should | |
427 | probably make it | |
428 | multiline so it doesn't | |
429 | look awful. | |
430 | |
431 | === Ruby evaluators |
432 | |
433 | ==== = |
434 | |
435 | The equals character is followed by Ruby code, |
436 | which is evaluated and the output inserted into the document as plain text. |
437 | For example: |
438 | |
439 | %p |
440 | = ['hi', 'there', 'reader!'].join " " |
441 | = "yo" |
442 | |
443 | is compiled to: |
444 | |
445 | <p> |
446 | hi there reader! |
447 | yo |
448 | </p> |
449 | |
450 | ==== ~ |
451 | |
452 | The tilde character works the same as the equals character, |
453 | but the output is modified in such a way |
454 | that newlines in whitespace-sensitive elements work properly. |
455 | For example: |
456 | |
457 | %foo |
458 | = "Woah <pre> this is \n</pre> crazy" |
459 | %foo2 |
460 | ~ "Woah <pre> this is \n</pre> crazy" |
461 | |
462 | is compiled to: |
463 | |
464 | <foo> |
465 | Woah <pre> this is |
466 | </pre> crazy |
467 | </foo> |
468 | <foo2> |
469 | Woah <pre> this is 
</pre> crazy |
470 | </foo2> |
471 | |
472 | If the ~ character isn't followed by text, |
473 | it doesn't evaluate Ruby at all. |
474 | Instead, an indented section following it will be rendered |
475 | in a whitespace-sensitive manner, |
476 | using HTML encodings for newlines. |
477 | For example: |
478 | |
479 | For example: |
480 | |
481 | .house |
482 | %pre |
483 | ~ |
484 | /^^^\ |
485 | |[] []| |
486 | |_____| |
487 | |
488 | is compiled to: |
489 | |
490 | <div class="house"> |
491 | <pre> |
492 | 
 /^^^\
|[] []|
|_____|
 |
493 | </pre> |
494 | </div> |
495 | |
496 | ==== - |
497 | |
498 | The hyphen character makes the text following it into "silent script": |
499 | Ruby script that is evaluated, but not output. |
500 | |
501 | <b>It is not recommended that you use this widely; |
502 | almost all processing code and logic should be restricted |
503 | to the Controller, the Helper, or partials.</b> |
504 | |
505 | For example: |
506 | |
507 | - foo = "hello" |
508 | - foo << " there" |
509 | - foo << " you!" |
510 | %p= foo |
511 | |
512 | is compiled to: |
513 | |
514 | <p> |
515 | hello there you! |
516 | </p> |
517 | |
518 | ===== Blocks |
519 | |
520 | Ruby blocks, like XHTML tags, don't need to be explicitly closed in Haml. |
521 | Rather, they're automatically closed, based on indentation. |
522 | A block begins whenever the indentation is increased |
523 | after a silent script command. |
524 | It ends when the indentation decreases |
525 | (as long as it's not an +else+ clause or something similar). |
526 | For example: |
527 | |
528 | - (42...47).each do |i| |
529 | %p= i |
530 | %p See, I can count! |
531 | |
532 | is compiled to: |
533 | |
534 | <p> |
535 | 42 |
536 | </p> |
537 | <p> |
538 | 43 |
539 | </p> |
540 | <p> |
541 | 44 |
542 | </p> |
543 | <p> |
544 | 45 |
545 | </p> |
546 | <p> |
547 | 46 |
548 | </p> |
549 | |
550 | Another example: |
551 | |
552 | %p |
553 | - case 2 |
554 | - when 1 |
555 | = "1!" |
556 | - when 2 |
557 | = "2?" |
558 | - when 3 |
559 | = "3." |
560 | |
561 | is compiled to: |
562 | |
563 | <p> |
564 | 2? |
565 | </p> |
566 | |
567 | == Using Haml as a Rails plugin |
568 | |
569 | Write Rails templates with the .haml extension. |
570 | For example: |
571 | |
572 | # file: app/views/movies/teen_wolf.haml |
573 | |
574 | %html |
575 | %head |
576 | %title= "Teen Wolf (1985)" |
577 | %body |
578 | #contents |
579 | %h1 "A highschooler discovers that he is a werewolf" |
580 | %ul.cast |
581 | %li "Scott Howard" |
582 | %li "Rupert 'Stiles' Stilinski" |
583 | %li "Lisa 'Boof' Marconi" |
584 | %li "Lewis" |
585 | |
586 | is compiled to: |
587 | |
588 | <html> |
589 | <head> |
590 | <title>Teen Wolf (1985)</title> |
591 | </head> |
592 | <body> |
593 | <div id='contents'> |
594 | <h1>A highschooler discovers that he is a werewolf</h1> |
595 | <ul class='cast'> |
596 | <li>Scott Howard</li> |
597 | <li>Rupert 'Stiles' Stilinski</li> |
598 | <li>Lisa 'Boof' Marconi</li> |
599 | <li>Lewis</li> |
600 | </ul> |
601 | </div> |
602 | </body> |
603 | </html> |
604 | |
605 | You can access instance variables in Haml templates |
606 | the same way you do in ERb templates. |
607 | Helper methods are also available in Haml templates. |
608 | For example: |
609 | |
610 | # file: app/controllers/movies_controller.rb |
611 | |
612 | class MoviesController < ApplicationController |
613 | def index |
614 | @title = "Teen Wolf" |
615 | end |
616 | end |
617 | |
618 | # file: app/views/movies/index.haml |
619 | |
620 | #content |
621 | .title |
622 | %h1= @title |
623 | = link_to 'Home', home_url |
624 | |
625 | may be compiled to: |
626 | |
627 | <div id='content'> |
628 | <div class='title'> |
629 | <h1>Teen Wolf</h1> |
630 | <a href='/'>Home</a> |
631 | </div> |
632 | </div> |
633 | |
634 | === Setting Options |
635 | |
636 | Options can be set by setting the hash <tt>Haml::Template.options</tt> |
637 | from <tt>environment.rb</tt>. |
638 | Available options are: |
639 | |
640 | [<tt>:suppress_eval</tt>] Whether or not attribute hashes and Ruby scripts |
641 | designated by <tt>=</tt> or <tt>~</tt> should be |
642 | evaluated. If this is true, said scripts are |
643 | rendered as empty strings. Defaults to false. |
644 | |
645 | [<tt>:precompiled</tt>] A string containing a precompiled Haml template. |
646 | If this is passed, <tt>template</tt> is ignored |
647 | and no precompilation is done. |
648 | |
649 | [<tt>:attr_wrapper</tt>] The character that should wrap element attributes. |
650 | This defaults to <tt>'</tt> (an apostrophe). Characters |
651 | of this type within the attributes will be escaped |
652 | (e.g. by replacing them with <tt>'</tt>) if |
653 | the character is an apostrophe or a quotation mark. |
654 | |
655 | [<tt>:locals</tt>] The local variables that will be available within the |
656 | template. For instance, if <tt>:locals</tt> is |
657 | <tt>{ :foo => "bar" }</tt>, then within the template, |
658 | <tt>= foo</tt> will produce <tt>bar</tt>. |
659 | |
660 | --- |
661 | Copyright (c) 2006 Hampton Catlin |
662 | Licensed under the MIT License |