The PEAR ITX Templating System - How to make templates

(Page 4 of 5 )

Now that we know how to insert ITX into our application, it's time to make our first template.

There are two items in an ITX template that you can use: blocks and variables.

Variables

Like their name suggests, variables are placeholders in the template. You can assign values to variables, and those values will be used in the template instead of the variable name.

For instance, if you had this template:

Hello {name}, I'm glad we met!

and you set the value of the name variable to "Steve" the parsed template would look like this:

Hello Steve, I'm glad we met!

By now you must be wondering how we get the data into and the parsed template out of ITX! So, here's a short snippet of code that would run the example above:

<?php $tpl-&gt;setVariable("name", "Steve"); $tpl-&gt;show(); ?>

After you execute this piece of code, you are done. The ITX class has rendered the template with its contents and displayed the output to the user. How's that for short, eh? :)

It would certainly be tedious to set a large number of variables manually like this, so there is a faster way to load the contents of an associative array directly into the template. You can accomplish that by simply passing the array containing the data to the setVariable method:

<?php $data = array(     "name" =&gt; "Steve" ); $tpl-&gt;setVariable($data); $tpl-&gt;show(); ?>

The result would be the same like the above method, so you might be wondering why bother? An answer may be obvious when you start thinking about the data extracted from a database which would suit perfectly for this kind of passing into the template.

Blocks

Let's now pretend for a moment that we have several sets of data that all have the same properties. For instance, we are making a listing of all the students in some school. Every student would have the same type of information associated with him: name, date of birth and current address.

To represent this kind of data we use blocks. They allow us to group variables together and parse them several times with different sets of data. In order to work with blocks, we need to learn several new ITX methods. First off, we need to learn how to write the templates that contain blocks:

<!-- BEGIN student -->    Name: {name}    DOB: {birth}    Address: {addr} <!-- END student -->

Now assume that we are pulling data out of the PEAR database abstraction layer in the associative fetch mode. Populating this block with data and displaying the whole web page to the user is as simple as writing this:

<?php $tpl-&gt;setCurrentBlock("student"); while ($data=$result-&gt;fetchRow()) {    $tpl-&gt;setVariable($data);    $tpl-&gt;parseCurrentBlock(); } $tpl-&gt;show(); ?>

We've met two new methods here!

First off, we have setCurrentBlock. Its purpose is to tell ITX which block we want to populate with the data. After that we use a while loop along with the setVariable method to put the data directly from the $data array into ITX.

For the end, we need to tell ITX that we have finished adding one set of data and are about to start working on another set - another student if you will. To mark this we use the parseCurrentBlock method.

A word of warning to those that are wondering: ITX doesn't like same named variables even if they are contained in different blocks. Using them will usually lead you to no good.

Blocks within blocks

In real life one level of data grouping will rarely suffice. Car dealerships handle lists of cars, and sub lists of previous car owners for each car separately. Online stores handle buyers and lists of items bought by any person. Schools keep lists of classes, students and grades for each subject for each student.

While doing this with only one block can be accomplished, this would be rather ugly. There is however a way to handle blocks within blocks.

Writing a template for this case proves to be quite intuitive:

<!-- BEGIN student -->    Name: {name}    DOB: {birth}    Address: {addr}    <!-- BEGIN grade -->       Subject: {subject}       Grade: {grade}    <!-- END grade --> <!-- END student -->

Unfortunately, writing code to populate this kind of a data structure is not so simple. Let's see how the code looks like, and we'll talk about the new things we've seen after it!

<?php while ($student = $studentResult-&gt;fetchRow()) {    $tpl-&gt;setCurrentBlock("student");    $tpl-&gt;setVariable($student);    $tpl-&gt;setCurrentBlock("grade");    while ($grade = someGradeFetchFunction($student)) {       $tpl-&gt;setVariable($grade);       $tpl-&gt;parseCurrentBlock();    }    $tpl-&gt;parse("student"); } $tpl-&gt;show(); ?>

First of all, you'll notice that we have used a new method. It's called parse and is used to parse any block, no matter what the current block is. You should use this method carefully. Take special care not to parse blocks that haven't been populated with data. ITX is pretty lax when it comes to this type of security and can produce the strangest results if you do this!

The second issue is more serious. We are constantly changing from one block to the other as we switch between populating the template with students and grades. This requires quite a lot of care from the programmer. If you populate a wrong block with your data the error will usually be quite difficult to diagnose.

You'll notice that I've used a fictional function called someGradeFetchFunction in the inner while loop. The implementation of it would be quite explicit and even writing the PEAR database access inline would be simple. I'll leave it to the reader as an exercise in creativity! :)

Next: The conclusion >>
 

More PEAR Articles Articles
More By Codewalkers

Comments On: The PEAR ITX Templating System

· For those interested in the integrated doc in the source code, you can find a phpDoc...    · I've been struggling trying to get the phplib template system to work (with nested...    · I've been using them for almost almost a year now. I was using PHPlib template.inc...   >>> Post your comment now!