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

blob: 5c184be5879da80aeea483a8a9e6ba96622e4333 [file] [log] [blame]

Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	1	#####################
				2	Template Parser Class
				3	#####################
				4
				5	The Template Parser Class enables you to parse pseudo-variables
				6	contained within your view files. It can parse simple variables or
				7	variable tag pairs. If you've never used a template engine,
				8	pseudo-variables look like this::
				9
Derek Jones	eb946d0	2011-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 Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	24
				25	These variables are not actual PHP variables, but rather plain text
				26	representations 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
				38	Initializing the Class
				39	======================
				40
				41	Like most other classes in CodeIgniter, the Parser class is initialized
				42	in your controller using the $this->load->library function::
				43
				44	$this->load->library('parser');
				45
				46	Once loaded, the Parser library object will be available using:
				47	$this->parser
				48
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame^]	49	Parsing templates
				50	=================
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	51
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame^]	52	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]	53
				54	$data = array(
				55	'blog_title' => 'My Blog Title',
				56	'blog_heading' => 'My Blog Heading'
				57	);
				58
				59	$this->parser->parse('blog_template', $data);
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	60
				61	The first parameter contains the name of the :doc:`view
				62	file <../general/views>` (in this example the file would be called
				63	blog_template.php), and the second parameter contains an associative
				64	array of data to be replaced in the template. In the above example, the
				65	template would contain two variables: {blog_title} and {blog_heading}
				66
				67	There is no need to "echo" or do something with the data returned by
				68	$this->parser->parse(). It is automatically passed to the output class
				69	to be sent to the browser. However, if you do want the data returned
				70	instead of sent to the output class you can pass TRUE (boolean) to the
				71	third parameter::
				72
				73	$string = $this->parser->parse('blog_template', $data, TRUE);
				74
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	75	Variable Pairs
				76	==============
				77
				78	The above example code allows simple variables to be replaced. What if
				79	you would like an entire block of variables to be repeated, with each
				80	iteration containing new values? Consider the template example we showed
				81	at the top of the page::
				82
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	83	<html>
				84	<head>
				85	<title>{blog_title}</title>
				86	</head>
				87	<body>
				88
				89	<h3>{blog_heading}</h3>
				90
				91	{blog_entries}
				92	<h5>{title}</h5>
				93	<p>{body}</p>
				94	{/blog_entries}
				95	</body>
				96	</html>
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	97
				98	In the above code you'll notice a pair of variables: {blog_entries}
				99	data... {/blog_entries}. In a case like this, the entire chunk of data
				100	between these pairs would be repeated multiple times, corresponding to
				101	the number of rows in a result.
				102
				103	Parsing variable pairs is done using the identical code shown above to
				104	parse single variables, except, you will add a multi-dimensional array
				105	corresponding to your variable pair data. Consider this example::
				106
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	107	$this->load->library('parser');
				108
				109	$data = array(
				110	'blog_title' => 'My Blog Title',
				111	'blog_heading' => 'My Blog Heading',
				112	'blog_entries' => array(
				113	array('title' => 'Title 1', 'body' => 'Body 1'),
				114	array('title' => 'Title 2', 'body' => 'Body 2'),
				115	array('title' => 'Title 3', 'body' => 'Body 3'),
				116	array('title' => 'Title 4', 'body' => 'Body 4'),
				117	array('title' => 'Title 5', 'body' => 'Body 5')
				118	)
				119	);
				120
				121	$this->parser->parse('blog_template', $data);
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	122
				123	If your "pair" data is coming from a database result, which is already a
				124	multi-dimensional array, you can simply use the database result_array()
				125	function::
				126
Derek Jones	eb946d0	2011-10-05 15:47:43 -0500	[diff] [blame]	127	$query = $this->db->query("SELECT * FROM blog");
				128
				129	$this->load->library('parser');
				130
				131	$data = array(
				132	'blog_title' => 'My Blog Title',
				133	'blog_heading' => 'My Blog Heading',
				134	'blog_entries' => $query->result_array()
				135	);
				136
				137	$this->parser->parse('blog_template', $data);
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	138
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame^]	139	***************
				140	Class Reference
				141	***************
				142
				143	.. class: CI_Parser
				144
				145	.. method:: parse($template, $data[, $return = FALSE])
				146
				147	:param string $template: Path to view file
				148	:param array $data: Variable data
				149	:param bool $return: Whether to return the parsed template
				150	:returns: mixed
				151
				152	Parses a template from the provided path and variables.
				153
				154	.. method:: parse_string($template, $data[, $return = FALSE])
				155
				156	:param string $template: Path to view file
				157	:param array $data: Variable data
				158	:param bool $return: Whether to return the parsed template
				159	:returns: mixed
				160
				161	This method works exactly like ``parse()``, only it accepts the template as a
				162	string instead of loading a view file.
				163
				164	.. method:: set_delimiters([$l = '{'[, $r = '}']])
				165
				166	:param string $l: Left delimiter
				167	:param string $r: Right delimiter
				168	:returns: void
				169
				170	Sets the delimiters (opening and closing) for a value "tag" in a template.