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`, and `xml:lang` attributes of the `html` 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, = haml_buffer.[:preserve], &block) return find_and_preserve(capture_haml(&block), input || ) if block input = input.to_s input.gsub(/<(#{.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.[:attr_wrapper], rest.shift || {}) if text.nil? && block.nil? && (haml_buffer.[: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 |