diff --git a/phpBB/includes/style/resource_locator.php b/phpBB/includes/style/resource_locator.php index 8658fe4a36..04beddb434 100644 --- a/phpBB/includes/style/resource_locator.php +++ b/phpBB/includes/style/resource_locator.php @@ -44,7 +44,7 @@ class phpbb_style_resource_locator implements phpbb_template_locator * style directory, such as admin control panel templates. * @var string */ - public $template_path = 'template/'; + private $template_path; /** * Map from root index to handles to source template file paths. @@ -63,6 +63,16 @@ class phpbb_style_resource_locator implements phpbb_template_locator */ private $filenames = array(); + /** + * Constructor. + * + * Sets default template path to template/. + */ + public function __construct() + { + $this->set_default_template_path(); + } + /** * Sets the list of style paths * @@ -93,6 +103,31 @@ class phpbb_style_resource_locator implements phpbb_template_locator } } + /** + * Sets the location of templates directory within style directories. + * + * The location must be a relative path, with a trailing slash. + * Typically it is one directory level deep, e.g. "template/". + * + * @param string $template_path Relative path to templates directory within style directories + * @return void + */ + public function set_template_path($template_path) + { + $this->template_path = $template_path; + } + + /** + * Sets the location of templates directory within style directories + * to the default, which is "template/". + * + * @return void + */ + public function set_default_template_path() + { + $this->template_path = 'template/'; + } + /** * {@inheritDoc} */ @@ -229,4 +264,85 @@ class phpbb_style_resource_locator implements phpbb_template_locator // search failed return $default_result; } + + /** + * Obtains filesystem path for a template file. + * + * The simplest use is specifying a single template file as a string + * in the first argument. This template file should be a basename + * of a template file in the selected style, or its parent styles + * if template inheritance is being utilized. + * + * Note: "selected style" is whatever style the style resource locator + * is configured for. + * + * The return value then will be a path, relative to the current + * directory or absolute, to the template file in the selected style + * or its closest parent. + * + * If the selected style does not have the template file being searched, + * (and if inheritance is involved, none of the parents have it either), + * false will be returned. + * + * Specifying true for $return_default will cause the function to + * return the first path which was checked for existence in the event + * that the template file was not found, instead of false. + * This is the path in the selected style itself, not any of its + * parents. + * + * $files can be given an array of templates instead of a single + * template. When given an array, the function will try to resolve + * each template in the array to a path, and will return the first + * path that exists, or false if none exist. + * + * If $files is an array and template inheritance is involved, first + * each of the files will be checked in the selected style, then each + * of the files will be checked in the immediate parent, and so on. + * + * If $return_full_path is false, then instead of returning a usable + * path (when the template is found) only the template's basename + * will be returned. This can be used to check which of the templates + * specified in $files exists. Naturally more than one template must + * be given in $files. + * + * This function works identically to get_first_file_location except + * it operates on a list of templates, not files. Practically speaking, + * the templates given in the first argument first are prepended with + * the template path (property in this class), then given to + * get_first_file_location for the rest of the processing. + * + * Templates given to this function can be relative paths for templates + * located in subdirectories of the template directories. The paths + * should be relative to the templates directory (template/ by default). + * + * @param string or array $files List of templates to locate. If there is only + * one template, $files can be a string to make code easier to read. + * @param bool $return_default Determines what to return if template does not + * exist. If true, function will return location where template is + * supposed to be. If false, function will return false. + * @param bool $return_full_path If true, function will return full path + * to template. If false, function will return template file name. + * This parameter can be used to check which one of set of template + * files is available. + * @return string or boolean Source template path if template exists or $return_default is + * true. False if template does not exist and $return_default is false + */ + public function get_first_template_location($templates, $return_default = false, $return_full_path = true) + { + // add template path prefix + $files = array(); + if (is_string($templates)) + { + $files[] = $this->template_path . $templates; + } + else + { + foreach ($templates as $template) + { + $files[] = $this->template_path . $template; + } + } + + return $this->get_first_file_location($files, $return_default, $return_full_path); + } } diff --git a/phpBB/includes/style/style.php b/phpBB/includes/style/style.php index 36298b49ec..effd496fb9 100644 --- a/phpBB/includes/style/style.php +++ b/phpBB/includes/style/style.php @@ -110,7 +110,7 @@ class phpbb_style * * @param string $name Name of style, used for cache prefix. Examples: "admin", "prosilver" * @param array or string $paths Array of style paths, relative to current root directory - * @param string $template_path Path to templates, relative to style directory. False if path should not be changed. + * @param string $template_path Path to templates, relative to style directory. False if path should be set to default (templates/). */ public function set_custom_style($name, $paths, $template_path = false) { @@ -122,12 +122,16 @@ class phpbb_style $this->provider->set_styles($paths); $this->locator->set_paths($this->provider); - $this->template->cachepath = $this->phpbb_root_path . 'cache/tpl_' . str_replace('_', '-', $name) . '_'; - if ($template_path !== false) { - $this->template->template_path = $this->locator->template_path = $template_path; + $this->locator->set_template_path($template_path); } + else + { + $this->locator->set_default_template_path(); + } + + $this->template->cachepath = $this->phpbb_root_path . 'cache/tpl_' . str_replace('_', '-', $name) . '_'; return true; } diff --git a/phpBB/includes/template/locator.php b/phpBB/includes/template/locator.php index 01c79eec4e..42db91efb2 100644 --- a/phpBB/includes/template/locator.php +++ b/phpBB/includes/template/locator.php @@ -99,12 +99,54 @@ interface phpbb_template_locator public function get_source_file_for_handle($handle, $find_all = false); /** - * Locates source file path, accounting for styles tree and verifying that - * the path exists. + * Obtains a complete filesystem path for a file in a style. * - * Unlike previous functions, this function works without template handle - * and it can search for more than one file. If more than one file name is - * specified, it will return location of file that it finds first. + * This function traverses the style tree (selected style and + * its parents in order, if inheritance is being used) and finds + * the first file on the filesystem matching specified relative path, + * or the first of the specified paths if more than one path is given. + * + * This function can be used to determine filesystem path of any + * file under any style, with the consequence being that complete + * relative to the style directory path must be provided as an argument. + * + * In particular, this function can be used to locate templates + * and javascript files. + * + * For locating templates get_first_template_location should be used + * as it prepends the configured template path to the template basename. + * + * Note: "selected style" is whatever style the style resource locator + * is configured for. + * + * The return value then will be a path, relative to the current + * directory or absolute, to the first existing file in the selected + * style or its closest parent. + * + * If the selected style does not have the file being searched, + * (and if inheritance is involved, none of the parents have it either), + * false will be returned. + * + * Multiple files can be specified, in which case the first file in + * the list that can be found on the filesystem is returned. + * + * If multiple files are specified and inheritance is involved, + * first each of the specified files is checked in the selected style, + * then each of the specified files is checked in the immediate parent, + * etc. + * + * Specifying true for $return_default will cause the function to + * return the first path which was checked for existence in the event + * that the template file was not found, instead of false. + * This is always a path in the selected style itself, not any of its + * parents. + * + * If $return_full_path is false, then instead of returning a usable + * path (when the file is found) the file's path relative to the style + * directory will be returned. This is the same path as was given to + * the function as a parameter. This can be used to check which of the + * files specified in $files exists. Naturally this requires passing + * more than one file in $files. * * @param array $files List of files to locate. * @param bool $return_default Determines what to return if file does not diff --git a/phpBB/includes/template/template.php b/phpBB/includes/template/template.php index 8a7dc6b2f3..5396ddbfad 100644 --- a/phpBB/includes/template/template.php +++ b/phpBB/includes/template/template.php @@ -74,12 +74,6 @@ class phpbb_template */ private $locator; - /** - * Location of templates directory within style directories - * @var string - */ - public $template_path = 'template/'; - /** * Constructor. * @@ -95,7 +89,6 @@ class phpbb_template $this->config = $config; $this->user = $user; $this->locator = $locator; - $this->template_path = $this->locator->template_path; $this->context = $context; } @@ -458,74 +451,6 @@ class phpbb_template include($file); } - /** - * Obtains filesystem path for a template file. - * - * The simplest use is specifying a single template file as a string - * in the first argument. This template file should be a basename - * of a template file in the selected style, or its parent styles - * if template inheritance is being utilized. - * - * Note: "selected style" is whatever style the style resource locator - * is configured for. - * - * The return value then will be a path, relative to the current - * directory or absolute, to the template file in the selected style - * or its closest parent. - * - * If the selected style does not have the template file being searched, - * (and if inheritance is involved, none of the parents have it either), - * false will be returned. - * - * Specifying true for $return_default will cause the function to - * return the first path which was checked for existence in the event - * that the template file was not found, instead of false. - * This is the path in the selected style itself, not any of its - * parents. - * - * $files can be given an array of templates instead of a single - * template. When given an array, the function will try to resolve - * each template in the array to a path, and will return the first - * path that exists, or false if none exist. - * - * If $return_full_path is false, then instead of returning a usable - * path (when the template is found) only the template's basename - * will be returned. This can be used to check which of the templates - * specified in $files exists, provided different file names are - * used for different templates. - * - * @param string or array $files List of templates to locate. If there is only - * one template, $files can be a string to make code easier to read. - * @param bool $return_default Determines what to return if template does not - * exist. If true, function will return location where template is - * supposed to be. If false, function will return false. - * @param bool $return_full_path If true, function will return full path - * to template. If false, function will return template file name. - * This parameter can be used to check which one of set of template - * files is available. - * @return string or boolean Source template path if template exists or $return_default is - * true. False if template does not exist and $return_default is false - */ - public function locate($files, $return_default = false, $return_full_path = true) - { - // add template path prefix - $templates = array(); - if (is_string($files)) - { - $templates[] = $this->template_path . $files; - } - else - { - foreach ($files as $file) - { - $templates[] = $this->template_path . $file; - } - } - - // use resource locator to find files - return $this->locator->get_first_file_location($templates, $return_default, $return_full_path); - } - /** * Include JS file * diff --git a/tests/template/template_locate_test.php b/tests/template/template_locate_test.php index be9ae06809..851dcae8ea 100644 --- a/tests/template/template_locate_test.php +++ b/tests/template/template_locate_test.php @@ -62,7 +62,7 @@ class phpbb_template_template_locate_test extends phpbb_template_template_test_c $this->setup_engine(); // Locate template - $result = $this->template->locate($files, $return_default, $return_full_path); + $result = $this->style_resource_locator->get_first_template_location($files, $return_default, $return_full_path); $this->assertSame($expected, $result); } }