From cbe3247819be75c34231ea200874044735bd853b Mon Sep 17 00:00:00 2001
From: Greg Aker <greg.aker@ellislab.com>
Date: Thu, 5 Aug 2010 14:09:20 -0500
Subject: Adding an ellipsize function to the text helper, and associated
 documentation to the user guide.

---
 system/helpers/text_helper.php      | 42 +++++++++++++++++++++++++++++++++++++
 user_guide/changelog.html           |  1 +
 user_guide/helpers/text_helper.html | 12 +++++++++++
 3 files changed, 55 insertions(+)

diff --git a/system/helpers/text_helper.php b/system/helpers/text_helper.php
index 477260216..b7ade7a8f 100644
--- a/system/helpers/text_helper.php
+++ b/system/helpers/text_helper.php
@@ -495,6 +495,48 @@ if ( ! function_exists('word_wrap'))
 	}
 }
  
+// ------------------------------------------------------------------------
+
+if ( ! function_exists('ellipsize'))
+{
+	/**
+	 * Ellipsize String
+	 *
+	 * This function will strip tags from a string, split it at its max_length and ellipsize
+	 *
+	 * @param 	string		string to ellipsize
+	 * @param	integer		max length of string
+	 * @param	mixed		int (1|0) or float, .5, .2, etc for position to split
+	 * @param 	string		ellipsis ; Default '...'
+	 * @return	string		ellipsized string
+	 */
+	function ellipsize($str, $max_length, $position = 1, $ellipsis = '&hellip;')
+	{
+		// Strip tags
+		$str = trim(strip_tags($str));
+
+		// Is the string long enough to ellipsize?
+		if (strlen($str) <= $max_length)
+		{
+			return $str;
+		}
+
+		$beg = substr($str, 0, floor($max_length * $position));
+
+		$position = ($position > 1) ? 1 : $position;
+
+		if ($position === 1)
+		{
+			$end = substr($str, 0, -($max_length - strlen($beg)));
+		}
+		else
+		{
+			$end = substr($str, -($max_length - strlen($beg)));
+		}
+
+		return $beg.$ellipsis.$end;	
+	}
+}
 
 /* End of file text_helper.php */
 /* Location: ./system/helpers/text_helper.php */
\ No newline at end of file
diff --git a/user_guide/changelog.html b/user_guide/changelog.html
index ce017c9fd..f32ee58b3 100644
--- a/user_guide/changelog.html
+++ b/user_guide/changelog.html
@@ -128,6 +128,7 @@ Hg Tag: </p>
 			<li>The <kbd>img()</kbd> function of the <a href="./helpers/html_helper.html">HTML helper</a> will now generate an empty string as an alt attribute if one is not provided.</li>
 			<li>If CSRF is enabled in the application config file, <kbd>form_open()</kbd> will automatically insert it as a hidden field.</li>
 			<li>Added <kbd>sanitize_filename()</kbd> into the <a href="./helpers/security_helper.html">Security helper</a>.</li>
+			<li>Added <kbd>ellipsize()</kbd> to the <a href="./helpers/text_helper.html">Text Helper</a></li>
 		</ul>
 	</li>
 	<li>Other Changes
diff --git a/user_guide/helpers/text_helper.html b/user_guide/helpers/text_helper.html
index d477f53a9..438eaec45 100644
--- a/user_guide/helpers/text_helper.html
+++ b/user_guide/helpers/text_helper.html
@@ -177,7 +177,19 @@ of text that will help<br />
 us demonstrate this<br />
 function</code>
 
+<h2>ellipsize()</h2>
 
+<p>This function will strip tags from a string, split it at a defined maximum length, and insert an ellipsis.</p>
+<p>The first parameter is the string to ellipsize, the second is the number of characters in the final string. The third parameter is where in the string the ellipsis should appear from 0 - 1, left to right.  For example.  a value of 1 will place the ellipsis at the right of the string, .5 in the middle, and 0 at the left.</p>
+<p>An optional forth parameter is the kind of ellipsis.  By default, <samp>&amp;hellip;</samp> will be inserted.</p>
+
+<code>$str = 'this_string_is_entirely_too_long_and_might_break_my_design.jpg';<br />
+<br />
+echo ellipsize($str, 32, .5);</code>
+
+Produces:
+
+<code>this_string_is_e&hellip;ak_my_design.jpg</code>
 
 
 </div>
-- 
cgit v1.2.3-24-g4f1b