0
@@ -22,6 +22,9 @@ HAML was originally created by Hampton Catlin (hcatlin). Help with the
0
Ruby On Rails implementation and much of the documentation by
0
Jeff Hardy (packagethief).
0
+Nathan Weizenbaum (Nex3) contribued the buffered-engine code along with many
0
+other enhancements including the silent-line syntax ("-").
0
If you use this software, you must pay Hampton a compliment. Say something
0
nice about it. Beyond that, the implementation is licensed under the MIT
0
License. Ok, fine, I guess that means compliments aren't *required*.
0
@@ -50,72 +53,185 @@ is compiled to:
0
== Characters with meaning to Haml
0
-Haml responds to certain special characters. To create an element in the form of
0
-<tt><element></element></tt> use the <tt>%</tt> character, immediately followed
0
-by the element name. To specify attributes, include a hash of attributes inside
0
+Various characters, when placed at a certain point in a line, instruct HAML
0
+to render different types of things.
0
+These characters render XHTML tags.
0
+This element is placed at the beginning of a line. It's followed immediately
0
+by the name of an element, then optionally by modifiers (see below), a space,
0
+and text to be rendered inside the element. It creates an element in the form of
0
+<tt><element></element></tt>. For example:
0
- %meta{:content => 'something'}/
0
- <meta content='something' />
0
<three>Hey there</three>
0
Any string is a valid element name; Haml will automatically generate opening and
0
-closing tags for any element. When you want to force the output of a
0
-self-closing tag, use the forward slash character. Example:
0
+closing tags for any element.
0
+Brackets represent a Ruby hash that is used for specifying the attributes of an
0
+element. It is literally evaluated as a Ruby hash, so logic will work in it. At
0
+the moment, though, it doesn't see local variables. The hash is placed after
0
+the tag is defined. For example:
0
+ %head{ :name => "doc_head" }
0
+ %script{ 'type' => "text/" + "javascript", :src => "javascripts/script_#{2 + 7}" }
0
+ <head name="doc_head">
0
+ <script src='javascripts/script_9' type='text/javascript'>
0
+Square brackets follow a tag definiton and contain a Ruby object that is used to
0
+set the class and id of that tag. The class is set to the object's class
0
+(transformed to use underlines rather than camel case), and the id is set to the
0
+object's class followed by its id. Because the id of an object is normally an
0
+obscure implementation detail, this is most useful for elements that represent
0
+instances of Models. For example:
0
+ # file: app/controllers/users_controller.rb
0
+ @user = CrazyUser.find(15)
0
+ # file: app/views/users/show.haml
0
+ <div class="crazy_user" id="crazy_user_15">
0
+ <bar class="fixnum" id="fixnum_581" />
0
+This is based off of DHH's SimplyHelpful syntax as presented at RailsConf Europe 2006.
0
+The forward slash character, when placed at the end of a tag definition, causes
0
+the tag to be self-closed. For example:
0
%meta{:http-equiv => 'Content-Type', :content => 'text/html'}/
0
- # => <meta http-equiv='Content-Type' content='text/html' />
0
-HTML div elements are assumed when no <tt>%tag</tt> is present and the line is
0
-preceeded by either the <tt>#</tt> or the <tt>.</tt> characters. This convention
0
-uses familiar CSS semantics: <tt>#</tt> denotes the id of the element,
0
-<tt>.</tt> denotes its class name. Example:
0
+ <meta http-equiv='Content-Type' content='text/html' />
0
+The period and pound sign are borrowed from CSS and used as shortcuts to specify the
0
+<tt>class</tt> and <tt>id</tt> attributes of an element, respectively. They are
0
+placed immediately after the tag, and before an attributes hash. For example:
0
+ %span#rice Chicken Fried
0
+ %p.beans{ :food => 'true' } The magical fruit
0
+ <span id='rice'>Chicken Fried</span>
0
+ <p class='beans' food='true'>The magical fruit</p>
0
+ <h1 class='class' id='id'>La La La</h1>
0
+Because the div element is used so often, it is the default element. If you only
0
+define a class and/or id using the <tt>.</tt> or <tt>#</tt> syntax, a div element
0
+is automatically used. For example:
0
+ .description What a cool item!
0
%div{:id => collection}
0
+
%div{:class => 'description'} What a cool item!0
<div class='item'>Broken record album</div>
0
+ <div class='description'>What a cool item!</div>
0
-There is a shortcut when you want to specify either the id or class attributes
0
-of an element: follow the element name with either the <tt>#</tt> or the
0
-<tt>.</tt> characters. Example:
0
+<tt>=</tt> and <tt>~</tt> are placed at the end of a tag definition, after class,
0
+id, and attribute declarations. They're just shortcuts for inserting Ruby code
0
+into an element. They work the same as <tt>=</tt> and <tt>~</tt> without a tag;
0
+see below for documentation of those. For example:
0
- %span#rice Chicken Fried
0
- %p.beans The magical fruit
0
+==== No Special Character
0
+If no special character appears at the beginning of a line, it is rendered as plain
0
- <span id='rice'>Chicken Fried</span>
0
- <p class='beans'>The magical fruit</p>
0
-===
Specifying a document type0
-When describing
xhtml documents with Haml, you can have a document type
0
+When describing
XHTML documents with Haml, you can have a document type
0
generated automatically by including the characters <tt>!!!</tt> as the first
0
line in your document. Example:
0
@@ -139,11 +255,158 @@ is compiled to:
0
<p>Sign my guestbook</p>
0
+The forward slash character, when placed at the beginning of a line, wraps all
0
+text after it in an HTML comment. For example:
0
+ / This is the billabong element
0
+ <!-- This is the billabong element -->
0
+The pipe character designates a multiline string. It's placed at the end of a line,
0
+and means that all following lines that end with <tt>|</tt> will be evaluated as
0
+though they were on the same line. For example:
0
+ %hoo I think this might get |
0
+ pretty long so I should |
0
+ multiline so it doesn't |
0
+ %hoo I think this might get |
0
+ pretty long so I should |
0
+ multiline so it doesn't |
0
+The equals character is followed by Ruby code, which is evaluated and the output
0
+inserted into the document as plain text. For example:
0
+ = ['hi', 'there', 'reader!'].join " "
0
+The tilde character works the same as the equals character, but the output is
0
+modified in such a way that newlines in whitespace-sensitive elements work
0
+ = "Woah <pre> this is \n</pre> crazy"
0
+ ~ "Woah <pre> this is \n</pre> crazy"
0
+ Woah <pre> this is 
</pre> crazy
0
+The hyphen character makes the text following it into "silent script", or
0
+Ruby script that is evaluated, but not output.
0
+<b>It is not reccomended that you use this widely; almost all processing
0
+code and logic should be kept to the Controller, the Helper, or partials.</b>
0
+Like XHTML tags, you don't need to explicity close your Ruby blocks in
0
+HAML. Rather, they're automatically closed based on tabs. A block begins
0
+whenever the indentation is increased after a silent script command, and
0
+ends when the indentation decreases (as long as it's not an +else+ clause
0
+or something similar). For example:
0
+ - (42...47).each do |i|
0
== Using Haml as a Rails plugin
0
Write Rails templates with the .haml extension. Example:
0
+ # file: app/views/movies/teen_wolf.haml
0
%title= "Teen Wolf (1985)"
0
@@ -176,12 +439,9 @@ is compiled to:
0
You can access instance variables in Haml templates the same way you do in ERb
0
-templates. Helper methods are also available in Haml templates. To specify that
0
-a line should be evaulated as Ruby, use the <tt>=</tt> character at the begining
0
-of a line, or immediately following an element name. The return value of the
0
-method call will be inserted into the stream. Example:
0
+templates. Helper methods are also available in Haml templates. Example:
0
-
file: app/controllers/movies_controller.rb
0
+
# file: app/controllers/movies_controller.rb
0
class MoviesController < ApplicationController
0
@@ -189,14 +449,14 @@ method call will be inserted into the stream. Example:
0
-
file: app/views/movies/index.haml
0
+
# file: app/views/movies/index.haml
0
= link_to 'Home', home_url
0
@@ -206,8 +466,6 @@ is be compiled to:
0
Copyright (c) 2006 Hampton Catlin
0
Licensed under the MIT License
) is private.
