Brought docs up to date, made REFERENCE formatting more consistent.
This commit is contained in:
Norman Clarke
parent
debd767dbb
commit
bf9cd14de8
|
|
@ -725,7 +725,7 @@ Thanks to [Josh Peek](http://joshpeek.com/).
|
|||
|
||||
[Tagged on GitHub](http://github.com/nex3/haml/commit/2.2.21).
|
||||
|
||||
* Fix a few bugs in the git-revision-reporting in {Haml::Version#version}.
|
||||
* Fix a few bugs in the git-revision-reporting in Haml::Version.
|
||||
In particular, it will still work if `git gc` has been called recently,
|
||||
or if various files are missing.
|
||||
|
||||
|
|
|
|||
484
REFERENCE.md
484
REFERENCE.md
|
|
@ -1,13 +1,11 @@
|
|||
# Haml (XHTML Abstraction Markup Language)
|
||||
|
||||
Haml is a markup language
|
||||
that's used to cleanly and simply describe the XHTML of any web document,
|
||||
without the use of inline code.
|
||||
Haml functions as a replacement
|
||||
for inline page templating systems such as PHP, ERB, and ASP.
|
||||
However, Haml avoids the need for explicitly coding XHTML into the template,
|
||||
because it is actually an abstract description of the XHTML,
|
||||
with some code to generate dynamic content.
|
||||
Haml is a markup language that's used to cleanly and simply describe the XHTML
|
||||
of any web document, without the use of inline code. Haml functions as a
|
||||
replacement for inline page templating systems such as PHP, ERB, and ASP.
|
||||
However, Haml avoids the need for explicitly coding HTML into the template,
|
||||
because it is actually an abstract description of the HTML, with some code to
|
||||
generate dynamic content.
|
||||
|
||||
## Features
|
||||
|
||||
|
|
@ -21,9 +19,11 @@ with some code to generate dynamic content.
|
|||
## Using Haml
|
||||
|
||||
Haml can be used in three ways:
|
||||
as a command-line tool,
|
||||
as a plugin for Ruby on Rails,
|
||||
and as a standalone Ruby module.
|
||||
|
||||
* as a command-line tool,
|
||||
* as a plugin for Ruby on Rails,
|
||||
* and as a standalone Ruby module.
|
||||
|
||||
The first step for all of these is to install the Haml gem:
|
||||
|
||||
gem install haml
|
||||
|
|
@ -38,13 +38,11 @@ To use Haml with Rails, add the following line to the Gemfile:
|
|||
|
||||
gem "haml"
|
||||
|
||||
Once it's installed, all view files with the `".html.haml"` extension
|
||||
will be compiled using Haml.
|
||||
Once it's installed, all view files with the `".html.haml"` extension will be
|
||||
compiled using Haml.
|
||||
|
||||
You can access instance variables in Haml templates
|
||||
the same way you do in ERB templates.
|
||||
Helper methods are also available in Haml templates.
|
||||
For example:
|
||||
You can access instance variables in Haml templates the same way you do in ERB
|
||||
templates. Helper methods are also available in Haml templates. For example:
|
||||
|
||||
# file: app/controllers/movies_controller.rb
|
||||
|
||||
|
|
@ -70,34 +68,33 @@ may be compiled to:
|
|||
</div>
|
||||
</div>
|
||||
|
||||
#### Rails XSS Protection
|
||||
### Rails XSS Protection
|
||||
|
||||
Haml supports Rails' XSS protection scheme,
|
||||
which was introduced in Rails 2.3.5+ and is enabled by default in 3.0.0+.
|
||||
If it's enabled, Haml's [`:escape_html`](#escape_html-option)
|
||||
option is set to `true` by default -
|
||||
like in ERB, all strings printed to a Haml template are escaped by default.
|
||||
Also like ERB, strings marked as HTML safe are not escaped.
|
||||
Haml also has [its own syntax for printing a raw string to the template](#unescaping_html).
|
||||
Haml supports Rails' XSS protection scheme, which was introduced in Rails 2.3.5+
|
||||
and is enabled by default in 3.0.0+. If it's enabled, Haml's
|
||||
{Haml::Options#escape_html `:escape_html`} option is set to `true` by default -
|
||||
like in ERB, all strings printed to a Haml template are escaped by default. Also
|
||||
like ERB, strings marked as HTML safe are not escaped. Haml also has [its own
|
||||
syntax for printing a raw string to the template](#unescaping_html).
|
||||
|
||||
If the `:escape_html` option is set to false when XSS protection is enabled,
|
||||
Haml doesn't escape Ruby strings by default.
|
||||
However, if a string marked HTML-safe is passed to [Haml's escaping syntax](#escaping_html),
|
||||
it won't be escaped.
|
||||
Haml doesn't escape Ruby strings by default. However, if a string marked
|
||||
HTML-safe is passed to [Haml's escaping syntax](#escaping_html), it won't be
|
||||
escaped.
|
||||
|
||||
Finally, all the {Haml::Helpers Haml helpers} that return strings
|
||||
that are known to be HTML safe are marked as such.
|
||||
In addition, string input is escaped unless it's HTML safe.
|
||||
Finally, all the {Haml::Helpers Haml helpers} that return strings that are known
|
||||
to be HTML safe are marked as such. In addition, string input is escaped unless
|
||||
it's HTML safe.
|
||||
|
||||
### Ruby Module
|
||||
|
||||
Haml can also be used completely separately from Rails and ActionView.
|
||||
To do this, install the gem with RubyGems:
|
||||
Haml can also be used completely separately from Rails and ActionView. To do
|
||||
this, install the gem with RubyGems:
|
||||
|
||||
gem install haml
|
||||
|
||||
You can then use it by including the "haml" gem in Ruby code,
|
||||
and using {Haml::Engine} like so:
|
||||
You can then use it by including the "haml" gem in Ruby code, and using
|
||||
{Haml::Engine} like so:
|
||||
|
||||
engine = Haml::Engine.new("%p Haml code!")
|
||||
engine.render #=> "<p>Haml code!</p>\n"
|
||||
|
|
@ -107,8 +104,8 @@ and using {Haml::Engine} like so:
|
|||
Haml understands various configuration options that affect its performance and
|
||||
output.
|
||||
|
||||
In Rails, options can be set by setting the {Haml::Template#options
|
||||
Haml::Template.options} hash in an initializer:
|
||||
In Rails, options can be set by setting the {Haml::Template#options Haml::Template.options}
|
||||
hash in an initializer:
|
||||
|
||||
# config/initializers/haml.rb
|
||||
Haml::Template.options[:format] = :html5
|
||||
|
|
@ -123,30 +120,27 @@ see {Haml::Options}.
|
|||
|
||||
### Encodings
|
||||
|
||||
When using Ruby 1.9 or later,
|
||||
Haml supports the same sorts of encoding-declaration comments that Ruby does.
|
||||
Although both Ruby and Haml support several different styles,
|
||||
the easiest it just to add `-# coding: encoding-name`
|
||||
at the beginning of the Haml template
|
||||
(it must come before all other lines).
|
||||
This will tell Haml that the template is encoded using the named encoding.
|
||||
When using Ruby 1.9 or later, Haml supports the same sorts of
|
||||
encoding-declaration comments that Ruby does. Although both Ruby and Haml
|
||||
support several different styles, the easiest it just to add `-# coding:
|
||||
encoding-name` at the beginning of the Haml template (it must come before all
|
||||
other lines). This will tell Haml that the template is encoded using the named
|
||||
encoding.
|
||||
|
||||
By default, the HTML generated by Haml has the same encoding as the Haml template.
|
||||
However, if `Encoding.default_internal` is set, Haml will attempt to use that instead.
|
||||
In addition, the [`:encoding` option](#encoding-option) can be used
|
||||
to specify an output encoding manually.
|
||||
By default, the HTML generated by Haml has the same encoding as the Haml
|
||||
template. However, if `Encoding.default_internal` is set, Haml will attempt to
|
||||
use that instead. In addition, the [`:encoding` option](#encoding-option) can be
|
||||
used to specify an output encoding manually.
|
||||
|
||||
Note that, like Ruby, Haml does not support templates encoded in UTF-16 or UTF-32,
|
||||
since these encodings are not compatible with ASCII.
|
||||
It is possible to use these as the output encoding, though.
|
||||
Note that, like Ruby, Haml does not support templates encoded in UTF-16 or
|
||||
UTF-32, since these encodings are not compatible with ASCII. It is possible to
|
||||
use these as the output encoding, though.
|
||||
|
||||
## Plain Text
|
||||
|
||||
A substantial portion of any HTML document is its content,
|
||||
which is plain old text.
|
||||
Any Haml line that's not interpreted as something else
|
||||
is taken to be plain text, and passed through unmodified.
|
||||
For example:
|
||||
A substantial portion of any HTML document is its content, which is plain old
|
||||
text. Any Haml line that's not interpreted as something else is taken to be
|
||||
plain text, and passed through unmodified. For example:
|
||||
|
||||
%gee
|
||||
%whiz
|
||||
|
|
@ -160,11 +154,9 @@ is compiled to:
|
|||
</whiz>
|
||||
</gee>
|
||||
|
||||
Note that HTML tags are passed through unmodified as well.
|
||||
If you have some HTML you don't want to convert to Haml,
|
||||
or you're converting a file line-by-line,
|
||||
you can just include it as-is.
|
||||
For example:
|
||||
Note that HTML tags are passed through unmodified as well. If you have some HTML
|
||||
you don't want to convert to Haml, or you're converting a file line-by-line, you
|
||||
can just include it as-is. For example:
|
||||
|
||||
%p
|
||||
<div id="blah">Blah!</div>
|
||||
|
|
@ -177,9 +169,8 @@ is compiled to:
|
|||
|
||||
### Escaping: `\`
|
||||
|
||||
The backslash character escapes the first character of a line,
|
||||
allowing use of otherwise interpreted characters as plain text.
|
||||
For example:
|
||||
The backslash character escapes the first character of a line, allowing use of
|
||||
otherwise interpreted characters as plain text. For example:
|
||||
|
||||
%title
|
||||
= @title
|
||||
|
|
@ -197,12 +188,10 @@ is compiled to:
|
|||
|
||||
### Element Name: `%`
|
||||
|
||||
The percent character is placed at the beginning of a line.
|
||||
It's followed immediately by the name of an element,
|
||||
then optionally by modifiers (see below), a space,
|
||||
and text to be rendered inside the element.
|
||||
It creates an element in the form of `<element></element>`.
|
||||
For example:
|
||||
The percent character is placed at the beginning of a line. It's followed
|
||||
immediately by the name of an element, then optionally by modifiers (see below),
|
||||
a space, and text to be rendered inside the element. It creates an element in
|
||||
the form of `<element></element>`. For example:
|
||||
|
||||
%one
|
||||
%two
|
||||
|
|
@ -216,19 +205,16 @@ is compiled to:
|
|||
</two>
|
||||
</one>
|
||||
|
||||
Any string is a valid element name;
|
||||
Haml will automatically generate opening and closing tags for any element.
|
||||
Any string is a valid element name; Haml will automatically generate opening and
|
||||
closing tags for any element.
|
||||
|
||||
### Attributes: `{}` or `()` {#attributes}
|
||||
|
||||
Brackets represent a Ruby hash
|
||||
that is used for specifying the attributes of an element.
|
||||
It is literally evaluated as a Ruby hash,
|
||||
so logic will work in it and local variables may be used.
|
||||
Quote characters within the attribute
|
||||
will be replaced by appropriate escape sequences.
|
||||
The hash is placed after the tag is defined.
|
||||
For example:
|
||||
Brackets represent a Ruby hash that is used for specifying the attributes of an
|
||||
element. It is literally evaluated as a Ruby hash, so logic will work in it and
|
||||
local variables may be used. Quote characters within the attribute will be
|
||||
replaced by appropriate escape sequences. The hash is placed after the tag is
|
||||
defined. For example:
|
||||
|
||||
%html{:xmlns => "http://www.w3.org/1999/xhtml", "xml:lang" => "en", :lang => "en"}
|
||||
|
||||
|
|
@ -236,9 +222,8 @@ is compiled to:
|
|||
|
||||
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'></html>
|
||||
|
||||
Attribute hashes can also be stretched out over multiple lines
|
||||
to accommodate many attributes.
|
||||
However, newlines may only be placed immediately after commas.
|
||||
Attribute hashes can also be stretched out over multiple lines to accommodate
|
||||
many attributes. However, newlines may only be placed immediately after commas.
|
||||
For example:
|
||||
|
||||
%script{:type => "text/javascript",
|
||||
|
|
@ -251,11 +236,9 @@ is compiled to:
|
|||
#### `:class` and `:id` Attributes
|
||||
{#class-and-id-attributes}
|
||||
|
||||
The `:class` and `:id` attributes can also be specified as a Ruby array
|
||||
whose elements will be joined together.
|
||||
A `:class` array is joined with `" "`
|
||||
and an `:id` array is joined with `"_"`.
|
||||
For example:
|
||||
The `:class` and `:id` attributes can also be specified as a Ruby array whose
|
||||
elements will be joined together. A `:class` array is joined with `" "` and an
|
||||
`:id` array is joined with `"_"`. For example:
|
||||
|
||||
%div{:id => [@item.type, @item.number], :class => [@item.type, @item.urgency]}
|
||||
|
||||
|
|
@ -263,10 +246,8 @@ is equivalent to:
|
|||
|
||||
%div{:id => "#{@item.type}_#{@item.number}", :class => "#{@item.type} #{@item.urgency}"}
|
||||
|
||||
The array will first be flattened
|
||||
and any elements that do not test as true will be removed.
|
||||
The remaining elements will be converted to strings.
|
||||
For example:
|
||||
The array will first be flattened and any elements that do not test as true will
|
||||
be removed. The remaining elements will be converted to strings. For example:
|
||||
|
||||
%div{:class => [@item.type, @item == @sortcol && [:sort, @sortdir]] } Contents
|
||||
|
||||
|
|
@ -277,13 +258,11 @@ could render as any of:
|
|||
<div class="sort descending">Contents</div>
|
||||
<div>Contents</div>
|
||||
|
||||
depending on whether `@item.type` is `"numeric"` or `nil`,
|
||||
whether `@item == @sortcol`,
|
||||
depending on whether `@item.type` is `"numeric"` or `nil`, whether `@item == @sortcol`,
|
||||
and whether `@sortdir` is `"ascending"` or `"descending"`.
|
||||
|
||||
If a single value is specified and it evaluates to false it is ignored;
|
||||
otherwise it gets converted to a string.
|
||||
For example:
|
||||
otherwise it gets converted to a string. For example:
|
||||
|
||||
.item{:class => @item.is_empty? && "empty"}
|
||||
|
||||
|
|
@ -294,15 +273,13 @@ could render as either of:
|
|||
|
||||
#### HTML-style Attributes: `()`
|
||||
|
||||
Haml also supports a terser, less Ruby-specific attribute syntax
|
||||
based on HTML's attributes.
|
||||
These are used with parentheses instead of brackets, like so:
|
||||
Haml also supports a terser, less Ruby-specific attribute syntax based on HTML's
|
||||
attributes. These are used with parentheses instead of brackets, like so:
|
||||
|
||||
%html(xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en")
|
||||
|
||||
Ruby variables can be used by omitting the quotes.
|
||||
Local variables or instance variables can be used.
|
||||
For example:
|
||||
Ruby variables can be used by omitting the quotes. Local variables or instance
|
||||
variables can be used. For example:
|
||||
|
||||
%a(title=@title href=href) Stuff
|
||||
|
||||
|
|
@ -310,28 +287,32 @@ This is the same as:
|
|||
|
||||
%a{:title => @title, :href => href} Stuff
|
||||
|
||||
Because there are no commas separating attributes, though,
|
||||
more complicated expressions aren't allowed.
|
||||
For those you'll have to use the `{}` syntax.
|
||||
You can, however, use both syntaxes together:
|
||||
Because there are no commas separating attributes, though, more complicated
|
||||
expressions aren't allowed. For those you'll have to use the `{}` syntax. You
|
||||
can, however, use both syntaxes together:
|
||||
|
||||
%a(title=@title){:href => @link.href} Stuff
|
||||
|
||||
You can also use `#{}` interpolation to insert complicated expressions
|
||||
in a HTML-style attribute:
|
||||
You can also use `#{}` interpolation to insert complicated expressions in a
|
||||
HTML-style attribute:
|
||||
|
||||
%span(class="widget_#{@widget.number}")
|
||||
|
||||
HTML-style attributes can be stretched across multiple lines
|
||||
just like hash-style attributes:
|
||||
HTML-style attributes can be stretched across multiple lines just like
|
||||
hash-style attributes:
|
||||
|
||||
%script(type="text/javascript"
|
||||
src="javascripts/script_#{2 + 7}")
|
||||
|
||||
#### Ruby 1.9-style Hashes
|
||||
|
||||
On Ruby 1.9, Haml also supports Ruby's new hash syntax:
|
||||
|
||||
%a{title: @title, href: href} Stuff
|
||||
|
||||
#### Attribute Methods
|
||||
|
||||
A Ruby method call that returns a hash
|
||||
can be substituted for the hash contents.
|
||||
A Ruby method call that returns a hash can be substituted for the hash contents.
|
||||
For example, {Haml::Helpers} defines the following method:
|
||||
|
||||
def html_attrs(lang = 'en-US')
|
||||
|
|
@ -347,11 +328,9 @@ This is compiled to:
|
|||
<html lang='fr-fr' xml:lang='fr-fr' xmlns='http://www.w3.org/1999/xhtml'>
|
||||
</html>
|
||||
|
||||
You can use as many such attribute methods as you want
|
||||
by separating them with commas,
|
||||
like a Ruby argument list.
|
||||
All the hashes will me merged together, from left to right.
|
||||
For example, if you defined
|
||||
You can use as many such attribute methods as you want by separating them with
|
||||
commas, like a Ruby argument list. All the hashes will me merged together, from
|
||||
left to right. For example, if you defined
|
||||
|
||||
def hash1
|
||||
{:bread => 'white', :filling => 'peanut butter and jelly'}
|
||||
|
|
@ -376,29 +355,29 @@ Attribute methods aren't supported for HTML-style attributes.
|
|||
|
||||
#### Boolean Attributes
|
||||
|
||||
Some attributes, such as "checked" for `input` tags or "selected" for `option` tags,
|
||||
are "boolean" in the sense that their values don't matter -
|
||||
it only matters whether or not they're present.
|
||||
In HTML (but not XHTML), these attributes can be written as
|
||||
Some attributes, such as "checked" for `input` tags or "selected" for `option`
|
||||
tags, are "boolean" in the sense that their values don't matter - it only
|
||||
matters whether or not they're present. In HTML (but not XHTML), these
|
||||
attributes can be written as
|
||||
|
||||
<input selected>
|
||||
|
||||
To do this in Haml using hash-style attributes, just assign a Ruby
|
||||
`true` value to the attribute:
|
||||
To do this in Haml using hash-style attributes, just assign a Ruby `true` value
|
||||
to the attribute:
|
||||
|
||||
%input{:selected => true}
|
||||
|
||||
In XHTML, the only valid value for these attributes is the name of the
|
||||
attribute. Thus this will render in XHTML as
|
||||
attribute. Thus this will render in XHTML as
|
||||
|
||||
<input selected='selected'>
|
||||
|
||||
To set these attributes to false, simply assign them to a Ruby false value.
|
||||
In both XHTML and HTML
|
||||
To set these attributes to false, simply assign them to a Ruby false value. In
|
||||
both XHTML and HTML,
|
||||
|
||||
%input{:selected => false}
|
||||
|
||||
will just render as
|
||||
will just render as:
|
||||
|
||||
<input>
|
||||
|
||||
|
|
@ -412,12 +391,12 @@ or using `true` and `false`:
|
|||
|
||||
#### HTML5 Custom Data Attributes
|
||||
|
||||
HTML5 allows for adding [custom non-visible data attributes](http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#embedding-custom-non-visible-data)
|
||||
to elements using attribute names beginning with `data-`.
|
||||
Custom data attributes can be used in Haml by using the key `:data` with a Hash value
|
||||
in an attribute hash.
|
||||
Each of the key/value pairs in the Hash will be transformed into a custom data attribute.
|
||||
For example:
|
||||
HTML5 allows for adding [custom non-visible data
|
||||
attributes](http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#embedding-custom-non-visible-data)
|
||||
to elements using attribute names beginning with `data-`. Custom data attributes
|
||||
can be used in Haml by using the key `:data` with a Hash value in an attribute
|
||||
hash. Each of the key/value pairs in the Hash will be transformed into a custom
|
||||
data attribute. For example:
|
||||
|
||||
%a{:href=>"/posts", :data => {:author_id => 123}} Posts By Author
|
||||
|
||||
|
|
@ -434,13 +413,11 @@ rendered as:
|
|||
|
||||
### Class and ID: `.` and `#`
|
||||
|
||||
The period and pound sign are borrowed from CSS.
|
||||
They are used as shortcuts to specify the `class`
|
||||
and `id` attributes of an element, respectively.
|
||||
Multiple class names can be specified in a similar way to CSS,
|
||||
by chaining the class names together with periods.
|
||||
They are placed immediately after the tag and before an attributes hash.
|
||||
For example:
|
||||
The period and pound sign are borrowed from CSS. They are used as shortcuts to
|
||||
specify the `class` and `id` attributes of an element, respectively. Multiple
|
||||
class names can be specified in a similar way to CSS, by chaining the class
|
||||
names together with periods. They are placed immediately after the tag and
|
||||
before an attributes hash. For example:
|
||||
|
||||
%div#things
|
||||
%span#rice Chicken Fried
|
||||
|
|
@ -476,11 +453,10 @@ is compiled to:
|
|||
</div>
|
||||
</div>
|
||||
|
||||
These shortcuts can be combined with long-hand attributes;
|
||||
the two values will be merged together
|
||||
as though they were all placed in an array
|
||||
(see [the documentation on `:class` and `:id` attributes](#class-and-id-attributes)).
|
||||
For example:
|
||||
These shortcuts can be combined with long-hand attributes; the two values will
|
||||
be merged together as though they were all placed in an array (see [the
|
||||
documentation on `:class` and `:id` attributes](#class-and-id-attributes)). For
|
||||
example:
|
||||
|
||||
%div#Article.article.entry{:id => @article.number, :class => @article.visibility}
|
||||
|
||||
|
|
@ -494,10 +470,8 @@ and could compile to:
|
|||
|
||||
#### Implicit Div Elements
|
||||
|
||||
Because divs are used so often, they're the default elements.
|
||||
If you only define a class and/or id using `.` or `#`,
|
||||
a div is automatically used.
|
||||
For example:
|
||||
Because divs are used so often, they're the default elements. If you only define
|
||||
a class and/or id using `.` or `#`, a div is automatically used. For example:
|
||||
|
||||
#collection
|
||||
.item
|
||||
|
|
@ -519,9 +493,8 @@ and is compiled to:
|
|||
|
||||
### Self-Closing Tags: `/`
|
||||
|
||||
The forward slash character, when placed at the end of a tag definition,
|
||||
causes the tag to be self-closed.
|
||||
For example:
|
||||
The forward slash character, when placed at the end of a tag definition, causes
|
||||
the tag to be self-closed. For example:
|
||||
|
||||
%br/
|
||||
%meta{'http-equiv' => 'Content-Type', :content => 'text/html'}/
|
||||
|
|
@ -531,10 +504,10 @@ is compiled to:
|
|||
<br />
|
||||
<meta http-equiv='Content-Type' content='text/html' />
|
||||
|
||||
Some tags are automatically closed, as long as they have no content.
|
||||
`meta`, `img`, `link`, `script`, `br`, and `hr` tags are closed by default.
|
||||
This list can be customized by setting the [`:autoclose`](#autoclose-option) option.
|
||||
For example:
|
||||
Some tags are automatically closed, as long as they have no content. `meta`,
|
||||
`img`, `link`, `script`, `br`, and `hr` tags are closed by default. This list
|
||||
can be customized by setting the [`:autoclose`](#autoclose-option) option. For
|
||||
example:
|
||||
|
||||
%br
|
||||
%meta{'http-equiv' => 'Content-Type', :content => 'text/html'}
|
||||
|
|
@ -546,16 +519,13 @@ is also compiled to:
|
|||
|
||||
### Whitespace Removal: `>` and `<`
|
||||
|
||||
`>` and `<` give you more control over the whitespace near a tag.
|
||||
`>` will remove all whitespace surrounding a tag,
|
||||
while `<` will remove all whitespace immediately within a tag.
|
||||
You can think of them as alligators eating the whitespace:
|
||||
`>` faces out of the tag and eats the whitespace on the outside,
|
||||
and `<` faces into the tag and eats the whitespace on the inside.
|
||||
They're placed at the end of a tag definition,
|
||||
after class, id, and attribute declarations
|
||||
but before `/` or `=`.
|
||||
For example:
|
||||
`>` and `<` give you more control over the whitespace near a tag. `>` will
|
||||
remove all whitespace surrounding a tag, while `<` will remove all whitespace
|
||||
immediately within a tag. You can think of them as alligators eating the
|
||||
whitespace: `>` faces out of the tag and eats the whitespace on the outside, and
|
||||
`<` faces into the tag and eats the whitespace on the inside. They're placed at
|
||||
the end of a tag definition, after class, id, and attribute declarations but
|
||||
before `/` or `=`. For example:
|
||||
|
||||
%blockquote<
|
||||
%div
|
||||
|
|
@ -601,16 +571,13 @@ is compiled to:
|
|||
|
||||
### Object Reference: `[]`
|
||||
|
||||
Square brackets follow a tag definition and contain a Ruby object
|
||||
that is used to set the class and id of that tag.
|
||||
The class is set to the object's class
|
||||
(transformed to use underlines rather than camel case)
|
||||
and the id is set to the object's class, followed by the value
|
||||
of its `#to_key` or `#id` method (in that order).
|
||||
This is most useful for elements that represent instances of Models.
|
||||
Additionally, the second argument (if present) will be used as a prefix for
|
||||
both the id and class attributes.
|
||||
For example:
|
||||
Square brackets follow a tag definition and contain a Ruby object that is used
|
||||
to set the class and id of that tag. The class is set to the object's class
|
||||
(transformed to use underlines rather than camel case) and the id is set to the
|
||||
object's class, followed by the value of its `#to_key` or `#id` method (in that
|
||||
order). This is most useful for elements that represent instances of Active
|
||||
Model models. Additionally, the second argument (if present) will be used as a
|
||||
prefix for both the id and class attributes. For example:
|
||||
|
||||
# file: app/controllers/users_controller.rb
|
||||
|
||||
|
|
@ -631,8 +598,8 @@ is compiled to:
|
|||
Hello!
|
||||
</div>
|
||||
|
||||
If you require that the class be something other than the underscored
|
||||
object's class, you can implement the `haml_object_ref` method on the object.
|
||||
If you require that the class be something other than the underscored object's
|
||||
class, you can implement the `haml_object_ref` method on the object.
|
||||
|
||||
# file: app/models/crazy_user.rb
|
||||
|
||||
|
|
@ -656,10 +623,8 @@ is compiled to:
|
|||
|
||||
## Doctype: `!!!`
|
||||
|
||||
When describing HTML documents with Haml,
|
||||
you can have a document type or XML prolog generated automatically
|
||||
by including the characters `!!!`.
|
||||
For example:
|
||||
When describing HTML documents with Haml, you can have a document type or XML
|
||||
prolog generated automatically by including the characters `!!!`. For example:
|
||||
|
||||
!!! XML
|
||||
!!!
|
||||
|
|
@ -684,8 +649,8 @@ is compiled to:
|
|||
</body>
|
||||
</html>
|
||||
|
||||
You can also specify the specific doctype after the `!!!`
|
||||
When the [`:format`](#format-option) is set to `:xhtml` (the default except in Rails 3),
|
||||
You can also specify the specific doctype after the `!!!` When the
|
||||
[`:format`](#format-option) is set to `:xhtml` (the default except in Rails 3),
|
||||
the following doctypes are supported:
|
||||
|
||||
`!!!`
|
||||
|
|
@ -720,8 +685,8 @@ the following doctypes are supported:
|
|||
: XHTML+RDFa 1.0<br/>
|
||||
`<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">`
|
||||
|
||||
When the [`:format`](#format-option) option is set to `:html4`,
|
||||
the following doctypes are supported:
|
||||
When the [`:format`](#format-option) option is set to `:html4`, the following
|
||||
doctypes are supported:
|
||||
|
||||
`!!!`
|
||||
: HTML 4.01 Transitional<br/>
|
||||
|
|
@ -738,10 +703,8 @@ the following doctypes are supported:
|
|||
When the [`:format`](#format-option) option is set to `:html5`,
|
||||
`!!!` is always `<!DOCTYPE html>`.
|
||||
|
||||
If you're not using the UTF-8 character set for your document,
|
||||
you can specify which encoding should appear
|
||||
in the XML prolog in a similar way.
|
||||
For example:
|
||||
If you're not using the UTF-8 character set for your document, you can specify
|
||||
which encoding should appear in the XML prolog in a similar way. For example:
|
||||
|
||||
!!! XML iso-8859-1
|
||||
|
||||
|
|
@ -749,21 +712,19 @@ is compiled to:
|
|||
|
||||
<?xml version='1.0' encoding='iso-8859-1' ?>
|
||||
|
||||
If the mime_type of the template being rendered is `text/xml` then
|
||||
a format of `:xhtml` will be used even if the global output format
|
||||
is set to `:html4` or `:html5`.
|
||||
If the mime_type of the template being rendered is `text/xml` then a format of
|
||||
`:xhtml` will be used even if the global output format is set to `:html4` or
|
||||
`:html5`.
|
||||
|
||||
## Comments
|
||||
|
||||
Haml supports two sorts of comments:
|
||||
those that show up in the HTML output
|
||||
and those that don't.
|
||||
Haml supports two sorts of comments: those that show up in the HTML output and
|
||||
those that don't.
|
||||
|
||||
### HTML Comments: `/`
|
||||
|
||||
The forward slash character, when placed at the beginning of a line,
|
||||
wraps all text after it in an HTML comment.
|
||||
For example:
|
||||
The forward slash character, when placed at the beginning of a line, wraps all
|
||||
text after it in an HTML comment. For example:
|
||||
|
||||
%peanutbutterjelly
|
||||
/ This is the peanutbutterjelly element
|
||||
|
|
@ -794,9 +755,9 @@ is compiled to:
|
|||
|
||||
#### Conditional Comments: `/[]`
|
||||
|
||||
You can also use [Internet Explorer conditional comments](http://www.quirksmode.org/css/condcom.html)
|
||||
by enclosing the condition in square brackets after the `/`.
|
||||
For example:
|
||||
You can also use [Internet Explorer conditional
|
||||
comments](http://www.quirksmode.org/css/condcom.html) by enclosing the condition
|
||||
in square brackets after the `/`. For example:
|
||||
|
||||
/[if IE]
|
||||
%a{ :href => 'http://www.mozilla.com/en-US/firefox/' }
|
||||
|
|
@ -812,10 +773,8 @@ is compiled to:
|
|||
|
||||
### Haml Comments: `-#`
|
||||
|
||||
The hyphen followed immediately by the pound sign
|
||||
signifies a silent comment.
|
||||
Any text following this isn't rendered in the resulting document
|
||||
at all.
|
||||
The hyphen followed immediately by the pound sign signifies a silent comment.
|
||||
Any text following this isn't rendered in the resulting document at all.
|
||||
|
||||
For example:
|
||||
|
||||
|
|
@ -828,9 +787,8 @@ is compiled to:
|
|||
<p>foo</p>
|
||||
<p>bar</p>
|
||||
|
||||
You can also nest text beneath a silent comment.
|
||||
None of this text will be rendered.
|
||||
For example:
|
||||
You can also nest text beneath a silent comment. None of this text will be
|
||||
rendered. For example:
|
||||
|
||||
%p foo
|
||||
-#
|
||||
|
|
@ -848,9 +806,8 @@ is compiled to:
|
|||
|
||||
### Inserting Ruby: `=`
|
||||
|
||||
The equals character is followed by Ruby code.
|
||||
This code is evaluated and the output is inserted into the document.
|
||||
For example:
|
||||
The equals character is followed by Ruby code. This code is evaluated and the
|
||||
output is inserted into the document. For example:
|
||||
|
||||
%p
|
||||
= ['hi', 'there', 'reader!'].join " "
|
||||
|
|
@ -863,8 +820,8 @@ is compiled to:
|
|||
yo
|
||||
</p>
|
||||
|
||||
If the [`:escape_html`](#escape_html-option) option is set, `=` will sanitize any
|
||||
HTML-sensitive characters generated by the script. For example:
|
||||
If the [`:escape_html`](#escape_html-option) option is set, `=` will sanitize
|
||||
any HTML-sensitive characters generated by the script. For example:
|
||||
|
||||
= '<script>alert("I\'m evil!");</script>'
|
||||
|
||||
|
|
@ -877,13 +834,12 @@ For example:
|
|||
|
||||
%p= "hello"
|
||||
|
||||
would be compiled to
|
||||
would be compiled to:
|
||||
|
||||
<p>hello</p>
|
||||
|
||||
A line of Ruby code can be stretched over multiple lines
|
||||
as long as each line but the last ends with a comma.
|
||||
For example:
|
||||
A line of Ruby code can be stretched over multiple lines as long as each line
|
||||
but the last ends with a comma. For example:
|
||||
|
||||
= link_to_remote "Add to cart",
|
||||
:url => { :action => "add", :id => product.id },
|
||||
|
|
@ -893,12 +849,11 @@ Note that it's illegal to nest code within a tag that ends with `=`.
|
|||
|
||||
### Running Ruby: `-`
|
||||
|
||||
The hyphen character is also followed by Ruby code.
|
||||
This code is evaluated but *not* inserted into the document.
|
||||
The hyphen character is also followed by Ruby code. This code is evaluated but
|
||||
*not* inserted into the document.
|
||||
|
||||
**It is not recommended that you use this widely;
|
||||
almost all processing code and logic should be restricted
|
||||
to the Controller, the Helper, or partials.**
|
||||
**It is not recommended that you use this widely; almost all processing code and
|
||||
logic should be restricted to Controllers, Helpers, or partials.**
|
||||
|
||||
For example:
|
||||
|
||||
|
|
@ -913,9 +868,8 @@ is compiled to:
|
|||
hello there you!
|
||||
</p>
|
||||
|
||||
A line of Ruby code can be stretched over multiple lines
|
||||
as long as each line but the last ends with a comma.
|
||||
For example:
|
||||
A line of Ruby code can be stretched over multiple lines as long as each line
|
||||
but the last ends with a comma. For example:
|
||||
|
||||
- links = {:home => "/",
|
||||
:docs => "/docs",
|
||||
|
|
@ -924,12 +878,10 @@ For example:
|
|||
#### Ruby Blocks
|
||||
|
||||
Ruby blocks, like XHTML tags, don't need to be explicitly closed in Haml.
|
||||
Rather, they're automatically closed, based on indentation.
|
||||
A block begins whenever the indentation is increased
|
||||
after a Ruby evaluation command.
|
||||
It ends when the indentation decreases
|
||||
(as long as it's not an `else` clause or something similar).
|
||||
For example:
|
||||
Rather, they're automatically closed, based on indentation. A block begins
|
||||
whenever the indentation is increased after a Ruby evaluation command. It ends
|
||||
when the indentation decreases (as long as it's not an `else` clause or
|
||||
something similar). For example:
|
||||
|
||||
- (42...47).each do |i|
|
||||
%p= i
|
||||
|
|
@ -963,8 +915,8 @@ is compiled to:
|
|||
|
||||
### Whitespace Preservation: `~` {#tilde}
|
||||
|
||||
`~` works just like `=`, except that it runs {Haml::Helpers#find\_and\_preserve} on its input.
|
||||
For example,
|
||||
`~` works just like `=`, except that it runs {Haml::Helpers#find\_and\_preserve}
|
||||
on its input. For example,
|
||||
|
||||
~ "Foo\n<pre>Bar\nBaz</pre>"
|
||||
|
||||
|
|
@ -981,9 +933,8 @@ See also [Whitespace Preservation](#whitespace_preservation).
|
|||
|
||||
### Ruby Interpolation: `#{}`
|
||||
|
||||
Ruby code can also be interpolated within plain text using `#{}`,
|
||||
similarly to Ruby string interpolation.
|
||||
For example,
|
||||
Ruby code can also be interpolated within plain text using `#{}`, similarly to
|
||||
Ruby string interpolation. For example,
|
||||
|
||||
%p This is #{h quality} cake!
|
||||
|
||||
|
|
@ -991,34 +942,32 @@ is the same as
|
|||
|
||||
%p= "This is the #{h quality} cake!"
|
||||
|
||||
and might compile to
|
||||
and might compile to:
|
||||
|
||||
<p>This is scrumptious cake!</p>
|
||||
|
||||
Backslashes can be used to escape `#{}` strings,
|
||||
but they don't act as escapes anywhere else in the string.
|
||||
For example:
|
||||
Backslashes can be used to escape `#{}` strings, but they don't act as escapes
|
||||
anywhere else in the string. For example:
|
||||
|
||||
%p
|
||||
Look at \\#{h word} lack of backslash: \#{foo}
|
||||
And yon presence thereof: \{foo}
|
||||
|
||||
might compile to
|
||||
might compile to:
|
||||
|
||||
<p>
|
||||
Look at \yon lack of backslash: #{foo}
|
||||
And yon presence thereof: \{foo}
|
||||
</p>
|
||||
|
||||
Interpolation can also be used within [filters](#filters).
|
||||
For example:
|
||||
Interpolation can also be used within [filters](#filters). For example:
|
||||
|
||||
:javascript
|
||||
$(document).ready(function() {
|
||||
alert(#{@message.to_json});
|
||||
});
|
||||
|
||||
might compile to
|
||||
might compile to:
|
||||
|
||||
<script type='text/javascript'>
|
||||
//< option is set,
|
||||
`&=` behaves identically to `=`.
|
||||
If the {Haml::Options#escape_html `:escape_html`} option is set, `&=` behaves
|
||||
identically to `=`.
|
||||
|
||||
`&` can also be used on its own so that `#{}` interpolation is escaped.
|
||||
For example,
|
||||
`&` can also be used on its own so that `#{}` interpolation is escaped. For
|
||||
example,
|
||||
|
||||
& I like #{"cheese & crackers"}
|
||||
|
||||
compiles to
|
||||
compiles to:
|
||||
|
||||
I like cheese & crackers
|
||||
|
||||
### Unescaping HTML: `!=` {#unescaping_html}
|
||||
|
||||
An exclamation mark followed by one or two equals characters
|
||||
evaluates Ruby code just like the equals would,
|
||||
but never sanitizes the HTML.
|
||||
An exclamation mark followed by one or two equals characters evaluates Ruby code
|
||||
just like the equals would, but never sanitizes the HTML.
|
||||
|
||||
By default, the single equals doesn't sanitize HTML either.
|
||||
However, if the [`:escape_html`](#escape_html-option) option is set,
|
||||
`=` will sanitize the HTML, but `!=` still won't.
|
||||
For example, if `:escape_html` is set:
|
||||
By default, the single equals doesn't sanitize HTML either. However, if the
|
||||
{Haml::Options#escape_html `:escape_html`} option is set, `=` will sanitize the
|
||||
HTML, but `!=` still won't. For example, if `:escape_html` is set:
|
||||
|
||||
= "I feel <strong>!"
|
||||
!= "I feel <strong>!"
|
||||
|
|
@ -1086,7 +1032,7 @@ compiles to
|
|||
The colon character designates a filter. This allows you to pass an indented
|
||||
block of text as input to another filtering program and add the result to the
|
||||
output of Haml. The syntax is simply a colon followed by the name of the filter.
|
||||
For example,
|
||||
For example:
|
||||
|
||||
%p
|
||||
:markdown
|
||||
|
|
@ -1094,7 +1040,7 @@ For example,
|
|||
|
||||
Hello, *World*
|
||||
|
||||
is compiled to
|
||||
is compiled to:
|
||||
|
||||
<p>
|
||||
<h1>Greetings</h1>
|
||||
|
|
@ -1102,7 +1048,7 @@ is compiled to
|
|||
<p>Hello, <em>World</em></p>
|
||||
</p>
|
||||
|
||||
Filters can have Ruby code interpolated with `#{}`. For example,
|
||||
Filters can have Ruby code interpolated with `#{}`. For example:
|
||||
|
||||
- flavor = "raspberry"
|
||||
#content
|
||||
|
|
@ -1115,16 +1061,16 @@ is compiled to
|
|||
<p>I <strong>really</strong> prefer <em>raspberry</em> jam.</p>
|
||||
</div>
|
||||
|
||||
Currently, filters ignore the [`:escape_html`](#escape_html-option) option. This
|
||||
means that `#{}` interpolation within filters is never HTML-escaped.
|
||||
Currently, filters ignore the {Haml::Options#escape_html `:escape_html`} option.
|
||||
This means that `#{}` interpolation within filters is never HTML-escaped.
|
||||
|
||||
The functionality of some filters such as Markdown can be provided by many
|
||||
different libraries. Usually you don't have to worry about this - you can just
|
||||
load the gem of your choice and Haml will automatically use it.
|
||||
|
||||
However in some cases you may want to make Haml explicitly use a specific gem
|
||||
to be used by a filter. In these cases you can do this via Tilt, the library
|
||||
Haml uses to implement many filters:
|
||||
However in some cases you may want to make Haml explicitly use a specific gem to
|
||||
be used by a filter. In these cases you can do this via Tilt, the library Haml
|
||||
uses to implement many of its filters:
|
||||
|
||||
Tilt.prefer Tilt::RedCarpetTemplate
|
||||
|
||||
|
|
|
|||
|
|
@ -228,7 +228,7 @@ module Haml
|
|||
end
|
||||
end
|
||||
|
||||
# Returns a subset of \{#options}: those that {Haml::Buffer} cares about.
|
||||
# Returns a subset of options: those that {Haml::Buffer} cares about.
|
||||
# All of the values here are such that when `#inspect` is called on the hash,
|
||||
# it can be `Kernel#eval`ed to get the same result back.
|
||||
#
|
||||
|
|
|
|||
Loading…
Reference in New Issue