1036 lines
28 KiB
Ruby
1036 lines
28 KiB
Ruby
dir = File.dirname(__FILE__)
|
|
$LOAD_PATH << dir unless $LOAD_PATH.include?(dir)
|
|
|
|
# = 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.
|
|
#
|
|
# == Features
|
|
#
|
|
# * Whitespace active
|
|
# * Well-formatted markup
|
|
# * DRY
|
|
# * Follows CSS conventions
|
|
# * Integrates Ruby code
|
|
# * Implements Rails templates with the .haml extension
|
|
#
|
|
# == Using Haml
|
|
#
|
|
# Haml can be used in two ways:
|
|
# as a plugin for Ruby on Rails,
|
|
# and as a standalone Ruby module.
|
|
#
|
|
# Sass can be used in several ways:
|
|
# As a template engine for Ruby on Rails or Merb,
|
|
# or as a standalone engine.
|
|
# The first step for all of these is to install the Haml gem:
|
|
#
|
|
# gem install haml
|
|
#
|
|
# To enable it as a Rails plugin,
|
|
# then run
|
|
#
|
|
# haml --rails path/to/rails/app
|
|
#
|
|
# Haml is enabled in Merb by default,
|
|
# so Merb users don't have to do anything more.
|
|
#
|
|
# Once it's installed, all view files with the ".haml" extension
|
|
# (or ".html.haml" for Merb or edge Rails)
|
|
# 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 (this example uses Rails, but the principle for Merb is the same):
|
|
#
|
|
# # file: app/controllers/movies_controller.rb
|
|
#
|
|
# class MoviesController < ApplicationController
|
|
# def index
|
|
# @title = "Teen Wolf"
|
|
# end
|
|
# end
|
|
#
|
|
# -# file: app/views/movies/index.haml
|
|
#
|
|
# #content
|
|
# .title
|
|
# %h1= @title
|
|
# = link_to 'Home', home_url
|
|
#
|
|
# may be compiled to:
|
|
#
|
|
# <div id='content'>
|
|
# <div class='title'>
|
|
# <h1>Teen Wolf</h1>
|
|
# <a href='/'>Home</a>
|
|
# </div>
|
|
# </div>
|
|
#
|
|
# === Ruby Module
|
|
#
|
|
# 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:
|
|
#
|
|
# engine = Haml::Engine.new("%p Haml code!")
|
|
# engine.render #=> "<p>Haml code!</p>\n"
|
|
#
|
|
# == Characters with meaning to Haml
|
|
#
|
|
# Various characters, when placed at a certain point in a line,
|
|
# instruct Haml to render different types of things.
|
|
#
|
|
# === XHTML Tags
|
|
#
|
|
# These characters render XHTML tags.
|
|
#
|
|
# ==== %
|
|
#
|
|
#
|
|
# 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 <tt><element></element></tt>.
|
|
# For example:
|
|
#
|
|
# %one
|
|
# %two
|
|
# %three Hey there
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <one>
|
|
# <two>
|
|
# <three>Hey there</three>
|
|
# </two>
|
|
# </one>
|
|
#
|
|
# Any string is a valid element name;
|
|
# Haml will automatically generate opening and closing tags for any element.
|
|
#
|
|
# ==== {}
|
|
#
|
|
# 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:
|
|
#
|
|
# %head{ :name => "doc_head" }
|
|
# %script{ 'type' => "text/" + "javascript",
|
|
# :src => "javascripts/script_#{2 + 7}" }
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <head name="doc_head">
|
|
# <script src='javascripts/script_9' type='text/javascript'>
|
|
# </script>
|
|
# </head>
|
|
#
|
|
# ===== 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 me 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' />
|
|
#
|
|
# ===== Boolean Attributes
|
|
#
|
|
# Some attributes, such as "checked" for <tt>input</tt> tags or "selected" for <tt>option</tt> 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, 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
|
|
#
|
|
# <input selected="selected">
|
|
#
|
|
# 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
|
|
#
|
|
# <input>
|
|
#
|
|
# ==== []
|
|
#
|
|
# 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 its id.
|
|
# Because the id of an object is normally an obscure implementation detail,
|
|
# 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:
|
|
#
|
|
# # file: app/controllers/users_controller.rb
|
|
#
|
|
# def show
|
|
# @user = CrazyUser.find(15)
|
|
# end
|
|
#
|
|
# -# file: app/views/users/show.haml
|
|
#
|
|
# %div[@user, :greeting]
|
|
# %bar[290]/
|
|
# Hello!
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <div class="greeting_crazy_user" id="greeting_crazy_user_15">
|
|
# <bar class="fixnum" id="fixnum_581" />
|
|
# Hello!
|
|
# </div>
|
|
#
|
|
# ==== /
|
|
#
|
|
# 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'}/
|
|
#
|
|
# 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 <tt>:autoclose</tt> option (see below).
|
|
# For example:
|
|
#
|
|
# %br
|
|
# %meta{'http-equiv' => 'Content-Type', :content => 'text/html'}
|
|
#
|
|
# is also compiled to:
|
|
#
|
|
# <br />
|
|
# <meta http-equiv='Content-Type' content='text/html' />
|
|
#
|
|
# ==== . and #
|
|
#
|
|
# The period and pound sign are borrowed from CSS.
|
|
# They are used as shortcuts to specify the <tt>class</tt>
|
|
# and <tt>id</tt> 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
|
|
# %p.beans{ :food => 'true' } The magical fruit
|
|
# %h1.class.otherclass#id La La La
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <div id='things'>
|
|
# <span id='rice'>Chicken Fried</span>
|
|
# <p class='beans' food='true'>The magical fruit</p>
|
|
# <h1 class='class otherclass' id='id'>La La La</h1>
|
|
# </div>
|
|
#
|
|
# And,
|
|
#
|
|
# #content
|
|
# .articles
|
|
# .article.title
|
|
# Doogie Howser Comes Out
|
|
# .article.date
|
|
# 2006-11-05
|
|
# .article.entry
|
|
# Neil Patrick Harris would like to dispel any rumors that he is straight
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <div id="content">
|
|
# <div class="articles">
|
|
# <div class="article title">Doogie Howser Comes Out</div>
|
|
# <div class="article date">2006-11-05</div>
|
|
# <div class="article entry">
|
|
# Neil Patrick Harris would like to dispel any rumors that he is straight
|
|
# </div>
|
|
# </div>
|
|
# </div>
|
|
#
|
|
# ==== Implicit Div Elements
|
|
#
|
|
# Because the div element is used so often, it is the default element.
|
|
# If you only define a class and/or id using the <tt>.</tt> or <tt>#</tt> syntax,
|
|
# a div element is automatically used.
|
|
# For example:
|
|
#
|
|
# #collection
|
|
# .item
|
|
# .description What a cool item!
|
|
#
|
|
# is the same as:
|
|
#
|
|
# %div{:id => collection}
|
|
# %div{:class => 'item'}
|
|
# %div{:class => 'description'} What a cool item!
|
|
#
|
|
# and is compiled to:
|
|
#
|
|
# <div id='collection'>
|
|
# <div class='item'>
|
|
# <div class='description'>What a cool item!</div>
|
|
# </div>
|
|
# </div>
|
|
#
|
|
# ==== > and <
|
|
#
|
|
# <tt>></tt> and <tt><</tt> give you more control over the whitespace near a tag.
|
|
# <tt>></tt> will remove all whitespace surrounding a tag,
|
|
# while <tt><</tt> will remove all whitespace immediately within a tag.
|
|
# You can think of them as alligators eating the whitespace:
|
|
# <tt>></tt> faces out of the tag and eats the whitespace on the outside,
|
|
# and <tt><</tt> 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 <tt>/</tt> or <tt>=</tt>.
|
|
# For example:
|
|
#
|
|
# %blockquote<
|
|
# %div
|
|
# Foo!
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <blockquote><div>
|
|
# Foo!
|
|
# </div></blockquote>
|
|
#
|
|
# And:
|
|
#
|
|
# %img
|
|
# %img>
|
|
# %img
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <img /><img /><img />
|
|
#
|
|
# And:
|
|
#
|
|
# %p<= "Foo\nBar"
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <p>Foo
|
|
# Bar</p>
|
|
#
|
|
# And finally:
|
|
#
|
|
# %img
|
|
# %pre><
|
|
# foo
|
|
# bar
|
|
# %img
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <img /><pre>foo
|
|
# bar</pre><img />
|
|
#
|
|
# ==== =
|
|
#
|
|
# <tt>=</tt> is placed at the end of a tag definition,
|
|
# after class, id, and attribute declarations.
|
|
# It's just a shortcut for inserting Ruby code into an element.
|
|
# It works the same as <tt>=</tt> without a tag:
|
|
# it inserts the result of the Ruby code into the template.
|
|
# However, if the result is short enough,
|
|
# it is displayed entirely on one line.
|
|
# For example:
|
|
#
|
|
# %p= "hello"
|
|
#
|
|
# is not quite the same as:
|
|
#
|
|
# %p
|
|
# = "hello"
|
|
#
|
|
# It's compiled to:
|
|
#
|
|
# <p>hello</p>
|
|
#
|
|
# ==== ~
|
|
#
|
|
# ~ works just like =, except that it runs Haml::Helpers#find_and_preserve on its input.
|
|
# For example,
|
|
#
|
|
# ~ "Foo\n<pre>Bar\nBaz</pre>"
|
|
#
|
|
# is the same as:
|
|
#
|
|
# = find_and_preserve("Foo\n<pre>Bar\nBaz</pre>")
|
|
#
|
|
# and is compiled to:
|
|
#
|
|
# Foo
|
|
# <pre>Bar
Baz</pre>
|
|
#
|
|
# See also Whitespace Preservation, below.
|
|
#
|
|
# === XHTML Helpers
|
|
#
|
|
# ==== No Special Character
|
|
#
|
|
# If no special character appears at the beginning of a line,
|
|
# the line is rendered as plain text.
|
|
# For example:
|
|
#
|
|
# %gee
|
|
# %whiz
|
|
# Wow this is cool!
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <gee>
|
|
# <whiz>
|
|
# Wow this is cool!
|
|
# </whiz>
|
|
# </gee>
|
|
#
|
|
# ==== !!!
|
|
#
|
|
# When describing XHTML documents with Haml,
|
|
# you can have a document type or XML prolog generated automatically
|
|
# by including the characters <tt>!!!</tt>.
|
|
# For example:
|
|
#
|
|
# !!! XML
|
|
# !!!
|
|
# %html
|
|
# %head
|
|
# %title Myspace
|
|
# %body
|
|
# %h1 I am the international space station
|
|
# %p Sign my guestbook
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <?xml version="1.0" encoding="utf-8" ?>
|
|
# <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
# <html>
|
|
# <head>
|
|
# <title>Myspace</title>
|
|
# </head>
|
|
# <body>
|
|
# <h1>I am the international space station</h1>
|
|
# <p>Sign my guestbook</p>
|
|
# </body>
|
|
# </html>
|
|
#
|
|
# You can also specify the version and type of XHTML after the <tt>!!!</tt>.
|
|
# XHTML 1.0 Strict, Transitional, and Frameset and XHTML 1.1 are supported.
|
|
# The default version is 1.0 and the default type is Transitional.
|
|
# For example:
|
|
#
|
|
# !!! 1.1
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
|
#
|
|
# and
|
|
#
|
|
# !!! Strict
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
#
|
|
# 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
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <?xml version="1.0" encoding="iso-8859-1" ?>
|
|
#
|
|
# ==== /
|
|
#
|
|
# 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
|
|
# I like sandwiches!
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <peanutbutterjelly>
|
|
# <!-- This is the peanutbutterjelly element -->
|
|
# I like sandwiches!
|
|
# </peanutbutterjelly>
|
|
#
|
|
# The forward slash can also wrap indented sections of code. For example:
|
|
#
|
|
# /
|
|
# %p This doesn't render...
|
|
# %div
|
|
# %h1 Because it's commented out!
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <!--
|
|
# <p>This doesn't render...</p>
|
|
# <div>
|
|
# <h1>Because it's commented out!</h1>
|
|
# </div>
|
|
# -->
|
|
#
|
|
# You can also use Internet Explorer conditional comments
|
|
# (about)[http://www.quirksmode.org/css/condcom.html]
|
|
# by enclosing the condition in square brackets after the <tt>/</tt>.
|
|
# For example:
|
|
#
|
|
# /[if IE]
|
|
# %a{ :href => 'http://www.mozilla.com/en-US/firefox/' }
|
|
# %h1 Get Firefox
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <!--[if IE]>
|
|
# <a href='http://www.mozilla.com/en-US/firefox/'>
|
|
# <h1>Get Firefox</h1>
|
|
# </a>
|
|
# <![endif]-->
|
|
#
|
|
# ==== \
|
|
#
|
|
# The backslash character escapes the first character of a line,
|
|
# allowing use of otherwise interpreted characters as plain text.
|
|
# For example:
|
|
#
|
|
# %title
|
|
# = @title
|
|
# \- MySite
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <title>
|
|
# MyPage
|
|
# - MySite
|
|
# </title>
|
|
#
|
|
# ==== |
|
|
#
|
|
# The pipe character designates a multiline string.
|
|
# It's placed at the end of a line
|
|
# and means that all following lines that end with <tt>|</tt>
|
|
# will be evaluated as though they were on the same line.
|
|
# For example:
|
|
#
|
|
# %whoo
|
|
# %hoo I think this might get |
|
|
# pretty long so I should |
|
|
# probably make it |
|
|
# multiline so it doesn't |
|
|
# look awful. |
|
|
# %p This is short.
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <whoo>
|
|
# <hoo>
|
|
# I think this might get pretty long so I should probably make it multiline so it doesn't look awful.
|
|
# </hoo>
|
|
# </whoo>
|
|
#
|
|
# ==== :
|
|
#
|
|
# 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,
|
|
#
|
|
# %p
|
|
# :markdown
|
|
# Textile
|
|
# =======
|
|
#
|
|
# Hello, *World*
|
|
#
|
|
# is compiled to
|
|
#
|
|
# <p>
|
|
# <h1>Textile</h1>
|
|
#
|
|
# <p>Hello, <em>World</em></p>
|
|
# </p>
|
|
#
|
|
# Filters can have Ruby code interpolated, like with ==.
|
|
# For example,
|
|
#
|
|
# - flavor = "raspberry"
|
|
# #content
|
|
# :textile
|
|
# I *really* prefer _#{h flavor}_ jam.
|
|
#
|
|
# is compiled to
|
|
#
|
|
# <div id='content'>
|
|
# <p>I <strong>really</strong> prefer <em>raspberry</em> jam.</p>
|
|
# </div>
|
|
#
|
|
# Haml has the following filters defined:
|
|
#
|
|
# [plain] Does not parse the filtered text.
|
|
# This is useful for large blocks of text without HTML tags,
|
|
# when you don't want lines starting with <tt>.</tt> or <tt>-</tt>
|
|
# to be parsed.
|
|
#
|
|
# [javascript] Surrounds the filtered text with <script> and CDATA tags.
|
|
# Useful for including inline Javascript.
|
|
#
|
|
# [escaped] Works the same as plain, but HTML-escapes the text
|
|
# before placing it in the document.
|
|
#
|
|
# [ruby] Parses the filtered text with the normal Ruby interpreter.
|
|
# All output sent to <tt>$stdout</tt>, like with +puts+,
|
|
# is output into the Haml document.
|
|
# Not available if the <tt>suppress_eval</tt> option is set to true.
|
|
# The Ruby code is evaluated in the same context as the Haml template.
|
|
#
|
|
# [preserve] Inserts the filtered text into the template with whitespace preserved.
|
|
# <tt>preserve</tt>d blocks of text aren't indented,
|
|
# and newlines are replaced with the HTML escape code for newlines,
|
|
# to preserve nice-looking output.
|
|
# See also Whitespace Preservation, below.
|
|
#
|
|
# [erb] Parses the filtered text with ERB, like an RHTML template.
|
|
# Not available if the <tt>suppress_eval</tt> option is set to true.
|
|
# Embedded Ruby code is evaluated in the same context as the Haml template.
|
|
#
|
|
# [sass] Parses the filtered text with Sass to produce CSS output.
|
|
#
|
|
# [redcloth] Parses the filtered text with RedCloth (http://whytheluckystiff.net/ruby/redcloth),
|
|
# which uses both Textile and Markdown syntax.
|
|
# Only works if RedCloth is installed.
|
|
#
|
|
# [textile] Parses the filtered text with Textile (http://www.textism.com/tools/textile).
|
|
# Only works if RedCloth is installed.
|
|
#
|
|
# [markdown] Parses the filtered text with Markdown (http://daringfireball.net/projects/markdown).
|
|
# Only works if RedCloth or BlueCloth (http://www.deveiate.org/projects/BlueCloth)
|
|
# is installed
|
|
# (BlueCloth takes precedence if both are installed).
|
|
#
|
|
# You can also define your own filters (see Setting Options, below).
|
|
#
|
|
# === Ruby evaluators
|
|
#
|
|
# ==== =
|
|
#
|
|
# The equals character is followed by Ruby code,
|
|
# which is evaluated and the output inserted into the document as plain text.
|
|
# For example:
|
|
#
|
|
# %p
|
|
# = ['hi', 'there', 'reader!'].join " "
|
|
# = "yo"
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <p>
|
|
# hi there reader!
|
|
# yo
|
|
# </p>
|
|
#
|
|
# If the <tt>:escape_html</tt> option is set, <tt>=</tt> will sanitize any
|
|
# HTML-sensitive characters generated by the script. For example:
|
|
#
|
|
# = '<script>alert("I\'m evil!");</script>'
|
|
#
|
|
# would be compiled to
|
|
#
|
|
# <script>alert("I'm evil!");</script>
|
|
#
|
|
# ==== -
|
|
#
|
|
# The hyphen character makes the text following it into "silent script":
|
|
# Ruby script that is evaluated, but not output.
|
|
#
|
|
# <b>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.</b>
|
|
#
|
|
# For example:
|
|
#
|
|
# - foo = "hello"
|
|
# - foo << " there"
|
|
# - foo << " you!"
|
|
# %p= foo
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <p>
|
|
# hello there you!
|
|
# </p>
|
|
#
|
|
# ==== ==
|
|
#
|
|
# Two equals characters interpolates Ruby code into plain text,
|
|
# similarly to Ruby string interpolation.
|
|
# For example,
|
|
#
|
|
# %p== This is #{h quality} cake!
|
|
#
|
|
# is the same as
|
|
#
|
|
# %p= "This is #{h quality} cake!"
|
|
#
|
|
# 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:
|
|
#
|
|
# %p
|
|
# == \\ Look at \\#{h word} lack of backslash: \#{foo}
|
|
#
|
|
# might compile to
|
|
#
|
|
# <p>
|
|
# \\ Look at \yon lack of backslash: #{foo}
|
|
# </p>
|
|
#
|
|
# ==== &=
|
|
#
|
|
# An ampersand followed by one or two equals characters
|
|
# evaluates Ruby code just like the equals without the ampersand,
|
|
# but sanitizes any HTML-sensitive characters in the result of the code.
|
|
# For example:
|
|
#
|
|
# &= "I like cheese & crackers"
|
|
#
|
|
# compiles to
|
|
#
|
|
# I like cheese & crackers
|
|
#
|
|
# If the <tt>:escape_html</tt> option is set,
|
|
# &= behaves identically to =.
|
|
#
|
|
# ==== !=
|
|
#
|
|
# 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 <tt>:escape_html</tt> option is set, = will sanitize the HTML, but != still won't.
|
|
# For example, if <tt>:escape_html</tt> is set:
|
|
#
|
|
# = "I feel <strong>!"
|
|
# != "I feel <strong>!"
|
|
#
|
|
# compiles to
|
|
#
|
|
# I feel <strong>!
|
|
# I feel <strong>!
|
|
#
|
|
# ===== 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 silent script 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
|
|
# %p See, I can count!
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <p>
|
|
# 42
|
|
# </p>
|
|
# <p>
|
|
# 43
|
|
# </p>
|
|
# <p>
|
|
# 44
|
|
# </p>
|
|
# <p>
|
|
# 45
|
|
# </p>
|
|
# <p>
|
|
# 46
|
|
# </p>
|
|
#
|
|
# Another example:
|
|
#
|
|
# %p
|
|
# - case 2
|
|
# - when 1
|
|
# = "1!"
|
|
# - when 2
|
|
# = "2?"
|
|
# - when 3
|
|
# = "3."
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <p>
|
|
# 2?
|
|
# </p>
|
|
#
|
|
# ==== -#
|
|
#
|
|
# 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:
|
|
#
|
|
# %p foo
|
|
# -# This is a comment
|
|
# %p bar
|
|
#
|
|
# 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:
|
|
#
|
|
# %p foo
|
|
# -#
|
|
# This won't be displayed
|
|
# Nor will this
|
|
# %p bar
|
|
#
|
|
# is compiled to:
|
|
#
|
|
# <p>foo</p>
|
|
# <p>bar</p>
|
|
#
|
|
# == Other Useful Things
|
|
#
|
|
# === Whitespace Preservation
|
|
#
|
|
# Sometimes you don't want Haml to indent all your text.
|
|
# For example, tags like +pre+ and +textarea+ are whitespace-sensitive;
|
|
# indenting the text makes them render wrong.
|
|
#
|
|
# Haml deals with this by "preserving" newlines before they're put into the document --
|
|
# converting them to the XHTML whitespace escape code, <tt>
</tt>.
|
|
# Then Haml won't try to re-format the indentation.
|
|
#
|
|
# Literal +textarea+ and +pre+ tags automatically preserve their content.
|
|
# Dynamically can't be caught automatically,
|
|
# and so should be passed through Haml::Helpers#find_and_preserve or the <tt>~</tt> command,
|
|
# which has the same effect (see above).
|
|
#
|
|
# Blocks of literal text can be preserved using the :preserve filter (see above).
|
|
#
|
|
# === 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.
|
|
#
|
|
# === Haml Options
|
|
#
|
|
# Options can be set by setting the hash <tt>Haml::Template.options</tt>
|
|
# from <tt>environment.rb</tt> in Rails,
|
|
# or by passing an options hash to Haml::Engine.
|
|
# Available options are:
|
|
#
|
|
# [<tt>:output</tt>] Determines the output format. The default is :xhtml.
|
|
# Other options are :html4 and :html5, which are
|
|
# identical to :xhtml except there are no self-closing tags,
|
|
# XML prolog is ignored and correct DOCTYPEs are generated.
|
|
#
|
|
# [<tt>:escape_html</tt>] Sets whether or not to escape HTML-sensitive characters in script.
|
|
# If this is true, = behaves like &=;
|
|
# otherwise, it behaves like !=.
|
|
# <b>Note that this escapes tag attributes.</b>
|
|
# Defaults to false.
|
|
#
|
|
# [<tt>:suppress_eval</tt>] Whether or not attribute hashes and Ruby scripts
|
|
# designated by <tt>=</tt> or <tt>~</tt> should be
|
|
# evaluated. If this is true, said scripts are
|
|
# rendered as empty strings. Defaults to false.
|
|
#
|
|
# [<tt>:attr_wrapper</tt>] The character that should wrap element attributes.
|
|
# This defaults to <tt>'</tt> (an apostrophe). Characters
|
|
# of this type within the attributes will be escaped
|
|
# (e.g. by replacing them with <tt>'</tt>) if
|
|
# the character is an apostrophe or a quotation mark.
|
|
#
|
|
# [<tt>:filename</tt>] The name of the Haml file being parsed.
|
|
# This is only used as information when exceptions are raised.
|
|
# This is automatically assigned when working through ActionView,
|
|
# so it's really only useful for the user to assign
|
|
# when dealing with Haml programatically.
|
|
#
|
|
# [<tt>:line</tt>] The line offset of the Haml template being parsed.
|
|
# This is useful for inline templates,
|
|
# similar to the last argument to Kernel#eval.
|
|
#
|
|
# [<tt>:filters</tt>] A hash of filters that can be applied to Haml code.
|
|
# The keys are the string names of the filters;
|
|
# the values are references to the classes of the filters.
|
|
# User-defined filters should always have lowercase keys,
|
|
# and should have the interface described in Haml::Filters::Base.
|
|
#
|
|
# [<tt>:autoclose</tt>] A list of tag names that should be automatically self-closed
|
|
# if they have no content.
|
|
# Defaults to <tt>['meta', 'img', 'link', 'br', 'hr', 'input', 'area', 'param', 'col', 'base']</tt>.
|
|
#
|
|
# [<tt>:preserve</tt>] A list of tag names that should automatically have their newlines preserved
|
|
# using the Haml::Helpers#preserve helper.
|
|
# This means that any content given on the same line as the tag will be preserved.
|
|
# For example:
|
|
#
|
|
# %textarea= "Foo\nBar"
|
|
#
|
|
# compiles to:
|
|
#
|
|
# <textarea>Foo&
Bar</textarea>
|
|
#
|
|
# Defaults to <tt>['textarea', 'pre']</tt>.
|
|
#
|
|
# See also Whitespace Preservation, above.
|
|
#
|
|
module Haml
|
|
# Returns a hash representing the version of Haml.
|
|
# The :major, :minor, and :teeny keys have their respective numbers.
|
|
# The :string key contains a human-readable string representation of the version.
|
|
# If Haml is checked out from Git,
|
|
# the :rev key will have the revision hash.
|
|
def self.version
|
|
return @@version if defined?(@@version)
|
|
|
|
numbers = File.read(scope('VERSION')).strip.split('.').map { |n| n.to_i }
|
|
@@version = {
|
|
:major => numbers[0],
|
|
:minor => numbers[1],
|
|
:teeny => numbers[2]
|
|
}
|
|
@@version[:string] = [:major, :minor, :teeny].map { |comp| @@version[comp] }.compact.join('.')
|
|
|
|
if File.exists?(scope('REVISION'))
|
|
rev = File.read(scope('REVISION')).strip
|
|
rev = nil if rev !~ /a-f0-9+/
|
|
end
|
|
|
|
if rev.nil? && File.exists?(scope('.git/HEAD'))
|
|
rev = File.read(scope('.git/HEAD')).strip
|
|
if rev =~ /^ref: (.*)$/
|
|
rev = File.read(scope(".git/#{$1}")).strip
|
|
end
|
|
end
|
|
|
|
if rev
|
|
@@version[:rev] = rev
|
|
@@version[:string] << "." << rev[0...7]
|
|
end
|
|
|
|
@@version
|
|
end
|
|
|
|
# Returns the path of file relative to the Haml root.
|
|
def self.scope(file) # :nodoc:
|
|
File.join(File.dirname(__FILE__), '..', file)
|
|
end
|
|
|
|
# A string representing the version of Haml.
|
|
# A more fine-grained representation is generated by Haml.version.
|
|
VERSION = version[:string] unless defined?(Haml::VERSION)
|
|
|
|
# This method is called by init.rb,
|
|
# which is run by Rails on startup.
|
|
# We use it rather than putting stuff straight into init.rb
|
|
# so we can change the initialization behavior
|
|
# without modifying the file itself.
|
|
def self.init_rails(binding)
|
|
%w[haml/template sass sass/plugin].each(&method(:require))
|
|
end
|
|
end
|
|
|
|
require 'haml/engine'
|