summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/typography.rst
blob: db3f227bedc44b21f481a2eac672866d450588ec (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
################
Typography Class
################

The Typography Class provides functions that help you format text.

Initializing the Class
======================

Like most other classes in CodeIgniter, the Typography class is
initialized in your controller using the $this->load->library function::

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

Once loaded, the Typography library object will be available using:
$this->typography

auto_typography()
==================

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);

Parameters
----------

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.

By default the parser does not reduce line breaks. In other words, if no
parameters are submitted, it is the same as doing this::

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

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

format_characters()
====================

This function is similar to the auto_typography function 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);

nl2br_except_pre()
====================

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.

Usage example::

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

protect_braced_quotes
=======================

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

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