phpBB/includes/classes/template.php

   1 <?php
   2 /**
   3 *
   4 * @package phpBB3
   5 * @version $Id$
   6 * @copyright (c) 2005 phpBB Group, sections (c) 2001 ispi of Lincoln Inc
   7 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
   8 *
   9 */
  10
  11 /**
  12 * @ignore
  13 */
  14 if (!defined('IN_PHPBB'))
  15 {
  16         exit;
  17 }
  18
  19 /**
  20 * @todo
  21 * IMG_ for image substitution?
  22 * {IMG_[key]:[alt]:[type]}
  23 * {IMG_ICON_CONTACT:CONTACT:full} -> phpbb::$user->img('icon_contact', 'CONTACT', 'full');
  24 *
  25 * More in-depth...
  26 * yadayada
  27 */
  28
  29 /**
  30 * Base Template class.
  31 * @package phpBB3
  32 */
  33 class phpbb_template
  34 {
  35         public $phpbb_required = array('user', 'config');
  36         public $phpbb_optional = array();
  37
  38         /**
  39         * variable that holds all the data we'll be substituting into
  40         * the compiled templates. Takes form:
  41         * --> $this->_tpldata[block][iteration#][child][iteration#][child2][iteration#][variablename] == value
  42         * if it's a root-level variable, it'll be like this:
  43         * --> $this->_tpldata[.][0][varname] == value
  44         * @var array
  45         */
  46         private $_tpldata = array('.' => array(0 => array()));
  47
  48         /**
  49         * @var array Reference to template->_tpldata['.'][0]
  50         */
  51         private $_rootref;
  52
  53         /**
  54         * @var string Root dir for template.
  55         */
  56         private $root = '';
  57
  58         /**
  59         * @var string Path of the cache directory for the template
  60         */
  61         public $cachepath = '';
  62
  63         /**
  64         * @var array Hash of handle => file path pairs
  65         */
  66         public $files = array();
  67
  68         /**
  69         * @var array Hash of handle => filename pairs
  70         */
  71         public $filename = array();
  72
  73         /**
  74         * Set template location
  75         * @access public
  76         */
  77         public function set_template()
  78         {
  79                 if (file_exists(PHPBB_ROOT_PATH . 'styles/' . phpbb::$user->theme['template_path'] . '/template'))
  80                 {
  81                         $this->root = PHPBB_ROOT_PATH . 'styles/' . phpbb::$user->theme['template_path'] . '/template';
  82                         $this->cachepath = PHPBB_ROOT_PATH . 'cache/tpl_' . phpbb::$user->theme['template_path'] . '_';
  83                 }
  84                 else
  85                 {
  86                         trigger_error('Template path could not be found: styles/' . phpbb::$user->theme['template_path'] . '/template', E_USER_ERROR);
  87                 }
  88
  89                 $this->_rootref = &$this->_tpldata['.'][0];
  90         }
  91
  92         /**
  93         * Set custom template location (able to use directory outside of phpBB)
  94         * @access public
  95         * @param string $template_path Path to template directory
  96         * @param string $template_name Name of template
  97         */
  98         public function set_custom_template($template_path, $template_name)
  99         {
 100                 $this->root = $template_path;
 101                 $this->cachepath = PHPBB_ROOT_PATH . 'cache/ctpl_' . str_replace('_', '-', $template_name) . '_';
 102         }
 103
 104         /**
 105         * Sets the template filenames for handles. $filename_array
 106         * @access public
 107         * @param array $filname_array Should be a hash of handle => filename pairs.
 108         */
 109         public function set_filenames(array $filename_array)
 110         {
 111                 foreach ($filename_array as $handle => $filename)
 112                 {
 113                         if (empty($filename))
 114                         {
 115                                 trigger_error("template->set_filenames: Empty filename specified for $handle", E_USER_ERROR);
 116                         }
 117
 118                         $this->filename[$handle] = $filename;
 119                         $this->files[$handle] = $this->root . '/' . $filename;
 120                 }
 121
 122                 return true;
 123         }
 124
 125         /**
 126         * Destroy template data set
 127         * @access public
 128         */
 129         public function __destruct()
 130         {
 131                 $this->_tpldata = array('.' => array(0 => array()));
 132         }
 133
 134         /**
 135         * Reset/empty complete block
 136         * @access public
 137         * @param string $blockname Name of block to destroy
 138         */
 139         public function destroy_block_vars($blockname)
 140         {
 141                 if (strpos($blockname, '.') !== false)
 142                 {
 143                         // Nested block.
 144                         $blocks = explode('.', $blockname);
 145                         $blockcount = sizeof($blocks) - 1;
 146
 147                         $str = &$this->_tpldata;
 148                         for ($i = 0; $i < $blockcount; $i++)
 149                         {
 150                                 $str = &$str[$blocks[$i]];
 151                                 $str = &$str[sizeof($str) - 1];
 152                         }
 153
 154                         unset($str[$blocks[$blockcount]]);
 155                 }
 156                 else
 157                 {
 158                         // Top-level block.
 159                         unset($this->_tpldata[$blockname]);
 160                 }
 161         }
 162
 163         /**
 164         * Display handle
 165         * @access public
 166         * @param string $handle Handle to display
 167         * @param bool $include_once Allow multiple inclusions
 168         * @return bool True on success, false on failure
 169         */
 170         public function display($handle, $include_once = true)
 171         {
 172 /*
 173                 if (!empty($phpbb_hook) && $phpbb_hook->call_hook(array(__CLASS__, __FUNCTION__), $handle, $include_once))
 174                 {
 175                         if ($phpbb_hook->hook_return(array(__CLASS__, __FUNCTION__)))
 176                         {
 177                                 return $phpbb_hook->hook_return_result(array(__CLASS__, __FUNCTION__));
 178                         }
 179                 }
 180 */
 181 /*              if (defined('IN_ERROR_HANDLER'))
 182                 {
 183                         if ((E_NOTICE & error_reporting()) == E_NOTICE)
 184                         {
 185                                 //error_reporting(error_reporting() ^ E_NOTICE);
 186                         }
 187                 }*/
 188
 189                 $_tpldata       = &$this->_tpldata;
 190                 $_rootref       = &$this->_rootref;
 191                 $_lang          = &phpbb::$user->lang;
 192
 193                 if (($filename = $this->_tpl_load($handle)) !== false)
 194                 {
 195                         ($include_once) ? include_once($filename) : include($filename);
 196                 }
 197                 else if (($code = $this->_tpl_eval($handle)) !== false)
 198                 {
 199                         $code = ' ?> ' . $code . ' <?php ';
 200                         eval($code);
 201                 }
 202                 else
 203                 {
 204                         // if we could not eval AND the file exists, something horrific has occured
 205                         return false;
 206                 }
 207
 208                 return true;
 209         }
 210
 211         /**
 212         * Display the handle and assign the output to a template variable or return the compiled result.
 213         * @access public
 214         * @param string $handle Handle to operate on
 215         * @param string $template_var Template variable to assign compiled handle to
 216         * @param bool $return_content If true return compiled handle, otherwise assign to $template_var
 217         * @param bool $include_once Allow multiple inclusions of the file
 218         * @return bool|string If $return_content is true return string of the compiled handle, otherwise return true
 219         */
 220         public function assign_display($handle, $template_var = '', $return_content = true, $include_once = false)
 221         {
 222                 ob_start();
 223                 $this->display($handle, $include_once);
 224                 $contents = ob_get_clean();
 225
 226                 if ($return_content)
 227                 {
 228                         return $contents;
 229                 }
 230
 231                 $this->assign_var($template_var, $contents);
 232
 233                 return true;
 234         }
 235
 236         /**
 237         * Load a compiled template if possible, if not, recompile it
 238         * @access private
 239         * @param string $handle Handle of the template to load
 240         * @return string|bool Return filename on success otherwise false
 241         * @uses template_compile is used to compile uncached templates
 242         */
 243         private function _tpl_load($handle)
 244         {
 245                 if (!isset($this->filename[$handle]))
 246                 {
 247                         trigger_error("template->_tpl_load(): No file specified for handle $handle", E_USER_ERROR);
 248                 }
 249
 250                 $filename = $this->cachepath . str_replace('/', '.', $this->filename[$handle]) . '.' . PHP_EXT;
 251
 252                 $recompile = (!file_exists($filename) || @filesize($filename) === 0 || (phpbb::$config['load_tplcompile'] && @filemtime($filename) < filemtime($this->files[$handle]))) ? true : false;
 253
 254                 if (phpbb::$base_config['debug_extra'])
 255                 {
 256                         $recompile = true;
 257                 }
 258
 259                 // Recompile page if the original template is newer, otherwise load the compiled version
 260                 if ($recompile)
 261                 {
 262                         $compile = new phpbb_template_compile($this);
 263
 264                         // If we don't have a file assigned to this handle, die.
 265                         if (!isset($this->files[$handle]))
 266                         {
 267                                 trigger_error("template->_tpl_load(): No file specified for handle $handle", E_USER_ERROR);
 268                         }
 269
 270                         if ($compile->_tpl_load_file($handle) === false)
 271                         {
 272                                 return false;
 273                         }
 274                 }
 275
 276                 return $filename;
 277         }
 278
 279         /**
 280         * This code should only run when some high level error prevents us from writing to the cache.
 281         * @access private
 282         * @param string $handle Template handle to compile
 283         * @return string|bool Return compiled code on success otherwise false
 284         * @uses template_compile is used to compile template
 285         */
 286         private function _tpl_eval($handle)
 287         {
 288                 $compile = new phpbb_template_compile($this);
 289
 290                 // If we don't have a file assigned to this handle, die.
 291                 if (!isset($this->files[$handle]))
 292                 {
 293                         trigger_error("template->_tpl_eval(): No file specified for handle $handle", E_USER_ERROR);
 294                 }
 295
 296                 if (($code = $compile->_tpl_gen_src($handle)) === false)
 297                 {
 298                         return false;
 299                 }
 300
 301                 return $code;
 302         }
 303
 304         /**
 305         * Assign key variable pairs from an array
 306         * @access public
 307         * @param array $vararray A hash of variable name => value pairs
 308         */
 309         public function assign_vars(array $vararray)
 310         {
 311                 foreach ($vararray as $key => $val)
 312                 {
 313                         $this->_rootref[$key] = $val;
 314                 }
 315         }
 316
 317         /**
 318         * Assign a single variable to a single key
 319         * @access public
 320         * @param string $varname Variable name
 321         * @param string $varval Value to assign to variable
 322         */
 323         public function assign_var($varname, $varval)
 324         {
 325                 $this->_rootref[$varname] = $varval;
 326         }
 327
 328         /**
 329         * Assign key variable pairs from an array to a specified block
 330         * @access public
 331         * @param string $blockname Name of block to assign $vararray to
 332         * @param array $vararray A hash of variable name => value pairs
 333         */
 334         public function assign_block_vars($blockname, array $vararray)
 335         {
 336                 if (strpos($blockname, '.') !== false)
 337                 {
 338                         // Nested block.
 339                         $blocks = explode('.', $blockname);
 340                         $blockcount = sizeof($blocks) - 1;
 341
 342                         $str = &$this->_tpldata;
 343                         for ($i = 0; $i < $blockcount; $i++)
 344                         {
 345                                 $str = &$str[$blocks[$i]];
 346                                 $str = &$str[sizeof($str) - 1];
 347                         }
 348
 349                         // Now we add the block that we're actually assigning to.
 350                         // We're adding a new iteration to this block with the given
 351                         // variable assignments.
 352                         $str[$blocks[$blockcount]][] = $vararray;
 353                 }
 354                 else
 355                 {
 356                         // Top-level block.
 357
 358                         // Add a new iteration to this block with the variable assignments we were given.
 359                         $this->_tpldata[$blockname][] = $vararray;
 360                 }
 361         }
 362
 363         /**
 364         * Change already assigned key variable pair (one-dimensional - single loop entry)
 365         *
 366         * An example of how to use this function:
 367         *
 368         * @param        string  $blockname      the blockname, for example 'loop'
 369         * @param        array   $vararray       the var array to insert/add or merge
 370         * @param        mixed   $key            Key to search for
 371         *
 372         * array: KEY => VALUE [the key/value pair to search for within the loop to determine the correct position]
 373         *
 374         * int: Position [the position to change or insert at directly given]
 375         *
 376         * If key is false the position is set to 0
 377         * If key is true the position is set to the last entry
 378         *
 379         * @param        string  $mode           Mode to execute (valid modes are 'insert' and 'change')
 380         *
 381         *       If insert, the vararray is inserted at the given position (position counting from zero).
 382         *       If change, the current block gets merged with the vararray (resulting in new key/value pairs be added and existing keys be replaced by the new value).
 383         *
 384         * Since counting begins by zero, inserting at the last position will result in this array: array(vararray, last positioned array)
 385         * and inserting at position 1 will result in this array: array(first positioned array, vararray, following vars)
 386         *
 387         * @return bool false on error, true on success
 388         * @access public
 389         */
 390         public function alter_block_array($blockname, array $vararray, $key = false, $mode = 'insert')
 391         {
 392                 if (strpos($blockname, '.') !== false)
 393                 {
 394                         // Nested block.
 395                         $blocks = explode('.', $blockname);
 396                         $blockcount = sizeof($blocks) - 1;
 397
 398                         $block = &$this->_tpldata;
 399                         for ($i = 0; $i < $blockcount; $i++)
 400                         {
 401                                 if (($pos = strpos($blocks[$i], '[')) !== false)
 402                                 {
 403                                         $name = substr($blocks[$i], 0, $pos);
 404
 405                                         if (strpos($blocks[$i], '[]') === $pos)
 406                                         {
 407                                                 $index = sizeof($block[$name]) - 1;
 408                                         }
 409                                         else
 410                                         {
 411                                                 $index = min((int) substr($blocks[$i], $pos + 1, -1), sizeof($block[$name]) - 1);
 412                                         }
 413                                 }
 414                                 else
 415                                 {
 416                                         $name = $blocks[$i];
 417                                         $index = sizeof($block[$name]) - 1;
 418                                 }
 419                                 $block = &$block[$name];
 420                                 $block = &$block[$index];
 421                         }
 422
 423                         $block = &$block[$blocks[$i]]; // Traverse the last block
 424                 }
 425                 else
 426                 {
 427                         // Top-level block.
 428                         $block = &$this->_tpldata[$blockname];
 429                 }
 430
 431                 // Change key to zero (change first position) if false and to last position if true
 432                 if ($key === false || $key === true)
 433                 {
 434                         $key = ($key === false) ? 0 : sizeof($block);
 435                 }
 436
 437                 // Get correct position if array given
 438                 if (is_array($key))
 439                 {
 440                         // Search array to get correct position
 441                         list($search_key, $search_value) = @each($key);
 442
 443                         $key = NULL;
 444                         foreach ($block as $i => $val_ary)
 445                         {
 446                                 if ($val_ary[$search_key] === $search_value)
 447                                 {
 448                                         $key = $i;
 449                                         break;
 450                                 }
 451                         }
 452
 453                         // key/value pair not found
 454                         if ($key === NULL)
 455                         {
 456                                 return false;
 457                         }
 458                 }
 459
 460                 // Insert Block
 461                 if ($mode == 'insert')
 462                 {
 463                         // Re-position template blocks
 464                         for ($i = sizeof($block); $i > $key; $i--)
 465                         {
 466                                 $block[$i] = $block[$i-1];
 467                         }
 468
 469                         // Insert vararray at given position
 470                         $block[$key] = $vararray;
 471
 472                         return true;
 473                 }
 474
 475                 // Which block to change?
 476                 if ($mode == 'change')
 477                 {
 478                         if ($key == sizeof($block))
 479                         {
 480                                 $key--;
 481                         }
 482
 483                         $block[$key] = array_merge($block[$key], $vararray);
 484
 485                         return true;
 486                 }
 487
 488                 return false;
 489         }
 490
 491         /**
 492         * Include a separate template
 493         * @access private
 494         * @param string $filename Template filename to include
 495         * @param bool $include True to include the file, false to just load it
 496         * @uses template_compile is used to compile uncached templates
 497         */
 498         private function _tpl_include($filename, $include = true)
 499         {
 500                 $handle = $filename;
 501                 $this->filename[$handle] = $filename;
 502                 $this->files[$handle] = $this->root . '/' . $filename;
 503
 504                 $filename = $this->_tpl_load($handle);
 505
 506                 if ($include)
 507                 {
 508                         $_tpldata       = &$this->_tpldata;
 509                         $_rootref       = &$this->_rootref;
 510                         $_lang          = &phpbb::$user->lang;
 511
 512                         if ($filename)
 513                         {
 514                                 include($filename);
 515                                 return;
 516                         }
 517                         else
 518                         {
 519                                 $compile = new phpbb_template_compile($this);
 520
 521                                 if (($code = $compile->_tpl_gen_src($handle)) !== false)
 522                                 {
 523                                         $code = ' ?> ' . $code . ' <?php ';
 524                                         eval($code);
 525                                 }
 526                         }
 527                 }
 528         }
 529 }
 530
 531 ?>