diff options
| author | James L Parry <jim_parry@bcit.ca> | 2014-11-24 18:51:33 +0100 |
|---|---|---|
| committer | James L Parry <jim_parry@bcit.ca> | 2014-11-24 18:51:33 +0100 |
| commit | dd73ea53f2d23379cb0dd74ccfa5f697c15b3299 (patch) | |
| tree | 276144be8d048df7d4fa95d351ae7223196f2b4f /user_guide_src/source | |
| parent | 09ada67ddf7c320b625905ebb12b2878e23401f7 (diff) | |
Enhance Template Parser Class Writeup in User Guide
Added two additional sections to the writeup: template parser usage notes, and view fragments.
Clarified a couple of "pseudo-variable" references.
Verified sphinx build.
Signed-off-by:James L Parry <jim_parry@bcit.ca>
Diffstat (limited to 'user_guide_src/source')
| -rw-r--r-- | user_guide_src/source/libraries/parser.rst | 182 |
1 files changed, 149 insertions, 33 deletions
diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst index 5af504a03..23b2492c9 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 +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-variables look like this:: +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 @@ -42,8 +44,9 @@ representations that allow you to eliminate PHP from your templates <div class="custom-index container"></div> +********************** Initializing the Class -====================== +********************** Like most other classes in CodeIgniter, the Parser class is initialized in your controller using the $this->load->library function:: @@ -53,8 +56,9 @@ in your controller using the $this->load->library function:: Once loaded, the Parser library object will be available using: $this->parser +***************** Parsing templates -================= +***************** You can use the ``parse()`` method to parse (or render) simple templates, like this:: @@ -74,13 +78,14 @@ 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); +************** Variable Pairs -============== +************** The above example code allows simple variables to be replaced. What if you would like an entire block of variables to be repeated, with each @@ -88,24 +93,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 @@ -143,6 +148,117 @@ function:: $this->parser->parse('blog_template', $data); +*************************** +Template Parser 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_result = ''; + $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_result .= $this->parser->parse_string($template1, $menuitem, TRUE); + } + + $template = '<ul>{menuitems}</ul>'; + $data = array( + 'menuitems' => $temp_result + ); + $this->parser->parse_string($template, $data); + + Result: + - First Link + - Second Link + *************** Class Reference *************** @@ -176,4 +292,4 @@ 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 |