Docs For Class Template

Description

Substitutes special template tags with given content.

This is just another template class for HTML/XML/text templates. BUT it is the result of studying several other template engines and tries to merge all advantages. This text explains you two things:

How To Use - some examples
Why This Way - good reasons for the syntax and the API

You can download this class:

http://svn.savannah.nongnu.org/svn/ubook/trunk/text/

Feedback is very welcome: contact formular

How To Use

A usage example:

// Begin to create pure HTML. It could be like this:
$theHtmlCodeAsString = <<<EOT
<h1>Hi 'user'!</h1>
<p>This is a list of names:</p>
<ul>
<li>'name'</li>
</ul>
EOT;
$template = new Template($theHtmlCodeAsString);
// or
// $template = Template::fromFile($filenameOfTemplate);
// Now let's write code to fill it with data.
// replace a variable with a value
$template->assign('user', 'Joe');
// use the subtemplate to generate three list items
$sub1 = $template->addSubtemplate('item');
$sub1->assign('name', 'Andrea');
$sub2 = $template->addSubtemplate('item');
$sub2->assign('name', 'Andy');
$sub3 = $template->addSubtemplate('item');
$sub3->assign('name', 'Anna');
// ready...
echo $template->result();
// results in
/// <h1>Hi Joe!</h1>
/// <p>This is a list of names:</p>
/// <ul>
/// <li>Andrea</li>
/// <li>Andy</li>
/// <li>Anna</li>
/// </ul>

Why This Way

This class was written for a simple project. It's just one class, not a whole framework with caching and so on. It supports everything, that a simple template engine should support. But not more. Keep it simple.

Why do you use single quotes for variables?

There are three reasons:

It's easy to write on most keyboards.
Valid HTML will stay valid, when you insert single quotes in the text. It's also no problem to insert single quotes into a double quoted parameter value.
You can prevent unintended replacements by encoding the user data via htmlentities() before inserting into the template (see example below).

Besides, if you like another syntax, just change the constants in the script. It's free.

Why don't you recommend the assignArray-method?

It's no good idea to store everything in an array. The more complex your application becomes, the harder it is to remember all the array structures. Additionally some IDEs (e.g. NetBeans) support the correct renaming of variables, but not of array indices, of course.

Assigning one variable to the template is not more complicated than a new entry in an array.

And most important: Perhaps you have a full array of data from mysql_fetch_array(). But you should not insert this into a template. Normally you have more data in there than you want to present the user. And you have to encode the user data to prevent code injection. So depending on your application, perhaps you can do something like this:

mysql_connect('localhost', 'test');
$result = mysql_query('select "Joe<script>...</script>" as user;');
$arr = mysql_fetch_array($result);
foreach ($arr as $key => $value) {
$encoded = htmlentities($value, ENT_QUOTES, 'UTF-8');
$template->assign($key, $encoded);
}
echo $template->result();
// results in
/// <h1>Hi Joe<script>...</script>!</h1>
/// <p>This is a list of names:</p>
/// <ul>
/// <li>Andrea</li>
/// <li>Andy</li>
/// <li>Anna</li>
/// </ul>

But this depends on your application.

Wouldn't it be nice to define conditions for subtemplates or provide something like a for-loop syntax?

No. It's a good idea to seperate PHP and HTML cleanly. So you have all your application logic in your PHP code. Your template files only define, what can be displayed and how. If you really want to script within your HTML, then you can just use PHP itself:

What is the other way?

Other interesting template classes:

author: Maikel Linke (contact formular)
version: 2011-09-30

Located in /Template.php (line 163)

Class Constant Summary

SUB_PATTERN = '/(\n[\t ]*)?(.*?)(\n[\t ]*)?/ims'

TAG_END = "'"

TAG_START = "'"

Method Summary

static Template fromFile (string $filename)

Template __construct (string $content)

Template addSubtemplate (string $name)

void assign (string $name, [string $value = ''])

void assignArray (array $associativeArray)

string result ()

Methods

static method fromFile (line 195)

Loads the content of a template file.

return: instance with the content of the template file
throws: Exception if $filename doesn't point to a file or reading fails (plus Exception from the constructor)
access: public

static Template fromFile (string $filename)

string $filename: path to the template file

Constructor __construct (line 211)

Creates a new instance with given string as source (not filename).

throws: Exception if there are ambiguous subtemplates
access: public

Template __construct (string $content)

string $content: containing the code of the template

addSubtemplate (line 242)

Subtemplates are defined once and will appear in the result zero or more times. Varying content and also sub-subtemplates are possible.

return: a full template instance to customize this subtemplate
throws: Exception if their is no such subtemplate
access: public

Template addSubtemplate (string $name)

string $name: identifyer of the subtemplate

assign (line 221)

Replaces a template tag with the given value.

access: public

void assign (string $name, [string $value = ''])

string $name: tag identifier in the template
string $value: new value in the document

assignArray (line 231)

Assigns all values of the given array to the keys of the array.

Warning: This function is seldom useful. Don't assign arrays from your database without encoding the data. See documentation above.

access: public

void assignArray (array $associativeArray)

array $associativeArray: of the form array( 'tag_name' => 'value' )

result (line 261)

Returns the parsed result.

return: actual result with all given replacements
access: public

string result ()

Class Constants

SUB_PATTERN = '/(\n[\t ]*)?(.*?)(\n[\t ]*)?/ims' (line 180)

Regular expression for subtemplates.

It uses the following pattern modifiers:

i - caseless
m - multiline
s - dotall

TAG_END = "'" (line 171)

The beginning of a tag to substitute. Tag example: 'bar'

TAG_START = "'" (line 167)

The beginning of a tag to substitute. Tag example: 'foo'