Additional Documentation on the TPLManager Class
AUTHOR : Gregory Patmore
CONTACT : mail a.t gregorypatmore d.o.t c.o.m
DESCRIPTION : Lightweight Template Parser
---------------------------------------------------------------
NOTES FROM THE AUTHOR:
---------------------------------------------------------------
The TPLManager class was written for those who want to leverage
the use of templates to manage content but dont want to bog down
their application with a whole templating system designed for
advanced template processing like Smarty or one of the pear
packages. I love using templates to separate the data layers,
but I dont want to load a whole new application into my project
that I wont use half of. It just seems silly.
So TPLManager is a bare bones implementation of the essence
of what a template processor does... find spots in the template
file and replace them with the crap you give it. Nothing more..
and nothing less. I have written some extentions to this class
to provide some more advaced processing features like recursive
processing(processing a template reference inside a template),
so if you want a copy of that, and cant find it where you got
this file from, contact me at mail@gregorypatmore.com.
CONCEPT:
---------------------------------------------------------------
To provide a no-frills approach to using templates to separate
Presentation logic from Application logic.
The premise that the TPLManager works on is simple.
1. You give it a path to a template file.
2. It finds all the hotspots embedded in the template file.
A Hotspot is a piece of text trapped in braces('{}').
an example of a hotspot would be {MYHOTSPOTNAME}.
See the examples below for more info.
3. You give it values to replace the hotspots with.
4. It replaces them.
5. You get the processed text back and do something useful with it(hopefully).
---------------------------------------------------------------
FEATURES:
---------------------------------------------------------------
Aside from bare bones processing I added a few extra features
that I found frequently useful.
Results Compacting:
By default the TPLManager will leave the original text how it was
originally formatted, but you can enable a feature to compact the
final processed text to remove extra spaces and returns out of the
text before it gets output. You can enable compacting by calling
TPLManager::enableCompacting() before processing your template.
use TPLManager::disableCompacting() to turn it back off.
Constant Checking:
By default this feature is disabled, but frequently I have found
it convenient to embed the name of a pre-defined constant into a
template. Rather then supplying a value each time I want to use
it, it's convenient to check the defined constants directly. It
should be noted that enabling this feature can expose a
vulnerability if not used properly. See the class source
documentation for more on that, but for now, just know that you
can enable this by calling TPLManager::enableConstChecking() and
turn it back off with TPLManager::disableConstChecking()
---------------------------------------------------------------
USAGE
---------------------------------------------------------------
The main thinga I wanted out of this class were:
1. Ease of use.
2. Minimum amount of code to process a template if you had
everything you needed for processing ahead of time.
3. The ability to let the hotspots guide content generation.
The reason I like this class is because its simplicity makes it
very flexible. There are probably a dozen or more ways to use
this class but I mainly use it one of 2 ways.
1. Processing a template with hotspots I know about ahead of time.
A. You create a template.
B. You format the replacement value array.
C. Create a new TPLManager and pass it the value array.
D. Retrieve the processed text.
2. Processing a template with unknown hotspots.
A. Create a new TPLManager.
B. Retrieve the list of hotspots found in the file
C. Loop through them and generate an array of replacements.
D. Load in the array of replacements and process the template.
E. Retrieve the processed text.
---------------------------------------------------------------
EXAMPLES
---------------------------------------------------------------
LOAD-N-LAUNCH METHOD:
Processing a template with hotspots I know about: ('load-n-launch').
Here we have a template with hotspots the application knows about
before hand.
For our example let's consider processing a simple template to use
for sending someone an email message. The template is a file called
thanks_email.tpl.
The contents of the template file are:
_______________________________________________________________
Hi {NAME},
Thanks for checking out my site! If you have any problems
Please contact me at {SUPPORTEMAIL}.
We look forward to seeing you again, {NAME}. Stop by
anytime.
Best Regards,
{MY_NAME}
_______________________________________________________________
Here is the php script to process it.
_______________________________________________________________
<?php
try{
/* Include the file. */
include('tplmanager.class.php');
/* Create the replacements array */
$repls = array(
'NAME' => 'John Q. Public',
'SUPPORTEMAIL' => 'mail@gregorypatmore.com',
'MY_NAME' => 'Gregory Patmore'
);
/* Create a TPLManager and send it the values */
$t = new TPLManager('thanks_email.tpl', $repls);
/* Retrieve the processed text */
$procTxt = $t->getParsed();
/* (Do something useful with it here) */
}catch($e){
/* Do something with an error here */
}
?>
_______________________________________________________________
CREATE-N-LOOP METHOD
I originally wrote it to only work the first way. But then it
started to get tedious to write code to create EVERY single tpl.
Most of the time I was rewriting the same code over and over
to replace common values. So I added some functionality to
help me automate common replacements. This class won't fully
automate the replacements, but it's a reverse approach from the
last method.
We will use the template from the last example for this method.
Here is the php script to process it.
_______________________________________________________________
<?php
function getName(){ return 'John Q. Public'; }
function getSupportEmail(){ return 'mail@gregorypatmore.com'; }
function getMyName(){ return 'Gregory Patmore'; }
try{
/* Include the file. */
include('tplmanager.class.php');
/* Create a new instance */
$t = new TPLManager('thanks_email.tpl');
/* Retrieve the hotspot list */
$spots = $t->getHotspotList();
if(is_array($spots)){
/* Loop through and assign a value */
foreach($spots as $s){
switch($s){
case 'NAME' : $t->setVal('NAME', getName());
break;
case 'SUPPORTEMAIL' : $t->setVal('SUPPORTEMAIL', getSupportEmail());
break;
case 'MY_NAME' : $t->setVal('SUPPORTEMAIL', getMyName());
break;
}
}
/* Retrieve the processed text */
$procTxt = $t->getParsed();
/* (Do something useful with it here) */
}else trigger_error('Template processing failed to find any hotspots to replace', E_USER_WARNING);
}catch($e){
/* Do something with an error here */
}
?>
_______________________________________________________________
Heres a variation on the CREATE-N-LOOP that I use alot.
_______________________________________________________________
<?php
function getTPLV_NAME(){ return 'John Q. Public'; }
function getTPLV_SUPPORTEMAIL(){ return 'mail@gregorypatmore.com'; }
function getTPLV_MY_NAME(){ return 'Gregory Patmore'; }
try{
/* Include the file. */
include('tplmanager.class.php');
/* Create a new instance */
$t = new TPLManager('thanks_email.tpl');
/* Retrieve the hotspot list */
$spots = $t->getHotspotList();
if(is_array($spots)){
/* Loop through and assign a value */
foreach($spots as $s){
$func = 'getTPLV_' . strtoupper($s);
if(function_exists($func))
$t->setVal($s, $func());
}
/* Retrieve the processed text */
$procTxt = $t->getParsed();
/* (Do something useful with it here) */
}else trigger_error('Template processing failed to find any hotspots to replace', E_USER_WARNING);
}catch($e){
/* Do something with an error here */
}
?>
_______________________________________________________________
It's also worth noting again that you can call
TPLManager::enableConstChecking() if you want to consider
replacements coming from the currently defined constants. If your
the only one developing on the application you can utilize this to
set basic template values without the defining the loops or
functions as laid out above.
--------------------------------------------------------------- |
Stumble It!
Bookmark in del.icio.us
Download
