From 766353fe5c40e4d62c1c28f439dd369acbe4efb6 Mon Sep 17 00:00:00 2001 From: Oleg Pudeyev Date: Mon, 11 Jun 2012 23:33:28 -0400 Subject: [PATCH] [ticket/10933] Useful documentation for template locate function PHPBB3-10933 --- phpBB/includes/template/template.php | 36 ++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/phpBB/includes/template/template.php b/phpBB/includes/template/template.php index a0fb887310..c89e6ec201 100644 --- a/phpBB/includes/template/template.php +++ b/phpBB/includes/template/template.php @@ -458,8 +458,40 @@ class phpbb_template } /** - * Locates source template path, accounting for styles tree and verifying that - * the path exists. + * 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.