# Module: Haml::Helpers

Extended by:
  Helpers

Includes:
  ActionViewExtensions, XssMods

Included in:
  Buffer, Helpers

Defined in:
  lib/haml/helpers.rb,
  lib/haml/template.rb,
  lib/haml/helpers/action_view_extensions.rb

## Overview

This module contains various helpful methods to make it easier to do various tasks. 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.

## Defined Under Namespace

Modules: ActionViewExtensions Classes: ErrorReturn

## Class Method Summary collapse

- .action_view? ⇒ Boolean

  Whether or not ActionView is loaded.

## Instance Method Summary collapse

- #block_is_haml?(block) ⇒ Boolean

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

- #capture_haml(*args) {|args| ... }

  Captures the result of a block of Haml code, gets rid of the excess indentation, and returns it as a string.

- #escape_once(text) ⇒ String (also: #escape_once_without_haml_xss)

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

- #find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block)

  Uses #preserve to convert any newlines inside whitespace-sensitive tags into the HTML entities for endlines.

- #haml_concat(text = "")

  Outputs text directly to the Haml buffer, with the proper indentation.

- #haml_indent ⇒ String

  The indentation string for the current line.

- #haml_tag(name, *rest, &block)

  Creates an HTML tag with the given name and optionally text and attributes.

- #haml_tag_if(condition, *tag)

  Conditionally wrap a block in an element.

- #html_attrs(lang = 'en-US') ⇒ {#to_s => String}

  Returns a hash containing default assignments for the `xmlns`, `lang`, and `xml:lang` attributes of the `html` HTML element.

- #html_escape(text) ⇒ String (also: #html_escape_without_haml_xss)

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

- #init_haml_helpers

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

- #is_haml? ⇒ Boolean

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

- #list_of(enum, opts = {}) {|item| ... }

  Takes an `Enumerable` object and a block and iterates over the enum, yielding each element to a Haml block and putting the result into `<li>` elements.

- #non_haml { ... }

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

- #precede(str) { ... }

  Prepends a string to the beginning of a Haml block, with no whitespace between.

- #preserve(input = nil, &block) (also: #flatten)

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

- #succeed(str) { ... }

  Appends a string to the end of a Haml block, with no whitespace between.

- #surround(front, back = front) { ... }

  Surrounds a block of Haml code with strings, with no whitespace in between.

- #tab_down(i = 1)

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

- #tab_up(i = 1)

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

- #with_tabs(i) { ... }

  Sets the number of tabs the buffer automatically adds to the lines of the template, but only for the duration of the block.

### Methods included from ActionViewExtensions

#page_class, #with_raw_haml_concat

## Class Method Details

### .action_view? ⇒ `Boolean`

Returns Whether or not ActionView is loaded.

Returns:

- (`Boolean`) —

  Whether or not ActionView is loaded

    56
    57
    58

    # File 'lib/haml/helpers.rb', line 56

    def self.action_view?
      @@action_view_defined
    end

## Instance Method Details

### #block_is_haml?(block) ⇒ `Boolean`

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

Parameters:

- block (`Proc`) —

  A Ruby block

Returns:

- (`Boolean`) —

  Whether or not `block` is defined directly in a Haml template

    646
    647
    648

    # File 'lib/haml/helpers.rb', line 646

    def block_is_haml?(block)
      eval('!!defined?(_hamlout)', block.binding)
    end

### #capture_haml(*args) {|args| ... }

Captures the result of a 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"`.

Parameters:

- args (`Array`) —

  Arguments to pass into the block

Yields:

- (`args`) —

  A block of Haml code that will be converted to a string

Yield Parameters:

- args (`Array`) —

  `args`

    373
    374
    375
    376
    377
    378
    379
    380
    381
    382
    383
    384
    385
    386
    387
    388
    389
    390
    391

    # File 'lib/haml/helpers.rb', line 373

    def capture_haml(*args, &block)
      buffer = eval('if defined? _hamlout then _hamlout else nil end', block.binding) || haml_buffer
      with_haml_buffer(buffer) do
        position = haml_buffer.buffer.length

        haml_buffer.capture_position = position
        value = block.call(*args)

        captured = haml_buffer.buffer.slice!(position..-1)

        if captured == '' and value != haml_buffer.buffer
          captured = (value.is_a?(String) ? value : nil)
        end

        captured
      end
    ensure
      haml_buffer.capture_position = nil
    end

### #escape_once(text) ⇒ `String` Also known as: escape_once_without_haml_xss

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

Parameters:

- text (`String`) —

  The string to sanitize

Returns:

- (`String`) —

  The sanitized string

    623
    624
    625
    626

    # File 'lib/haml/helpers.rb', line 623

    def escape_once(text)
      text = text.to_s
      text.gsub(HTML_ESCAPE_ONCE_REGEX, HTML_ESCAPE)
    end

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

Uses #preserve to convert any newlines inside whitespace-sensitive tags into the HTML entities for endlines.

Overloads:

- #find_and_preserve(input, tags = haml_buffer.options[:preserve])

  Escapes newlines within a string.

  Parameters:

  - input (`String`) —

    The string within which to escape newlines

- #find_and_preserve(tags = haml_buffer.options[:preserve]) { ... }

  Escapes newlines within a block of Haml code.

  Yields:

  - The block within which to escape newlines

Parameters:

- tags (`Array<String>`) (defaults to: `haml_buffer.options[:preserve]`) —

  Tags that should have newlines escaped

    111
    112
    113
    114
    115
    116
    117
    118
    119

    # File 'lib/haml/helpers.rb', line 111

    def find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block)
      return find_and_preserve(capture_haml(&block), input || tags) if block
      tags = tags.map { |tag| Regexp.escape(tag) }.join('|')
      re = /<(#{tags})([^>]*)>(.*?)(<\/\1>)/im
      input.to_s.gsub(re) do |s|
        s =~ re # Can't rely on $1, etc. existing since Rails' SafeBuffer#gsub is incompatible
        "<#{$1}#{$2}>#{preserve($3)}</#{$1}>"
      end
    end

### #haml_concat(text = "")

Outputs text directly to the Haml buffer, with the proper indentation.

Parameters:

- text (`#to_s`) (defaults to: `""`) —

  The text to output

    396
    397
    398
    399

    # File 'lib/haml/helpers.rb', line 396

    def haml_concat(text = "")
      haml_internal_concat text
      ErrorReturn.new("haml_concat")
    end

### #haml_indent ⇒ `String`

Returns The indentation string for the current line.

Returns:

- (`String`) —

  The indentation string for the current line

    427
    428
    429

    # File 'lib/haml/helpers.rb', line 427

    def haml_indent
      '  ' * haml_buffer.tabulation
    end

### #haml_tag(name, *rest, 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 run between the opening and closing tags. If the block is a Haml block or outputs text using #haml_concat, the text will be properly indented.

`name` can be a string using the standard Haml class/id shorthand (e.g. “span#foo.bar”, “#foo”). Just like standard Haml tags, these class and id values will be merged with manually-specified attributes.

`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.

`haml_tag` outputs directly to the buffer; its return value should not be used. If you need to get the results as a string, use #capture_haml.

For example,

    haml_tag :table do
      haml_tag :tr do
        haml_tag 'td.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>

Overloads:

- #haml_tag(name, *rest, attributes = {}) { ... }

  Yields:

  - The block of Haml code within the tag

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

  Parameters:

  - text (`#to_s`) —

    The text within the tag

  - flags (`Array<Symbol>`) —

    Haml end-of-tag flags

Parameters:

- name (`#to_s`) —

  The name of the tag

    488
    489
    490
    491
    492
    493
    494
    495
    496
    497
    498
    499
    500
    501
    502
    503
    504
    505
    506
    507
    508
    509
    510
    511
    512
    513
    514
    515
    516
    517
    518
    519
    520
    521
    522
    523
    524
    525
    526
    527
    528
    529
    530
    531
    532
    533
    534
    535
    536
    537
    538
    539
    540
    541
    542
    543
    544
    545
    546
    547
    548
    549
    550

    # File 'lib/haml/helpers.rb', line 488

    def haml_tag(name, *rest, &block)
      ret = ErrorReturn.new("haml_tag")

      text = rest.shift.to_s unless [Symbol, Hash, NilClass].any? {|t| rest.first.is_a? t}
      flags = []
      flags << rest.shift while rest.first.is_a? Symbol
      attrs = (rest.shift || {})
      attrs.keys.each {|key| attrs[key.to_s] = attrs.delete(key)} unless attrs.empty?
      name, attrs = merge_name_and_attributes(name.to_s, attrs)

      attributes = Haml::AttributeBuilder.build_attributes(haml_buffer.html?,
        haml_buffer.options[:attr_wrapper],
        haml_buffer.options[:escape_attrs],
        haml_buffer.options[:hyphenate_data_attrs],
        attrs)

      if text.nil? && block.nil? && (haml_buffer.options[:autoclose].include?(name) || flags.include?(:/))
        haml_internal_concat_raw "<#{name}#{attributes}#{' /' if haml_buffer.options[:format] == :xhtml}>"
        return ret
      end

      if flags.include?(:/)
        raise Error.new(Error.message(:self_closing_content)) if text
        raise Error.new(Error.message(:illegal_nesting_self_closing)) if block
      end

      tag = "<#{name}#{attributes}>"
      end_tag = "</#{name}>"
      if block.nil?
        text = text.to_s
        if text.include?("\n")
          haml_internal_concat_raw tag
          tab_up
          haml_internal_concat text
          tab_down
          haml_internal_concat_raw end_tag
        else
          haml_internal_concat_raw tag, false
          haml_internal_concat text, false, false
          haml_internal_concat_raw end_tag, true, false
        end
        return ret
      end

      if text
        raise Error.new(Error.message(:illegal_nesting_line, name))
      end

      if flags.include?(:<)
        haml_internal_concat_raw tag, false
        haml_internal_concat "#{capture_haml(&block).strip}", false, false
        haml_internal_concat_raw end_tag, true, false
        return ret
      end

      haml_internal_concat_raw tag
      tab_up
      block.call
      tab_down
      haml_internal_concat_raw end_tag

      ret
    end

### #haml_tag_if(condition, *tag)

Conditionally wrap a block in an element. If `condition` is `true` then this method renders the tag described by the arguments in `tag` (using #haml_tag) with the given block inside, otherwise it just renders the block.

For example,

    - haml_tag_if important, '.important' do
      %p
        A (possibly) important paragraph.

will produce

    <div class='important'>
      <p>
        A (possibly) important paragraph.
      </p>
    </div>

if `important` is truthy, and just

    <p>
      A (possibly) important paragraph.
    </p>

otherwise.

Like #haml_tag, `haml_tag_if` outputs directly to the buffer and its return value should not be used. Use #capture_haml if you need to use its results as a string.

Parameters:

- condition —

  The condition to test to determine whether to render the enclosing tag

- tag —

  Definition of the enclosing tag. See #haml_tag for details (specifically the form that takes a block)

    586
    587
    588
    589
    590
    591
    592
    593

    # File 'lib/haml/helpers.rb', line 586

    def haml_tag_if(condition, *tag)
      if condition
        haml_tag(*tag){ yield }
      else
        yield
      end
      ErrorReturn.new("haml_tag_if")
    end

### #html_attrs(lang = 'en-US') ⇒ `{#to_s => String}`

Returns a hash containing default assignments for the `xmlns`, `lang`, and `xml:lang` attributes of the `html` HTML element. For example,

    %html{html_attrs}

becomes

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

Parameters:

- lang (`String`) (defaults to: `'en-US'`) —

  The value of `xml:lang` and `lang`

Returns:

- (`{#to_s => String}`) —

  The attribute hash

    228
    229
    230
    231
    232
    233
    234

    # File 'lib/haml/helpers.rb', line 228

    def html_attrs(lang = 'en-US')
      if haml_buffer.options[:format] == :xhtml
        {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
      else
        {:lang => lang}
      end
    end

### #html_escape(text) ⇒ `String` Also known as: html_escape_without_haml_xss

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

Note that if ActionView is loaded and XSS protection is enabled (as is the default for Rails 3.0+, and optional for version 2.3.5+), this won’t escape text declared as “safe”.

Parameters:

- text (`String`) —

  The string to sanitize

Returns:

- (`String`) —

  The sanitized string

    609
    610
    611

    # File 'lib/haml/helpers.rb', line 609

    def html_escape(text)
      CGI.escapeHTML(text.to_s)
    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 instance 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"

    76
    77
    78
    79

    # File 'lib/haml/helpers.rb', line 76

    def init_haml_helpers
      @haml_buffer = Haml::Buffer.new(haml_buffer, Options.new.for_buffer)
      nil
    end

### #is_haml? ⇒ `Boolean`

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.

Returns:

- (`Boolean`) —

  Whether or not the current template is a Haml template

    638
    639
    640

    # File 'lib/haml/helpers.rb', line 638

    def is_haml?
      !@haml_buffer.nil? && @haml_buffer.active?
    end

### #list_of(enum, opts = {}) {|item| ... }

Takes an `Enumerable` object and a block and iterates over the enum, 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>

While:

    = list_of(["Home", "About", "Contact", "FAQ"], {class: "nav", role: "nav"}) do |item|
      %a{ href="#" }= item

Produces:

    <li class='nav' role='nav'>
      <a href='#'>Home</a>
    </li>
    <li class='nav' role='nav'>
      <a href='#'>About</a>
    </li>
    <li class='nav' role='nav'>
      <a href='#'>Contact</a>
    </li>
    <li class='nav' role='nav'>
      <a href='#'>FAQ</a>
    </li>

`[[class", "nav"], [role", "nav"]]` could have been used instead of `{class: "nav", role: "nav"}` (or any enumerable collection where each pair of items responds to #to_s)

Parameters:

- enum (`Enumerable`) —

  The list of objects to iterate over

- opts (`Enumerable<#to_s,#to_s>`) (defaults to: `{}`) —

  Each key/value pair will become an attribute pair for each list item element.

Yields:

- (`item`) —

  A block which contains Haml code that goes within list items

Yield Parameters:

- item —

  An element of `enum`

    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214

    # File 'lib/haml/helpers.rb', line 200

    def list_of(enum, opts={}, &block)
      opts_attributes = opts.map { |k, v| " #{k}='#{v}'" }.join
      enum.map do |i|
        result = capture_haml(i, &block)

        if result.count("\n") > 1
          result.gsub!("\n", "\n  ")
          result = "\n  #{result.strip}\n"
        else
          result.strip!
        end

        %Q!<li#{opts_attributes}>#{result}</li>!
      end.join("\n")
    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.

Yields:

- A block which won’t register as Haml

    90
    91
    92
    93
    94
    95
    96

    # File 'lib/haml/helpers.rb', line 90

    def non_haml
      was_active = @haml_buffer.active?
      @haml_buffer.active = false
      yield
    ensure
      @haml_buffer.active = was_active
    end

### #precede(str) { ... }

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

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

Produces:

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

Parameters:

- str (`String`) —

  The string to add before the Haml

Yields:

- A block of Haml to prepend to

    336
    337
    338

    # File 'lib/haml/helpers.rb', line 336

    def precede(str, &block)
      "#{str}#{capture_haml(&block).chomp}\n"
    end

### #preserve(input) #preserve { ... } Also known as: flatten

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

Overloads:

- #preserve(input)

  Escapes newlines within a string.

  Parameters:

  - input (`String`) —

    The string within which to escape all newlines

- #preserve { ... }

  Escapes newlines within a block of Haml code.

  Yields:

  - The block within which to escape newlines

    133
    134
    135
    136
    137
    138
    139

    # File 'lib/haml/helpers.rb', line 133

    def preserve(input = nil, &block)
      return preserve(capture_haml(&block)) if block
      s = input.to_s.chomp("\n")
      s.gsub!(/\n/, '&#x000A;')
      s.delete!("\r")
      s
    end

### #succeed(str) { ... }

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

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

Produces:

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

Parameters:

- str (`String`) —

  The string to add after the Haml

Yields:

- A block of Haml to append to

    355
    356
    357

    # File 'lib/haml/helpers.rb', line 355

    def succeed(str, &block)
      "#{capture_haml(&block).chomp}#{str}\n"
    end

### #surround(front, back = front) { ... }

Surrounds a block of Haml code with strings, 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>*

Parameters:

- front (`String`) —

  The string to add before the Haml

- back (`String`) (defaults to: `front`) —

  The string to add after the Haml

Yields:

- A block of Haml to surround

    317
    318
    319
    320
    321

    # File 'lib/haml/helpers.rb', line 317

    def surround(front, back = front, &block)
      output = capture_haml(&block)

      "#{front}#{output.chomp}#{back}\n"
    end

### #tab_down(i = 1)

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

Parameters:

- i (`Fixnum`) (defaults to: `1`) —

  The number of tabs by which to decrease the indentation

See Also:

- #tab_up

    263
    264
    265

    # File 'lib/haml/helpers.rb', line 263

    def tab_down(i = 1)
      haml_buffer.tabulation -= i
    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>

Parameters:

- i (`Fixnum`) (defaults to: `1`) —

  The number of tabs by which to increase the indentation

See Also:

- #tab_down

    254
    255
    256

    # File 'lib/haml/helpers.rb', line 254

    def tab_up(i = 1)
      haml_buffer.tabulation += i
    end

### #with_tabs(i) { ... }

Sets the number of tabs the buffer automatically adds to the lines of the template, but only for the duration of the block. For example:

    %h1 foo
    - with_tabs(2) do
      %p bar
    %strong baz

Produces:

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

Parameters:

- i (`Fixnum`) —

  The number of tabs to use

Yields:

- A block in which the indentation will be `i` spaces

    286
    287
    288
    289
    290
    291
    292

    # File 'lib/haml/helpers.rb', line 286

    def with_tabs(i)
      old_tabs = haml_buffer.tabulation
      haml_buffer.tabulation = i
      yield
    ensure
      haml_buffer.tabulation = old_tabs
    end