Wiki Navigation

You are here: WikiStart/Docs/Variables

Adding variables to the template

Variables are placeholders in your templates that you may assign any value from your PHP application.

There are two types of variables in patTemplate:

Local variables, that are only available in the template that they have been added to
Global variables, that are available in all templates

To place a variable in a template, you need to enclose the variable in curly braces. Variables may only consist of uppercase letters, number, dashes and the uderscore:

<patTemplate:tmpl name="page">
  Hello {NAME}.<br/>
</patTemplate:tmpl>

This template contains a variable called {NAME} that you may assign a value from your application.

Adding a local variable with addVar()

When adding a local variable, you have to use the addVar() method and pass the name of the template, where you want to add variable, the name of the variable as well as the value you want to assign:

$tmpl = new patTemplate();
$tmpl->readTemplatesFromInput('my-template.tmpl');
$tmpl->addVar('page', 'NAME', 'Stephan');
$tmpl->displayParsedTemplate();

This script will display:

Hello Stephan.

Instead of a string, you may also pass an array containing several values. In this case, patTemplate will repeat the template to which the variable has been assigned for each entry on your array. Change only one line of code to add more than one name:

$tmpl->addVar('page', 'NAME', array('Stephan', 'Sebastian'));

Now the script will display:

Hello Stephan.
Hello Sebastian.

No need to create a for loop, neither in your PHP application, nor in your template file.

Adding several variables at once with addVars()

A template need not only contain one variable, it can contain as many of them, as you like:

<patTemplate:tmpl name="page">
  {GREETING} {NAME}.<br/>
</patTemplate:tmpl>

Instead of two calls to addVar() you may also pass an associative array to the addVars() method:

$vars = array(
         'GREETING' => 'Guten Tag',
         'NAME'     => 'Stephan'
        );
$tmpl->addVars('page', $vars);

This will add two variables (GREETING and NAME) to the template page and display:

Guten Tag Stephan.

It is also possible to assign more than one value to a variable using addVars():

$vars = array(
         'GREETING' => array('Guten Tag', 'Bonjour'),
         'NAME'     => array('Stephan', 'Sebastian')
        );
$tmpl->addVars('page', $vars);

This will display:

Guten Tag Stephan.
Bonjour Sebastian.

If you assign an array to one variable and a string to the other, patTemplate will use the same string for each iteration:

$vars = array(
         'GREETING' => 'Hello',
         'NAME'     => array('Stephan', 'Sebastian')
        );
$tmpl->addVars('page', $vars);

This example will display:

Hello Stephan.
Hello Sebastian.

Adding rows of variables with addRows()

Often, you are confronted with record sets in the following structure:

$data = array(
           array('name' => 'Stephan Schmidt', 'id' => 'schst'),
           array('name' => 'Sebastian Mordziol', 'id' => 'argh'),
           array('name' => 'Gerd Schaufelberger', 'id' => 'gerd')
        );

If you want to create an HTML-table containting this information, you can use the addRows() method and the following template:

<patTemplate:tmpl name="page">
<table>
  <tr>
    <th>User-Id</th>
    <th>Name</th>
  </tr>
  <patTemplate:tmpl name="entry">
  <tr>
    <td>{USER_ID}</td>
    <td>{USER_NAME}</td>
  </tr>
  </patTemplate:tmpl>
</table>
</patTemplate:tmpl>

This page constists of two templates, the root template (page) and template, that should be repeated for each record set in your array (entry). To build a list containg all record sets, you only need to call one method:

$tmpl = new patTemplate();
$tmpl->readTemplatesFromInput('my-template.tmpl');
$tmpl->addRows('entry', $data, 'USER_');
$tmpl->displayParsedTemplate();

The addRows() method accepts three arguments:

The name of the template
An array containing all record sets
An optional prefix for the variable names

The addRows() method is perfectly suited to create lists from database result sets, like they are returned by PEAR DB's getAll() method.

Adding objects with addObject()

Instead of using an associative array, you may also work with an object instead.

Imagine, you are using the following class in your application:

class User {
  public $id;
  public $name;

  public function __construct($id, $name) {
    $this->id = $id;
    $this->name = $name;
  }
}

And you created a template to display user information:

<patTemplate:tmpl name="user-info">
<table>
  <tr>
    <th>Id:</th>
    <td>{USER_ID}</td>
  </tr>
  <tr>
    <th>Name:</th>
    <td>{USER_NAME}</td>
  </tr>
</table>
</patTemplate:tmpl>

You may now pass instance of the User class directly to the template:

$schst = new User('schst', 'Stephan Schmidt');

$tmpl = new patTemplate();
$tmpl->readTemplatesFromInput('user-info.tmpl');
$tmpl->addObject('user-info', $schst, 'USER_');

This will display:

Id:   schst
Name: Stephan Schmidt

patTemplate will extract all properties that are marked as public and add them to the specified template while prefixing them as you have seen in the addRows() example. If you do not want to declare your properties as public, you may as well implement a getVars() method in your class that returns an associative array containing the variables that should be added to the template:

class User {
  private $id;
  private $name;

  public function __construct($id, $name) {
    $this->id = $id;
    $this->name = $name;
  }

  /**
   * This method will be invoked by patTemplate if the
   * object is passed to addObject()
   */
  public function getVars() {
    return array(
             'id'   => $this->id,
             'name' => $this->name
           );
  }
}

The result will be exactly the same.

Adding global variables with addGlobalVar() and addGlobalVars()

If you want to use a variable in every template block of a page, it can get cumbersome to use any of the above methods to add this variable to every template. Instead, you may use the methods addGlobalVar() or addGlobalVars() to add the variable to every template in your page:

$tmpl = new patTemplate();
$tmpl->readTemplatesFromInput('my-template.tmpl');
$tmpl->addGlobalVar('NOW', date('Y-m-d H:i:s', time()));

The variable {NOW} may now be used in all of your templates:

<patTemplate:tmpl name="page">
  Current date/time : {NOW}<br/>
  <patTemplate:tmpl name="footer">
    <div class="footer">Generated at {NOW}</div>
  </patTemplate:tmpl>
</patTemplate:tmpl>

There are two differences between the methods for local and global variables:

The global methods do not need the template name as the first parameter.
The global methods do not accept an array as values of variables.

If a variable-name is used globally and locally, the local variable has precedence.

Wiki Navigation

TracNav menu

Documentation

Adding variables

Advanced features

Extending patTemplate