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

blob: 6c9d2895918fa95205506f42f477f73aa3b4a04e [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>
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	13	<head>
				14	<title>{blog_title}</title>
				15	</head>
				16	<body>
				17	<h3>{blog_heading}</h3>
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	18
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	19	{blog_entries}
				20	<h5>{title}</h5>
				21	<p>{body}</p>
				22	{/blog_entries}
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	23
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	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.
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	33	However, some developers prefer to use a template engine if
				34	they work with designers who they feel would find some
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	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
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	56	in your controller using the ``$this->load->library()`` method::
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	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
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	66	You can use the ``parse()`` method to parse (or render) simple templates,
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	67	like this::
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	68
				69	$data = array(
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	70	'blog_title' => 'My Blog Title',
				71	'blog_heading' => 'My Blog Heading'
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	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>
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	99	<head>
				100	<title>{blog_title}</title>
				101	</head>
				102	<body>
				103	<h3>{blog_heading}</h3>
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	104
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	105	{blog_entries}
				106	<h5>{title}</h5>
				107	<p>{body}</p>
				108	{/blog_entries}
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	109
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	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(
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[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	)
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	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
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	139	multi-dimensional array, you can simply use the database ``result_array()``
				140	method::
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	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(
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	147	'blog_title' => 'My Blog Title',
				148	'blog_heading' => 'My Blog Heading',
				149	'blog_entries' => $query->result_array()
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	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
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	157	If you include substitution parameters that are not referenced in your
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	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(
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	162	'title' => 'Mr',
				163	'firstname' => 'John',
				164	'lastname' => 'Doe'
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	165	);
				166	$this->parser->parse_string($template, $data);
				167
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	168	// Result: Hello, John Doe
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	169
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	170	If you do not include a substitution parameter that is referenced in your
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	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(
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	175	'title' => 'Mr',
				176	'firstname' => 'John',
				177	'lastname' => 'Doe'
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	178	);
				179	$this->parser->parse_string($template, $data);
				180
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	181	// Result: Hello, John {initials} Doe
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	182
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	183	If you provide a string substitution parameter when an array is expected,
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	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(
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	189	'degrees' => 'Mr',
				190	'firstname' => 'John',
				191	'lastname' => 'Doe',
				192	'titles' => array(
				193	array('degree' => 'BSc'),
				194	array('degree' => 'PhD')
				195	)
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	196	);
				197	$this->parser->parse_string($template, $data);
				198
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	199	// Result: Hello, John Doe (Mr{degree} {/degrees})
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	200
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	201	If you name one of your individual substitution parameters the same as one
				202	used inside a variable pair, the results may not be as expected::
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	203
				204	$template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})';
				205	$data = array(
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	206	'degree' => 'Mr',
				207	'firstname' => 'John',
				208	'lastname' => 'Doe',
				209	'degrees' => array(
				210	array('degree' => 'BSc'),
				211	array('degree' => 'PhD')
				212	)
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	213	);
				214	$this->parser->parse_string($template, $data);
				215
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	216	// Result: Hello, John Doe (Mr Mr )
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	217
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	218	View Fragments
James L Parry	307663f	2014-11-24 10:59:09 -0800	[diff] [blame]	219	==============
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	220
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	221	You do not have to use variable pairs to get the effect of iteration in
				222	your views. It is possible to use a view fragment for what would be inside
				223	a variable pair, and to control the iteration in your controller instead
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	224	of in the view.
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	225
				226	An example with the iteration controlled in the view::
				227
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	228	$template = '<ul>{menuitems}
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	229	<li><a href="{link}">{title}</a></li>
				230	{/menuitems}</ul>';
				231
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	232	$data = array(
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	233	'menuitems' => array(
				234	array('title' => 'First Link', 'link' => '/first'),
				235	array('title' => 'Second Link', 'link' => '/second'),
				236	)
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	237	);
				238	$this->parser->parse_string($template, $data);
				239
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	240	Result::
				241
				242	<ul>
				243	<li><a href="/first">First Link</a></li>
				244	<li><a href="/second">Second Link</a></li>
				245	</ul>
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	246
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	247	An example with the iteration controlled in the controller,
				248	using a view fragment::
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	249
James L Parry	def2c8f	2014-11-24 10:56:45 -0800	[diff] [blame]	250	$temp = '';
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	251	$template1 = '<li><a href="{link}">{title}</a></li>';
				252	$data1 = array(
				253	array('title' => 'First Link', 'link' => '/first'),
				254	array('title' => 'Second Link', 'link' => '/second'),
				255	);
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	256
				257	foreach ($data1 as $menuitem)
				258	{
				259	$temp .= $this->parser->parse_string($template1, $menuitem, TRUE);
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	260	}
				261
				262	$template = '<ul>{menuitems}</ul>';
				263	$data = array(
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	264	'menuitems' => $temp
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	265	);
				266	$this->parser->parse_string($template, $data);
				267
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	268	Result::
				269
				270	<ul>
				271	<li><a href="/first">First Link</a></li>
				272	<li><a href="/second">Second Link</a></li>
				273	</ul>
James L Parry	dd73ea5	2014-11-24 09:51:33 -0800	[diff] [blame]	274
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	275	***************
				276	Class Reference
				277	***************
				278
Andrey Andreev	cd3d9db	2015-02-02 13:41:01 +0200	[diff] [blame]	279	.. php:class:: CI_Parser
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	280
Andrey Andreev	cd3d9db	2015-02-02 13:41:01 +0200	[diff] [blame]	281	.. php:method:: parse($template, $data[, $return = FALSE])
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	282
Andrey Andreev	28c2c97	2014-02-08 04:27:48 +0200	[diff] [blame]	283	:param string $template: Path to view file
				284	:param array $data: Variable data
				285	:param bool $return: Whether to only return the parsed template
				286	:returns: Parsed template string
				287	:rtype: string
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	288
				289	Parses a template from the provided path and variables.
				290
Andrey Andreev	cd3d9db	2015-02-02 13:41:01 +0200	[diff] [blame]	291	.. php:method:: parse_string($template, $data[, $return = FALSE])
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	292
Andrey Andreev	28c2c97	2014-02-08 04:27:48 +0200	[diff] [blame]	293	:param string $template: Path to view file
				294	:param array $data: Variable data
				295	:param bool $return: Whether to only return the parsed template
				296	:returns: Parsed template string
				297	:rtype: string
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	298
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	299	This method works exactly like ``parse()``, only it accepts
				300	the template as a string instead of loading a view file.
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	301
Andrey Andreev	cd3d9db	2015-02-02 13:41:01 +0200	[diff] [blame]	302	.. php:method:: set_delimiters([$l = '{'[, $r = '}']])
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	303
Andrey Andreev	28c2c97	2014-02-08 04:27:48 +0200	[diff] [blame]	304	:param string $l: Left delimiter
				305	:param string $r: Right delimiter
				306	:rtype: void
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	307
Andrey Andreev	f3f06f2	2014-12-04 16:54:07 +0200	[diff] [blame]	308	Sets the delimiters (opening and closing) for a
				309	pseudo-variable "tag" in a template.