Template Interface Engine: Template engine based on regular expression.

Template Interface Engine V1.0+
===============================
This template engine joins back-end code (as business logic layer) and HTML code (known as presentation layer)
which are written in separate files.

This class implements a template engine that uses regular expressions to locate placeholder marks.

It supports template loops and uses event driven callback functions to set variables inside the loop sections.
Outside loop sections, the variable values can set directly.

The tags used by this engine are enclosed by comment HTML tags, so the templates layout can be edited later by
any WYSIWYG HTML editor.

Supported tags are: LOOP, IF, ELSEIF, ELSE and INCLUDE.

The engine is equipped by configuration file for customization.

It also may handles multiple files (such as header, body and footer) and supports '_PIPE' output instead of
stdout or as file.


History Version
===============
Version 1.0.1
- PHP4 Compatibility class added.

Version 1.0
- Configuration file added for own customization
- INCLUDE tag feature added
- Fixed "logic expression" evaluation
- Enhanced "logic expression" evaluation:
  *) Now in "logic expression" can be the loop name as variable instead of another one which
     will be evaluated as the count of the table data loop.
  *) While by default it is impossible to use all internal PHP function, now you can use it by
     define it explicitly through configuration file.
- "RegisterFunction" function added, which is used to register custom function used by the class.

Version 0.8.11
- Fixed error in function to evaluate from the given expression.

Version 0.8.1
- PHP4 Compatibility class added.

Version 0.8
- Major changed enhancement added.

Version 0.6
- Initial release.


Requirements
============
The class was developed using PHP V5.1.0-dev but now we added for PHP4 compatibility ;)
Until reported from the supporter users, this is the version compatible (thanks for users):
+ PHP4 Version >= 4.1.30
+ PHP5 Version >= 5.1.0-dev

Now this template engine supports:
- INCLUDE tags
- LOOP block
- IF-ELSEIF-ELSE block
- Configuration file for customization
- Handle multi template files for header, body and footer separately
- The output could send result to stdout, file or as string (by set as '_PIPE')
- The blocks support to be recursively applied
- and ofcourse, this is PHP5 ;)
- but for PHP4 users, we added for PHP4 compatibility.

This is the release with some function we didn't finish to write it yet, as
function to parse error the tag is wrote, or internal user function name which can't be used.
If you interest to write it, let us know it... :)

Since now we release for PHP4, please report any bugs if raised because
we do not test it for some versions in PHP4 and prior.


How To Update
=============
If you are users from our previous release, this is simple to take.
Just replace the previous release class with this updated class, and there is no changed needed
in both template file part and the PHP code since we've worked it to compatible to the old users.


How To Use
==========
[*] First Step
    ==========
First, you need to define the class with the filename template as parameter, as example:
	$tmpl = new CInterface("template_file.extension");

[*] Variable Definition Section
    ===========================
Variables inside the template are defined by "{$" and "$}" tag, as example:
	{$varname$}
then if you need to set it by:
	$tmpl->varname = some_value;
or get the value by:
	$myvar = $tmpl->varname;

[*] INCLUDE Section
    ===============
First, before you use this tag feature, you may need to know about the "SetHeader" and "SetFooter"
function feature... However, for extended custom need reason, this tag be there... :)
To use the 'include' tag, write as example:

	<!--include:[other_templatefile.extension]-->

with "other_templatefile.extension" pointed the other template file which may consists full path, relative
from the template file, and may consists variable tags too. The string is as is, without quoted.
The tag can be used many more and can be placed anywhere in the template file.

[*] LOOP Section
    ============
Loop segment is defined by "<!--{###[loop_name]-->" and closed by "<!--[loop_name]###}-->" tag, as example:
	<!--{###loopname-->
		<html>some loop block</html>
	<!--loopname###}-->

As our knowledge, loop block will be used as table appearance, so
if you use loop block you have to define the table data first, then
to show it at your html page you need to define in your template file as example:
	<!--{###loopname-->
		this is colomn 0: {$loopname0$}<br />{$varinsideloop$}<br />
		this is colomn 1: {$loopname1$}<br />
		this is colomn 2: {$loopname2$}<br />
		this is colomn 3: {$loopname3$}<br />
	<!--loopname###}-->
then in your code you define the variable:
	$tmpl->loopname = array(
			array("row0_kol0", "row0_kol1", "row0_kol2", "row0_kol3"),
			array("row1_kol0", "row1_kol1", "row1_kol2", "row1_kol3"),
			array("row2_kol0", "row2_kol1", "row2_kol2", "row2_kol3"),
			array("row3_kol0", "row3_kol1", "row3_kol2", "row3_kol3"));
as you look, the above variable is defined by table array. That's right!

For customization of the table data, you can declare function with 'loopname' as name, as example:
	function loopname ($data) {
		//customization corresponds to the colomn is wrote here
		$data['kol0'] = some_customvalue_for_colom_0;
		$data['kol2'] = some_customvalue_for_colom_2;
		return $data;
	}
If the script inside the above function is used to modify the table data, you have to return
the data value back using "return $data;". But if not, it is not necessary.

In new release, for loop block use:
	<!--loop:[loopname]-->
		<html>some loop block</html>
	<!--/loop:[loopname]-->
instead using the old style tag.

*NOTICE*:
Since the tags can be customized to some behaviour by configuration file, it is *NOT* recommended
to use the old style tag because it can raises unexpected results. In addition, it will difficult
to be maintained later.

And finally, to define the variables inside loop block you have to write function 
with name format: <loop_name>_<var_inside_loop> with row number variable as parameter, as example:
	function loopname_varinsideloop ($row) {
		return $some_value;
	}

*NEW*:
In recent version, you can declare function with any function name, maybe as follow:
	function some_functionname ($row) {
		return $some_value;
	}
Then, after that you have to register the function through "RegisterFunction", as example:

	$tmpl->RegisterFunction('some_functionname', 'loopname_varinsideloop');

The second parameter should be the string which will points to the variable inside the loop block,
with format like the first example function name above.

So for the table data customization, which may as follow:
	function someother_functionname ($data) {
		//customization corresponds to the colomn is wrote here
		$data['kol0'] = some_customvalue_for_colom_0;
		$data['kol2'] = some_customvalue_for_colom_2;
		return $data;
	}
Then, after that you have to register the function as example:

	$tmpl->RegisterFunction('someother_functionname', 'loopname');

The second parameter should be the name of the loop block what it should be.

*WARNING*:
Since you can declare function with custom name, you may accidentally declare with name similar to the variable
correlates to the other loop block, or even the other loop block name. Because of that, this is *RECOMMENDED*
always use "RegisterFunction" to avoid deprecated function used which can be raised.

[*] IF-ELSEIF-ELSE Section
    ======================
For using the if-elseif-else block, use the tag as example:
<!--if:[ifblockname]=[logic expression]-->
	<html>the if block</html>
<!--/if:[ifblockname]-->
<!--elseif:[ifblockname]=[logic expression]-->
	<html>the elseif block</html>
<!--/elseif:[ifblockname]-->
<!--else:[ifblockname]-->
	<html>the else block</html>
<!--/else:[ifblockname]-->

The "logic expression" is the expression which should result boolean value,
and for security reason, it doesn't permitted to use any PHP function,
just use simple boolean expression. Any PHP operators are understandable ;)
It may uses variables used inside the template, but it will understood locally
inside the loop block scope only if it is used variables inside the loop block.

[*] Public Use Section
    ==================
1. Variable
#. $class->TemplateFile = some_templatefile;
#. $class->Var['varname'] = some_value;

2. Function
#. $class->SetHeader($fileheader);
#. $class->SetFooter($filefooter);
#. $class->RegisterFunction($functionname, $loopfor);
#. $class->Execute();
#. $class->Output([($outfile = '' | _PIPE)[, ($pipe_onlybody = TRUE | $writefile_mode = "w")]]);


Conclusion
==========
That's all, simply look inside the sample code and template file to more learn and use it.
And hope this class will helps you doing something your work easier. :)

Ofcourse, We're opened to people who need to develop this class for more powerful,
so any question, or anything you need to know, just feel free to email us.



Regards,
Muhamad Zakaria
===============
ym id: muhamad_zakaria