Module: Haml::Helpers

Extended by:
Helpers
Includes:
ActionViewExtensions
Included in:
Buffer, Helpers
Defined in:
lib/haml/helpers.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

Constant Summary collapse

HTML_ESCAPE =

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

{ '&'=>'&amp;', '<'=>'&lt;', '>'=>'&gt;', '"'=>'&quot;', "'"=>'&#039;', }
@@action_view_defined = 
defined?(ActionView)
@@force_no_action_view = 
false

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ActionViewExtensions

#page_class

Class Method Details

.action_view? ⇒ Boolean

Returns Whether or not ActionView is loaded.

Returns:

  • (Boolean) —

    Whether or not ActionView is loaded



40
41
42
 
# File 'lib/haml/helpers.rb', line 40

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



488
489
490
491
492
493
 
# File 'lib/haml/helpers.rb', line 488

def block_is_haml?(block)
  eval('_hamlout', block.binding)
  true
rescue
  false
end

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

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`



300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/haml/helpers.rb', line 300

def capture_haml(*args, &block)
  buffer = eval('_hamlout', block.binding) rescue 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).split(/^/)

    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[min_tabs..-1]
    end.join
  end
ensure
  haml_buffer.capture_position = nil
end

#escape_once(text) ⇒ String

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



469
470
471
 
# File 'lib/haml/helpers.rb', line 469

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

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

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]) ⇒ Object

    Escapes newlines within a string.

    Parameters:

    • input (String) —

      The string within which to escape newlines

  • #find_and_preserve(tags = haml_buffer.options[:preserve]) { ... } ⇒ Object

    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



95
96
97
98
99
100
101
102
 
# File 'lib/haml/helpers.rb', line 95

def find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block)
  return find_and_preserve(capture_haml(&block), input || tags) if block

  input = input.to_s
  input.gsub(/<(#{tags.map(&Regexp.method(:escape)).join('|')})([^>]*)>(.*?)(<\/\1>)/im) do
    "<#{$1}#{$2}>#{preserve($3)}</#{$1}>"
  end
end

#haml_concat(text = "") ⇒ Object

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

Parameters:

  • text (#to_s) (defaults to: "") —

    The text to output



339
340
341
342
 
# File 'lib/haml/helpers.rb', line 339

def haml_concat(text = "")
  haml_buffer.buffer << haml_indent << text.to_s << "\n"
  nil
end

#haml_indent ⇒ String

Returns The indentation string for the current line.

Returns:

  • (String) —

    The indentation string for the current line



345
346
347
 
# File 'lib/haml/helpers.rb', line 345

def haml_indent
  '  ' * haml_buffer.tabulation
end

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

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>

Overloads:

  • #haml_tag(name, *flags, attributes = {}) { ... } ⇒ Object

    Yields:

    • The block of Haml code within the tag

  • #haml_tag(name, text, *flags, attributes = {}) ⇒ Object

    Parameters:

    • text (#to_s) —

      The text within the tag

Parameters:

  • name (#to_s) —

    The name of the tag

  • flags (Array<Symbol>) —

    Haml end-of-tag flags



401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/haml/helpers.rb', line 401

def haml_tag(name, *rest, &block)
  ret = ErrorReturn.new(<<MESSAGE)
haml_tag outputs directly to the Haml template.
Disregard its return value and use the - operator,
or use capture_haml to get the value as a String.
MESSAGE

  name = name.to_s
  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
  attributes = Haml::Precompiler.build_attributes(haml_buffer.html?,
                                                  haml_buffer.options[:attr_wrapper],
                                                  rest.shift || {})

  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("Self-closing tags can't have content.") if text
    raise Error.new("Illegal nesting: nesting within a self-closing tag is illegal.") if block
  end

  tag = "<#{name}#{attributes}>"
  if block.nil?
    tag << text.to_s << "</#{name}>"
    haml_concat tag
    return ret
  end

  if text
    raise Error.new("Illegal nesting: content can't be both given to haml_tag :#{name} and nested within it.")
  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') ⇒ Hash<#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:

  • (Hash<#to_s, String>) —

    The attribute hash



186
187
188
 
# File 'lib/haml/helpers.rb', line 186

def html_attrs(lang = 'en-US')
  {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
end

#html_escape(text) ⇒ String

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

Parameters:

  • text (String) —

    The string to sanitize

Returns:

  • (String) —

    The sanitized string



460
461
462
 
# File 'lib/haml/helpers.rb', line 460

def html_escape(text)
  text.to_s.gsub(/[\"><&]/) { |s| HTML_ESCAPE[s] }
end

#init_haml_helpers ⇒ Object

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"



60
61
62
63
 
# File 'lib/haml/helpers.rb', line 60

def init_haml_helpers
  @haml_buffer = Haml::Buffer.new(@haml_buffer, Haml::Engine.new('').send(:options_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



480
481
482
 
# File 'lib/haml/helpers.rb', line 480

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

#list_of(enum) {|item| ... } ⇒ Object

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>

Parameters:

  • enum (Enumerable) —

    The list of objects to iterate over

Yields:

  • (item) —

    A block which contains Haml code that goes within list items

Yield Parameters:

  • item —

    An element of ‘enum`



158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/haml/helpers.rb', line 158

def list_of(enum, &block)
  to_return = enum.collect 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

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

#non_haml { ... } ⇒ Object

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



74
75
76
77
78
79
80
 
# File 'lib/haml/helpers.rb', line 74

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

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

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



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

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

#perserve(input) ⇒ Object #perserve { ... } ⇒ Object 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:

  • #perserve(input) ⇒ Object

    Escapes newlines within a string.

    Parameters:

    • input (String) —

      The string within which to escape all newlines

  • #perserve { ... } ⇒ Object

    Escapes newlines within a block of Haml code.

    Yields:

    • The block within which to escape newlines



116
117
118
119
120
 
# File 'lib/haml/helpers.rb', line 116

def preserve(input = '', &block)
  return preserve(capture_haml(&block)) if block

  input.chomp("\n").gsub(/\n/, '&#x000A;').gsub(/\r/, '')
end

#puts(*args) ⇒ Object

Deprecated.

This will be removed in version 2.4.

See Also:

  • Haml::Helpers.\{\{#haml\_concat}


327
328
329
330
331
332
333
334
 
# File 'lib/haml/helpers.rb', line 327

def puts(*args)
  warn <<END
DEPRECATION WARNING:
The Haml #puts helper is deprecated and will be removed in version 2.4.
Use the #haml_concat helper instead.
END
  haml_concat(*args)
end

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

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



282
283
284
 
# File 'lib/haml/helpers.rb', line 282

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

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

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



244
245
246
247
248
 
# File 'lib/haml/helpers.rb', line 244

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

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

#tab_down(i = 1) ⇒ Object

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:



217
218
219
 
# File 'lib/haml/helpers.rb', line 217

def tab_down(i = 1)
  haml_buffer.tabulation -= i
end

#tab_up(i = 1) ⇒ Object

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:



208
209
210
 
# File 'lib/haml/helpers.rb', line 208

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