Module: ActionView::Helpers::TextHelper
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Included In:
ActionDispatch::DebugView,
::ActionView::Base ,
::ActionView::Helpers ,
FormHelper ,
FormOptionsHelper ,
FormTagHelper ,
ActionView::Helpers::Tags::Base,
ActionView::Helpers::Tags::CheckBox,
ActionView::Helpers::Tags::CollectionCheckBoxes,
ActionView::Helpers::Tags::CollectionRadioButtons,
ActionView::Helpers::Tags::CollectionSelect,
ActionView::Helpers::Tags::ColorField,
ActionView::Helpers::Tags::DateField,
ActionView::Helpers::Tags::DateSelect,
ActionView::Helpers::Tags::DatetimeField,
ActionView::Helpers::Tags::DatetimeLocalField,
ActionView::Helpers::Tags::DatetimeSelect,
ActionView::Helpers::Tags::EmailField,
ActionView::Helpers::Tags::FileField,
ActionView::Helpers::Tags::GroupedCollectionSelect,
ActionView::Helpers::Tags::HiddenField,
ActionView::Helpers::Tags::Label,
ActionView::Helpers::Tags::MonthField,
ActionView::Helpers::Tags::NumberField,
ActionView::Helpers::Tags::PasswordField,
ActionView::Helpers::Tags::RadioButton,
ActionView::Helpers::Tags::RangeField,
ActionView::Helpers::Tags::SearchField,
ActionView::Helpers::Tags::Select,
ActionView::Helpers::Tags::TelField,
ActionView::Helpers::Tags::TextArea,
ActionView::Helpers::Tags::TextField,
ActionView::Helpers::Tags::TimeField,
ActionView::Helpers::Tags::TimeSelect,
ActionView::Helpers::Tags::TimeZoneSelect,
ActionView::Helpers::Tags::UrlField,
ActionView::Helpers::Tags::WeekField,
ActionView::Helpers::Tags::WeekdaySelect,
::ActionView::TestCase ,
::ActionView::TestCase::Behavior
| |
Super Chains via Extension / Inclusion / Inheritance | |
Class Chain:
self,
::ActiveSupport::Concern
|
|
Instance Chain:
|
|
Defined in: | actionview/lib/action_view/helpers/text_helper.rb |
Overview
Action View Text Helpers
The TextHelper module provides a set of methods for filtering, formatting and transforming strings, which can reduce the amount of inline Ruby code in your views. These helper methods extend Action View making them callable within your template files.
Sanitization
Most text helpers that generate HTML output sanitize the given input by default, but do not escape it. This means HTML tags will appear in the page but all malicious code will be removed. Let’s look at some examples using the #simple_format method:
simple_format('<a href="http://example.com/">Example</a>')
# => "<p><a href=\"http://example.com/\">Example</a></p>"
simple_format('<a href="javascript:alert(\'no!\')">Example</a>')
# => "<p><a>Example</a></p>"
If you want to escape all content, you should invoke the h
method before calling the text helper.
simple_format h('<a href="http://example.com/">Example</a>')
# => "<p><a href=\"http://example.com/\">Example</a></p>"
Constant Summary
TagHelper
- Included
ARIA_PREFIXES, BOOLEAN_ATTRIBUTES, DATA_PREFIXES, PRE_CONTENT_STRINGS, TAG_TYPES
Class Method Summary
::ActiveSupport::Concern
- Extended
class_methods | Define class methods from given block. |
included | Evaluate given block in context of base class, so that you can write class macros here. |
prepended | Evaluate given block in context of base class, so that you can write class macros here. |
Instance Attribute Summary
SanitizeHelper
- Included
Instance Method Summary
-
#concat(string)
The preferred method of outputting text in your views is to use the
<%= "text" %>
eRuby syntax. -
#current_cycle(name = "default")
Returns the current cycle string after a cycle has been started.
-
#cycle(first_value, *values)
Creates a
Cycle
object whoseto_s
method cycles through elements of an array every time it is called. -
#excerpt(text, phrase, options = {})
Extracts the first occurrence of
phrase
plus surrounding text fromtext
. -
#highlight(text, phrases, options = {}, &block)
Highlights occurrences of
phrases
intext
by formatting them with a highlighter string. -
#pluralize(count, singular, plural_arg = nil, plural: plural_arg, locale: I18n.locale)
Attempts to pluralize the
singular
word unlesscount
is 1. -
#reset_cycle(name = "default")
Resets a cycle so that it starts from the first element the next time it is called.
- #safe_concat(string)
-
#simple_format(text, html_options = {}, options = {})
Returns
text
transformed into HTML using simple formatting rules. -
#truncate(text, options = {}, &block)
Truncates
text
if it is longer than a specified:length
. -
#word_wrap(text, line_width: 80, break_sequence: "\n")
Wraps the
text
into lines no longer thanline_width
width.
TagHelper
- Included
#cdata_section | Returns a CDATA section with the given |
#class_names | Alias for TagHelper#token_list. |
#content_tag | Returns an HTML block tag of type |
#escape_once | Returns an escaped version of |
#tag | Returns an HTML tag. |
#token_list | Returns a string of tokens built from |
OutputSafetyHelper
- Included
#raw | This method outputs without escaping a string. |
#safe_join | This method returns an HTML safe string similar to what |
#to_sentence | Converts the array to a comma-separated sentence where the last element is joined by the connector word. |
CaptureHelper
- Included
#capture | The capture method extracts part of a template as a string object. |
#content_for | Calling |
#content_for? |
|
#provide | The same as |
SanitizeHelper
- Included
#sanitize | Sanitizes HTML input, stripping all but known-safe tags and attributes. |
#sanitize_css | Sanitizes a block of CSS code. |
#strip_links | Strips all link tags from |
#strip_tags | Strips all HTML tags from |
Instance Method Details
#concat(string)
The preferred method of outputting text in your views is to use the <%= "text" %>
eRuby syntax. The regular puts
and print
methods do not operate as expected in an eRuby code block. If you absolutely must output text within a non-output code block (i.e., <% %>
), you can use the concat
method.
<% concat "hello" %> is equivalent to <%= "hello" %>
<%
unless signed_in?
concat link_to("Sign In", action: :sign_in)
end
%>
is equivalent to
<% unless signed_in? %>
<%= link_to "Sign In", action: :sign_in %>
<% end %>
# File 'actionview/lib/action_view/helpers/text_helper.rb', line 63
def concat(string) output_buffer << string end
#current_cycle(name = "default")
Returns the current cycle string after a cycle has been started. Useful for complex table highlighting or any other design need which requires the current cycle string in more than one place.
<%# Alternate background colors %>
<% @items = [1,2,3,4] %>
<% @items.each do |item| %>
<div style="background-color:<%= cycle("red","white","blue") %>">
<span style="background-color:<%= current_cycle %>"><%= item %></span>
</div>
<% end %>
#cycle(first_value, *values)
Creates a TextHelper::Cycle
object whose to_s
method cycles through elements of an array every time it is called. This can be used for example, to alternate classes for table rows. You can use named cycles to allow nesting in loops. Passing a ::Hash
as the last parameter with a :name
key will create a named cycle. The default name for a cycle without a :name
key is "default"
. You can manually reset a cycle by calling reset_cycle and passing the name of the cycle. The current cycle string can be obtained anytime using the current_cycle method.
<%# Alternate CSS classes for even and odd numbers... %>
<% @items = [1,2,3,4] %>
<table>
<% @items.each do |item| %>
<tr class="<%= cycle("odd", "even") -%>">
<td><%= item %></td>
</tr>
<% end %>
</table>
<%# Cycle CSS classes for rows, and text colors for values within each row %>
<% @items = [
{ first: "Robert", middle: "Daniel", last: "James" },
{ first: "Emily", middle: "Shannon", maiden: "Pike", last: "Hicks" },
{ first: "June", middle: "Dae", last: "Jones" },
] %>
<% @items.each do |item| %>
<tr class="<%= cycle("odd", "even", name: "row_class") -%>">
<td>
<% item.values.each do |value| %>
<%# Create a named cycle "colors" %>
<span style="color:<%= cycle("red", "green", "blue", name: "colors") -%>">
<%= value %>
</span>
<% end %>
<% reset_cycle("colors") %>
</td>
</tr>
<% end %>
#excerpt(text, phrase, options = {})
Extracts the first occurrence of phrase
plus surrounding text from text
. An omission marker is prepended / appended if the start / end of the result does not coincide with the start / end of text
. The result is always stripped in any case. Returns nil
if phrase
isn’t found.
Options
:radius
-
The number of characters (or tokens — see
:separator
option) aroundphrase
to include in the result. Defaults to 100. :omission
-
The marker to prepend / append when the start / end of the excerpt does not coincide with the start / end of
text
. Defaults to"..."
. :separator
-
The separator between tokens to count for
:radius
. Defaults to""
, which treats each character as a token.
Examples
excerpt('This is an example', 'an', radius: 5)
# => "...s is an exam..."
excerpt('This is an example', 'is', radius: 5)
# => "This is a..."
excerpt('This is an example', 'is')
# => "This is an example"
excerpt('This next thing is an example', 'ex', radius: 2)
# => "...next..."
excerpt('This is also an example', 'an', radius: 8, omission: '<chop> ')
# => "<chop> is also an example"
excerpt('This is a very beautiful morning', 'very', separator: ' ', radius: 1)
# => "...a very beautiful..."
# File 'actionview/lib/action_view/helpers/text_helper.rb', line 235
def excerpt(text, phrase, = {}) return unless text && phrase separator = .fetch(:separator, nil) || "" case phrase when Regexp regex = phrase else regex = /#{Regexp.escape(phrase)}/i end return unless matches = text.match(regex) phrase = matches[0] unless separator.empty? text.split(separator).each do |value| if value.match?(regex) phrase = value break end end end first_part, second_part = text.split(phrase, 2) prefix, first_part = cut_excerpt_part(:first, first_part, separator, ) postfix, second_part = cut_excerpt_part(:second, second_part, separator, ) affix = [first_part, separator, phrase, separator, second_part].join.strip [prefix, affix, postfix].join end
#highlight(text, phrases, options = {}, &block)
Highlights occurrences of phrases
in text
by formatting them with a highlighter string. phrases
can be one or more strings or regular expressions. The result will be marked HTML safe. By default, text
is sanitized before highlighting to prevent possible XSS attacks.
If a block is specified, it will be used instead of the highlighter string. Each occurrence of a phrase will be passed to the block, and its return value will be inserted into the final result.
Options
:highlighter
-
The highlighter string. Uses
\1
as the placeholder for a phrase, similar toString#sub
. Defaults to"<mark>\1</mark>"
. This option is ignored if a block is specified. :sanitize
-
Whether to sanitize
text
before highlighting. Defaults to true.
Examples
highlight('You searched for: rails', 'rails')
# => "You searched for: <mark>rails</mark>"
highlight('You searched for: rails', /for|rails/)
# => "You searched <mark>for</mark>: <mark>rails</mark>"
highlight('You searched for: ruby, rails, dhh', 'actionpack')
# => "You searched for: ruby, rails, dhh"
highlight('You searched for: rails', ['for', 'rails'], highlighter: '<em>\1</em>')
# => "You searched <em>for</em>: <em>rails</em>"
highlight('You searched for: rails', 'rails', highlighter: '<a href="search?q=\1">\1</a>')
# => "You searched for: <a href=\"search?q=rails\">rails</a>"
highlight('You searched for: rails', 'rails') { |match| link_to(search_path(q: match, match)) }
# => "You searched for: <a href=\"search?q=rails\">rails</a>"
highlight('<a href="javascript:alert(\'no!\')">ruby</a> on rails', 'rails', sanitize: false)
# => "<a href=\"javascript:alert('no!')\">ruby</a> on <mark>rails</mark>"
# File 'actionview/lib/action_view/helpers/text_helper.rb', line 174
def highlight(text, phrases, = {}, &block) text = sanitize(text) if .fetch(:sanitize, true) if text.blank? || phrases.blank? text || "" else patterns = Array(phrases).map { |phrase| Regexp === phrase ? phrase : Regexp.escape(phrase) } pattern = /(#{patterns.join("|")})/i highlighter = .fetch(:highlighter, '<mark>\1</mark>') unless block text.scan(/<[^>]*|[^<]+/).each do |segment| if !segment.start_with?("<") if block segment.gsub!(pattern, &block) else segment.gsub!(pattern, highlighter) end end end.join end.html_safe end
#pluralize(count, singular, plural_arg = nil, plural: plural_arg, locale: I18n.locale)
Attempts to pluralize the singular
word unless count
is 1. If plural
is supplied, it will use that when count is > 1, otherwise it will use the Inflector to determine the plural form for the given locale, which defaults to I18n.locale
.
The word will be pluralized using rules defined for the locale (you must define your own inflection rules for languages other than English). See ActiveSupport::Inflector.pluralize
pluralize(1, 'person')
# => "1 person"
pluralize(2, 'person')
# => "2 people"
pluralize(3, 'person', plural: 'users')
# => "3 users"
pluralize(0, 'person')
# => "0 people"
pluralize(2, 'Person', locale: :de)
# => "2 Personen"
# File 'actionview/lib/action_view/helpers/text_helper.rb', line 290
def pluralize(count, singular, plural_arg = nil, plural: plural_arg, locale: I18n.locale) word = if count == 1 || count.to_s.match?(/^1(\.0+)?$/) singular else plural || singular.pluralize(locale) end "#{count || 0} #{word}" end
#reset_cycle(name = "default")
Resets a cycle so that it starts from the first element the next time it is called. Pass in name
to reset a named cycle.
<%# Alternate CSS classes for even and odd numbers... %>
<% @items = [[1,2,3,4], [5,6,3], [3,4,5,6,7,4]] %>
<table>
<% @items.each do |item| %>
<tr class="<%= cycle("even", "odd") -%>">
<% item.each do |value| %>
<span style="color:<%= cycle("#333", "#666", "#999", name: "colors") -%>">
<%= value %>
</span>
<% end %>
<% reset_cycle("colors") %>
</tr>
<% end %>
</table>
#safe_concat(string)
[ GitHub ]# File 'actionview/lib/action_view/helpers/text_helper.rb', line 67
def safe_concat(string) output_buffer.respond_to?(:safe_concat) ? output_buffer.safe_concat(string) : concat(string) end
#simple_format(text, html_options = {}, options = {})
Returns text
transformed into HTML using simple formatting rules. Two or more consecutive newlines (\n\n
or \r\n\r\n
) are considered a paragraph and wrapped in <p>
tags. One newline (\n
or \r\n
) is considered a linebreak and a <br />
tag is appended. This method does not remove the newlines from the text
.
You can pass any HTML attributes into html_options
. These will be added to all created paragraphs.
Options
-
:sanitize
- Iffalse
, does not sanitizetext
. -
:sanitize_options
- Any extra options you want appended to the sanitize. -
:wrapper_tag
-::String
representing the wrapper tag, defaults to"p"
Examples
my_text = "Here is some basic text...\n...with a line break."
simple_format(my_text)
# => "<p>Here is some basic text...\n<br />...with a line break.</p>"
simple_format(my_text, {}, wrapper_tag: "div")
# => "<div>Here is some basic text...\n<br />...with a line break.</div>"
more_text = "We want to put a paragraph...\n\n...right there."
simple_format(more_text)
# => "<p>We want to put a paragraph...</p>\n\n<p>...right there.</p>"
simple_format("Look ma! A class!", class: 'description')
# => "<p class='description'>Look ma! A class!</p>"
simple_format("<blink>Unblinkable.</blink>")
# => "<p>Unblinkable.</p>"
simple_format("<blink>Blinkable!</blink> It's true.", {}, sanitize: false)
# => "<p><blink>Blinkable!</blink> It's true.</p>"
simple_format("<a target=\"_blank\" href=\"http://example.com\">Continue</a>", {}, { sanitize_options: { attributes: %w[target href] } })
# => "<p><a target=\"_blank\" href=\"http://example.com\">Continue</a></p>"
# File 'actionview/lib/action_view/helpers/text_helper.rb', line 376
def simple_format(text, = {}, = {}) wrapper_tag = [:wrapper_tag] || "p" text = sanitize(text, .fetch(:, {})) if .fetch(:sanitize, true) paragraphs = split_paragraphs(text) if paragraphs.empty? content_tag(wrapper_tag, nil, ) else paragraphs.map! { |paragraph| content_tag(wrapper_tag, raw(paragraph), ) }.join("\n\n").html_safe end end
#truncate(text, options = {}, &block)
Truncates text
if it is longer than a specified :length
. If text
is truncated, an omission marker will be appended to the result for a total length not exceeding :length
.
You can also pass a block to render and append extra content after the omission marker when text
is truncated. However, this content can cause the total length to exceed :length
characters.
The result will be escaped unless escape: false
is specified. In any case, the result will be marked HTML-safe. Care should be taken if text
might contain HTML tags or entities, because truncation could produce invalid HTML, such as unbalanced or incomplete tags.
Options
:length
-
The maximum number of characters that should be returned, excluding any extra content from the block. Defaults to 30.
:omission
-
The string to append after truncating. Defaults to
"..."
. :separator
-
A string or regexp used to find a breaking point at which to truncate. By default, truncation can occur at any character in
text
. :escape
-
Whether to escape the result. Defaults to true.
Examples
truncate("Once upon a time in a world far far away")
# => "Once upon a time in a world..."
truncate("Once upon a time in a world far far away", length: 17)
# => "Once upon a ti..."
truncate("Once upon a time in a world far far away", length: 17, separator: ' ')
# => "Once upon a..."
truncate("And they found that many people were sleeping better.", length: 25, omission: '... (continued)')
# => "And they f... (continued)"
truncate("<p>Once upon a time in a world far far away</p>")
# => "<p>Once upon a time in a wo..."
truncate("<p>Once upon a time in a world far far away</p>", escape: false)
# => "<p>Once upon a time in a wo..."
truncate("Once upon a time in a world far far away") { link_to "Continue", "#" }
# => "Once upon a time in a world...<a href=\"#\">Continue</a>"
# File 'actionview/lib/action_view/helpers/text_helper.rb', line 122
def truncate(text, = {}, &block) if text length = .fetch(:length, 30) content = text.truncate(length, ) content = [:escape] == false ? content.html_safe : ERB::Util.html_escape(content) content << capture(&block) if block_given? && text.length > length content end end
#word_wrap(text, line_width: 80, break_sequence: "\n")
Wraps the text
into lines no longer than line_width
width. This method breaks on the first whitespace character that does not exceed line_width
(which is 80 by default).
word_wrap('Once upon a time')
# => "Once upon a time"
word_wrap('Once upon a time, in a kingdom called Far Far Away, a king fell ill, and finding a successor to the throne turned out to be more trouble than anyone could have imagined...')
# => "Once upon a time, in a kingdom called Far Far Away, a king fell ill, and finding\na successor to the throne turned out to be more trouble than anyone could have\nimagined..."
word_wrap('Once upon a time', line_width: 8)
# => "Once\nupon a\ntime"
word_wrap('Once upon a time', line_width: 1)
# => "Once\nupon\na\ntime"
You can also specify a custom break_sequence
(“n” by default):
word_wrap('Once upon a time', line_width: 1, break_sequence: "\r\n")
# => "Once\r\nupon\r\na\r\ntime"
# File 'actionview/lib/action_view/helpers/text_helper.rb', line 320
def word_wrap(text, line_width: 80, break_sequence: "\n") return +"" if text.empty? # Match up to `line_width` characters, followed by one of # (1) non-newline whitespace plus an optional newline # (2) the end of the string, ignoring any trailing newlines # (3) a newline # # -OR- # # Match an empty line pattern = /(.{1,#{line_width}})(?:[^\S\n]+\n?|\n*\Z|\n)|\n/ text.gsub(pattern, "\\1#{break_sequence}").chomp!(break_sequence) end