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

blob: 5af504a03f88b15ee2cfe36638bfb9eae7536145 [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
Andrey Andreev	cc04209	2014-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 Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	45	Initializing the Class
				46	======================
				47
				48	Like most other classes in CodeIgniter, the Parser class is initialized
				49	in your controller using the $this->load->library function::
				50
				51	$this->load->library('parser');
				52
				53	Once loaded, the Parser library object will be available using:
				54	$this->parser
				55
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	56	Parsing templates
				57	=================
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	58
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	59	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]	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 Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	67
				68	The first parameter contains the name of the :doc:`view
				69	file <../general/views>` (in this example the file would be called
				70	blog_template.php), and the second parameter contains an associative
				71	array of data to be replaced in the template. In the above example, the
				72	template would contain two variables: {blog_title} and {blog_heading}
				73
				74	There 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
				76	to be sent to the browser. However, if you do want the data returned
				77	instead of sent to the output class you can pass TRUE (boolean) to the
				78	third parameter::
				79
				80	$string = $this->parser->parse('blog_template', $data, TRUE);
				81
Derek Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	82	Variable Pairs
				83	==============
				84
				85	The above example code allows simple variables to be replaced. What if
				86	you would like an entire block of variables to be repeated, with each
				87	iteration containing new values? Consider the template example we showed
				88	at the top of the page::
				89
Derek Jones	eb946d0	2011-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 Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	104
				105	In the above code you'll notice a pair of variables: {blog_entries}
				106	data... {/blog_entries}. In a case like this, the entire chunk of data
				107	between these pairs would be repeated multiple times, corresponding to
				108	the number of rows in a result.
				109
				110	Parsing variable pairs is done using the identical code shown above to
				111	parse single variables, except, you will add a multi-dimensional array
				112	corresponding to your variable pair data. Consider this example::
				113
Derek Jones	eb946d0	2011-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 Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	129
				130	If your "pair" data is coming from a database result, which is already a
				131	multi-dimensional array, you can simply use the database result_array()
				132	function::
				133
Derek Jones	eb946d0	2011-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 Jones	8ede1a2	2011-10-05 13:34:52 -0500	[diff] [blame]	145
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	146	***************
				147	Class Reference
				148	***************
				149
Andrey Andreev	1e58420	2014-02-07 21:50:36 +0200	[diff] [blame]	150	.. class:: CI_Parser
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	151
				152	.. method:: parse($template, $data[, $return = FALSE])
				153
Andrey Andreev	28c2c97	2014-02-08 04:27:48 +0200	[diff] [blame]	154	:param string $template: Path to view file
				155	:param array $data: Variable data
				156	:param bool $return: Whether to only return the parsed template
				157	:returns: Parsed template string
				158	:rtype: string
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	159
				160	Parses a template from the provided path and variables.
				161
				162	.. method:: parse_string($template, $data[, $return = FALSE])
				163
Andrey Andreev	28c2c97	2014-02-08 04:27:48 +0200	[diff] [blame]	164	:param string $template: Path to view file
				165	:param array $data: Variable data
				166	:param bool $return: Whether to only return the parsed template
				167	:returns: Parsed template string
				168	:rtype: string
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	169
				170	This method works exactly like ``parse()``, only it accepts the template as a
				171	string instead of loading a view file.
				172
				173	.. method:: set_delimiters([$l = '{'[, $r = '}']])
				174
Andrey Andreev	28c2c97	2014-02-08 04:27:48 +0200	[diff] [blame]	175	:param string $l: Left delimiter
				176	:param string $r: Right delimiter
				177	:rtype: void
Andrey Andreev	8da2e22	2014-01-03 12:47:37 +0200	[diff] [blame]	178
				179	Sets the delimiters (opening and closing) for a value "tag" in a template.