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, RHTML, 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 # * Interpolates Ruby code # * Implements Rails templates with the .haml extension # # # == 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. # # ==== % # # # This element 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 . # For example: # # %one # %two # %three Hey there # # is compiled to: # # # # Hey there # # # # 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: # # # # # # ==== [] # # 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. # For example: # # # file: app/controllers/users_controller.rb # # def show # @user = CrazyUser.find(15) # end # # # file: app/views/users/show.haml # # %div[@user] # %bar[290]/ # Hello! # # is compiled to: # #

# # Hello! #

# # This is based off of DHH's SimplyHelpful syntax, # as presented at RailsConf Europe 2006. # # ==== / # # 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: # #
# # # ==== . 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: # # %div#things # %span#rice Chicken Fried # %p.beans{ :food => 'true' } The magical fruit # %h1.class.otherclass#id La La La # # is compiled to: # #

# Chicken Fried #

The magical fruit

La La La

# # 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: # #

Doogie Howser Comes Out

2006-11-05

# Neil Patrick Harris would like to dispel any rumors that he is straight #

# # ==== 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 . or # 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: # #

Broken record album

What a cool item!

# # ==== = and ~ # # = and ~ are placed at the end of a tag definition, # after class, id, and attribute declarations. # They're just shortcuts for inserting Ruby code into an element. # They work the same as = and ~ without a tag; # see below for documentation of those. # However, if the result is short enough, # it is displayed entirely on one line. # For example: # # %p= "hello" # %h1~ 1 + 2 # # is not quite the same as: # # %p # = "hello" # %h1 # ~ 1 + 2 # # It's compiled to: # #

hello

3

# # === 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: # # # # Wow this is cool! # # # # ==== !!! # # When describing XHTML documents with Haml, # you can have a document type or XML prolog generated automatically # by including the characters !!!. # For example: # # !!! XML # !!! # %html # %head # %title Myspace # %body # %h1 I am the international space station # %p Sign my guestbook # # is compiled to: # # # # # # Myspace # # #

I am the international space station

Sign my guestbook

# # # # You can also specify the version and type of XHTML after the !!!. # 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: # # # # and # # !!! Strict # # is compiled to: # # # # If you're not using the UTF-8 characterset 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: # # # # ==== / # # The forward slash character, when placed at the beginning of a line, # wraps all text after it in an HTML comment. # For example: # # %billabong # / This is the billabong element # I like billabongs! # # is compiled to: # # # # I like billabongs! # # # 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: # # # # 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 /. # For example: # # /[if IE] # %a{ :href => 'http://www.mozilla.com/en-US/firefox/' } # %h1 Get Firefox # # is compiled to: # # # # ==== \ # # 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: # # # MyPage # - MySite # # # ==== | # # 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 | # 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: # # %hoo I think this might get | # pretty long so I should | # probably make it | # multiline so it doesn't | # look awful. | # # ==== : # # 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 # #

Textile

# #

Hello, World

# # Haml has the following filters defined: # # [plain] Does not parse the filtered text. # # [ruby] Parses the filtered text with the normal Ruby interpreter. # All output sent to $stdout, like with +puts+, # is output into the Haml document. # Not available if the suppress_eval option is set to true. # # [erb] Parses the filtered text with ERB, like an RHTML template. # Not available if the suppress_eval option is set to true. # At the moment, this doesn't support access to variables # defined by Ruby on Rails or Haml code. # # [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: # #

# hi there reader! # yo #

# # ==== ~ # # The tilde character works the same as the equals character, # but the output is modified in such a way # that newlines in whitespace-sensitive elements work properly. # For example: # # %foo # = "Woah

  this is   \n

crazy" # %foo2 # ~ "Woah

  this is   \n

crazy" # # is compiled to: # # # Woah

  this is
#

crazy # # # Woah

  this is

crazy # # # If the ~ character isn't followed by text, # it doesn't evaluate Ruby at all. # Instead, an indented section following it will be rendered # in a whitespace-sensitive manner, # using HTML encodings for newlines. # For example: # # For example: # # .house # %pre # ~ # /^^^\ # |[] []| # |_____| # # is compiled to: # #

#       
 /^^^\
|[] []|
|_____|

#

# # ==== - # # The hyphen character makes the text following it into "silent script": # Ruby script that is evaluated, but not output. # # 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. # # For example: # # - foo = "hello" # - foo << " there" # - foo << " you!" # %p= foo # # is compiled to: # #

# hello there you! #

# # ===== 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: # #

# 42 #

# 43 #

# 44 #

# 45 #

# 46 #

# # Another example: # # %p # - case 2 # - when 1 # = "1!" # - when 2 # = "2?" # - when 3 # = "3." # # is compiled to: # #

# 2? #

# # == Using Haml as a Rails plugin # # Write Rails templates with the .haml extension. # For example: # # # file: app/views/movies/teen_wolf.haml # # %html # %head # %title= "Teen Wolf (1985)" # %body # #contents # %h1 "A highschooler discovers that he is a werewolf" # %ul.cast # %li "Scott Howard" # %li "Rupert 'Stiles' Stilinski" # %li "Lisa 'Boof' Marconi" # %li "Lewis" # # is compiled to: # # # # Teen Wolf (1985) # # #

A highschooler discovers that he is a werewolf

Scott Howard
Rupert 'Stiles' Stilinski
Lisa 'Boof' Marconi
Lewis

# # # # 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 # # 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: # #

Teen Wolf

# Home #

# # === Setting Options # # Options can be set by setting the hash Haml::Template.options # from environment.rb. # Available options are: # # [:suppress_eval] Whether or not attribute hashes and Ruby scripts # designated by = or ~ should be # evaluated. If this is true, said scripts are # rendered as empty strings. Defaults to false. # # [:precompiled] A string containing a precompiled Haml template. # If this is passed, template is ignored # and no precompilation is done. # # [:attr_wrapper] The character that should wrap element attributes. # This defaults to ' (an apostrophe). Characters # of this type within the attributes will be escaped # (e.g. by replacing them with ') if # the character is an apostrophe or a quotation mark. # # [:filename] 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. # # [:filters] 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: # * An +initialize+ method that accepts one parameter, # the text to be filtered. # * A +render+ method that returns the result of the filtering. # # [:locals] The local variables that will be available within the # template. For instance, if :locals is # { :foo => "bar" }, then within the template, # = foo will produce bar. # module Haml; end require 'haml/engine'