Packageindex Classtrees Modulegroups Elementlist Report XML Files
 
File: c:/www/apache/doc2//form/IT.php
PEAR Integrated Template [Extension] - IT[X], 11.02.2001 -

IntegratedTemplate

IntegratedTemplate

Integrated Template - IT

 

public class IntegratedTemplate

Integrated Template - IT
Well there's not much to say about it. I needed a template class thatsupports a single template file with multiple (nested) blocks inside anda simple block API.The Isotemplate API is somewhat tricky for a beginner although it is the bestone you can build. template::parse() [phplib template = Isotemplate] requestsyou to name a source and a target where the current block gets parsed into.Source and target can be block names or even handler names. This API gives youa maximum of fexibility but you always have to know what you do which isquite unusual for php skripter like me.I noticed that I do not any control on which block gets parsed into which one.If all blocks are within one file, the script knows how they are nested and inwhich way you have to parse them. IT knows that inner1 is a child of block2, there'sno need to tell him about this.<table border><tr><td colspan=2>__global__<p>(hidden and automatically added)</td></tr><tr><td>block1</td><td><table border><tr><td colspan=2>block2</td></tr><tr><td>inner1</td><td>inner2</td></tr></table></td></tr></table>To add content to block1 you simply type:<code>$tpl->setCurrentBlock("block1");</code>and repeat this as often as needed:<code>$tpl->setVariable(...);$tpl->parseCurrentBlock();</code>To add content to block2 you would type something like:<code>$tpl->setCurrentBlock("inner1");$tpl->setVariable(...);$tpl->parseCurrentBlock();$tpl->setVariable(...);$tpl->parseCurrentBlock();$tpl->parse("block1");</code>This will result in one repition of block1 which contains two repitionsof inner1. inner2 will be removed if $removeEmptyBlock is set to true which is the default.Usage:<code>$tpl = new IntegratedTemplate( [string filerootdir] );// 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 Isotemplates 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()$tpl->get();</code>

AuthorsUlf Wendel <uw@netuse.de>
Version$Id: IT.php,v 1.3 2001/01/19 13:37:03 sbergmann Exp $
 
Direct known subclasses: IntegratedTemplateExtension

Public Method Summary
void

IntegratedTemplate([ string $root ])

Builds some complex regular expressions and optinally sets the file root directory.
string

get([ string $block ])

Returns a block with all replacements done.
void

parse([ string $block ], boolean $flag_recursion)

Parses the given block.
void

parseCurrentBlock()

Parses the current block
void

setVariable(mixed $variable)

Sets a variable value.
boolean

setCurrentBlock([ string $block ])

Sets the name of the current block that is the block where variables are added.
boolean

touchBlock(string $block)

Preserves an empty block even if removeEmptyBlocks is true.
void

init()

Clears all datafields of the object and rebuild the internal blocklist
void

free()

Clears all datafields of the object.
void

setTemplate(string $template)

Sets the template.
boolean

loadTemplatefile(string $filename, [ boolean $removeUnknownVariables, boolean $removeEmptyBlocks ])

Reads a template file from the disk.
void

setRoot(string $root)

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

Private Method Summary
void

show([ string $block ])

Print a certain block with all replacements done.
void

buildBlockvariablelist()

Build a list of all variables within of a block
void

getGlobalvariables()

Returns a list of all
void

findBlocks(string $string)

Recusively builds a list of all blocks within the template.
string

getFile(string $filename)

Reads a file from disk and returns its content.
void

halt(string $message, [ mixed $file, integer $line ])

Error Handling function.

Public Field Summary
array

$err

Contains the error objects
boolean

$printError

Print error messages?
boolean

$haltOnError

Call die() on error?
string

$openingDelimiter

First character of a variable placeholder ( _ ).
string

$closingDelimiter

Last character of a variable placeholder ( _ ).
string

$blocknameRegExp

RegExp matching a block in the template.
string

$variablenameRegExp

RegExp matching a variable placeholder in the template.
string

$variablesRegExp

RegExp used to find variable placeholder, filled by the constructor.
boolean

$removeUnknownVariables

Controls the handling of unknown variables, default is remove.
boolean

$removeEmptyBlocks

Controls the handling of empty blocks, default is remove.

Private Field Summary
boolean

$clearCache

Clear cache on get()?
string

$removeVariablesRegExp

RegExp used to strip unused variable placeholder.
string

$blockRegExp

RegExp used to find blocks an their content, filled by the constructor.
string

$currentBlock

Name of the current block.
string

$template

Content of the template.
array

$blocklist

Array of all blocks and their content.
array

$blockdata

Array with the parsed content of a block.
array

$blockvariables

Array of variables in a block.
array

$blockinner

Array of inner blocks of a block.
array

$touchedBlocks

List of blocks to preverse even if they are "empty".
array

$variableCache

Variable cache.
boolean

$clearCacheOnParse

Clear the variable cache on parse?
string

$fileRoot

Root directory for all file operations.
boolean

$flagBlocktrouble

Internal flag indicating that a blockname was used multiple times.
boolean

$flagGlobalParsed

Flag indicating that the global block was parsed.
boolean

$flagCacheTemplatefile

EXPERIMENTAL! FIXME!
string

$lastTemplatefile

EXPERIMENTAL! FIXME!

Public Method Details

IntegratedTemplate

public void IntegratedTemplate( [ string $root ] )
  Builds some complex regular expressions and optinally sets the file root directory.
Make sure that you call this constructor if you derive your templateclass from this one.

Parameter
string $root = >>""<<
root directory, prefix for all filenames given to the object.
Returns void

See Also setRoot()

get

public string get( [ string $block ] )
  Returns a block with all replacements done.

Parameter
string $block = >>"__global__"<<
of the block
Returns string

See Also show()

parse

public void parse( [ string $block ], boolean $flag_recursion )
  Parses the given block.

Parameter
string $block = >>"__global__"<<
of the block to be parsed
boolean $flag_recursion
Warning: documentation is missing.
Returns void

See Also parseCurrentBlock()

parseCurrentBlock

public void parseCurrentBlock( )
  Parses the current block

Returns void

See Also parse(), setCurrentBlock(), $currentBlock

setVariable

public void setVariable( mixed $variable )
  Sets a variable value.
The function can be used eighter like setVariable( "varname", "value")or with one array $variables["varname"] = "value" given setVariable($variables)quite like phplib templates set_var().

Parameter
mixed $variable
with the variable name or an array %variables["varname"] = "value"
Returns void

setCurrentBlock

public boolean setCurrentBlock( [ string $block ] )
  Sets the name of the current block that is the block where variables are added.

Parameter
string $block = >>"__global__"<<
of the block
Returns boolean

false on failure, otherwise true

touchBlock

public boolean touchBlock( string $block )
  Preserves an empty block even if removeEmptyBlocks is true.

Parameter
string $block
of the block
Returns boolean

false on false, otherwise true
See Also $removeEmptyBlocks

init

public void init( )
  Clears all datafields of the object and rebuild the internal blocklist
LoadTemplatefile() and setTemplate() automatically call this functionwhen a new template is given. Don't use this functionunless you know what you're doing.

Returns void

See Also free()

free

public void free( )
  Clears all datafields of the object.
Don't use this function unless you know what you're doing.

Returns void

See Also init()

setTemplate

public void setTemplate( string $template )
  Sets the template.
You can eighter load a template file from disk with LoadTemplatefile() or set thetemplate manually using this function.

Parameter
string $template
content
Returns void

See Also LoadTemplatefile(), $template

loadTemplatefile

public boolean loadTemplatefile( string $filename, [ boolean $removeUnknownVariables, boolean $removeEmptyBlocks ] )
  Reads a template file from the disk.

Parameter
string $filename
of the template file
boolean $removeUnknownVariables = >>true<<
to handle unknown variables.
boolean $removeEmptyBlocks = >>true<<
to handle empty blocks.
Returns boolean

false on failure, otherwise true
See Also $template, $removeUnknownVariables, $removeEmptyBlocks, setTemplate()

setRoot

public void setRoot( string $root )
  Sets the file root. The file root gets prefixed to all filenames passed to the object.
Make sure that you override this function when using the classon windows.

Parameter
string $root
Returns void

See Also IntegratedTemplate()

Private Method Details

show

private void show( [ string $block ] )
  Print a certain block with all replacements done.

Parameter
string $block = >>"__global__"<<
of the block
Returns void

See Also show()

buildBlockvariablelist

private void buildBlockvariablelist( )
  Build a list of all variables within of a block

Returns void

getGlobalvariables

private void getGlobalvariables( )
  Returns a list of all

Returns void

findBlocks

private void findBlocks( string $string )
  Recusively builds a list of all blocks within the template.

Parameter
string $string
that gets scanned
Returns void

See Also $blocklist

getFile

private string getFile( string $filename )
  Reads a file from disk and returns its content.

Parameter
string $filename
Returns string

Filecontent

halt

private void halt( string $message, [ mixed $file, integer $line ] )
  Error Handling function.

Parameter
string $message
message
mixed $file = >>""<<
where the error occured
integer $line = >>0<<
where the error occured
Returns void

See Also $err

Public Field Details

$err

public array $err

>>array()<<

Contains the error objects

See Also halt(), $printError, $haltOnError

$printError

public boolean $printError

>>false<<

Print error messages?

See Also halt(), $haltOnError, $err

$haltOnError

public boolean $haltOnError

>>false<<

Call die() on error?

See Also halt(), $printError, $err

$openingDelimiter

public string $openingDelimiter

>>"{"<<

First character of a variable placeholder ( _ ).

See Also $closingDelimiter, $blocknameRegExp, $variablenameRegExp

$closingDelimiter

public string $closingDelimiter

>>"}"<<

Last character of a variable placeholder ( _ ).

See Also $openingDelimiter, $blocknameRegExp, $variablenameRegExp

$blocknameRegExp

public string $blocknameRegExp

>>"[0-9A-Za-z_-]+"<<

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

See Also $variablenameRegExp, $openingDelimiter, $closingDelimiter

$variablenameRegExp

public string $variablenameRegExp

>>"[0-9A-Za-z_-]+"<<

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 Also $blocknameRegExp, $openingDelimiter, $closingDelimiter

$variablesRegExp

public string $variablesRegExp

>>""<<

RegExp used to find variable placeholder, filled by the constructor.

See Also IntegratedTemplate()

$removeUnknownVariables

public boolean $removeUnknownVariables

>>true<<

Controls the handling of unknown variables, default is remove.

$removeEmptyBlocks

public boolean $removeEmptyBlocks

>>true<<

Controls the handling of empty blocks, default is remove.

Private Field Details

$clearCache

private boolean $clearCache

>>false<<

Clear cache on get()?

$removeVariablesRegExp

private string $removeVariablesRegExp

>>""<<

RegExp used to strip unused variable placeholder.

$blockRegExp

private string $blockRegExp

>>""<<

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

See Also IntegratedTemplate()

$currentBlock

private string $currentBlock

>>"__global__"<<

Name of the current block.

$template

private string $template

>>""<<

Content of the template.

$blocklist

private array $blocklist

>>array()<<

Array of all blocks and their content.

See Also findBlocks()

$blockdata

private array $blockdata

>>array()<<

Array with the parsed content of a block.

$blockvariables

private array $blockvariables

>>array()<<

Array of variables in a block.

$blockinner

private array $blockinner

>>array()<<

Array of inner blocks of a block.

$touchedBlocks

private array $touchedBlocks

>>array()<<

List of blocks to preverse even if they are "empty".
This is something special. Sometimes you have blocks thatshould be preserved although they are empty (no placeholder replaced).Think of a shopping basket. If it's empty you have to drop a message tothe user. If it's filled you have to show the contents of the shopping baseket.Now where do you place the message that the basket is empty? It's no goodidea to place it in you applications as customers tend to like unecessary minortext changes. Having another template file for an empty basket means that it'svery likely that one fine day the filled and empty basket templates have differentlayout. I decided to introduce blocks that to not contain any placeholder but onlytext such as the message "Your shopping basked is empty".Now if there is no replacement done in such a block the block will be recognizedas "empty" and by default ($removeEmptyBlocks = true) be stripped off. To avoid thisyou can now call touchBlock() to avoid this.The array $touchedBlocks stores a list of touched block which must not be removed evenif they are empty.

See Also touchBlock(), $removeEmptyBlocks

$variableCache

private array $variableCache

>>array()<<

Variable cache.
Variables get cached before any replacement is done.Advantage: empty blocks can be removed automatically.Disadvantage: might take some more memory

See Also setVariable(), $clearCacheOnParse

$clearCacheOnParse

private boolean $clearCacheOnParse

>>false<<

Clear the variable cache on parse?
If you're not an expert just leave the default false.True reduces memory consumption somewhat if you tend toadd lots of values for unknown placeholder.

$fileRoot

private string $fileRoot

>>""<<

Root directory for all file operations.
The string gets prefixed to all filenames given.

See Also IntegratedTemplate(), setRoot()

$flagBlocktrouble

private boolean $flagBlocktrouble

>>false<<

Internal flag indicating that a blockname was used multiple times.

$flagGlobalParsed

private boolean $flagGlobalParsed

>>false<<

Flag indicating that the global block was parsed.

$flagCacheTemplatefile

private boolean $flagCacheTemplatefile

>>true<<

EXPERIMENTAL! FIXME!
Flag indication that a template gets cached.Complex templates require some times to be preparsedbefore the replacement can take place. Often I useone template file over and over again but I don't knowbefore that I will use the same template file again.Now IT could notice this and skip the preparse.

$lastTemplatefile

private string $lastTemplatefile

>>""<<

EXPERIMENTAL! FIXME!

Packageindex Classtrees Modulegroups Elementlist Report XML Files
PHPDoc 1.0beta