3 // +----------------------------------------------------------------------+
4 // | Copyright (c) 1997-2005 Ulf Wendel, Pierre-Alain Joye |
5 // +----------------------------------------------------------------------+
6 // | This source file is subject to the New BSD license, That is bundled |
7 // | with this package in the file LICENSE, and is available through |
8 // | the world-wide-web at |
9 // | http://www.opensource.org/licenses/bsd-license.php |
10 // | If you did not receive a copy of the new BSDlicense and are unable |
11 // | to obtain it through the world-wide-web, please send a note to |
12 // | pajoye@php.net so we can mail you a copy immediately. |
13 // +----------------------------------------------------------------------+
14 // | Author: Ulf Wendel <ulf.wendel@phpdoc.de> |
15 // | Pierre-Alain Joye <pajoye@php.net> |
16 // +----------------------------------------------------------------------+
18 // $Id: IT.php,v 1.14 2005/11/01 10:14:19 pajoye Exp $
21 require_once 'PEAR.php';
24 define('IT_ERROR', -1);
25 define('IT_TPL_NOT_FOUND', -2);
26 define('IT_BLOCK_NOT_FOUND', -3);
27 define('IT_BLOCK_DUPLICATE', -4);
28 define('IT_UNKNOWN_OPTION', -6);
30 * Integrated Template - IT
32 * Well there's not much to say about it. I needed a template class that
33 * supports a single template file with multiple (nested) blocks inside and
36 * The Isotemplate API is somewhat tricky for a beginner although it is the best
37 * one you can build. template::parse() [phplib template = Isotemplate] requests
38 * you to name a source and a target where the current block gets parsed into.
39 * Source and target can be block names or even handler names. This API gives you
40 * a maximum of fexibility but you always have to know what you do which is
41 * quite unusual for php skripter like me.
43 * I noticed that I do not any control on which block gets parsed into which one.
44 * If all blocks are within one file, the script knows how they are nested and in
45 * which way you have to parse them. IT knows that inner1 is a child of block2, there's
46 * no need to tell him about this.
53 * (hidden and automatically added)
61 * <td colspan=2>block2</td>
72 * To add content to block1 you simply type:
73 * <code>$tpl->setCurrentBlock("block1");</code>
74 * and repeat this as often as needed:
76 * $tpl->setVariable(...);
77 * $tpl->parseCurrentBlock();
80 * To add content to block2 you would type something like:
82 * $tpl->setCurrentBlock("inner1");
83 * $tpl->setVariable(...);
84 * $tpl->parseCurrentBlock();
86 * $tpl->setVariable(...);
87 * $tpl->parseCurrentBlock();
89 * $tpl->parse("block1");
92 * This will result in one repition of block1 which contains two repitions
93 * of inner1. inner2 will be removed if $removeEmptyBlock is set to true which is the default.
97 * $tpl = new HTML_Template_IT( [string filerootdir] );
99 * // load a template or set it with setTemplate()
100 * $tpl->loadTemplatefile( string filename [, boolean removeUnknownVariables, boolean removeEmptyBlocks] )
102 * // set "global" Variables meaning variables not beeing within a (inner) block
103 * $tpl->setVariable( string variablename, mixed value );
105 * // like with the Isotemplates there's a second way to use setVariable()
106 * $tpl->setVariable( array ( string varname => mixed value ) );
108 * // Let's use any block, even a deeply nested one
109 * $tpl->setCurrentBlock( string blockname );
111 * // repeat this as often as you need it.
112 * $tpl->setVariable( array ( string varname => mixed value ) );
113 * $tpl->parseCurrentBlock();
115 * // get the parsed template or print it: $tpl->show()
119 * @author Ulf Wendel <uw@netuse.de>
120 * @version $Id: IT.php,v 1.14 2005/11/01 10:14:19 pajoye Exp $
122 * @package HTML_Template_IT
124 class HTML_Template_IT
127 * Contains the error objects
130 * @see halt(), $printError, $haltOnError
135 * Clear cache on get()?
138 var $clearCache = false;
141 * First character of a variable placeholder ( _{_VARIABLE} ).
144 * @see $closingDelimiter, $blocknameRegExp, $variablenameRegExp
146 var $openingDelimiter = '{';
149 * Last character of a variable placeholder ( {VARIABLE_}_ ).
152 * @see $openingDelimiter, $blocknameRegExp, $variablenameRegExp
154 var $closingDelimiter = '}';
157 * RegExp matching a block in the template.
158 * Per default "sm" is used as the regexp modifier, "i" is missing.
159 * That means a case sensitive search is done.
162 * @see $variablenameRegExp, $openingDelimiter, $closingDelimiter
164 var $blocknameRegExp = '[0-9A-Za-z_-]+';
167 * RegExp matching a variable placeholder in the template.
168 * Per default "sm" is used as the regexp modifier, "i" is missing.
169 * That means a case sensitive search is done.
172 * @see $blocknameRegExp, $openingDelimiter, $closingDelimiter
174 var $variablenameRegExp = '[0-9A-Za-z_-]+';
177 * RegExp used to find variable placeholder, filled by the constructor.
178 * @var string Looks somewhat like @(delimiter varname delimiter)@
180 * @see IntegratedTemplate()
182 var $variablesRegExp = '';
185 * RegExp used to strip unused variable placeholder.
186 * @brother $variablesRegExp
188 var $removeVariablesRegExp = '';
191 * Controls the handling of unknown variables, default is remove.
195 var $removeUnknownVariables = true;
198 * Controls the handling of empty blocks, default is remove.
202 var $removeEmptyBlocks = true;
205 * RegExp used to find blocks an their content, filled by the constructor.
207 * @see IntegratedTemplate()
209 var $blockRegExp = '';
212 * Name of the current block.
215 var $currentBlock = '__global__';
218 * Content of the template.
224 * Array of all blocks and their content.
229 var $blocklist = array();
232 * Array with the parsed content of a block.
236 var $blockdata = array();
239 * Array of variables in a block.
242 var $blockvariables = array();
245 * Array of inner blocks of a block.
248 var $blockinner = array();
251 * List of blocks to preverse even if they are "empty".
253 * This is something special. Sometimes you have blocks that
254 * should be preserved although they are empty (no placeholder replaced).
255 * Think of a shopping basket. If it's empty you have to drop a message to
256 * the user. If it's filled you have to show the contents of
257 * the shopping baseket. Now where do you place the message that the basket
258 * is empty? It's no good idea to place it in you applications as customers
259 * tend to like unecessary minor text changes. Having another template file
260 * for an empty basket means that it's very likely that one fine day
261 * the filled and empty basket templates have different layout. I decided
262 * to introduce blocks that to not contain any placeholder but only
263 * text such as the message "Your shopping basked is empty".
265 * Now if there is no replacement done in such a block the block will
266 * be recognized as "empty" and by default ($removeEmptyBlocks = true) be
267 * stripped off. To avoid thisyou can now call touchBlock() to avoid this.
269 * The array $touchedBlocks stores a list of touched block which must not
270 * be removed even if they are empty.
272 * @var array $touchedBlocks
273 * @see touchBlock(), $removeEmptyBlocks
275 var $touchedBlocks = array();
278 * List of blocks which should not be shown even if not "empty"
279 * @var array $_hiddenBlocks
280 * @see hideBlock(), $removeEmptyBlocks
282 var $_hiddenBlocks = array();
287 * Variables get cached before any replacement is done.
288 * Advantage: empty blocks can be removed automatically.
289 * Disadvantage: might take some more memory
292 * @see setVariable(), $clearCacheOnParse
294 var $variableCache = array();
297 * Clear the variable cache on parse?
299 * If you're not an expert just leave the default false.
300 * True reduces memory consumption somewhat if you tend to
301 * add lots of values for unknown placeholder.
305 var $clearCacheOnParse = false;
308 * Root directory for all file operations.
309 * The string gets prefixed to all filenames given.
311 * @see HTML_Template_IT(), setRoot()
316 * Internal flag indicating that a blockname was used multiple times.
319 var $flagBlocktrouble = false;
322 * Flag indicating that the global block was parsed.
325 var $flagGlobalParsed = false;
328 * EXPERIMENTAL! FIXME!
329 * Flag indication that a template gets cached.
331 * Complex templates require some times to be preparsed
332 * before the replacement can take place. Often I use
333 * one template file over and over again but I don't know
334 * before that I will use the same template file again.
335 * Now IT could notice this and skip the preparse.
339 var $flagCacheTemplatefile = true;
342 * EXPERIMENTAL! FIXME!
344 var $lastTemplatefile = '';
347 * $_options['preserve_data'] Whether to substitute variables and remove
348 * empty placeholders in data passed through setVariable
349 * (see also bugs #20199, #21951).
350 * $_options['use_preg'] Whether to use preg_replace instead of
351 * str_replace in parse()
352 * (this is a backwards compatibility feature, see also bugs #21951, #20392)
354 var $_options = array(
355 'preserve_data' => false,
360 * Builds some complex regular expressions and optinally sets the
361 * file root directory.
363 * Make sure that you call this constructor if you derive your template
364 * class from this one.
366 * @param string File root directory, prefix for all filenames
367 * given to the object.
370 function HTML_Template_IT($root = '', $options = null)
372 if (!is_null($options)) {
373 $this->setOptions($options);
375 $this->variablesRegExp = '@' . $this->openingDelimiter .
376 '(' . $this->variablenameRegExp . ')' .
377 $this->closingDelimiter . '@sm';
378 $this->removeVariablesRegExp = '@' . $this->openingDelimiter .
379 "\s*(" . $this->variablenameRegExp .
380 ")\s*" . $this->closingDelimiter .'@sm';
382 $this->blockRegExp = '@<!--\s+BEGIN\s+(' . $this->blocknameRegExp .
383 ')\s+-->(.*)<!--\s+END\s+\1\s+-->@sm';
385 $this->setRoot($root);
390 * Sets the option for the template class
393 * @param string option name
394 * @param mixed option value
395 * @return mixed IT_OK on success, error object on failure
397 function setOption($option, $value)
399 if (array_key_exists($option, $this->_options)) {
400 $this->_options[$option] = $value;
404 return PEAR::raiseError(
405 $this->errorMessage(IT_UNKNOWN_OPTION) . ": '{$option}'",
411 * Sets the options for the template class
414 * @param string options array of options
416 * 'preserve_data' => false,
418 * @param mixed option value
419 * @return mixed IT_OK on success, error object on failure
422 function setOptions($options)
424 if (is_array($options)) {
425 foreach ($options as $option => $value) {
426 $error = $this->setOption($option, $value);
427 if (PEAR::isError($error)) {
437 * Print a certain block with all replacements done.
440 function show($block = '__global__')
442 print $this->get($block);
446 * Returns a block with all replacements done.
448 * @param string name of the block
454 function get($block = '__global__')
456 if ($block == '__global__' && !$this->flagGlobalParsed) {
457 $this->parse('__global__');
460 if (!isset($this->blocklist[$block])) {
461 $this->err[] = PEAR::raiseError(
462 $this->errorMessage(IT_BLOCK_NOT_FOUND) .
469 if (isset($this->blockdata[$block])) {
470 $ret = $this->blockdata[$block];
471 if ($this->clearCache) {
472 unset($this->blockdata[$block]);
474 if ($this->_options['preserve_data']) {
476 $this->openingDelimiter .
477 '%preserved%' . $this->closingDelimiter,
478 $this->openingDelimiter,
489 * Parses the given block.
491 * @param string name of the block to be parsed
493 * @see parseCurrentBlock()
496 function parse($block = '__global__', $flag_recursion = false)
498 static $regs, $values;
500 if (!isset($this->blocklist[$block])) {
501 return PEAR::raiseError(
502 $this->errorMessage( IT_BLOCK_NOT_FOUND ) . '"' . $block . "'",
507 if ($block == '__global__') {
508 $this->flagGlobalParsed = true;
511 if (!$flag_recursion) {
515 $outer = $this->blocklist[$block];
518 if ($this->clearCacheOnParse) {
519 foreach ($this->variableCache as $name => $value) {
520 $regs[] = $this->openingDelimiter .
521 $name . $this->closingDelimiter;
525 $this->variableCache = array();
527 foreach ($this->blockvariables[$block] as $allowedvar => $v) {
529 if (isset($this->variableCache[$allowedvar])) {
530 $regs[] = $this->openingDelimiter .
531 $allowedvar . $this->closingDelimiter;
532 $values[] = $this->variableCache[$allowedvar];
533 unset($this->variableCache[$allowedvar]);
539 if (isset($this->blockinner[$block])) {
540 foreach ($this->blockinner[$block] as $k => $innerblock) {
542 $this->parse($innerblock, true);
543 if ($this->blockdata[$innerblock] != '') {
547 $placeholder = $this->openingDelimiter . "__" .
548 $innerblock . "__" . $this->closingDelimiter;
549 $outer = str_replace(
551 $this->blockdata[$innerblock], $outer
553 $this->blockdata[$innerblock] = "";
558 if (!$flag_recursion && 0 != count($values)) {
559 if ($this->_options['use_preg']) {
560 $regs = array_map(array(
561 &$this, '_addPregDelimiters'),
564 $funcReplace = 'preg_replace';
566 $funcReplace = 'str_replace';
569 if ($this->_options['preserve_data']) {
571 array(&$this, '_preserveOpeningDelimiter'), $values
575 $outer = $funcReplace($regs, $values, $outer);
577 if ($this->removeUnknownVariables) {
578 $outer = preg_replace($this->removeVariablesRegExp, "", $outer);
583 if (!$this->removeEmptyBlocks) {
584 $this->blockdata[$block ].= $outer;
586 if (isset($this->touchedBlocks[$block])) {
587 $this->blockdata[$block] .= $outer;
588 unset($this->touchedBlocks[$block]);
592 $this->blockdata[$block] .= $outer;
599 * Parses the current block
600 * @see parse(), setCurrentBlock(), $currentBlock
603 function parseCurrentBlock()
605 return $this->parse($this->currentBlock);
606 } // end func parseCurrentBlock
609 * Sets a variable value.
611 * The function can be used eighter like setVariable( "varname", "value")
612 * or with one array $variables["varname"] = "value"
613 * given setVariable($variables) quite like phplib templates set_var().
615 * @param mixed string with the variable name or an array
616 * %variables["varname"] = "value"
617 * @param string value of the variable or empty if $variable
619 * @param string prefix for variable names
622 function setVariable($variable, $value = '')
624 if (is_array($variable)) {
625 $this->variableCache = array_merge(
626 $this->variableCache, $variable
629 $this->variableCache[$variable] = $value;
631 } // end func setVariable
634 * Sets the name of the current block that is the block where variables
637 * @param string name of the block
638 * @return boolean false on failure, otherwise true
642 function setCurrentBlock($block = '__global__')
645 if (!isset($this->blocklist[$block])) {
646 return PEAR::raiseError(
647 $this->errorMessage( IT_BLOCK_NOT_FOUND ) .
648 '"' . $block . "'", IT_BLOCK_NOT_FOUND
652 $this->currentBlock = $block;
655 } // end func setCurrentBlock
658 * Preserves an empty block even if removeEmptyBlocks is true.
660 * @param string name of the block
661 * @return boolean false on false, otherwise true
664 * @see $removeEmptyBlocks
666 function touchBlock($block)
668 if (!isset($this->blocklist[$block])) {
669 return PEAR::raiseError(
670 $this->errorMessage(IT_BLOCK_NOT_FOUND) .
671 '"' . $block . "'", IT_BLOCK_NOT_FOUND);
674 $this->touchedBlocks[$block] = true;
677 } // end func touchBlock
680 * Clears all datafields of the object and rebuild the internal blocklist
682 * LoadTemplatefile() and setTemplate() automatically call this function
683 * when a new template is given. Don't use this function
684 * unless you know what you're doing.
692 $this->findBlocks($this->template);
693 // we don't need it any more
694 $this->template = '';
695 $this->buildBlockvariablelist();
699 * Clears all datafields of the object.
701 * Don't use this function unless you know what you're doing.
708 $this->err = array();
710 $this->currentBlock = '__global__';
712 $this->variableCache = array();
713 $this->blocklookup = array();
714 $this->touchedBlocks = array();
716 $this->flagBlocktrouble = false;
717 $this->flagGlobalParsed = false;
723 * You can eighter load a template file from disk with
724 * LoadTemplatefile() or set the template manually using this function.
726 * @param string template content
727 * @param boolean remove unknown/unused variables?
728 * @param boolean remove empty blocks?
729 * @see LoadTemplatefile(), $template
732 function setTemplate( $template, $removeUnknownVariables = true,
733 $removeEmptyBlocks = true)
735 $this->removeUnknownVariables = $removeUnknownVariables;
736 $this->removeEmptyBlocks = $removeEmptyBlocks;
738 if ($template == '' && $this->flagCacheTemplatefile) {
739 $this->variableCache = array();
740 $this->blockdata = array();
741 $this->touchedBlocks = array();
742 $this->currentBlock = '__global__';
744 $this->template = '<!-- BEGIN __global__ -->' . $template .
745 '<!-- END __global__ -->';
749 if ($this->flagBlocktrouble) {
754 } // end func setTemplate
757 * Reads a template file from the disk.
759 * @param string name of the template file
760 * @param bool how to handle unknown variables.
761 * @param bool how to handle empty blocks.
763 * @return boolean false on failure, otherwise true
764 * @see $template, setTemplate(), $removeUnknownVariables,
767 function loadTemplatefile( $filename,
768 $removeUnknownVariables = true,
769 $removeEmptyBlocks = true )
772 if (!$this->flagCacheTemplatefile ||
773 $this->lastTemplatefile != $filename
775 $template = $this->getFile($filename);
777 $this->lastTemplatefile = $filename;
779 return $template != '' ?
781 $template,$removeUnknownVariables, $removeEmptyBlocks
783 } // end func LoadTemplatefile
786 * Sets the file root. The file root gets prefixed to all filenames passed
789 * Make sure that you override this function when using the class
793 * @see IntegratedTemplate()
796 function setRoot($root)
798 if ($root != '' && substr($root, -1) != '/') {
802 $this->fileRoot = $root;
803 } // end func setRoot
806 * Build a list of all variables within of a block
808 function buildBlockvariablelist()
810 foreach ($this->blocklist as $name => $content) {
811 preg_match_all($this->variablesRegExp, $content, $regs);
813 if (count($regs[1]) != 0) {
814 foreach ($regs[1] as $k => $var) {
815 $this->blockvariables[$name][$var] = true;
818 $this->blockvariables[$name] = array();
821 } // end func buildBlockvariablelist
824 * Returns a list of all global variables
826 function getGlobalvariables()
831 foreach ($this->blockvariables['__global__'] as $allowedvar => $v) {
832 if (isset($this->variableCache[$allowedvar])) {
833 $regs[] = '@' . $this->openingDelimiter .
834 $allowedvar . $this->closingDelimiter . '@';
835 $values[] = $this->variableCache[$allowedvar];
836 unset($this->variableCache[$allowedvar]);
840 return array($regs, $values);
841 } // end func getGlobalvariables
844 * Recusively builds a list of all blocks within the template.
846 * @param string string that gets scanned
849 function findBlocks($string)
851 $blocklist = array();
853 if (preg_match_all($this->blockRegExp, $string, $regs, PREG_SET_ORDER)) {
854 foreach ($regs as $k => $match) {
855 $blockname = $match[1];
856 $blockcontent = $match[2];
858 if (isset($this->blocklist[$blockname])) {
859 $this->err[] = PEAR::raiseError(
861 IT_BLOCK_DUPLICATE, $blockname),
864 $this->flagBlocktrouble = true;
867 $this->blocklist[$blockname] = $blockcontent;
868 $this->blockdata[$blockname] = "";
870 $blocklist[] = $blockname;
872 $inner = $this->findBlocks($blockcontent);
873 foreach ($inner as $k => $name) {
875 '@<!--\s+BEGIN\s+%s\s+-->(.*)<!--\s+END\s+%s\s+-->@sm',
880 $this->blocklist[$blockname] = preg_replace(
882 $this->openingDelimiter .
883 '__' . $name . '__' .
884 $this->closingDelimiter,
885 $this->blocklist[$blockname]
887 $this->blockinner[$blockname][] = $name;
888 $this->blockparents[$name] = $blockname;
894 } // end func findBlocks
897 * Reads a file from disk and returns its content.
898 * @param string Filename
899 * @return string Filecontent
901 function getFile($filename)
903 if ($filename{0} == '/' && substr($this->fileRoot, -1) == '/') {
904 $filename = substr($filename, 1);
907 $filename = $this->fileRoot . $filename;
909 if (!($fh = @fopen($filename, 'r'))) {
910 $this->err[] = PEAR::raiseError(
911 $this->errorMessage(IT_TPL_NOT_FOUND) .
912 ': "' .$filename .'"',
918 $content = fread($fh, filesize($filename));
922 "#<!-- INCLUDE (.*) -->#ime", "\$this->getFile('\\1')", $content
924 } // end func getFile
927 * Adds delimiters to a string, so it can be used as a pattern
928 * in preg_* functions
933 function _addPregDelimiters($str)
935 return '@' . $str . '@';
939 * Replaces an opening delimiter by a special string
944 function _preserveOpeningDelimiter($str)
946 return (false === strpos($str, $this->openingDelimiter))?
949 $this->openingDelimiter,
950 $this->openingDelimiter .
951 '%preserved%' . $this->closingDelimiter,
957 * Return a textual error message for a IT error code
959 * @param integer $value error code
961 * @return string error message, or false if the error code was
964 function errorMessage($value, $blockname = '')
966 static $errorMessages;
967 if (!isset($errorMessages)) {
968 $errorMessages = array(
970 IT_ERROR => 'unknown error',
971 IT_TPL_NOT_FOUND => 'Cannot read the template file',
972 IT_BLOCK_NOT_FOUND => 'Cannot find this block',
973 IT_BLOCK_DUPLICATE => 'The name of a block must be'.
974 ' uniquewithin a template.'.
975 ' Found "' . $blockname . '" twice.'.
976 'Unpredictable results '.
978 IT_UNKNOWN_OPTION => 'Unknown option'
982 if (PEAR::isError($value)) {
983 $value = $value->getCode();
986 return isset($errorMessages[$value]) ?
987 $errorMessages[$value] : $errorMessages[IT_ERROR];
989 } // end class IntegratedTemplate