mirror of
https://github.com/haml/haml.git
synced 2022-11-09 12:33:31 -05:00
Update references that may be obsolete
Sorry, I don't have bandwidth to make this perfect immediately. If you want to resurrect some contents, please file a pull request. However, removing Haml helpers was intentional in Haml 6. Mentions of helpers are not supposed to be resurrected.
This commit is contained in:
Takashi Kokubun
parent
481ee299c3
commit
83ccbeeeb5
1 changed files with 4 additions and 161 deletions
165
REFERENCE.md
165
REFERENCE.md
|
|
@ -30,7 +30,7 @@ The first step for all of these is to install the Haml gem:
|
|||
|
||||
To run Haml from the command line, just use
|
||||
|
||||
haml input.haml output.html
|
||||
haml render input.haml > output.html
|
||||
|
||||
Use `haml --help` for full documentation.
|
||||
|
||||
|
|
@ -68,24 +68,6 @@ may be compiled to:
|
|||
</div>
|
||||
</div>
|
||||
|
||||
### 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
|
||||
{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.
|
||||
|
||||
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
|
||||
|
|
@ -96,59 +78,9 @@ this, install the gem with RubyGems:
|
|||
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 = Haml::Template.new { "%p Haml code!" }
|
||||
engine.render #=> "<p>Haml code!</p>\n"
|
||||
|
||||
### Options
|
||||
|
||||
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:
|
||||
|
||||
```ruby
|
||||
# config/initializers/haml.rb
|
||||
Haml::Template.options[:format] = :html5
|
||||
|
||||
# Avoid escaping attributes which are already escaped
|
||||
Haml::Template.options[:escape_attrs] = :once
|
||||
```
|
||||
|
||||
Outside Rails, you can set them by configuring them globally in
|
||||
Haml::Options.defaults:
|
||||
|
||||
```ruby
|
||||
Haml::Options.defaults[:format] = :html5
|
||||
```
|
||||
|
||||
In sinatra specifically, you can set them in global config with:
|
||||
```ruby
|
||||
set :haml, { escape_html: true }
|
||||
```
|
||||
|
||||
Finally, you can also set them by passing an options hash to
|
||||
{Haml::Engine#initialize}. For the complete list of available options, please
|
||||
see {Haml::Options}.
|
||||
|
||||
### Encodings
|
||||
|
||||
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 {Haml::Options#encoding `: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.
|
||||
|
||||
## Plain Text
|
||||
|
||||
A substantial portion of any HTML document is its content, which is plain old
|
||||
|
|
@ -325,49 +257,6 @@ 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.
|
||||
For example, {Haml::Helpers} defines the following method:
|
||||
|
||||
def html_attrs(lang = 'en-US')
|
||||
{:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
|
||||
end
|
||||
|
||||
This can then be used in Haml, like so:
|
||||
|
||||
%html{html_attrs('fr-fr')}
|
||||
|
||||
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 be merged together, from
|
||||
left to right. For example, if you defined
|
||||
|
||||
def hash1
|
||||
{:bread => 'white', :filling => 'peanut butter and jelly'}
|
||||
end
|
||||
|
||||
def hash2
|
||||
{:bread => 'whole wheat'}
|
||||
end
|
||||
|
||||
then
|
||||
|
||||
%sandwich{hash1, hash2, :delicious => 'true'}/
|
||||
|
||||
would compile to:
|
||||
|
||||
<sandwich bread='whole wheat' delicious='true' filling='peanut butter and jelly' />
|
||||
|
||||
Note that the Haml attributes list has the same syntax as a Ruby method call.
|
||||
This means that any attribute methods must come before the hash literal.
|
||||
|
||||
Attribute methods aren't supported for HTML-style attributes.
|
||||
|
||||
#### Boolean Attributes
|
||||
|
||||
Some attributes, such as "checked" for `input` tags or "selected" for `option`
|
||||
|
|
@ -993,7 +882,7 @@ is compiled to:
|
|||
|
||||
### Whitespace Preservation: `~` {#tilde}
|
||||
|
||||
`~` works just like `=`, except that it runs {Haml::Helpers#find\_and\_preserve}
|
||||
`~` works just like `=`, except that it runs {Haml::Helpers.preserve}
|
||||
on its input. For example,
|
||||
|
||||
~ "Foo\n<pre>Bar\nBaz</pre>"
|
||||
|
|
@ -1154,9 +1043,6 @@ is compiled to
|
|||
<p>I <strong>really</strong> prefer <em>raspberry</em> jam.</p>
|
||||
</div>
|
||||
|
||||
Note that `#{}` interpolation within filters is HTML-escaped if you specify true to
|
||||
{Haml::Options#escape_filter_interpolations `:escape_filter_interpolations`} option.
|
||||
|
||||
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.
|
||||
|
|
@ -1273,42 +1159,6 @@ default. This filter is implemented using Tilt.
|
|||
|
||||
You can also define your own filters. See {Haml::Filters} for details.
|
||||
|
||||
## Helper Methods {#helper-methods}
|
||||
|
||||
Sometimes you need to manipulate whitespace in a more precise fashion than what
|
||||
the whitespace removal methods allow. There are a few helper methods that are
|
||||
useful when dealing with inline content. All these methods take a Haml block to
|
||||
modify.
|
||||
|
||||
### surround {#surround}
|
||||
|
||||
Surrounds a Haml block with text. Expects 1 or 2 string arguments used to
|
||||
surround the Haml block. If a second argument is not provided, the first
|
||||
argument is used as the second.
|
||||
|
||||
= surround "(", ")" do
|
||||
= link_to "learn more", "#"
|
||||
|
||||
### precede {#precede}
|
||||
|
||||
Prepends a Haml block with text. Expects 1 argument.
|
||||
|
||||
= precede "*" do
|
||||
%span Required
|
||||
|
||||
### succeed {#succeed}
|
||||
|
||||
Appends a Haml block with text. Expects 1 argument.
|
||||
|
||||
Begin by
|
||||
= succeed "," do
|
||||
= link_to "filling out your profile", "#"
|
||||
= succeed "," do
|
||||
= link_to "adding a bio", "#"
|
||||
and
|
||||
= succeed "." do
|
||||
= link_to "inviting friends", "#"
|
||||
|
||||
## Multiline: `|` {#multiline}
|
||||
|
||||
The pipe character designates a multiline string.
|
||||
|
|
@ -1367,14 +1217,7 @@ Haml won't try to re-format the indentation.
|
|||
Literal `textarea` and `pre` tags automatically preserve content given through
|
||||
`=`. Dynamically-generated `textarea`s and `pre`s can't be preserved
|
||||
automatically, and so should be passed through
|
||||
{Haml::Helpers#find\_and\_preserve} or the [`~` command](#tilde), which has the
|
||||
{Haml::Helpers.preserve} or the [`~` command](#tilde), which has the
|
||||
same effect.
|
||||
|
||||
Blocks of literal text can be preserved using the [`:preserve` filter](#preserve-filter).
|
||||
|
||||
## Helpers
|
||||
|
||||
Haml offers a bunch of helpers that are useful for doing stuff like preserving
|
||||
whitespace, creating nicely indented output for user-defined helpers, and other
|
||||
useful things. The helpers are all documented in the {Haml::Helpers} and
|
||||
{Haml::Helpers::ActionViewExtensions} modules.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue