1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
<?php
/**
*
* @package phpBB3
* @copyright (c) 2011 phpBB Group
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/
/**
* @ignore
*/
if (!defined('IN_PHPBB'))
{
exit;
}
/**
* Resource locator interface.
*
* Objects implementing this interface maintain mapping from template handles
* to source template file paths and locate templates.
*
* Locates style files.
*
* Resource locator is aware of styles tree, and can return actual
* filesystem paths (i.e., the "child" style or the "parent" styles)
* depending on what files exist.
*
* Root paths stored in locator are paths to style directories. Templates are
* stored in subdirectory that $template_path points to.
*
* @package phpBB3
*/
interface phpbb_template_locator
{
/**
* Sets the template filenames for handles. $filename_array
* should be a hash of handle => filename pairs.
*
* @param array $filename_array Should be a hash of handle => filename pairs.
*/
public function set_filenames(array $filename_array);
/**
* 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
*/
public function get_filename_for_handle($handle);
/**
* 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
*/
public function get_virtual_source_file_for_handle($handle);
/**
* 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
*/
public function get_source_file_for_handle($handle, $find_all = false);
/**
* Obtains a complete filesystem path for a file in a style.
*
* 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
* 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
*/
public function get_first_file_location($files, $return_default = false, $return_full_path = true);
}
|
