class.rFastTemplate.php CVS Log

Working file: class.rFastTemplate.php
head: 1.26
branch:
locks: strict
access list:
symbolic names:
	start: 1.1.1.1
	rlenter: 1.1.1
keyword substitution: kv
total revisions: 27;	selected revisions: 27
description:
----------------------------
revision 1.26
date: 2002/10/01 20:47:48;  author: roland;  state: Exp;  lines: +3 -3
Added /s qualify to PCRE regexps.  This makes multiline comments
following the {BEGIN,END}_DYNAMIC_TEMPLATE work as intended.
----------------------------
revision 1.25
date: 2002/09/24 21:54:42;  author: roland;  state: Exp;  lines: +16 -1
Added $t->append($x) function to be equivalent to
$t->assign($t->getkey($key).$x).  Actually its better than that since
it takes the same arguments as assign/setkey, i.e., it can process an
array argument.
----------------------------
revision 1.24
date: 2002/09/23 16:52:01;  author: roland;  state: Exp;  lines: +19 -5
Modified load() to not throw an error if the template file is empty.
The previous work around was to create a template with at least one
byte.
----------------------------
revision 1.23
date: 2002/02/15 20:51:21;  author: roland;  state: Exp;  lines: +24 -5
quiet() was ignoring argument.

Added missing_dir_okay() which allows you to include directories in
the template path array which do not exist.  The default is 'false'.
Think about organizing a web site into sections which correspond to
directories.  The template tree includes a generic menu plus specific
menus for each section.  The specific menus are arranged in a
directory tree parallel to the main web site.  If there is no specific
menu, the generic one is used.  Previously, you had to create the
directory tree even if you had no templates to go in there.
----------------------------
revision 1.22
date: 2001/10/18 21:36:53;  author: roland;  state: Exp;  lines: +15 -4
Added quiet() to allow you to pass through template variables
unchanged without generating an error.  I.e., normally, if something
like {FOO} appears in the text, it is either removed with no_strict()
or you get a warning message with strict().  This does neither, i.e.,
no warning and no removal.
----------------------------
revision 1.21
date: 2001/10/18 15:25:16;  author: roland;  state: Exp;  lines: +81 -25
Added clear_dynamic().  Changed clear() to behave like FastTemplate
version.  A few more cleanups to be quiet with E_ALL.
----------------------------
revision 1.20
date: 2001/10/11 20:17:16;  author: roland;  state: Exp;  lines: +76 -64
Clean up under error_reporting(E_ALL).
----------------------------
revision 1.19
date: 2001/10/03 21:24:01;  author: roland;  state: Exp;  lines: +9 -6
Fixed $t->parse(MAIN,array('table','main')) bug to be compatible with
FastTemplate.  This will change the behavior for people who were using
the array() form, but I can't imagine how it worked satisfactorily
before.
----------------------------
revision 1.18
date: 2001/09/29 02:12:45;  author: roland;  state: Exp;  lines: +114 -95
Added define_raw() for shoving text directly into a template
----------------------------
revision 1.17
date: 2001/08/08 01:50:35;  author: roland;  state: Exp;  lines: +5 -8
Fixed problem with clearing template results.
Fixed typo in fetch that prevented default from working.
----------------------------
revision 1.16
date: 2001/07/25 18:31:14;  author: roland;  state: Exp;  lines: +3 -3
clear() and parse_internal_1() both referenced an array element
[results] which should have been [result].  The meant neither were
correctly clearing the element.
----------------------------
revision 1.15
date: 2001/07/25 18:06:06;  author: roland;  state: Exp;  lines: +9 -5
Added "if($debug)" to all $this->logwrite(...) calls.
----------------------------
revision 1.14
date: 2001/06/28 01:42:54;  author: roland;  state: Exp;  lines: +2 -2
Typo/thinko due to failed testing!
----------------------------
revision 1.13
date: 2001/06/28 00:56:05;  author: roland;  state: Exp;  lines: +14 -8
Allow '.' as a valid character in a template name.
Allow class.FastTemplate.php3 compatible use of define_dynamic.
----------------------------
revision 1.12
date: 2001/06/27 16:51:04;  author: roland;  state: Exp;  lines: +23 -31
Fixed handling of no_strict() which was broken after then last set of changes.
----------------------------
revision 1.11
date: 2001/06/18 20:59:13;  author: roland;  state: Exp;  lines: +78 -35
o Added several logwrite sections to help track differences with
  class.FastTemplate.php3.
o Added class.FastTemplate.php3 compatible define_dynamic() to allow
  dynamic templates to be declared.
o Added second optional argument to define() to allow dynamic
  templates to be defined by file rather than parent.  If you have
  lots of nested templates, this might be easier.
o Added support for smarter autoloading so a declared dynamic template
  will try to declared location first. If there is no declared
  location, it will load all templates trying to find a match.
----------------------------
revision 1.10
date: 2001/06/18 19:08:48;  author: roland;  state: Exp;  lines: +49 -38
Fixed problem with double append in [result] element.
----------------------------
revision 1.9
date: 2001/06/18 16:46:49;  author: roland;  state: Exp;  lines: +9 -5
Fixed incorrect test for trailing whitespace after END block.
----------------------------
revision 1.8
date: 2001/06/18 03:51:21;  author: roland;  state: Exp;  lines: +67 -57
o Fixed problem with templates being parsed multiple times.
o Fixed problem with extra append of template contents if the first
  call to parse() is in append mode instead of overwrite mode.
----------------------------
revision 1.7
date: 2001/06/15 19:17:19;  author: roland;  state: Exp;  lines: +79 -65
o Skipping whitespace could back up over a linefeed inappropriately.
o If a dynamic template began at the start of a "part" it would be
  duplicated in the output.
----------------------------
revision 1.6
date: 2001/06/14 17:52:23;  author: roland;  state: Exp;  lines: +2 -2
Fixed typo/thinko in unsetkey; isempty -> empty.
----------------------------
revision 1.5
date: 2001/06/14 02:56:51;  author: roland;  state: Exp;  lines: +204 -74
o Merged Alister Bulman's  changes.
o Fixed problem with trailing comments in BEGIN/END blocks.
o Discard space on BEGIN/END lines if those lines contain ONLY
  whitespace.
----------------------------
revision 1.4
date: 2001/06/12 19:04:20;  author: roland;  state: Exp;  lines: +18 -21
Additional copyright cleanup.
----------------------------
revision 1.3
date: 2001/06/12 03:43:17;  author: roland;  state: Exp;  lines: +52 -17
Updated copyright notice, minor comment changes.
----------------------------
revision 1.2
date: 2001/06/07 15:28:46;  author: roland;  state: Exp;  lines: +222 -222
Whitespace cleanup
----------------------------
revision 1.1
date: 2001/06/07 15:10:58;  author: roland;  state: Exp;
branches:  1.1.1;
Initial revision
----------------------------
revision 1.1.1.1
date: 2001/06/07 15:10:58;  author: roland;  state: Exp;  lines: +0 -0
class.FastTemplate replacement
=============================================================================

class.rFastTemplate.php ChangeLog

2002-10-01  Roland Roberts  

	* class.rFastTemplate.php: Added /s qualify to PCRE regexps.  This
	  makes multiline comments following the
	  {BEGIN,END}_DYNAMIC_TEMPLATE work as intended.
	
2002-09-24  Roland Roberts  

	* class.rFastTemplate.php (append): New function, equivalent to
	  $t->assign($t->getkey($key).$x).  Actually its better than that
	  since it takes the same arguments as assign/setkey, i.e., it can
	  process an array argument.

2002-02-15  Roland Roberts  

	* class.rFastTemplate.php (quiet): was ignoring argument.

	* class.rFastTemplate.php (missing_dir_okay) allows you to include
	  directories in the template path array which do not exist.  The
	  default is 'false'.  Think about organizing a web site into
	  sections which correspond to directories.  The template tree
	  includes a generic menu plus specific menus for each section.
	  The specific menus are arranged in a directory tree parallel to
	  the main web site.  If there is no specific menu, the generic
	  one is used.  Previously, you had to create the directory tree
	  even if you had no templates to go in there.

2001-10-18  Roland Roberts  

	* class.rFastTemplate.php (clear): Made compatible with
	  FastTemplate.  It wasn't even working consistently.

	* class.rFastTemplate.php (clear_dynamic): New function,
	  compatible with FastTemplate.  This will clear a dynamic
	  template so that on the next parse() of an outer template,
	  the inner template will be complately blanked; i.e., *all*
	  of the text will be removed including surrounding constant
	  text.

	  Note that this behavior may be surprising to users of
	  FastTemplate since that package completely and permanently
	  removes the template text from the template; as if the
	  template were an empty string.  For a simple dynamic
	  template, the effect is the same, but for nested templates
	  where the inner template is used in a loop, the effect is
	  different.  The rFT behavior allows the contents to be
	  temporarily blanked until the next loop.  This allows you
	  to, for example, make a two-level list where some list
	  elements have not sub-lists but subsequent ones do.

	* class.rFastTemplate.php (quiet): Added quiet() to allow you
	  to pass through template variables unchanged without
	  generating an error.  I.e., normally, if something like
	  {FOO} appears in the text, it is either removed with
	  no_strict() or you get a warning message with strict().
	  This does neither, i.e., no warning and no removal.
	
2001-10-11  Roland Roberts  

	* class.rFastTemplate.php: Miscellaneous cleanup to run clean
	  with error_reporting(E_ALL).

2001-10-03  Roland Roberts  

	* class.rFastTemplate.php: Fixed
	  $t->parse(MAIN,array('table','main')) bug to be compatible
	  with FastTemplate.  This will change the behavior for people
	  who were using the array() form, but I can't imagine how it
	  worked satisfactorily before.
	
2001-09-29  Roland Roberts  
	
	* class.rFastTemplate.php: Added define_raw() for shoving text
	  directly into a template.

2001-08-08  Roland Roberts  	

	* class.rFastTemplate.php: Fixed problem with clearing
	  template results.  Fixed typo in fetch that prevented
	  default from working.

2001-07-25  Roland Roberts  

	* class.rFastTemplate.php: Added "if($debug)" to all
	  $this->logwrite(...) calls.

	* class.rFastTemplate.php: clear() and parse_internal_1() both
	  referenced an array element [results] which should have been
	  [result].  The meant neither were correctly clearing the
	  element.
	
2001-06-28  Roland Roberts  

	* class.rFastTemplate.php: Typo/thinko due to failed testing!

2001-06-27  Roland Roberts  
	
	* class.rFastTemplate.php: Fixed handling of no_strict() which
	  was broken after then last set of changes.

2001-06-18  Roland Roberts  

	* class.rFastTemplate.php: Fixed problem with templates being
	  parsed multiple times.  Fixed problem with extra append of
	  template contents if the first call to parse() is in append
	  mode instead of overwrite mode.
	
	* class.rFastTemplate.php: Fixed incorrect test for trailing
	  whitespace after END block.

	* class.rFastTemplate.php: Fixed problem with double append in
	  [result] element.

	* class.rFastTemplate.php: Added several logwrite sections to
	  help track differences with class.FastTemplate.php3.  Added
	  class.FastTemplate.php3 compatible define_dynamic() to allow
	  dynamic templates to be declared.  Added second optional
	  argument to define() to allow dynamic templates to be
	  defined by file rather than parent.  If you have lots of
	  nested templates, this might be easier.  Added support for
	  smarter autoloading so a declared dynamic template will try
	  to declared location first. If there is no declared
	  location, it will load all templates trying to find a match.
	
2001-06-15  Roland Roberts  

	* class.rFastTemplate.php: Skipping whitespace could back up
	  over a linefeed inappropriately.  If a dynamic template
	  began at the start of a "part" it would be duplicated in the
	  output.
	
2001-06-14  Roland Roberts  
	
	* class.rFastTemplate.php: Fixed typo/thinko in unsetkey;
	  isempty changed to empty.

2001-06-12  Roland Roberts  

	
	* class.rFastTemplate.php: Merged in changes from Alister
	  Bulman .  These include: (1) Changed
	  quotes from double to single where possible to avoid
	  unnecessary variable interpolation, (2) Allow multiple
	  template roots, (3) Remember last handle parsed for use with
	  FastPrint(), and (4) changed `if ($die == 1)' to simple `if
	  ($die)'.
	
	* class.rFastTemplate.php: Calls to $this->error() now use
	  "true" as the second argument rather than integer values.

	* class.rFastTemplate.php: Formatting cleanup.
	
2001-06-13  Roland Roberts  

	* class.rFastTemplate.php: Fixed problem with trailing
	  comments in BEGIN/END blocks not being ignored.

	* class.rFastTemplate.php: If the BEGIN/END block lives on a
	  line by itself, remove the complete line.  More
	  specifically, if the only thing before the opening HTML
	  comment marker and after the closing HTML comment marker is
	  whitespace, we delete the whitespace as well.  This prevents
	  unwanted whitespace from creaping into the file.

class.rFastTemplate.php Documentation

class.rFastTemplate.php is a PHP class to help build web pages based on templates, i.e., fill-in-the-blank HTML. class.rFastTemplate.php allows you to build your pages as full-blown HTML with simple "blanks" to be filled in, with repeating blocks, with block which can be deleted, or as fragments where you can mix-and-match.

Synopsis

// Creating a template object.
require ('class.rFastTemplate.php');
$template = array ('.', 'template/fancy', 'template/simple');
$t = new rFastTemplate ($template);
$t->set_root ($template);

// Declaring templates.
$t->define (array ('main' => 'index.thtml',
                   'motd' => 'motd.thtml'));
$t->define (array ('list' => 'index.thtml'), true);
$t->define_dynamic ('table', 'main');
$t->define_nofile (array ('main' => $main_string), true);
$t->define_raw (array ('main' => $main_string), true);

// Assigning/clearing template variables.
$t->assign (TITLE, 'Hello, World!');
$t->setkey (TITLE, 'Hello, World!');
$value = $t->get_assigned (TITLE);
$value = $t->getkey (TITLE);
$t->unsetkey (TABLE);
$t->clear_href (TABLE);

// Substituting variables into a template.
$t->parse (MOTD, 'motd');
$t->subst (MOTD, 'motd');
$t->parse (array (MAIN => 'main', MOTD => 'motd'));

// Obtaining the output from completed template.
$t->xprint (MAIN);
$t->FastPrint ();
$string = $t->fetch ();

// Clearing/resetting a template.
$t->clear ('main');
$t->clear (array ('main', 'motd'));
$t->unload ('main');
$t->clear_dynamic ($template);

// Template debugging options.
$t->debug ('parse');
$t->debug ('parse', false);
$t->debugall ();
$t->debugall (false);
$t->debugfile ($path);
$t->logwrite ($message);

// Template parsing options.
$t->no_strict ()
$t->strict ();
$t->quiet ();
$t->dynamic (false);
$t->missing_dir_okay (true);

// Other internal functions.
$t->FindTemplate ($file);
$t->load ($file);
$t->parse_internal ($tag);
$t->parse_internal_1 ($tag, $rest = '');

Functions/Methods

rFastTemplate

Creates a new rFastTemplate object.

class rFastTemplate ([mixed TEMPLATE_PATH]);

If $template_path is omitted, it must be defined via set_root before calling define. If $template_path is a scalar, it is taken to be the path where the define'd templates should be found. If it an an array, it is taken as a list of directories which will be searched to located define'd templates.

set_root

Set the root directory which will be searched for any define'd templates.

void set_root (mixed TEMPLATE);

TEMPLATE may be a scalar in which case it is the name of the directory where the templates will be stored. If TEMPLATE is an array, the elements are the names of directories which will be searched in sequence to find the template files. See also missing_dir_okay.

About Multi template-roots

The most obvious use for multi template-roots are for website theming. The array of template roots are searched in order of being listed for a matching filename (that filename may also include a relative path). This leads to the advantage that entire groups of templates do not have to be duplicated, only templates that have changed. Others which would be the same will be 'fallen-back' to.

Example of multi template-roots

In the examples below, set_root is given an array argument which holds a list of directories which will be searched when trying to find the templates declared via define. In the first example, template/fancy/ need only contain a index.thtml if, say, the other templates were identical beween the two. In the second example, template/simple is assumed to contain a generic set of template while $HolidayThemeDir holds holiday specific templates.

// PHP 4; PHP 3 uses require().
require_once ('class.rFastTemplate.php');
$t = new rFastTemplate ($template);

// Example 1: look in 'template/fancy' then fall back to 'template'.
$t->set_root (array ('template/fancy/',
                     'template/'));

// Example 2: directory names may be passed via variables to set a
// holiday theme, e.g., 'template/Xmas/', 'template/Valentines/' etc.
// Fallback is as before.  If any of the directories do not exist,
// they will be skipped.
$t->set_root (array ($HolidayThemeDir,    
                     'template/simple/'));

// Declare some templates; paths are relative to the declared root(s).
$t->define (array ('main'    => 'index.thtml',
                   'motd'    => 'motd.thtml',
                   'weather' => 'weather/weatherforcast.thtml'));


// 'list' is a dynamic template contained in the file 'index.thtml'
$t->define (array ('list' => 'index.thtml'), true);  

// 'table' is also a dynamic template.  'main' must be declared via
// define() because loading 'table' will check to see what
// file 'main' was declared to use.
$t->define_dynamic ('table', 'main');

define

Define an association between a template name and a template file.

void define (array TEMPLATE [, boolean DYNAMIC = false]);

$template is an array of one or more elements whose keys are the names of the templates and whose values are the associated files. $dynamic is an informational declaration that tells the class that the templates being defined are not independent but are inferior templates embedded within a parent template.

It is not necessary to declare any dynamic/inferior templates; they will be automatically found when the parent template is loaded. However, if you wish to predeclare many templates only some of which will be actually be used, declaring the dynamic templates can greatly reduce the amount of file I/O that takes place. The reason for this is simple: if you try to parse an undeclared dynamic template, class.rFastTemplate.php will have to load each of the declared templates until it finds the one being parsed. If you have tens or hundreds of predeclared templates, this can generate a lot of file I/O as well as waste CPU and memory loading files which are ultimately discarded. On the other hand, if you have only a couple of templates, all of which are actually used, there is no benefit to explicitly declaring dynamic templates. There is almost no cost to actually do so however (see code).

define_dynamic

Declare a dynamic template and its associated parent template.

void define_dynamic (mixed TEMPLATE [, string PARENT]);

This function is for compatibility with class.FastTemplate.php3 where declaring dynamic templates is required. With class.rFastTemplate.php, this declaration is not required, but can optimize the template loading process; see define for more details.

This function call can take two forms:

• declare one dynamic template and its the parent
• declare multiple dynamic templates and their parents

Here is an example of each:

// Single dynamic template and its parent.
define_dynamic ('dyn1', 'parent1');

// Multiple dynamic templates and their parents.
define_dynamic (array('dyn1' => 'parent1',
                      'dyn2' => 'parent2'));

define_nofile

See define_raw.

define_raw

This provides a way to define a template without having to read the template contents from a file.

$t->define_raw (array TEMPLATE [, boolean DYNAMIC]);

The first argument is an array of template definitions just like define except instead of having a template name point to a file it points to a string:

$t->define_raw (array ('main' => $main, 'trailer' => $trailer));

The dynamic flag defaults to false and the state is automatically set to 'loaded'. Use this if you store your templates elsewhere, e.g., a database. Another use is to create a template from a partially parsed template which still has template forms (bracket-enclosed variables) and then reparse using the newly created template, that is,

$t->define (array ('main' => 'main.thtml'));

// Do all your normal processing and assigning.
// ....

$t->parse ('MAIN', 'main');
$t->define_raw (array ('content' => $t->fetch ('MAIN')));

// Now process the "raw" template.
// ....

$t->parse ('CONTENT', 'content');
$t->FastPrint ();

assign

assign sets the value of a template variable for use during the parse/substitution phase. Internally, the function is setkey.

$somevariable = "some value";
$t->assign (MYVAR, "some value");
$t->setkey (MYVAR, "some value");
$t->assign (MYVAR, $somevariable);
$t->setkey (MYVAR, $somevariable);
$t->setkey (array (MYVAR => $somevariable));

$t->assign (array (MYVAR1 => "one",
                   MYVAR2 => "two"));

All of the calls above, except the last, are equivalent. The last call illustrates how one can assign multiple variable with a single call.

setkey

See assign. In hindsight, perhaps this should have been called setval.

get_assigned

This allows you to retrive the value of a previously assigned variable. It is completely equivalent to getkey. You should note that get_assigned will only retrive the value associated with a variable set via setkey or assign. This is the only place where the results of parse and assign are treated differently.

$somevariable = $t->get_assigned (MYVAR);
$somevariable = $t->getkey (MYVAR);

getkey

See get_assigned.

clear_href

This provides a mechanism for clearing the value of a key prior to parsing a template. The primary utility of this is in the case where a variable might be used in multiple contexts or in a dynamic template where the current iteration should be empty. If no_strict has been called, this is functionally equivalent to setting the variable to be an empty string.

$t->clear_href (MYVAR);
$t->unsetkey (MYVAR);

For the no_strict case, if the variable is not set or unset, during the substitution phase, the variable will be treated as if it were assigned to an empty string.

unsetkey

See clear_href.

parse

Not yet written, try again later.

subst

See parse.

FastPrint

See xprint.

xprint

When I first wrote rFastTemplate, I found having a member function named the same as a PHP function was not a good idea. It can be made to work, but internally you keep having to say something like $this->print instead of just print. Being confused at the time, I named the function xprint to avoid the problem.

xprint will print out the contents of the specified handle. Note that variable contents will not be printed, only handles. If no handle is specified, whatever handle was last used wil be parsed will be used.

$t->define (array ('main' => 'main.thtml'));
// ....
$t->parse ('CONTENT', 'main');
// This will print the same thing twice; both xprint statements
// are equivalent.
$t->xprint ();
$t->xprint ('ROW');

fetch

fetch provides a method to retrive the current contents of a handle without having to reach behind the class interface.

$t->fetch ([string HANDLE]);

It is equivalent to $t->HANDLE[$handle] with the exception that if no handle name is specified, the last one passed to parse will be used.

$t->define (array ('main' => 'main.thtml'));

// ....
$t->parse ('CONTENT', 'main');

// This will print the same thing twice; both xprint statements
// are equivalent.
$mystring = $t->fetch ();

// You can now manipulate the "finished" template before printing.
// ....
print $mystring;

clear

This provides a method to "null out" the results of a template. This is most useful when one sub-element of a dynamic template needs to be blank.

$t->define (array ('main' => 'main.thtml'));
$t->define_dynamic (array ('row' => 'main',
                           'col' => 'main'));
// ....
$row = 'row';
for ($i = 0; $i < $nrows; $i++) {
    $col = 'col';
    for ($j = 0; $j <= $ncols; $j++) {
        <determine value of element (i,j)>
        if (<element i,j should be omitted>) {
            $t->clear ('col');
        }
        $t->parse (COL, $col);
        $col = '.col';
    }
    $t->parse (ROW, $row);
    $row = '.row';
}

What is perhaps not so obvious from the above code is why you would want to use clear instead of clear_href. The latter is designed to simply clear the setting of a key from an assign call. The former will clear out the entire block inside a dynamic block including any fixed HTML that is part of that dynamic block.

unload

Not yet written, try again later.

clear_dynamic

Clears a dynamic block from a template. The intent is to remove an inferior template from a parent as it the text were never present in the first place.

$t->clear_dynamic ([string TAG]);

If TAG is NULL, clear_dyanmic will clear all result elements.

clear_dyanmic will work even if the template has already been parsed by going straight to the internal results element of the parsed template and clearing it. It will also work on templates which have not yet been loaded by forcing a load via parse_internal.

debug

Turn on diagnostic printing for a particular function. This does not enable debugging via the PHP debugging mechanism; this is purely a "print some information" function.

$t->debug (string WHAT [, boolean ON]);

The first parameter is the name of the function for which diagnostic messages should be enabled, the second is a boolean flag to indicate whether printing is being turned on (true) or off (false). Whether or not anything happens is dependent on whether or not the function supports diagnostic printing.

debugall

Sets a global flag to turn on printing in all class function which support diagnostic messages.

$t->debug ([boolean ON]);

The default is to turn on debugging. If the ON parameter is set to false, debugging is turned off.

debugfile

Specify the name of the file to which diagnostic messages should be printed.

$t->debugfile (string DEBUGFILE);

There is no default for DEBUGFILE but it is intialized in the class to /tmp/class.rFastTemplate.php.dbg. When debugging is turned on, class members which support diagnostic printing will print to this file. But be warned: don't try this on a live site! First you will significantly slow things down. Second, the output from different hits on the same page will likely be intermixed making it impossible to decypher.

logwrite

logwrite is an internal function used for all of the diagnostic print statements in rFastTemplate member functions. It is not intended to be called directly.

$t->logwrite (string MESSAGE);

logwrite opens the diagnostic file (if not already open) and write the specified text with a time stamp prepended.

strict

Sets template parsing to "strict" mode; no template variables (matching regular expressions) may be present in the final output.

$t->strict ([boolean ON]);

This is the opposite of no_strict and is the default behavior. The following two calls are equivalent:

$t->no_strict ();
$t->strict (false);

no_strict

Set template parsing to "no strict" mode. At the end of the substitution phase, any remaining template variable (matching regular expressions) will be treated as if that template variable had been assigned a value of an empty string.

$t->no_strict ();

If no_strict is not used, class.rFastTemplate.php will both complain (display an error message on the page) and leave the template variables as-is in the output. It may be desirable to separate this behavior in the future, i.e., to make it possible to leave the variables in the template but not issue an error message. Among other things, it is difficult to write templates which contain examples of templates.

quiet

One of the problems with the strict/no_strict division is that switching modes does more than one thing. When in strict mode, the template form is left intact but an error message is produced. When in no-strict mode, the error message is suppressed and the template form is removed. But what if you have a form where you expect to have things which look like template forms and you want them to be passed through?

Quiet mode allows you to do just that. It suppresses the error messages but still allows the template forms to pass through to the final output. Before I added quiet mode, I couldn't insert an actual template form (e.g., {F_SOME_FIELD}) into the HTML text of this page!

dynamic

Turn on dynamic template parsing.

$t->dynamic ([boolean ON]);

By default, dynamic template parsing is on.

missing_dir_okay

Suppress errors if the template path array has non-existent members.

$t->missing_dir_okay ([boolean ON]);

The default value for ON is true if the function is called; the default behavior for a newly created template is equivalent to missing_dir_okay(false).

I originally wrote this function to get around the problem of some dynamically generated template paths. In particular, I had some code which would prepend a template path parallel to the HTML path for every page. This let me do things like have a generic navigation menu which could be superceded by a more specific one. If the more specific one did not exist the more general one was used. However, if the template path did not exist, PHP would throw an error that prevented me from doing any processing.

FindTemplate

Not yet written, try again later.

load

Not yet written, try again later.

parse_internal

Not yet written, try again later.

parse_internal_1

Not yet written, try again later.

Known Bugs

If missing_dir_okay has called, set_root can actually produce an empty ROOT array which means no templates will exist. This can only happen if, in fact, there are no valid template locations specified in the call to set_root. Still, an error should be produced at the time set_root is called to better localize the error.

Credits and References

Jason Moore wrote the original Perl version of FastTemplate for use with mod_perl. It was last known to be available at www.sober.com.

CDI from thewebmasters.net wrote class.FastTemplate.php as PHP "port" of the original Perl version.

Alister Bulman of www.minotaur.nu contributed some cleanups and allowed the template root to be a search list (array of paths).