friends / includes / class-gamajo-template-loader-1-4-0.php

class-gamajo-template-loader-1-4-0.php in Friends 4.1.0, at includes/class-gamajo-template-loader-1-4-0.php

247 lines 7.6 KB

Raw Download Zip

1	<?php
2	/**
3	* Template Loader for Plugins.
4	*
5	* @package Gamajo_Template_Loader
6	* @author Gary Jones
7	* @link http://github.com/GaryJones/Gamajo-Template-Loader
8	* @copyright 2013 Gary Jones
9	* @license GPL-2.0-or-later
10	* @version 1.4.0
11	*/
12
13	if ( ! class_exists( 'Gamajo_Template_Loader_1_4_0' ) ) {
14
15	/**
16	* Template loader.
17	*
18	* Originally based on functions in Easy Digital Downloads (thanks Pippin!).
19	*
20	* When using in a plugin, create a new class that extends this one and just overrides the properties.
21	*
22	* @package Gamajo_Template_Loader
23	* @author Gary Jones
24	*/
25	class Gamajo_Template_Loader_1_4_0 {
26	/**
27	* Prefix for filter names.
28	*
29	* @since 1.0.0
30	*
31	* @var string
32	*/
33	protected $filter_prefix = 'your_plugin';
34
35	/**
36	* Directory name where custom templates for this plugin should be found in the theme.
37	*
38	* For example: 'your-plugin-templates'.
39	*
40	* @since 1.0.0
41	*
42	* @var string
43	*/
44	protected $theme_template_directory = 'plugin-templates';
45
46	/**
47	* Reference to the root directory path of this plugin.
48	*
49	* Can either be a defined constant, or a relative reference from where the subclass lives.
50	*
51	* e.g. YOUR_PLUGIN_TEMPLATE or plugin_dir_path( dirname( __FILE__ ) ); etc.
52	*
53	* @since 1.0.0
54	*
55	* @var string
56	*/
57	protected $plugin_directory = 'YOUR_PLUGIN_DIR';
58
59	/**
60	* Directory name where templates are found in this plugin.
61	*
62	* Can either be a defined constant, or a relative reference from where the subclass lives.
63	*
64	* e.g. 'templates' or 'includes/templates', etc.
65	*
66	* @since 1.1.0
67	*
68	* @var string
69	*/
70	protected $plugin_template_directory = 'templates';
71
72	/**
73	* Internal use only: Store located template paths.
74	*
75	* @var array
76	*/
77	private $template_path_cache = array();
78
79	/**
80	* Retrieve a template part.
81	*
82	* @since 1.0.0
83	*
84	* @param string $slug Template slug.
85	* @param string $name Optional. Template variation name. Default null.
86	* @param array $args Optional. Variables passed to template. Default empty array.
87	* @param bool $load Optional. Whether to load template. Default true.
88	* @return string
89	*/
90	public function get_template_part( $slug, $name = null, $args = array(), $load = true ) {
91	// Execute code for this part.
92	do_action( 'get_template_part_' . $slug, $slug, $name, $args );
93	do_action( $this->filter_prefix . '_get_template_part_' . $slug, $slug, $name, $args );
94
95	// Get files names of templates, for given slug and name.
96	$templates = $this->get_template_file_names( $slug, $name, $args );
97
98	// Return the part that is found.
99	return $this->locate_template( $templates, $load, false, $args );
100	}
101
102	/**
103	* Given a slug and optional name, create the file names of templates.
104	*
105	* @since 1.0.0
106	*
107	* @param string $slug Template slug.
108	* @param string $name Template variation name.
109	* @param array $args Optional. Variables passed to template.
110	* @return array
111	*/
112	protected function get_template_file_names( $slug, $name, $args ) {
113	$templates = array();
114	if ( isset( $name ) ) {
115	$templates[] = $slug . '-' . $name . '.php';
116	}
117	$templates[] = $slug . '.php';
118
119	/**
120	* Allow template choices to be filtered.
121	*
122	* The resulting array should be in the order of most specific first, to least specific last.
123	* e.g. 0 => recipe-instructions.php, 1 => recipe.php
124	*
125	* @since 1.0.0
126	*
127	* @param array $templates Names of template files that should be looked for, for given slug and name.
128	* @param string $slug Template slug.
129	* @param string $name Template variation name.
130	*/
131	return apply_filters( $this->filter_prefix . '_get_template_part', $templates, $slug, $name, $args );
132	}
133
134	/**
135	* Retrieve the name of the highest priority template file that exists.
136	*
137	* Searches in the STYLESHEETPATH before TEMPLATEPATH so that themes which
138	* inherit from a parent theme can just overload one file. If the template is
139	* not found in either of those, it looks in the theme-compat folder last.
140	*
141	* @since 1.0.0
142	*
143	* @param string\|array $template_names Template file(s) to search for, in order.
144	* @param bool $load If true the template file will be loaded if it is found.
145	* @param bool $use_require_once Whether to require_once or require. Default true.
146	* Has no effect if $load is false.
147	* @param array $args Optional. Variables passed to template. Default empty array.
148	*
149	* @return string The template filename if one is located.
150	*/
151	public function locate_template( $template_names, $load = false, $use_require_once = true, $args = array() ) {
152
153	// Use $template_names as a cache key - either first element of array or the variable itself if it's a string.
154	$cache_key = is_array( $template_names ) ? $template_names[0] : $template_names;
155
156	// If the key is in the cache array, we've already located this file.
157	if ( isset( $this->template_path_cache[ $cache_key ] ) ) {
158	$located = $this->template_path_cache[ $cache_key ];
159	} else {
160
161	// No file found yet.
162	$located = false;
163
164	// Remove empty entries.
165	$template_names = array_filter( (array) $template_names );
166	$template_paths = $this->get_template_paths();
167
168	// Try to find a template file.
169	foreach ( $template_names as $template_name ) {
170	// Trim off any slashes from the template name.
171	$template_name = ltrim( $template_name, '/' );
172
173	// Try locating this template file by looping through the template paths.
174	foreach ( $template_paths as $template_path ) {
175	if ( file_exists( $template_path . $template_name ) ) {
176	$located = $template_path . $template_name;
177	// Store the template path in the cache.
178	$this->template_path_cache[ $cache_key ] = $located;
179	break 2;
180	}
181	}
182	}
183	}
184
185	if ( $load && $located ) {
186	global $wp_query;
187	$wp_query->query_vars['args'] = $args;
188	load_template( $located, $use_require_once, $args );
189	}
190
191	return $located;
192	}
193
194	/**
195	* Return a list of paths to check for template locations.
196	*
197	* Default is to check in a child theme (if relevant) before a parent theme, so that themes which inherit from a
198	* parent theme can just overload one file. If the template is not found in either of those, it looks in the
199	* theme-compat folder last.
200	*
201	* @since 1.0.0
202	*
203	* @return mixed\|void
204	*/
205	protected function get_template_paths() {
206	$theme_directory = trailingslashit( $this->theme_template_directory );
207
208	$file_paths = array(
209	10 => trailingslashit( get_template_directory() ) . $theme_directory,
210	100 => $this->get_templates_dir(),
211	);
212
213	// Only add this conditionally, so non-child themes don't redundantly check active theme twice.
214	if ( get_stylesheet_directory() !== get_template_directory() ) {
215	$file_paths[1] = trailingslashit( get_stylesheet_directory() ) . $theme_directory;
216	}
217
218	/**
219	* Allow ordered list of template paths to be amended.
220	*
221	* @since 1.0.0
222	*
223	* @param array $var Default is directory in child theme at index 1, parent theme at 10, and plugin at 100.
224	*/
225	$file_paths = apply_filters( $this->filter_prefix . '_template_paths', $file_paths );
226
227	// Sort the file paths based on priority.
228	ksort( $file_paths, SORT_NUMERIC );
229
230	return array_map( 'trailingslashit', $file_paths );
231	}
232
233	/**
234	* Return the path to the templates directory in this plugin.
235	*
236	* May be overridden in subclass.
237	*
238	* @since 1.0.0
239	*
240	* @return string
241	*/
242	protected function get_templates_dir() {
243	return trailingslashit( $this->plugin_directory ) . $this->plugin_template_directory;
244	}
245	}
246	}
247