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