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:
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
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:
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.
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:
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.
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" tagIn 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.
See the sample scripts for more information.
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