README file for TagTemplate

TagTemplate v2.0

There are many PHP template libraries available in the Open Source domain, but when I searched I was unable to find solutions to what I thought would be two very simple and common problems:

Retrieve the contents of a particular HTML tag from another HTML file (say, everything between <BODY> and </BODY>)
Retrieve everything from an HTML file except for the stuff in some arbitrary tag.

So I wrote my own.

TagTemplate is a class that performs both of the above tasks, and a little more. Another use would be to scan through a given file, and every time a particular tag is encountered, perform some particular action. It's a tiny bit similar to the XML parsing functions in PHP

What is it for?

Technically speaking, TagTemplate is used to parse a file (typically an HTML file) looking for a particular tag. It is configured (by you, the programmer) to do something with the contents of that tag, and do something else with the rest of the file. The tag can be a regular HTML tag, like <BODY>, or a made-up one, such as <MY_TAG>. The things you might want to do with either the tag or the rest of the file could be:

echo it to the screen (the default)
save it for later
discard it (and keep the other part of the file)
some custom action (specified by you)

For example, you might want to extract the contents of the <BODY> tag of some file and use it in another file. In other words, you might want to "include" one HTML file in another, but without the <HEAD> and everything else that's not in the <BODY>. Or you could surround an arbitrary piece of HTML code with some invented tag (such as <INCLUDED_BIT>This is to be included in other files</INCLUDED_BIT>) and extract that HTML code snippet for insertion into other files. In this case, you would be choosing either option 1 or 2 (above) for the stuff inside the chosen tag, and option 3 for the rest.

But the best example of the use of TagTemplate is to create a template for your website - an HTML file that represents the stuff you want to have in every page in your site (such as the logo, the navigation buttons, the copyright message at the bottom, etc), and put some invented tag in that template that represents where all the HTML that varies from page to page should go. You might call this invented tag something like <MY_BODY>This text inside is ignored</MY_BODY> (you don't actually have to have anything inside the tag). In this case you would choose option 4 (above) for the stuff inside the tag (you would echo out the stuff specific to this particular page) and probably option 1 for the rest of the file.

How does it work?

In the most simple case, you instantiate the TagTemplate class, tell it the name of the file you want to parse, and then ask it to parse the file. The input does not have to come from a file - it can also come from a string or an array of strings. If you don't specify anything further, the entire contents of your file would simply be echo'd to the screen. Typically you would want more sophisticated processing than that, so you would also need to specify either one or two handling functions, and a particular tag to look for.

For each line of the input (file/string/array) that TagTemplate reads, it calls one of two handling functions. It calls the "in" function if it is currently reading and processing data from "inside" an instance of the particular tag that you are parsing for (in other words, it is currently processing text that is between the <TAG> and the </TAG>). It calls the "out" function if you are not inside an instance of the tag. It is your job to correctly specify which functions get called. The default is to call the function that echo's the text to the screen (for both "in" and "out" conditions).

Three handling functions have been created for you, for the three most basic of tasks:

Echo the data (the default)
Ignore the data
Save the data to a global variable called $tt_output, for later use (a bit ugly, I know, but I was lazy)

If you want more sophisticated behaviour, you simply have to write your own handling function and then specify it to TagTemplate before the parsing takes place. Handling functions always look the same:

void handling_func($s, $count)

$s is the text that is being processed (either a line from the input, or a portion of a line from the input). $count is the number of instances of the tag that have been processed so far. When you are "before" the first instance of the special tag you're looking for, $count is 0. When you are "inside" the first instance of the tag, $count is 1. When you are just "after" the first instance of the tag, and before the second instance, $count is 1.

Worked example

	include "TagTemplate.inc.php";
	
	function my_inside_func($s, $count)
	{
		// do something
	}
	
	$my_tt = new TagTemplate;		// instantiate the class
	$my_tt->tt_set_input_file("myfile.htm");	// get input from the specified file
	$my_tt->tt_set_out_func("tt_ignore");	// use one of the provided handling funcs
	$my_tt->tt_set_in_func("my_inside_func");	// use a custom func (above)
	$my_tt->tt_parse("body");	// DO IT!  We are interested in the "body" tag

In this example, my_inside_func() will get called once for each of the lines encountered inside the <BODY> tag, and the predefined function tt_ignore() will get called for each of the rest of the lines in the file.

Notes

Tag attributes (such as <BODY BGCOLOR="RED"> are handled properly, but ignored. The end tag is assumed to have no attributes
There can be multiple instances of the tag in the file. The $count parameter to the handling function will reflect this.
XHTML-style closing tags (<IMG SRC="blank.gif" />) are not handled.
You can re-parse the same input looking for a different tag, or look for the same tag but with different handling functions.
It is possible to specify class/object methods as the handling functions. Instead of a string that represents the function name, use an array, where the first element is the object (typically a reference to the object), and the second element is a string that represents the name of the method to use.
The original tag_template() function from version 1.x has been retained for backward compatibility, and should still work, but you should change all your code to use the new interface.

See the sample scripts for more information.

Version History

Version 2.00	December 20th, 2003	Total rewrite. TagTemplate is now a class, not a function. Much more flexible.
Version 1.01	April 25th, 2002	Fixed a small bug that relates to the TMPLT_BETWEEN option. HTML code immediately before the closing tag, on the same line as that closing tag, was being ignored. Thanks to M. Jean-Eudes Onfray for spotting (and fixing) this problem.
Version 1.00	August 16, 2001	Original Version. Non-class-based

TagTemplate is Thankyouware - if you use it in a project, please email me at mark@virtualcreations.com.au and let me know. I'll put a link to your site on my TagTemplate page.

Mark Virtue
Sydney, Australia.
mark@virtualcreations.com.au