library/Dot/Template.php

Properties

Description

This code that was derived from the original PHPLIB Template class is copyright by Kristian Koehntopp, NetUSE AG and was released under the LGPL.

DotBoost Technologies Inc. DotKernel Application Framework

Classes

Dot_Template

Properties

Extends

Implements

author

Kristian Koehntopp <kris@koehntopp.de>

author

DotKernel Team <team@dotkernel.com>

Description

Template engine, based on PHPLIB Template class

Methods

__clone, __construct, _endTimer, _filename, _halt, _haltMsg, _loadFile, _startTimer, _varname, exists, finish, get, getInstance, getLastError, getUndefined, getVar, getVars, initBlock, initVar, p, parse, pparse, psubst, setBlock, setFile, setRoot, setUnknowns, setVar, subst, unsetVar, varExists,

__clone( ) : void

Description

Singleton pattern implementation makes 'clone' unavailable

Return value

Type	Description
void

Tags

Name	Description
access	protected

__construct( string $root = ., string $unknowns = remove, array $fallback, ) : void

Description

Singleton pattern implementation makes 'new' unavailable

Arguments

Name	Type	Description	Default
$root	string	Template root directory	.
$unknowns	string	How to handle unknown variables	remove
$fallback	array	Fallback paths

Return value

Type	Description
void

Tags

Name	Description
access	protected

_endTimer( $varname, ) : float

Description

Return the end time

Arguments

Name	Type	Description	Default
$varname	n/a

Return value

Type	Description
float

Tags

Name	Description
access	private

_filename( string $filename, ) : string

Description

When called with a relative pathname, this function will return the pathname with $this->_root prepended. Absolute pathnames are returned unchanged.

RETURNS: a string containing an absolute pathname. USAGE: filename(string $filename)

Arguments

Name	Type	Description	Default
$filename	string

Return value

Type	Description
string

Tags

Name	Description
access	private
see	set_root

_halt( string $msg, ) : bool

Description

Is called whenever an error occurs and will handle the error according to the policy defined in $this->_haltOnError. Additionally the error message will be saved in $this->_lastError.

USAGE: _halt(string $msg)

Arguments

Name	Type	Description	Default
$msg	string

Return value

Type	Description
bool

Tags

Name	Description
access	private

_haltMsg( string $msg, ) : void

Description

Prints an error message.

It can be overridden by your subclass of Template. It will be called with an error message to display. USAGE: _haltMsg(string $msg)

Arguments

Name	Type	Description	Default
$msg	string

Return value

Type	Description
void

Tags

Name	Description
access	private

_loadFile( string $varname, ) : bool

Description

If a variable's value is undefined and the variable has a filename stored in $this->_file[$varname] then the backing file will be loaded and the file's contents will be assigned as the variable's value.

USAGE: loadFile(string $varname)

Arguments

Name	Type	Description	Default
$varname	string

Return value

Type	Description
bool

Tags

Name	Description
access	private

_startTimer( ) : array

Description

Start the time to measure something

Return value

Type	Description
array

Tags

Name	Description
access	private

_varname( string $varname, ) : string

Description

Will construct a regexp for a given variable name with any special chars quoted.

Arguments

Name	Type	Description	Default
$varname	string

Return value

Type	Description
string

Tags

Name	Description
access	private

exists( string|array $var, ) : bool

Description

Inspired From PEAR HTML_Template_PHPLIB 1.4.0 Checks if the given variable exists.

When an array is given, it is checked if all variables exist.

Arguments

Name	Type	Description	Default
$var	string\|array	Variable to check

Return value

Type	Description
bool

Tags

Name	Description
access	public

finish( string $str, ) : string

Description

Returns the finished version of $str.

USAGE: finish(string $str)

Arguments

Name	Type	Description	Default
$str	string

Return value

Type	Description
string

Tags

Name	Description
access	public

get( string $varname, ) : void

Description

Returns the finished version of the value of the variable named by $varname.

USAGE: get(string $varname)

Arguments

Name	Type	Description	Default
$varname	string

Return value

Type	Description
void

Tags

Name	Description
access	public

getInstance( string $root = ., string $unknowns = remove, array $fallback, ) : Dot_Template

Description

Returns an instance of Dot_View Singleton pattern implementation

Arguments

Name	Type	Description	Default
$root	string	Template root directory	.
$unknowns	string	How to handle unknown variables	remove
$fallback	array	Fallback paths

Return value

Type	Description
Dot_Template

Tags

Name	Description
access	public
static

getLastError( ) : boolean|string

Description

Returns the last error message if any

Return value

Type	Description
boolean\|string	Last error message if any

Tags

Name	Description
access	public

getUndefined( string $varname, ) : array

Description

Returns a hash of unresolved variable names in $varname, keyed by their names (that is, the hash has the form $a[$name] = $name).

USAGE: getUndefined(string $varname)

Arguments

Name	Type	Description	Default
$varname	string

Return value

Type	Description
array	or false

Tags

Name	Description
access	public

getVar( mixed $varname, ) : mixed

Description

Returns the value of the variable named by $varname.

If $varname references a file and that file has not been loaded yet, the variable will be reported as empty. When called with an array of variable names this public function will return a a hash of variable values keyed by their names. USAGE: getVar(string $varname) or USAGE: getVar(array $varname)

Arguments

Name	Type	Description	Default
$varname	mixed

Return value

Type	Description
mixed

Tags

Name	Description
access	public

getVars( ) : array

Description

Returns an associative array of all defined variables with the name as the key and the value of the variable as the value.

This is mostly useful for debugging. Also note that $this->_debug can be used to echo all variable assignments as they occur and to trace execution. USAGE: getVars()

Return value

Type	Description
array

Tags

Name	Description
access	public

initBlock( mixed $target, mixed $value, $append = false, ) : bool

Description

Initialize a block A variable $parent may contain a variable block defined by:  content . This public function removes that block from $parent and replaces it with a variable reference named $name.

The block is inserted into the varkeys and varvals hashes. If $name is omitted, it is assumed to be the same as $varname. Blocks may be nested but care must be taken to extract the blocks in order from the innermost block to the outermost block. USAGE: setBlock(string $parent, string $varname, [string $name = ''])

Arguments

Name	Type	Default
$target	mixed
$value	mixed
$append	n/a	false

Return value

Type	Description
bool

Tags

Name	Description
access	public

initVar( mixed $varname, mixed $value, bool $append = false, ) : void

Description

Initialize the value of a variable.

It may be called with either a varname and a value as two strings or an an associative array with the key being the varname and the value being the new variable value. The public function inserts the new value of the variable into the $varkeys and $varvals hashes. It is not necessary for a variable to exist in these hashes before calling this public function. An optional third parameter allows the value for each varname to be appended to the existing variable instead of replacing it. The default is to replace. USAGE: initVar(string $varname, [string $value = ''], [boolean $append = false]) or USAGE: initVar(array $varname = (string $varname => string $value), [mixed $dummy_var], [boolean $append = false]) or USAGE: initVar(array $varname = (string $value), [mixed $dummy_var], [boolean $append = false])

Arguments

Name	Type	Default
$varname	mixed
$value	mixed
$append	bool	false

Return value

Type	Description
void

Tags

Name	Description
access	public

p( string $varname, ) : void

Description

Prints the finished version of the value of the variable named by $varname.

USAGE: p(string $varname)

Arguments

Name	Type	Description	Default
$varname	string

Return value

Type	Description
void

Tags

Name	Description
access	public

parse( string $target, mixed $varname, bool $append = false, ) : mixed

Description

Substitutes the values of all defined variables in the variable named $varname and stores or appends the result in the variable named $target.

It may be called with either a target and a varname as two strings or a target as a string and an array of variable names in varname. The public function inserts the new value of the variable into the $varkeys and $varvals hashes. It is not necessary for a variable to exist in these hashes before calling this public function. An optional third parameter allows the value for each varname to be appended to the existing target variable instead of replacing it. The default is to replace. If $target and $varname are both strings, the substituted value of the variable $varname is inserted into or appended to $target. If $handle is an array of variable names the variables named by $handle are sequentially substituted and the result of each substitution step is inserted into or appended to in $target. The resulting substitution is available in the variable named by $target, as is each intermediate step for the next $varname in sequence. Note that while it is possible, it is only rarely desirable to call this public function with an array of varnames and with $append = true. USAGE: parse(string $target, string $varname, [boolean $append]) or USAGE: parse(string $target, array $varname = (string $varname), [boolean $append])

Arguments

Name	Type	Default
$target	string
$varname	mixed
$append	bool	false

Return value

Type	Description
mixed

Tags

Name	Description
access	public

pparse( string $target, mixed $varname, bool $append = false, ) : bool

Description

This is shorthand for print $this->parse(...) and is public functionally identical.

USAGE: pparse(string $target, string $varname, [boolean $append]) or USAGE: pparse(string $target, array $varname = (string $varname), [boolean $append])

Arguments

Name	Type	Default
$target	string
$varname	mixed
$append	bool	false

Return value

Type	Description
bool	FALSE

Tags

Name	Description
access	public

psubst( string $varname, ) : bool

Description

This is shorthand for print $this->subst($varname). See subst for further details.

USAGE: psubst(string $varname)

Arguments

Name	Type	Description	Default
$varname	string

Return value

Type	Description
bool

Tags

Name	Description
access	public

setBlock( string $parent, string $varname, string $name, ) : bool

Description

A variable $parent may contain a variable block defined by:  content . This public function removes that block from $parent and replaces it with a variable reference named $name.

Arguments

Name	Type	Description	Default
$parent	string
$varname	string
$name	string

Return value

Type	Description
bool

Tags

Name	Description
access	public

setFile( string $varname, string $filename, ) : bool

Description

Defines a filename for the initial value of a variable.

It may be passed either a varname and a file name as two strings or a hash of strings with the key being the varname and the value being the file name. The new mappings are stored in the array $this->file. The files are not loaded yet, but only when needed. USAGE: setFile(array $filelist = (string $varname => string $filename)) or USAGE: setFile(string $varname, string $filename)

Arguments

Name	Type	Description	Default
$varname	string
$filename	string

Return value

Type	Description
bool

Tags

Name	Description
access	public

setRoot( $root, ) : bool

Description

Checks that $root is a valid directory and if so sets this directory as the base directory from which templates are loaded by storing the value in $this->root. Relative filenames are prepended with the path in $this->root.

Arguments

Name	Type	Description	Default
$root	n/a

Return value

Type	Description
bool

Tags

Name	Description
access	public

setUnknowns( string $unknowns = remove, ) : void

Description

Sets the policy for dealing with unresolved variable names.

Arguments

Name	Type	Description	Default
$unknowns	string	- default = 'remove'	remove

Return value

Type	Description
void

Tags

Name	Description
access	public

setVar( mixed $varname, mixed $value, bool $append = false, ) : bool

Description

Sets the value of a variable.

It may be called with either a varname and a value as two strings or an an associative array with the key being the varname and the value being the new variable value. The public function inserts the new value of the variable into the $varkeys and $varvals hashes. It is not necessary for a variable to exist in these hashes before calling this public function. An optional third parameter allows the value for each varname to be appended to the existing variable instead of replacing it. The default is to replace. This feature was introduced after the 7.2d release. USAGE: setVar(string $varname, [string $value = ''], [boolean $append = false]) or USAGE: setVar(array $varname = (string $varname => string $value), [mixed $dummy_var], [boolean $append = false])

Arguments

Name	Type	Default
$varname	mixed
$value	mixed
$append	bool	false

Return value

Type	Description
bool

Tags

Name	Description
access	public

subst( mixed $varname, ) : mixed

Description

Fills in all the variables contained within the variable named $varname. The resulting value is returned as the public function result and the original value of the variable varname is not changed. The resulting string is not 'finished'.

RETURNS: the value of the variable $varname with all variables substituted or FALSE if halted USAGE: subst(string $varname)

Arguments

Name	Type	Description	Default
$varname	mixed

Return value

Type	Description
mixed

Tags

Name	Description
access	public

unsetVar( mixed $varname, ) : void

Description

Unsets a variable completely.

It may be called with either a varname as a string or an array with the values being the varnames to be cleared. The public function removes the variable from the $varkeys and $varvals hashes. It is not necessary for a variable to exist in these hashes before calling this public function. USAGE: unsetVar(string $varname) or USAGE: unsetVar(array $varname = (string $varname))

Arguments

Name	Type	Description	Default
$varname	mixed

Return value

Type	Description
void

Tags

Name	Description
access	public

varExists( string $token, ) : bool

Description

Checks if the given variable exists as token inside the declared variables or files content.

Arguments

Name	Type	Description	Default
$token	string	Variable to check

Return value

Type	Description
bool

Tags

Name	Description
since	1.3.1
access	public

Properties

$_debug, $_debugBlock, $_endTime, $_file, $_fileFallbacks, $_filenameComments, $_haltOnError, $_instance, $_lastError, $_root, $_startTime, $_unknownRegexp, $_unknowns, $_varkeys, $_varvals,

private $_debug = false

If set, echo assignmentsbool

private $_debugBlock = false

If set, echo blocks time parsebool

private $_endTime = array

End time array

private $_file = array

$file[handle] = 'filename';array

private $_fileFallbacks = array

fallback paths that should be defined in a child classarray

private $_filenameComments = false

Determines whether Template outputs filename comments.string
<p>false = no filename outputs true = HTML comments (e.g. ) placed in output</p>

private $_haltOnError = yes

'yes' => halt, 'report' => report error, continue, 'no' => ignore error quietlystring

protected static $_instance = null

Singleton instanceDot_Template

private $_lastError =

The last error message is retained herestring

private $_root = ..

Relative filenames are relative to this pathnamestring

private $_startTime = array

Start time array

private $_unknownRegexp = loose

Determines the regular expression used to find unknown variable tags.bool
<p>'loose' = traditional match all curly braces with no whitespace between 'strict' = adopts PHP's variable naming rules</p>

private $_unknowns = remove

'remove' => remove undefined variables 'comment' => replace undefined variables with comments 'keep' => keep undefined variablesstring

private $_varkeys = array

$varkeys[key] = 'key'array

private $_varvals = array

$varvals[key] = 'value';array