diff options
Diffstat (limited to 'user_guide_src/source/libraries/parser.rst')
| -rw-r--r-- | user_guide_src/source/libraries/parser.rst | 309 |
1 files changed, 0 insertions, 309 deletions
diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst deleted file mode 100644 index 6c9d28959..000000000 --- a/user_guide_src/source/libraries/parser.rst +++ /dev/null @@ -1,309 +0,0 @@ -##################### -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. - -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> - </html> - -These variables are not actual PHP variables, but rather plain text -representations that allow you to eliminate PHP from your templates -(view files). - -.. 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. - -.. important:: The Template Parser Class is **not** a full-blown - template parsing solution. We've kept it very lean on purpose in order - to maintain maximum performance. - -.. contents:: - :local: - -.. raw:: html - - <div class="custom-index container"></div> - -******************************* -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()`` method:: - - $this->load->library('parser'); - -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:: - - $data = array( - 'blog_title' => 'My Blog Title', - 'blog_heading' => 'My Blog Heading' - ); - - $this->parser->parse('blog_template', $data); - -The first parameter contains the name of the :doc:`view -file <../general/views>` (in this example the file would be called -blog_template.php), and the second parameter contains an associative -array of data to be replaced in the template. In the above example, the -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) 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 -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> - </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 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 -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') - ) - ); - - $this->parser->parse('blog_template', $data); - -If your "pair" data is coming from a database result, which is already a -multi-dimensional array, you can simply use the database ``result_array()`` -method:: - - $query = $this->db->query("SELECT * FROM blog"); - - $this->load->library('parser'); - - $data = 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:: - - <ul> - <li><a href="/first">First Link</a></li> - <li><a href="/second">Second Link</a></li> - </ul> - -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:: - - <ul> - <li><a href="/first">First Link</a></li> - <li><a href="/second">Second Link</a></li> - </ul> - -*************** -Class Reference -*************** - -.. php:class:: CI_Parser - - .. php:method:: parse($template, $data[, $return = FALSE]) - - :param string $template: Path to view file - :param array $data: Variable data - :param bool $return: Whether to only return the parsed template - :returns: Parsed template string - :rtype: string - - Parses a template from the provided path and variables. - - .. php:method:: parse_string($template, $data[, $return = FALSE]) - - :param string $template: Path to view file - :param array $data: Variable data - :param bool $return: Whether to only return the parsed template - :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. - - .. php:method:: set_delimiters([$l = '{'[, $r = '}']]) - - :param string $l: Left delimiter - :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 |