WordPress 3.8
[autoinstalls/wordpress.git] / wp-includes / template.php
1 <?php
2 /**
3  * Template loading functions.
4  *
5  * @package WordPress
6  * @subpackage Template
7  */
8
9 /**
10  * Retrieve path to a template
11  *
12  * Used to quickly retrieve the path of a template without including the file
13  * extension. It will also check the parent theme, if the file exists, with
14  * the use of {@link locate_template()}. Allows for more generic template location
15  * without the use of the other get_*_template() functions.
16  *
17  * @since 1.5.0
18  *
19  * @param string $type Filename without extension.
20  * @param array $templates An optional list of template candidates
21  * @return string Full path to file.
22  */
23 function get_query_template( $type, $templates = array() ) {
24         $type = preg_replace( '|[^a-z0-9-]+|', '', $type );
25
26         if ( empty( $templates ) )
27                 $templates = array("{$type}.php");
28
29         $template = locate_template( $templates );
30         /**
31          * Filter the path of the queried template by type.
32          *
33          * The dynamic portion of the hook name, $type, refers to the filename
34          * -- minus the extension -- of the file to load. This hook also applies
35          * to various types of files loaded as part of the Template Hierarchy.
36          *
37          * @since 1.5.0
38          *
39          * @param string $template Path to the template. @see locate_template()
40          */
41         return apply_filters( "{$type}_template", $template );
42 }
43
44 /**
45  * Retrieve path of index template in current or parent template.
46  *
47  * @since 3.0.0
48  *
49  * @return string
50  */
51 function get_index_template() {
52         return get_query_template('index');
53 }
54
55 /**
56  * Retrieve path of 404 template in current or parent template.
57  *
58  * @since 1.5.0
59  *
60  * @return string
61  */
62 function get_404_template() {
63         return get_query_template('404');
64 }
65
66 /**
67  * Retrieve path of archive template in current or parent template.
68  *
69  * @since 1.5.0
70  *
71  * @return string
72  */
73 function get_archive_template() {
74         $post_types = array_filter( (array) get_query_var( 'post_type' ) );
75
76         $templates = array();
77
78         if ( count( $post_types ) == 1 ) {
79                 $post_type = reset( $post_types );
80                 $templates[] = "archive-{$post_type}.php";
81         }
82         $templates[] = 'archive.php';
83
84         return get_query_template( 'archive', $templates );
85 }
86
87 /**
88  * Retrieve path of post type archive template in current or parent template.
89  *
90  * @since 3.7.0
91  *
92  * @return string
93  */
94 function get_post_type_archive_template() {
95         $post_type = get_query_var( 'post_type' );
96         if ( is_array( $post_type ) )
97                 $post_type = reset( $post_type );
98
99         $obj = get_post_type_object( $post_type );
100         if ( ! $obj->has_archive )
101                 return '';
102
103         return get_archive_template();
104 }
105
106 /**
107  * Retrieve path of author template in current or parent template.
108  *
109  * @since 1.5.0
110  *
111  * @return string
112  */
113 function get_author_template() {
114         $author = get_queried_object();
115
116         $templates = array();
117
118         if ( is_a( $author, 'WP_User' ) ) {
119                 $templates[] = "author-{$author->user_nicename}.php";
120                 $templates[] = "author-{$author->ID}.php";
121         }
122         $templates[] = 'author.php';
123
124         return get_query_template( 'author', $templates );
125 }
126
127 /**
128  * Retrieve path of category template in current or parent template.
129  *
130  * Works by first retrieving the current slug, for example 'category-default.php', and then
131  * trying category ID, for example 'category-1.php', and will finally fall back to category.php
132  * template, if those files don't exist.
133  *
134  * @since 1.5.0
135  * @uses apply_filters() Calls 'category_template' on file path of category template.
136  *
137  * @return string
138  */
139 function get_category_template() {
140         $category = get_queried_object();
141
142         $templates = array();
143
144         if ( ! empty( $category->slug ) ) {
145                 $templates[] = "category-{$category->slug}.php";
146                 $templates[] = "category-{$category->term_id}.php";
147         }
148         $templates[] = 'category.php';
149
150         return get_query_template( 'category', $templates );
151 }
152
153 /**
154  * Retrieve path of tag template in current or parent template.
155  *
156  * Works by first retrieving the current tag name, for example 'tag-wordpress.php', and then
157  * trying tag ID, for example 'tag-1.php', and will finally fall back to tag.php
158  * template, if those files don't exist.
159  *
160  * @since 2.3.0
161  * @uses apply_filters() Calls 'tag_template' on file path of tag template.
162  *
163  * @return string
164  */
165 function get_tag_template() {
166         $tag = get_queried_object();
167
168         $templates = array();
169
170         if ( ! empty( $tag->slug ) ) {
171                 $templates[] = "tag-{$tag->slug}.php";
172                 $templates[] = "tag-{$tag->term_id}.php";
173         }
174         $templates[] = 'tag.php';
175
176         return get_query_template( 'tag', $templates );
177 }
178
179 /**
180  * Retrieve path of taxonomy template in current or parent template.
181  *
182  * Retrieves the taxonomy and term, if term is available. The template is
183  * prepended with 'taxonomy-' and followed by both the taxonomy string and
184  * the taxonomy string followed by a dash and then followed by the term.
185  *
186  * The taxonomy and term template is checked and used first, if it exists.
187  * Second, just the taxonomy template is checked, and then finally, taxonomy.php
188  * template is used. If none of the files exist, then it will fall back on to
189  * index.php.
190  *
191  * @since 2.5.0
192  * @uses apply_filters() Calls 'taxonomy_template' filter on found path.
193  *
194  * @return string
195  */
196 function get_taxonomy_template() {
197         $term = get_queried_object();
198
199         $templates = array();
200
201         if ( ! empty( $term->slug ) ) {
202                 $taxonomy = $term->taxonomy;
203                 $templates[] = "taxonomy-$taxonomy-{$term->slug}.php";
204                 $templates[] = "taxonomy-$taxonomy.php";
205         }
206         $templates[] = 'taxonomy.php';
207
208         return get_query_template( 'taxonomy', $templates );
209 }
210
211 /**
212  * Retrieve path of date template in current or parent template.
213  *
214  * @since 1.5.0
215  *
216  * @return string
217  */
218 function get_date_template() {
219         return get_query_template('date');
220 }
221
222 /**
223  * Retrieve path of home template in current or parent template.
224  *
225  * This is the template used for the page containing the blog posts.
226  *
227  * Attempts to locate 'home.php' first before falling back to 'index.php'.
228  *
229  * @since 1.5.0
230  * @uses apply_filters() Calls 'home_template' on file path of home template.
231  *
232  * @return string
233  */
234 function get_home_template() {
235         $templates = array( 'home.php', 'index.php' );
236
237         return get_query_template( 'home', $templates );
238 }
239
240 /**
241  * Retrieve path of front-page template in current or parent template.
242  *
243  * Looks for 'front-page.php'.
244  *
245  * @since 3.0.0
246  * @uses apply_filters() Calls 'front_page_template' on file path of template.
247  *
248  * @return string
249  */
250 function get_front_page_template() {
251         $templates = array('front-page.php');
252
253         return get_query_template( 'front_page', $templates );
254 }
255
256 /**
257  * Retrieve path of page template in current or parent template.
258  *
259  * Will first look for the specifically assigned page template.
260  * Then will search for 'page-{slug}.php', followed by 'page-{id}.php',
261  * and finally 'page.php'.
262  *
263  * @since 1.5.0
264  *
265  * @return string
266  */
267 function get_page_template() {
268         $id = get_queried_object_id();
269         $template = get_page_template_slug();
270         $pagename = get_query_var('pagename');
271
272         if ( ! $pagename && $id ) {
273                 // If a static page is set as the front page, $pagename will not be set. Retrieve it from the queried object
274                 $post = get_queried_object();
275                 if ( $post )
276                         $pagename = $post->post_name;
277         }
278
279         $templates = array();
280         if ( $template && 0 === validate_file( $template ) )
281                 $templates[] = $template;
282         if ( $pagename )
283                 $templates[] = "page-$pagename.php";
284         if ( $id )
285                 $templates[] = "page-$id.php";
286         $templates[] = 'page.php';
287
288         return get_query_template( 'page', $templates );
289 }
290
291 /**
292  * Retrieve path of paged template in current or parent template.
293  *
294  * @since 1.5.0
295  *
296  * @return string
297  */
298 function get_paged_template() {
299         return get_query_template('paged');
300 }
301
302 /**
303  * Retrieve path of search template in current or parent template.
304  *
305  * @since 1.5.0
306  *
307  * @return string
308  */
309 function get_search_template() {
310         return get_query_template('search');
311 }
312
313 /**
314  * Retrieve path of single template in current or parent template.
315  *
316  * @since 1.5.0
317  *
318  * @return string
319  */
320 function get_single_template() {
321         $object = get_queried_object();
322
323         $templates = array();
324
325         if ( ! empty( $object->post_type ) )
326                 $templates[] = "single-{$object->post_type}.php";
327         $templates[] = "single.php";
328
329         return get_query_template( 'single', $templates );
330 }
331
332 /**
333  * Retrieve path of attachment template in current or parent template.
334  *
335  * The attachment path first checks if the first part of the mime type exists.
336  * The second check is for the second part of the mime type. The last check is
337  * for both types separated by an underscore. If neither are found then the file
338  * 'attachment.php' is checked and returned.
339  *
340  * Some examples for the 'text/plain' mime type are 'text.php', 'plain.php', and
341  * finally 'text_plain.php'.
342  *
343  * @since 2.0.0
344  *
345  * @return string
346  */
347 function get_attachment_template() {
348         global $posts;
349
350         if ( ! empty( $posts ) && isset( $posts[0]->post_mime_type ) ) {
351                 $type = explode( '/', $posts[0]->post_mime_type );
352
353                 if ( ! empty( $type ) ) {
354                         if ( $template = get_query_template( $type[0] ) )
355                                 return $template;
356                         elseif ( ! empty( $type[1] ) ) {
357                                 if ( $template = get_query_template( $type[1] ) )
358                                         return $template;
359                                 elseif ( $template = get_query_template( "$type[0]_$type[1]" ) )
360                                         return $template;
361                         }
362                 }
363         }
364
365         return get_query_template( 'attachment' );
366 }
367
368 /**
369  * Retrieve path of comment popup template in current or parent template.
370  *
371  * Checks for comment popup template in current template, if it exists or in the
372  * parent template.
373  *
374  * @since 1.5.0
375  * @uses apply_filters() Calls 'comments_popup_template' filter on path.
376  *
377  * @return string
378  */
379 function get_comments_popup_template() {
380         $template = get_query_template( 'comments_popup', array( 'comments-popup.php' ) );
381
382         // Backward compat code will be removed in a future release
383         if ('' == $template)
384                 $template = ABSPATH . WPINC . '/theme-compat/comments-popup.php';
385
386         return $template;
387 }
388
389 /**
390  * Retrieve the name of the highest priority template file that exists.
391  *
392  * Searches in the STYLESHEETPATH before TEMPLATEPATH so that themes which
393  * inherit from a parent theme can just overload one file.
394  *
395  * @since 2.7.0
396  *
397  * @param string|array $template_names Template file(s) to search for, in order.
398  * @param bool $load If true the template file will be loaded if it is found.
399  * @param bool $require_once Whether to require_once or require. Default true. Has no effect if $load is false.
400  * @return string The template filename if one is located.
401  */
402 function locate_template($template_names, $load = false, $require_once = true ) {
403         $located = '';
404         foreach ( (array) $template_names as $template_name ) {
405                 if ( !$template_name )
406                         continue;
407                 if ( file_exists(STYLESHEETPATH . '/' . $template_name)) {
408                         $located = STYLESHEETPATH . '/' . $template_name;
409                         break;
410                 } else if ( file_exists(TEMPLATEPATH . '/' . $template_name) ) {
411                         $located = TEMPLATEPATH . '/' . $template_name;
412                         break;
413                 }
414         }
415
416         if ( $load && '' != $located )
417                 load_template( $located, $require_once );
418
419         return $located;
420 }
421
422 /**
423  * Require the template file with WordPress environment.
424  *
425  * The globals are set up for the template file to ensure that the WordPress
426  * environment is available from within the function. The query variables are
427  * also available.
428  *
429  * @since 1.5.0
430  *
431  * @param string $_template_file Path to template file.
432  * @param bool $require_once Whether to require_once or require. Default true.
433  */
434 function load_template( $_template_file, $require_once = true ) {
435         global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;
436
437         if ( is_array( $wp_query->query_vars ) )
438                 extract( $wp_query->query_vars, EXTR_SKIP );
439
440         if ( $require_once )
441                 require_once( $_template_file );
442         else
443                 require( $_template_file );
444 }
445