summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/typography.rst
blob: 321b064ba103a19c95c490da8bad6237d079ae7d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
################
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);