Changeset 38789

Timestamp:

10/14/2016 02:19:08 PM (8 years ago)

Author:

johnbillion

Message:

Themes: Improve the inline documentation for the get_*_template() functions by providing examples instead of verbose explanations.

Fixes #38249
See #37770

File:

• trunk/src/wp-includes/template.php (modified) (16 diffs)

trunk/src/wp-includes/template.php

@@ -145 +145 @@
  * 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.
@@ -171 +183 @@
  * 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.
@@ -179 +199 @@
  *
  * @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()
@@ -207 +229 @@
  * 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.
@@ -215 +245 @@
  *
  * @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()
@@ -241 +273 @@
 
 /**
- * Retrieve path of taxonomy 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 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.
+ * Retrieve path of custom taxonomy term template in current or parent template.
+ *
+ * The hierarchy for this template looks like:
+ *
+ * 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.
@@ -256 +291 @@
  *
  * @since 2.5.0
- *
- * @see get_query_template()
- *
- * @return string Full path to taxonomy template file.
+ * @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 custom taxonomy term template file.
  */
 function get_taxonomy_template() {
@@ -301 +338 @@
  * 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.
@@ -340 +374 @@
  * 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.
@@ -348 +392 @@
  *
  * @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()
@@ -399 +445 @@
 
 /**
- * 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.
@@ -406 +465 @@
  * @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()
@@ -435 +496 @@
  * 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.
@@ -483 +554 @@
  * 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.
- *
- * Some examples for the 'text/plain' mime type are 'text.php', 'plain.php', and
- * finally 'text-plain.php'.
+ * The hierarchy for this template looks like:
+ *
+ * 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.
@@ -495 +572 @@
  *
  * @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()
@@ -602 +680 @@
     }
 }
-