From dd73ea53f2d23379cb0dd74ccfa5f697c15b3299 Mon Sep 17 00:00:00 2001 From: James L Parry Date: Mon, 24 Nov 2014 09:51:33 -0800 Subject: 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 --- user_guide_src/source/libraries/parser.rst | 182 +++++++++++++++++++++++------ 1 file 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:: - - {blog_title} - - - -

{blog_heading}

- - {blog_entries} -
{title}
-

{body}

- {/blog_entries} - + + {blog_title} + + + +

{blog_heading}

+ + {blog_entries} +
{title}
+

{body}

+ {/blog_entries} + 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
+********************** 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:: - - {blog_title} - - - -

{blog_heading}

- - {blog_entries} -
{title}
-

{body}

- {/blog_entries} - + + {blog_title} + + + +

{blog_heading}

+ + {blog_entries} +
{title}
+

{body}

+ {/blog_entries} + 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 = ''; + $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 = '
  • {title}
    • '; + $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 = ''; + $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 -- cgit v1.2.3-24-g4f1b From def2c8f1c39e7543d02411ee7228489c758ebb8e Mon Sep 17 00:00:00 2001 From: James L Parry Date: Mon, 24 Nov 2014 10:56:45 -0800 Subject: Fixed the convention violations. Changed the HTML example formatting to use tabs instead of spaces. Adjusted line lengths. Verified sphinx build. Signed-off-by:James L Parry --- user_guide_src/source/libraries/parser.rst | 139 +++++++++++++++-------------- 1 file changed, 74 insertions(+), 65 deletions(-) diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst index 23b2492c9..7c690ac2a 100644 --- a/user_guide_src/source/libraries/parser.rst +++ b/user_guide_src/source/libraries/parser.rst @@ -2,26 +2,26 @@ Template Parser Class ##################### -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. +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:: - - {blog_title} - - - -

    {blog_heading}

    - - {blog_entries} -
    {title}
    -

    {body}

    - {/blog_entries} - + + {blog_title} + + + +

    {blog_heading}

    + + {blog_entries} +
    {title}
    +

    {body}

    + {/blog_entries} + These variables are not actual PHP variables, but rather plain text @@ -30,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 @@ -60,12 +61,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); @@ -93,18 +95,18 @@ iteration containing new values? Consider the template example we showed at the top of the page:: - - {blog_title} - - - -

    {blog_heading}

    - - {blog_entries} -
    {title}
    -

    {body}

    - {/blog_entries} - + + {blog_title} + + + +

    {blog_heading}

    + + {blog_entries} +
    {title}
    +

    {body}

    + {/blog_entries} + In the above code you'll notice a pair of variables: {blog_entries} @@ -119,16 +121,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); @@ -141,10 +143,10 @@ 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); @@ -152,7 +154,8 @@ function:: Template Parser Usage Notes *************************** -If you include substitution parameters that are not referenced in your template, they are ignored:: +If you include substitution parameters that are not referenced in your +template, they are ignored:: $template = 'Hello, {firstname} {lastname}'; $data = array( @@ -164,8 +167,8 @@ If you include substitution parameters that are not referenced in your template, 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:: +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( @@ -177,9 +180,9 @@ pseudo-variable is shown in the result:: 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:: +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( @@ -196,7 +199,8 @@ tag is not rendered properly:: 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 +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})'; @@ -218,13 +222,16 @@ may not be as expected:: 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. +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 = ''; + $template = '
      {menuitems} +
    • {title}
      • + {/menuitems}
    '; $data = array( 'menuitems' => array( array('title' => 'First Link', 'link' => '/first'), @@ -237,21 +244,22 @@ An example with the iteration controlled in the view:: - First Link - Second Link -An example with the iteration controlled in the controller, using a view fragment:: +An example with the iteration controlled in the controller, +using a view fragment:: - $temp_result = ''; + $temp = ''; $template1 = '
  • {title}
    • '; $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); + $temp .= $this->parser->parse_string($template1, $menuitem, TRUE); } $template = '
      {menuitems}
    '; $data = array( - 'menuitems' => $temp_result + 'menuitems' => $temp ); $this->parser->parse_string($template, $data); @@ -283,8 +291,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 = '}']]) @@ -292,4 +300,5 @@ Class Reference :param string $r: Right delimiter :rtype: void - Sets the delimiters (opening and closing) for a pseudo-variable "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 -- cgit v1.2.3-24-g4f1b From 307663f2c05f5800c4e17fe8eff9b329bbcb8fa8 Mon Sep 17 00:00:00 2001 From: James L Parry Date: Mon, 24 Nov 2014 10:59:09 -0800 Subject: Fixed the convention violations. Changed the section/subsection treatment Verified sphinx build. Signed-off-by:James L Parry --- user_guide_src/source/libraries/parser.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst index 7c690ac2a..e7c7e3abd 100644 --- a/user_guide_src/source/libraries/parser.rst +++ b/user_guide_src/source/libraries/parser.rst @@ -45,9 +45,12 @@ representations that allow you to eliminate PHP from your templates
    -********************** +******************************* +Using the Template Parser Class +******************************* + Initializing the Class -********************** +====================== Like most other classes in CodeIgniter, the Parser class is initialized in your controller using the $this->load->library function:: @@ -57,9 +60,8 @@ 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:: @@ -85,9 +87,8 @@ 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 @@ -150,9 +151,8 @@ function:: $this->parser->parse('blog_template', $data); -*************************** -Template Parser Usage Notes -*************************** +Usage Notes +=========== If you include substitution parameters that are not referenced in your template, they are ignored:: @@ -218,9 +218,8 @@ may not be as expected:: 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 -- cgit v1.2.3-24-g4f1b