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(BSApp
::GetAppPath() . $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 if (defined('SVN') AND preg_match('#^\$Id:?#', constant('SVN')))
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> — r\2</div>', constant('SVN'));
273 if (defined('ISSO_MT_START'))
275 $debugBlock .= "\n<div align=\"center\">Executed in " . round(BSFunctions
::FetchMicrotimeDiff(ISSO_MT_START
), 10) . ' seconds</div>';
278 $debugBlock .= "\n<br /><div align=\"center\">" . BSApp
::GetDebugList() . "</div>";
282 foreach ($this->usage
AS $name => $count)
284 if (in_array($name, $this->uncached
))
286 $optlist[] = $name . '[' . $count . ']';
288 $usage[] = $name . " ($count)";
290 $sizeof = sizeof($this->uncached
);
293 $debugBlock .= "<br /><div style=\"color: red\" align=\"center\"><strong>Uncached Template(s):</strong> $sizeof ( " . implode(' ', $optlist) . " )</div>\n";
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)
299 $debugBlock .= "<option>--- $tpl</option>";
301 $debugBlock .= "</select></div>\n";
303 if (BSApp
::GetType('Db'))
305 $queries = BSApp
::GetType('Db')->getHistory();
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>';
309 foreach ($queries AS $query)
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>";
316 $debugBlock .= "\n</table>\n\n\n";
320 $template = str_replace('</body>', $debugBlock . '</body>', $template);
325 // ###################################################################
327 * Loads an additional template from the database
329 * @param string The name of the template
331 * @return string Template data from the database
333 protected function _loadTemplate($name)
335 $path = BSApp
::GetAppPath() . $this->templateDir
. $name . '.' . $this->extension
;
338 if (($template = @file_get_contents($path)) !== false)
344 throw new Exception("Could not load the template '$path'");
349 throw new Exception("Could not load the template
'$path'");
353 // ###################################################################
355 * A wrapper for all the parsing functions and compiling functins
357 * @param string Unparsed template data
359 * @return string Parsed template data
361 protected function _parseTemplate($template)
363 $template = str_replace('"', '\"', $template);
365 if (function_exists($this->preParseHook))
367 $template = call_user_func($this->preParseHook, $template);
370 $template = $this->_parseBlocksAndTokens($template);
371 $template = $this->_parsePhrases($template);
372 $template = $this->_parseConditionals($template);
376 // ###################################################################
378 * Parses anything with curly braces {} (including phrases)
380 * @param string Template data
382 * @return string Parsed template data
384 private function _parseBlocksAndTokens($template)
391 for ($i = 0; $i < strlen($template); $i++)
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)
399 if ($template[$i] == '{')
401 // ignore escaped sequences
402 if ($template[$i - 1] != '\\')
404 array_push($stack, $i);
407 else if ($template[$i] == '}')
409 // there's no stack so it was probably escaped
410 if (sizeof($stack) == 0)
414 // we're good and nested
415 else if (sizeof($stack) == 1)
417 $open = array_pop($stack);
418 $token = substr($template, $open, $i - $open + 1);
419 $template = str_replace($token, $this->_parseToken($token), $template);
432 // ###################################################################
434 * Parses a curly brace token {}
436 * @param string Token
438 * @return string Parsed value
440 private function _parseToken($token)
442 // knock of the braces
443 $token = substr($token, 1, strlen($token) - 2);
446 if ($token[0] == '@' AND $token[1] == '\\' AND $token[2] == '"')
448 return '" . ' . $this->langcall . '(\'' . str_replace(array('\\\"', "'"), array('"', "\'
"), substr($token, 3, strlen($token) - 5)) . '\')' . ' . "';
453 return '" . (' . $token . ') . "';
457 // ###################################################################
459 * Prepares language and locale information inside templates
461 * @param string Template data to be processed
463 * @return string Language-ready template data
465 private function _parsePhrases($template)
467 $tagStart = '<lang
';
470 $start = -1; // start of open tag
471 $end = -1; // start of the close tag
472 $varEnd = -1; // end of the open tag
474 while ($start <= strlen($template))
477 $varMap = array(); // storage for all the substitution indices
479 // Find the start language object tag
480 $start = strpos($template, $tagStart, $end + 1);
481 if ($start === false)
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))
493 if ($template[$i] == '=')
495 // backtrack to find the previous variable substitution
497 while ($backPos >= $start)
499 if ($template[$backPos] == '"')
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);
510 // do we have a valid index?
511 if (intval($capture) > 0)
513 // set aside the index and restart capturing
520 throw new Exception('Invalid language variable index "' . $capture . '"');
523 else if ($template[$i] == '>' AND $template[$i - 1] == '"')
525 // the final variable substitution
526 $varMap[intval($varNum)] = BSFunctions::Substring($template, $capturePos + 3, $i - 2);
531 $capture .= $template[$i];
535 // locate the end tag
536 $end = strpos($template, $tagEnd, $i);
542 // this is the string that gets variable replacement
543 $str = BSFunctions::Substring($template, $varEnds + 1, $end);
545 // create the complete varmap
547 for ($i = max(array_keys($varMap)); $i > 0; $i--)
549 if (!isset($varMap[$i]))
551 $varMap[$i] = '<strong
>[MISSING SUBSTITUTION INDEX
: ' . $i . ']</strong
>';
555 // put all the keys in corresponding argument order
558 // FINALLY, construct the call to sprintf()
559 $template = substr_replace($template, '" . ' . $this->langconst . '(\'' . $str . '\', "' . implode('", "', $varMap) . '") . "', $start, ($end + strlen($tagEnd)) - $start);
565 // ###################################################################
567 * Parser for in-line template conditionals
569 * @param string Template data awaiting processing
571 * @return string Parsed template data
573 private function _parseConditionals($template)
576 $tag_start = '<if condition
=\"';
577 $tag_start_end = '\"
>';
578 $tag_else = '<else />';
584 // the information about the current active tag
593 if (strpos($template, $tag_start) === false)
598 for ($i = $offset; $i < strlen($template); $i++)
600 // we've found ourselves a conditional
!
601 if (substr($template, $i, strlen($tag_start)) == $tag_start)
603 // push the position into the tag stack
606 array_push($stack, $i);
610 $tag_full['posi'] = $i;
614 else if (substr($template, $i, strlen($tag_else)) == $tag_else)
616 if (sizeof($stack) == 0 AND !isset($tag_full['else']))
618 $tag_full['else'] = $i;
621 // do we have an end tag?
622 else if (substr($template, $i, strlen($tag_end)) == $tag_end)
624 if (sizeof($stack) != 0)
630 // calculate the position of the end tag
631 $tag_full['posf'] = $i +
strlen($tag_end) - 1;
633 // extract the entire conditional from the template
634 $fullspread = substr($template, $tag_full['posi'], $tag_full['posf'] - $tag_full['posi'] +
1);
636 // remove the beginning tag
637 $conditional = substr($fullspread, strlen($tag_start));
639 // find the end of the expression
640 $temp_end = strpos($conditional, $tag_start_end);
642 // save the expression
643 $parsed[0] = stripslashes(substr($conditional, 0, $temp_end));
645 // remove the expression from the conditional
646 $conditional = substr($conditional, strlen($parsed[0]) +
strlen($tag_start_end));
648 // remove the tailing end tag
649 $conditional = substr($conditional, 0, strlen($conditional) - strlen($tag_end));
652 if (isset($tag_full['else']))
654 // now relative to the start of the <if>
655 $relpos = $tag_full['else'] - $tag_full['posi'];
657 // calculate the length of the expression and opening tag
658 $length = strlen($parsed[0]) +
strlen($tag_start) +
strlen($tag_start_end);
660 // relative to the start of iftrue
661 $elsepos = $relpos - $length;
663 $parsed[1] = substr($conditional, 0, $elsepos);
664 $parsed[2] = substr($conditional, $elsepos +
strlen($tag_else));
669 $parsed[1] = $conditional;
673 // final parsed output
674 $parsed = '" . ((' . stripslashes($parsed[0]) . ') ? "' . $parsed[1] . '" : "' . $parsed[2] . '") . "';
676 // replace the conditional
677 $template = str_replace($fullspread, $parsed, $template);
680 $offset = $tag_full['posi'] +
strlen($tag_start) +
strlen($tag_start_end);
684 unset($fullspread, $conditional, $temp_end, $relpos, $length, $elsepos);
694 // ###################################################################
696 * Debugging function used to print characters in a string that are
697 * around a certain position.
701 * @param string The haystack string
702 * @param integer Position to print around
704 function print_around($str, $pos)
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 ]);
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 <<<';
722 /*=====================================================================*\
723 || ###################################################################
726 || ###################################################################
727 \*=====================================================================*/