Module: Hamlit::HamlHelpers
- Extended by:
- HamlHelpers
- Includes:
- XssMods
- Included in:
- HamlBuffer, HamlHelpers
- Defined in:
- lib/hamlit/rails_template.rb,
lib/hamlit/parser/haml_helpers.rb,
lib/hamlit/parser/haml_helpers/xss_mods.rb
Overview
This module contains various helpful methods to make it easier to do various tasks. HamlHelpers 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: XssMods Classes: ErrorReturn
Constant Summary collapse
- HTML_ESCAPE =
Characters that need to be escaped to HTML entities from user input
{'&' => '&', '<' => '<', '>' => '>', '"' => '"', "'" => '''}.freeze
- HTML_ESCAPE_REGEX =
/['"><&]/
- HTML_ESCAPE_ONCE_REGEX =
/['"><]|&(?!(?:[a-zA-Z]+|#(?:\d+|[xX][0-9a-fA-F]+));)/
- @@action_view_defined =
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
(also: #escape_once_without_haml_xss)
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.
-
#haml_tag_if(condition, *tag) ⇒ Object
Conditionally wrap a block in an element.
-
#html_attrs(lang = 'en-US') ⇒ {#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
(also: #html_escape_without_haml_xss)
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, opts = {}) {|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 = nil, &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.
-
#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.
-
#with_tabs(i) { ... } ⇒ Object
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 XssMods
#capture_haml_with_haml_xss, #escape_once_with_haml_xss, #find_and_preserve_with_haml_xss, #haml_concat_with_haml_xss, #haml_indent_with_haml_xss, #html_escape_with_haml_xss, included, #list_of_with_haml_xss, #precede_with_haml_xss, #preserve_with_haml_xss, #succeed_with_haml_xss, #surround_with_haml_xss
Class Method Details
.action_view? ⇒ Boolean
Returns Whether or not ActionView is loaded.
56 57 58 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 56 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.
646 647 648 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 646 def block_is_haml?(block) eval('!!defined?(_hamlout)', block.binding) 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”`.
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 373 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 value = block.call(*args) captured = haml_buffer.buffer.slice!(position..-1) if captured == '' and value != haml_buffer.buffer captured = (value.is_a?(String) ? value : nil) end captured end ensure haml_buffer.capture_position = nil end |
#escape_once(text) ⇒ String Also known as: escape_once_without_haml_xss
Escapes HTML entities in ‘text`, but without escaping an ampersand that is already part of an escaped entity.
623 624 625 626 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 623 def escape_once(text) text = text.to_s text.gsub(HTML_ESCAPE_ONCE_REGEX, HTML_ESCAPE) 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.
111 112 113 114 115 116 117 118 119 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 111 def find_and_preserve(input = nil, = haml_buffer.[:preserve], &block) return find_and_preserve(capture_haml(&block), input || ) if block = .map { |tag| Regexp.escape(tag) }.join('|') re = /<(#{})([^>]*)>(.*?)(<\/\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 = "") ⇒ Object
Outputs text directly to the Haml buffer, with the proper indentation.
396 397 398 399 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 396 def haml_concat(text = "") haml_internal_concat text ErrorReturn.new("haml_concat") end |
#haml_indent ⇒ String
Returns The indentation string for the current line.
427 428 429 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 427 def haml_indent ' ' * haml_buffer.tabulation end |
#haml_tag(name, *rest, 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.
‘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>
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 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 488 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 = Hamlit::HamlAttributeBuilder.build_attributes(haml_buffer.html?, haml_buffer.[:attr_wrapper], haml_buffer.[:escape_attrs], haml_buffer.[:hyphenate_data_attrs], attrs) if text.nil? && block.nil? && (haml_buffer.[:autoclose].include?(name) || flags.include?(:/)) haml_internal_concat_raw "<#{name}#{attributes}#{' /' if haml_buffer.[:format] == :xhtml}>" return ret end if flags.include?(:/) raise HamlError.new(HamlError.(:self_closing_content)) if text raise HamlError.new(HamlError.(:illegal_nesting_self_closing)) if block end tag = "<#{name}#{attributes}>" end_tag = "</#{name}>" if block.nil? text = text.to_s if text.include?("\n") haml_internal_concat_raw tag tab_up haml_internal_concat text tab_down haml_internal_concat_raw end_tag else haml_internal_concat_raw tag, false haml_internal_concat text, false, false haml_internal_concat_raw end_tag, true, false end return ret end if text raise HamlError.new(HamlError.(:illegal_nesting_line, name)) end if flags.include?(:<) haml_internal_concat_raw tag, false haml_internal_concat "#{capture_haml(&block).strip}", false, false haml_internal_concat_raw end_tag, true, false return ret end haml_internal_concat_raw tag tab_up block.call tab_down haml_internal_concat_raw end_tag ret end |
#haml_tag_if(condition, *tag) ⇒ Object
Conditionally wrap a block in an element. If ‘condition` is `true` then this method renders the tag described by the arguments in `tag` (using #haml_tag) with the given block inside, otherwise it just renders the block.
For example,
- haml_tag_if important, '.important' do
%p
A (possibly) important paragraph.
will produce
<div class='important'>
<p>
A (possibly) important paragraph.
</p>
</div>
if ‘important` is truthy, and just
<p>
A (possibly) important paragraph.
</p>
otherwise.
Like #haml_tag, ‘haml_tag_if` outputs directly to the buffer and its return value should not be used. Use #capture_haml if you need to use its results as a string.
586 587 588 589 590 591 592 593 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 586 def haml_tag_if(condition, *tag) if condition haml_tag(*tag){ yield } else yield end ErrorReturn.new("haml_tag_if") end |
#html_attrs(lang = 'en-US') ⇒ {#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'>
228 229 230 231 232 233 234 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 228 def html_attrs(lang = 'en-US') if haml_buffer.[:format] == :xhtml {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang} else {:lang => lang} end end |
#html_escape(text) ⇒ String Also known as: html_escape_without_haml_xss
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”.
609 610 611 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 609 def html_escape(text) CGI.escapeHTML(text.to_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 Hamlit::HamlHelpers
end
context.init_haml_helpers
context.haml_tag :p, "Stuff"
76 77 78 79 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 76 def init_haml_helpers @haml_buffer = Hamlit::HamlBuffer.new(haml_buffer, HamlOptions.new.for_buffer) nil end |
#is_haml? ⇒ Boolean
Returns whether or not the current template is a Haml template.
This function, unlike other Hamlit::HamlHelpers functions, also works in other ‘ActionView` templates, where it will always return false.
638 639 640 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 638 def is_haml? !@haml_buffer.nil? && @haml_buffer.active? end |
#list_of(enum, opts = {}) {|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>
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)
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 200 def list_of(enum, opts={}, &block) opts_attributes = opts.map { |k, v| " #{k}='#{v}'" }.join enum.map 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 %Q!<li#{opts_attributes}>#{result}</li>! end.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.
90 91 92 93 94 95 96 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 90 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>
336 337 338 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 336 def precede(str, &block) "#{str}#{capture_haml(&block).chomp}\n" end |
#preserve(input) ⇒ Object #preserve { ... } ⇒ 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.
133 134 135 136 137 138 139 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 133 def preserve(input = nil, &block) return preserve(capture_haml(&block)) if block s = input.to_s.chomp("\n") s.gsub!(/\n/, '
') s.delete!("\r") s 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>.
355 356 357 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 355 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>*
317 318 319 320 321 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 317 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.
263 264 265 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 263 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>
254 255 256 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 254 def tab_up(i = 1) haml_buffer.tabulation += i end |
#with_tabs(i) { ... } ⇒ Object
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>
286 287 288 289 290 291 292 |
# File 'lib/hamlit/parser/haml_helpers.rb', line 286 def with_tabs(i) old_tabs = haml_buffer.tabulation haml_buffer.tabulation = i yield ensure haml_buffer.tabulation = old_tabs end |