diff options
| author | Oleg Pudeyev <oleg@bsdpower.com> | 2012-06-12 01:50:22 -0400 |
|---|---|---|
| committer | Oleg Pudeyev <oleg@bsdpower.com> | 2012-11-02 19:45:02 -0400 |
| commit | 7fdab9c5d7d212f206cfdd79f5ccef097070a7f5 (patch) | |
| tree | ce4788899a3d681e42d0adba505d2e0c4729cf66 /phpBB | |
| parent | bf66c47650682331454487c9db3999265f06df78 (diff) | |
| download | forums-7fdab9c5d7d212f206cfdd79f5ccef097070a7f5.tar forums-7fdab9c5d7d212f206cfdd79f5ccef097070a7f5.tar.gz forums-7fdab9c5d7d212f206cfdd79f5ccef097070a7f5.tar.bz2 forums-7fdab9c5d7d212f206cfdd79f5ccef097070a7f5.tar.xz forums-7fdab9c5d7d212f206cfdd79f5ccef097070a7f5.zip | |
[ticket/10933] Prose for get_first_file_location.
Also rewrite get_first_template_location prose a little to be
less repetitive with get_first_file_location.
PHPBB3-10933
Diffstat (limited to 'phpBB')
| -rw-r--r-- | phpBB/includes/style/resource_locator.php | 19 | ||||
| -rw-r--r-- | phpBB/includes/template/locator.php | 52 |
2 files changed, 60 insertions, 11 deletions
diff --git a/phpBB/includes/style/resource_locator.php b/phpBB/includes/style/resource_locator.php index 6181653d4e..04beddb434 100644 --- a/phpBB/includes/style/resource_locator.php +++ b/phpBB/includes/style/resource_locator.php @@ -295,19 +295,26 @@ class phpbb_style_resource_locator implements phpbb_template_locator * 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, provided different file names are - * used for different templates. - * - * Just like get_first_file_location but works on a list of templates, - * not files. + * specified in $files exists. Naturally more than one template must + * be given in $files. * - * The templates given in the first argument first are prepended with + * 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 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 |