WordPress.org

Make WordPress Core

Changeset 38789


Ignore:
Timestamp:
10/14/16 14:19:08 (14 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.