Module: Haml::Helpers
- Extended by:
- Helpers
- Includes:
- ActionViewExtensions
- 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
{ '&'=>'&', '<'=>'<', '>'=>'>', '"'=>'"', "'"=>''', }
- @@action_view_defined =
defined?(ActionView)
- @@force_no_action_view =
false
Class Method Summary collapse
-
.action_view? ⇒ Boolean
Whether or not ActionView is loaded.
Instance Method Summary collapse
-
#block_is_haml?(block) ⇒ Boolean
Returns whether or not
block
is defined directly in a Haml template. -
#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.
-
#escape_once(text) ⇒ String
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) ⇒ Object
Uses #preserve to convert any newlines inside whitespace-sensitive tags into the HTML entities for endlines.
-
#haml_concat(text = "") ⇒ Object
Outputs text directly to the Haml buffer, with the proper indentation.
-
#haml_indent ⇒ String
The indentation string for the current line.
-
#haml_tag(name, *rest, &block) ⇒ Object
Creates an HTML tag with the given name and optionally text and attributes.
-
#html_attrs(lang = 'en-US') ⇒ Hash<#to_s, String>
Returns a hash containing default assignments for the
xmlns
,lang
, andxml:lang
attributes of thehtml
HTML element. -
#html_escape(text) ⇒ String
Returns a copy of
text
with ampersands, angle brackets and quotes escaped into HTML entities. -
#init_haml_helpers ⇒ Object
Note: this does not need to be called when using Haml helpers normally in Rails.
-
#is_haml? ⇒ Boolean
Returns whether or not the current template is a Haml template.
-
#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. -
#non_haml { ... } ⇒ Object
Runs a block of code in a non-Haml context (i.e. #is_haml? will return false).
-
#precede(str) { ... } ⇒ Object
Prepends a string to the beginning of a Haml block, with no whitespace between.
-
#preserve(input = '', &block) ⇒ Object
(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.
-
#puts(*args) ⇒ Object
deprecated
Deprecated.
This will be removed in version 2.4.
-
#succeed(str) { ... } ⇒ Object
Appends a string to the end of a Haml block, with no whitespace between.
-
#surround(front, back = front) { ... } ⇒ Object
Surrounds a block of Haml code with strings, with no whitespace in between.
-
#tab_down(i = 1) ⇒ Object
Decrements the number of tabs the buffer automatically adds to the lines of the template.
-
#tab_up(i = 1) ⇒ Object
Increments the number of tabs the buffer automatically adds to the lines of the template.
Methods included from ActionViewExtensions
Class Method Details
.action_view? ⇒ Boolean
Returns 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.
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"
.
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.
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.
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.
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.
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>
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'>
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.
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.
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>
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.
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>
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.
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/, '
').gsub(/\r/, '')
end
|
#puts(*args) ⇒ Object
This will be removed in version 2.4.
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>.
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>*
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.
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>
208 209 210 |
# File 'lib/haml/helpers.rb', line 208
def tab_up(i = 1)
haml_buffer.tabulation += i
end
|