Module: Haml::Helpers

Module | Haml::Helpers
In: | lib/haml/helpers.rb lib/haml/helpers/action_view_extensions.rb

This module contains various helpful methods to make it easier to do various tasks. Haml::Helpers is automatically included in the context that a Haml template is parsed in, so all these methods are at your disposal from within the template.

### Methods

action_view? block_is_haml? capture_haml escape_once find_and_preserve flatten haml_concat haml_indent haml_tag html_attrs html_escape init_haml_helpers is_haml? list_of non_haml precede preserve succeed surround tab_down tab_up

### Included Modules

ActionViewExtensions

### Classes and Modules

Module Haml::Helpers::ActionViewExtensions

### Constants

HTML_ESCAPE | = | { '&'=>'&amp;', '<'=>'&lt;', '>'=>'&gt;', '"'=>'&quot;', "'"=>'&#039;', } |  | Characters that need to be escaped to HTML entities from user input

### Public Class methods

action_view?()

Returns whether or not ActionView is installed on the system.

[Source]

        # File lib/haml/helpers.rb, line 16
    16:     def self.action_view?
    17:       @@action_view_defined
    18:     end

### Public Instance methods

block_is_haml?(block)

Returns whether or not `block` is defined directly in a Haml template.

[Source]

         # File lib/haml/helpers.rb, line 415
    415:     def block_is_haml?(block)
    416:       eval('_hamlout', block.binding)
    417:       true
    418:     rescue
    419:       false
    420:     end

capture_haml(*args, &block)

Captures the result of the given block of Haml code, gets rid of the excess indentation, and returns it as a string. For example, after the following,

      .foo
        - foo = capture_haml(13) do |a|
          %p= a

the local variable `foo` would be assigned to "<p>13</p>\n".

[Source]

         # File lib/haml/helpers.rb, line 256
    256:     def capture_haml(*args, &block)
    257:       buffer = eval('_hamlout', block.binding) rescue haml_buffer
    258:       with_haml_buffer(buffer) do
    259:         position = haml_buffer.buffer.length
    260:
    261:         block.call(*args)
    262:
    263:         captured = haml_buffer.buffer.slice!(position..-1).split(/^/)
    264:
    265:         min_tabs = nil
    266:         captured.each do |line|
    267:           tabs = line.index(/[^ ]/) || line.length
    268:           min_tabs ||= tabs
    269:           min_tabs = min_tabs > tabs ? tabs : min_tabs
    270:         end
    271:
    272:         result = captured.map do |line|
    273:           line[min_tabs..-1]
    274:         end
    275:         result.to_s
    276:       end
    277:     end

escape_once(text)

Escapes HTML entities in `text`, but without escaping an ampersand that is already part of an escaped entity.

[Source]

         # File lib/haml/helpers.rb, line 401
    401:     def escape_once(text)
    402:       text.to_s.gsub(/[\"><]|&(?!([a-zA-Z]+|(#\d+));)/) { |s| HTML_ESCAPE[s] }
    403:     end

find_and_preserve(input, tags = haml_buffer.options[:preserve])
find_and_preserve {...}

Uses preserve to convert any newlines inside whitespace-sensitive tags into the HTML entities for endlines. @tags@ is an array of tags to preserve. It defaults to the value of the `:preserve` option.

[Source]

        # File lib/haml/helpers.rb, line 70
    70:     def find_and_preserve(input = '', tags = haml_buffer.options[:preserve], &block)
    71:       return find_and_preserve(capture_haml(&block)) if block
    72:
    73:       input = input.to_s
    74:       input.gsub(/<(#{tags.map(&Regexp.method(:escape)).join('|')})([^>]*)>(.*?)(<\/\1>)/im) do
    75:         "<#{$1}#{$2}>#{preserve($3)}</#{$1}>"
    76:       end
    77:     end

flatten(input = '', &block)

Alias for preserve

haml_concat(text = "")

Outputs text directly to the Haml buffer, with the proper tabulation

[Source]

         # File lib/haml/helpers.rb, line 290
    290:     def haml_concat(text = "")
    291:       haml_buffer.buffer << haml_indent << text.to_s << "\n"
    292:       nil
    293:     end

haml_indent()

Returns the string that should be used to indent the current line

[Source]

         # File lib/haml/helpers.rb, line 296
    296:     def haml_indent
    297:       '  ' * haml_buffer.tabulation
    298:     end

haml_tag(name, *flags, attributes = {}) {...}
haml_tag(name, text, *flags, attributes = {}) {...}

Creates an HTML tag with the given name and optionally text and attributes. Can take a block that will be executed between when the opening and closing tags are output. If the block is a Haml block or outputs text using haml_concat, the text will be properly indented.

`flags` is a list of symbol flags like those that can be put at the end of a Haml tag (`:/`, `:<`, and `:>`). Currently, only `:/` and `:<` are supported.

For example,

      haml_tag :table do
        haml_tag :tr do
          haml_tag :td, {:class => 'cell'} do
            haml_tag :strong, "strong!"
            haml_concat "data"
          end
          haml_tag :td do
            haml_concat "more_data"
          end
        end
      end

outputs

      <table>
        <tr>
          <td class='cell'>
            <strong>
              strong!
            </strong>
            data
          </td>
          <td>
            more_data
          </td>
        </tr>
      </table>

[Source]

         # File lib/haml/helpers.rb, line 346
    346:     def haml_tag(name, *rest, &block)
    347:       name = name.to_s
    348:       text = rest.shift.to_s unless [Symbol, Hash, NilClass].any? {|t| rest.first.is_a? t}
    349:       flags = []
    350:       flags << rest.shift while rest.first.is_a? Symbol
    351:       attributes = Haml::Precompiler.build_attributes(haml_buffer.html?,
    352:                                                       haml_buffer.options[:attr_wrapper],
    353:                                                       rest.shift || {})
    354:
    355:       if text.nil? && block.nil? && (haml_buffer.options[:autoclose].include?(name) || flags.include?(:/))
    356:         haml_concat "<#{name}#{attributes} />"
    357:         return nil
    358:       end
    359:
    360:       if flags.include?(:/)
    361:         raise Error.new("Self-closing tags can't have content.") if text
    362:         raise Error.new("Illegal nesting: nesting within a self-closing tag is illegal.") if block
    363:       end
    364:
    365:       tag = "<#{name}#{attributes}>"
    366:       if block.nil?
    367:         tag << text.to_s << "</#{name}>"
    368:         haml_concat tag
    369:         return
    370:       end
    371:
    372:       if text
    373:         raise Error.new("Illegal nesting: content can't be both given to haml_tag :#{name} and nested within it.")
    374:       end
    375:
    376:       if flags.include?(:<)
    377:         tag << capture_haml(&block).strip << "</#{name}>"
    378:         haml_concat tag
    379:         return
    380:       end
    381:
    382:       haml_concat tag
    383:       tab_up
    384:       block.call
    385:       tab_down
    386:       haml_concat "</#{name}>"
    387:       nil
    388:     end

html_attrs(lang = 'en-US')

Returns a hash containing default assignments for the xmlns and xml:lang attributes of the `html` HTML element. It also takes an optional argument for the value of xml:lang and lang, which defaults to ‘en-US’. For example,

      %html{html_attrs}

becomes

      <html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en-US' lang='en-US'>

[Source]

         # File lib/haml/helpers.rb, line 154
    154:     def html_attrs(lang = 'en-US')
    155:       {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
    156:     end

html_escape(text)

Returns a copy of `text` with ampersands, angle brackets and quotes escaped into HTML entities.

[Source]

         # File lib/haml/helpers.rb, line 395
    395:     def html_escape(text)
    396:       text.to_s.gsub(/[\"><&]/) { |s| HTML_ESCAPE[s] }
    397:     end

init_haml_helpers()

Note: this does not need to be called when using Haml helpers normally in Rails.

Initializes the current object as though it were in the same context as a normal ActionView rendering using Haml. This is useful if you want to use the helpers in a context other than the normal setup with ActionView. For example:

      context = Object.new
      class << context
        include Haml::Helpers
      end
      context.init_haml_helpers
      context.haml_tag :p, "Stuff"

[Source]

        # File lib/haml/helpers.rb, line 39
    39:     def init_haml_helpers
    40:       @haml_buffer = Haml::Buffer.new(@haml_buffer, Haml::Engine.new('').send(:options_for_buffer))
    41:       nil
    42:     end

is_haml?()

Returns whether or not the current template is a Haml template.

This function, unlike other Haml::Helpers functions, also works in other ActionView templates, where it will always return false.

[Source]

         # File lib/haml/helpers.rb, line 410
    410:     def is_haml?
    411:       !@haml_buffer.nil? && @haml_buffer.active?
    412:     end

list_of(array) {|item| ...}

Takes an Enumerable object and a block and iterates over the object, yielding each element to a Haml block and putting the result into `<li>` elements. This creates a list of the results of the block. For example:

      = list_of([['hello'], ['yall']]) do |i|
        = i[0]

Produces:

      <li>hello</li>
      <li>yall</li>

And

      = list_of({:title => 'All the stuff', :description => 'A book about all the stuff.'}) do |key, val|
        %h3= key.humanize
        %p= val

Produces:

      <li>
        <h3>Title</h3>
        <p>All the stuff</p>
      </li>
      <li>
        <h3>Description</h3>
        <p>A book about all the stuff.</p>
      </li>

[Source]

         # File lib/haml/helpers.rb, line 126
    126:     def list_of(array, &block) # :yields: item
    127:       to_return = array.collect do |i|
    128:         result = capture_haml(i, &block)
    129:
    130:         if result.count("\n") > 1
    131:           result.gsub!("\n", "\n  ")
    132:           result = "\n  #{result.strip}\n"
    133:         else
    134:           result.strip!
    135:         end
    136:
    137:         "<li>#{result}</li>"
    138:       end
    139:       to_return.join("\n")
    140:     end

non_haml { ... }

Runs a block of code in a non-Haml context (i.e. is_haml? will return false).

This is mainly useful for rendering sub-templates such as partials in a non-Haml language, particularly where helpers may behave differently when run from Haml.

Note that this is automatically applied to Rails partials.

[Source]

        # File lib/haml/helpers.rb, line 54
    54:     def non_haml
    55:       was_active = @haml_buffer.active?
    56:       @haml_buffer.active = false
    57:       yield
    58:     ensure
    59:       @haml_buffer.active = was_active
    60:     end

precede(char, &block)

Prepends the given character to the beginning of the Haml block, with no whitespace between. For example:

      = precede '*' do
        %span.small Not really

Produces:

      *<span class='small'>Not really</span>

[Source]

         # File lib/haml/helpers.rb, line 224
    224:     def precede(char, &block)
    225:       "#{char}#{capture_haml(&block).chomp}\n"
    226:     end

preserve(input)
preserve {...}

Takes any string, finds all the endlines and converts them to HTML entities for endlines so they‘ll render correctly in whitespace-sensitive tags without screwing up the indentation.

[Source]

        # File lib/haml/helpers.rb, line 86
    86:     def preserve(input = '', &block)
    87:       return preserve(capture_haml(&block)) if block
    88:
    89:       input.chomp("\n").gsub(/\n/, '&#x000A;').gsub(/\r/, '')
    90:     end

succeed(char, &block)

Appends the given character to the end of the Haml block, with no whitespace between. For example:

      click
      = succeed '.' do
        %a{:href=>"thing"} here

Produces:

      click
      <a href='thing'>here</a>.

[Source]

         # File lib/haml/helpers.rb, line 241
    241:     def succeed(char, &block)
    242:       "#{capture_haml(&block).chomp}#{char}\n"
    243:     end

surround(front, back = nil, &block)

Surrounds the given block of Haml code with the given characters, with no whitespace in between. For example:

      = surround '(', ')' do
        %a{:href => "food"} chicken

Produces:

      (<a href='food'>chicken</a>)

and

      = surround '*' do
        %strong angry

Produces:

      *<strong>angry</strong>*

[Source]

         # File lib/haml/helpers.rb, line 206
    206:     def surround(front, back = nil, &block)
    207:       back ||= front
    208:       output = capture_haml(&block)
    209:
    210:       "#{front}#{output.chomp}#{back}\n"
    211:     end

tab_down(i = 1)

Decrements the number of tabs the buffer automatically adds to the lines of the template.

See also tab_up.

[Source]

         # File lib/haml/helpers.rb, line 182
    182:     def tab_down(i = 1)
    183:       haml_buffer.tabulation -= i
    184:     end

tab_up(i = 1)

Increments the number of tabs the buffer automatically adds to the lines of the template. For example:

      %h1 foo
      - tab_up
      %p bar
      - tab_down
      %strong baz

Produces:

      <h1>foo</h1>
        <p>bar</p>
      <strong>baz</strong>

[Source]

         # File lib/haml/helpers.rb, line 174
    174:     def tab_up(i = 1)
    175:       haml_buffer.tabulation += i
    176:     end

[Validate]