Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / cc042095bcce9856402cc04997f44310074716e0 / . / user_guide_src / source / libraries / parser.rst
blob: 50bde82c7e43478c3dcb7bed1fc39e924d5281f0 [file] [log] [blame]
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]1#####################
2Template Parser Class
3#####################
4
5The Template Parser Class enables you to parse pseudo-variables
6contained within your view files. It can parse simple variables or
7variable tag pairs. If you've never used a template engine,
8pseudo-variables look like this::
9
Derek Joneseb946d02011-10-05 15:47:43 -0500[diff] [blame]10 <html>
11 <head>
12 <title>{blog_title}</title>
13 </head>
14 <body>
15
16 <h3>{blog_heading}</h3>
17
18 {blog_entries}
19 <h5>{title}</h5>
20 <p>{body}</p>
21 {/blog_entries}
22 </body>
23 </html>
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]24
25These variables are not actual PHP variables, but rather plain text
26representations that allow you to eliminate PHP from your templates
27(view files).
28
29.. note:: CodeIgniter does **not** require you to use this class since
30 using pure PHP in your view pages lets them run a little faster.
31 However, some developers prefer to use a template engine if they work
32 with designers who they feel would find some confusion working with PHP.
33
34.. important:: The Template Parser Class is **not** a full-blown
35 template parsing solution. We've kept it very lean on purpose in order
36 to maintain maximum performance.
37
Andrey Andreevcc042092014-01-03 17:08:27 +0200[diff] [blame^]38.. contents::
39 :local:
40
41.. raw:: html
42
43 <div class="custom-index container"></div>
44
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]45Initializing the Class
46======================
47
48Like most other classes in CodeIgniter, the Parser class is initialized
49in your controller using the $this->load->library function::
50
51 $this->load->library('parser');
52
53Once loaded, the Parser library object will be available using:
54$this->parser
55
Andrey Andreev8da2e222014-01-03 12:47:37 +0200[diff] [blame]56Parsing templates
57=================
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]58
Andrey Andreev8da2e222014-01-03 12:47:37 +0200[diff] [blame]59You can use the ``parse()`` method to parse (or render) simple templates, like this::
Derek Joneseb946d02011-10-05 15:47:43 -0500[diff] [blame]60
61 $data = array(
62 'blog_title' => 'My Blog Title',
63 'blog_heading' => 'My Blog Heading'
64 );
65
66 $this->parser->parse('blog_template', $data);
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]67
68The first parameter contains the name of the :doc:`view
69file <../general/views>` (in this example the file would be called
70blog_template.php), and the second parameter contains an associative
71array of data to be replaced in the template. In the above example, the
72template would contain two variables: {blog_title} and {blog_heading}
73
74There is no need to "echo" or do something with the data returned by
75$this->parser->parse(). It is automatically passed to the output class
76to be sent to the browser. However, if you do want the data returned
77instead of sent to the output class you can pass TRUE (boolean) to the
78third parameter::
79
80 $string = $this->parser->parse('blog_template', $data, TRUE);
81
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]82Variable Pairs
83==============
84
85The above example code allows simple variables to be replaced. What if
86you would like an entire block of variables to be repeated, with each
87iteration containing new values? Consider the template example we showed
88at the top of the page::
89
Derek Joneseb946d02011-10-05 15:47:43 -0500[diff] [blame]90 <html>
91 <head>
92 <title>{blog_title}</title>
93 </head>
94 <body>
95
96 <h3>{blog_heading}</h3>
97
98 {blog_entries}
99 <h5>{title}</h5>
100 <p>{body}</p>
101 {/blog_entries}
102 </body>
103 </html>
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]104
105In the above code you'll notice a pair of variables: {blog_entries}
106data... {/blog_entries}. In a case like this, the entire chunk of data
107between these pairs would be repeated multiple times, corresponding to
108the number of rows in a result.
109
110Parsing variable pairs is done using the identical code shown above to
111parse single variables, except, you will add a multi-dimensional array
112corresponding to your variable pair data. Consider this example::
113
Derek Joneseb946d02011-10-05 15:47:43 -0500[diff] [blame]114 $this->load->library('parser');
115
116 $data = array(
117 'blog_title' => 'My Blog Title',
118 'blog_heading' => 'My Blog Heading',
119 'blog_entries' => array(
120 array('title' => 'Title 1', 'body' => 'Body 1'),
121 array('title' => 'Title 2', 'body' => 'Body 2'),
122 array('title' => 'Title 3', 'body' => 'Body 3'),
123 array('title' => 'Title 4', 'body' => 'Body 4'),
124 array('title' => 'Title 5', 'body' => 'Body 5')
125 )
126 );
127
128 $this->parser->parse('blog_template', $data);
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]129
130If your "pair" data is coming from a database result, which is already a
131multi-dimensional array, you can simply use the database result_array()
132function::
133
Derek Joneseb946d02011-10-05 15:47:43 -0500[diff] [blame]134 $query = $this->db->query("SELECT * FROM blog");
135
136 $this->load->library('parser');
137
138 $data = array(
139 'blog_title' => 'My Blog Title',
140 'blog_heading' => 'My Blog Heading',
141 'blog_entries' => $query->result_array()
142 );
143
144 $this->parser->parse('blog_template', $data);
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]145
Andrey Andreev8da2e222014-01-03 12:47:37 +0200[diff] [blame]146***************
147Class Reference
148***************
149
150.. class: CI_Parser
151
152 .. method:: parse($template, $data[, $return = FALSE])
153
154 :param string $template: Path to view file
155 :param array $data: Variable data
156 :param bool $return: Whether to return the parsed template
157 :returns: mixed
158
159 Parses a template from the provided path and variables.
160
161 .. method:: parse_string($template, $data[, $return = FALSE])
162
163 :param string $template: Path to view file
164 :param array $data: Variable data
165 :param bool $return: Whether to return the parsed template
166 :returns: mixed
167
168 This method works exactly like ``parse()``, only it accepts the template as a
169 string instead of loading a view file.
170
171 .. method:: set_delimiters([$l = '{'[, $r = '}']])
172
173 :param string $l: Left delimiter
174 :param string $r: Right delimiter
175 :returns: void
176
177 Sets the delimiters (opening and closing) for a value "tag" in a template.