HTML_Template_IT::touchBlock() (Previous) (Next) HTML_Template_Sigma
View this page in Last updated: Sun, 01 Jul 2007
English | French | German | Hungarian | Japanese | Polish | Spanish | Plain HTML

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

Példa 43-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>

Példa 43-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.

Példa 43-141. Loading a template file


<?php
$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.

Példa 43-142. Defining a block


<?php
$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).

Példa 43-143. Setting a variable


<?php
$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.

Példa 43-144. Parsing a block


<?php
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.

Példa 43-145. Finishing a file and writing it out


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

Példa 43-146. Finishing a file and writing it out, the easy way


<?php
echo $tpl->finish($t->parse('OUT', 'authors'));
?>
HTML_Template_IT::touchBlock() (Previous) (Next) HTML_Template_Sigma
Download Documentation Last updated: Sun, 01 Jul 2007
Do you think that something on this page is wrong? Please file a bug report or add a note.
User Notes:
There are no user contributed notes for this page.