From 7d414d04ca80b3dc5efc7ece4c3c28123a4e7e89 Mon Sep 17 00:00:00 2001 From: Vjacheslav Trushkin Date: Wed, 14 Mar 2012 22:57:58 +0200 Subject: [feature/merging-style-components] Moving template classes to style Moving includes/template/ to includes/style/, adding template_ prefix to classes that deal only with templates PHPBB3-10632 --- phpBB/includes/style/template.php | 504 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 504 insertions(+) create mode 100644 phpBB/includes/style/template.php (limited to 'phpBB/includes/style/template.php') diff --git a/phpBB/includes/style/template.php b/phpBB/includes/style/template.php new file mode 100644 index 0000000000..bac5445511 --- /dev/null +++ b/phpBB/includes/style/template.php @@ -0,0 +1,504 @@ + $user->img('icon_contact', 'CONTACT', 'full'); +* +* More in-depth... +* yadayada +*/ + +/** +* Base Template class. +* @package phpBB3 +*/ +class phpbb_template +{ + /** + * @var phpbb_template_context Template context. + * Stores template data used during template rendering. + */ + private $context; + + /** + * @var string Path of the cache directory for the template + */ + public $cachepath = ''; + + /** + * @var string phpBB root path + */ + private $phpbb_root_path; + + /** + * @var phpEx PHP file extension + */ + private $phpEx; + + /** + * @var phpbb_config phpBB config instance + */ + private $config; + + /** + * @var user current user + */ + private $user; + + /** + * Template locator + * @var phpbb_template_locator + */ + private $locator; + + /** + * Template path provider + * @var phpbb_template_path_provider + */ + private $provider; + + /** + * Constructor. + * + * @param string $phpbb_root_path phpBB root path + * @param user $user current user + * @param phpbb_template_locator $locator template locator + * @param phpbb_template_path_provider $provider template path provider + */ + public function __construct($phpbb_root_path, $phpEx, $config, $user, phpbb_template_locator $locator, phpbb_template_path_provider_interface $provider) + { + $this->phpbb_root_path = $phpbb_root_path; + $this->phpEx = $phpEx; + $this->config = $config; + $this->user = $user; + $this->locator = $locator; + $this->provider = $provider; + } + + /** + * Set template location based on (current) user's chosen style. + */ + public function set_template() + { + $template_name = $this->user->theme['template_path']; + $fallback_name = ($this->user->theme['template_inherits_id']) ? $this->user->theme['template_inherit_path'] : false; + + return $this->set_custom_template(false, $template_name, false, $fallback_name); + } + + /** + * Defines a prefix to use for template paths in extensions + * + * @param string $ext_dir_prefix The prefix including trailing slash + * @return null + */ + public function set_ext_dir_prefix($ext_dir_prefix) + { + $this->provider->set_ext_dir_prefix($ext_dir_prefix); + } + + /** + * Set custom template location (able to use directory outside of phpBB). + * + * Note: Templates are still compiled to phpBB's cache directory. + * + * @param string $template_path Path to template directory + * @param string $template_name Name of template + * @param string $fallback_template_path Path to fallback template + * @param string $fallback_template_name Name of fallback template + */ + public function set_custom_template($template_path, $template_name, $fallback_template_path = false, $fallback_template_name = false) + { + $templates = array($template_name => $template_path); + + if ($fallback_template_name !== false) + { + $templates[$fallback_template_name] = $fallback_template_path; + } + + $this->provider->set_templates($templates, $this->phpbb_root_path); + $this->locator->set_paths($this->provider); + $this->locator->set_main_template($this->provider->get_main_template_path()); + + $this->cachepath = $this->phpbb_root_path . 'cache/tpl_' . str_replace('_', '-', $template_name) . '_'; + + $this->context = new phpbb_template_context(); + + return true; + } + + /** + * Sets the template filenames for handles. + * + * @param array $filname_array Should be a hash of handle => filename pairs. + */ + public function set_filenames(array $filename_array) + { + $this->locator->set_filenames($filename_array); + + return true; + } + + /** + * Clears all variables and blocks assigned to this template. + */ + public function destroy() + { + $this->context->clear(); + } + + /** + * Reset/empty complete block + * + * @param string $blockname Name of block to destroy + */ + public function destroy_block_vars($blockname) + { + $this->context->destroy_block_vars($blockname); + } + + /** + * Display a template for provided handle. + * + * The template will be loaded and compiled, if necessary, first. + * + * This function calls hooks. + * + * @param string $handle Handle to display + * @return bool True on success, false on failure + */ + public function display($handle) + { + $result = $this->call_hook($handle); + if ($result !== false) + { + return $result[0]; + } + + return $this->load_and_render($handle); + } + + /** + * Loads a template for $handle, compiling it if necessary, and + * renders the template. + * + * @param string $handle Template handle to render + * @return bool True on success, false on failure + */ + private function load_and_render($handle) + { + $renderer = $this->_tpl_load($handle); + + if ($renderer) + { + $renderer->render($this->context, $this->get_lang()); + return true; + } + else + { + return false; + } + } + + /** + * Calls hook if any is defined. + * + * @param string $handle Template handle being displayed. + */ + private function call_hook($handle) + { + global $phpbb_hook; + + if (!empty($phpbb_hook) && $phpbb_hook->call_hook(array(__CLASS__, __FUNCTION__), $handle, $this)) + { + if ($phpbb_hook->hook_return(array(__CLASS__, __FUNCTION__))) + { + $result = $phpbb_hook->hook_return_result(array(__CLASS__, __FUNCTION__)); + return array($result); + } + } + + return false; + } + + /** + * Obtains language array. + * This is either lang property of $user property, or if + * it is not set an empty array. + * @return array language entries + */ + public function get_lang() + { + if (isset($this->user->lang)) + { + $lang = $this->user->lang; + } + else + { + $lang = array(); + } + return $lang; + } + + /** + * Display the handle and assign the output to a template variable + * or return the compiled result. + * + * @param string $handle Handle to operate on + * @param string $template_var Template variable to assign compiled handle to + * @param bool $return_content If true return compiled handle, otherwise assign to $template_var + * @return bool|string false on failure, otherwise if $return_content is true return string of the compiled handle, otherwise return true + */ + public function assign_display($handle, $template_var = '', $return_content = true) + { + ob_start(); + $result = $this->display($handle); + $contents = ob_get_clean(); + if ($result === false) + { + return false; + } + + if ($return_content) + { + return $contents; + } + + $this->assign_var($template_var, $contents); + + return true; + } + + /** + * Obtains a template renderer for a template identified by specified + * handle. The template renderer can display the template later. + * + * Template source will first be compiled into php code. + * If template cache is writable the compiled php code will be stored + * on filesystem and template will not be subsequently recompiled. + * If template cache is not writable template source will be recompiled + * every time it is needed. DEBUG_EXTRA define and load_tplcompile + * configuration setting may be used to force templates to be always + * recompiled. + * + * Returns an object implementing phpbb_template_renderer, or null + * if template loading or compilation failed. Call render() on the + * renderer to display the template. This will result in template + * contents sent to the output stream (unless, of course, output + * buffering is in effect). + * + * @param string $handle Handle of the template to load + * @return phpbb_template_renderer Template renderer object, or null on failure + * @uses phpbb_template_compile is used to compile template source + */ + private function _tpl_load($handle) + { + $output_file = $this->_compiled_file_for_handle($handle); + + $recompile = defined('DEBUG_EXTRA') || + !file_exists($output_file) || + @filesize($output_file) === 0; + + if ($recompile || $this->config['load_tplcompile']) + { + // Set only if a recompile or an mtime check are required. + $source_file = $this->locator->get_source_file_for_handle($handle); + + if (!$recompile && @filemtime($output_file) < @filemtime($source_file)) + { + $recompile = true; + } + } + + // Recompile page if the original template is newer, otherwise load the compiled version + if (!$recompile) + { + return new phpbb_template_renderer_include($output_file, $this); + } + + $compile = new phpbb_template_compile($this->config['tpl_allow_php']); + + if ($compile->compile_file_to_file($source_file, $output_file) !== false) + { + $renderer = new phpbb_template_renderer_include($output_file, $this); + } + else if (($code = $compile->compile_file($source_file)) !== false) + { + $renderer = new phpbb_template_renderer_eval($code, $this); + } + else + { + $renderer = null; + } + + return $renderer; + } + + /** + * Determines compiled file path for handle $handle. + * + * @param string $handle Template handle (i.e. "friendly" template name) + * @return string Compiled file path + */ + private function _compiled_file_for_handle($handle) + { + $source_file = $this->locator->get_filename_for_handle($handle); + $compiled_file = $this->cachepath . str_replace('/', '.', $source_file) . '.' . $this->phpEx; + return $compiled_file; + } + + /** + * Assign key variable pairs from an array + * + * @param array $vararray A hash of variable name => value pairs + */ + public function assign_vars(array $vararray) + { + foreach ($vararray as $key => $val) + { + $this->assign_var($key, $val); + } + } + + /** + * Assign a single scalar value to a single key. + * + * Value can be a string, an integer or a boolean. + * + * @param string $varname Variable name + * @param string $varval Value to assign to variable + */ + public function assign_var($varname, $varval) + { + $this->context->assign_var($varname, $varval); + } + + /** + * Append text to the string value stored in a key. + * + * Text is appended using the string concatenation operator (.). + * + * @param string $varname Variable name + * @param string $varval Value to append to variable + */ + public function append_var($varname, $varval) + { + $this->context->append_var($varname, $varval); + } + + // Docstring is copied from phpbb_template_context method with the same name. + /** + * Assign key variable pairs from an array to a specified block + * @param string $blockname Name of block to assign $vararray to + * @param array $vararray A hash of variable name => value pairs + */ + public function assign_block_vars($blockname, array $vararray) + { + return $this->context->assign_block_vars($blockname, $vararray); + } + + // Docstring is copied from phpbb_template_context method with the same name. + /** + * Change already assigned key variable pair (one-dimensional - single loop entry) + * + * An example of how to use this function: + * {@example alter_block_array.php} + * + * @param string $blockname the blockname, for example 'loop' + * @param array $vararray the var array to insert/add or merge + * @param mixed $key Key to search for + * + * array: KEY => VALUE [the key/value pair to search for within the loop to determine the correct position] + * + * int: Position [the position to change or insert at directly given] + * + * If key is false the position is set to 0 + * If key is true the position is set to the last entry + * + * @param string $mode Mode to execute (valid modes are 'insert' and 'change') + * + * If insert, the vararray is inserted at the given position (position counting from zero). + * 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). + * + * Since counting begins by zero, inserting at the last position will result in this array: array(vararray, last positioned array) + * and inserting at position 1 will result in this array: array(first positioned array, vararray, following vars) + * + * @return bool false on error, true on success + */ + public function alter_block_array($blockname, array $vararray, $key = false, $mode = 'insert') + { + return $this->context->alter_block_array($blockname, $vararray, $key, $mode); + } + + /** + * Include a separate template. + * + * This function is marked public due to the way the template + * implementation uses it. It is actually an implementation function + * and should not be considered part of template class's public API. + * + * @param string $filename Template filename to include + * @param bool $include True to include the file, false to just load it + * @uses template_compile is used to compile uncached templates + */ + public function _tpl_include($filename, $include = true) + { + $this->locator->set_filenames(array($filename => $filename)); + + if (!$this->load_and_render($filename)) + { + // trigger_error cannot be used here, as the output already started + echo 'template->_tpl_include(): Failed including ' . htmlspecialchars($handle) . "\n"; + } + } + + /** + * Include a PHP file. + * + * If a relative path is passed in $filename, it is considered to be + * relative to board root ($phpbb_root_path). Absolute paths are + * also allowed. + * + * This function is marked public due to the way the template + * implementation uses it. It is actually an implementation function + * and should not be considered part of template class's public API. + * + * @param string $filename Path to PHP file to include + */ + public function _php_include($filename) + { + if (phpbb_is_absolute($filename)) + { + $file = $filename; + } + else + { + $file = $this->phpbb_root_path . $filename; + } + + if (!file_exists($file)) + { + // trigger_error cannot be used here, as the output already started + echo 'template->_php_include(): File ' . htmlspecialchars($file) . " does not exist\n"; + return; + } + include($file); + } +} -- cgit v1.2.1 From b7d84a586c1e253ff7075e80ab721db5c1101c9f Mon Sep 17 00:00:00 2001 From: Vjacheslav Trushkin Date: Wed, 14 Mar 2012 23:12:11 +0200 Subject: [feature/merging-style-components] Renaming template classes Changing template classes prefixes from phpbb_template to phpbb_style (for classes that will work with styles) or phpbb_style_template (for classes that are specific to templates) PHPBB3-10632 --- phpBB/includes/style/template.php | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'phpBB/includes/style/template.php') diff --git a/phpBB/includes/style/template.php b/phpBB/includes/style/template.php index bac5445511..a8c5139dd0 100644 --- a/phpBB/includes/style/template.php +++ b/phpBB/includes/style/template.php @@ -29,10 +29,10 @@ if (!defined('IN_PHPBB')) * Base Template class. * @package phpBB3 */ -class phpbb_template +class phpbb_style_template { /** - * @var phpbb_template_context Template context. + * @var phpbb_style_template_context Template context. * Stores template data used during template rendering. */ private $context; @@ -64,13 +64,13 @@ class phpbb_template /** * Template locator - * @var phpbb_template_locator + * @var phpbb_style_locator */ private $locator; /** * Template path provider - * @var phpbb_template_path_provider + * @var phpbb_style_path_provider */ private $provider; @@ -79,10 +79,10 @@ class phpbb_template * * @param string $phpbb_root_path phpBB root path * @param user $user current user - * @param phpbb_template_locator $locator template locator - * @param phpbb_template_path_provider $provider template path provider + * @param phpbb_style_locator $locator template locator + * @param phpbb_style_path_provider $provider template path provider */ - public function __construct($phpbb_root_path, $phpEx, $config, $user, phpbb_template_locator $locator, phpbb_template_path_provider_interface $provider) + public function __construct($phpbb_root_path, $phpEx, $config, $user, phpbb_style_locator $locator, phpbb_style_path_provider_interface $provider) { $this->phpbb_root_path = $phpbb_root_path; $this->phpEx = $phpEx; @@ -139,7 +139,7 @@ class phpbb_template $this->cachepath = $this->phpbb_root_path . 'cache/tpl_' . str_replace('_', '-', $template_name) . '_'; - $this->context = new phpbb_template_context(); + $this->context = new phpbb_style_template_context(); return true; } @@ -298,15 +298,15 @@ class phpbb_template * configuration setting may be used to force templates to be always * recompiled. * - * Returns an object implementing phpbb_template_renderer, or null + * Returns an object implementing phpbb_style_template_renderer, or null * if template loading or compilation failed. Call render() on the * renderer to display the template. This will result in template * contents sent to the output stream (unless, of course, output * buffering is in effect). * * @param string $handle Handle of the template to load - * @return phpbb_template_renderer Template renderer object, or null on failure - * @uses phpbb_template_compile is used to compile template source + * @return phpbb_style_template_renderer Template renderer object, or null on failure + * @uses phpbb_style_template_compile is used to compile template source */ private function _tpl_load($handle) { @@ -330,18 +330,18 @@ class phpbb_template // Recompile page if the original template is newer, otherwise load the compiled version if (!$recompile) { - return new phpbb_template_renderer_include($output_file, $this); + return new phpbb_style_template_renderer_include($output_file, $this); } - $compile = new phpbb_template_compile($this->config['tpl_allow_php']); + $compile = new phpbb_style_template_compile($this->config['tpl_allow_php']); if ($compile->compile_file_to_file($source_file, $output_file) !== false) { - $renderer = new phpbb_template_renderer_include($output_file, $this); + $renderer = new phpbb_style_template_renderer_include($output_file, $this); } else if (($code = $compile->compile_file($source_file)) !== false) { - $renderer = new phpbb_template_renderer_eval($code, $this); + $renderer = new phpbb_style_template_renderer_eval($code, $this); } else { @@ -403,7 +403,7 @@ class phpbb_template $this->context->append_var($varname, $varval); } - // Docstring is copied from phpbb_template_context method with the same name. + // Docstring is copied from phpbb_style_template_context method with the same name. /** * Assign key variable pairs from an array to a specified block * @param string $blockname Name of block to assign $vararray to @@ -414,7 +414,7 @@ class phpbb_template return $this->context->assign_block_vars($blockname, $vararray); } - // Docstring is copied from phpbb_template_context method with the same name. + // Docstring is copied from phpbb_style_template_context method with the same name. /** * Change already assigned key variable pair (one-dimensional - single loop entry) * -- cgit v1.2.1 From 234e5d6402978ba1a7cfbb3d163512657c7b87fc Mon Sep 17 00:00:00 2001 From: Vjacheslav Trushkin Date: Wed, 14 Mar 2012 23:22:02 +0200 Subject: [feature/merging-style-components] Implementing unlimited parent templates Implementing possibility of unlimited levels of parent templates. Paths are stored in style_parent_tree, entries are separated by / PHPBB3-10632 --- phpBB/includes/style/template.php | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) (limited to 'phpBB/includes/style/template.php') diff --git a/phpBB/includes/style/template.php b/phpBB/includes/style/template.php index a8c5139dd0..02fa0bd250 100644 --- a/phpBB/includes/style/template.php +++ b/phpBB/includes/style/template.php @@ -97,8 +97,8 @@ class phpbb_style_template */ public function set_template() { - $template_name = $this->user->theme['template_path']; - $fallback_name = ($this->user->theme['template_inherits_id']) ? $this->user->theme['template_inherit_path'] : false; + $template_name = $this->user->theme['style_path']; + $fallback_name = ($this->user->theme['style_parent_id']) ? array_reverse(explode('/', $this->user->theme['style_parent_tree'])) : false; return $this->set_custom_template(false, $template_name, false, $fallback_name); } @@ -121,17 +121,26 @@ class phpbb_style_template * * @param string $template_path Path to template directory * @param string $template_name Name of template - * @param string $fallback_template_path Path to fallback template - * @param string $fallback_template_name Name of fallback template + * @param string or array $fallback_template_path Path to fallback template + * @param string or array $fallback_template_name Name of fallback template */ public function set_custom_template($template_path, $template_name, $fallback_template_path = false, $fallback_template_name = false) { $templates = array($template_name => $template_path); - if ($fallback_template_name !== false) + if (is_string($fallback_template_name)) { $templates[$fallback_template_name] = $fallback_template_path; } + if (is_array($fallback_template_name)) + { + $i = 0; + foreach ($fallback_template_name as $fallback_template_name_item) + { + $templates[$fallback_template_name_item] = is_array($fallback_template_path) ? $fallback_template_path[$i] : $fallback_template_path; + $i ++; + } + } $this->provider->set_templates($templates, $this->phpbb_root_path); $this->locator->set_paths($this->provider); -- cgit v1.2.1 From 8b7c2c3c6516fd4eb606054ca3822d8a7f977282 Mon Sep 17 00:00:00 2001 From: Vjacheslav Trushkin Date: Thu, 15 Mar 2012 16:33:13 +0200 Subject: [feature/merging-style-components] Renaming style locator Renaming style locator to style resource locator PHPBB3-10632 --- phpBB/includes/style/template.php | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'phpBB/includes/style/template.php') diff --git a/phpBB/includes/style/template.php b/phpBB/includes/style/template.php index 02fa0bd250..076b9e05ea 100644 --- a/phpBB/includes/style/template.php +++ b/phpBB/includes/style/template.php @@ -64,7 +64,7 @@ class phpbb_style_template /** * Template locator - * @var phpbb_style_locator + * @var phpbb_style_resource_locator */ private $locator; @@ -79,10 +79,10 @@ class phpbb_style_template * * @param string $phpbb_root_path phpBB root path * @param user $user current user - * @param phpbb_style_locator $locator template locator + * @param phpbb_style_resource_locator $locator template locator * @param phpbb_style_path_provider $provider template path provider */ - public function __construct($phpbb_root_path, $phpEx, $config, $user, phpbb_style_locator $locator, phpbb_style_path_provider_interface $provider) + public function __construct($phpbb_root_path, $phpEx, $config, $user, phpbb_style_resource_locator $locator, phpbb_style_path_provider_interface $provider) { $this->phpbb_root_path = $phpbb_root_path; $this->phpEx = $phpEx; -- cgit v1.2.1 From 5b149e93b91ab1cb09e2e9c8c3c00312973c1c5e Mon Sep 17 00:00:00 2001 From: Vjacheslav Trushkin Date: Thu, 15 Mar 2012 21:08:41 +0200 Subject: [feature/merging-style-components] Changing template class Removing functions that are now handled by phpbb_style class, allowing to write $context, updating docblocks PHPBB3-10632 --- phpBB/includes/style/template.php | 76 ++++++--------------------------------- 1 file changed, 11 insertions(+), 65 deletions(-) (limited to 'phpBB/includes/style/template.php') diff --git a/phpBB/includes/style/template.php b/phpBB/includes/style/template.php index 076b9e05ea..21a2e821dd 100644 --- a/phpBB/includes/style/template.php +++ b/phpBB/includes/style/template.php @@ -35,7 +35,7 @@ class phpbb_style_template * @var phpbb_style_template_context Template context. * Stores template data used during template rendering. */ - private $context; + public $context; /** * @var string Path of the cache directory for the template @@ -63,7 +63,7 @@ class phpbb_style_template private $user; /** - * Template locator + * Style resource locator * @var phpbb_style_resource_locator */ private $locator; @@ -74,13 +74,19 @@ class phpbb_style_template */ private $provider; + /** + * Location of templates directory within style directories + * @var string + */ + public $template_path = 'template/'; + /** * Constructor. * * @param string $phpbb_root_path phpBB root path * @param user $user current user - * @param phpbb_style_resource_locator $locator template locator - * @param phpbb_style_path_provider $provider template path provider + * @param phpbb_style_resource_locator $locator style resource locator + * @param phpbb_style_path_provider $provider style path provider */ public function __construct($phpbb_root_path, $phpEx, $config, $user, phpbb_style_resource_locator $locator, phpbb_style_path_provider_interface $provider) { @@ -89,70 +95,10 @@ class phpbb_style_template $this->config = $config; $this->user = $user; $this->locator = $locator; + $this->template_path = $this->locator->template_path; $this->provider = $provider; } - /** - * Set template location based on (current) user's chosen style. - */ - public function set_template() - { - $template_name = $this->user->theme['style_path']; - $fallback_name = ($this->user->theme['style_parent_id']) ? array_reverse(explode('/', $this->user->theme['style_parent_tree'])) : false; - - return $this->set_custom_template(false, $template_name, false, $fallback_name); - } - - /** - * Defines a prefix to use for template paths in extensions - * - * @param string $ext_dir_prefix The prefix including trailing slash - * @return null - */ - public function set_ext_dir_prefix($ext_dir_prefix) - { - $this->provider->set_ext_dir_prefix($ext_dir_prefix); - } - - /** - * Set custom template location (able to use directory outside of phpBB). - * - * Note: Templates are still compiled to phpBB's cache directory. - * - * @param string $template_path Path to template directory - * @param string $template_name Name of template - * @param string or array $fallback_template_path Path to fallback template - * @param string or array $fallback_template_name Name of fallback template - */ - public function set_custom_template($template_path, $template_name, $fallback_template_path = false, $fallback_template_name = false) - { - $templates = array($template_name => $template_path); - - if (is_string($fallback_template_name)) - { - $templates[$fallback_template_name] = $fallback_template_path; - } - if (is_array($fallback_template_name)) - { - $i = 0; - foreach ($fallback_template_name as $fallback_template_name_item) - { - $templates[$fallback_template_name_item] = is_array($fallback_template_path) ? $fallback_template_path[$i] : $fallback_template_path; - $i ++; - } - } - - $this->provider->set_templates($templates, $this->phpbb_root_path); - $this->locator->set_paths($this->provider); - $this->locator->set_main_template($this->provider->get_main_template_path()); - - $this->cachepath = $this->phpbb_root_path . 'cache/tpl_' . str_replace('_', '-', $template_name) . '_'; - - $this->context = new phpbb_style_template_context(); - - return true; - } - /** * Sets the template filenames for handles. * -- cgit v1.2.1