bcit-ci/CodeIgniter

################
Typography Class
################

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()`` method::

    $this->load->library('typography');

Once loaded, the Typography library object will be available using::

    $this->typography

***************
Class Reference
***************

.. php:class:: CI_Typography

    .. attribute:: $protect_braced_quotes = FALSE

        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.

        Usage example::

            $this->load->library('typography');
            $this->typography->protect_braced_quotes = TRUE;

    .. php:method:: auto_typography($str[, $reduce_linebreaks = FALSE])

        :param    string    $str: Input string
        :param    bool    $reduce_linebreaks: Whether to reduce consecutive linebreaks
        :returns:    HTML typography-safe string
        :rtype:    string

        Formats text so that it is semantically and typographically correct HTML.
        Takes a string as input and returns it with the following formatting:

         -  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.

        Usage example::

            $string = $this->typography->auto_typography($string);

        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->auto_typography($string, TRUE);

        .. 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.

    .. php:method:: format_characters($str)

        :param    string    $str: Input string
        :returns:    Formatted string
        :rtype:    string

        This method is similar to ``auto_typography()`` above, except that it only does character conversion:

         -  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.

        Usage example::

            $string = $this->typography->format_characters($string);

    .. php: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);