diff --git a/src/wp-includes/template.php b/src/wp-includes/template.php index 2a03a99e71..fd0476bae1 100644 --- a/src/wp-includes/template.php +++ b/src/wp-includes/template.php @@ -144,6 +144,18 @@ function get_post_type_archive_template() { /** * Retrieve path of author template in current or parent template. * + * The hierarchy for this template looks like: + * + * 1. author-{nicename}.php + * 2. author-{id}.php + * 3. author.php + * + * An example of this is: + * + * 1. author-john.php + * 2. author-1.php + * 3. author.php + * * The template hierarchy is filterable via the {@see 'author_template_hierarchy'} hook. * The template path is filterable via the {@see 'author_template'} hook. * @@ -170,14 +182,24 @@ function get_author_template() { /** * Retrieve path of category template in current or parent template. * - * Works by first retrieving the current slug, for example 'category-default.php', - * and then trying category ID, for example 'category-1.php', and will finally fall - * back to category.php template, if those files don't exist. + * The hierarchy for this template looks like: + * + * 1. category-{slug}.php + * 2. category-{id}.php + * 3. category.php + * + * An example of this is: + * + * 1. category-news.php + * 2. category-2.php + * 3. category.php * * The template hierarchy is filterable via the {@see 'category_template_hierarchy'} hook. * The template path is filterable via the {@see 'category_template'} hook. * * @since 1.5.0 + * @since 4.7.0 The decoded form of `category-{slug}.php` was added to the top of the + * template hierarchy when the category slug contains multibyte characters. * * @see get_query_template() * @@ -206,14 +228,24 @@ function get_category_template() { /** * Retrieve path of tag template in current or parent template. * - * Works by first retrieving the current tag name, for example 'tag-wordpress.php', - * and then trying tag ID, for example 'tag-1.php', and will finally fall back to - * tag.php template, if those files don't exist. + * The hierarchy for this template looks like: + * + * 1. tag-{slug}.php + * 2. tag-{id}.php + * 3. tag.php + * + * An example of this is: + * + * 1. tag-wordpress.php + * 2. tag-3.php + * 3. tag.php * * The template hierarchy is filterable via the {@see 'tag_template_hierarchy'} hook. * The template path is filterable via the {@see 'tag_template'} hook. * * @since 2.3.0 + * @since 4.7.0 The decoded form of `tag-{slug}.php` was added to the top of the + * template hierarchy when the tag slug contains multibyte characters. * * @see get_query_template() * @@ -240,25 +272,30 @@ function get_tag_template() { } /** - * Retrieve path of taxonomy template in current or parent template. + * Retrieve path of custom taxonomy term template in current or parent template. * - * Retrieves the taxonomy and term, if term is available. The template is - * prepended with 'taxonomy-' and followed by both the taxonomy string and - * the taxonomy string followed by a dash and then followed by the term. + * The hierarchy for this template looks like: * - * The taxonomy and term template is checked and used first, if it exists. - * Second, just the taxonomy template is checked, and then finally, taxonomy.php - * template is used. If none of the files exist, then it will fall back on to - * index.php. + * 1. taxonomy-{taxonomy_slug}-{term_slug}.php + * 2. taxonomy-{taxonomy_slug}.php + * 3. taxonomy.php + * + * An example of this is: + * + * 1. taxonomy-location-texas.php + * 2. taxonomy-location.php + * 3. taxonomy.php * * The template hierarchy is filterable via the {@see 'taxonomy_template_hierarchy'} hook. * The template path is filterable via the {@see 'taxonomy_template'} hook. * * @since 2.5.0 + * @since 4.7.0 The decoded form of `taxonomy-{taxonomy_slug}-{term_slug}.php` was added to the top of the + * template hierarchy when the term slug contains multibyte characters. * * @see get_query_template() * - * @return string Full path to taxonomy template file. + * @return string Full path to custom taxonomy term template file. */ function get_taxonomy_template() { $term = get_queried_object(); @@ -300,9 +337,6 @@ function get_date_template() { /** * Retrieve path of home template in current or parent template. * - * This is the template used for the page containing the blog posts. - * Attempts to locate 'home.php' first before falling back to 'index.php'. - * * The template hierarchy is filterable via the {@see 'home_template_hierarchy'} hook. * The template path is filterable via the {@see 'home_template'} hook. * @@ -339,14 +373,26 @@ function get_front_page_template() { /** * Retrieve path of page template in current or parent template. * - * Will first look for the specifically assigned page template. - * Then will search for 'page-{slug}.php', followed by 'page-{id}.php', - * and finally 'page.php'. + * The hierarchy for this template looks like: + * + * 1. {Page Template}.php + * 2. page-{page_name}.php + * 3. page-{id}.php + * 4. page.php + * + * An example of this is: + * + * 1. page-templates/full-width.php + * 2. page-about.php + * 3. page-4.php + * 4. page.php * * The template hierarchy is filterable via the {@see 'page_template_hierarchy'} hook. * The template path is filterable via the {@see 'page_template'} hook. * * @since 1.5.0 + * @since 4.7.0 The decoded form of `page-{page_name}.php` was added to the top of the + * template hierarchy when the page name contains multibyte characters. * * @see get_query_template() * @@ -398,13 +444,28 @@ function get_search_template() { } /** - * Retrieve path of single template in current or parent template. + * Retrieve path of single template in current or parent template. Applies to single Posts, + * single Attachments, and single custom post types. + * + * The hierarchy for this template looks like: + * + * 1. single-{post_type}-{post_name}.php + * 2. single-{post_type}.php + * 3. single.php + * + * An example of this is: + * + * 1. single-post-hello-world.php + * 2. single-post.php + * 3. single.php * * The template hierarchy is filterable via the {@see 'single_template_hierarchy'} hook. * The template path is filterable via the {@see 'single_template'} hook. * * @since 1.5.0 * @since 4.4.0 `single-{post_type}-{post_name}.php` was added to the top of the template hierarchy. + * @since 4.7.0 The decoded form of `single-{post_type}-{post_name}.php` was added to the top of the + * template hierarchy when the post name contains multibyte characters. * * @see get_query_template() * @@ -434,7 +495,17 @@ function get_single_template() { /** * Retrieves an embed template path in the current or parent template. * - * By default the WordPress-template is returned. + * The hierarchy for this template looks like: + * + * 1. embed-{post_type}-{post_format}.php + * 2. embed-{post_type}.php + * 3. embed.php + * + * An example of this is: + * + * 1. embed-post-audio.php + * 2. embed-post.php + * 3. embed.php * * The template hierarchy is filterable via the {@see 'embed_template_hierarchy'} hook. * The template path is filterable via the {@see 'embed_template'} hook. @@ -482,18 +553,25 @@ function get_singular_template() { /** * Retrieve path of attachment template in current or parent template. * - * The attachment path first checks if the first part of the mime type exists. - * The second check is for the second part of the mime type. The last check is - * for both types separated by an underscore. If neither are found then the file - * 'attachment.php' is checked and returned. + * The hierarchy for this template looks like: * - * Some examples for the 'text/plain' mime type are 'text.php', 'plain.php', and - * finally 'text-plain.php'. + * 1. {mime_type}-{sub_type}.php + * 2. {sub_type}.php + * 3. {mime_type}.php + * 4. attachment.php + * + * An example of this is: + * + * 1. image-jpeg.php + * 2. jpeg.php + * 3. image.php + * 4. attachment.php * * The template hierarchy is filterable via the {@see 'attachment_template_hierarchy'} hook. * The template path is filterable via the {@see 'attachment_template'} hook. * * @since 2.0.0 + * @since 4.3.0 The order of the mime type logic was reversed so the hierarchy is more logical. * * @see get_query_template() * @@ -601,4 +679,3 @@ function load_template( $_template_file, $require_once = true ) { require( $_template_file ); } } -