| 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.
| HTML_ESCAPE | = | { '&'=>'&', '<'=>'<', '>'=>'>', '"'=>'"', "'"=>''', } | Characters that need to be escaped to HTML entities from user input |
Returns whether or not ActionView is installed on the system.
# File lib/haml/helpers.rb, line 16
16: def self.action_view?
17: @@action_view_defined
18: end
Captures the result of the given 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".
# File lib/haml/helpers.rb, line 256
256: def capture_haml(*args, &block)
257: buffer = eval('_hamlout', block.binding) rescue haml_buffer
258: with_haml_buffer(buffer) do
259: position = haml_buffer.buffer.length
260:
261: block.call(*args)
262:
263: captured = haml_buffer.buffer.slice!(position..-1).split(/^/)
264:
265: min_tabs = nil
266: captured.each do |line|
267: tabs = line.index(/[^ ]/) || line.length
268: min_tabs ||= tabs
269: min_tabs = min_tabs > tabs ? tabs : min_tabs
270: end
271:
272: captured.map do |line|
273: line[min_tabs..-1]
274: end.join
275: end
276: end
Uses preserve to convert any newlines inside whitespace-sensitive tags into the HTML entities for endlines. @tags@ is an array of tags to preserve. It defaults to the value of the :preserve option.
# File lib/haml/helpers.rb, line 70
70: def find_and_preserve(input = '', tags = haml_buffer.options[:preserve], &block)
71: return find_and_preserve(capture_haml(&block)) if block
72:
73: input = input.to_s
74: input.gsub(/<(#{tags.map(&Regexp.method(:escape)).join('|')})([^>]*)>(.*?)(<\/\1>)/im) do
75: "<#{$1}#{$2}>#{preserve($3)}</#{$1}>"
76: end
77: end
Returns the string that should be used to indent the current line
# File lib/haml/helpers.rb, line 295
295: def haml_indent
296: ' ' * haml_buffer.tabulation
297: end
Creates an HTML tag with the given name and optionally text and attributes. Can take a block that will be executed between when the opening and closing tags are output. 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.
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>
# File lib/haml/helpers.rb, line 345
345: def haml_tag(name, *rest, &block)
346: name = name.to_s
347: text = rest.shift.to_s unless [Symbol, Hash, NilClass].any? {|t| rest.first.is_a? t}
348: flags = []
349: flags << rest.shift while rest.first.is_a? Symbol
350: attributes = Haml::Precompiler.build_attributes(haml_buffer.html?,
351: haml_buffer.options[:attr_wrapper],
352: rest.shift || {})
353:
354: if text.nil? && block.nil? && (haml_buffer.options[:autoclose].include?(name) || flags.include?(:/))
355: haml_concat "<#{name}#{attributes} />"
356: return nil
357: end
358:
359: if flags.include?(:/)
360: raise Error.new("Self-closing tags can't have content.") if text
361: raise Error.new("Illegal nesting: nesting within a self-closing tag is illegal.") if block
362: end
363:
364: tag = "<#{name}#{attributes}>"
365: if block.nil?
366: tag << text.to_s << "</#{name}>"
367: haml_concat tag
368: return
369: end
370:
371: if text
372: raise Error.new("Illegal nesting: content can't be both given to haml_tag :#{name} and nested within it.")
373: end
374:
375: if flags.include?(:<)
376: tag << capture_haml(&block).strip << "</#{name}>"
377: haml_concat tag
378: return
379: end
380:
381: haml_concat tag
382: tab_up
383: block.call
384: tab_down
385: haml_concat "</#{name}>"
386: nil
387: end
Returns a hash containing default assignments for the xmlns and xml:lang attributes of the html HTML element. It also takes an optional argument for the value of xml:lang and lang, which defaults to ‘en-US’. For example,
%html{html_attrs}
becomes
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en-US' lang='en-US'>
# File lib/haml/helpers.rb, line 154
154: def html_attrs(lang = 'en-US')
155: {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
156: 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 rendering 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 39
39: def init_haml_helpers
40: @haml_buffer = Haml::Buffer.new(@haml_buffer, Haml::Engine.new('').send(:options_for_buffer))
41: nil
42: 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.
# File lib/haml/helpers.rb, line 409
409: def is_haml?
410: !@haml_buffer.nil? && @haml_buffer.active?
411: end
Takes an Enumerable object and a block and iterates over the object, 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>
# File lib/haml/helpers.rb, line 126
126: def list_of(array, &block) # :yields: item
127: to_return = array.collect do |i|
128: result = capture_haml(i, &block)
129:
130: if result.count("\n") > 1
131: result.gsub!("\n", "\n ")
132: result = "\n #{result.strip}\n"
133: else
134: result.strip!
135: end
136:
137: "<li>#{result}</li>"
138: end
139: to_return.join("\n")
140: 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.
# File lib/haml/helpers.rb, line 54
54: def non_haml
55: was_active = @haml_buffer.active?
56: @haml_buffer.active = false
57: yield
58: ensure
59: @haml_buffer.active = was_active
60: end
Prepends the given character to the beginning of the Haml block, with no whitespace between. For example:
= precede '*' do
%span.small Not really
Produces:
*<span class='small'>Not really</span>
# File lib/haml/helpers.rb, line 224
224: def precede(char, &block)
225: "#{char}#{capture_haml(&block).chomp}\n"
226: end
Takes any string, finds all the endlines and converts them to HTML entities for endlines so they‘ll render correctly in whitespace-sensitive tags without screwing up the indentation.
# File lib/haml/helpers.rb, line 86
86: def preserve(input = '', &block)
87: return preserve(capture_haml(&block)) if block
88:
89: input.chomp("\n").gsub(/\n/, '
').gsub(/\r/, '')
90: end
Appends the given character to the end of the Haml block, with no whitespace between. For example:
click
= succeed '.' do
%a{:href=>"thing"} here
Produces:
click <a href='thing'>here</a>.
# File lib/haml/helpers.rb, line 241
241: def succeed(char, &block)
242: "#{capture_haml(&block).chomp}#{char}\n"
243: end
Surrounds the given block of Haml code with the given characters, 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>*
# File lib/haml/helpers.rb, line 206
206: def surround(front, back = nil, &block)
207: back ||= front
208: output = capture_haml(&block)
209:
210: "#{front}#{output.chomp}#{back}\n"
211: 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>
# File lib/haml/helpers.rb, line 174
174: def tab_up(i = 1)
175: haml_buffer.tabulation += i
176: end