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