Module: Haml::Helpers
- Extended by:
- Helpers
- Includes:
- ActionViewExtensions, XssMods
- Included in:
- Buffer, Helpers
- Defined in:
- lib/haml/helpers.rb,
lib/haml/template.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
Class Method Summary (collapse)
-
+ (Boolean) action_view?
Whether or not ActionView is loaded.
Instance Method Summary (collapse)
-
- (Boolean) block_is_haml?(block)
Returns whether or not
block
is defined directly in a Haml template. -
- capture_haml(*args) {|args| ... }
Captures the result of a block of Haml code, gets rid of the excess indentation, and returns it as a string.
-
- (String) escape_once(text)
Escapes HTML entities in
text
, but without escaping an ampersand that is already part of an escaped entity. -
- find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block)
Uses #preserve to convert any newlines inside whitespace-sensitive tags into the HTML entities for endlines.
-
- haml_concat(text = "")
Outputs text directly to the Haml buffer, with the proper indentation.
-
- (String) haml_indent
The indentation string for the current line.
-
- haml_tag(name, *rest, &block)
Creates an HTML tag with the given name and optionally text and attributes.
-
- ({#to_s => String}) html_attrs(lang = 'en-US')
Returns a hash containing default assignments for the
xmlns
,lang
, andxml:lang
attributes of thehtml
HTML element. -
- (String) html_escape(text)
Returns a copy of
text
with ampersands, angle brackets and quotes escaped into HTML entities. -
- init_haml_helpers
Note: this does not need to be called when using Haml helpers normally in Rails.
-
- (Boolean) is_haml?
Returns whether or not the current template is a Haml template.
-
- list_of(enum, opts = {}) {|item| ... }
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. -
- non_haml { ... }
Runs a block of code in a non-Haml context (i.e. #is_haml? will return false).
-
- precede(str) { ... }
Prepends a string to the beginning of a Haml block, with no whitespace between.
-
- preserve(input = nil, &block)
(also: #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.
-
- succeed(str) { ... }
Appends a string to the end of a Haml block, with no whitespace between.
-
- surround(front, back = front) { ... }
Surrounds a block of Haml code with strings, with no whitespace in between.
-
- tab_down(i = 1)
Decrements the number of tabs the buffer automatically adds to the lines of the template.
-
- tab_up(i = 1)
Increments the number of tabs the buffer automatically adds to the lines of the template.
-
- with_tabs(i) { ... }
Sets the number of tabs the buffer automatically adds to the lines of the template, but only for the duration of the block.
Methods included from ActionViewExtensions
#page_class, #with_raw_haml_concat
Class Method Details
+ (Boolean) action_view?
Whether or not ActionView is loaded
52 53 54 |
# File 'lib/haml/helpers.rb', line 52
def self.action_view?
@@action_view_defined
end
|
Instance Method Details
- (Boolean) block_is_haml?(block)
Returns whether or not block
is defined directly in a Haml template.
593 594 595 |
# File 'lib/haml/helpers.rb', line 593
def block_is_haml?(block)
eval('!!defined?(_hamlout)', block.binding)
end
|
- capture_haml(*args) {|args| ... }
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"
.
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 |
# File 'lib/haml/helpers.rb', line 362
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
block.call(*args)
captured = haml_buffer.buffer.slice!(position..-1)
return captured if haml_buffer.options[:ugly]
# Note that the "reject" is needed for rbx 1.2.4, which includes empty
# strings in the returned array when splitting by /^/.
captured = captured.split(/^/).reject {|x| x == ""}
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.slice(min_tabs, line.length)
end.join
end
ensure
haml_buffer.capture_position = nil
end
|
- (String) escape_once(text)
Escapes HTML entities in text
, but without escaping an ampersand that is already part of an escaped entity.
565 566 567 568 569 |
# File 'lib/haml/helpers.rb', line 565
def escape_once(text)
text = text.to_s
text.gsub!(HTML_ESCAPE_ONCE_REGEX, HTML_ESCAPE)
text
end
|
- find_and_preserve(input, tags = haml_buffer.options[:preserve]) - find_and_preserve(tags = haml_buffer.options[:preserve]) { ... }
Uses #preserve to convert any newlines inside whitespace-sensitive tags into the HTML entities for endlines.
107 108 109 110 111 112 113 114 |
# File 'lib/haml/helpers.rb', line 107
def find_and_preserve(input = nil, tags = haml_buffer.options[:preserve], &block)
return find_and_preserve(capture_haml(&block), input || tags) if block
re = /<(#{tags.map(&Regexp.method(:escape)).join('|')})([^>]*)>(.*?)(<\/\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 = "")
Outputs text directly to the Haml buffer, with the proper indentation.
394 395 396 397 398 399 400 401 402 |
# File 'lib/haml/helpers.rb', line 394
def haml_concat(text = "")
unless haml_buffer.options[:ugly] || haml_indent == 0
haml_buffer.buffer << haml_indent <<
text.to_s.gsub("\n", "\n" + haml_indent) << "\n"
else
haml_buffer.buffer << text.to_s << "\n"
end
ErrorReturn.new("haml_concat")
end
|
- (String) haml_indent
The indentation string for the current line
405 406 407 |
# File 'lib/haml/helpers.rb', line 405
def haml_indent
' ' * haml_buffer.tabulation
end
|
- haml_tag(name, *rest, attributes = {}) { ... } - haml_tag(name, text, *flags, attributes = {})
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>
466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 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 |
# File 'lib/haml/helpers.rb', line 466
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 = Haml::Compiler.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_concat "<#{name}#{attributes} />"
return ret
end
if flags.include?(:/)
raise Error.new(Error.message(:self_closing_content)) if text
raise Error.new(Error.message(:illegal_nesting_self_closing)) if block
end
tag = "<#{name}#{attributes}>"
if block.nil?
text = text.to_s
if text.include?("\n")
haml_concat tag
tab_up
haml_concat text
tab_down
haml_concat "</#{name}>"
else
tag << text << "</#{name}>"
haml_concat tag
end
return ret
end
if text
raise Error.new(Error.message(:illegal_nesting_line, name))
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
|
- ({#to_s => String}) html_attrs(lang = 'en-US')
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'>
221 222 223 |
# File 'lib/haml/helpers.rb', line 221
def html_attrs(lang = 'en-US')
{:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang}
end
|
- (String) html_escape(text)
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”.
544 545 546 547 |
# File 'lib/haml/helpers.rb', line 544
def html_escape(text)
text = text.to_s
text.gsub(HTML_ESCAPE_REGEX, HTML_ESCAPE)
end
|
- init_haml_helpers
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"
72 73 74 75 |
# File 'lib/haml/helpers.rb', line 72
def init_haml_helpers
@haml_buffer = Haml::Buffer.new(haml_buffer, Options.new.for_buffer)
nil
end
|
- (Boolean) is_haml?
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.
585 586 587 |
# File 'lib/haml/helpers.rb', line 585
def is_haml?
!@haml_buffer.nil? && @haml_buffer.active?
end
|
- list_of(enum, opts = {}) {|item| ... }
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)
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 |
# File 'lib/haml/helpers.rb', line 192
def list_of(enum, opts={}, &block)
opts_attributes = opts.empty? ? "" : " ".<<(opts.map{|k,v| "#{k}='#{v}'" }.join(" "))
to_return = enum.collect do |i|
result = capture_haml(i, &block)
if result.count("\n") > 1
result = result.gsub("\n", "\n ")
result = "\n #{result.strip}\n"
else
result = result.strip
end
%Q!<li#{opts_attributes}>#{result}</li>!
end
to_return.join("\n")
end
|
- non_haml { ... }
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.
86 87 88 89 90 91 92 |
# File 'lib/haml/helpers.rb', line 86
def non_haml
was_active = @haml_buffer.active?
@haml_buffer.active = false
yield
ensure
@haml_buffer.active = was_active
end
|
- precede(str) { ... }
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>
325 326 327 |
# File 'lib/haml/helpers.rb', line 325
def precede(str, &block)
"#{str}#{capture_haml(&block).chomp}\n"
end
|
- perserve(input) - perserve { ... } 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.
128 129 130 131 |
# File 'lib/haml/helpers.rb', line 128
def preserve(input = nil, &block)
return preserve(capture_haml(&block)) if block
input.to_s.chomp("\n").gsub(/\n/, '
').gsub(/\r/, '')
end
|
- succeed(str) { ... }
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>.
344 345 346 |
# File 'lib/haml/helpers.rb', line 344
def succeed(str, &block)
"#{capture_haml(&block).chomp}#{str}\n"
end
|
- surround(front, back = front) { ... }
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>*
306 307 308 309 310 |
# File 'lib/haml/helpers.rb', line 306
def surround(front, back = front, &block)
output = capture_haml(&block)
"#{front}#{output.chomp}#{back}\n"
end
|
- tab_down(i = 1)
Decrements the number of tabs the buffer automatically adds to the lines of the template.
252 253 254 |
# File 'lib/haml/helpers.rb', line 252
def tab_down(i = 1)
haml_buffer.tabulation -= i
end
|
- tab_up(i = 1)
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>
243 244 245 |
# File 'lib/haml/helpers.rb', line 243
def tab_up(i = 1)
haml_buffer.tabulation += i
end
|
- with_tabs(i) { ... }
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>
275 276 277 278 279 280 281 |
# File 'lib/haml/helpers.rb', line 275
def with_tabs(i)
old_tabs = haml_buffer.tabulation
haml_buffer.tabulation = i
yield
ensure
haml_buffer.tabulation = old_tabs
end
|