From 2488ed218f42ad4c068a26ef01280766673edf5a Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Fri, 19 Jul 2013 16:35:25 -0700 Subject: Updating Text Helper docs --- user_guide_src/source/helpers/text_helper.rst | 201 ++++++++++++-------------- 1 file changed, 93 insertions(+), 108 deletions(-) (limited to 'user_guide_src/source/helpers') diff --git a/user_guide_src/source/helpers/text_helper.rst b/user_guide_src/source/helpers/text_helper.rst index 773257220..0cacd1b69 100644 --- a/user_guide_src/source/helpers/text_helper.rst +++ b/user_guide_src/source/helpers/text_helper.rst @@ -5,7 +5,12 @@ Text Helper The Text Helper file contains functions that assist in working with text. -.. contents:: Page Contents +.. contents:: + :local: + +.. raw:: html + +
Loading this Helper =================== @@ -14,145 +19,131 @@ This helper is loaded using the following code:: $this->load->helper('text'); -The following functions are available: +Available Functions +=================== -word_limiter() -============== +The following functions are available: -.. function:: word_limiter($str, $limit = 100, $end_char = '…') +.. function:: word_limiter($str[, $limit = 100[, $end_char = '…']]) :param string $str: Input string :param int $limit: Limit :param string $end_char: End character (usually an ellipsis) :returns: string -Truncates a string to the number of *words* specified. Example:: + Truncates a string to the number of *words* specified. Example:: - $string = "Here is a nice text string consisting of eleven words."; - $string = word_limiter($string, 4); - // Returns: Here is a nice… + $string = "Here is a nice text string consisting of eleven words."; + $string = word_limiter($string, 4); + // Returns: Here is a nice… -The third parameter is an optional suffix added to the string. By -default it adds an ellipsis. + The third parameter is an optional suffix added to the string. By + default it adds an ellipsis. -character_limiter() -=================== -.. function:: character_limiter($str, $n = 500, $end_char = '…') +.. function:: character_limiter($str[, $n = 500[, $end_char = '…']]) :param string $str: Input string :param int $n: Number of characters :param string $end_char: End character (usually an ellipsis) :returns: string -Truncates a string to the number of *characters* specified. It -maintains the integrity of words so the character count may be slightly -more or less then what you specify. + Truncates a string to the number of *characters* specified. It + maintains the integrity of words so the character count may be slightly + more or less then what you specify. -Example:: + Example:: - $string = "Here is a nice text string consisting of eleven words."; - $string = character_limiter($string, 20); - // Returns: Here is a nice text string… + $string = "Here is a nice text string consisting of eleven words."; + $string = character_limiter($string, 20); + // Returns: Here is a nice text string… -The third parameter is an optional suffix added to the string, if -undeclared this helper uses an ellipsis. + The third parameter is an optional suffix added to the string, if + undeclared this helper uses an ellipsis. -.. note:: If you need to truncate to an exact number of characters please - see the :ref:`ellipsize()` function below. + .. note:: If you need to truncate to an exact number of characters please + see the :func:`ellipsize()` function below. -ascii_to_entities() -=================== .. function:: ascii_to_entities($str) :param string $str: Input string :returns: string -Converts ASCII values to character entities, including high ASCII and MS -Word characters that can cause problems when used in a web page, so that -they can be shown consistently regardless of browser settings or stored -reliably in a database. There is some dependence on your server's -supported character sets, so it may not be 100% reliable in all cases, -but for the most part it should correctly identify characters outside -the normal range (like accented characters). + Converts ASCII values to character entities, including high ASCII and MS + Word characters that can cause problems when used in a web page, so that + they can be shown consistently regardless of browser settings or stored + reliably in a database. There is some dependence on your server's + supported character sets, so it may not be 100% reliable in all cases, + but for the most part it should correctly identify characters outside + the normal range (like accented characters). -Example:: + Example:: - $string = ascii_to_entities($string); + $string = ascii_to_entities($string); -entities_to_ascii() -=================== -.. function::entities_to_ascii($str, $all = TRUE) +.. function::entities_to_ascii($str[, $all = TRUE]) :param string $str: Input string :param bool $all: Whether to convert unsafe entities as well :returns: string -This function does the opposite of :php:func:`ascii_to_entities()`. -It turns character entities back into ASCII. + This function does the opposite of :func:`ascii_to_entities()`. + It turns character entities back into ASCII. -convert_accented_characters() -============================= .. function:: convert_accented_characters($str) :param string $str: Input string :returns: string -Transliterates high ASCII characters to low ASCII equivalents. Useful -when non-English characters need to be used where only standard ASCII -characters are safely used, for instance, in URLs. + Transliterates high ASCII characters to low ASCII equivalents. Useful + when non-English characters need to be used where only standard ASCII + characters are safely used, for instance, in URLs. -Example:: + Example:: - $string = convert_accented_characters($string); + $string = convert_accented_characters($string); -.. note:: This function uses a companion config file - `application/config/foreign_chars.php` to define the to and - from array for transliteration. + .. note:: This function uses a companion config file + `application/config/foreign_chars.php` to define the to and + from array for transliteration. -word_censor() -============= -.. function:: word_censor($str, $censored, $replacement = '') +.. function:: word_censor($str, $censored[, $replacement = '']) :param string $str: Input string :param array $censored: List of bad words to censor :param string $replacement: What to replace bad words with :returns: string -Enables you to censor words within a text string. The first parameter -will contain the original string. The second will contain an array of -words which you disallow. The third (optional) parameter can contain -a replacement value for the words. If not specified they are replaced -with pound signs: ####. + Enables you to censor words within a text string. The first parameter + will contain the original string. The second will contain an array of + words which you disallow. The third (optional) parameter can contain + a replacement value for the words. If not specified they are replaced + with pound signs: ####. -Example:: + Example:: - $disallowed = array('darn', 'shucks', 'golly', 'phooey'); - $string = word_censor($string, $disallowed, 'Beep!'); + $disallowed = array('darn', 'shucks', 'golly', 'phooey'); + $string = word_censor($string, $disallowed, 'Beep!'); -highlight_code() -================ .. function:: highlight_code($str) :param string $str: Input string :returns: string -Colorizes a string of code (PHP, HTML, etc.). Example:: + Colorizes a string of code (PHP, HTML, etc.). Example:: - $string = highlight_code($string); + $string = highlight_code($string); -The function uses PHP's ``highlight_string()`` function, so the -colors used are the ones specified in your php.ini file. + The function uses PHP's ``highlight_string()`` function, so the + colors used are the ones specified in your php.ini file. -highlight_phrase() -================== -.. function:: highlight_phrase($str, $phrase, $tag_open = '', $tag_close = '') +.. function:: highlight_phrase($str, $phrase[, $tag_open = ''[, $tag_close = '']]) :param string $str: Input string :param string $phrase: Phrase to highlight @@ -160,45 +151,39 @@ highlight_phrase() :param string $tag_close: Closing tag for the highlight :returns: string -Will highlight a phrase within a text string. The first parameter will -contain the original string, the second will contain the phrase you wish -to highlight. The third and fourth parameters will contain the -opening/closing HTML tags you would like the phrase wrapped in. + Will highlight a phrase within a text string. The first parameter will + contain the original string, the second will contain the phrase you wish + to highlight. The third and fourth parameters will contain the + opening/closing HTML tags you would like the phrase wrapped in. -Example:: + Example:: - $string = "Here is a nice text string about nothing in particular."; - echo highlight_phrase($string, "nice text", '', ''); + $string = "Here is a nice text string about nothing in particular."; + echo highlight_phrase($string, "nice text", '', ''); -The above code prints:: + The above code prints:: - Here is a nice text string about nothing in particular. + Here is a nice text string about nothing in particular. -word_wrap() -=========== -.. function:: word_wrap($str, $charlim = 76) +.. function:: word_wrap($str[, $charlim = 76]) :param string $str: Input string :param int $charlim: Character limit :returns: string -Wraps text at the specified *character* count while maintaining -complete words. - -Example:: + Wraps text at the specified *character* count while maintaining + complete words. - $string = "Here is a simple string of text that will help us demonstrate this function."; - echo word_wrap($string, 25); + Example:: - // Would produce: Here is a simple string of text that will help us demonstrate this function + $string = "Here is a simple string of text that will help us demonstrate this function."; + echo word_wrap($string, 25); -.. _ellipsize(): + // Would produce: Here is a simple string of text that will help us demonstrate this function -ellipsize() -=========== -.. function:: ellipsize($str, $max_length, $position = 1, $ellipsis = '…') +.. function:: ellipsize($str, $max_length[, $position = 1[, $ellipsis = '…']]) :param string $str: Input string :param int $max_length: String length limit @@ -207,23 +192,23 @@ ellipsize() :param string $ellipsis: What to use as the ellipsis character :returns: string -This function will strip tags from a string, split it at a defined -maximum length, and insert an ellipsis. + This function will strip tags from a string, split it at a defined + maximum length, and insert an ellipsis. -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. + 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. -An optional forth parameter is the kind of ellipsis. By default, -… will be inserted. + An optional forth parameter is the kind of ellipsis. By default, + … will be inserted. -Example:: + Example:: - $str = 'this_string_is_entirely_too_long_and_might_break_my_design.jpg'; - echo ellipsize($str, 32, .5); + $str = 'this_string_is_entirely_too_long_and_might_break_my_design.jpg'; + echo ellipsize($str, 32, .5); -Produces:: + Produces:: - this_string_is_e…ak_my_design.jpg \ No newline at end of file + this_string_is_e…ak_my_design.jpg \ No newline at end of file -- cgit v1.2.3-24-g4f1b