sergiotarxz
/
Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

Fixes #38249
See #37770


git-svn-id: https://develop.svn.wordpress.org/trunk@38789 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
John Blackbourn 2016-10-14 14:19:08 +00:00
parent ddeae5feee
commit 6b8d8c90a5
1 changed files with 107 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
src/wp-includes/template.php
View File

@ -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 );
}
}