Subversion Repositories Applications.papyrus

Rev

Go to most recent revision | Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
832 florian 1
<?php
2
//
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
// +----------------------------------------------------------------------+
17
//
18
// $Id$
19
//
20
 
21
require_once 'PEAR.php';
22
 
23
define('IT_OK',                         1);
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);
29
/**
30
 * Integrated Template - IT
31
 *
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
34
 * a simple block API.
35
 *
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.
42
 *
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.
47
 *
48
 * <table border>
49
 *   <tr>
50
 *     <td colspan=2>
51
 *       __global__
52
 *       <p>
53
 *       (hidden and automatically added)
54
 *     </td>
55
 *   </tr>
56
 *   <tr>
57
 *     <td>block1</td>
58
 *     <td>
59
 *       <table border>
60
 *         <tr>
61
 *           <td colspan=2>block2</td>
62
 *         </tr>
63
 *         <tr>
64
 *           <td>inner1</td>
65
 *           <td>inner2</td>
66
 *         </tr>
67
 *       </table>
68
 *     </td>
69
 *   </tr>
70
 * </table>
71
 *
72
 * To add content to block1 you simply type:
73
 * <code>$tpl->setCurrentBlock("block1");</code>
74
 * and repeat this as often as needed:
75
 * <code>
76
 *   $tpl->setVariable(...);
77
 *   $tpl->parseCurrentBlock();
78
 * </code>
79
 *
80
 * To add content to block2 you would type something like:
81
 * <code>
82
 * $tpl->setCurrentBlock("inner1");
83
 * $tpl->setVariable(...);
84
 * $tpl->parseCurrentBlock();
85
 *
86
 * $tpl->setVariable(...);
87
 * $tpl->parseCurrentBlock();
88
 *
89
 * $tpl->parse("block1");
90
 * </code>
91
 *
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.
94
 *
95
 * Usage:
96
 * <code>
97
 * $tpl = new HTML_Template_IT( [string filerootdir] );
98
 *
99
 * // load a template or set it with setTemplate()
100
 * $tpl->loadTemplatefile( string filename [, boolean removeUnknownVariables, boolean removeEmptyBlocks] )
101
 *
102
 * // set "global" Variables meaning variables not beeing within a (inner) block
103
 * $tpl->setVariable( string variablename, mixed value );
104
 *
105
 * // like with the Isotemplates there's a second way to use setVariable()
106
 * $tpl->setVariable( array ( string varname => mixed value ) );
107
 *
108
 * // Let's use any block, even a deeply nested one
109
 * $tpl->setCurrentBlock( string blockname );
110
 *
111
 * // repeat this as often as you need it.
112
 * $tpl->setVariable( array ( string varname => mixed value ) );
113
 * $tpl->parseCurrentBlock();
114
 *
115
 * // get the parsed template or print it: $tpl->show()
116
 * $tpl->get();
117
 * </code>
118
 *
119
 * @author   Ulf Wendel <uw@netuse.de>
120
 * @version  $Id$
121
 * @access   public
122
 * @package  HTML_Template_IT
123
 */
124
class HTML_Template_IT
125
{
126
    /**
127
     * Contains the error objects
128
     * @var      array
129
     * @access   public
130
     * @see      halt(), $printError, $haltOnError
131
     */
132
    var $err = array();
133
 
134
    /**
135
     * Clear cache on get()?
136
     * @var      boolean
137
     */
138
    var $clearCache = false;
139
 
140
    /**
141
     * First character of a variable placeholder ( _{_VARIABLE} ).
142
     * @var      string
143
     * @access   public
144
     * @see      $closingDelimiter, $blocknameRegExp, $variablenameRegExp
145
     */
146
    var $openingDelimiter = '{';
147
 
148
    /**
149
     * Last character of a variable placeholder ( {VARIABLE_}_ ).
150
     * @var      string
151
     * @access   public
152
     * @see      $openingDelimiter, $blocknameRegExp, $variablenameRegExp
153
     */
154
    var $closingDelimiter     = '}';
155
 
156
    /**
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.
160
     * @var      string
161
     * @access   public
162
     * @see      $variablenameRegExp, $openingDelimiter, $closingDelimiter
163
     */
164
    var $blocknameRegExp    = '[0-9A-Za-z_-]+';
165
 
166
    /**
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.
170
     * @var      string
171
     * @access   public
172
     * @see      $blocknameRegExp, $openingDelimiter, $closingDelimiter
173
     */
174
    var $variablenameRegExp    = '[0-9A-Za-z_-]+';
175
 
176
    /**
177
     * RegExp used to find variable placeholder, filled by the constructor.
178
     * @var      string    Looks somewhat like @(delimiter varname delimiter)@
179
     * @access   public
180
     * @see      IntegratedTemplate()
181
     */
182
    var $variablesRegExp = '';
183
 
184
    /**
185
     * RegExp used to strip unused variable placeholder.
186
     * @brother  $variablesRegExp
187
     */
188
    var $removeVariablesRegExp = '';
189
 
190
    /**
191
     * Controls the handling of unknown variables, default is remove.
192
     * @var      boolean
193
     * @access   public
194
     */
195
    var $removeUnknownVariables = true;
196
 
197
    /**
198
     * Controls the handling of empty blocks, default is remove.
199
     * @var      boolean
200
     * @access   public
201
     */
202
    var $removeEmptyBlocks = true;
203
 
204
    /**
205
     * RegExp used to find blocks an their content, filled by the constructor.
206
     * @var      string
207
     * @see      IntegratedTemplate()
208
     */
209
    var $blockRegExp = '';
210
 
211
    /**
212
     * Name of the current block.
213
     * @var      string
214
     */
215
    var $currentBlock = '__global__';
216
 
217
    /**
218
     * Content of the template.
219
     * @var      string
220
     */
221
    var $template = '';
222
 
223
    /**
224
     * Array of all blocks and their content.
225
     *
226
     * @var      array
227
     * @see      findBlocks()
228
     */
229
    var $blocklist = array();
230
 
231
    /**
232
     * Array with the parsed content of a block.
233
     *
234
     * @var      array
235
     */
236
    var $blockdata = array();
237
 
238
    /**
239
     * Array of variables in a block.
240
     * @var      array
241
     */
242
    var $blockvariables = array();
243
 
244
    /**
245
     * Array of inner blocks of a block.
246
     * @var      array
247
     */
248
    var $blockinner = array();
249
 
250
    /**
251
     * List of blocks to preverse even if they are "empty".
252
     *
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".
264
     *
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.
268
     *
269
     * The array $touchedBlocks stores a list of touched block which must not
270
     * be removed even if they are empty.
271
     *
272
     * @var  array    $touchedBlocks
273
     * @see  touchBlock(), $removeEmptyBlocks
274
     */
275
     var $touchedBlocks = array();
276
 
277
    /**
278
     * List of blocks which should not be shown even if not "empty"
279
     * @var  array    $_hiddenBlocks
280
     * @see  hideBlock(), $removeEmptyBlocks
281
     */
282
    var $_hiddenBlocks = array();
283
 
284
    /**
285
     * Variable cache.
286
     *
287
     * Variables get cached before any replacement is done.
288
     * Advantage: empty blocks can be removed automatically.
289
     * Disadvantage: might take some more memory
290
     *
291
     * @var    array
292
     * @see    setVariable(), $clearCacheOnParse
293
     */
294
    var $variableCache = array();
295
 
296
    /**
297
     * Clear the variable cache on parse?
298
     *
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.
302
     *
303
     * @var    boolean
304
     */
305
    var $clearCacheOnParse = false;
306
 
307
    /**
308
     * Root directory for all file operations.
309
     * The string gets prefixed to all filenames given.
310
     * @var    string
311
     * @see    HTML_Template_IT(), setRoot()
312
     */
313
    var $fileRoot = '';
314
 
315
    /**
316
     * Internal flag indicating that a blockname was used multiple times.
317
     * @var    boolean
318
     */
319
    var $flagBlocktrouble = false;
320
 
321
    /**
322
     * Flag indicating that the global block was parsed.
323
     * @var    boolean
324
     */
325
    var $flagGlobalParsed = false;
326
 
327
    /**
328
     * EXPERIMENTAL! FIXME!
329
     * Flag indication that a template gets cached.
330
     *
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.
336
     *
337
     * @var    boolean
338
     */
339
    var $flagCacheTemplatefile = true;
340
 
341
    /**
342
     * EXPERIMENTAL! FIXME!
343
     */
344
    var $lastTemplatefile = '';
345
 
346
    /**
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)
353
     */
354
    var $_options = array(
355
        'preserve_data' => false,
356
        'use_preg'      => true
357
    );
358
 
359
    /**
360
     * Builds some complex regular expressions and optinally sets the
361
     * file root directory.
362
     *
363
     * Make sure that you call this constructor if you derive your template
364
     * class from this one.
365
     *
366
     * @param    string    File root directory, prefix for all filenames
367
     *                     given to the object.
368
     * @see      setRoot()
369
     */
370
    function HTML_Template_IT($root = '', $options = null)
371
    {
372
        if (!is_null($options)) {
373
            $this->setOptions($options);
374
        }
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';
381
 
382
        $this->blockRegExp = '@<!--\s+BEGIN\s+(' . $this->blocknameRegExp .
383
                             ')\s+-->(.*)<!--\s+END\s+\1\s+-->@sm';
384
 
385
        $this->setRoot($root);
386
    } // end constructor
387
 
388
 
389
    /**
390
     * Sets the option for the template class
391
     *
392
     * @access public
393
     * @param  string  option name
394
     * @param  mixed   option value
395
     * @return mixed   IT_OK on success, error object on failure
396
     */
397
    function setOption($option, $value)
398
    {
399
        if (array_key_exists($option, $this->_options)) {
400
            $this->_options[$option] = $value;
401
            return IT_OK;
402
        }
403
 
404
        return PEAR::raiseError(
405
                $this->errorMessage(IT_UNKNOWN_OPTION) . ": '{$option}'",
406
                IT_UNKNOWN_OPTION
407
            );
408
    }
409
 
410
    /**
411
     * Sets the options for the template class
412
     *
413
     * @access public
414
     * @param  string  options array of options
415
     *                 default value:
416
     *                   'preserve_data' => false,
417
     *                   'use_preg'      => true
418
     * @param  mixed   option value
419
     * @return mixed   IT_OK on success, error object on failure
420
     * @see $options
421
     */
422
    function setOptions($options)
423
    {
424
        if (is_array($options)) {
425
            foreach ($options as $option => $value) {
426
                $error = $this->setOption($option, $value);
427
                if (PEAR::isError($error)) {
428
                    return $error;
429
                }
430
            }
431
        }
432
 
433
        return IT_OK;
434
    }
435
 
436
    /**
437
     * Print a certain block with all replacements done.
438
     * @brother get()
439
     */
440
    function show($block = '__global__')
441
    {
442
        print $this->get($block);
443
    } // end func show
444
 
445
    /**
446
     * Returns a block with all replacements done.
447
     *
448
     * @param    string     name of the block
449
     * @return   string
450
     * @throws   PEAR_Error
451
     * @access   public
452
     * @see      show()
453
     */
454
    function get($block = '__global__')
455
    {
456
        if ($block == '__global__'  && !$this->flagGlobalParsed) {
457
            $this->parse('__global__');
458
        }
459
 
460
        if (!isset($this->blocklist[$block])) {
461
            $this->err[] = PEAR::raiseError(
462
                            $this->errorMessage(IT_BLOCK_NOT_FOUND) .
463
                            '"' . $block . "'",
464
                            IT_BLOCK_NOT_FOUND
465
                        );
466
            return '';
467
        }
468
 
469
        if (isset($this->blockdata[$block])) {
470
            $ret = $this->blockdata[$block];
471
            if ($this->clearCache) {
472
                unset($this->blockdata[$block]);
473
            }
474
            if ($this->_options['preserve_data']) {
475
                $ret = str_replace(
476
                        $this->openingDelimiter .
477
                        '%preserved%' . $this->closingDelimiter,
478
                        $this->openingDelimiter,
479
                        $ret
480
                    );
481
            }
482
            return $ret;
483
        }
484
 
485
        return '';
486
    } // end func get()
487
 
488
    /**
489
     * Parses the given block.
490
     *
491
     * @param    string    name of the block to be parsed
492
     * @access   public
493
     * @see      parseCurrentBlock()
494
     * @throws   PEAR_Error
495
     */
496
    function parse($block = '__global__', $flag_recursion = false)
497
    {
498
        static $regs, $values;
499
 
500
        if (!isset($this->blocklist[$block])) {
501
            return PEAR::raiseError(
502
                $this->errorMessage( IT_BLOCK_NOT_FOUND ) . '"' . $block . "'",
503
                        IT_BLOCK_NOT_FOUND
504
                );
505
        }
506
 
507
        if ($block == '__global__') {
508
            $this->flagGlobalParsed = true;
509
        }
510
 
511
        if (!$flag_recursion) {
512
            $regs   = array();
513
            $values = array();
514
        }
515
        $outer = $this->blocklist[$block];
516
        $empty = true;
517
 
518
        if ($this->clearCacheOnParse) {
519
            foreach ($this->variableCache as $name => $value) {
520
                $regs[] = $this->openingDelimiter .
521
                          $name . $this->closingDelimiter;
522
                $values[] = $value;
523
                $empty = false;
524
            }
525
            $this->variableCache = array();
526
        } else {
527
            foreach ($this->blockvariables[$block] as $allowedvar => $v) {
528
 
529
                if (isset($this->variableCache[$allowedvar])) {
530
                   $regs[]   = $this->openingDelimiter .
531
                               $allowedvar . $this->closingDelimiter;
532
                   $values[] = $this->variableCache[$allowedvar];
533
                   unset($this->variableCache[$allowedvar]);
534
                   $empty = false;
535
                }
536
            }
537
        }
538
 
539
        if (isset($this->blockinner[$block])) {
540
            foreach ($this->blockinner[$block] as $k => $innerblock) {
541
 
542
                $this->parse($innerblock, true);
543
                if ($this->blockdata[$innerblock] != '') {
544
                    $empty = false;
545
                }
546
 
547
                $placeholder = $this->openingDelimiter . "__" .
548
                                $innerblock . "__" . $this->closingDelimiter;
549
                $outer = str_replace(
550
                                    $placeholder,
551
                                    $this->blockdata[$innerblock], $outer
552
                        );
553
                $this->blockdata[$innerblock] = "";
554
            }
555
 
556
        }
557
 
558
        if (!$flag_recursion && 0 != count($values)) {
559
            if ($this->_options['use_preg']) {
560
                $regs        = array_map(array(
561
                                    &$this, '_addPregDelimiters'),
562
                                    $regs
563
                                );
564
                $funcReplace = 'preg_replace';
565
            } else {
566
                $funcReplace = 'str_replace';
567
            }
568
 
569
            if ($this->_options['preserve_data']) {
570
                $values = array_map(
571
                            array(&$this, '_preserveOpeningDelimiter'), $values
572
                        );
573
            }
574
 
575
            $outer = $funcReplace($regs, $values, $outer);
576
 
577
            if ($this->removeUnknownVariables) {
578
                $outer = preg_replace($this->removeVariablesRegExp, "", $outer);
579
            }
580
        }
581
 
582
        if ($empty) {
583
            if (!$this->removeEmptyBlocks) {
584
                $this->blockdata[$block ].= $outer;
585
            } else {
586
                if (isset($this->touchedBlocks[$block])) {
587
                    $this->blockdata[$block] .= $outer;
588
                    unset($this->touchedBlocks[$block]);
589
                }
590
            }
591
        } else {
592
            $this->blockdata[$block] .= $outer;
593
        }
594
 
595
        return $empty;
596
    } // end func parse
597
 
598
    /**
599
     * Parses the current block
600
     * @see      parse(), setCurrentBlock(), $currentBlock
601
     * @access   public
602
     */
603
    function parseCurrentBlock()
604
    {
605
        return $this->parse($this->currentBlock);
606
    } // end func parseCurrentBlock
607
 
608
    /**
609
     * Sets a variable value.
610
     *
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().
614
     *
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
618
     *                     is an array.
619
     * @param    string    prefix for variable names
620
     * @access   public
621
     */
622
    function setVariable($variable, $value = '')
623
    {
624
        if (is_array($variable)) {
625
            $this->variableCache = array_merge(
626
                                            $this->variableCache, $variable
627
                                    );
628
        } else {
629
            $this->variableCache[$variable] = $value;
630
        }
631
    } // end func setVariable
632
 
633
    /**
634
     * Sets the name of the current block that is the block where variables
635
     * are added.
636
     *
637
     * @param    string      name of the block
638
     * @return   boolean     false on failure, otherwise true
639
     * @throws   PEAR_Error
640
     * @access   public
641
     */
642
    function setCurrentBlock($block = '__global__')
643
    {
644
 
645
        if (!isset($this->blocklist[$block])) {
646
            return PEAR::raiseError(
647
                $this->errorMessage( IT_BLOCK_NOT_FOUND ) .
648
                '"' . $block . "'", IT_BLOCK_NOT_FOUND
649
            );
650
        }
651
 
652
        $this->currentBlock = $block;
653
 
654
        return true;
655
    } // end func setCurrentBlock
656
 
657
    /**
658
     * Preserves an empty block even if removeEmptyBlocks is true.
659
     *
660
     * @param    string      name of the block
661
     * @return   boolean     false on false, otherwise true
662
     * @throws   PEAR_Error
663
     * @access   public
664
     * @see      $removeEmptyBlocks
665
     */
666
    function touchBlock($block)
667
    {
668
        if (!isset($this->blocklist[$block])) {
669
            return PEAR::raiseError(
670
                $this->errorMessage(IT_BLOCK_NOT_FOUND) .
671
                '"' . $block . "'", IT_BLOCK_NOT_FOUND);
672
        }
673
 
674
        $this->touchedBlocks[$block] = true;
675
 
676
        return true;
677
    } // end func touchBlock
678
 
679
    /**
680
     * Clears all datafields of the object and rebuild the internal blocklist
681
     *
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.
685
     *
686
     * @access   public
687
     * @see      free()
688
     */
689
    function init()
690
    {
691
        $this->free();
692
        $this->findBlocks($this->template);
693
        // we don't need it any more
694
        $this->template = '';
695
        $this->buildBlockvariablelist();
696
    } // end func init
697
 
698
    /**
699
     * Clears all datafields of the object.
700
     *
701
     * Don't use this function unless you know what you're doing.
702
     *
703
     * @access   public
704
     * @see      init()
705
     */
706
    function free()
707
    {
708
        $this->err = array();
709
 
710
        $this->currentBlock = '__global__';
711
 
712
        $this->variableCache    = array();
713
        $this->blocklookup      = array();
714
        $this->touchedBlocks    = array();
715
 
716
        $this->flagBlocktrouble = false;
717
        $this->flagGlobalParsed = false;
718
    } // end func free
719
 
720
    /**
721
     * Sets the template.
722
     *
723
     * You can eighter load a template file from disk with
724
     * LoadTemplatefile() or set the template manually using this function.
725
     *
726
     * @param        string      template content
727
     * @param        boolean     remove unknown/unused variables?
728
     * @param        boolean     remove empty blocks?
729
     * @see          LoadTemplatefile(), $template
730
     * @access       public
731
     */
732
    function setTemplate( $template, $removeUnknownVariables = true,
733
                          $removeEmptyBlocks = true)
734
    {
735
        $this->removeUnknownVariables = $removeUnknownVariables;
736
        $this->removeEmptyBlocks = $removeEmptyBlocks;
737
 
738
        if ($template == '' && $this->flagCacheTemplatefile) {
739
            $this->variableCache = array();
740
            $this->blockdata = array();
741
            $this->touchedBlocks = array();
742
            $this->currentBlock = '__global__';
743
        } else {
744
            $this->template = '<!-- BEGIN __global__ -->' . $template .
745
                              '<!-- END __global__ -->';
746
            $this->init();
747
        }
748
 
749
        if ($this->flagBlocktrouble) {
750
            return false;
751
        }
752
 
753
        return true;
754
    } // end func setTemplate
755
 
756
    /**
757
     * Reads a template file from the disk.
758
     *
759
     * @param    string      name of the template file
760
     * @param    bool        how to handle unknown variables.
761
     * @param    bool        how to handle empty blocks.
762
     * @access   public
763
     * @return   boolean    false on failure, otherwise true
764
     * @see      $template, setTemplate(), $removeUnknownVariables,
765
     *           $removeEmptyBlocks
766
     */
767
    function loadTemplatefile( $filename,
768
                               $removeUnknownVariables = true,
769
                               $removeEmptyBlocks = true )
770
    {
771
        $template = '';
772
        if (!$this->flagCacheTemplatefile ||
773
            $this->lastTemplatefile != $filename
774
        ) {
775
            $template = $this->getFile($filename);
776
        }
777
        $this->lastTemplatefile = $filename;
778
 
779
        return $template != '' ?
780
                $this->setTemplate(
781
                        $template,$removeUnknownVariables, $removeEmptyBlocks
782
                    ) : false;
783
    } // end func LoadTemplatefile
784
 
785
    /**
786
     * Sets the file root. The file root gets prefixed to all filenames passed
787
     * to the object.
788
     *
789
     * Make sure that you override this function when using the class
790
     * on windows.
791
     *
792
     * @param    string
793
     * @see      IntegratedTemplate()
794
     * @access   public
795
     */
796
    function setRoot($root)
797
    {
798
        if ($root != '' && substr($root, -1) != '/') {
799
            $root .= '/';
800
        }
801
 
802
        $this->fileRoot = $root;
803
    } // end func setRoot
804
 
805
    /**
806
     * Build a list of all variables within of a block
807
     */
808
    function buildBlockvariablelist()
809
    {
810
        foreach ($this->blocklist as $name => $content) {
811
            preg_match_all($this->variablesRegExp, $content, $regs);
812
 
813
            if (count($regs[1]) != 0) {
814
                foreach ($regs[1] as $k => $var) {
815
                    $this->blockvariables[$name][$var] = true;
816
                }
817
            } else {
818
                $this->blockvariables[$name] = array();
819
            }
820
        }
821
    } // end func buildBlockvariablelist
822
 
823
    /**
824
     * Returns a list of all global variables
825
     */
826
    function getGlobalvariables()
827
    {
828
        $regs   = array();
829
        $values = array();
830
 
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]);
837
            }
838
        }
839
 
840
        return array($regs, $values);
841
    } // end func getGlobalvariables
842
 
843
    /**
844
     * Recusively builds a list of all blocks within the template.
845
     *
846
     * @param    string    string that gets scanned
847
     * @see      $blocklist
848
     */
849
    function findBlocks($string)
850
    {
851
        $blocklist = array();
852
 
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];
857
 
858
                if (isset($this->blocklist[$blockname])) {
859
                    $this->err[] = PEAR::raiseError(
860
                                            $this->errorMessage(
861
                                            IT_BLOCK_DUPLICATE, $blockname),
862
                                            IT_BLOCK_DUPLICATE
863
                                    );
864
                    $this->flagBlocktrouble = true;
865
                }
866
 
867
                $this->blocklist[$blockname] = $blockcontent;
868
                $this->blockdata[$blockname] = "";
869
 
870
                $blocklist[] = $blockname;
871
 
872
                $inner = $this->findBlocks($blockcontent);
873
                foreach ($inner as $k => $name) {
874
                    $pattern = sprintf(
875
                        '@<!--\s+BEGIN\s+%s\s+-->(.*)<!--\s+END\s+%s\s+-->@sm',
876
                        $name,
877
                        $name
878
                    );
879
 
880
                    $this->blocklist[$blockname] = preg_replace(
881
                                        $pattern,
882
                                        $this->openingDelimiter .
883
                                        '__' . $name . '__' .
884
                                        $this->closingDelimiter,
885
                                        $this->blocklist[$blockname]
886
                               );
887
                    $this->blockinner[$blockname][] = $name;
888
                    $this->blockparents[$name] = $blockname;
889
                }
890
            }
891
        }
892
 
893
        return $blocklist;
894
    } // end func findBlocks
895
 
896
    /**
897
     * Reads a file from disk and returns its content.
898
     * @param    string    Filename
899
     * @return   string    Filecontent
900
     */
901
    function getFile($filename)
902
    {
903
        if ($filename{0} == '/' && substr($this->fileRoot, -1) == '/') {
904
            $filename = substr($filename, 1);
905
        }
906
 
907
        $filename = $this->fileRoot . $filename;
908
 
909
        if (!($fh = @fopen($filename, 'r'))) {
910
            $this->err[] = PEAR::raiseError(
911
                        $this->errorMessage(IT_TPL_NOT_FOUND) .
912
                        ': "' .$filename .'"',
913
                        IT_TPL_NOT_FOUND
914
                    );
915
            return "";
916
        }
917
 
918
        $content = fread($fh, filesize($filename));
919
        fclose($fh);
920
 
921
        return preg_replace(
922
            "#<!-- INCLUDE (.*) -->#ime", "\$this->getFile('\\1')", $content
923
        );
924
    } // end func getFile
925
 
926
    /**
927
     * Adds delimiters to a string, so it can be used as a pattern
928
     * in preg_* functions
929
     *
930
     * @param string
931
     * @return string
932
     */
933
    function _addPregDelimiters($str)
934
    {
935
        return '@' . $str . '@';
936
    }
937
 
938
   /**
939
    * Replaces an opening delimiter by a special string
940
    *
941
    * @param string
942
    * @return string
943
    */
944
    function _preserveOpeningDelimiter($str)
945
    {
946
        return (false === strpos($str, $this->openingDelimiter))?
947
                $str:
948
                str_replace(
949
                    $this->openingDelimiter,
950
                    $this->openingDelimiter .
951
                    '%preserved%' . $this->closingDelimiter,
952
                    $str
953
                );
954
    }
955
 
956
    /**
957
     * Return a textual error message for a IT error code
958
     *
959
     * @param integer $value error code
960
     *
961
     * @return string error message, or false if the error code was
962
     * not recognized
963
     */
964
    function errorMessage($value, $blockname = '')
965
    {
966
        static $errorMessages;
967
        if (!isset($errorMessages)) {
968
            $errorMessages = array(
969
                IT_OK                       => '',
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 '.
977
                                               'may appear.',
978
                IT_UNKNOWN_OPTION           => 'Unknown option'
979
            );
980
        }
981
 
982
        if (PEAR::isError($value)) {
983
            $value = $value->getCode();
984
        }
985
 
986
        return isset($errorMessages[$value]) ?
987
                $errorMessages[$value] : $errorMessages[IT_ERROR];
988
    }
989
} // end class IntegratedTemplate
990
?>