108 lines
3.9 KiB
ReStructuredText
108 lines
3.9 KiB
ReStructuredText
################
|
|
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 consequitive 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);
|