2 /*=====================================================================*\
3 || ###################################################################
4 || # Blue Static ISSO Framework
5 || # Copyright ©2002-[#]year[#] Blue Static
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.
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
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 \*=====================================================================*/
23 * Database-Driven Template System (template.php)
28 require_once('ISSO/Functions.php');
31 * File-Based Template System
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:
39 * CREATE TABLE template (filename VARCHAR (250) NOT NULL, template TEXT NOT NULL, timestamp INT NOT NULL);
42 * @copyright Copyright ©2002 - [#]year[#], Blue Static
50 * The path, from the path of the application, where templates are stored
53 private $templateDir = '';
56 * The extension all the template files have
59 private $extension = 'tpl';
62 * The database table name for the template cache
65 private $dbCacheTable = null
;
68 * The name of the function phrases are fetched with
71 private $langcall = 'gettext';
74 * The name of the function phrases are sprintf() parsed with
77 private $langconst = 'sprintf';
80 * Array of pre-compiled templates that are stored to decrease server load
83 protected $cache = array();
86 * A list of the number of times each template has been used
89 protected $usage = array();
92 * A list of templates that weren't cached, but are still used
95 protected $uncached = array();
98 * Whether or not the page has been flush()'d already
101 private $doneflush = false
;
104 * The name of a function that is called before template parsing of phrases and conditionals occurs
107 private $preParseHook = ':undefined:';
109 // ###################################################################
111 * Sets the template directory name
113 * @param string Template directory name
115 public function setTemplateDirectory($dir)
117 $this->templateDir
= BSFunctions
::FetchSourcePath($dir);
120 // ###################################################################
122 * Sets the file extension for the templates
124 * @param string File extension
126 public function setExtension($ext)
128 $this->extension
= $ext;
131 // ###################################################################
133 * Sets the name of the table to access for the datbase cache
135 * @param string DB table name
137 public function setDatabaseCache($table)
139 $this->dbCacheTable
= $table;
142 // ###################################################################
144 * Sets the pre-parse hook method which is called before any other
145 * processing is done on the template.
147 * @param string Method name
149 public function setPreParseHook($hook)
151 $this->preParseHook
= $hook;
154 // ###################################################################
156 * Takes an array of template names, loads them, and then stores a
157 * parsed version for optimum speed.
159 * @param array List of template names to be cached
161 public function cache($namearray)
163 if (sizeof($this->cache
) > 0)
165 throw new Exception('You cannot cache templates more than once per initialization');
170 if ($this->dbCacheTable
)
172 $db =& BSApp
::GetType('Db');
173 $cache = $db->query("SELECT * FROM {$this->dbCacheTable} WHERE filename IN ('" . implode("', '", $namearray) . "')");
174 while ($tpl = $db->fetchArray($cache))
176 $time = filemtime($this->templateDir
. $tpl['filename'] . '.' . $this->extension
);
177 $template = $tpl['template'];
178 if ($time > $tpl['timestamp'])
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;
184 $dbCache["$tpl[filename]"] = $template;
187 foreach ($namearray AS $name)
189 if ($this->dbCacheTable
)
191 if (isset($dbCache["$name"]))
193 $template = $dbCache["$name"];
197 $template = $this->_parseTemplate($this->_loadTemplate($name));
198 $db->query("INSERT INTO {$this->dbCacheTable} (filename, template, timestamp) VALUES ('$name', '" . $db->escapeString($template) . "', " . TIMENOW
. ")");
203 $template = $this->_parseTemplate($this->_loadTemplate($name));
206 $this->cache
["$name"] = $template;
207 $this->usage
["$name"] = 0;
212 // ###################################################################
214 * Loads a template from the cache or the _load function and stores the
215 * parsed version of it
217 * @param string The name of the template
219 * @return string A parsed and loaded template
221 public function fetch($name)
223 if (isset($this->cache
["$name"]))
225 $template = $this->cache
["$name"];
229 $this->uncached
[] = $name;
230 BSApp
::Debug("Manually loading template '$name'");
231 $template = $this->_loadTemplate($name);
232 $template = $this->_parseTemplate($template);
235 if (!isset($this->usage
["$name"]))
237 $this->usage
["$name"] = 0;
240 $this->usage
["$name"]++
;
245 // ###################################################################
247 * Output a template fully compiled to the browser
249 * @param string Compiled and ready template
251 public function flush($template)
255 if (empty($template))
257 throw new Exception('There was no output to print');
260 if ($this->doneflush
)
262 throw new Exception('A template has already been sent to the output buffer');
266 if (BSApp
::GetDebug())
268 $debugBlock .= "\n<div align=\"center\">Executed in " . round(BSFunctions
::FetchMicrotimeDiff($_SERVER['REQUEST_TIME']), 10) . ' seconds</div>';
269 $debugBlock .= "\n<br /><div align=\"center\">" . BSApp
::GetDebugList() . "</div>";
273 foreach ($this->usage
AS $name => $count)
275 if (in_array($name, $this->uncached
))
277 $optlist[] = $name . '[' . $count . ']';
279 $usage[] = $name . " ($count)";
281 $sizeof = sizeof($this->uncached
);
284 $debugBlock .= "<br /><div style=\"color: red\" align=\"center\"><strong>Uncached Template(s):</strong> $sizeof ( " . implode(' ', $optlist) . " )</div>\n";
287 $debugBlock .= (sizeof($this->uncached
) < 1 ?
"<br />\n" : '') . "<div align=\"center\"><select><option>Template Usage (" . array_sum($this->usage
) . ")</option>";
288 foreach ($usage AS $tpl)
290 $debugBlock .= "<option>--- $tpl</option>";
292 $debugBlock .= "</select></div>\n";
294 if (BSApp
::GetType('Db'))
296 $queries = BSApp
::GetType('Db')->getHistory();
298 $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>';
300 foreach ($queries AS $query)
302 $debugBlock .= "\n\t<tr style=\"background-color: rgb(230, 230, 230); color: black\">";
303 $debugBlock .= "\n\t\t<td>";
304 $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>";
307 $debugBlock .= "\n</table>\n\n\n";
311 $template = str_replace('</body>', $debugBlock . '</body>', $template);
316 // ###################################################################
318 * Loads an additional template from the database
320 * @param string The name of the template
322 * @return string Template data from the database
324 protected function _loadTemplate($name)
326 $path = $this->templateDir
. $name . '.' . $this->extension
;
327 if (is_file($path) AND is_readable($path))
329 return @file_get_contents($path);
333 throw new Exception("Could not load the template '$path'");
337 // ###################################################################
339 * A wrapper for all the parsing functions and compiling functins
341 * @param string Unparsed template data
343 * @return string Parsed template data
345 protected function _parseTemplate($template)
347 $template = str_replace('"', '\"', $template);
349 if (function_exists($this->preParseHook
))
351 $template = call_user_func($this->preParseHook
, $template);
354 $template = $this->_parseBlocksAndTokens($template);
355 $template = $this->_parsePhrases($template);
356 $template = $this->_parseConditionals($template);
360 // ###################################################################
362 * Parses anything with curly braces {} (including phrases)
364 * @param string Template data
366 * @return string Parsed template data
368 private function _parseBlocksAndTokens($template)
375 for ($i = 0; $i < strlen($template); $i++
)
377 // we've run through the template and there's nothing in the stack--done
378 if ($i == strlen($template) - 1 AND sizeof($stack) == 0)
383 if ($template[$i] == '{')
385 // ignore escaped sequences
386 if ($template[$i - 1] != '\\')
388 array_push($stack, $i);
391 else if ($template[$i] == '}')
393 // there's no stack so it was probably escaped
394 if (sizeof($stack) == 0)
398 // we're good and nested
399 else if (sizeof($stack) == 1)
401 $open = array_pop($stack);
402 $token = substr($template, $open, $i - $open +
1);
403 $template = str_replace($token, $this->_parseToken($token), $template);
416 // ###################################################################
418 * Parses a curly brace token {}
420 * @param string Token
422 * @return string Parsed value
424 private function _parseToken($token)
426 // knock of the braces
427 $token = substr($token, 1, strlen($token) - 2);
430 if ($token[0] == '@' AND $token[1] == '\\' AND $token[2] == '"')
432 return '" . ' . $this->langcall
. '(\'' . str_replace(array('\\\"', "'"), array('"', "\'"), substr($token, 3, strlen($token) - 5)) . '\')' . ' . "';
437 return '" . (' . $token . ') . "';
441 // ###################################################################
443 * Prepares language and locale information inside templates
445 * @param string Template data to be processed
447 * @return string Language-ready template data
449 private function _parsePhrases($template)
451 $tagStart = '<lang ';
454 $start = -1; // start of open tag
455 $end = -1; // start of the close tag
456 $varEnd = -1; // end of the open tag
458 while ($start <= strlen($template))
461 $varMap = array(); // storage for all the substitution indices
463 // Find the start language object tag
464 $start = strpos($template, $tagStart, $end +
1);
465 if ($start === false
)
470 // look ahead to parse out all the variables
471 $i = $start +
strlen($tagStart); // current position
472 $capture = ''; // current capture
473 $capturePos = $i; // the place to start capturing
474 $varNum = -1; // variable placeholder index
475 while ($i < strlen($template))
477 if ($template[$i] == '=')
479 // backtrack to find the previous variable substitution
481 while ($backPos >= $start)
483 if ($template[$backPos] == '"')
485 // startPosition + length(startTag) + length(=\")
486 $varMap[intval($varNum)] = BSFunctions
::Substring($template, $capturePos +
3, $backPos - 1);
487 // remove our old substitution from the capture
488 $capture = BSFunctions
::Substring($template, $backPos +
1, $i);
494 // do we have a valid index?
495 if (intval($capture) > 0)
497 // set aside the index and restart capturing
504 throw new Exception('Invalid language variable index "' . $capture . '"');
507 else if ($template[$i] == '>' AND $template[$i - 1] == '"')
509 // the final variable substitution
510 $varMap[intval($varNum)] = BSFunctions
::Substring($template, $capturePos +
3, $i - 2);
515 $capture .= $template[$i];
519 // locate the end tag
520 $end = strpos($template, $tagEnd, $i);
526 // this is the string that gets variable replacement
527 $str = BSFunctions
::Substring($template, $varEnds +
1, $end);
529 // create the complete varmap
531 for ($i = max(array_keys($varMap)); $i > 0; $i--)
533 if (!isset($varMap[$i]))
535 $varMap[$i] = '<strong>[MISSING SUBSTITUTION INDEX: ' . $i . ']</strong>';
539 // put all the keys in corresponding argument order
542 // FINALLY, construct the call to sprintf()
543 $template = substr_replace($template, '" . ' . $this->langconst
. '(\'' . $str . '\', "' . implode('", "', $varMap) . '") . "', $start, ($end +
strlen($tagEnd)) - $start);
549 // ###################################################################
551 * Parser for in-line template conditionals
553 * @param string Template data awaiting processing
555 * @return string Parsed template data
557 private function _parseConditionals($template)
560 $tag_start = '<if condition=\"';
561 $tag_start_end = '\">';
562 $tag_else = '<else />';
568 // the information about the current active tag
577 if (strpos($template, $tag_start) === false
)
582 for ($i = $offset; $i < strlen($template); $i++
)
584 // we've found ourselves a conditional!
585 if (substr($template, $i, strlen($tag_start)) == $tag_start)
587 // push the position into the tag stack
590 array_push($stack, $i);
594 $tag_full['posi'] = $i;
598 else if (substr($template, $i, strlen($tag_else)) == $tag_else)
600 if (sizeof($stack) == 0 AND !isset($tag_full['else']))
602 $tag_full['else'] = $i;
605 // do we have an end tag?
606 else if (substr($template, $i, strlen($tag_end)) == $tag_end)
608 if (sizeof($stack) != 0)
614 // calculate the position of the end tag
615 $tag_full['posf'] = $i +
strlen($tag_end) - 1;
617 // extract the entire conditional from the template
618 $fullspread = substr($template, $tag_full['posi'], $tag_full['posf'] - $tag_full['posi'] +
1);
620 // remove the beginning tag
621 $conditional = substr($fullspread, strlen($tag_start));
623 // find the end of the expression
624 $temp_end = strpos($conditional, $tag_start_end);
626 // save the expression
627 $parsed[0] = stripslashes(substr($conditional, 0, $temp_end));
629 // remove the expression from the conditional
630 $conditional = substr($conditional, strlen($parsed[0]) +
strlen($tag_start_end));
632 // remove the tailing end tag
633 $conditional = substr($conditional, 0, strlen($conditional) - strlen($tag_end));
636 if (isset($tag_full['else']))
638 // now relative to the start of the <if>
639 $relpos = $tag_full['else'] - $tag_full['posi'];
641 // calculate the length of the expression and opening tag
642 $length = strlen($parsed[0]) +
strlen($tag_start) +
strlen($tag_start_end);
644 // relative to the start of iftrue
645 $elsepos = $relpos - $length;
647 $parsed[1] = substr($conditional, 0, $elsepos);
648 $parsed[2] = substr($conditional, $elsepos +
strlen($tag_else));
653 $parsed[1] = $conditional;
657 // final parsed output
658 $parsed = '" . ((' . stripslashes($parsed[0]) . ') ? "' . $parsed[1] . '" : "' . $parsed[2] . '") . "';
660 // replace the conditional
661 $template = str_replace($fullspread, $parsed, $template);
664 $offset = $tag_full['posi'] +
strlen($tag_start) +
strlen($tag_start_end);
668 unset($fullspread, $conditional, $temp_end, $relpos, $length, $elsepos);
678 // ###################################################################
680 * Debugging function used to print characters in a string that are
681 * around a certain position.
685 * @param string The haystack string
686 * @param integer Position to print around
688 function print_around($str, $pos)
690 echo '>>> PA >>>>>>>>[';
691 echo htmlspecialchars($str[ $pos - 5 ]);
692 echo htmlspecialchars($str[ $pos - 4 ]);
693 echo htmlspecialchars($str[ $pos - 3 ]);
694 echo htmlspecialchars($str[ $pos - 2 ]);
695 echo htmlspecialchars($str[ $pos - 1 ]);
697 echo htmlspecialchars($str[ $pos +
0 ]);
698 echo htmlspecialchars($str[ $pos +
1 ]);
699 echo htmlspecialchars($str[ $pos +
2 ]);
700 echo htmlspecialchars($str[ $pos +
3 ]);
701 echo htmlspecialchars($str[ $pos +
4 ]);
702 echo htmlspecialchars($str[ $pos +
5 ]);
703 echo ']<<<<<<<< PA <<<';
706 /*=====================================================================*\
707 || ###################################################################
710 || ###################################################################
711 \*=====================================================================*/