WordPress 4.3
[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 template 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         /**
32          * Filter the path of the queried template by type.
33          *
34          * The dynamic portion of the hook name, `$type`, refers to the filename -- minus the file
35          * extension and any non-alphanumeric characters delimiting words -- of the file to load.
36          * This hook also applies to various types of files loaded as part of the Template Hierarchy.
37          *
38          * @since 1.5.0
39          *
40          * @param string $template Path to the template. See locate_template().
41          */
42         return apply_filters( "{$type}_template", $template );
43 }
44
45 /**
46  * Retrieve path of index template in current or parent template.
47  *
48  * The template path is filterable via the dynamic {@see '$type_template'} hook,
49  * e.g. 'index_template'.
50  *
51  * @since 3.0.0
52  *
53  * @see get_query_template()
54  *
55  * @return string Full path to index template file.
56  */
57 function get_index_template() {
58         return get_query_template('index');
59 }
60
61 /**
62  * Retrieve path of 404 template in current or parent template.
63  *
64  * The template path is filterable via the dynamic {@see '$type_template'} hook,
65  * e.g. '404_template'.
66  *
67  * @since 1.5.0
68  *
69  * @see get_query_template()
70  *
71  * @return string Full path to 404 template file.
72  */
73 function get_404_template() {
74         return get_query_template('404');
75 }
76
77 /**
78  * Retrieve path of archive template in current or parent template.
79  *
80  * The template path is filterable via the dynamic {@see '$type_template'} hook,
81  * e.g. 'archive_template'.
82  *
83  * @since 1.5.0
84  *
85  * @see get_query_template()
86  *
87  * @return string Full path to archive template file.
88  */
89 function get_archive_template() {
90         $post_types = array_filter( (array) get_query_var( 'post_type' ) );
91
92         $templates = array();
93
94         if ( count( $post_types ) == 1 ) {
95                 $post_type = reset( $post_types );
96                 $templates[] = "archive-{$post_type}.php";
97         }
98         $templates[] = 'archive.php';
99
100         return get_query_template( 'archive', $templates );
101 }
102
103 /**
104  * Retrieve path of post type archive template in current or parent template.
105  *
106  * The template path is filterable via the dynamic {@see '$type_template'} hook,
107  * e.g. 'archive_template'.
108  *
109  * @since 3.7.0
110  *
111  * @see get_archive_template()
112  *
113  * @return string Full path to archive template file.
114  */
115 function get_post_type_archive_template() {
116         $post_type = get_query_var( 'post_type' );
117         if ( is_array( $post_type ) )
118                 $post_type = reset( $post_type );
119
120         $obj = get_post_type_object( $post_type );
121         if ( ! $obj->has_archive )
122                 return '';
123
124         return get_archive_template();
125 }
126
127 /**
128  * Retrieve path of author template in current or parent template.
129  *
130  * The template path is filterable via the dynamic {@see '$type_template'} hook,
131  * e.g. 'author_template'.
132  *
133  * @since 1.5.0
134  *
135  * @see get_query_template()
136  *
137  * @return string Full path to author template file.
138  */
139 function get_author_template() {
140         $author = get_queried_object();
141
142         $templates = array();
143
144         if ( $author instanceof WP_User ) {
145                 $templates[] = "author-{$author->user_nicename}.php";
146                 $templates[] = "author-{$author->ID}.php";
147         }
148         $templates[] = 'author.php';
149
150         return get_query_template( 'author', $templates );
151 }
152
153 /**
154  * Retrieve path of category template in current or parent template.
155  *
156  * Works by first retrieving the current slug, for example 'category-default.php',
157  * and then trying category ID, for example 'category-1.php', and will finally fall
158  * back to category.php template, if those files don't exist.
159  *
160  * The template path is filterable via the dynamic {@see '$type_template'} hook,
161  * e.g. 'category_template'.
162  *
163  * @since 1.5.0
164  *
165  * @see get_query_template()
166  *
167  * @return string Full path to category template file.
168  */
169 function get_category_template() {
170         $category = get_queried_object();
171
172         $templates = array();
173
174         if ( ! empty( $category->slug ) ) {
175                 $templates[] = "category-{$category->slug}.php";
176                 $templates[] = "category-{$category->term_id}.php";
177         }
178         $templates[] = 'category.php';
179
180         return get_query_template( 'category', $templates );
181 }
182
183 /**
184  * Retrieve path of tag template in current or parent template.
185  *
186  * Works by first retrieving the current tag name, for example 'tag-wordpress.php',
187  * and then trying tag ID, for example 'tag-1.php', and will finally fall back to
188  * tag.php template, if those files don't exist.
189  *
190  * The template path is filterable via the dynamic {@see '$type_template'} hook,
191  * e.g. 'tag_template'.
192  *
193  * @since 2.3.0
194  *
195  * @see get_query_template()
196  *
197  * @return string Full path to tag template file.
198  */
199 function get_tag_template() {
200         $tag = get_queried_object();
201
202         $templates = array();
203
204         if ( ! empty( $tag->slug ) ) {
205                 $templates[] = "tag-{$tag->slug}.php";
206                 $templates[] = "tag-{$tag->term_id}.php";
207         }
208         $templates[] = 'tag.php';
209
210         return get_query_template( 'tag', $templates );
211 }
212
213 /**
214  * Retrieve path of taxonomy template in current or parent template.
215  *
216  * Retrieves the taxonomy and term, if term is available. The template is
217  * prepended with 'taxonomy-' and followed by both the taxonomy string and
218  * the taxonomy string followed by a dash and then followed by the term.
219  *
220  * The taxonomy and term template is checked and used first, if it exists.
221  * Second, just the taxonomy template is checked, and then finally, taxonomy.php
222  * template is used. If none of the files exist, then it will fall back on to
223  * index.php.
224  *
225  * The template path is filterable via the dynamic {@see '$type_template'} hook,
226  * e.g. 'taxonomy_template'.
227  *
228  * @since 2.5.0
229  *
230  * @see get_query_template()
231  *
232  * @return string Full path to taxonomy template file.
233  */
234 function get_taxonomy_template() {
235         $term = get_queried_object();
236
237         $templates = array();
238
239         if ( ! empty( $term->slug ) ) {
240                 $taxonomy = $term->taxonomy;
241                 $templates[] = "taxonomy-$taxonomy-{$term->slug}.php";
242                 $templates[] = "taxonomy-$taxonomy.php";
243         }
244         $templates[] = 'taxonomy.php';
245
246         return get_query_template( 'taxonomy', $templates );
247 }
248
249 /**
250  * Retrieve path of date template in current or parent template.
251  *
252  * The template path is filterable via the dynamic {@see '$type_template'} hook,
253  * e.g. 'date_template'.
254  *
255  * @since 1.5.0
256  *
257  * @see get_query_template()
258  *
259  * @return string Full path to date template file.
260  */
261 function get_date_template() {
262         return get_query_template('date');
263 }
264
265 /**
266  * Retrieve path of home template in current or parent template.
267  *
268  * This is the template used for the page containing the blog posts.
269  * Attempts to locate 'home.php' first before falling back to 'index.php'.
270  *
271  * The template path is filterable via the dynamic {@see '$type_template'} hook,
272  * e.g. 'home_template'.
273  *
274  * @since 1.5.0
275  *
276  * @see get_query_template()
277  *
278  * @return string Full path to home template file.
279  */
280 function get_home_template() {
281         $templates = array( 'home.php', 'index.php' );
282
283         return get_query_template( 'home', $templates );
284 }
285
286 /**
287  * Retrieve path of front-page template in current or parent template.
288  *
289  * Looks for 'front-page.php'. The template path is filterable via the
290  * dynamic {@see '$type_template'} hook, e.g. 'frontpage_template'.
291  *
292  * @since 3.0.0
293  *
294  * @see get_query_template()
295  *
296  * @return string Full path to front page template file.
297  */
298 function get_front_page_template() {
299         $templates = array('front-page.php');
300
301         return get_query_template( 'front_page', $templates );
302 }
303
304 /**
305  * Retrieve path of page template in current or parent template.
306  *
307  * Will first look for the specifically assigned page template.
308  * Then will search for 'page-{slug}.php', followed by 'page-{id}.php',
309  * and finally 'page.php'.
310  *
311  * The template path is filterable via the dynamic {@see '$type_template'} hook,
312  * e.g. 'page_template'.
313  *
314  * @since 1.5.0
315  *
316  * @see get_query_template()
317  *
318  * @return string Full path to page template file.
319  */
320 function get_page_template() {
321         $id = get_queried_object_id();
322         $template = get_page_template_slug();
323         $pagename = get_query_var('pagename');
324
325         if ( ! $pagename && $id ) {
326                 // If a static page is set as the front page, $pagename will not be set. Retrieve it from the queried object
327                 $post = get_queried_object();
328                 if ( $post )
329                         $pagename = $post->post_name;
330         }
331
332         $templates = array();
333         if ( $template && 0 === validate_file( $template ) )
334                 $templates[] = $template;
335         if ( $pagename )
336                 $templates[] = "page-$pagename.php";
337         if ( $id )
338                 $templates[] = "page-$id.php";
339         $templates[] = 'page.php';
340
341         return get_query_template( 'page', $templates );
342 }
343
344 /**
345  * Retrieve path of paged template in current or parent template.
346  *
347  * The template path is filterable via the dynamic {@see '$type_template'} hook,
348  * e.g. 'paged_template'.
349  *
350  * @since 1.5.0
351  *
352  * @see get_query_template()
353  *
354  * @return string Full path to paged template file.
355  */
356 function get_paged_template() {
357         return get_query_template('paged');
358 }
359
360 /**
361  * Retrieve path of search template in current or parent template.
362  *
363  * The template path is filterable via the dynamic {@see '$type_template'} hook,
364  * e.g. 'search_template'.
365  *
366  * @since 1.5.0
367  *
368  * @see get_query_template()
369  *
370  * @return string Full path to search template file.
371  */
372 function get_search_template() {
373         return get_query_template('search');
374 }
375
376 /**
377  * Retrieve path of single template in current or parent template.
378  *
379  * The template path is filterable via the dynamic {@see '$type_template'} hook,
380  * e.g. 'single_template'.
381  *
382  * @since 1.5.0
383  *
384  * @see get_query_template()
385  *
386  * @return string Full path to single template file.
387  */
388 function get_single_template() {
389         $object = get_queried_object();
390
391         $templates = array();
392
393         if ( ! empty( $object->post_type ) )
394                 $templates[] = "single-{$object->post_type}.php";
395         $templates[] = "single.php";
396
397         return get_query_template( 'single', $templates );
398 }
399
400 /**
401  * Retrieves the path of the singular template in current or parent template.
402  *
403  * The template path is filterable via the dynamic {@see '$type_template'} hook,
404  * e.g. 'singular_template'.
405  *
406  * @since 4.3.0
407  *
408  * @see get_query_template()
409  *
410  * @return string Full path to singular template file
411  */
412 function get_singular_template() {
413         return get_query_template( 'singular' );
414 }
415
416 /**
417  * Retrieve path of attachment template in current or parent template.
418  *
419  * The attachment path first checks if the first part of the mime type exists.
420  * The second check is for the second part of the mime type. The last check is
421  * for both types separated by an underscore. If neither are found then the file
422  * 'attachment.php' is checked and returned.
423  *
424  * Some examples for the 'text/plain' mime type are 'text.php', 'plain.php', and
425  * finally 'text-plain.php'.
426  *
427  * The template path is filterable via the dynamic {@see '$type_template'} hook,
428  * e.g. 'attachment_template'.
429  *
430  * @since 2.0.0
431  *
432  * @see get_query_template()
433  *
434  * @global array $posts
435  *
436  * @return string Full path to attachment template file.
437  */
438 function get_attachment_template() {
439         $attachment = get_queried_object();
440
441         $templates = array();
442
443         if ( $attachment ) {
444                 if ( false !== strpos( $attachment->post_mime_type, '/' ) ) {
445                         list( $type, $subtype ) = explode( '/', $attachment->post_mime_type );
446                 } else {
447                         list( $type, $subtype ) = array( $attachment->post_mime_type, '' );
448                 }
449
450                 if ( ! empty( $subtype ) ) {
451                         $templates[] = "{$type}-{$subtype}.php";
452                         $templates[] = "{$subtype}.php";
453                 }
454                 $templates[] = "{$type}.php";
455         }
456         $templates[] = 'attachment.php';
457
458         return get_query_template( 'attachment', $templates );
459 }
460
461 /**
462  * Retrieve path of comment popup template in current or parent template.
463  *
464  * Checks for comment popup template in current template, if it exists or in the
465  * parent template.
466  *
467  * The template path is filterable via the dynamic {@see '$type_template'} hook,
468  * e.g. 'commentspopup_template'.
469  *
470  * @since 1.5.0
471  *
472  * @see get_query_template()
473  *
474  * @return string Full path to comments popup template file.
475  */
476 function get_comments_popup_template() {
477         $template = get_query_template( 'comments_popup', array( 'comments-popup.php' ) );
478
479         // Backward compat code will be removed in a future release.
480         if ('' == $template)
481                 $template = ABSPATH . WPINC . '/theme-compat/comments-popup.php';
482
483         return $template;
484 }
485
486 /**
487  * Retrieve the name of the highest priority template file that exists.
488  *
489  * Searches in the STYLESHEETPATH before TEMPLATEPATH so that themes which
490  * inherit from a parent theme can just overload one file.
491  *
492  * @since 2.7.0
493  *
494  * @param string|array $template_names Template file(s) to search for, in order.
495  * @param bool         $load           If true the template file will be loaded if it is found.
496  * @param bool         $require_once   Whether to require_once or require. Default true. Has no effect if $load is false.
497  * @return string The template filename if one is located.
498  */
499 function locate_template($template_names, $load = false, $require_once = true ) {
500         $located = '';
501         foreach ( (array) $template_names as $template_name ) {
502                 if ( !$template_name )
503                         continue;
504                 if ( file_exists(STYLESHEETPATH . '/' . $template_name)) {
505                         $located = STYLESHEETPATH . '/' . $template_name;
506                         break;
507                 } elseif ( file_exists(TEMPLATEPATH . '/' . $template_name) ) {
508                         $located = TEMPLATEPATH . '/' . $template_name;
509                         break;
510                 }
511         }
512
513         if ( $load && '' != $located )
514                 load_template( $located, $require_once );
515
516         return $located;
517 }
518
519 /**
520  * Require the template file with WordPress environment.
521  *
522  * The globals are set up for the template file to ensure that the WordPress
523  * environment is available from within the function. The query variables are
524  * also available.
525  *
526  * @since 1.5.0
527  *
528  * @global array      $posts
529  * @global WP_Post    $post
530  * @global bool       $wp_did_header
531  * @global WP_Query   $wp_query
532  * @global WP_Rewrite $wp_rewrite
533  * @global wpdb       $wpdb
534  * @global string     $wp_version
535  * @global WP         $wp
536  * @global int        $id
537  * @global object     $comment
538  * @global int        $user_ID
539  *
540  * @param string $_template_file Path to template file.
541  * @param bool   $require_once   Whether to require_once or require. Default true.
542  */
543 function load_template( $_template_file, $require_once = true ) {
544         global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID;
545
546         if ( is_array( $wp_query->query_vars ) ) {
547                 extract( $wp_query->query_vars, EXTR_SKIP );
548         }
549
550         if ( isset( $s ) ) {
551                 $s = esc_attr( $s );
552         }
553
554         if ( $require_once ) {
555                 require_once( $_template_file );
556         } else {
557                 require( $_template_file );
558         }
559 }
560