PEAR Manual
PrevChapter 44. HTMLNext

HTML_Template_PHPLIB

HTML_Template_PHPLIB is the PEARified version of the once-so-famous PHPLIB template class. It provides variables and repeatable blocks. The original PHPLIB code can be found at phplib.sf.net.

Concept

When using HTML_Template_PHPLIB to generate HTML or other code from templates, you do the following steps:

  1. Create template class instance

  2. Load template file

  3. Define blocks

  4. Set variables, parse blocks

  5. Finish and output

Variables are placeholders in your HTML code that can be replaced with dynamic values provided from database or calculated in your code. An example for a variable is {CODE_AUTHOR}: You enclose the variable name in curly braces. The name of the variable may contain any characters, except spaces, tabs and newlines.

Blocks surround certain pieces of HTML code and can be re-used, e.g. a <tr>row in a table. Blocks are defined by using HTML comments, containing BEGIN or END, and the block name. Example: 
<table>
 <caption>Authors</caption>
 <thead>
  <tr><th>Name</th><th>Email</th></tr>
 </thead>
 <tbody>
<!-- BEGIN authorline -->
  <tr><td>{AUTHOR_NAME}</td><td>{AUTHOR_EMAIL}</td></tr>
<!-- END authorline -->
 </tbody>
</table>

Simple example

Example 44-139. Template file: authors.tpl

<html>
 <head><title>{PAGE_TITLE}</title></head>
 <body>
  <table>
   <caption>Authors</caption>
   <thead>
    <tr><th>Name</th><th>Email</th></tr>
   </thead>
   <tfoot>
    <tr><td colspan="2">{NUM_AUTHORS}</td></tr>
   </tfoot>
   <tbody>
<!-- BEGIN authorline -->
    <tr><td>{AUTHOR_NAME}</td><td>{AUTHOR_EMAIL}</td></tr>
<!-- END authorline -->
   </tbody>
  </table>
 </body>
</html>

Example 44-140. PHP code: authors.php

<?php
//we want to display this author list
$authors = array(
    'Christian Weiske'  => 'cweiske@php.net',
    'Bjoern Schotte'     => 'schotte@mayflower.de'
);

require_once 'HTML/Template/PHPLIB.php';
//create template object
$t =& new HTML_Template_PHPLIB(dirname(__FILE__), 'keep');
//load file
$t->setFile('authors', 'authors.tpl');
//set block
$t->setBlock('authors', 'authorline', 'authorline_ref');

//set some variables
$t->setVar('NUM_AUTHORS', count($authors));
$t->setVar('PAGE_TITLE', 'Code authors as of ' . date('Y-m-d'));

//display the authors
foreach ($authors as $name => $email) {
    $t->setVar('AUTHOR_NAME', $name);
    $t->setVar('AUTHOR_EMAIL', $email);
    $t->parse('authorline_ref', 'authorline', true);
}

//finish and echo
echo $t->finish($t->parse('OUT', 'authors'));
?>

Loading files

Template file locations are relative to a definable root directory. You can specify it directly in the constructor (first parameter, defaults to .) or via setRoot().

Files are referenced via handle names. Thus you need to specify the handle name as first parameter, and the file's name as second parameter when calling setFile(). To speed things up, you may pass an array of handle-filename pairs to the method.

Example 44-141. Loading a template file

$t =& new HTML_Template_PHPLIB(dirname(__FILE__), 'keep');
$t->setFile('authors', 'authors.tpl');

Defining blocks

If you want to re-use certains parts of your HTML code multiple times, e.g. rows in a table, you can define blocks as described in the example above.

Blocks are not automatically detected, they need to be defined explicitely via the setBlock() method. The method takes the handle of the file in which the block is located as first parameter, the name of the block as written in the file as second and the new block handle as third parameter.

Example 44-142. Defining a block

$t->setBlock('authors', 'authorline', 'authorline_ref');

In the example template (available as handle authors), a block named authorline is defined. The handle of the block is now authorline_ref.

Setting variables

This is the most easy part: Just use setVar() with the variable name and it's new value. An optional third boolean parameter tells if the value should be appended to the existing value (defaults to false).

Example 44-143. Setting a variable

$t->setVar('AUTHOR_NAME', 'Christian Weiske');

Variables set influence all variables in the template, no matter if they are defined within a block or not.

Parsing blocks

Once you filled all variables in a block, you want to "save" them to be able to re-use the block another time. Method parse() is useful here. First parameter is the variable/handle in which the block content shall be stored, second is the handle name of the block. The optional third parameter tells if you want to append the block content to the handle value or not - it defaults to false, but you probably want to do that.

Example 44-144. Parsing a block

foreach ($authors as $name => $email) {
    $t->setVar('AUTHOR_NAME', $name);
    $t->setVar('AUTHOR_EMAIL', $email);
    $t->parse('authorline_ref', 'authorline', true);
}

In this example, handle authorline_ref is filled with the contents of block authorline. If the third parameter would be false instead of true, only the last line would be in it at the end.

Finish & output

When you're done with setting variables and parsing your blocks, it's time to write the contents to your client. At first, you need to parse() the contents of the file handle into a new handle.

To remove all unused variables and blocks, you might want to call finish(). Depending on the value set for unknowns (as second paramter in the constructor, or via setUnknowns()), unused variables are either erased (remove), kept (keep) or commented out (comment).

To echo your HTML, either directly use the return value of finish(), or use get() to retrieve the content.

Example 44-145. Finishing a file and writing it out

$t->parse('OUT', 'authors');
$htmlcode = $t->finish(
    $tpl->get('OUT')
);
echo $htmlcode;

Example 44-146. Finishing a file and writing it out, the easy way

echo $tpl->finish($t->parse('OUT', 'authors'));
PrevHomeNext
HTML_Template_IT::touchBlock()UpHTML_Template_Sigma