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