html_truncator 0.1.2 → 0.2.0

data/README.md

@@ -14,19 +14,19 @@ It's very simple. Install it with rubygems:
 
 Or, if you use bundler, add it to your `Gemfile`:
 
-    gem "html_truncator", :version => "~>0.1"
+    gem "html_truncator", :version => "~>0.2"
 
 Then you can use it in your code:
 
     require "html_truncator"
 	HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3)
-	# => "<p>Lorem ipsum dolor...</p>"
+	# => "<p>Lorem ipsum dolor…</p>"
 
 The HTML_Truncator class has only one method, `truncate`, with 3 arguments:
 
 * the HTML-formatted string to truncate
 * the number of words to keep (real words, tags and attributes aren't count)
-* the ellipsis (optional, '...' by default).
+* some options like the ellipsis (optional, '…' by default).
 
 And an attribute, `ellipsable_tags`, which lists the tags that can contain the ellipsis
 (by default: p ol ul li div header article nav section footer aside dd dt dl).
@@ -38,33 +38,43 @@ Examples
 A simple example:
 
 	HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3)
-	# => "<p>Lorem ipsum dolor...</p>"
+	# => "<p>Lorem ipsum dolor…</p>"
 
 If the text is too short to be truncated, it won't be modified:
 
     HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 5)
     # => "<p>Lorem ipsum dolor sit amet.</p>"
 
+If you prefer, you can have the length in characters instead of words:
+
+    HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 12, :length_in_chars => true)
+    # => "<p>Lorem ipsum …</p>"
+
 You can customize the ellipsis:
 
-    HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3, " (truncated)")
+    HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3, :ellipsis => " (truncated)")
     # => "<p>Lorem ipsum dolor (truncated)</p>"
 
 And even have HTML in the ellipsis:
 
-    HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3, '<a href="/more-to-read">...</a>')
+    HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3, :ellipsis => '<a href="/more-to-read">...</a>')
     # => "<p>Lorem ipsum dolor<a href="/more-to-read">...</a></p>"
 
 The ellipsis is put at the right place, inside `<p>`, but not `<i>`:
 
     HTML_Truncator.truncate("<p><i>Lorem ipsum dolor sit amet.</i></p>", 3)
-    # => "<p><i>Lorem ipsum dolor</i>...</p>"
+    # => "<p><i>Lorem ipsum dolor</i>…</p>"
 
 You can indicate that a tag can contain the ellipsis but adding it to the ellipsable_tags:
 
     HTML_Truncator.ellipsable_tags << "blockquote"
     HTML_Truncator.truncate("<blockquote>Lorem ipsum dolor sit amet.</blockquote>", 3)
-    # => "<blockquote>Lorem ipsum dolor...</blockquote>"
+    # => "<blockquote>Lorem ipsum dolor…</blockquote>"
+
+You can know if a string was truncated with the `html_truncated?` method:
+
+    HTML_Truncator.truncate("<p>Lorem ipsum dolor sit amet.</p>", 3).html_truncated?
+    # => true 
 
 
 Alternatives
@@ -102,5 +112,6 @@ Credits
 -------
 
 Thanks to François de Metz for his awesome help!
+Thanks to [kuroir](https://github.com/kuroir) and [benhutton](https://github.com/benhutton) for their suggestions.
 
 Copyright (c) 2011 Bruno Michel <bmichel@menfin.info>, released under the MIT license

data/lib/html_truncator.rb

@@ -1,11 +1,19 @@
+# encoding: utf-8
+
 require "nokogiri"
 require "set"
 
 
 class HTML_Truncator
-  def self.truncate(text, max_words, ellipsis="...")
+  DEFAULT_OPTIONS = { :ellipsis => "…", :length_in_chars => false }
+
+  def self.truncate(text, max, opts={})
+    return truncate(text, max, :ellipsis => opts) if String === opts
+    opts = DEFAULT_OPTIONS.merge(opts)
     doc = Nokogiri::HTML::DocumentFragment.parse(text)
-    doc.truncate(max_words, ellipsis).first
+    str, _, opts = doc.truncate(max, opts)
+    eval "class <<str; def html_truncated?; #{opts[:was_truncated]} end end"
+    str
   end
 
   class <<self
@@ -22,28 +30,29 @@ class Nokogiri::HTML::DocumentFragment
 end
 
 class Nokogiri::XML::Node
-  def truncate(max_words, ellipsis)
-    return ["", 1, ellipsis] if max_words == 0 && !ellipsable?
-    inner, remaining, ellipsis = inner_truncate(max_words, ellipsis)
+  def truncate(max, opts)
+    return ["", 1, opts] if max == 0 && !ellipsable?
+    inner, remaining, opts = inner_truncate(max, opts)
     children.remove
     add_child Nokogiri::HTML::DocumentFragment.parse(inner)
-    [to_xml(:indent => 0), max_words - remaining, ellipsis]
+    [to_html(:indent => 0), max - remaining, opts]
   end
 
-  def inner_truncate(max_words, ellipsis)
-    inner, remaining = "", max_words
+  def inner_truncate(max, opts)
+    inner, remaining = "", max
     self.children.each do |node|
-      txt, nb, ellipsis = node.truncate(remaining, ellipsis)
+      txt, nb, opts = node.truncate(remaining, opts)
       remaining -= nb
       inner += txt
       next if remaining >= 0
       if ellipsable?
-        inner += ellipsis
-        ellipsis = ""
+        inner += opts[:ellipsis]
+        opts[:ellipsis] = ""
+        opts[:was_truncated] = true
       end
       break
     end
-    [inner, remaining, ellipsis]
+    [inner, remaining, opts]
   end
 
   def ellipsable?
@@ -52,10 +61,16 @@ class Nokogiri::XML::Node
 end
 
 class Nokogiri::XML::Text
-  def truncate(max_words, ellipsis)
-    words    = content.split
-    nb_words = words.length
-    return [to_xhtml, nb_words, ellipsis] if nb_words <= max_words && max_words > 0
-    [words.slice(0, max_words).join(' '), nb_words, ellipsis]
+   def truncate(max, opts)
+     if opts[:length_in_chars]
+       count = content.length
+       return [to_xhtml, count, opts] if count <= max && max > 0
+       [content.slice(0, max), count, opts]
+     else
+       words = content.split
+       count = words.length
+       return [to_xhtml, count, opts] if count <= max && max > 0
+       [words.slice(0, max).join(' '), count, opts]
+     end
   end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
   - 2
-  version: 0.1.2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Bruno Michel
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-14 00:00:00 +01:00
+date: 2011-01-28 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency