Docs For Class HTML_Template

[line 121]
HTML_Template_Sigma: implementation of Integrated Templates API with template 'compilation' added.

The main new feature in Sigma is the template 'compilation'. Consider the following: when loading a template file the engine has to parse it using regular expressions to find all the blocks and variable placeholders. This is a very "expensive" operation and is definitely an overkill to do on every page request: templates seldom change on production websites. This is where the cache kicks in: it saves an internal representation of the template structure into a file and this file gets loaded instead of the source one on subsequent requests (unless the source changes, of course).

While HTML_Template_Sigma inherits PHPLib Template's template syntax, it has an API which is easier to understand. When using HTML_Template_PHPLIB, you have to explicitly name a source and a target the block gets parsed into. This gives maximum flexibility but requires full knowledge of template structure from the programmer.

Integrated Template on the other hands manages block nesting and parsing itself. The engine knows that inner1 is a child of block2, there's no need to tell it about this:

block1

inner1
inner2

To add content to block1 you simply type:

$tpl->setCurrentBlock("block1");

and repeat this as often as needed:

   $tpl->setVariable(...);
   $tpl->parseCurrentBlock();

To add content to block2 you would type something like:

 $tpl->setCurrentBlock("inner1");

 $tpl->setVariable(...);
 $tpl->parseCurrentBlock();
 
 $tpl->setVariable(...);
 $tpl->parseCurrentBlock();
 
 $tpl->parse("block2");

This will result in one repetition of block2 which contains two repetitions of inner1. inner2 will be removed if $removeEmptyBlock is set to true (which is the default).

Usage:

 $tpl = new HTML_Template_Sigma( [string filerootdir], [string cacherootdir] );

 
 // load a template or set it with setTemplate()
 $tpl->loadTemplatefile( string filename [, boolean removeUnknownVariables, boolean removeEmptyBlocks] )
 
 // set "global" Variables meaning variables not beeing within a (inner) block
 $tpl->setVariable( string variablename, mixed value );
 
 // like with the HTML_Template_PHPLIB there's a second way to use setVariable()
 $tpl->setVariable( array ( string varname => mixed value ) );
 
 // Let's use any block, even a deeply nested one
 $tpl->setCurrentBlock( string blockname );
 
 // repeat this as often as you need it.
 $tpl->setVariable( array ( string varname => mixed value ) );
 $tpl->parseCurrentBlock();
 
 // get the parsed template or print it: $tpl->show()
 $html = $tpl->get();

Author: Alexey Borzov <avb@php.net>
Author: Ulf Wendel <ulf.wendel@phpdoc.de>
Version: $Revision: 1.12 $
Access: public

Class Variables

$blocknameRegExp = '[0-9A-Za-z_-]+'

[line 147]

RegExp for matching the block names in the template.

Per default "sm" is used as the regexp modifier, "i" is missing. That means a case sensitive search is done.

See: HTML_Template_Sigma::$variablenameRegExp, HTML_Template_Sigma::$openingDelimiter, HTML_Template_Sigma::$closingDelimiter
Access: public

Type:

string

[ Top ]

$blockRegExp = ''

[line 177]

RegExp used to find blocks and their content, filled by the constructor

See: HTML_Template_Sigma::HTML_Template_Sigma()

Type:

string

[ Top ]

$closingDelimiter = '}'

[line 137]

Last character of a variable placeholder ( {VARIABLE_}_ )

See: HTML_Template_Sigma::$openingDelimiter, HTML_Template_Sigma::$blocknameRegExp, HTML_Template_Sigma::$variablenameRegExp
Access: public

Type:

string

[ Top ]

$currentBlock = 'global'

[line 197]

Name of the current block

Type:

string

[ Top ]

$fileRoot = ''

[line 278]

Root directory for "source" templates

See: HTML_Template_Sigma::HTML_Template_Sigma(), HTML_Template_Sigma::setRoot()

Type:

string

[ Top ]

$flagGlobalParsed = false

[line 292]

Flag indicating that the global block was parsed

Type:

boolean

[ Top ]

$functionnameRegExp = '[_a-zA-Z]+[A-Za-z_0-9]*'

[line 318]

Function name RegExp

Type:

string

[ Top ]

$functionPrefix = 'func_'

[line 312]

Function name prefix used when searching for function calls in the template

Type:

string

[ Top ]

$functionRegExp = ''

[line 325]

RegExp used to grep function calls in the template (set by the constructor)

See: _buildFunctionlist(), HTML_Template_Sigma::HTML_Template_Sigma()

Type:

string

[ Top ]

$includeRegExp = '##ime'

[line 345]

RegExp used to find file inclusion calls in the template (should have 'e' modifier)

Type:

string

[ Top ]

$openingDelimiter = '{'

[line 129]

First character of a variable placeholder ( _{_VARIABLE} ).

See: HTML_Template_Sigma::$closingDelimiter, HTML_Template_Sigma::$blocknameRegExp, HTML_Template_Sigma::$variablenameRegExp
Access: public

Type:

string

[ Top ]

$removeEmptyBlocks = true

[line 191]

Controls the handling of empty blocks, default is remove

Access: public

Type:

boolean

[ Top ]

$removeUnknownVariables = true

[line 184]

Controls the handling of unknown variables, default is remove

Access: public

Type:

boolean

[ Top ]

$removeVariablesRegExp = ''

[line 170]

RegExp used to strip unused variable placeholders

See: HTML_Template_Sigma::$variablesRegExp, HTML_Template_Sigma::HTML_Template_Sigma()

Type:

mixed

[ Top ]

$variablenameRegExp = '[0-9A-Za-z_-]+'

[line 157]

RegExp matching a variable placeholder in the template.

Per default "sm" is used as the regexp modifier, "i" is missing. That means a case sensitive search is done.

See: HTML_Template_Sigma::$blocknameRegExp, HTML_Template_Sigma::$openingDelimiter, HTML_Template_Sigma::$closingDelimiter
Access: public

Type:

string

[ Top ]

$variablesRegExp = ''

[line 164]

RegExp used to find variable placeholder, filled by the constructor

Var: Looks somewhat like @(delimiter varname delimiter)@
See: HTML_Template_Sigma::HTML_Template_Sigma()

Type:

string

[ Top ]

Method Detail

HTML_Template_Sigma (Constructor) [line 366]

HTML_Template_Sigma HTML_Template_Sigma(
[string
$root = ''], [string
$cacheRoot = ''])

Constructor: builds some complex regular expressions and optionally sets the root directories.

Make sure that you call this constructor if you derive your template class from this one.

See: HTML_Template_Sigma::setRoot(), HTML_Template_Sigma::setCacheRoot()

Parameters:

string	`$root`	—	root directory for templates
string	`$cacheRoot`	—	directory to cache "prepared" templates in

[ Top ]

addBlock [line 879]

mixed addBlock(
string
$placeholder, string
$block, string
$template)

Adds a block to the template changing a variable placeholder to a block placeholder.

This means that a new block will be integrated into the template in place of a variable placeholder. The variable placeholder will be removed and the new block will behave in the same way as if it was inside the original template.

The block content must not start with  and end with , if it does the error will be thrown.

Return: SIGMA_OK on success, error object on failure
See: HTML_Template_Sigma::addBlockfile()
Throws: PEAR_Error
Access: public

Parameters:

string	`$placeholder`	—	name of the variable placeholder, the name must be unique within the template.
string	`$block`	—	name of the block to be added
string	`$template`	—	content of the block

[ Top ]

addBlockfile [line 913]

mixed addBlockfile(
string
$placeholder, string
$block, string
$filename)

Adds a block taken from a file to the template, changing a variable placeholder to a block placeholder.

Return: SIGMA_OK on success, error object on failure
See: HTML_Template_Sigma::addBlock()
Throws: PEAR_Error
Access: public

Parameters:

string	`$placeholder`	—	name of the variable placeholder
string	`$block`	—	name of the block to be added
string	`$filename`	—	template file that contains the block

[ Top ]

blockExists [line 1011]

bool blockExists(
string
$block)

Checks if the block exists in the template

Access: public

Parameters:

string $block — block name

[ Top ]

clearVariables [line 1165]

void clearVariables(
)

Clears the variables

Global variables are not affected. The method is useful when you add a lot of variables via setVariable() and are not sure whether all of them appear in the block you parse(). If you clear the variables after parse(), you don't risk them suddenly showing up in other blocks.

See: HTML_Template_Sigma::setVariable()
Access: public

[ Top ]

errorMessage [line 455]

string errorMessage(
integer
$code, [string
$data = null])

Returns a textual error message for an error code

Return: error message
Access: public

Parameters:

integer	`$code`	—	error code
string	`$data`	—	additional data to insert into message

[ Top ]

get [line 509]

string get(
[string
$block = '__global__'], [bool
$clear = false])

Returns a block with all replacements done.

Return: block with all replacements done
See: HTML_Template_Sigma::show()
Throws: PEAR_Error
Access: public

Parameters:

string	`$block`	—	block name
bool	`$clear`	—	whether to clear parsed block contents

[ Top ]

getBlockList [line 1109]

array getBlockList(
[string
$parent = '__global__'], [bool
$recursive = false])

Returns a list of blocks within a template.

If $recursive is false, it returns just a 'flat' array of $parent's direct subblocks. If $recursive is true, it builds a tree of template blocks using $parent as root. Tree structure is compatible with PEAR::Tree's Memory_Array driver.

Return: a list of child blocks
Throws: PEAR_Error
Access: public

Parameters:

string	`$parent`	—	parent block name
bool	`$recursive`	—	whether to return a tree of child blocks (true) or a 'flat' array (false)

[ Top ]

getCurrentBlock [line 728]

string getCurrentBlock(
)

Returns the current block name

Return: block name
Access: public

[ Top ]

getPlaceholderList [line 1139]

array getPlaceholderList(
[string
$block = '__global__'])

Returns a list of placeholders within a block.

Only 'normal' placeholders are returned, not auto-created ones.

Return: a list of placeholders
Throws: PEAR_Error
Access: public

Parameters:

string $block — block name

[ Top ]

hideBlock [line 788]

mixed hideBlock(
string
$block)

Hides the block even if it is not "empty".

Is somewhat an opposite to touchBlock().

Consider a block (a 'edit' link for example) that should be visible to registered/"special" users only, but its visibility is triggered by some little 'id' field passed in a large array into setVariable(). You can either carefully juggle your variables to prevent the block from appearing (a fragile solution) or simply call hideBlock()

Return: SIGMA_OK on success, error object on failure
Throws: PEAR_Error
Access: public

Parameters:

string $block — block name

[ Top ]

loadTemplateFile [line 840]

mixed loadTemplateFile(
string
$filename, [boolean
$removeUnknownVariables = true], [boolean
$removeEmptyBlocks = true])

Loads a template file.

If caching is on, then it checks whether a "prepared" template exists. If it does, it gets loaded instead of the original, if it does not, then the original gets loaded and prepared and then the prepared version is saved. addBlockfile() and replaceBlockfile() implement quite the same logic.

Return: SIGMA_OK on success, error object on failure
See: HTML_Template_Sigma::setTemplate(), HTML_Template_Sigma::$removeUnknownVariables, HTML_Template_Sigma::$removeEmptyBlocks
Access: public

Parameters:

string	`$filename`	—	filename
boolean	`$removeUnknownVariables`	—	remove unknown/unused variables?
boolean	`$removeEmptyBlocks`	—	remove empty blocks?

[ Top ]

parse [line 547]

void parse(
[string
$block = '__global__'], [boolean
$flagRecursion = false], [boolean
$fakeParse = false])

Parses the given block.

See: HTML_Template_Sigma::parseCurrentBlock()
Throws: PEAR_Error
Access: public

Parameters:

string	`$block`	—	block name
boolean	`$flagRecursion`	—	true if the function is called recursively (do not set this to true yourself!)
boolean	`$fakeParse`	—	true if parsing a "hidden" block (do not set this to true yourself!)

[ Top ]

parseCurrentBlock [line 716]

void parseCurrentBlock(
)

Parses the current block

See: HTML_Template_Sigma::parse(), HTML_Template_Sigma::setCurrentBlock()
Access: public

[ Top ]

placeholderExists [line 1027]

string placeholderExists(
string
$placeholder, [string
$block = ''])

Returns the name of the (first) block that contains the specified placeholder.

Return: Name of the (first) block that contains the specified placeholder. If the placeholder was not found an empty string is returned.
Throws: PEAR_Error
Access: public

Parameters:

string	`$placeholder`	—	Name of the placeholder you're searching
string	`$block`	—	Name of the block to scan. If left out (default) all blocks are scanned.

[ Top ]

replaceBlock [line 953]

mixed replaceBlock(
string
$block, string
$template, [boolean
$keepContent = false])

Replaces an existing block with new content.

This function will replace a block of the template and all blocks contained in it and add a new block instead. This means you can dynamically change your template.

Sigma analyses the way you've nested blocks and knows which block belongs into another block. This nesting information helps to make the API short and simple. Replacing blocks does not only mean that Sigma has to update the nesting information (relatively time consuming task) but you have to make sure that you do not get confused due to the template change yourself.

Return: SIGMA_OK on success, error object on failure
See: HTML_Template_Sigma::replaceBlockfile(), HTML_Template_Sigma::addBlock()
Throws: PEAR_Error
Access: public

Parameters:

string	`$block`	—	name of a block to replace
string	`$template`	—	new content
boolean	`$keepContent`	—	true if the parsed contents of the block should be kept

[ Top ]

replaceBlockfile [line 982]

mixed replaceBlockfile(
string
$block, string
$filename, [boolean
$keepContent = false])

Replaces an existing block with new content from a file.

Return: SIGMA_OK on success, error object on failure
See: HTML_Template_Sigma::replaceBlock(), HTML_Template_Sigma::addBlockfile()
Throws: PEAR_Error
Access: public

Parameters:

string	`$block`	—	name of a block to replace
string	`$filename`	—	template file that contains the block
boolean	`$keepContent`	—	true if the parsed contents of the block should be kept

[ Top ]

setCacheRoot [line 418]

void setCacheRoot(
string
$root)

Sets the directory to cache "prepared" templates in, the directory should be writable for PHP.

The "prepared" template contains an internal representation of template structure: essentially a serialized array of $_blocks, $_blockVariables, $_children and $_functions, may also contain $_triggers. This allows to bypass expensive calls to _buildBlockVariables() and especially _buildBlocks() when reading the "prepared" template instead of the "source" one.

The files in this cache do not have any TTL and are regenerated when the source templates change.

See: HTML_Template_Sigma::HTML_Template_Sigma(), _getCached(), _writeCache()
Access: public

Parameters:

string $root — directory name

[ Top ]

setCallbackFunction [line 1082]

mixed setCallbackFunction(
string
$tplFunction, mixed
$callback, [bool
$preserveArgs = false])

Sets a callback function.

Sigma templates can contain simple function calls. This means that the author of the template can add a special placeholder to it: func_h1("embedded in h1") Sigma will parse the template for these placeholders and will allow you to define a callback function for them. Callback will be called automatically when the block containing such function call is parse()'d.

Please note that arguments to these template functions can contain variable placeholders: func_translate('Hello, {username}'), but not blocks or other function calls.

This should NOT be used to add logic (except some presentation one) to the template. If you use a lot of such callbacks and implement business logic through them, then you're reinventing the wheel. Consider using XML/XSLT, native PHP or some other template engine.

<?php function h_one($arg) { return '<h1>' . $arg . '</h1>'; } ... $tpl = new HTML_Template_Sigma( ... ); ... $tpl->setCallbackFunction('h1', 'h_one'); ?>

template: func_h1('H1 Headline');

Return: SIGMA_OK on success, error object on failure
Throws: PEAR_Error
Access: public

Parameters:

string	`$tplFunction`	—	Function name in the template
mixed	`$callback`	—	A callback: anything that can be passed to call_user_func_array()
bool	`$preserveArgs`	—	If true, then no variable substitution in arguments will take place before function call

[ Top ]

setCurrentBlock [line 700]

mixed setCurrentBlock(
[string
$block = '__global__'])

Sets the name of the current block: the block where variables are added

Return: SIGMA_OK on success, error object on failure
Throws: PEAR_Error
Access: public

Parameters:

string $block — block name

[ Top ]

setGlobalVariable [line 682]

void setGlobalVariable(
mixed
$variable, [string
$value = ''])

Sets a global variable value.

See: HTML_Template_Sigma::setVariable()
Access: public

Parameters:

mixed	`$variable`	—	variable name or array ('varname'=>'value')
string	`$value`	—	variable value if $variable is not an array

[ Top ]

setOption [line 437]

mixed setOption(
string
$option, mixed
$value)

Sets the option for the template class

Return: SIGMA_OK on success, error object on failure
Access: public

Parameters:

string	`$option`	—	option name
mixed	`$value`	—	option value

[ Top ]

setRoot [line 392]

void setRoot(
string
$root)

Sets the file root for templates. The file root gets prefixed to all filenames passed to the object.

See: HTML_Template_Sigma::HTML_Template_Sigma()
Access: public

Parameters:

string $root — directory name

[ Top ]

setTemplate [line 814]

mixed setTemplate(
string
$template, [boolean
$removeUnknownVariables = true], [boolean
$removeEmptyBlocks = true])

Sets the template.

You can either load a template file from disk with LoadTemplatefile() or set the template manually using this function.

Return: SIGMA_OK on success, error object on failure
See: loadTemplatefile()
Access: public

Parameters:

string	`$template`	—	template content
boolean	`$removeUnknownVariables`	—	remove unknown/unused variables?
boolean	`$removeEmptyBlocks`	—	remove empty blocks?

[ Top ]

setVariable [line 664]

void setVariable(
mixed
$variable, [string
$value = ''])

Sets a variable value.

The function can be used either like setVariable("varname", "value") or with one array $variables["varname"] = "value" given setVariable($variables)

Access: public

Parameters:

mixed	`$variable`	—	variable name or array ('varname'=>'value')
string	`$value`	—	variable value if $variable is not an array

[ Top ]

show [line 493]

void show(
[string
$block = '__global__'])

Prints a block with all replacements done.

See: HTML_Template_Sigma::get()
Access: public

Parameters:

string $block — block name

[ Top ]

touchBlock [line 759]

mixed touchBlock(
string
$block)

Preserves the block even if empty blocks should be removed.

Sometimes you have blocks that should be preserved although they are empty (no placeholder replaced). Think of a shopping basket. If it's empty you have to show a message to the user. If it's filled you have to show the contents of the shopping basket. Now where to place the message that the basket is empty? It's not a good idea to place it in you application as customers tend to like unecessary minor text changes. Having another template file for an empty basket means that one fine day the filled and empty basket templates will have different layouts.

So blocks that do not contain any placeholders but only messages like "Your shopping basked is empty" are intoduced. Now if there is no replacement done in such a block the block will be recognized as "empty" and by default ($removeEmptyBlocks = true) be stripped off. To avoid this you can call touchBlock()

Return: SIGMA_OK on success, error object on failure
See: HTML_Template_Sigma::$removeEmptyBlocks, $_touchedBlocks
Throws: PEAR_Error
Access: public

Parameters:

string $block — block name

[ Top ]

Class: HTML_Template_Sigma

Class Overview

Author(s):

Version:

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

Class Variables

$blocknameRegExp = '[0-9A-Za-z_-]+'

$blockRegExp = ''

$closingDelimiter = '}'

$currentBlock = '__global__'

$fileRoot = ''

$flagGlobalParsed = false

$functionnameRegExp = '[_a-zA-Z]+[A-Za-z_0-9]*'

$functionPrefix = 'func_'

$functionRegExp = ''

$includeRegExp = '##ime'

$openingDelimiter = '{'

$removeEmptyBlocks = true

$removeUnknownVariables = true

$removeVariablesRegExp = ''

$variablenameRegExp = '[0-9A-Za-z_-]+'

$variablesRegExp = ''

Method Detail

HTML_Template_Sigma (Constructor) [line 366]

Parameters:

addBlock [line 879]

Parameters:

addBlockfile [line 913]

Parameters:

blockExists [line 1011]

Parameters:

clearVariables [line 1165]

errorMessage [line 455]

Parameters:

get [line 509]

Parameters:

getBlockList [line 1109]

Parameters:

getCurrentBlock [line 728]

getPlaceholderList [line 1139]

Parameters:

hideBlock [line 788]

Parameters:

loadTemplateFile [line 840]

Parameters:

parse [line 547]

Parameters:

parseCurrentBlock [line 716]

placeholderExists [line 1027]

Parameters:

replaceBlock [line 953]

Parameters:

replaceBlockfile [line 982]

Parameters:

setCacheRoot [line 418]

Parameters:

setCallbackFunction [line 1082]

Parameters:

setCurrentBlock [line 700]

Parameters:

setGlobalVariable [line 682]

Parameters:

setOption [line 437]

Parameters:

setRoot [line 392]

Parameters:

setTemplate [line 814]

Parameters:

setVariable [line 664]

Parameters:

show [line 493]

Parameters:

touchBlock [line 759]

Parameters:

$currentBlock = 'global'