[phplib-dev] Added IT[X] Integrated Template [Extension] From: Ulf Wendel (UW <email protected>)
Date: 09/22/00

Hi,

I just commited a new template class to the phplib. It's placed
between SimpleTemplates ( just Search&Replace) and IsoTemplate (
the stable template.inc ).

+++ Why yet another template class? +++

When looking for templates you'll find two types of classes. Very
simple ones that can do no more than search and replace and the
pretty complex ones that offer blocks and even templates compound
of multiple files. One of the simple ones can be found in the
excellent book from Till Gerken and Tobias Ratschiller "Web
Application Development with PHP4". FastTemplate and IsoTemplate
( the nick of Kris is Isotopp, stable template.inc) are some
examples for complex templates.

FastTemplate is rather slow (does not utilize preg_replace) and
has a complicated API that only Perl programmers like...
IsoTemplate is really fast but the block API requests you to turn
on your brain.

Anyway none of them fits my needs. I do need block but my
customers and designer do not understand that they have to split
one file in multiple files to get blocks. No WYSIWYG tool offers
a deep blue button "convert to NetUSE" which they would
understand. Yes, I could manually split the template but I didn't
like the IsoTemplate Block API eighter so I wrote a new class:
"Integrated Template" (IT) and "Integrated Template Extension"
(ITX).

+++ Features +++
  
 IT:
    + (remove unknowns, remove empty blocks)
    + search&replace
    + blocks
    + nested blocks
    + single file

 ITX:
    + external blocks = multiple file possibility

Compared to IsoTemplate IT lacks the possibility to have external
blocks or to add blocks at runtime, which is excactly what I
needed. ITX offers external blocks and thereby a way to add
blocks at runtime which means it covers the full IsoTemplate
functionality.

+++ So what about the API? +++

Warning: I wrote IT[X] to be used in another project with
different naming conventions. The code has not been isofied yet
and the API names will change slightly. Feel free to convert it
to the phplib way, I do not have the time to do so now.

The API is simmilar to the IsoTemplate API and the block API is
even simpler when you're a first time user.

Using IT without blocks:

 $tpl = new IntegratedTemplate( [string fileroot] );

 // loadTemplatefile() or setTemplate()
 $tpl->loadTemplatefile( string filename [, boolean
removeUnknownVariables, boolean removeEmptyBlocks);

 // replace variable placeholder with values
 $tpl->setVariable( string varname, mixed value );
 $tpl->setVariable( array ( string varname => mixed value ) );
 ...

 // get() or show()
 $tpl->show();

Using IT with blocks:

 ...

 // use any block within the template, even a nested one
 $tpl->setCurrentBlock( string blockname )

 // as many loops as you like
 $tpl->setVariable( array ( string varname => mixed value ) );
 $tpl->parseCurrentBlock();

 // seting a "global" variable that can't be mixed up
 // with a block variable because it's name is unique
 $tpl->setVariable( string varname, mixed value );

 // setting a "global" variable that can be mixed up
 // with a block variable meaning there is a placeholder
 // with the same name in the block and outside
 $tpl->setCurrentBlock(); // fallback to block "__global__"
 $tpl->setVariable( string varname, mixed value );

 ...

Using ITX with external blocks:

  $tpl = new IntegratedTemplateExtension( [string fileroot] );

  // this time setTemplate instead of loadTemplatefile()...
  $tpl->setTemplate( string template [, boolean
removeUnknownVariables, boolean removeEmptyBlocks] );

  $tpl->setVariable( array ( string varname => mixed value ) );

  // ok, need a new block meaning: replacing a variable
placeholder
  // in the original template with a block from file
  $tpl->addBlockfile( string placeholder, string blockname,
string filename);

  // use it as usually
  $tpl->setCurrentBlock( string blockname );
  ...

Coming versions of ITX will allow you to exchange block templates
at runtime; replaceBlock() is currently without functionality.

+++ What about the speed? +++

Same as with IsoTemplate. IT might even be a touch faster because
you can have several blocks with only one IO operation whereas
IsoTemplate needs several. But it's hard to say if this is true
all my tests showed overall differences of about 5% (runtime:
20sec, several runs) which is within the difference of two runs.

+++ Is it stable? +++

Don't know, looks good. Remember my remarks on the API!

+++ Internal working +++

IT[X] works as a proxy. setVariable() transfers values from your
script into the global IT cache. parse() and parseCurrentBlock()
copies that values that fit the variable name list of the target
block to the target block cache. The replacement will be done
when you call get() or show(). The block cache gets -not- cleaned
by get(). Use free() if you're worried about the memory
consumption. free() gets automatically called when you assign a
new template to the object.

By the way get( string blockname ) can be used to retrive a
"parsed and replaced" block. That means you can parse any block
into multiple variable placeholder (as you can to with
IsoTemplate).

There's on "hack" in the code. IT builds it blocklist
recursively. To do so it needs to add "__global__" block around
the template. "__global__" is a default value for many function
arguments.

Have fun with it!

Ulf 

-- 
Ulf Wendel
NetUSE AG, Siemenswall, 24107 Kiel, Germany
Fon: +49 431 386435 00  --  Fax: +49 431 386435 99

---------------------------------------------------------------------
To unsubscribe, e-mail: phplib-dev-unsubscribe <email protected>
For additional commands, e-mail: phplib-dev-help <email protected>