TemplatePower manual

CopyRights © 2001, 2002 Ron P.J. Velzeboer
  1. Introduction
        What is TemplatePower?
        What can TemplatePower do?
        Why should you use TemplatePower?
        Requirements
        GNU General Public License
  2. Templateformat
  3. TemplatePower object
  4. Functions
        assign
        assignGlobal
        assignInclude
        getOutputContent
        getVarValue
        gotoBlock
        newBlock
        prepare
        printToScreen
        serializedBase
        showUnAssigned
        version

Index

What is TemplatePower?

TemplatePower offers you the ability to separate your PHP code and your (HTML) layoutfile. It's simular to the popular template class FastTemplate, but than a lot faster (about 6x faster).

What can TemplatePower do?

TemplatePower 1.6.2 supports the following:

- nested dynamic block support.
- block / file include support (note: PHP code will NOT be executed, use v2.0).
- show / hide unassigned variables.

TemplatePower 2.0 includes extra:
- ingore tag.
- PHP-file include tag, this code will be executed.
- global assign of variable
- multiple variable assign in one assign statement, using an associative array.
- save / use parsed template on / from disk.
- reuse tag (test state).

TemplatePower 3.0 includes extra
- database template support.

Why should you use TemplatePower?

First of all, its free for personal use (General Public License)!

The reason that I developed TemplatePower was that FastTemplate wasn't so easy to use (that's my opinion). At least it could be done easier, that's why I called it EasyTemplate first, but that name was already in use I noticed later. So, i changed the name into TemplatePower. I hope you agree with me, that TemplatePower is easier in use than FastTemplate. And as I wrote above TemplatePower is a lot faster than FastTemplate. These are probably the most important reasons why you should use TemplatePower instead of FastTemplate.

If you find a bug(s) please fill in the bugreport which you can find here.

Requirements

TemplatePower requires PHP 4.0.1 or higher and runs on windows and unix-based systems.

GNU General Public License

TemplatePower is released under the GNU General Public License. If you want to sell an application/site where TemplatePower is a part of, you can buy a special 'Certificate of Distribution'. This certificate allows you to sell a number (minimum quantity of five) of applications/sites with TemplatePower. It will cost (number x EUR 10) + EUR 5.00 (for administration costs). If you use TemplatePower for commercial purposes without a 'Certificate of Distribution' you will risk a fine of EUR 1000 + license costs.

Index

TemplateFormat


Main template markers/tags

Variables
{variablename}

Like most other template system TemplatePower uses {variablename} as a marker for some value. The variablename must be either a nonnegative integer or a string. However this string may not contain a curly bracket ( { ) or a white space. This means that variablemarkers like {-1}, {a{name} or {a name} are not allowed.

In your controllscript you can assign the variable with the function assign(). All variable markers, inside a block, with the same name will be seen as one variable. So, you only have to assign them once.

Dynamic blocks
<!-- START BLOCK : blockname -->

<!-- END BLOCK : blockname -->

You can use dynamic blocks, for example, when you want to create a table with products with on each row a productnumber, productname and price. Just place the rowcode between the above start/end markers. These markers must be on a separate line each, in order to work properly. The blockname must be either a nonnegative integer or a string. However this string may not contain a dot (.).

In your controllscript you can use these blocks with the function newBlock().

Blocks can also be used to hide or show information. If you have defined a block in your template but you don't create it with the function newBlock(), the blockcode will be hidden. This is handy to show/hide errormessages for example.
Include blocks
<!-- INCLUDE BLOCK : iblockname -->

With include blocks you can include files like subtemplates (the templatecode itself, no objects), HTML, etc. However, if you include a PHP-file, the PHP-code will not be executed. Including PHP-files is possible using the includescript block tag, see the TemplatePower v2.0+ template tag section below. This marker must be on a separate line, in order to work properly. The iblockname must be either a nonnegative integer or a string. However this string may not contain a dot (.).

In your controllscript you can assign files to iblockname with the function assignInclude().

In TemplatePower v3.0+ it's also possible to create a constant include block.

<!-- INCLUDE BLOCK : ./header.tpl -->

TemplatePower v2.0+ template tags

Includescript blocks
<!-- INCLUDESCRIPT BLOCK : iblockname -->

With the includescript block tag you can insert a PHP-file, the code will be executed. This marker must be on a separate line, in order to work properly. The iblockname must be either a nonnegative integer or a string. However this string may not contain a dot (.).

In your controllscript you can assign files to iblockname with the function assignInclude().

Like with the include block tag, it's also possible to create a constant includescript block. This feature is supported by TemplatePower v3.0 or higher.

<!-- INCLUDESCRIPT BLOCK : ./header.php -->

Ignore block
<!-- START IGNORE -->
	  
<!-- END IGNORE -->

If you place any code between the start/end ignore tag, this code will just be parsed as code. This means that no variable or block will be processed in this code. These markers must be on a separate line each, in order to work properly.

ReUse block
<!-- REUSE BLOCK : orig_bname AS copy_bname -->

With the reuse tag you can reuse an other block and give it a different blockname. This feature is not totally bug-proof. The reuse tag will only work properly when the block you want to reuse has no child block(s).

The copyblockname must be either a nonnegative integer or a string. However this string may not contain a dot (.).


Database templates

Database Templates have to be stored in the same format as normal templates. So, the Carriage Return (cr) and Line Feed (lf) must be stored in the database as well.

Index

TemplatePower object

(unknown)

Create a new TemplatePower object.

Description

object TemplatePower ( string basefile/content, [const type] )

The default value of the parameter type is the constant T_BYFILE, in case the first parameter is a filename. If the first parameter for example is a variable with the content of a template, type should be set to T_BYVAR.


See also: assignInclude().

Examples of TemplatePower v3.0+ objects.
//create a new TemplatePower object using a file

$tpl = new TemplatePower( "./base.tpl" );
$tpl = new TemplatePower( "./base.tpl", T_BYFILE );


//create a new TemplatePower object using a variable

$tpl = new TemplatePower( $base_content, T_BYVAR );


//create a new TemplatePower object using a 
//serialized template

$tpl = new TemplatePower( $base_content );
$tpl->serializedBase();


In version 1.6.2 of TemplatePower there was only one parameter, this was basefile. In version 2.0 there was a second parameter added, to tell if basefile was a serialized template. In version 3.0+ this is done different, using the function serializedBase().
Examples of TemplatePower v2.0 objects.
//create a new TemplatePower object using a file

$tpl = new TemplatePower( "./base.tpl" );


//create a new TemplatePower object using a 
//serialized template

$tpl = new TemplatePower( "./base.stpl", true );

Index

assign

Assign a value to a variable.

Description

assign ( string [blockname.]variablename, mixed value )
assign ( Array( [blockname.]variablename => value ) )

The default value of value is ''.


See also: assignGlobal(), getVarValue(), and showUnAssigned().

Example 1.
simple.tpl
<html>
<head>
  <title>Simple Template Example</title>
</head>
<body>
  <H2>Welcome {name}!</H2>
</body>
</html>

myscript.php 
<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./simple.tpl" );
$tpl->prepare();

$tpl->assign( "name", "Ron" );

$tpl->printToScreen();
?>

Examples of the assign function
$tpl->assign( "name", "Ron" );
$tpl->assign( Array( product_id  => $pid,
                     productname => $pname ));

Variables and Blocks

Each variable is a child of a parent block. Even in example 1, where no block is defined, the variable name has a parent block. The parent block of name is _ROOT, this is the default block if a variable has no user-defined parent-block.

Variables can also be defined together with the parent-blockname, in the format of 'blockname.variablename'.

$tpl->assign( "_ROOT.name", "Ron" );
$tpl->assign( "book.title", "Core PHP Programming" );

Index

assignGlobal

(TP 2.0+)

Assign a value to all variables with a specific name.

Description

assignGlobal ( string variablename, mixed value )
assignGlobal ( array( variablename => value ) )


The function assignGlobal() gives a default value to all variables, even in child blocks, with a specific name. This default value can be replaced in each block, which has a that variable, with the function assign().
Example 1.
img.tpl
<html>
<head>
  <title>AssignGlobal Example</title>
</head>
<body>
  <img src="{imagedir}/logo.gif">

  <!-- START BLOCK : image -->
    <img src="{imagedir}/img_{id}.gif">
  <!-- END BLOCK : image -->
</body>
</html>

myscript.php 
<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./img.tpl" );
$tpl->prepare();

$tpl->assignGlobal( "imagedir", "images");

for ( $i=1; $i<=10; $i++ )
{
    $tpl->newBlock( "image" );
    $tpl->assign( "id", $i );
}

$tpl->printToScreen();
?>

Examples of the assignGlobal function
$tpl->assignGlobal( "basedir", "/usr/local/apache/www/");
$tpl->assignGlobal( Array( basedir  => "/usr/local/apache/www/",
                           imagedir => "images/" ));

Index

assignInclude

(TP 2.0+)

Tell which file/content to include.

Description

assignInclude ( string includename, string filename/content, [const type] )


The default value of the parameter type is the constant T_BYFILE, in case the second parameter is a filename. If the second parameter for example is a variable with the content of a template, type should be set to T_BYVAR.
Example 1.
include.tpl
<html>
<head>
  <title>AssignInclude Example</title>
</head>
<body>
  <!-- INCLUDE BLOCK : header -->

  <!-- INCLUDESCRIPT BLOCK : content -->
</body>
</html>

myscript.php 
<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./include.tpl" );
$tpl->assignInclude( "header", "./header.tpl" );
$tpl->assignInclude( "content", "./about.php" );
$tpl->prepare();

$tpl->printToScreen();
?>


Examples of the assignInclude function
$tpl->assignInclude( "header", "./header.tpl" );
$tpl->assignInclude( "content", $content, T_BYVAR );


Example 2.  Database Templates

<?php
  include( "./class.TemplatePower.inc.php");

 //connect to database
   $link = mysql_connect("host", "user", "passwd")
              or die("Could not connect");
     
  mysql_select_db("my_database") 
      or die("Could not select database");  

 //get database templates
   $qry = "SELECT base, header FROM templates";

  $result = mysql_query($qry);
  
  if( mysql_num_rows($result) > 0)
  {
      list($base, $header) = mysql_fetch_row($result);
  }
 
 //make a new TemplatePower object
  $tpl = new TemplatePower( $base, T_BYVAR );

 //assign include template by variable
  $tpl->assignInclude( "header", $header, T_BYVAR );
  $tpl->prepare();

 //print the result
  $tpl->printToScreen();
 ?>

Index

getOutputContent

(unknown)

Returns a string with all templatedata, equal to the output of the printToScreen function.

Description

getOutputContent ()

Index

getVarValue

(unknown)

Returns the value of a variable.

Description

getVarValue ( string [blockname.]variablename )


Note: You are only able to retreive the value of the last instance of a variable. This means that if you have a repeating block, you can only retreive the the variablevalues of the last created block.
Example 1.
number.tpl
<html>
<head>
  <title>AssignInclude Example</title>
</head>
<body>
  <!-- START BLOCK : number -->
    {number}
  <!-- END BLOCK : number -->
  {total}
</body>
</html>

myscript.php 
<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./number.tpl" );
$tpl->prepare();

for( $i=1; $i <= 10; $i++ )
{
 $tpl->newBlock( "number" );
 
 $tpl->assign( "number"     , $i );
 $tpl->assign( "_ROOT.total", ($tpl->getVarValue( "_ROOT.total" ) + $i) );
}

$tpl->printToScreen();
?>

Index

gotoBlock

(unknown)

Move the 'blockpointer' to a block, to make it the currentblock.

Description

gotoBlock ( string blockname )

The function gotoBlock() moves the 'blockpointer' to the block blockname, to make it the currentblock. This is useful when you want to return to a previously made block and assign its variables.
Example 1.
newBlock.tpl 
<html>
<head>
  <title>NewBlock</title>
</head>
<body>
<table>
  <tr><td>Names</td></tr>
  <!-- START BLOCK : name_row -->
  <tr>
    <td>{name}</td>
  </tr>
  <!-- END BLOCK : name_row --> 
</table>
<br>
{total_names}
</body>
</html>

myscript.php 
<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./newBlock.tpl" );
$tpl->prepare();

$count = 0;

while( $count < 10 )
{
    $tpl->newBlock( "name_row" );
    $tpl->assign( "name", "Ron" );
 
    $count++;
}

$tpl->gotoBlock( "_ROOT" );
$tpl->assign( "total_names", $count );

$tpl->printToScreen();
?>

Index

newBlock

(unknown)

Create a new block.

Description

newBlock ( string blockname )

After using the function newBlock() TemplatePower will set the 'blockpointer' to the block blockname. So, if you want to assign a variable of an other block, you have to move the 'blockpointer' to that block (see gotoBlock() ) or use the variablename in combination with its blockname (see Variables and Blocks). If you don't TemplatePower will assume that the variable is part of the currentblock.
Example 1.
newBlock.tpl 
<html>
<head>
  <title>NewBlock</title>
</head>
<body>
<table>
  <tr><td>Names</td></tr>
  <!-- START BLOCK : name_row -->
  <tr>
    <td>{name}</td>
  </tr>
  <!-- END BLOCK : name_row --> 
</table>
<br>
{total_names}
</body>
</html>

myscript.php 
<?php
include_once( "./class.TemplatePower.inc.php" );

$tpl = new TemplatePower( "./newBlock.tpl" );
$tpl->prepare();

$count = 0;

while( $count < 10 )
{
    $tpl->newBlock( "name_row" );
    $tpl->assign( "name", "Ron" );
 
    $count++;
}

$tpl->gotoBlock( "_ROOT" );
$tpl->assign( "total_names", $count );

$tpl->printToScreen();
?>


If you don't use the function newBlock() to create a block, the code inside the block will be hidden. In 'Example 2' you see an example of this where an emailaddress can be submitted by a form. If no emailadress is enterred an errormessage will be printed.
Example 2.
form.tpl 
<html>
<head>
 <title></title>
</head>
<body>
<!-- START BLOCK : error -->
The following errors occurred.<br>
  <!-- START BLOCK : message -->
  - {message}<br>
  <!-- END BLOCK : message -->
<!-- END BLOCK : error -->

<form method="post" action="myscript.php">
  Email:
  <input type="text" name="email">
  <input type="submit" name="submit" value="Submit">
</form>
</body>
</html>

myscript.php 
<?php
include_once('./class.TemplatePower.inc.php');

$tpl = new TemplatePower('form.tpl');
$tpl->prepare();

$errorMessage = Array();
$errorFound   = false;

if( isset( $submit ) )
{
  if($email == '')
  {
    $errorMessage[] = 'No emailadress entered';   
    $errorFound     = true;
  }
    
  if( $errorFound )
  {
    $tpl->newBlock('error');
    
    $size = sizeof($errorMessage);

    for( $i=0; $i < $size; $i++ )
    {
      $tpl->newBlock('message');
      $tpl->assign('message', $errorMessage[$i]);
    }
  }
  else
  {
    Header('Location: member.php');
  }
}

$tpl->printToScreen();
?>

Index

prepare

(unknown)

Parse the templates.

Description

prepare ()

The prepare function has to be used for each TemplatePower object in order to make it work. Otherwise the templates will not be parsed and variables will not be assigned.

Note: The prepare function has to be executed before you create new blocks and/or assign variables and after function like assignInclude() and serializedBase().

Index

printToScreen

(unknown)

Outputs all templatedata.

Description

printToScreen ()

Index

serializedBase

(TP 3.0+)

Tell TemplatePower that the basefile/content is serialized.

Description

serializedBase ()

Index

showUnAssigned

(TP 3.0+)

Show/hide unassigned variables.

Description

showUnAssigned ( bool state )

Index

version

(TP 2.0+)

Returns the version of TemplatePower.