Module: Hamlit::HamlHelpers

Extended by:
HamlHelpers
Includes:
XssMods
Included in:
HamlBuffer, HamlHelpers
Defined in:
lib/hamlit/rails_template.rb,
lib/hamlit/parser/haml_helpers.rb,
lib/hamlit/parser/haml_xss_mods.rb

Overview

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.

Defined Under Namespace

Modules: XssMods Classes: ErrorReturn

Constant Summary collapse

HTML_ESCAPE =

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

{ '&' => '&amp;', '<' => '&lt;', '>' => '&gt;', '"' => '&quot;', "'" => '&#039;' }
HTML_ESCAPE_REGEX = 
/[\"><&]/
HTML_ESCAPE_ONCE_REGEX = 
/[\"><]|&(?!(?:[a-zA-Z]+|#(?:\d+|[xX][0-9a-fA-F]+));)/
@@action_view_defined = 
false

Class Method Summary collapse

Instance Method Summary collapse

Methods included from XssMods

#capture_haml_with_haml_xss, #escape_once_with_haml_xss, #find_and_preserve_with_haml_xss, #haml_concat_with_haml_xss, #haml_indent_with_haml_xss, #html_escape_with_haml_xss, included, #list_of_with_haml_xss, #precede_with_haml_xss, #preserve_with_haml_xss, #succeed_with_haml_xss, #surround_with_haml_xss

Class Method Details

.action_view? ⇒ Boolean

Returns Whether or not ActionView is loaded.

Returns:

  • (Boolean) —

    Whether or not ActionView is loaded



58
59
60
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 58

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



648
649
650
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 648

def block_is_haml?(block)
  eval('!!defined?(_hamlout)', block.binding)
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`



379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 379

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

    return nil if captured.nil?
    return (haml_buffer.options[:ugly] ? captured : prettify(captured))
  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



628
629
630
631
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 628

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



113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 113

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.each_with_object('') do |t, s|
    s << '|' unless s.empty?
    s << Regexp.escape(t)
  end
  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 = "") ⇒ Object

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

Parameters:

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

    The text to output



403
404
405
406
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 403

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



434
435
436
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 434

def haml_indent
  '  ' * haml_buffer.tabulation
end

#haml_tag(name, *rest, 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.

‘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 = {}) { ... } ⇒ 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

    • flags (Array<Symbol>) —

      Haml end-of-tag flags

Parameters:

  • name (#to_s) —

    The name of the tag



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
551
552
553
554
555
556
557
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 495

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 = ::Hamlit::HamlCompiler.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 ::Hamlit::HamlError.new(::Hamlit::HamlError.message(:self_closing_content)) if text
    raise ::Hamlit::HamlError.new(::Hamlit::HamlError.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 ::Hamlit::HamlError.new(::Hamlit::HamlError.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) ⇒ Object

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)



593
594
595
596
597
598
599
600
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 593

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



234
235
236
237
238
239
240
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 234

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

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



616
617
618
619
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 616

def html_escape(text)
  text = text.to_s
  text.gsub(HTML_ESCAPE_REGEX, HTML_ESCAPE)
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"



78
79
80
81
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 78

def init_haml_helpers
  @haml_buffer = ::Hamlit::HamlBuffer.new(haml_buffer, ::Hamlit::HamlOptions.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



640
641
642
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 640

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

#list_of(enum, opts = {}) {|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>

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`



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 205

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

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

    ret << "\n" unless ret.empty?
    ret << %Q!<li#{opts_attributes}>#{result}</li>!
  end
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



92
93
94
95
96
97
98
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 92

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



342
343
344
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 342

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

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

  • #preserve(input) ⇒ Object

    Escapes newlines within a string.

    Parameters:

    • input (String) —

      The string within which to escape all newlines

  • #preserve { ... } ⇒ Object

    Escapes newlines within a block of Haml code.

    Yields:

    • The block within which to escape newlines



138
139
140
141
142
143
144
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 138

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) { ... } ⇒ 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



361
362
363
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 361

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



323
324
325
326
327
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 323

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:



269
270
271
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 269

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:



260
261
262
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 260

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

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

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



292
293
294
295
296
297
298
 
# File 'lib/hamlit/parser/haml_helpers.rb', line 292

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