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