summaryrefslogtreecommitdiffstats
path: root/user_guide_src
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2014-11-24 20:07:04 +0100
committerAndrey Andreev <narf@devilix.net>2014-11-24 20:07:04 +0100
commit8371eb1f77b0a325cb89ad437d572ef1b94f5cf4 (patch)
tree1532d0738500a88f90a02de1c5c8818460ba478c /user_guide_src
parent09ada67ddf7c320b625905ebb12b2878e23401f7 (diff)
parent307663f2c05f5800c4e17fe8eff9b329bbcb8fa8 (diff)
Merge pull request #3365 from jim-parry/userguide/parser
Enhance Template Parser Class Writeup in User Guide
Diffstat (limited to 'user_guide_src')
-rw-r--r--user_guide_src/source/libraries/parser.rst230
1 files changed, 177 insertions, 53 deletions
diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst
index 5af504a03..e7c7e3abd 100644
--- a/user_guide_src/source/libraries/parser.rst
+++ b/user_guide_src/source/libraries/parser.rst
@@ -2,24 +2,26 @@
Template Parser Class
#####################
-The Template Parser Class enables you to parse pseudo-variables
-contained within your view files. It can parse simple variables or
-variable tag pairs. If you've never used a template engine,
-pseudo-variables look like this::
+The Template Parser Class can perform simple text substitution for
+pseudo-variables contained within your view files.
+It can parse simple variables or variable tag pairs.
+
+If you've never used a template engine,
+pseudo-variable names are enclosed in braces, like this::
<html>
- <head>
- <title>{blog_title}</title>
- </head>
- <body>
-
- <h3>{blog_heading}</h3>
-
- {blog_entries}
- <h5>{title}</h5>
- <p>{body}</p>
- {/blog_entries}
- </body>
+ <head>
+ <title>{blog_title}</title>
+ </head>
+ <body>
+
+ <h3>{blog_heading}</h3>
+
+ {blog_entries}
+ <h5>{title}</h5>
+ <p>{body}</p>
+ {/blog_entries}
+ </body>
</html>
These variables are not actual PHP variables, but rather plain text
@@ -28,8 +30,9 @@ representations that allow you to eliminate PHP from your templates
.. note:: CodeIgniter does **not** require you to use this class since
using pure PHP in your view pages lets them run a little faster.
- However, some developers prefer to use a template engine if they work
- with designers who they feel would find some confusion working with PHP.
+ However, some developers prefer to use a template engine if
+ they work with designers who they feel would find some
+ confusion working with PHP.
.. important:: The Template Parser Class is **not** a full-blown
template parsing solution. We've kept it very lean on purpose in order
@@ -42,6 +45,10 @@ representations that allow you to eliminate PHP from your templates
<div class="custom-index container"></div>
+*******************************
+Using the Template Parser Class
+*******************************
+
Initializing the Class
======================
@@ -56,12 +63,13 @@ $this->parser
Parsing templates
=================
-You can use the ``parse()`` method to parse (or render) simple templates, like this::
+You can use the ``parse()`` method to parse (or render) simple templates,
+like this::
$data = array(
- 'blog_title' => 'My Blog Title',
- 'blog_heading' => 'My Blog Heading'
- );
+ 'blog_title' => 'My Blog Title',
+ 'blog_heading' => 'My Blog Heading'
+ );
$this->parser->parse('blog_template', $data);
@@ -74,7 +82,7 @@ template would contain two variables: {blog_title} and {blog_heading}
There is no need to "echo" or do something with the data returned by
$this->parser->parse(). It is automatically passed to the output class
to be sent to the browser. However, if you do want the data returned
-instead of sent to the output class you can pass TRUE (boolean) to the
+instead of sent to the output class you can pass TRUE (boolean) as the
third parameter::
$string = $this->parser->parse('blog_template', $data, TRUE);
@@ -88,24 +96,24 @@ iteration containing new values? Consider the template example we showed
at the top of the page::
<html>
- <head>
- <title>{blog_title}</title>
- </head>
- <body>
-
- <h3>{blog_heading}</h3>
-
- {blog_entries}
- <h5>{title}</h5>
- <p>{body}</p>
- {/blog_entries}
- </body>
+ <head>
+ <title>{blog_title}</title>
+ </head>
+ <body>
+
+ <h3>{blog_heading}</h3>
+
+ {blog_entries}
+ <h5>{title}</h5>
+ <p>{body}</p>
+ {/blog_entries}
+ </body>
</html>
In the above code you'll notice a pair of variables: {blog_entries}
data... {/blog_entries}. In a case like this, the entire chunk of data
between these pairs would be repeated multiple times, corresponding to
-the number of rows in a result.
+the number of rows in the "blog_entries" element of the parameters array.
Parsing variable pairs is done using the identical code shown above to
parse single variables, except, you will add a multi-dimensional array
@@ -114,16 +122,16 @@ corresponding to your variable pair data. Consider this example::
$this->load->library('parser');
$data = array(
- 'blog_title' => 'My Blog Title',
- 'blog_heading' => 'My Blog Heading',
- 'blog_entries' => array(
- array('title' => 'Title 1', 'body' => 'Body 1'),
- array('title' => 'Title 2', 'body' => 'Body 2'),
- array('title' => 'Title 3', 'body' => 'Body 3'),
- array('title' => 'Title 4', 'body' => 'Body 4'),
- array('title' => 'Title 5', 'body' => 'Body 5')
- )
- );
+ 'blog_title' => 'My Blog Title',
+ 'blog_heading' => 'My Blog Heading',
+ 'blog_entries' => array(
+ array('title' => 'Title 1', 'body' => 'Body 1'),
+ array('title' => 'Title 2', 'body' => 'Body 2'),
+ array('title' => 'Title 3', 'body' => 'Body 3'),
+ array('title' => 'Title 4', 'body' => 'Body 4'),
+ array('title' => 'Title 5', 'body' => 'Body 5')
+ )
+ );
$this->parser->parse('blog_template', $data);
@@ -136,13 +144,128 @@ function::
$this->load->library('parser');
$data = array(
- 'blog_title' => 'My Blog Title',
- 'blog_heading' => 'My Blog Heading',
- 'blog_entries' => $query->result_array()
- );
+ 'blog_title' => 'My Blog Title',
+ 'blog_heading' => 'My Blog Heading',
+ 'blog_entries' => $query->result_array()
+ );
$this->parser->parse('blog_template', $data);
+Usage Notes
+===========
+
+If you include substitution parameters that are not referenced in your
+template, they are ignored::
+
+ $template = 'Hello, {firstname} {lastname}';
+ $data = array(
+ 'title' => 'Mr',
+ 'firstname' => 'John',
+ 'lastname' => 'Doe'
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result: Hello, John Doe
+
+If you do not include a substitution parameter that is referenced in your
+template, the original pseudo-variable is shown in the result::
+
+ $template = 'Hello, {firstname} {initials} {lastname}';
+ $data = array(
+ 'title' => 'Mr',
+ 'firstname' => 'John',
+ 'lastname' => 'Doe'
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result: Hello, John {initials} Doe
+
+If you provide a string substitution parameter when an array is expected,
+i.e. for a variable pair, the substitution is done for the opening variable
+pair tag, but the closing variable pair tag is not rendered properly::
+
+ $template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})';
+ $data = array(
+ 'degrees' => 'Mr',
+ 'firstname' => 'John',
+ 'lastname' => 'Doe',
+ 'titles' => array(
+ array('degree' => 'BSc'),
+ array('degree' => 'PhD')
+
+ )
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result: Hello, John Doe (Mr{degree} {/degrees})
+
+If you name one of your individual substitution parameters the same as one
+used inside a variable pair, the results
+may not be as expected::
+
+ $template = 'Hello, {firstname} {lastname} ({degrees}{degree} {/degrees})';
+ $data = array(
+ 'degree' => 'Mr',
+ 'firstname' => 'John',
+ 'lastname' => 'Doe',
+ 'degrees' => array(
+ array('degree' => 'BSc'),
+ array('degree' => 'PhD')
+
+ )
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result: Hello, John Doe (Mr Mr )
+
+View Fragments
+==============
+
+You do not have to use variable pairs to get the effect of iteration in
+your views. It is possible to use a view fragment for what would be inside
+a variable pair, and to control the iteration in your controller instead
+of in the view.
+
+An example with the iteration controlled in the view::
+
+ $template = '<ul>{menuitems}
+ <li><a href="{link}">{title}</a></li>
+ {/menuitems}</ul>';
+ $data = array(
+ 'menuitems' => array(
+ array('title' => 'First Link', 'link' => '/first'),
+ array('title' => 'Second Link', 'link' => '/second'),
+ )
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result:
+ - First Link
+ - Second Link
+
+An example with the iteration controlled in the controller,
+using a view fragment::
+
+ $temp = '';
+ $template1 = '<li><a href="{link}">{title}</a></li>';
+ $data1 = array(
+ array('title' => 'First Link', 'link' => '/first'),
+ array('title' => 'Second Link', 'link' => '/second'),
+ );
+ foreach ($data1 as $menuitem) {
+ $temp .= $this->parser->parse_string($template1, $menuitem, TRUE);
+ }
+
+ $template = '<ul>{menuitems}</ul>';
+ $data = array(
+ 'menuitems' => $temp
+ );
+ $this->parser->parse_string($template, $data);
+
+ Result:
+ - First Link
+ - Second Link
+
***************
Class Reference
***************
@@ -167,8 +290,8 @@ Class Reference
:returns: Parsed template string
:rtype: string
- This method works exactly like ``parse()``, only it accepts the template as a
- string instead of loading a view file.
+ This method works exactly like ``parse()``, only it accepts
+ the template as a string instead of loading a view file.
.. method:: set_delimiters([$l = '{'[, $r = '}']])
@@ -176,4 +299,5 @@ Class Reference
:param string $r: Right delimiter
:rtype: void
- Sets the delimiters (opening and closing) for a value "tag" in a template. \ No newline at end of file
+ Sets the delimiters (opening and closing) for a
+ pseudo-variable "tag" in a template. \ No newline at end of file