]> src.bluestatic.org Git - isso.git/blob - Template.php
Renaming BSRegister to BSApp and moving Register.php to App.php
[isso.git] / Template.php
1 <?php
2 /*=====================================================================*\
3 || ###################################################################
4 || # Blue Static ISSO Framework
5 || # Copyright ©2002-[#]year[#] Blue Static
6 || #
7 || # This program is free software; you can redistribute it and/or modify
8 || # it under the terms of the GNU General Public License as published by
9 || # the Free Software Foundation; version [#]gpl[#] of the License.
10 || #
11 || # This program is distributed in the hope that it will be useful, but
12 || # WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 || # or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
14 || # more details.
15 || #
16 || # You should have received a copy of the GNU General Public License along
17 || # with this program; if not, write to the Free Software Foundation, Inc.,
18 || # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
19 || ###################################################################
20 \*=====================================================================*/
21
22 /**
23 * Database-Driven Template System (template.php)
24 *
25 * @package ISSO
26 */
27
28 require_once('ISSO/Functions.php');
29
30 /**
31 * File-Based Template System
32 *
33 * This framework merely replaces the template loading functions with
34 * file-system based ones. It has an optional caching system in which
35 * template data will remain stored in the database as long as the filesystem
36 * file is modified. To do this, pass a table name to setDatabaseCache() and make sure
37 * there's a DB module that has access to a table with this schema:
38 *
39 * CREATE TABLE template (filename VARCHAR (250) NOT NULL, template TEXT NOT NULL, timestamp INT NOT NULL);
40 *
41 * @author Blue Static
42 * @copyright Copyright ©2002 - [#]year[#], Blue Static
43 * @version $Revision$
44 * @package ISSO
45 *
46 */
47 class BSTemplate
48 {
49 /**
50 * The path, from the path of the application, where templates are stored
51 * @var string
52 */
53 private $templateDir = '';
54
55 /**
56 * The extension all the template files have
57 * @var string
58 */
59 private $extension = 'tpl';
60
61 /**
62 * The database table name for the template cache
63 * @var string
64 */
65 private $dbCacheTable = null;
66
67 /**
68 * The name of the function phrases are fetched with
69 * @var string
70 */
71 private $langcall = 'gettext';
72
73 /**
74 * The name of the function phrases are sprintf() parsed with
75 * @var string
76 */
77 private $langconst = 'sprintf';
78
79 /**
80 * Array of pre-compiled templates that are stored to decrease server load
81 * @var array
82 */
83 protected $cache = array();
84
85 /**
86 * A list of the number of times each template has been used
87 * @var array
88 */
89 protected $usage = array();
90
91 /**
92 * A list of templates that weren't cached, but are still used
93 * @var array
94 */
95 protected $uncached = array();
96
97 /**
98 * Whether or not the page has been flush()'d already
99 * @var bool
100 */
101 private $doneflush = false;
102
103 /**
104 * The name of a function that is called before template parsing of phrases and conditionals occurs
105 * @var string
106 */
107 private $preParseHook = ':undefined:';
108
109 // ###################################################################
110 /**
111 * Sets the template directory name
112 *
113 * @param string Template directory name
114 */
115 public function setTemplateDirectory($dir)
116 {
117 $this->templateDir = BSFunctions::FetchSourcePath($dir);
118 }
119
120 // ###################################################################
121 /**
122 * Sets the file extension for the templates
123 *
124 * @param string File extension
125 */
126 public function setExtension($ext)
127 {
128 $this->extension = $ext;
129 }
130
131 // ###################################################################
132 /**
133 * Sets the name of the table to access for the datbase cache
134 *
135 * @param string DB table name
136 */
137 public function setDatabaseCache($table)
138 {
139 $this->dbCacheTable = $table;
140 }
141
142 // ###################################################################
143 /**
144 * Sets the pre-parse hook method which is called before any other
145 * processing is done on the template.
146 *
147 * @param string Method name
148 */
149 public function setPreParseHook($hook)
150 {
151 $this->preParseHook = $hook;
152 }
153
154 // ###################################################################
155 /**
156 * Takes an array of template names, loads them, and then stores a
157 * parsed version for optimum speed.
158 *
159 * @param array List of template names to be cached
160 */
161 public function cache($namearray)
162 {
163 if (sizeof($this->cache) > 0)
164 {
165 throw new Exception('You cannot cache templates more than once per initialization');
166 }
167 else
168 {
169 $dbCache = array();
170 if ($this->dbCacheTable)
171 {
172 $db =& BSApp::GetType('Db');
173 $cache = $db->query("SELECT * FROM {$this->dbCacheTable} WHERE filename IN ('" . implode("', '", $namearray) . "')");
174 while ($tpl = $db->fetchArray($cache))
175 {
176 $time = filemtime(BSApp::GetAppPath() . $this->templateDir . $tpl['filename'] . '.' . $this->extension);
177 $template = $tpl['template'];
178 if ($time > $tpl['timestamp'])
179 {
180 $template = $this->_parseTemplate($this->_loadTemplate($tpl['filename']));
181 $db->query("UPDATE {$this->dbCacheTable} SET template = '" . $db->escapeString($template) . "', timestamp = " . TIMENOW . " WHERE filename = '" . $tpl['filename'] . "'");
182 $tpl['template'] = $template;
183 }
184 $dbCache["$tpl[filename]"] = $template;
185 }
186 }
187 foreach ($namearray AS $name)
188 {
189 if ($this->dbCacheTable)
190 {
191 if (isset($dbCache["$name"]))
192 {
193 $template = $dbCache["$name"];
194 }
195 else
196 {
197 $template = $this->_parseTemplate($this->_loadTemplate($name));
198 $db->query("INSERT INTO {$this->dbCacheTable} (filename, template, timestamp) VALUES ('$name', '" . $db->escapeString($template) . "', " . TIMENOW . ")");
199 }
200 }
201 else
202 {
203 $template = $this->_parseTemplate($this->_loadTemplate($name));
204 }
205
206 $this->cache["$name"] = $template;
207 $this->usage["$name"] = 0;
208 }
209 }
210 }
211
212 // ###################################################################
213 /**
214 * Loads a template from the cache or the _load function and stores the
215 * parsed version of it
216 *
217 * @param string The name of the template
218 *
219 * @return string A parsed and loaded template
220 */
221 public function fetch($name)
222 {
223 if (isset($this->cache["$name"]))
224 {
225 $template = $this->cache["$name"];
226 }
227 else
228 {
229 $this->uncached[] = $name;
230 BSApp::Debug("Manually loading template '$name'");
231 $template = $this->_loadTemplate($name);
232 $template = $this->_parseTemplate($template);
233 }
234
235 if (!isset($this->usage["$name"]))
236 {
237 $this->usage["$name"] = 0;
238 }
239
240 $this->usage["$name"]++;
241
242 return $template;
243 }
244
245 // ###################################################################
246 /**
247 * Output a template fully compiled to the browser
248 *
249 * @param string Compiled and ready template
250 */
251 public function flush($template)
252 {
253 ob_start();
254
255 if (empty($template))
256 {
257 throw new Exception('There was no output to print');
258 }
259
260 if ($this->doneflush)
261 {
262 throw new Exception('A template has already been sent to the output buffer');
263 }
264
265 $debugBlock = '';
266 if (BSApp::GetDebug())
267 {
268 if (defined('SVN') AND preg_match('#^\$Id:?#', constant('SVN')))
269 {
270 $debugBlock .= preg_replace('#\$' . 'Id: (.+?) ([0-9].+?) [0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}(.+?) (.+?) \$#', "\n<br />\n" . '<div align="center"><strong>\1</strong> &mdash; r\2</div>', constant('SVN'));
271 }
272
273 if (defined('ISSO_MT_START'))
274 {
275 $debugBlock .= "\n<div align=\"center\">Executed in " . round(BSFunctions::FetchMicrotimeDiff(ISSO_MT_START), 10) . ' seconds</div>';
276 }
277
278 $debugBlock .= "\n<br /><div align=\"center\">" . BSApp::GetDebugList() . "</div>";
279
280 $optlist = array();
281 $usage = array();
282 foreach ($this->usage AS $name => $count)
283 {
284 if (in_array($name, $this->uncached))
285 {
286 $optlist[] = $name . '[' . $count . ']';
287 }
288 $usage[] = $name . " ($count)";
289 }
290 $sizeof = sizeof($this->uncached);
291 if ($sizeof > 0)
292 {
293 $debugBlock .= "<br /><div style=\"color: red\" align=\"center\"><strong>Uncached Template(s):</strong> $sizeof ( " . implode(' &nbsp; ', $optlist) . " )</div>\n";
294 }
295
296 $debugBlock .= (sizeof($this->uncached) < 1 ? "<br />\n" : '') . "<div align=\"center\"><select><option>Template Usage (" . array_sum($this->usage) . ")</option>";
297 foreach ($usage AS $tpl)
298 {
299 $debugBlock .= "<option>--- $tpl</option>";
300 }
301 $debugBlock .= "</select></div>\n";
302
303 if (BSApp::GetType('Db'))
304 {
305 $queries = BSApp::GetType('Db')->getHistory();
306
307 $debugBlock .= "<br />\n" . '<table cellpadding="4" cellspacing="1" border="0" align="center" width="30%" style="background-color: rgb(60, 60, 60); color: white">' . "\n\t" . '<tr><td><strong>Query Debug</strong></td></tr>';
308
309 foreach ($queries AS $query)
310 {
311 $debugBlock .= "\n\t<tr style=\"background-color: rgb(230, 230, 230); color: black\">";
312 $debugBlock .= "\n\t\t<td>";
313 $debugBlock .= "\n\t\t\t$query[query]\n\n\t\t\t<div style=\"font-size: 9px;\">($query[time])</div>\n<!--\n$query[trace]\n-->\n\t\t</td>\n\t</tr>";
314 }
315
316 $debugBlock .= "\n</table>\n\n\n";
317 }
318 }
319
320 $template = str_replace('</body>', $debugBlock . '</body>', $template);
321
322 print($template);
323 }
324
325 // ###################################################################
326 /**
327 * Loads an additional template from the database
328 *
329 * @param string The name of the template
330 *
331 * @return string Template data from the database
332 */
333 protected function _loadTemplate($name)
334 {
335 $path = BSApp::GetAppPath() . $this->templateDir . $name . '.' . $this->extension;
336 if (is_file($path))
337 {
338 if (($template = @file_get_contents($path)) !== false)
339 {
340 return $template;
341 }
342 else
343 {
344 throw new Exception("Could not load the template '$path'");
345 }
346 }
347 else
348 {
349 throw new Exception("Could not load the template '$path'");
350 }
351 }
352
353 // ###################################################################
354 /**
355 * A wrapper for all the parsing functions and compiling functins
356 *
357 * @param string Unparsed template data
358 *
359 * @return string Parsed template data
360 */
361 protected function _parseTemplate($template)
362 {
363 $template = str_replace('"', '\"', $template);
364
365 if (function_exists($this->preParseHook))
366 {
367 $template = call_user_func($this->preParseHook, $template);
368 }
369
370 $template = $this->_parseBlocksAndTokens($template);
371 $template = $this->_parsePhrases($template);
372 $template = $this->_parseConditionals($template);
373 return $template;
374 }
375
376 // ###################################################################
377 /**
378 * Parses anything with curly braces {} (including phrases)
379 *
380 * @param string Template data
381 *
382 * @return string Parsed template data
383 */
384 private function _parseBlocksAndTokens($template)
385 {
386 $stack = array();
387 $tokens = array();
388
389 while (1)
390 {
391 for ($i = 0; $i < strlen($template); $i++)
392 {
393 // we've run through the template and there's nothing in the stack--done
394 if ($i == strlen($template) - 1 AND sizeof($stack) == 0)
395 {
396 return $template;
397 }
398
399 if ($template[$i] == '{')
400 {
401 // ignore escaped sequences
402 if ($template[$i - 1] != '\\')
403 {
404 array_push($stack, $i);
405 }
406 }
407 else if ($template[$i] == '}')
408 {
409 // there's no stack so it was probably escaped
410 if (sizeof($stack) == 0)
411 {
412 continue;
413 }
414 // we're good and nested
415 else if (sizeof($stack) == 1)
416 {
417 $open = array_pop($stack);
418 $token = substr($template, $open, $i - $open + 1);
419 $template = str_replace($token, $this->_parseToken($token), $template);
420 break;
421 }
422 // just pop it off
423 else
424 {
425 array_pop($stack);
426 }
427 }
428 }
429 }
430 }
431
432 // ###################################################################
433 /**
434 * Parses a curly brace token {}
435 *
436 * @param string Token
437 *
438 * @return string Parsed value
439 */
440 private function _parseToken($token)
441 {
442 // knock of the braces
443 $token = substr($token, 1, strlen($token) - 2);
444
445 // language token
446 if ($token[0] == '@' AND $token[1] == '\\' AND $token[2] == '"')
447 {
448 return '" . ' . $this->langcall . '(\'' . str_replace(array('\\\"', "'"), array('"', "\'"), substr($token, 3, strlen($token) - 5)) . '\')' . ' . "';
449 }
450 // normal PHP code
451 else
452 {
453 return '" . (' . $token . ') . "';
454 }
455 }
456
457 // ###################################################################
458 /**
459 * Prepares language and locale information inside templates
460 *
461 * @param string Template data to be processed
462 *
463 * @return string Language-ready template data
464 */
465 private function _parsePhrases($template)
466 {
467 $tagStart = '<lang ';
468 $tagEnd = '</lang>';
469
470 $start = -1; // start of open tag
471 $end = -1; // start of the close tag
472 $varEnd = -1; // end of the open tag
473
474 while ($start <= strlen($template))
475 {
476 // reset
477 $varMap = array(); // storage for all the substitution indices
478
479 // Find the start language object tag
480 $start = strpos($template, $tagStart, $end + 1);
481 if ($start === false)
482 {
483 break;
484 }
485
486 // look ahead to parse out all the variables
487 $i = $start + strlen($tagStart); // current position
488 $capture = ''; // current capture
489 $capturePos = $i; // the place to start capturing
490 $varNum = -1; // variable placeholder index
491 while ($i < strlen($template))
492 {
493 if ($template[$i] == '=')
494 {
495 // backtrack to find the previous variable substitution
496 $backPos = $i;
497 while ($backPos >= $start)
498 {
499 if ($template[$backPos] == '"')
500 {
501 // startPosition + length(startTag) + length(=\")
502 $varMap[intval($varNum)] = BSFunctions::Substring($template, $capturePos + 3, $backPos - 1);
503 // remove our old substitution from the capture
504 $capture = BSFunctions::Substring($template, $backPos + 1, $i);
505 break;
506 }
507 $backPos--;
508 }
509
510 // do we have a valid index?
511 if (intval($capture) > 0)
512 {
513 // set aside the index and restart capturing
514 $varNum = $capture;
515 $capture = '';
516 $capturePos = $i;
517 }
518 else
519 {
520 throw new Exception('Invalid language variable index "' . $capture . '"');
521 }
522 }
523 else if ($template[$i] == '>' AND $template[$i - 1] == '"')
524 {
525 // the final variable substitution
526 $varMap[intval($varNum)] = BSFunctions::Substring($template, $capturePos + 3, $i - 2);
527 $varEnds = $i;
528 break;
529 }
530
531 $capture .= $template[$i];
532 $i++;
533 }
534
535 // locate the end tag
536 $end = strpos($template, $tagEnd, $i);
537 if ($end === false)
538 {
539 break;
540 }
541
542 // this is the string that gets variable replacement
543 $str = BSFunctions::Substring($template, $varEnds + 1, $end);
544
545 // create the complete varmap
546
547 for ($i = max(array_keys($varMap)); $i > 0; $i--)
548 {
549 if (!isset($varMap[$i]))
550 {
551 $varMap[$i] = '<strong>[MISSING SUBSTITUTION INDEX: ' . $i . ']</strong>';
552 }
553 }
554
555 // put all the keys in corresponding argument order
556 ksort($varMap);
557
558 // FINALLY, construct the call to sprintf()
559 $template = substr_replace($template, '" . ' . $this->langconst . '(\'' . $str . '\', "' . implode('", "', $varMap) . '") . "', $start, ($end + strlen($tagEnd)) - $start);
560 }
561
562 return $template;
563 }
564
565 // ###################################################################
566 /**
567 * Parser for in-line template conditionals
568 *
569 * @param string Template data awaiting processing
570 *
571 * @return string Parsed template data
572 */
573 private function _parseConditionals($template)
574 {
575 // tag data
576 $tag_start = '<if condition=\"';
577 $tag_start_end = '\">';
578 $tag_else = '<else />';
579 $tag_end = '</if>';
580
581 // tag stack
582 $stack = array();
583
584 // the information about the current active tag
585 $tag_full = array();
586 $parsed = array();
587
588 // start at 0
589 $offset = 0;
590
591 while (1)
592 {
593 if (strpos($template, $tag_start) === false)
594 {
595 break;
596 }
597
598 for ($i = $offset; $i < strlen($template); $i++)
599 {
600 // we've found ourselves a conditional!
601 if (substr($template, $i, strlen($tag_start)) == $tag_start)
602 {
603 // push the position into the tag stack
604 if ($tag_full)
605 {
606 array_push($stack, $i);
607 }
608 else
609 {
610 $tag_full['posi'] = $i;
611 }
612 }
613 // locate else tags
614 else if (substr($template, $i, strlen($tag_else)) == $tag_else)
615 {
616 if (sizeof($stack) == 0 AND !isset($tag_full['else']))
617 {
618 $tag_full['else'] = $i;
619 }
620 }
621 // do we have an end tag?
622 else if (substr($template, $i, strlen($tag_end)) == $tag_end)
623 {
624 if (sizeof($stack) != 0)
625 {
626 array_pop($stack);
627 continue;
628 }
629
630 // calculate the position of the end tag
631 $tag_full['posf'] = $i + strlen($tag_end) - 1;
632
633 // extract the entire conditional from the template
634 $fullspread = substr($template, $tag_full['posi'], $tag_full['posf'] - $tag_full['posi'] + 1);
635
636 // remove the beginning tag
637 $conditional = substr($fullspread, strlen($tag_start));
638
639 // find the end of the expression
640 $temp_end = strpos($conditional, $tag_start_end);
641
642 // save the expression
643 $parsed[0] = stripslashes(substr($conditional, 0, $temp_end));
644
645 // remove the expression from the conditional
646 $conditional = substr($conditional, strlen($parsed[0]) + strlen($tag_start_end));
647
648 // remove the tailing end tag
649 $conditional = substr($conditional, 0, strlen($conditional) - strlen($tag_end));
650
651 // handle the else
652 if (isset($tag_full['else']))
653 {
654 // now relative to the start of the <if>
655 $relpos = $tag_full['else'] - $tag_full['posi'];
656
657 // calculate the length of the expression and opening tag
658 $length = strlen($parsed[0]) + strlen($tag_start) + strlen($tag_start_end);
659
660 // relative to the start of iftrue
661 $elsepos = $relpos - $length;
662
663 $parsed[1] = substr($conditional, 0, $elsepos);
664 $parsed[2] = substr($conditional, $elsepos + strlen($tag_else));
665 }
666 // no else to handle
667 else
668 {
669 $parsed[1] = $conditional;
670 $parsed[2] = '';
671 }
672
673 // final parsed output
674 $parsed = '" . ((' . stripslashes($parsed[0]) . ') ? "' . $parsed[1] . '" : "' . $parsed[2] . '") . "';
675
676 // replace the conditional
677 $template = str_replace($fullspread, $parsed, $template);
678
679 // reset the parser
680 $offset = $tag_full['posi'] + strlen($tag_start) + strlen($tag_start_end);
681 $tag_full = array();
682 $stack = array();
683 $parsed = array();
684 unset($fullspread, $conditional, $temp_end, $relpos, $length, $elsepos);
685 break;
686 }
687 }
688 }
689
690 return $template;
691 }
692 }
693
694 // ###################################################################
695 /**
696 * Debugging function used to print characters in a string that are
697 * around a certain position.
698 *
699 * @access private
700 *
701 * @param string The haystack string
702 * @param integer Position to print around
703 */
704 function print_around($str, $pos)
705 {
706 echo '>>> PA >>>>>>>>[';
707 echo htmlspecialchars($str[ $pos - 5 ]);
708 echo htmlspecialchars($str[ $pos - 4 ]);
709 echo htmlspecialchars($str[ $pos - 3 ]);
710 echo htmlspecialchars($str[ $pos - 2 ]);
711 echo htmlspecialchars($str[ $pos - 1 ]);
712 echo '©';
713 echo htmlspecialchars($str[ $pos + 0 ]);
714 echo htmlspecialchars($str[ $pos + 1 ]);
715 echo htmlspecialchars($str[ $pos + 2 ]);
716 echo htmlspecialchars($str[ $pos + 3 ]);
717 echo htmlspecialchars($str[ $pos + 4 ]);
718 echo htmlspecialchars($str[ $pos + 5 ]);
719 echo ']<<<<<<<< PA <<<';
720 }
721
722 /*=====================================================================*\
723 || ###################################################################
724 || # $HeadURL$
725 || # $Id$
726 || ###################################################################
727 \*=====================================================================*/
728 ?>