| 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.
| HTML_ESCAPE | = | { '&'=>'&', '<'=>'<', '>'=>'>', '"'=>'"', "'"=>''', } | Characters that need to be escaped to HTML entities from user input |
@return [Boolean] Whether or not ActionView is loaded
# File lib/haml/helpers.rb, line 54
54: def self.action_view?
55: @@action_view_defined
56: end
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 539
539: def block_is_haml?(block)
540: eval('_hamlout', block.binding)
541: true
542: rescue
543: false
544: 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`
# 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
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 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
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
# 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
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 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
@return [String] The indentation string for the current line
# File lib/haml/helpers.rb, line 379
379: def haml_indent
380: ' ' * haml_buffer.tabulation
381: 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.
`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
# 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
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 197
197: def html_attrs(lang = 'en-US')
198: {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
199: end
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 509
509: def html_escape(text)
510: Haml::Util.silence_warnings {text.to_s.gsub(/[\"><&]/n) {|s| HTML_ESCAPE[s]}}
511: 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"
# 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
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 531
531: def is_haml?
532: !@haml_buffer.nil? && @haml_buffer.active?
533: 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`
# 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
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 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
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 301
301: def precede(str, &block)
302: "#{str}#{capture_haml(&block).chomp}\n"
303: 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
# 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/, '
').gsub(/\r/, '')
131: 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
# File lib/haml/helpers.rb, line 320
320: def succeed(str, &block)
321: "#{capture_haml(&block).chomp}#{str}\n"
322: 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
# 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
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 219
219: def tab_up(i = 1)
220: haml_buffer.tabulation += i
221: end
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 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