Module | Haml::Helpers
In: | lib/haml/helpers.rb lib/haml/helpers/xss_mods.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 with_tabs

### Included Modules

ActionViewExtensions

### Classes and Modules

Module Haml::Helpers::ActionViewExtensions
Module Haml::Helpers::XssMods
Class Haml::Helpers::ErrorReturn

### 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?()

@return [Boolean] Whether or not ActionView is loaded

[Source]

        # File lib/haml/helpers.rb, line 54
    54:     def self.action_view?
    55:       @@action_view_defined
    56:     end

### Public Instance methods

block_is_haml?(block)

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

@param block [Proc] A Ruby block @return [Boolean] Whether or not `block` is defined directly in a Haml template

[Source]

         # File lib/haml/helpers.rb, line 539
    539:     def block_is_haml?(block)
    540:       eval('_hamlout', block.binding)
    541:       true
    542:     rescue
    543:       false
    544:     end

capture_haml(*args, &block)

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

@param args [Array] Arguments to pass into the block @yield [args] A block of Haml code that will be converted to a string @yieldparam args [Array] `args`

[Source]

         # File lib/haml/helpers.rb, line 338
    338:     def capture_haml(*args, &block)
    339:       buffer = eval('_hamlout', block.binding) rescue haml_buffer
    340:       with_haml_buffer(buffer) do
    341:         position = haml_buffer.buffer.length
    342:
    343:         haml_buffer.capture_position = position
    344:         block.call(*args)
    345:
    346:         captured = haml_buffer.buffer.slice!(position..-1)
    347:         return captured if haml_buffer.options[:ugly]
    348:         captured = captured.split(/^/)
    349:
    350:         min_tabs = nil
    351:         captured.each do |line|
    352:           tabs = line.index(/[^ ]/) || line.length
    353:           min_tabs ||= tabs
    354:           min_tabs = min_tabs > tabs ? tabs : min_tabs
    355:         end
    356:
    357:         captured.map do |line|
    358:           line[min_tabs..-1]
    359:         end.join
    360:       end
    361:     ensure
    362:       haml_buffer.capture_position = nil
    363:     end

escape_once(text)

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

@param text [String] The string to sanitize @return [String] The sanitized string

[Source]

         # File lib/haml/helpers.rb, line 518
    518:     def escape_once(text)
    519:       Haml::Util.silence_warnings do
    520:         text.to_s.gsub(/[\"><]|&(?!(?:[a-zA-Z]+|(#\d+));)/n) {|s| HTML_ESCAPE[s]}
    521:       end
    522:     end

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.

@param tags [Array<String>] Tags that should have newlines escaped

@overload find_and_preserve(input, tags = haml_buffer.options[:preserve])

      Escapes newlines within a string.

      @param input [String] The string within which to escape newlines

@overload find_and_preserve(tags = haml_buffer.options[:preserve])

      Escapes newlines within a block of Haml code.

      @yield The block within which to escape newlines

[Source]

         # File lib/haml/helpers.rb, line 109
    109:     def find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block)
    110:       return find_and_preserve(capture_haml(&block), input || tags) if block
    111:       input.to_s.gsub(/<(#{tags.map(&Regexp.method(:escape)).join('|')})([^>]*)>(.*?)(<\/\1>)/im) do
    112:         "<#{$1}#{$2}>#{preserve($3)}</#{$1}>"
    113:       end
    114:     end

flatten(input = nil, &block)

Alias for preserve

haml_concat(text = "")

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

@param text [to_s] The text to output

[Source]

         # File lib/haml/helpers.rb, line 368
    368:     def haml_concat(text = "")
    369:       unless haml_buffer.options[:ugly] || haml_indent == 0
    370:         haml_buffer.buffer << haml_indent <<
    371:           text.to_s.gsub("\n", "\n" + haml_indent) << "\n"
    372:       else
    373:         haml_buffer.buffer << text.to_s << "\n"
    374:       end
    375:       ErrorReturn.new("haml_concat")
    376:     end

haml_indent()

@return [String] The indentation string for the current line

[Source]

         # File lib/haml/helpers.rb, line 379
    379:     def haml_indent
    380:       '  ' * haml_buffer.tabulation
    381:     end

haml_tag(name, *rest, &block)

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>

@param name [to_s] The name of the tag @param flags [Array<Symbol>] Haml end-of-tag flags

@overload haml_tag(name, *flags, attributes = {})

      @yield The block of Haml code within the tag

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

      @param text [#to_s] The text within the tag

[Source]

         # File lib/haml/helpers.rb, line 440
    440:     def haml_tag(name, *rest, &block)
    441:       ret = ErrorReturn.new("haml_tag")
    442:
    443:       text = rest.shift.to_s unless [Symbol, Hash, NilClass].any? {|t| rest.first.is_a? t}
    444:       flags = []
    445:       flags << rest.shift while rest.first.is_a? Symbol
    446:       name, attrs = merge_name_and_attributes(name.to_s, rest.shift || {})
    447:
    448:       attributes = Haml::Precompiler.build_attributes(haml_buffer.html?,
    449:                                                       haml_buffer.options[:attr_wrapper],
    450:                                                       attrs)
    451:
    452:       if text.nil? && block.nil? && (haml_buffer.options[:autoclose].include?(name) || flags.include?(:/))
    453:         haml_concat "<#{name}#{attributes} />"
    454:         return ret
    455:       end
    456:
    457:       if flags.include?(:/)
    458:         raise Error.new("Self-closing tags can't have content.") if text
    459:         raise Error.new("Illegal nesting: nesting within a self-closing tag is illegal.") if block
    460:       end
    461:
    462:       tag = "<#{name}#{attributes}>"
    463:       if block.nil?
    464:         text = text.to_s
    465:         if text.include?("\n")
    466:           haml_concat tag
    467:           tab_up
    468:           haml_concat text
    469:           tab_down
    470:           haml_concat "</#{name}>"
    471:         else
    472:           tag << text << "</#{name}>"
    473:           haml_concat tag
    474:         end
    475:         return ret
    476:       end
    477:
    478:       if text
    479:         raise Error.new("Illegal nesting: content can't be both given to haml_tag :#{name} and nested within it.")
    480:       end
    481:
    482:       if flags.include?(:<)
    483:         tag << capture_haml(&block).strip << "</#{name}>"
    484:         haml_concat tag
    485:         return ret
    486:       end
    487:
    488:       haml_concat tag
    489:       tab_up
    490:       block.call
    491:       tab_down
    492:       haml_concat "</#{name}>"
    493:
    494:       ret
    495:     end

html_attrs(lang = 'en-US')

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'>

@param lang [String] The value of `xml:lang` and `lang` @return [{to_s => String}] The attribute hash

[Source]

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

html_escape(text)

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

@param text [String] The string to sanitize @return [String] The sanitized string

[Source]

         # File lib/haml/helpers.rb, line 509
    509:     def html_escape(text)
    510:       Haml::Util.silence_warnings {text.to_s.gsub(/[\"><&]/n) {|s| HTML_ESCAPE[s]}}
    511:     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"

[Source]

        # File lib/haml/helpers.rb, line 74
    74:     def init_haml_helpers
    75:       @haml_buffer = Haml::Buffer.new(@haml_buffer, Haml::Engine.new('').send(:options_for_buffer))
    76:       nil
    77:     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.

@return [Boolean] Whether or not the current template is a Haml template

[Source]

         # File lib/haml/helpers.rb, line 531
    531:     def is_haml?
    532:       !@haml_buffer.nil? && @haml_buffer.active?
    533:     end

list_of(enum, &block)

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>

@param enum [Enumerable] The list of objects to iterate over @yield [item] A block which contains Haml code that goes within list items @yieldparam item An element of `enum`

[Source]

         # File lib/haml/helpers.rb, line 169
    169:     def list_of(enum, &block)
    170:       to_return = enum.collect do |i|
    171:         result = capture_haml(i, &block)
    172:
    173:         if result.count("\n") > 1
    174:           result.gsub!("\n", "\n  ")
    175:           result = "\n  #{result.strip}\n"
    176:         else
    177:           result.strip!
    178:         end
    179:
    180:         "<li>#{result}</li>"
    181:       end
    182:       to_return.join("\n")
    183:     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.

@yield A block which won‘t register as Haml

[Source]

        # File lib/haml/helpers.rb, line 88
    88:     def non_haml
    89:       was_active = @haml_buffer.active?
    90:       @haml_buffer.active = false
    91:       yield
    92:     ensure
    93:       @haml_buffer.active = was_active
    94:     end

precede(str, &block)

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>

@param str [String] The string to add before the Haml @yield A block of Haml to prepend to

[Source]

         # File lib/haml/helpers.rb, line 301
    301:     def precede(str, &block)
    302:       "#{str}#{capture_haml(&block).chomp}\n"
    303:     end

preserve(input = nil, &block)

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.

@overload perserve(input)

      Escapes newlines within a string.

      @param input [String] The string within which to escape all newlines

@overload perserve

      Escapes newlines within a block of Haml code.

      @yield The block within which to escape newlines

[Source]

         # File lib/haml/helpers.rb, line 128
    128:     def preserve(input = nil, &block)
    129:       return preserve(capture_haml(&block)) if block
    130:       input.to_s.chomp("\n").gsub(/\n/, '&#x000A;').gsub(/\r/, '')
    131:     end

succeed(str, &block)

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

@param str [String] The string to add after the Haml @yield A block of Haml to append to

[Source]

         # File lib/haml/helpers.rb, line 320
    320:     def succeed(str, &block)
    321:       "#{capture_haml(&block).chomp}#{str}\n"
    322:     end

surround(front, back = front, &block)

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>*

@param front [String] The string to add before the Haml @param back [String] The string to add after the Haml @yield A block of Haml to surround

[Source]

         # File lib/haml/helpers.rb, line 282
    282:     def surround(front, back = front, &block)
    283:       output = capture_haml(&block)
    284:
    285:       "#{front}#{output.chomp}#{back}\n"
    286:     end

tab_down(i = 1)

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

@param i [Fixnum] The number of tabs by which to decrease the indentation @see tab_up

[Source]

         # File lib/haml/helpers.rb, line 228
    228:     def tab_down(i = 1)
    229:       haml_buffer.tabulation -= i
    230:     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>

@param i [Fixnum] The number of tabs by which to increase the indentation @see tab_down

[Source]

         # File lib/haml/helpers.rb, line 219
    219:     def tab_up(i = 1)
    220:       haml_buffer.tabulation += i
    221:     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>

@param i [Fixnum] The number of tabs to use @yield A block in which the indentation will be `i` spaces

[Source]

         # File lib/haml/helpers.rb, line 251
    251:     def with_tabs(i)
    252:       old_tabs = haml_buffer.tabulation
    253:       haml_buffer.tabulation = i
    254:       yield
    255:     ensure
    256:       haml_buffer.tabulation = old_tabs
    257:     end

[Validate]