diff options
Diffstat (limited to 'user_guide_src/source/libraries/typography.rst')
| -rw-r--r-- | user_guide_src/source/libraries/typography.rst | 140 |
1 files changed, 71 insertions, 69 deletions
diff --git a/user_guide_src/source/libraries/typography.rst b/user_guide_src/source/libraries/typography.rst index db3f227be..65fea9d8e 100644 --- a/user_guide_src/source/libraries/typography.rst +++ b/user_guide_src/source/libraries/typography.rst @@ -2,104 +2,106 @@ Typography Class ################ -The Typography Class provides functions that help you format text. +The Typography Class provides methods that help you format text. + +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +************************** +Using the Typography Class +************************** Initializing the Class ====================== Like most other classes in CodeIgniter, the Typography class is -initialized in your controller using the $this->load->library function:: +initialized in your controller using the ``$this->load->library()`` method:: $this->load->library('typography'); -Once loaded, the Typography library object will be available using: -$this->typography +Once loaded, the Typography library object will be available using:: -auto_typography() -================== + $this->typography -Formats text so that it is semantically and typographically correct -HTML. Takes a string as input and returns it with the following -formatting: +*************** +Class Reference +*************** -- Surrounds paragraphs within <p></p> (looks for double line breaks to - identify paragraphs). -- Single line breaks are converted to <br />, except those that appear - within <pre> tags. -- Block level elements, like <div> tags, are not wrapped within - paragraphs, but their contained text is if it contains paragraphs. -- Quotes are converted to correctly facing curly quote entities, except - those that appear within tags. -- Apostrophes are converted to curly apostrophe entities. -- Double dashes (either like -- this or like--this) are converted to - em—dashes. -- Three consecutive periods either preceding or following a word are - converted to ellipsis… -- Double spaces following sentences are converted to non-breaking - spaces to mimic double spacing. +.. class:: CI_Typography -Usage example:: + .. attribute:: $protect_braced_quotes = FALSE - $string = $this->typography->auto_typography($string); + When using the Typography library in conjunction with the :doc:`Template Parser library <parser>` + it can often be desirable to protect single and double quotes within curly braces. + To enable this, set the ``protect_braced_quotes`` class property to TRUE. -Parameters ----------- + Usage example:: -There is one optional parameters that determines whether the parser -should reduce more then two consecutive line breaks down to two. Use -boolean TRUE or FALSE. + $this->load->library('typography'); + $this->typography->protect_braced_quotes = TRUE; -By default the parser does not reduce line breaks. In other words, if no -parameters are submitted, it is the same as doing this:: + .. method auto_typography($str[, $reduce_linebreaks = FALSE]) - $string = $this->typography->auto_typography($string, FALSE); + :param string $str: Input string + :param bool $reduce_linebreaks: Whether to reduce consequitive linebreaks + :returns: HTML typography-safe string + :rtype: string -.. note:: Typographic formatting can be processor intensive, - particularly if you have a lot of content being formatted. If you choose - to use this function you may want to consider :doc:`caching <../general/caching>` - your pages. + Formats text so that it is semantically and typographically correct HTML. + Takes a string as input and returns it with the following formatting: -format_characters() -==================== + - Surrounds paragraphs within <p></p> (looks for double line breaks to identify paragraphs). + - Single line breaks are converted to <br />, except those that appear within <pre> tags. + - Block level elements, like <div> tags, are not wrapped within paragraphs, but their contained text is if it contains paragraphs. + - Quotes are converted to correctly facing curly quote entities, except those that appear within tags. + - Apostrophes are converted to curly apostrophe entities. + - Double dashes (either like -- this or like--this) are converted to em—dashes. + - Three consecutive periods either preceding or following a word are converted to ellipsis (…). + - Double spaces following sentences are converted to non-breaking spaces to mimic double spacing. -This function is similar to the auto_typography function above, except -that it only does character conversion: + Usage example:: -- Quotes are converted to correctly facing curly quote entities, except - those that appear within tags. -- Apostrophes are converted to curly apostrophe entities. -- Double dashes (either like -- this or like--this) are converted to - em—dashes. -- Three consecutive periods either preceding or following a word are - converted to ellipsis… -- Double spaces following sentences are converted to non-breaking - spaces to mimic double spacing. + $string = $this->typography->auto_typography($string); -Usage example:: + There is one optional parameter that determines whether the parser should reduce more than two consecutive line breaks down to two. + Pass boolean TRUE to enable reducing line breaks:: - $string = $this->typography->format_characters($string); + $string = $this->typography->auto_typography($string, TRUE); -nl2br_except_pre() -==================== + .. note:: Typographic formatting can be processor intensive, particularly if you have a lot of content being formatted. + If you choose to use this method you may want to consider :doc:`caching <../general/caching>` your pages. -Converts newlines to <br /> tags unless they appear within <pre> tags. -This function is identical to the native PHP nl2br() function, except -that it ignores <pre> tags. + .. method:: format_characters($str) -Usage example:: + :param string $str: Input string + :returns: Formatted string + :rtype: string - $string = $this->typography->nl2br_except_pre($string); + This method is similar to ``auto_typography()`` above, except that it only does character conversion: -protect_braced_quotes -======================= + - Quotes are converted to correctly facing curly quote entities, except those that appear within tags. + - Apostrophes are converted to curly apostrophe entities. + - Double dashes (either like -- this or like--this) are converted to em—dashes. + - Three consecutive periods either preceding or following a word are converted to ellipsis (…). + - Double spaces following sentences are converted to non-breaking spaces to mimic double spacing. -When using the Typography library in conjunction with the Template -Parser library it can often be desirable to protect single and double -quotes within curly braces. To enable this, set the -protect_braced_quotes class property to TRUE. + Usage example:: -Usage example:: + $string = $this->typography->format_characters($string); - $this->load->library('typography'); - $this->typography->protect_braced_quotes = TRUE; + .. method:: nl2br_except_pre($str) + + :param string $str: Input string + :returns: Formatted string + :rtype: string + + Converts newlines to <br /> tags unless they appear within <pre> tags. + This method is identical to the native PHP :php:func:`nl2br()` function, except that it ignores <pre> tags. + + Usage example:: + $string = $this->typography->nl2br_except_pre($string);
\ No newline at end of file |