Harbor Documentation

Harbor::ViewContext::Helpers::Text

Text helper which provides common routines such as HTML escaping, or truncating (previewing) long pieces of text (such as photo captions).

Public Instance Methods

h(value, default = nil)

HTML escape value 

      # File lib/harbor/view_context/helpers/text.rb, line 14
14:   def h(value, default = nil)
15:     # TODO: Remove external dependency!
16:     Rack::Utils::escape_html(value.to_s.empty? ? default : value)
17:   end

q(value)

Querystring escape value 

      # File lib/harbor/view_context/helpers/text.rb, line 8
 8:   def q(value)
 9:     # TODO: Remove external dependency!
10:     Rack::Utils::escape(value)
11:   end

truncate(value, character_count = 30, trailing = "…")

Truncates an object to the specified character count, appending the specified trailing text. The character count includes the length of the trailer. HTML entities are counted as 1 character in trailing. 

  truncate("Lorem ipsum dolor sit amet, consectetur") # => "Lorem ipsum dolor sit amet, c…"
  truncate("Lorem ipsum dolor sit amet, consectetur", 20) # => "Lorem ipsum dolor s…"
  truncate("Lorem ipsum dolor sit amet, consectetur", 20, "...") # => "Lorem ipsum dolor..."

      # File lib/harbor/view_context/helpers/text.rb, line 29
29:   def truncate(value, character_count = 30, trailing = "…")
30:     unless character_count.is_a?(Integer)
31:       raise ArgumentError.new(
32:         "Harbor::ViewContext::Helpers::Text#truncate[character_count] must be an Integer, was #{character_count.inspect}"
33:       )
34:     end
35: 
36:     unless character_count > 0
37:       raise ArgumentError.new(
38:         "Harbor::ViewContext::Helpers::Text#truncate[character_count] must be greater than zero, was #{character_count.inspect}."
39:       )
40:     end
41: 
42:     unless trailing.is_a?(String)
43:       raise ArgumentError.new(
44:         "Harbor::ViewContext::Helpers::Text#truncate[trailing] must be a String, was #{trailing.inspect}"
45:       )
46:     end
47: 
48:     if value.nil?
49:       ""
50:     else
51:       string_form = value.to_s
52: 
53:       if string_form.nil? || string_form.empty?
54:         ""
55:       elsif string_form.size <= character_count
56:         string_form
57:       else
58:         # The Regexp match here is to determine if the +trailing+ value is an HTML entity code,
59:         # in which case we assume it's length is 1, or a textual value, in which case we use the
60:         # actual size.
61:         string_form[0, character_count - (trailing =~ /\&\w+\;/ ? 1 : trailing.size)] + trailing
62:       end
63:     end
64:   end

truncate_on_words(value, character_count = 30, trailing = "…")

Truncates an object on the nearest word to the specified character count, appending the specified trailing text. 

  truncate_on_words("Lorem ipsum dolor sit amet, consectetur") # => "Lorem ipsum dolor sit amet&hellip;"
  truncate_on_words("Lorem ipsum dolor sit amet, consectetur", 20) # => "Lorem ipsum dolor&hellip;"
  truncate_on_words("Lorem ipsum dolor sit amet, consectetur", 20, "...") # => "Lorem ipsum dolor..."

The truncation will always look backwards unless the forward word boundary is within 5% of the specified character count. Thus: 

  truncate_on_words("Lorem ipsum dolor sit amet, consectetur est.", 38) # => "Lorem ipsum dolor sit amet, consectetur..."

       # File lib/harbor/view_context/helpers/text.rb, line 80
 80:   def truncate_on_words(value, character_count = 30, trailing = "&hellip;")
 81:     unless character_count.is_a?(Integer)
 82:       raise ArgumentError.new(
 83:         "Harbor::ViewContext::Helpers::Text#truncate_on_words[character_count] must be an Integer, was #{character_count.inspect}"
 84:       )
 85:     end
 86: 
 87:     unless character_count > 0
 88:       raise ArgumentError.new(
 89:         "Harbor::ViewContext::Helpers::Text#truncate_on_words[character_count] must be greater than zero, was #{character_count.inspect}."
 90:       )
 91:     end
 92: 
 93:     unless trailing.is_a?(String)
 94:       raise ArgumentError.new(
 95:         "Harbor::ViewContext::Helpers::Text#truncate_on_words[trailing] must be a String, was #{trailing.inspect}"
 96:       )
 97:     end
 98: 
 99:     return "" if value.nil?
100: 
101:     truncated_text = value.to_s.dup
102:     text_length = truncated_text.length
103: 
104:     return value if character_count >= text_length
105: 
106:     leftover = truncated_text.slice!(character_count, text_length)
107: 
108:     if (index = leftover.index(/\W|$/)) && index < (character_count * 0.05).ceil
109:       truncated_text << leftover.slice(0, index)
110:     else
111:       truncated_text = truncated_text[0, truncated_text.rindex(/\W/)]
112:     end
113: 
114:     # Remove any trailing punctuation.
115:     truncated_text.slice!(truncated_text.length - 1) if truncated_text[truncated_text.length - 1, 1] =~ /\W/
116: 
117:     truncated_text + trailing
118:   end