From 9ded3dfd1fe743f828524b77ad6675aab928407b Mon Sep 17 00:00:00 2001
From: Sean Harvey <sean@silverstripe.com>
Date: Tue, 16 Dec 2008 09:50:50 +0000
Subject: [PATCH] MINOR Added documentation to various Text class methods for
 limiting field values ENHANCEMENT Added ability to define the ellipsis for
 LimitWordCount() setting "..." as the default

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/branches/2.3@69218 467b73ca-7a2a-4603-9d3b-597d59a354a9
---
 core/model/fieldtypes/Text.php | 50 ++++++++++++++++++++++++++--------
 1 file changed, 38 insertions(+), 12 deletions(-)

diff --git a/core/model/fieldtypes/Text.php b/core/model/fieldtypes/Text.php
index 3cf565afe..d4f8d58b4 100644
--- a/core/model/fieldtypes/Text.php
+++ b/core/model/fieldtypes/Text.php
@@ -17,16 +17,23 @@ class Text extends DBField {
 		return ($this->value || $this->value == '0');
 	}
 	
-	//useed for search results show only limited contents
-	function LimitWordCount($numWords = 26) {
+	/**
+	 * Limit this field's content by a number of words.
+	 * CAUTION: This is not XML safe. Please use
+	 * {@link LimitWordCountXML()} instead.
+	 *
+	 * @param int $numWords Number of words to limit by
+	 * @return string
+	 */
+	function LimitWordCount($numWords = 26, $add = '...') {
 		$this->value = Convert::xml2raw($this->value);
-		$ret = explode(" ", $this->value, $numWords);
+		$ret = explode(' ', $this->value, $numWords);
 		
-		if( Count($ret) < $numWords-1 ){
-			$ret=$this->value;
-		}else{
+		if(count($ret) < $numWords - 1) {
+			$ret = $this->value;
+		} else {
 			array_pop($ret);
-			$ret=implode(" ", $ret)."...";
+			$ret = implode(' ', $ret) . $add;
 		}
 		
 		return $ret;
@@ -43,11 +50,24 @@ class Text extends DBField {
 		return HTTP::absoluteURLs($this->value);
 	}
 	
+	/**
+	 * Limit this field's content by a number of characters.
+	 * Caution: This can be harmful on HTML, it can potentially
+	 * malform your HTML if it limits halfway through a tag.
+	 *
+	 * @param int $limit Number of characters to limit by
+	 * @param string $add Ellipsis to add to the end of limited string
+	 * @return string
+	 */
 	function LimitCharacters($limit = 20, $add = "...") {
 		$value = trim($this->value);
 		return (strlen($value) > $limit) ? substr($value, 0, $limit) . $add : $value;
 	}
 	
+	/**
+	 * @deprecated. Please use {@link LimitWordCount()}
+	 * or {@link LimitWordCountXML()} instead.
+	 */
 	function LimitWordCountPlainText($numWords = 26) {
 		$ret = $this->LimitWordCount( $numWords );
 		// Use LimitWordCountXML() instead!
@@ -55,11 +75,17 @@ class Text extends DBField {
 		return $ret;
 	}
 	
-	function LimitWordCountXML( $numWords = 26 ) {
-		$ret = $this->LimitWordCount( $numWords );
-		$ret = Convert::raw2xml($ret);
-		
-		return $ret;
+	/**
+	 * Limit the number of words of the current field's
+	 * content. This is XML safe, so characters like &
+	 * are converted to &amp;
+	 *
+	 * @param int $numWords Number of words to limit by
+	 * @return string
+	 */
+	function LimitWordCountXML($numWords = 26) {
+		$ret = $this->LimitWordCount($numWords);
+		return Convert::raw2xml($ret);
 	}
 
 	/**