PHP Classes
elePHPant
Icontem

TPLManager: Template engine that uses regular expressions

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Info   View files View files (5)   DownloadInstall with Composer Download .zip   Reputation   Support forum (1)   Blog    
Last Updated Ratings Unique User Downloads Download Rankings  
2008-02-29 (7 years ago) RSS 2.0 feedNot enough user ratingsTotal: 240 All time: 7,230 This week: 1,142Up
Version License PHP version Categories  
tplmanager 1.0GNU General Publi...5.0PHP 5, Templates
Description Author  

This class implements a template engine that uses regular expressions to search for placeholder tags.

It opens a template file and uses regular expressions to search for place holder tags that are enclosed in { } angle bracket characters.

The class can replace the tags by the respective replacement variable values.

Picture of Gregory Patmore
Name: Gregory Patmore <contact>
Classes: 1 package by
Country: United States United States
Age: ???
All time rank: 3633432 in United States United States
Week rank: 1533 Up167 in United States United States Up

Details provided by the author  
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.
---------------------------------------------------------------
  Files folder image Files  
File Role Description
Accessible without login Plain text file README.txt Doc. About the class and a tutorial
Accessible without login Plain text file example1.php Example example
Accessible without login Plain text file example2.php Example another example
Accessible without login Plain text file thanks_email.tpl Data sample template file
Plain text file tplmanager.class.php Class the class file

 Version Control Unique User Downloads Download Rankings  
 0%Total:240All time:7,230
 This week:0This week:1,142Up
 User Comments (1)