[ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
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 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 30 /** 31 * Filters the list of template filenames that are searched for when retrieving a template to use. 32 * 33 * The last element in the array should always be the fallback template for this query type. 34 * 35 * Possible values for `$type` include: 'index', '404', 'archive', 'author', 'category', 'tag', 'taxonomy', 'date', 36 * 'embed', 'home', 'frontpage', 'privacypolicy', 'page', 'paged', 'search', 'single', 'singular', and 'attachment'. 37 * 38 * @since 4.7.0 39 * 40 * @param array $templates A list of template candidates, in descending order of priority. 41 */ 42 $templates = apply_filters( "{$type}_template_hierarchy", $templates ); 43 44 $template = locate_template( $templates ); 45 46 /** 47 * Filters the path of the queried template by type. 48 * 49 * The dynamic portion of the hook name, `$type`, refers to the filename -- minus the file 50 * extension and any non-alphanumeric characters delimiting words -- of the file to load. 51 * This hook also applies to various types of files loaded as part of the Template Hierarchy. 52 * 53 * Possible values for `$type` include: 'index', '404', 'archive', 'author', 'category', 'tag', 'taxonomy', 'date', 54 * 'embed', 'home', 'frontpage', 'privacypolicy', 'page', 'paged', 'search', 'single', 'singular', and 'attachment'. 55 * 56 * @since 1.5.0 57 * @since 4.8.0 The `$type` and `$templates` parameters were added. 58 * 59 * @param string $template Path to the template. See locate_template(). 60 * @param string $type Sanitized filename without extension. 61 * @param array $templates A list of template candidates, in descending order of priority. 62 */ 63 return apply_filters( "{$type}_template", $template, $type, $templates ); 64 } 65 66 /** 67 * Retrieve path of index template in current or parent template. 68 * 69 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 70 * and {@see '$type_template'} dynamic hooks, where `$type` is 'index'. 71 * 72 * @since 3.0.0 73 * 74 * @see get_query_template() 75 * 76 * @return string Full path to index template file. 77 */ 78 function get_index_template() { 79 return get_query_template( 'index' ); 80 } 81 82 /** 83 * Retrieve path of 404 template in current or parent template. 84 * 85 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 86 * and {@see '$type_template'} dynamic hooks, where `$type` is '404'. 87 * 88 * @since 1.5.0 89 * 90 * @see get_query_template() 91 * 92 * @return string Full path to 404 template file. 93 */ 94 function get_404_template() { 95 return get_query_template( '404' ); 96 } 97 98 /** 99 * Retrieve path of archive template in current or parent template. 100 * 101 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 102 * and {@see '$type_template'} dynamic hooks, where `$type` is 'archive'. 103 * 104 * @since 1.5.0 105 * 106 * @see get_query_template() 107 * 108 * @return string Full path to archive template file. 109 */ 110 function get_archive_template() { 111 $post_types = array_filter( (array) get_query_var( 'post_type' ) ); 112 113 $templates = array(); 114 115 if ( count( $post_types ) == 1 ) { 116 $post_type = reset( $post_types ); 117 $templates[] = "archive-{$post_type}.php"; 118 } 119 $templates[] = 'archive.php'; 120 121 return get_query_template( 'archive', $templates ); 122 } 123 124 /** 125 * Retrieve path of post type archive template in current or parent template. 126 * 127 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 128 * and {@see '$type_template'} dynamic hooks, where `$type` is 'archive'. 129 * 130 * @since 3.7.0 131 * 132 * @see get_archive_template() 133 * 134 * @return string Full path to archive template file. 135 */ 136 function get_post_type_archive_template() { 137 $post_type = get_query_var( 'post_type' ); 138 if ( is_array( $post_type ) ) { 139 $post_type = reset( $post_type ); 140 } 141 142 $obj = get_post_type_object( $post_type ); 143 if ( ! ( $obj instanceof WP_Post_Type ) || ! $obj->has_archive ) { 144 return ''; 145 } 146 147 return get_archive_template(); 148 } 149 150 /** 151 * Retrieve path of author template in current or parent template. 152 * 153 * The hierarchy for this template looks like: 154 * 155 * 1. author-{nicename}.php 156 * 2. author-{id}.php 157 * 3. author.php 158 * 159 * An example of this is: 160 * 161 * 1. author-john.php 162 * 2. author-1.php 163 * 3. author.php 164 * 165 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 166 * and {@see '$type_template'} dynamic hooks, where `$type` is 'author'. 167 * 168 * @since 1.5.0 169 * 170 * @see get_query_template() 171 * 172 * @return string Full path to author template file. 173 */ 174 function get_author_template() { 175 $author = get_queried_object(); 176 177 $templates = array(); 178 179 if ( $author instanceof WP_User ) { 180 $templates[] = "author-{$author->user_nicename}.php"; 181 $templates[] = "author-{$author->ID}.php"; 182 } 183 $templates[] = 'author.php'; 184 185 return get_query_template( 'author', $templates ); 186 } 187 188 /** 189 * Retrieve path of category template in current or parent template. 190 * 191 * The hierarchy for this template looks like: 192 * 193 * 1. category-{slug}.php 194 * 2. category-{id}.php 195 * 3. category.php 196 * 197 * An example of this is: 198 * 199 * 1. category-news.php 200 * 2. category-2.php 201 * 3. category.php 202 * 203 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 204 * and {@see '$type_template'} dynamic hooks, where `$type` is 'category'. 205 * 206 * @since 1.5.0 207 * @since 4.7.0 The decoded form of `category-{slug}.php` was added to the top of the 208 * template hierarchy when the category slug contains multibyte characters. 209 * 210 * @see get_query_template() 211 * 212 * @return string Full path to category template file. 213 */ 214 function get_category_template() { 215 $category = get_queried_object(); 216 217 $templates = array(); 218 219 if ( ! empty( $category->slug ) ) { 220 221 $slug_decoded = urldecode( $category->slug ); 222 if ( $slug_decoded !== $category->slug ) { 223 $templates[] = "category-{$slug_decoded}.php"; 224 } 225 226 $templates[] = "category-{$category->slug}.php"; 227 $templates[] = "category-{$category->term_id}.php"; 228 } 229 $templates[] = 'category.php'; 230 231 return get_query_template( 'category', $templates ); 232 } 233 234 /** 235 * Retrieve path of tag template in current or parent template. 236 * 237 * The hierarchy for this template looks like: 238 * 239 * 1. tag-{slug}.php 240 * 2. tag-{id}.php 241 * 3. tag.php 242 * 243 * An example of this is: 244 * 245 * 1. tag-wordpress.php 246 * 2. tag-3.php 247 * 3. tag.php 248 * 249 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 250 * and {@see '$type_template'} dynamic hooks, where `$type` is 'tag'. 251 * 252 * @since 2.3.0 253 * @since 4.7.0 The decoded form of `tag-{slug}.php` was added to the top of the 254 * template hierarchy when the tag slug contains multibyte characters. 255 * 256 * @see get_query_template() 257 * 258 * @return string Full path to tag template file. 259 */ 260 function get_tag_template() { 261 $tag = get_queried_object(); 262 263 $templates = array(); 264 265 if ( ! empty( $tag->slug ) ) { 266 267 $slug_decoded = urldecode( $tag->slug ); 268 if ( $slug_decoded !== $tag->slug ) { 269 $templates[] = "tag-{$slug_decoded}.php"; 270 } 271 272 $templates[] = "tag-{$tag->slug}.php"; 273 $templates[] = "tag-{$tag->term_id}.php"; 274 } 275 $templates[] = 'tag.php'; 276 277 return get_query_template( 'tag', $templates ); 278 } 279 280 /** 281 * Retrieve path of custom taxonomy term template in current or parent template. 282 * 283 * The hierarchy for this template looks like: 284 * 285 * 1. taxonomy-{taxonomy_slug}-{term_slug}.php 286 * 2. taxonomy-{taxonomy_slug}.php 287 * 3. taxonomy.php 288 * 289 * An example of this is: 290 * 291 * 1. taxonomy-location-texas.php 292 * 2. taxonomy-location.php 293 * 3. taxonomy.php 294 * 295 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 296 * and {@see '$type_template'} dynamic hooks, where `$type` is 'taxonomy'. 297 * 298 * @since 2.5.0 299 * @since 4.7.0 The decoded form of `taxonomy-{taxonomy_slug}-{term_slug}.php` was added to the top of the 300 * template hierarchy when the term slug contains multibyte characters. 301 * 302 * @see get_query_template() 303 * 304 * @return string Full path to custom taxonomy term template file. 305 */ 306 function get_taxonomy_template() { 307 $term = get_queried_object(); 308 309 $templates = array(); 310 311 if ( ! empty( $term->slug ) ) { 312 $taxonomy = $term->taxonomy; 313 314 $slug_decoded = urldecode( $term->slug ); 315 if ( $slug_decoded !== $term->slug ) { 316 $templates[] = "taxonomy-$taxonomy-{$slug_decoded}.php"; 317 } 318 319 $templates[] = "taxonomy-$taxonomy-{$term->slug}.php"; 320 $templates[] = "taxonomy-$taxonomy.php"; 321 } 322 $templates[] = 'taxonomy.php'; 323 324 return get_query_template( 'taxonomy', $templates ); 325 } 326 327 /** 328 * Retrieve path of date template in current or parent template. 329 * 330 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 331 * and {@see '$type_template'} dynamic hooks, where `$type` is 'date'. 332 * 333 * @since 1.5.0 334 * 335 * @see get_query_template() 336 * 337 * @return string Full path to date template file. 338 */ 339 function get_date_template() { 340 return get_query_template( 'date' ); 341 } 342 343 /** 344 * Retrieve path of home template in current or parent template. 345 * 346 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 347 * and {@see '$type_template'} dynamic hooks, where `$type` is 'home'. 348 * 349 * @since 1.5.0 350 * 351 * @see get_query_template() 352 * 353 * @return string Full path to home template file. 354 */ 355 function get_home_template() { 356 $templates = array( 'home.php', 'index.php' ); 357 358 return get_query_template( 'home', $templates ); 359 } 360 361 /** 362 * Retrieve path of front page template in current or parent template. 363 * 364 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 365 * and {@see '$type_template'} dynamic hooks, where `$type` is 'frontpage'. 366 * 367 * @since 3.0.0 368 * 369 * @see get_query_template() 370 * 371 * @return string Full path to front page template file. 372 */ 373 function get_front_page_template() { 374 $templates = array( 'front-page.php' ); 375 376 return get_query_template( 'frontpage', $templates ); 377 } 378 379 /** 380 * Retrieve path of Privacy Policy page template in current or parent template. 381 * 382 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 383 * and {@see '$type_template'} dynamic hooks, where `$type` is 'privacypolicy'. 384 * 385 * @since 5.2.0 386 * 387 * @see get_query_template() 388 * 389 * @return string Full path to privacy policy template file. 390 */ 391 function get_privacy_policy_template() { 392 $templates = array( 'privacy-policy.php' ); 393 394 return get_query_template( 'privacypolicy', $templates ); 395 } 396 397 /** 398 * Retrieve path of page template in current or parent template. 399 * 400 * The hierarchy for this template looks like: 401 * 402 * 1. {Page Template}.php 403 * 2. page-{page_name}.php 404 * 3. page-{id}.php 405 * 4. page.php 406 * 407 * An example of this is: 408 * 409 * 1. page-templates/full-width.php 410 * 2. page-about.php 411 * 3. page-4.php 412 * 4. page.php 413 * 414 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 415 * and {@see '$type_template'} dynamic hooks, where `$type` is 'page'. 416 * 417 * @since 1.5.0 418 * @since 4.7.0 The decoded form of `page-{page_name}.php` was added to the top of the 419 * template hierarchy when the page name contains multibyte characters. 420 * 421 * @see get_query_template() 422 * 423 * @return string Full path to page template file. 424 */ 425 function get_page_template() { 426 $id = get_queried_object_id(); 427 $template = get_page_template_slug(); 428 $pagename = get_query_var( 'pagename' ); 429 430 if ( ! $pagename && $id ) { 431 // If a static page is set as the front page, $pagename will not be set. 432 // Retrieve it from the queried object. 433 $post = get_queried_object(); 434 if ( $post ) { 435 $pagename = $post->post_name; 436 } 437 } 438 439 $templates = array(); 440 if ( $template && 0 === validate_file( $template ) ) { 441 $templates[] = $template; 442 } 443 if ( $pagename ) { 444 $pagename_decoded = urldecode( $pagename ); 445 if ( $pagename_decoded !== $pagename ) { 446 $templates[] = "page-{$pagename_decoded}.php"; 447 } 448 $templates[] = "page-{$pagename}.php"; 449 } 450 if ( $id ) { 451 $templates[] = "page-{$id}.php"; 452 } 453 $templates[] = 'page.php'; 454 455 return get_query_template( 'page', $templates ); 456 } 457 458 /** 459 * Retrieve path of search template in current or parent template. 460 * 461 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 462 * and {@see '$type_template'} dynamic hooks, where `$type` is 'search'. 463 * 464 * @since 1.5.0 465 * 466 * @see get_query_template() 467 * 468 * @return string Full path to search template file. 469 */ 470 function get_search_template() { 471 return get_query_template( 'search' ); 472 } 473 474 /** 475 * Retrieve path of single template in current or parent template. Applies to single Posts, 476 * single Attachments, and single custom post types. 477 * 478 * The hierarchy for this template looks like: 479 * 480 * 1. {Post Type Template}.php 481 * 2. single-{post_type}-{post_name}.php 482 * 3. single-{post_type}.php 483 * 4. single.php 484 * 485 * An example of this is: 486 * 487 * 1. templates/full-width.php 488 * 2. single-post-hello-world.php 489 * 3. single-post.php 490 * 4. single.php 491 * 492 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 493 * and {@see '$type_template'} dynamic hooks, where `$type` is 'single'. 494 * 495 * @since 1.5.0 496 * @since 4.4.0 `single-{post_type}-{post_name}.php` was added to the top of the template hierarchy. 497 * @since 4.7.0 The decoded form of `single-{post_type}-{post_name}.php` was added to the top of the 498 * template hierarchy when the post name contains multibyte characters. 499 * @since 4.7.0 `{Post Type Template}.php` was added to the top of the template hierarchy. 500 * 501 * @see get_query_template() 502 * 503 * @return string Full path to single template file. 504 */ 505 function get_single_template() { 506 $object = get_queried_object(); 507 508 $templates = array(); 509 510 if ( ! empty( $object->post_type ) ) { 511 $template = get_page_template_slug( $object ); 512 if ( $template && 0 === validate_file( $template ) ) { 513 $templates[] = $template; 514 } 515 516 $name_decoded = urldecode( $object->post_name ); 517 if ( $name_decoded !== $object->post_name ) { 518 $templates[] = "single-{$object->post_type}-{$name_decoded}.php"; 519 } 520 521 $templates[] = "single-{$object->post_type}-{$object->post_name}.php"; 522 $templates[] = "single-{$object->post_type}.php"; 523 } 524 525 $templates[] = 'single.php'; 526 527 return get_query_template( 'single', $templates ); 528 } 529 530 /** 531 * Retrieves an embed template path in the current or parent template. 532 * 533 * The hierarchy for this template looks like: 534 * 535 * 1. embed-{post_type}-{post_format}.php 536 * 2. embed-{post_type}.php 537 * 3. embed.php 538 * 539 * An example of this is: 540 * 541 * 1. embed-post-audio.php 542 * 2. embed-post.php 543 * 3. embed.php 544 * 545 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 546 * and {@see '$type_template'} dynamic hooks, where `$type` is 'embed'. 547 * 548 * @since 4.5.0 549 * 550 * @see get_query_template() 551 * 552 * @return string Full path to embed template file. 553 */ 554 function get_embed_template() { 555 $object = get_queried_object(); 556 557 $templates = array(); 558 559 if ( ! empty( $object->post_type ) ) { 560 $post_format = get_post_format( $object ); 561 if ( $post_format ) { 562 $templates[] = "embed-{$object->post_type}-{$post_format}.php"; 563 } 564 $templates[] = "embed-{$object->post_type}.php"; 565 } 566 567 $templates[] = 'embed.php'; 568 569 return get_query_template( 'embed', $templates ); 570 } 571 572 /** 573 * Retrieves the path of the singular template in current or parent template. 574 * 575 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 576 * and {@see '$type_template'} dynamic hooks, where `$type` is 'singular'. 577 * 578 * @since 4.3.0 579 * 580 * @see get_query_template() 581 * 582 * @return string Full path to singular template file 583 */ 584 function get_singular_template() { 585 return get_query_template( 'singular' ); 586 } 587 588 /** 589 * Retrieve path of attachment template in current or parent template. 590 * 591 * The hierarchy for this template looks like: 592 * 593 * 1. {mime_type}-{sub_type}.php 594 * 2. {sub_type}.php 595 * 3. {mime_type}.php 596 * 4. attachment.php 597 * 598 * An example of this is: 599 * 600 * 1. image-jpeg.php 601 * 2. jpeg.php 602 * 3. image.php 603 * 4. attachment.php 604 * 605 * The template hierarchy and template path are filterable via the {@see '$type_template_hierarchy'} 606 * and {@see '$type_template'} dynamic hooks, where `$type` is 'attachment'. 607 * 608 * @since 2.0.0 609 * @since 4.3.0 The order of the mime type logic was reversed so the hierarchy is more logical. 610 * 611 * @see get_query_template() 612 * 613 * @global array $posts 614 * 615 * @return string Full path to attachment template file. 616 */ 617 function get_attachment_template() { 618 $attachment = get_queried_object(); 619 620 $templates = array(); 621 622 if ( $attachment ) { 623 if ( false !== strpos( $attachment->post_mime_type, '/' ) ) { 624 list( $type, $subtype ) = explode( '/', $attachment->post_mime_type ); 625 } else { 626 list( $type, $subtype ) = array( $attachment->post_mime_type, '' ); 627 } 628 629 if ( ! empty( $subtype ) ) { 630 $templates[] = "{$type}-{$subtype}.php"; 631 $templates[] = "{$subtype}.php"; 632 } 633 $templates[] = "{$type}.php"; 634 } 635 $templates[] = 'attachment.php'; 636 637 return get_query_template( 'attachment', $templates ); 638 } 639 640 /** 641 * Retrieve the name of the highest priority template file that exists. 642 * 643 * Searches in the STYLESHEETPATH before TEMPLATEPATH and wp-includes/theme-compat 644 * so that themes which inherit from a parent theme can just overload one file. 645 * 646 * @since 2.7.0 647 * @since 5.5.0 The `$args` parameter was added. 648 * 649 * @param string|array $template_names Template file(s) to search for, in order. 650 * @param bool $load If true the template file will be loaded if it is found. 651 * @param bool $require_once Whether to require_once or require. Has no effect if `$load` is false. 652 * Default true. 653 * @param array $args Optional. Additional arguments passed to the template. 654 * Default empty array. 655 * @return string The template filename if one is located. 656 */ 657 function locate_template( $template_names, $load = false, $require_once = true, $args = array() ) { 658 $located = ''; 659 foreach ( (array) $template_names as $template_name ) { 660 if ( ! $template_name ) { 661 continue; 662 } 663 if ( file_exists( STYLESHEETPATH . '/' . $template_name ) ) { 664 $located = STYLESHEETPATH . '/' . $template_name; 665 break; 666 } elseif ( file_exists( TEMPLATEPATH . '/' . $template_name ) ) { 667 $located = TEMPLATEPATH . '/' . $template_name; 668 break; 669 } elseif ( file_exists( ABSPATH . WPINC . '/theme-compat/' . $template_name ) ) { 670 $located = ABSPATH . WPINC . '/theme-compat/' . $template_name; 671 break; 672 } 673 } 674 675 if ( $load && '' !== $located ) { 676 load_template( $located, $require_once, $args ); 677 } 678 679 return $located; 680 } 681 682 /** 683 * Require the template file with WordPress environment. 684 * 685 * The globals are set up for the template file to ensure that the WordPress 686 * environment is available from within the function. The query variables are 687 * also available. 688 * 689 * @since 1.5.0 690 * @since 5.5.0 The `$args` parameter was added. 691 * 692 * @global array $posts 693 * @global WP_Post $post Global post object. 694 * @global bool $wp_did_header 695 * @global WP_Query $wp_query WordPress Query object. 696 * @global WP_Rewrite $wp_rewrite WordPress rewrite component. 697 * @global wpdb $wpdb WordPress database abstraction object. 698 * @global string $wp_version 699 * @global WP $wp Current WordPress environment instance. 700 * @global int $id 701 * @global WP_Comment $comment Global comment object. 702 * @global int $user_ID 703 * 704 * @param string $_template_file Path to template file. 705 * @param bool $require_once Whether to require_once or require. Default true. 706 * @param array $args Optional. Additional arguments passed to the template. 707 * Default empty array. 708 */ 709 function load_template( $_template_file, $require_once = true, $args = array() ) { 710 global $posts, $post, $wp_did_header, $wp_query, $wp_rewrite, $wpdb, $wp_version, $wp, $id, $comment, $user_ID; 711 712 if ( is_array( $wp_query->query_vars ) ) { 713 /* 714 * This use of extract() cannot be removed. There are many possible ways that 715 * templates could depend on variables that it creates existing, and no way to 716 * detect and deprecate it. 717 * 718 * Passing the EXTR_SKIP flag is the safest option, ensuring globals and 719 * function variables cannot be overwritten. 720 */ 721 // phpcs:ignore WordPress.PHP.DontExtract.extract_extract 722 extract( $wp_query->query_vars, EXTR_SKIP ); 723 } 724 725 if ( isset( $s ) ) { 726 $s = esc_attr( $s ); 727 } 728 729 if ( $require_once ) { 730 require_once $_template_file; 731 } else { 732 require $_template_file; 733 } 734 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated : Mon Jan 18 08:20:02 2021 | Cross-referenced by PHPXref |