TPLManager: Template engine that uses regular expressions

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.
---------------------------------------------------------------