1 files changed, 121 insertions, 64 deletions
diff --git a/phpBB/includes/style/resource_locator.php b/phpBB/includes/style/resource_locator.php
index fafa11c352..4cf767c062 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.
@@ -64,6 +64,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
 	*
 	* These paths will be searched for style files in the provided order.
@@ -94,10 +104,32 @@ class phpbb_style_resource_locator implements phpbb_template_locator
 	}
 
 	/**
-	* Sets the template filenames for handles. $filename_array
-	* should be a hash of handle => filename pairs.
+	* Sets the location of templates directory within style directories.
 	*
-	* @param array $filname_array Should be a hash of handle => filename pairs.
+	* 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 null
+	*/
+	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 null
+	*/
+	public function set_default_template_path()
+	{
+		$this->template_path = 'template/';
+	}
+
+	/**
+	* {@inheritDoc}
 	*/
 	public function set_filenames(array $filename_array)
 	{
@@ -121,14 +153,7 @@ class phpbb_style_resource_locator implements phpbb_template_locator
 	}
 
 	/**
-	* Determines the filename for a template handle.
-	*
-	* The filename comes from array used in a set_filenames call,
-	* which should have been performed prior to invoking this function.
-	* Return value is a file basename (without path).
-	*
-	* @param $handle string Template handle
-	* @return string Filename corresponding to the template handle
+	* {@inheritDoc}
 	*/
 	public function get_filename_for_handle($handle)
 	{
@@ -140,24 +165,7 @@ class phpbb_style_resource_locator implements phpbb_template_locator
 	}
 
 	/**
-	* Determines the source file path for a template handle without
-	* regard for styles tree.
-	*
-	* This function returns the path in "primary" style directory
-	* corresponding to the given template handle. That path may or
-	* may not actually exist on the filesystem. Because this function
-	* does not perform stat calls to determine whether the path it
-	* returns actually exists, it is faster than get_source_file_for_handle.
-	*
-	* Use get_source_file_for_handle to obtain the actual path that is
-	* guaranteed to exist (which might come from the parent style 
-	* directory if primary style has parent styles).
-	*
-	* This function will trigger an error if the handle was never
-	* associated with a template file via set_filenames.
-	*
-	* @param $handle string Template handle
-	* @return string Path to source file path in primary style directory
+	* {@inheritDoc}
 	*/
 	public function get_virtual_source_file_for_handle($handle)
 	{
@@ -172,23 +180,7 @@ class phpbb_style_resource_locator implements phpbb_template_locator
 	}
 
 	/**
-	* Determines the source file path for a template handle, accounting
-	* for styles tree and verifying that the path exists.
-	*
-	* This function returns the actual path that may be compiled for
-	* the specified template handle. It will trigger an error if
-	* the template handle was never associated with a template path
-	* via set_filenames or if the template file does not exist on the
-	* filesystem.
-	*
-	* Use get_virtual_source_file_for_handle to just resolve a template
-	* handle to a path without any filesystem or styles tree checks.
-	*
-	* @param string $handle Template handle (i.e. "friendly" template name)
-	* @param bool $find_all If true, each root path will be checked and function
-	*				will return array of files instead of string and will not
-	*				trigger a error if template does not exist
-	* @return string Source file path
+	* {@inheritDoc}
 	*/
 	public function get_source_file_for_handle($handle, $find_all = false)
 	{
@@ -239,23 +231,7 @@ class phpbb_style_resource_locator implements phpbb_template_locator
 	}
 
 	/**
-	* Locates source file path, accounting for styles tree and verifying that
-	* the path exists.
-	*
-	* 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.
-	*
-	* @param array $files List of files to locate.
-	* @param bool $return_default Determines what to return if file does not
-	*				exist. If true, function will return location where file is
-	*				supposed to be. If false, function will return false.
-	* @param bool $return_full_path If true, function will return full path
-	*				to file. If false, function will return file name. This
-	*				parameter can be used to check which one of set of files
-	*				is available.
-	* @return string or boolean Source file path if file exists or $return_default is
-	*				true. False if file does not exist and $return_default is false
+	* {@inheritDoc}
 	*/
 	public function get_first_file_location($files, $return_default = false, $return_full_path = true)
 	{
@@ -288,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);
+	}
 }