InTemplate - Developer Guide

About InTemplate

This class is a modified version of CDI's FastTemplates.

FastTemplates was originally written by some nice guys fromCDI <cdi@thewebmasters.net>, you can download the source here : http://www.thewebmasters.net/php/

Since it was written back then when we were still using PHP3, there are many 'old' function that should be replaced to gain a faster yet reliable templating system. Which I (and you) despradly need. Also, there are many features that i think should be included in a 'so called' templating system.

So, that brings me to InTemplate. See User Guide for detail use of this class.

Anyway, the name InTemplate goes to InArtS Multimedia, the place where i get real money. :-)

Authors CDI <cdi@thewebmasters.net>, Eris Ristemena <eris@ristemena.com>
Version 0.1

 

Public Method Summary

void InTemplate([ string $pathToTemplates ])
  Set the directory which all templates reside
 
boolean Define(array $fileList)
  Maps a template filename to a (usually shorter) name.
 
boolean DefineDynamic(string $Macro, string $parentName)
  A dynamic block lives inside another template file.
 
void Assign(array $parseVars, [ string $trailer ])
  Assigns values for var.
 
void Parse(string $ReturnVar, array $FileTags, [ string $lowerVar ])
  The meat of the whole class. The magic happens here.
 
void InPrint(string $template)
  Print the templates which has been modified.
 
void Fetch([ string $template ])
  Returns the raw data from a parsed handle.
 
boolean ClearDynamic([ string $Macro ])
  Strips a DYNAMIC BLOCK from a template.
 
void ClearParse([ string $returnVar ])
  Removes a given reference from the list of refs that is built using: $tpl->Assign(KEY = val);
 
void ClearAll()
  Clear all
 
void ClearTemplate(string $fileHandle)
  Clear templates
 
void ClearDefine([ string $fileTag ])
  Clears the internal list that stores data passed to $tpl->define();
 
void ClearAssign()
  Clears all variables set by assign()
 
void ShowUnknowns(string $line)
  Prints the warnings for unresolved variable references in template files.
 
void Strict()
  Strict template checking, if true sends warnings to STDOUT when
 
void NoStrict()
  Silently discards (removes) undefined variable references
 
boolean GetAssigned([ string $tpl_name ])
  Return the value of an assigned variable.
 
void AssignInclude(string $Macro, string $include)
  Handle any included file using include()
 

Private Method Summary

void SetRoot(string $root)
  All templates will be loaded from this "root" directory.
 
boolean IsSafe(string $fileName)
  A quick check of the template file before reading it.
 
string GetTemplate(string $template)
  Grabs a template from the root dir and
 
string ParseTemplate(string $template, array $parseVars)
  This routine does the actual to VALUE conversion within the template.
 
void ParseDynamic(string $MacroName, string $Macro, [ string $alt ])
  Parse a dynamic block
 
void Clear([ string $returnVar ])
  General clearance
 
void ClearHref(string $href)
  Clears all href
 
void Error(string $errorMsg, [ integer $die ])
  Prints any error message.
 
void utime()
  Calculates current microtime
 

Private Field Summary

array

$mFileList

Holds the array of filehandles mFileList[HANDLE] == "fileName"
array

$mDynamic

Holds the array of dynamic blocks,
array

$mParseVars

Holds the array of Variable handles.
array

$mLoaded

We only want to load a template once - when it's used.
array

$mHandle

Holds the handle names assigned by a call to parse()
array

$mSeling

Holds the handle names for selang-seling
string

$mRoot

Holds path-to-templates
boolean

$mWin32

Set to true if this is a WIN32 server
string

$mError

Holds the last error message
string

$mLast

Holds the HANDLE to the last template parsed by parse()
boolean

$mStrict

Strict template checking.
boolean

$append

Public Method Details

InTemplate

public void InTemplate( [ string $pathToTemplates ] )

  Set the directory which all templates reside

Parameter
string $pathToTemplates = >>""<<
path to templates
Returns void


Define

public boolean Define( array $fileList )

  Maps a template filename to a (usually shorter) name.
This new name is the name that you will use to refer to the templates.Let's just call it 'file tag'.

Parameter
array $fileList
array of template files
Returns boolean


DefineDynamic

public boolean DefineDynamic( string $Macro, string $parentName )

  A dynamic block lives inside another template file.
It will be stripped from the template when parsedand replaced with the {$Tag}.

Parameter
string $Macro
macro's name for dynamic block
string $parentName
parent var name
Returns boolean


Assign

public void Assign( array $parseVars, [ string $trailer ] )

  Assigns values for var.

Parameter
array $parseVars
array(var,value) or just a var (with value in trailer)
string $trailer = >>""<<
the value used only if $parseVars is not an array
Returns void


Parse

public void Parse( string $ReturnVar, array $FileTags, [ string $lowerVar ] )

  The meat of the whole class. The magic happens here.

Parameter
string $ReturnVar
the return variable
array $FileTags
file tags
string $lowerVar = >>""<<
lower var, for cascading block
Returns void

See Also Define(), DefineDynamic(), ParseTemplate()

InPrint

public void InPrint( string $template )

  Print the templates which has been modified.

Parameter
string $template
Warning: documentation is missing.
Returns void


Fetch

public void Fetch( [ string $template ] )

  Returns the raw data from a parsed handle.

Parameter
string $template = >>""<<
name of the templates
Returns void


ClearDynamic

public boolean ClearDynamic( [ string $Macro ] )

  Strips a DYNAMIC BLOCK from a template.

Parameter
string $Macro = >>""<<
Returns boolean


ClearParse

public void ClearParse( [ string $returnVar ] )

  Removes a given reference from the list of refs that is built using: $tpl->Assign(KEY = val);
If called with no arguments, it removes all references from the array.

Parameter
string $returnVar = >>""<<
clear any parsed variable from Assign()
Returns void

See Also Assign(), Clear()

ClearAll

public void ClearAll( )

  Clear all

Returns void


ClearTemplate

public void ClearTemplate( string $fileHandle )

  Clear templates

Parameter
string $fileHandle
Warning: documentation is missing.
Returns void


ClearDefine

public void ClearDefine( [ string $fileTag ] )

  Clears the internal list that stores data passed to $tpl->define();

Parameter
string $fileTag = >>""<<
file tag
Returns void


ClearAssign

public void ClearAssign( )

  Clears all variables set by assign()

Returns void


ShowUnknowns

public void ShowUnknowns( string $line )

  Prints the warnings for unresolved variable references in template files.
Used if mStrict is set true

Parameter
string $line
line pass from GetTemplates()
Returns void


Strict

public void Strict( )

  Strict template checking, if true sends warnings to STDOUT when
parsing a template with undefined variable referencesUsed for tracking down bugs-n-such. Use no_strict() to disable.

Returns void


NoStrict

public void NoStrict( )

  Silently discards (removes) undefined variable references
found in templates

Returns void


GetAssigned

public boolean GetAssigned( [ string $tpl_name ] )

  Return the value of an assigned variable.

Parameter
string $tpl_name = >>""<<
template name
Returns boolean


AssignInclude

public void AssignInclude( string $Macro, string $include )

  Handle any included file using include()
I'm sure there are some other better ways to do this

Parameter
string $Macro
current macro
string $include
the path to included file
Returns void


Private Method Details

SetRoot

private void SetRoot( string $root )

  All templates will be loaded from this "root" directory.
Can be changed in mid-process by re-calling with a newvalue.

Parameter
string $root
root directory
Returns void


IsSafe

private boolean IsSafe( string $fileName )

  A quick check of the template file before reading it.
This should check if the file is safe to read,it means the file really exists and the permissionallowed us to read it. [UNFINISHED]

Parameter
string $fileName
file name for checking
Returns boolean


GetTemplate

private string GetTemplate( string $template )

  Grabs a template from the root dir and
reads it into a (potentially REALLY) big string

Parameter
string $template
name of template's file
Returns string $contents

contents of the template


ParseTemplate

private string ParseTemplate( string $template, array $parseVars )

  This routine does the actual to VALUE conversion within the template.
I made a 'crucial' change here, i used str_replace instead of ereg_replace.That's why this class should go faster than the old FastTemplates.

Parameter
string $template
the template befor parsing
array $parseVars
array(var,value)
Returns string $template

the template after parsing

See Also Parse()

ParseDynamic

private void ParseDynamic( string $MacroName, string $Macro, [ string $alt ] )

  Parse a dynamic block

Parameter
string $MacroName
name of the new var for the replacement of dynamic block
string $Macro
name of the parent's tag
string $alt = >>""<<
set if alternation mode used
Returns void

See Also DefineDynamic()

Clear

private void Clear( [ string $returnVar ] )

  General clearance

Parameter
string $returnVar = >>""<<
macro, filetag or var
Returns void

See Also ClearParse(), ClearDefine()

ClearHref

private void ClearHref( string $href )

  Clears all href

Parameter
string $href
href
@class public
Returns void


Error

private void Error( string $errorMsg, [ integer $die ] )

  Prints any error message.

Parameter
string $errorMsg
Error messages
integer $die = >>0<<
whether exit or not after prints
Returns void


utime

private void utime( )

  Calculates current microtime
I throw this into all my classes for benchmarking purposesIt's not used by anything in this class and can be removedif you don't need it.

Returns void


Private Field Details

$mFileList

private array $mFileList

>>array()<<

Holds the array of filehandles mFileList[HANDLE] == "fileName"


$mDynamic

private array $mDynamic

>>array()<<

Holds the array of dynamic blocks,
and the fileHandles they live in.


$mParseVars

private array $mParseVars

>>array()<<

Holds the array of Variable handles.
mParseVars[HANDLE] == "value"


$mLoaded

private array $mLoaded

>>array()<<

We only want to load a template once - when it's used.
mLoaded[FILEHANDLE] == 1 if loaded undefined if not loaded yet.


$mHandle

private array $mHandle

>>array()<<

Holds the handle names assigned by a call to parse()


$mSeling

private array $mSeling

>>array()<<

Holds the handle names for selang-seling


$mRoot

private string $mRoot

>>""<<

Holds path-to-templates


$mWin32

private boolean $mWin32

>>false<<

Set to true if this is a WIN32 server


$mError

private string $mError

>>""<<

Holds the last error message


$mLast

private string $mLast

>>""<<

Holds the HANDLE to the last template parsed by parse()


$mStrict

private boolean $mStrict

>>true<<

Strict template checking.
Unresolved vars in templates will generate a warning when found.


$append

private boolean $append

>>true<<



Generated by. PHPDoc 1.0beta