W3cubDocs

/Padrino

Module: Padrino::Helpers::FormatHelpers

Overview

Helpers related to formatting or manipulating text within templates.

Instance Method Summary

Instance Method Details

#distance_of_time_in_words(from_time, to_time = 0, include_seconds = false, options = {}) ⇒ String

Reports the approximate distance in time between two Time or Date objects or integers as seconds. Set include_seconds to true if you want more detailed approximations when distance < 1 min, 29 secs Distances are reported based on the following table:

0 <-> 29 secs                                                           # => less than a minute
30 secs <-> 1 min, 29 secs                                              # => 1 minute
1 min, 30 secs <-> 44 mins, 29 secs                                     # => [2..44] minutes
44 mins, 30 secs <-> 89 mins, 29 secs                                   # => about 1 hour
89 mins, 29 secs <-> 23 hrs, 59 mins, 29 secs                           # => about [2..24] hours
23 hrs, 59 mins, 29 secs <-> 47 hrs, 59 mins, 29 secs                   # => 1 day
47 hrs, 59 mins, 29 secs <-> 29 days, 23 hrs, 59 mins, 29 secs          # => [2..29] days
29 days, 23 hrs, 59 mins, 30 secs <-> 59 days, 23 hrs, 59 mins, 29 secs # => about 1 month
59 days, 23 hrs, 59 mins, 30 secs <-> 1 yr minus 1 sec                  # => [2..12] months
1 yr <-> 1 yr, 3 months                                                 # => about 1 year
1 yr, 3 months <-> 1 yr, 9 months                                       # => over 1 year
1 yr, 9 months <-> 2 yr minus 1 sec                                     # => almost 2 years
2 yrs <-> max time or date                                              # => (same rules as 1 yr)

With include_seconds = true and the difference < 1 minute 29 seconds:

0-4   secs      # => less than 5 seconds
5-9   secs      # => less than 10 seconds
10-19 secs      # => less than 20 seconds
20-39 secs      # => half a minute
40-59 secs      # => less than a minute
60-89 secs      # => 1 minute

Examples:

from_time = Time.now
distance_of_time_in_words(from_time, from_time + 50.minutes)        # => about 1 hour
distance_of_time_in_words(from_time, 50.minutes.from_now)           # => about 1 hour
distance_of_time_in_words(from_time, from_time + 15.seconds)        # => less than a minute
distance_of_time_in_words(from_time, from_time + 15.seconds, true)  # => less than 20 seconds
distance_of_time_in_words(from_time, 3.years.from_now)              # => about 3 years
distance_of_time_in_words(from_time, from_time + 60.hours)          # => about 3 days
distance_of_time_in_words(from_time, from_time + 45.seconds, true)  # => less than a minute
distance_of_time_in_words(from_time, from_time - 45.seconds, true)  # => less than a minute
distance_of_time_in_words(from_time, 76.seconds.from_now)           # => 1 minute
distance_of_time_in_words(from_time, from_time + 1.year + 3.days)   # => about 1 year
distance_of_time_in_words(from_time, from_time + 3.years + 6.months) # => over 3 years
distance_of_time_in_words(from_time, from_time + 4.years + 9.days + 30.minutes + 5.seconds) # => about 4 years
to_time = Time.now + 6.years + 19.days
distance_of_time_in_words(from_time, to_time, true)     # => about 6 years
distance_of_time_in_words(to_time, from_time, true)     # => about 6 years
distance_of_time_in_words(Time.now, Time.now)           # => less than a minute

Parameters:

  • from_time (Time) — The time to be compared against to_time in order to approximate the distance.
  • to_time (Time) (defaults to: 0) — The time to be compared against from_time in order to approximate the distance.
  • include_seconds (Boolean) (defaults to: false) — Set true for more detailed approximations.
  • options (Hash) (defaults to: {}) — Flags for the approximation.

Options Hash (options):

  • :locale (String) — The translation locale to be used for approximating the time.

Returns:

  • (String) — The time formatted as a relative string.

#escape_html(text) ⇒ String Also known as: h, sanitize_html

Returns escaped text to protect against malicious content.

Examples:

escape_html("<b>Hey<b>") => "&lt;b&gt;Hey&lt;b;gt;"
h("Me & Bob") => "Me &amp; Bob"

Parameters:

  • text (String) — Unsanitized HTML string that needs to be escaped.

Returns:

  • (String) — HTML with escaped characters.

#h!(text, blank_text = '&nbsp;') ⇒ String

Returns escaped text to protect against malicious content.

Examples:

h!("Me & Bob") => "Me &amp; Bob"
h!("", "Whoops") => "Whoops"

Parameters:

  • text (String) — Unsanitized HTML string that needs to be escaped.
  • blank_text (String) (defaults to: '&nbsp;') — Text to return if escaped text is blank.

Returns:

  • (String) — HTML with escaped characters or the value specified if blank.

#highlight(text, words, options = {}) ⇒ String

Highlights one or more words everywhere in text by inserting it into a :highlighter string.

The highlighter can be customized by passing :highlighter as a single-quoted string with 1 where the phrase is to be inserted.

Examples:

highlight('Lorem ipsum dolor sit amet', 'dolor')
# => Lorem ipsum <strong class="highlight">dolor</strong> sit amet

highlight('Lorem ipsum dolor sit amet', 'dolor', :highlighter => '<span class="custom">\1</span>')
# => Lorem ipsum <strong class="custom">dolor</strong> sit amet

Parameters:

  • text (String) — The text that will be searched.
  • words (String) — The words to be highlighted in the text.
  • options (Hash) (defaults to: {}) — Formatting options for the highlight.

Options Hash (options):

  • :highlighter (String) — default: '<strong class="highlight">\1</strong>' — The html pattern for wrapping the highlighted words.

Returns:

  • (String) — The text with the words specified wrapped with highlighted spans.

#js_escape_html(html_content) ⇒ String Also known as: escape_javascript

Used in xxxx.js.erb files to escape html so that it can be passed to javascript from Padrino.

Examples:

js_escape_html("<h1>Hey</h1>")

Parameters:

  • html (String) — The HTML content to be escaped into javascript compatible format.

Returns:

  • (String) — The html escaped for javascript passing.

#pluralize(count, singular, plural = nil) ⇒ String

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 inflector to determine the plural form.

Examples:

pluralize(2, 'person') => '2 people'

Parameters:

  • count (Fixnum) — The count which determines pluralization.
  • singular (String) — The word to be pluralized if appropriate based on count.
  • plural (String) (defaults to: nil) — Explicit pluralized word to be used; if not specified uses inflector.

Returns:

  • (String) — The properly pluralized word.

#simple_format(text, options = {}) ⇒ String

Returns text transformed into HTML using simple formatting rules. Two or more consecutive newlines(nn) are considered as a paragraph and wrapped in <p> or your own tags. One newline (n) is considered as a linebreak and a <br /> tag is appended. This method does not remove the newlines from the text.

Examples:

simple_format("hello\nworld") # => "<p>hello<br/>world</p>"
simple_format("hello\nworld", :tag => :div, :class => :foo) # => "<div class="foo">hello<br/>world</div>"

Parameters:

  • text (String) — The simple text to be formatted.
  • options (Hash) (defaults to: {}) — Formatting options for the text. Can accept html options for the wrapper tag.

Options Hash (options):

  • :tag (Symbol) — default: p — The html tag to use for formatting newlines.

Returns:

  • (String) — The text formatted as simple HTML.

#strip_tags(html) ⇒ String

Strips all HTML tags from the html.

Examples:

strip_tags("<b>Hey</b>") => "Hey"

Parameters:

  • html (String) — The HTML for which to strip tags.

Returns:

  • (String) — HTML with tags stripped.

#time_ago_in_words(from_time, include_seconds = false) ⇒ String

Like distance_of_time_in_words, but where to_time is fixed to Time.now.

Examples:

time_ago_in_words(3.minutes.from_now)  # => 3 minutes
time_ago_in_words(Time.now - 15.hours) # => 15 hours
time_ago_in_words(Time.now)            # => less than a minute

Parameters:

  • from_time (Time) — The time to be compared against now in order to approximate the distance.
  • include_seconds (Boolean) (defaults to: false) — Set true for more detailed approximations.

Returns:

  • (String) — The time formatted as a relative string.

#truncate(text, options = {}) ⇒ String

Truncates a given text after a given :length if text is longer than :length (defaults to 30). The last characters will be replaced with the :omission (defaults to “…”) for a total length not exceeding :length.

Examples:

truncate("Once upon a time in a world far far away", :length => 8) => "Once upon..."

Parameters:

  • text (String) — The text to be truncated.
  • options (Hash) (defaults to: {}) — Formatting options for the truncation.

Options Hash (options):

  • :length (Fixnum) — default: 30 — The number of characters before truncation occurs.
  • :omission (String) — default: "..." — The characters that are placed after the truncated text.

Returns:

  • (String) — The text truncated after the given number of characters.

#truncate_words(text, options = {}) ⇒ String

Truncates words of a given text after a given :length if number of words in text is more than :length (defaults to 30). The last words will be replaced with the :omission (defaults to “…”) for a total number of words not exceeding :length.

Examples:

truncate_words("Once upon a time in a world far far away", :length => 8) => "Once upon a time in a world far..."

Parameters:

  • text (String) — The text to be truncated.
  • options (Hash) (defaults to: {}) — Formatting options for the truncation.

Options Hash (options):

  • :length (Fixnum) — default: 30 — The number of words before truncation occurs.
  • :omission (String) — default: "..." — The characters that are placed after the truncated text.

Returns:

  • (String) — The text truncated after the given number of words.

#word_wrap(text, options = {}) ⇒ String

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).

Examples:

word_wrap('Once upon a time', :line_width => 8) => "Once upon\na time"

Parameters:

  • text (String) — The text to be wrapped.
  • options (Hash) (defaults to: {}) — Formatting options for the wrapping.

Options Hash (options):

  • :line_width (Fixnum) — default: 80 — The line width before a wrap should occur.

Returns:

  • (String) — The text with line wraps for lines longer then line_width.