Blame - user_guide_src/source/libraries/parser.rst - code-igniter-v3-giggi

blob: 23b2492c9e7f9ac615a57b7cf1bd89e5756c66cf [file] [log] [blame]

Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	1	#####################
				2	Template Parser Class
				3	#####################
				4
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	5	The Template Parser Class can perform simple text substitution for pseudo-variables
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	6	contained within your view files. It can parse simple variables or
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	7	variable tag pairs.
				8
				9	If you've never used a template engine,
				10	pseudo-variable names are enclosed in braces, like this::
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	11
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	12	<html>
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	13	<head>
				14	<title>{blog_title}</title>
				15	</head>
				16	<body>
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	17
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	18	<h3>{blog_heading}</h3>
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	19
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	20	{blog_entries}
				21	<h5>{title}</h5>
				22	<p>{body}</p>
				23	{/blog_entries}
				24	</body>
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	25	</html>
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	26
				27	These variables are not actual PHP variables, but rather plain text
				28	representations that allow you to eliminate PHP from your templates
				29	(view files).
				30
				31	.. note:: CodeIgniter does not require you to use this class since
				32	using pure PHP in your view pages lets them run a little faster.
				33	However, some developers prefer to use a template engine if they work
				34	with designers who they feel would find some confusion working with PHP.
				35
				36	.. important:: The Template Parser Class is not a full-blown
				37	template parsing solution. We've kept it very lean on purpose in order
				38	to maintain maximum performance.
				39
Andrey Andreev	cc04209	2014-01-03 17:08:27 +0200	[diff] [blame]	40	.. contents::
				41	:local:
				42
				43	.. raw:: html
				44
				45	<div class="custom-index container"></div>
				46
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	47	**********************
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	48	Initializing the Class
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	49	**********************
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	50
				51	Like most other classes in CodeIgniter, the Parser class is initialized
				52	in your controller using the $this->load->library function::
				53
				54	$this->load->library('parser');
				55
				56	Once loaded, the Parser library object will be available using:
				57	$this->parser
				58
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	59	*****************
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	60	Parsing templates
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	61	*****************
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	62
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	63	You can use the ``parse()`` method to parse (or render) simple templates, like this::
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	64
				65	$data = array(
				66	'blog_title' => 'My Blog Title',
				67	'blog_heading' => 'My Blog Heading'
				68	);
				69
				70	$this->parser->parse('blog_template', $data);
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	71
				72	The first parameter contains the name of the :doc:`view
				73	file <../general/views>` (in this example the file would be called
				74	blog_template.php), and the second parameter contains an associative
				75	array of data to be replaced in the template. In the above example, the
				76	template would contain two variables: {blog_title} and {blog_heading}
				77
				78	There is no need to "echo" or do something with the data returned by
				79	$this->parser->parse(). It is automatically passed to the output class
				80	to be sent to the browser. However, if you do want the data returned
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	81	instead of sent to the output class you can pass TRUE (boolean) as the
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	82	third parameter::
				83
				84	$string = $this->parser->parse('blog_template', $data, TRUE);
				85
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	86	**************
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	87	Variable Pairs
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	88	**************
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	89
				90	The above example code allows simple variables to be replaced. What if
				91	you would like an entire block of variables to be repeated, with each
				92	iteration containing new values? Consider the template example we showed
				93	at the top of the page::
				94
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	95	<html>
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	96	<head>
				97	<title>{blog_title}</title>
				98	</head>
				99	<body>
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	100
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	101	<h3>{blog_heading}</h3>
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	102
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	103	{blog_entries}
				104	<h5>{title}</h5>
				105	<p>{body}</p>
				106	{/blog_entries}
				107	</body>
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	108	</html>
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	109
				110	In the above code you'll notice a pair of variables: {blog_entries}
				111	data... {/blog_entries}. In a case like this, the entire chunk of data
				112	between these pairs would be repeated multiple times, corresponding to
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	113	the number of rows in the "blog_entries" element of the parameters array.
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	114
				115	Parsing variable pairs is done using the identical code shown above to
				116	parse single variables, except, you will add a multi-dimensional array
				117	corresponding to your variable pair data. Consider this example::
				118
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	119	$this->load->library('parser');
				120
				121	$data = array(
				122	'blog_title' => 'My Blog Title',
				123	'blog_heading' => 'My Blog Heading',
				124	'blog_entries' => array(
				125	array('title' => 'Title 1', 'body' => 'Body 1'),
				126	array('title' => 'Title 2', 'body' => 'Body 2'),
				127	array('title' => 'Title 3', 'body' => 'Body 3'),
				128	array('title' => 'Title 4', 'body' => 'Body 4'),
				129	array('title' => 'Title 5', 'body' => 'Body 5')
				130	)
				131	);
				132
				133	$this->parser->parse('blog_template', $data);
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	134
				135	If your "pair" data is coming from a database result, which is already a
				136	multi-dimensional array, you can simply use the database result_array()
				137	function::
				138
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	139	$query = $this->db->query("SELECT * FROM blog");
				140
				141	$this->load->library('parser');
				142
				143	$data = array(
				144	'blog_title' => 'My Blog Title',
				145	'blog_heading' => 'My Blog Heading',
				146	'blog_entries' => $query->result_array()
				147	);
				148
				149	$this->parser->parse('blog_template', $data);
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	150
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	151	***************************
				152	Template Parser Usage Notes
				153	***************************
				154
				155	If you include substitution parameters that are not referenced in your template, they are ignored::
				156
				157	$template = 'Hello, {firstname} {lastname}';
				158	$data = array(
				159	'title' => 'Mr',
				160	'firstname' => 'John',
				161	'lastname' => 'Doe'
				162	);
				163	$this->parser->parse_string($template, $data);
				164
				165	Result: Hello, John Doe
				166
				167	If you do not include a substitution parameter that is referenced in your template, the original
				168	pseudo-variable is shown in the result::
				169
				170	$template = 'Hello, {firstname} {initials} {lastname}';
				171	$data = array(
				172	'title' => 'Mr',
				173	'firstname' => 'John',
				174	'lastname' => 'Doe'
				175	);
				176	$this->parser->parse_string($template, $data);
				177
				178	Result: Hello, John {initials} Doe
				179
				180	If you provide a string substitution parameter when an array is expected, i.e. for a variable pair,
				181	the substitution is done for the opening variable pair tag, but the closing variable pair
				182	tag is not rendered properly::
				183
				184	$template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})';
				185	$data = array(
				186	'degrees' => 'Mr',
				187	'firstname' => 'John',
				188	'lastname' => 'Doe',
				189	'titles' => array(
				190	array('degree' => 'BSc'),
				191	array('degree' => 'PhD')
				192
				193	)
				194	);
				195	$this->parser->parse_string($template, $data);
				196
				197	Result: Hello, John Doe (Mr{degree} {/degrees})
				198
				199	If you name one of your individual substitution parameters the same as one used inside a variable pair, the results
				200	may not be as expected::
				201
				202	$template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})';
				203	$data = array(
				204	'degree' => 'Mr',
				205	'firstname' => 'John',
				206	'lastname' => 'Doe',
				207	'degrees' => array(
				208	array('degree' => 'BSc'),
				209	array('degree' => 'PhD')
				210
				211	)
				212	);
				213	$this->parser->parse_string($template, $data);
				214
				215	Result: Hello, John Doe (Mr Mr )
				216
				217	**************
				218	View Fragments
				219	**************
				220
				221	You do not have to use variable pairs to get the effect of iteration in your views.
				222	It is possible to use a view fragment for what would be inside a variable pair, and to
				223	control the iteration in your controller instead of in the view.
				224
				225	An example with the iteration controlled in the view::
				226
				227	$template = '<ul>{menuitems}<li><a href="{link}">{title}</a></li>{/menuitems}</ul>';
				228	$data = array(
				229	'menuitems' => array(
				230	array('title' => 'First Link', 'link' => '/first'),
				231	array('title' => 'Second Link', 'link' => '/second'),
				232	)
				233	);
				234	$this->parser->parse_string($template, $data);
				235
				236	Result:
				237	- First Link
				238	- Second Link
				239
				240	An example with the iteration controlled in the controller, using a view fragment::
				241
				242	$temp_result = '';
				243	$template1 = '<li><a href="{link}">{title}</a></li>';
				244	$data1 = array(
				245	array('title' => 'First Link', 'link' => '/first'),
				246	array('title' => 'Second Link', 'link' => '/second'),
				247	);
				248	foreach ($data1 as $menuitem) {
				249	$temp_result .= $this->parser->parse_string($template1, $menuitem, TRUE);
				250	}
				251
				252	$template = '<ul>{menuitems}</ul>';
				253	$data = array(
				254	'menuitems' => $temp_result
				255	);
				256	$this->parser->parse_string($template, $data);
				257
				258	Result:
				259	- First Link
				260	- Second Link
				261
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	262	***************
				263	Class Reference
				264	***************
				265
Andrey Andreev	1e58420	2014-02-07 21:50:36 +0200	[diff] [blame]	266	.. class:: CI_Parser
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	267
				268	.. method:: parse($template, $data[, $return = FALSE])
				269
Andrey Andreev	28c2c97	2014-02-08 04:27:48 +0200	[diff] [blame]	270	:param string $template: Path to view file
				271	:param array $data: Variable data
				272	:param bool $return: Whether to only return the parsed template
				273	:returns: Parsed template string
				274	:rtype: string
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	275
				276	Parses a template from the provided path and variables.
				277
				278	.. method:: parse_string($template, $data[, $return = FALSE])
				279
Andrey Andreev	28c2c97	2014-02-08 04:27:48 +0200	[diff] [blame]	280	:param string $template: Path to view file
				281	:param array $data: Variable data
				282	:param bool $return: Whether to only return the parsed template
				283	:returns: Parsed template string
				284	:rtype: string
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	285
				286	This method works exactly like ``parse()``, only it accepts the template as a
				287	string instead of loading a view file.
				288
				289	.. method:: set_delimiters([$l = '{'[, $r = '}']])
				290
Andrey Andreev	28c2c97	2014-02-08 04:27:48 +0200	[diff] [blame]	291	:param string $l: Left delimiter
				292	:param string $r: Right delimiter
				293	:rtype: void
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	294
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame^]	295	Sets the delimiters (opening and closing) for a pseudo-variable "tag" in a template.