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

Included Modules

ActionViewExtensions

Classes and Modules

Module Haml::Helpers::ActionViewExtensions
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

@return [Boolean] Whether or not ActionView is loaded

[Source]

    # File lib/haml/helpers.rb, line 40
40:     def self.action_view?
41:       @@action_view_defined
42:     end

Public Instance methods

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 490
490:     def block_is_haml?(block)
491:       eval('_hamlout', block.binding)
492:       true
493:     rescue
494:       false
495:     end

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 300
300:     def capture_haml(*args, &block)
301:       buffer = eval('_hamlout', block.binding) rescue haml_buffer
302:       with_haml_buffer(buffer) do
303:         position = haml_buffer.buffer.length
304: 
305:         haml_buffer.capture_position = position
306:         block.call(*args)
307: 
308:         captured = haml_buffer.buffer.slice!(position..-1).split(/^/)
309: 
310:         min_tabs = nil
311:         captured.each do |line|
312:           tabs = line.index(/[^ ]/) || line.length
313:           min_tabs ||= tabs
314:           min_tabs = min_tabs > tabs ? tabs : min_tabs
315:         end
316: 
317:         captured.map do |line|
318:           line[min_tabs..-1]
319:         end.join
320:       end
321:     ensure
322:       haml_buffer.capture_position = nil
323:     end

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 471
471:     def escape_once(text)
472:       text.to_s.gsub(/[\"><]|&(?!([a-zA-Z]+|(#\d+));)/) { |s| HTML_ESCAPE[s] }
473:     end

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 95
 95:     def find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block)
 96:       return find_and_preserve(capture_haml(&block), input || tags) if block
 97: 
 98:       input = input.to_s
 99:       input.gsub(/<(#{tags.map(&Regexp.method(:escape)).join('|')})([^>]*)>(.*?)(<\/\1>)/im) do
100:         "<#{$1}#{$2}>#{preserve($3)}</#{$1}>"
101:       end
102:     end
flatten(input = '', &block)

Alias for preserve

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 340
340:     def haml_concat(text = "")
341:       haml_buffer.buffer << haml_indent << text.to_s << "\n"
342:       nil
343:     end

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

[Source]

     # File lib/haml/helpers.rb, line 346
346:     def haml_indent
347:       '  ' * haml_buffer.tabulation
348:     end

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.

`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, {: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>

@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 402
402:     def haml_tag(name, *rest, &block)
403:       ret = ErrorReturn.new("haml_tag outputs directly to the Haml template.\nDisregard its return value and use the - operator,\nor use capture_haml to get the value as a String.\n")
404: 
405:       name = name.to_s
406:       text = rest.shift.to_s unless [Symbol, Hash, NilClass].any? {|t| rest.first.is_a? t}
407:       flags = []
408:       flags << rest.shift while rest.first.is_a? Symbol
409:       attributes = Haml::Precompiler.build_attributes(haml_buffer.html?,
410:                                                       haml_buffer.options[:attr_wrapper],
411:                                                       rest.shift || {})
412: 
413:       if text.nil? && block.nil? && (haml_buffer.options[:autoclose].include?(name) || flags.include?(:/))
414:         haml_concat "<#{name}#{attributes} />"
415:         return ret
416:       end
417: 
418:       if flags.include?(:/)
419:         raise Error.new("Self-closing tags can't have content.") if text
420:         raise Error.new("Illegal nesting: nesting within a self-closing tag is illegal.") if block
421:       end
422: 
423:       tag = "<#{name}#{attributes}>"
424:       if block.nil?
425:         tag << text.to_s << "</#{name}>"
426:         haml_concat tag
427:         return ret
428:       end
429: 
430:       if text
431:         raise Error.new("Illegal nesting: content can't be both given to haml_tag :#{name} and nested within it.")
432:       end
433: 
434:       if flags.include?(:<)
435:         tag << capture_haml(&block).strip << "</#{name}>"
436:         haml_concat tag
437:         return ret
438:       end
439: 
440:       haml_concat tag
441:       tab_up
442:       block.call
443:       tab_down
444:       haml_concat "</#{name}>"
445: 
446:       ret
447:     end

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 [Hash<to_s, String>] The attribute hash

[Source]

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

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

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

[Source]

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

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 60
60:     def init_haml_helpers
61:       @haml_buffer = Haml::Buffer.new(@haml_buffer, Haml::Engine.new('').send(:options_for_buffer))
62:       nil
63:     end

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 482
482:     def is_haml?
483:       !@haml_buffer.nil? && @haml_buffer.active?
484:     end

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 158
158:     def list_of(enum, &block)
159:       to_return = enum.collect do |i|
160:         result = capture_haml(i, &block)
161: 
162:         if result.count("\n") > 1
163:           result.gsub!("\n", "\n  ")
164:           result = "\n  #{result.strip}\n"
165:         else
166:           result.strip!
167:         end
168: 
169:         "<li>#{result}</li>"
170:       end
171:       to_return.join("\n")
172:     end

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 74
74:     def non_haml
75:       was_active = @haml_buffer.active?
76:       @haml_buffer.active = false
77:       yield
78:     ensure
79:       @haml_buffer.active = was_active
80:     end

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 263
263:     def precede(str, &block)
264:       "#{str}#{capture_haml(&block).chomp}\n"
265:     end

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 116
116:     def preserve(input = '', &block)
117:       return preserve(capture_haml(&block)) if block
118: 
119:       input.chomp("\n").gsub(/\n/, '&#x000A;').gsub(/\r/, '')
120:     end

@deprecated This will be removed in version 2.4. @see \{haml_concat}

[Source]

     # File lib/haml/helpers.rb, line 327
327:     def puts(*args)
328:       warn "DEPRECATION WARNING:\nThe Haml #puts helper is deprecated and will be removed in version 2.4.\nUse the #haml_concat helper instead.\n"
329:       haml_concat(*args)
330:     end

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 282
282:     def succeed(str, &block)
283:       "#{capture_haml(&block).chomp}#{str}\n"
284:     end

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 244
244:     def surround(front, back = front, &block)
245:       output = capture_haml(&block)
246: 
247:       "#{front}#{output.chomp}#{back}\n"
248:     end

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 217
217:     def tab_down(i = 1)
218:       haml_buffer.tabulation -= i
219:     end

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 208
208:     def tab_up(i = 1)
209:       haml_buffer.tabulation += i
210:     end

[Validate]