WordPress.org

Make WordPress Core

Changeset 38789


Ignore:
Timestamp:
10/14/2016 02:19:08 PM (20 months 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:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/template.php

    r38755 r38789  
    145145 * Retrieve path of author template in current or parent template.
    146146 *
     147 * The hierarchy for this template looks like:
     148 *
     149 * 1. author-{nicename}.php
     150 * 2. author-{id}.php
     151 * 3. author.php
     152 *
     153 * An example of this is:
     154 *
     155 * 1. author-john.php
     156 * 2. author-1.php
     157 * 3. author.php
     158 *
    147159 * The template hierarchy is filterable via the {@see 'author_template_hierarchy'} hook.
    148160 * The template path is filterable via the {@see 'author_template'} hook.
     
    171183 * Retrieve path of category template in current or parent template.
    172184 *
    173  * Works by first retrieving the current slug, for example 'category-default.php',
    174  * and then trying category ID, for example 'category-1.php', and will finally fall
    175  * back to category.php template, if those files don't exist.
     185 * The hierarchy for this template looks like:
     186 *
     187 * 1. category-{slug}.php
     188 * 2. category-{id}.php
     189 * 3. category.php
     190 *
     191 * An example of this is:
     192 *
     193 * 1. category-news.php
     194 * 2. category-2.php
     195 * 3. category.php
    176196 *
    177197 * The template hierarchy is filterable via the {@see 'category_template_hierarchy'} hook.
     
    179199 *
    180200 * @since 1.5.0
     201 * @since 4.7.0 The decoded form of `category-{slug}.php` was added to the top of the
     202 *              template hierarchy when the category slug contains multibyte characters.
    181203 *
    182204 * @see get_query_template()
     
    207229 * Retrieve path of tag template in current or parent template.
    208230 *
    209  * Works by first retrieving the current tag name, for example 'tag-wordpress.php',
    210  * and then trying tag ID, for example 'tag-1.php', and will finally fall back to
    211  * tag.php template, if those files don't exist.
     231 * The hierarchy for this template looks like:
     232 *
     233 * 1. tag-{slug}.php
     234 * 2. tag-{id}.php
     235 * 3. tag.php
     236 *
     237 * An example of this is:
     238 *
     239 * 1. tag-wordpress.php
     240 * 2. tag-3.php
     241 * 3. tag.php
    212242 *
    213243 * The template hierarchy is filterable via the {@see 'tag_template_hierarchy'} hook.
     
    215245 *
    216246 * @since 2.3.0
     247 * @since 4.7.0 The decoded form of `tag-{slug}.php` was added to the top of the
     248 *              template hierarchy when the tag slug contains multibyte characters.
    217249 *
    218250 * @see get_query_template()
     
    241273
    242274/**
    243  * Retrieve path of taxonomy template in current or parent template.
    244  *
    245  * Retrieves the taxonomy and term, if term is available. The template is
    246  * prepended with 'taxonomy-' and followed by both the taxonomy string and
    247  * the taxonomy string followed by a dash and then followed by the term.
    248  *
    249  * The taxonomy and term template is checked and used first, if it exists.
    250  * Second, just the taxonomy template is checked, and then finally, taxonomy.php
    251  * template is used. If none of the files exist, then it will fall back on to
    252  * index.php.
     275 * Retrieve path of custom taxonomy term template in current or parent template.
     276 *
     277 * The hierarchy for this template looks like:
     278 *
     279 * 1. taxonomy-{taxonomy_slug}-{term_slug}.php
     280 * 2. taxonomy-{taxonomy_slug}.php
     281 * 3. taxonomy.php
     282 *
     283 * An example of this is:
     284 *
     285 * 1. taxonomy-location-texas.php
     286 * 2. taxonomy-location.php
     287 * 3. taxonomy.php
    253288 *
    254289 * The template hierarchy is filterable via the {@see 'taxonomy_template_hierarchy'} hook.
     
    256291 *
    257292 * @since 2.5.0
    258  *
    259  * @see get_query_template()
    260  *
    261  * @return string Full path to taxonomy template file.
     293 * @since 4.7.0 The decoded form of `taxonomy-{taxonomy_slug}-{term_slug}.php` was added to the top of the
     294 *              template hierarchy when the term slug contains multibyte characters.
     295 *
     296 * @see get_query_template()
     297 *
     298 * @return string Full path to custom taxonomy term template file.
    262299 */
    263300function get_taxonomy_template() {
     
    301338 * Retrieve path of home template in current or parent template.
    302339 *
    303  * This is the template used for the page containing the blog posts.
    304  * Attempts to locate 'home.php' first before falling back to 'index.php'.
    305  *
    306340 * The template hierarchy is filterable via the {@see 'home_template_hierarchy'} hook.
    307341 * The template path is filterable via the {@see 'home_template'} hook.
     
    340374 * Retrieve path of page template in current or parent template.
    341375 *
    342  * Will first look for the specifically assigned page template.
    343  * Then will search for 'page-{slug}.php', followed by 'page-{id}.php',
    344  * and finally 'page.php'.
     376 * The hierarchy for this template looks like:
     377 *
     378 * 1. {Page Template}.php
     379 * 2. page-{page_name}.php
     380 * 3. page-{id}.php
     381 * 4. page.php
     382 *
     383 * An example of this is:
     384 *
     385 * 1. page-templates/full-width.php
     386 * 2. page-about.php
     387 * 3. page-4.php
     388 * 4. page.php
    345389 *
    346390 * The template hierarchy is filterable via the {@see 'page_template_hierarchy'} hook.
     
    348392 *
    349393 * @since 1.5.0
     394 * @since 4.7.0 The decoded form of `page-{page_name}.php` was added to the top of the
     395 *              template hierarchy when the page name contains multibyte characters.
    350396 *
    351397 * @see get_query_template()
     
    399445
    400446/**
    401  * Retrieve path of single template in current or parent template.
     447 * Retrieve path of single template in current or parent template. Applies to single Posts,
     448 * single Attachments, and single custom post types.
     449 *
     450 * The hierarchy for this template looks like:
     451 *
     452 * 1. single-{post_type}-{post_name}.php
     453 * 2. single-{post_type}.php
     454 * 3. single.php
     455 *
     456 * An example of this is:
     457 *
     458 * 1. single-post-hello-world.php
     459 * 2. single-post.php
     460 * 3. single.php
    402461 *
    403462 * The template hierarchy is filterable via the {@see 'single_template_hierarchy'} hook.
     
    406465 * @since 1.5.0
    407466 * @since 4.4.0 `single-{post_type}-{post_name}.php` was added to the top of the template hierarchy.
     467 * @since 4.7.0 The decoded form of `single-{post_type}-{post_name}.php` was added to the top of the
     468 *              template hierarchy when the post name contains multibyte characters.
    408469 *
    409470 * @see get_query_template()
     
    435496 * Retrieves an embed template path in the current or parent template.
    436497 *
    437  * By default the WordPress-template is returned.
     498 * The hierarchy for this template looks like:
     499 *
     500 * 1. embed-{post_type}-{post_format}.php
     501 * 2. embed-{post_type}.php
     502 * 3. embed.php
     503 *
     504 * An example of this is:
     505 *
     506 * 1. embed-post-audio.php
     507 * 2. embed-post.php
     508 * 3. embed.php
    438509 *
    439510 * The template hierarchy is filterable via the {@see 'embed_template_hierarchy'} hook.
     
    483554 * Retrieve path of attachment template in current or parent template.
    484555 *
    485  * The attachment path first checks if the first part of the mime type exists.
    486  * The second check is for the second part of the mime type. The last check is
    487  * for both types separated by an underscore. If neither are found then the file
    488  * 'attachment.php' is checked and returned.
    489  *
    490  * Some examples for the 'text/plain' mime type are 'text.php', 'plain.php', and
    491  * finally 'text-plain.php'.
     556 * The hierarchy for this template looks like:
     557 *
     558 * 1. {mime_type}-{sub_type}.php
     559 * 2. {sub_type}.php
     560 * 3. {mime_type}.php
     561 * 4. attachment.php
     562 *
     563 * An example of this is:
     564 *
     565 * 1. image-jpeg.php
     566 * 2. jpeg.php
     567 * 3. image.php
     568 * 4. attachment.php
    492569 *
    493570 * The template hierarchy is filterable via the {@see 'attachment_template_hierarchy'} hook.
     
    495572 *
    496573 * @since 2.0.0
     574 * @since 4.3.0 The order of the mime type logic was reversed so the hierarchy is more logical.
    497575 *
    498576 * @see get_query_template()
     
    602680    }
    603681}
    604 
Note: See TracChangeset for help on using the changeset viewer.