Module: Haml::Helpers

### Home Classes Methods

### In Files

- lib/haml/helpers/action_view_extensions.rb
- lib/haml/helpers/xss_mods.rb
- lib/haml/helpers.rb
- lib/haml/template.rb

### Namespace

- MODULE Haml::Helpers::ActionViewExtensions
- MODULE Haml::Helpers::XssMods
- CLASS Haml::Helpers::ErrorReturn

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

- Haml::Helpers::ActionViewExtensions
- Haml::Helpers::XssMods

### Class/Module Index

Quicksearch

- Haml
- Haml::Buffer
- Haml::Compiler
- Haml::Engine
- Haml::Error
- Haml::ErubisTemplateHandler
- Haml::Exec
- Haml::Exec::Generic
- Haml::Exec::Haml
- Haml::Filters
- Haml::Filters::Base
- Haml::Filters::Cdata
- Haml::Filters::Css
- Haml::Filters::Erb
- Haml::Filters::Escaped
- Haml::Filters::Javascript
- Haml::Filters::Plain
- Haml::Filters::PrecompiledTiltFilter
- Haml::Filters::Preserve
- Haml::Filters::Ruby
- Haml::Filters::SassRailsTemplate
- Haml::Filters::ScssRailsTemplate
- Haml::Filters::TiltFilter
- Haml::Helpers
- Haml::Helpers::ActionViewExtensions
- Haml::Helpers::ErrorReturn
- Haml::Helpers::XssMods
- Haml::Options
- Haml::Parser
- Haml::Parser::Line
- Haml::Parser::ParseNode
- Haml::Plugin
- Haml::Railtie
- Haml::SafeErubisTemplate
- Haml::SyntaxError
- Haml::Template
- Haml::Util
- Haml::Util::StaticConditionalContext
- ActionView
- ActionView::Base
- ActionView::Helpers
- ActionView::Helpers::CaptureHelper
- ActionView::Helpers::FormHelper
- ActionView::Helpers::FormTagHelper
- ActionView::Helpers::HamlSupport
- ActionView::Helpers::InstanceTag
- ActionView::Helpers::TagHelper
- ActionView::Helpers::Tags
- ActionView::Helpers::Tags::TextArea
- ActionView::Helpers::TextHelper
- Object

No matching classes.

# Haml::Helpers

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.

### Constants

HTML_ESCAPE

  Characters that need to be escaped to HTML entities from user input

HTML_ESCAPE_ONCE_REGEX
HTML_ESCAPE_REGEX

### Public Class Methods

action_view?() click to toggle source

@return [Boolean] Whether or not ActionView is loaded

    # File lib/haml/helpers.rb, line 52
    def self.action_view?
      @@action_view_defined
    end

### Public Instance Methods

block_is_haml?(block) click to toggle source

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

    # File lib/haml/helpers.rb, line 593
    def block_is_haml?(block)
      eval('!!defined?(_hamlout)', block.binding)
    end

capture_haml(*args, &block) click to toggle source

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`

    # File lib/haml/helpers.rb, line 362
    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
        block.call(*args)

        captured = haml_buffer.buffer.slice!(position..-1)
        return captured if haml_buffer.options[:ugly]
        # Note that the "reject" is needed for rbx 1.2.4, which includes empty
        # strings in the returned array when splitting by /^/.
        captured = captured.split(/^/).reject {|x| x == ""}

        min_tabs = nil
        captured.each do |line|
          tabs = line.index(/[^ ]/) || line.length
          min_tabs ||= tabs
          min_tabs = min_tabs > tabs ? tabs : min_tabs
        end

        captured.map do |line|
          line.slice(min_tabs, line.length)
        end.join
      end
    ensure
      haml_buffer.capture_position = nil
    end

escape_once(text) click to toggle source

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

    # File lib/haml/helpers.rb, line 565
    def escape_once(text)
      text = text.to_s
      text.gsub!(HTML_ESCAPE_ONCE_REGEX, HTML_ESCAPE)
      text
    end

find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block) click to toggle source

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)

    Escapes newlines within a string.

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

@overload find_and_preserve(tags = haml_buffer.options)

    Escapes newlines within a block of Haml code.

    @yield The block within which to escape newlines

    # File lib/haml/helpers.rb, line 107
    def find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block)
      return find_and_preserve(capture_haml(&block), input || tags) if block
      re = /<(#{tags.map(&Regexp.method(:escape)).join('|')})([^>]*)>(.*?)(<\/\11>>)/m
      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

flatten(input = nil, &block) click to toggle source
Alias for: preserve
haml_concat(text = "") click to toggle source

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

@param text [to_s] The text to output

    # File lib/haml/helpers.rb, line 394
    def haml_concat(text = "")
      unless haml_buffer.options[:ugly] || haml_indent == 0
        haml_buffer.buffer << haml_indent <<
          text.to_s.gsub("\n", "\n" + haml_indent) << "\n"
      else
        haml_buffer.buffer << text.to_s << "\n"
      end
      ErrorReturn.new("haml_concat")
    end

haml_indent() click to toggle source

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

    # File lib/haml/helpers.rb, line 405
    def haml_indent
      '  ' * haml_buffer.tabulation
    end

haml_tag(name, *rest, &block) click to toggle source

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

@overload haml_tag(name, *rest, 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
    @param flags [Array<Symbol>] Haml end-of-tag flags

    # File lib/haml/helpers.rb, line 466
    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::Compiler.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_concat "<#{name}#{attributes} />"
        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}>"
      if block.nil?
        text = text.to_s
        if text.include?("\n")
          haml_concat tag
          tab_up
          haml_concat text
          tab_down
          haml_concat "</#{name}>"
        else
          tag << text << "</#{name}>"
          haml_concat tag
        end
        return ret
      end

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

      if flags.include?(:<)
        tag << capture_haml(&block).strip << "</#{name}>"
        haml_concat tag
        return ret
      end

      haml_concat tag
      tab_up
      block.call
      tab_down
      haml_concat "</#{name}>"

      ret
    end

html_attrs(lang = 'en-US') click to toggle source

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

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

html_escape(text) click to toggle source

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

    # File lib/haml/helpers.rb, line 544
    def html_escape(text)
      text = text.to_s
      text.gsub(HTML_ESCAPE_REGEX, HTML_ESCAPE)
    end

init_haml_helpers() click to toggle source

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"

    # File lib/haml/helpers.rb, line 72
    def init_haml_helpers
      @haml_buffer = Haml::Buffer.new(haml_buffer, Options.new.for_buffer)
      nil
    end

is_haml?() click to toggle source

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

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

list_of(enum, opts={}, &block) click to toggle source

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)

@param enum [Enumerable] The list of objects to iterate over @param [Enumerable<to_s,to_s>] opts Each key/value pair will become an attribute pair for each list item element. @yield [item] A block which contains Haml code that goes within list items @yieldparam item An element of `enum`

    # File lib/haml/helpers.rb, line 192
    def list_of(enum, opts={}, &block)
      opts_attributes = opts.empty? ? "" : " ".<<(opts.map{|k,v| "#{k}='#{v}'" }.join(" "))
      to_return = enum.collect do |i|
        result = capture_haml(i, &block)

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

        %<li#{opts_attributes}>#{result}</li>!
      end
      to_return.join("\n")
    end

non_haml() click to toggle source

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

    # File lib/haml/helpers.rb, line 86
    def non_haml
      was_active = @haml_buffer.active?
      @haml_buffer.active = false
      yield
    ensure
      @haml_buffer.active = was_active
    end

precede(str, &block) click to toggle source

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

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

preserve(input = nil, &block) click to toggle source

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

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

Also aliased as: flatten
succeed(str, &block) click to toggle source

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

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

surround(front, back = front, &block) click to toggle source

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

    # File lib/haml/helpers.rb, line 306
    def surround(front, back = front, &block)
      output = capture_haml(&block)

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

tab_down(i = 1) click to toggle source

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

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

tab_up(i = 1) click to toggle source

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

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

with_tabs(i) click to toggle source

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

    # File lib/haml/helpers.rb, line 275
    def with_tabs(i)
      old_tabs = haml_buffer.tabulation
      haml_buffer.tabulation = i
      yield
    ensure
      haml_buffer.tabulation = old_tabs
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.