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

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