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