WordPress.org
Get WordPress

Make WordPress Core

Changeset 8975


Ignore:
Timestamp:
09/25/2008 02:16:27 PM (16 years ago)
Author:
azaozz
Message:

Complete inline documentation for category-template.php, props jacobsantos, fixes #5634

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/category-template.php

    r8668 r8975  
    11<?php
    2 
     2/**
     3 * Category Template Tags and API.
     4 *
     5 * @package WordPress
     6 * @subpackage Template
     7 */
     8
     9/**
     10 * Retrieve category children list separated before and after the term IDs.
     11 *
     12 * @since 1.2.0
     13 *
     14 * @param int $id Category ID to retrieve children.
     15 * @param string $before Optional. Prepend before category term ID.
     16 * @param string $after Optional, default is empty string. Append after category term ID.
     17 * @param array $visited Optional. Category Term IDs that have already been added.
     18 * @return string
     19 */
    320function get_category_children( $id, $before = '/', $after = '', $visited = array() ) {
    421    if ( 0 == $id )
    … …  
    623
    724    $chain = '';
    8     // TODO: consult hierarchy
     25    /** TODO: consult hierarchy */
    926    $cat_ids = get_all_category_ids();
    1027    foreach ( (array) $cat_ids as $cat_id ) {
    … …  
    2441}
    2542
     43/**
     44 * Retrieve category link URL.
     45 *
     46 * @since 1.0.0
     47 * @uses apply_filters() Calls 'category_link' filter on category link and category ID.
     48 *
     49 * @param int $category_id Category ID.
     50 * @return string
     51 */
    2652function get_category_link( $category_id ) {
    2753    global $wp_rewrite;
    … …  
    4672}
    4773
    48 function get_category_parents( $id, $link = FALSE, $separator = '/', $nicename = FALSE, $visited = array() ) {
     74/**
     75 * Retrieve category parents with separator.
     76 *
     77 * @since 1.2.0
     78 *
     79 * @param int $id Category ID.
     80 * @param bool $link Optional, default is false. Whether to format with link.
     81 * @param string $separator Optional, default is '/'. How to separate categories.
     82 * @param bool $nicename Optional, default is false. Whether to use nice name for display.
     83 * @param array $visited Optional. Already linked to categories to prevent duplicates.
     84 * @return string
     85 */
     86function get_category_parents( $id, $link = false, $separator = '/', $nicename = false, $visited = array() ) {
    4987    $chain = '';
    5088    $parent = &get_category( $id );
    … …  
    69107}
    70108
     109/**
     110 * Retrieve post categories.
     111 *
     112 * @since 0.71
     113 * @uses $post
     114 *
     115 * @param int $id Optional, default to current post ID. The post ID.
     116 * @return array
     117 */
    71118function get_the_category( $id = false ) {
    72119    global $post;
    … …  
    92139}
    93140
     141/**
     142 * Sort categories by name.
     143 *
     144 * Used by usort() as a callback, should not be used directly. Can actually be
     145 * used to sort any term object.
     146 *
     147 * @since 2.3.0
     148 * @access private
     149 *
     150 * @param object $a
     151 * @param object $b
     152 * @return int
     153 */
    94154function _usort_terms_by_name( $a, $b ) {
    95155    return strcmp( $a->name, $b->name );
    96156}
    97157
     158/**
     159 * Sort categories by ID.
     160 *
     161 * Used by usort() as a callback, should not be used directly. Can actually be
     162 * used to sort any term object.
     163 *
     164 * @since 2.3.0
     165 * @access private
     166 *
     167 * @param object $a
     168 * @param object $b
     169 * @return int
     170 */
    98171function _usort_terms_by_ID( $a, $b ) {
    99172    if ( $a->term_id > $b->term_id )
    … …  
    105178}
    106179
     180/**
     181 * Retrieve category name based on category ID.
     182 *
     183 * @since 0.71
     184 *
     185 * @param int $cat_ID Category ID.
     186 * @return string Category name.
     187 */
    107188function get_the_category_by_ID( $cat_ID ) {
    108189    $cat_ID = (int) $cat_ID;
    … …  
    113194}
    114195
     196/**
     197 * Retrieve category list in either HTML list or custom format.
     198 *
     199 * @since 1.5.1
     200 *
     201 * @param string $separator Optional, default is empty string. Separator for between the categories.
     202 * @param string $parents Optional. How to display the parents.
     203 * @param int $post_id Optional. Post ID to retrieve categories.
     204 * @return string
     205 */
    115206function get_the_category_list( $separator = '', $parents='', $post_id = false ) {
    116207    global $wp_rewrite;
    … …  
    129220                case 'multiple':
    130221                    if ( $category->parent )
    131                         $thelist .= get_category_parents( $category->parent, TRUE );
     222                        $thelist .= get_category_parents( $category->parent, true );
    132223                    $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>' . $category->name.'</a></li>';
    133224                    break;
    … …  
    135226                    $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>';
    136227                    if ( $category->parent )
    137                         $thelist .= get_category_parents( $category->parent, FALSE );
     228                        $thelist .= get_category_parents( $category->parent, false );
    138229                    $thelist .= $category->name.'</a></li>';
    139230                    break;
    … …  
    152243                case 'multiple':
    153244                    if ( $category->parent )
    154                         $thelist .= get_category_parents( $category->parent, TRUE );
     245                        $thelist .= get_category_parents( $category->parent, true );
    155246                    $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>' . $category->cat_name.'</a>';
    156247                    break;
    … …  
    158249                    $thelist .= '<a href="' . get_category_link( $category->term_id ) . '" title="' . sprintf( __( "View all posts in %s" ), $category->name ) . '" ' . $rel . '>';
    159250                    if ( $category->parent )
    160                         $thelist .= get_category_parents( $category->parent, FALSE );
     251                        $thelist .= get_category_parents( $category->parent, false );
    161252                    $thelist .= "$category->cat_name</a>";
    162253                    break;
    … …  
    171262}
    172263
    173 /*
    174  * in_category() - Checks whether the current post is within a particular category
    175  *
    176  * This function checks to see if the post is within the supplied category.  The categoy
    177  * can be specified by number or name and will be checked as a name first to allow for categories with numeric names.
    178  * Note: Prior to v2.5 of WordPress category names where not supported.
     264/**
     265 * Checks whether the current post is within a particular category.
     266 *
     267 * This function checks to see if the post is within the supplied category. The
     268 * category can be specified by number or name and will be checked as a name
     269 * first to allow for categories with numeric names. Note: Prior to v2.5 of
     270 * WordPress category names were not supported.
    179271 *
    180272 * @since 1.2.0
    181273 *
    182  * @param int|string $category
    183  * @return bool true if the post is in the supplied category
     274 * @param int|string $category Category ID or category name.
     275 * @return bool True, if the post is in the supplied category.
    184276*/
    185 function in_category( $category ) { // Check if the current post is in the given category
     277function in_category( $category ) {
    186278    global $post;
    187279
    … …  
    205297}
    206298
     299/**
     300 * Display the category list for the post.
     301 *
     302 * @since 0.71
     303 *
     304 * @param string $separator Optional, default is empty string. Separator for between the categories.
     305 * @param string $parents Optional. How to display the parents.
     306 * @param int $post_id Optional. Post ID to retrieve categories.
     307 */
    207308function the_category( $separator = '', $parents='', $post_id = false ) {
    208309    echo get_the_category_list( $separator, $parents, $post_id );
    209310}
    210311
     312/**
     313 * Retrieve category description.
     314 *
     315 * @since 1.0.0
     316 *
     317 * @param int $category Optional. Category ID. Will use global category ID by default.
     318 * @return string Category description, available.
     319 */
    211320function category_description( $category = 0 ) {
    212321    global $cat;
    … …  
    217326}
    218327
     328/**
     329 * Display or retrieve the HTML dropdown list of categories.
     330 *
     331 * The list of arguments is below:
     332 *     'show_option_all' (string) - Text to display for showing all categories.
     333 *     'show_option_none' (string) - Text to display for showing no categories.
     334 *     'orderby' (string) default is 'ID' - What column to use for ordering the
     335 * categories.
     336 *     'order' (string) default is 'ASC' - What direction to order categories.
     337 *     'show_last_update' (bool|int) default is 0 - See {@link get_categories()}
     338 *     'show_count' (bool|int) default is 0 - Whether to show how many posts are
     339 * in the category.
     340 *     'hide_empty' (bool|int) default is 1 - Whether to hide categories that
     341 * don't have any posts attached to them.
     342 *     'child_of' (int) default is 0 - See {@link get_categories()}.
     343 *     'exclude' (string) - See {@link get_categories()}.
     344 *     'echo' (bool|int) default is 1 - Whether to display or retrieve content.
     345 *     'depth' (int) - The max depth.
     346 *     'tab_index' (int) - Tab index for select element.
     347 *     'name' (string) - The name attribute value for selected element.
     348 *     'class' (string) - The class attribute value for selected element.
     349 *     'selected' (int) - Which category ID is selected.
     350 *
     351 * The 'hierarchical' argument, which is disabled by default, will override the
     352 * depth argument, unless it is true. When the argument is false, it will
     353 * display all of the categories. When it is enabled it will use the value in
     354 * the 'depth' argument.
     355 *
     356 * @since 2.1.0
     357 *
     358 * @param string|array $args Optional. Override default arguments.
     359 * @return string HTML content only if 'echo' argument is 0.
     360 */
    219361function wp_dropdown_categories( $args = '' ) {
    220362    $defaults = array(
    … …  
    272414}
    273415
     416/**
     417 * Display or retrieve the HTML list of categories.
     418 *
     419 * The list of arguments is below:
     420 *     'show_option_all' (string) - Text to display for showing all categories.
     421 *     'orderby' (string) default is 'ID' - What column to use for ordering the
     422 * categories.
     423 *     'order' (string) default is 'ASC' - What direction to order categories.
     424 *     'show_last_update' (bool|int) default is 0 - See {@link
     425 * walk_category_dropdown_tree()}
     426 *     'show_count' (bool|int) default is 0 - Whether to show how many posts are
     427 * in the category.
     428 *     'hide_empty' (bool|int) default is 1 - Whether to hide categories that
     429 * don't have any posts attached to them.
     430 *     'use_desc_for_title' (bool|int) default is 1 - Whether to use the
     431 * description instead of the category title.
     432 *     'feed' - See {@link get_categories()}.
     433 *     'feed_type' - See {@link get_categories()}.
     434 *     'feed_image' - See {@link get_categories()}.
     435 *     'child_of' (int) default is 0 - See {@link get_categories()}.
     436 *     'exclude' (string) - See {@link get_categories()}.
     437 *     'echo' (bool|int) default is 1 - Whether to display or retrieve content.
     438 *     'current_category' (int) - See {@link get_categories()}.
     439 *     'hierarchical' (bool) - See {@link get_categories()}.
     440 *     'title_li' (string) - See {@link get_categories()}.
     441 *     'depth' (int) - The max depth.
     442 *
     443 * @since 2.1.0
     444 *
     445 * @param string|array $args Optional. Override default arguments.
     446 * @return string HTML content only if 'echo' argument is 0.
     447 */
    274448function wp_list_categories( $args = '' ) {
    275449    $defaults = array(
    … …  
    338512}
    339513
     514/**
     515 * Display tag cloud.
     516 *
     517 * The text size is set by the 'smallest' and 'largest' arguments, which will
     518 * use the 'unit' argument value for the CSS text size unit. The 'format'
     519 * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
     520 * 'format' argument will separate tags with spaces. The list value for the
     521 * 'format' argument will format the tags in a UL HTML list. The array value for
     522 * the 'format' argument will return in PHP array type format.
     523 *
     524 * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
     525 * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC'.
     526 *
     527 * The 'number' argument is how many tags to return. By default, the limit will
     528 * be to return the top 45 tags in the tag cloud list.
     529 *
     530 * The 'single_text' and 'multiple_text' arguments are used for the link title
     531 * for the tag link. If the tag only has one, it will use the text in the
     532 * 'single_text' or if it has more than one it will use 'multiple_text' instead.
     533 *
     534 * The 'exclude' and 'include' arguments are used for the {@link get_tags()}
     535 * function. Only one should be used, because only one will be used and the
     536 * other ignored, if they are both set.
     537 *
     538 * @since 2.3.0
     539 *
     540 * @param array|string $args Optional. Override default arguments.
     541 * @return array Generated tag cloud, only if no failures and 'array' is set for the 'format' argument.
     542 */
    340543function wp_tag_cloud( $args = '' ) {
    341544    $defaults = array(
    … …  
    371574
    372575/**
    373  * Generates a tag cloud (heatmap) from provided data
    374  *
    375  * TODO: Complete
    376  *
    377  * @since 2.6
    378  *
    379  * $tags = array of objects with the properties 'name', 'link', 'id', and 'count'
    380  * $args['format'] = 'flat' => whitespace separated, 'list' => UL, 'array' => array()
    381  * $args['orderby'] = 'name', 'count'
    382 */
     576 * Generates a tag cloud (heatmap) from provided data.
     577 *
     578 * The text size is set by the 'smallest' and 'largest' arguments, which will
     579 * use the 'unit' argument value for the CSS text size unit. The 'format'
     580 * argument can be 'flat' (default), 'list', or 'array'. The flat value for the
     581 * 'format' argument will separate tags with spaces. The list value for the
     582 * 'format' argument will format the tags in a UL HTML list. The array value for
     583 * the 'format' argument will return in PHP array type format.
     584 *
     585 * The 'orderby' argument will accept 'name' or 'count' and defaults to 'name'.
     586 * The 'order' is the direction to sort, defaults to 'ASC' and can be 'DESC' or
     587 * 'RAND'.
     588 *
     589 * The 'number' argument is how many tags to return. By default, the limit will
     590 * be to return the entire tag cloud list.
     591 *
     592 * The 'single_text' and 'multiple_text' arguments are used for the link title
     593 * for the tag link. If the tag only has one, it will use the text in the
     594 * 'single_text' or if it has more than one it will use 'multiple_text' instead.
     595 *
     596 * @todo Complete functionality.
     597 * @since 2.3.0
     598 *
     599 * @param array $tags List of tags.
     600 * @param string|array $args Optional, override default arguments.
     601 * @return string
     602 */
    383603function wp_generate_tag_cloud( $tags, $args = '' ) {
    384604    global $wp_rewrite;
    … …  
    461681//
    462682
     683/**
     684 * Retrieve HTML list content for category list.
     685 *
     686 * @uses Walker_Category to create HTML list content.
     687 * @since 2.1.0
     688 * @see Walker_Category::walk() for parameters and return description.
     689 */
    463690function walk_category_tree() {
    464691    $walker = new Walker_Category;
    … …  
    467694}
    468695
     696/**
     697 * Retrieve HTML dropdown (select) content for category list.
     698 *
     699 * @uses Walker_CategoryDropdown to create HTML dropdown content.
     700 * @since 2.1.0
     701 * @see Walker_CategoryDropdown::walk() for parameters and return description.
     702 */
    469703function walk_category_dropdown_tree() {
    470704    $walker = new Walker_CategoryDropdown;
    … …  
    477711//
    478712
     713/**
     714 * Retrieve the link to the tag.
     715 *
     716 * @since 2.3.0
     717 * @uses apply_filters() Calls 'tag_link' with tag link and tag ID as parameters.
     718 *
     719 * @param int $tag_id Tag (term) ID.
     720 * @return string
     721 */
    479722function get_tag_link( $tag_id ) {
    480723    global $wp_rewrite;
    … …  
    496739}
    497740
     741/**
     742 * Retrieve the tags for a post.
     743 *
     744 * @since 2.3.0
     745 * @uses apply_filters() Calls 'get_the_tags' filter on the list of post tags.
     746 *
     747 * @param int $id Post ID.
     748 * @return array
     749 */
    498750function get_the_tags( $id = 0 ) {
    499751    return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) );
    500752}
    501753
     754/**
     755 * Retrieve the tags for a post formatted as a string.
     756 *
     757 * @since 2.3.0
     758 * @uses apply_filters() Calls 'the_tags' filter on string list of tags.
     759 *
     760 * @param string $before Optional. Before tags.
     761 * @param string $sep Optional. Between tags.
     762 * @param string $after Optional. After tags.
     763 * @return string
     764 */
    502765function get_the_tag_list( $before = '', $sep = '', $after = '' ) {
    503766    return apply_filters( 'the_tags', get_the_term_list( 0, 'post_tag', $before, $sep, $after ) );
    504767}
    505768
     769/**
     770 * Retrieve the tags for a post.
     771 *
     772 * @since 2.3.0
     773 *
     774 * @param string $before Optional. Before list.
     775 * @param string $sep Optional. Separate items using this.
     776 * @param string $after Optional. After list.
     777 * @return string
     778 */
    506779function the_tags( $before = 'Tags: ', $sep = ', ', $after = '' ) {
    507780    return the_terms( 0, 'post_tag', $before, $sep, $after );
    508781}
    509782
     783/**
     784 * Retrieve the terms of the taxonomy that are attached to the post.
     785 *
     786 * This function can only be used within the loop.
     787 *
     788 * @since 2.5.0
     789 *
     790 * @param int $id Post ID. Is not optional.
     791 * @param string $taxonomy Taxonomy name.
     792 * @return array|bool False on failure. Array of term objects on success.
     793 */
    510794function get_the_terms( $id = 0, $taxonomy ) {
    511795    global $post;
    … …  
    529813}
    530814
     815/**
     816 * Retrieve terms as a list with specified format.
     817 *
     818 * @since 2.5.0
     819 *
     820 * @param int $id Term ID.
     821 * @param string $taxonomy Taxonomy name.
     822 * @param string $before Optional. Before list.
     823 * @param string $sep Optional. Separate items using this.
     824 * @param string $after Optional. After list.
     825 * @return string
     826 */
    531827function get_the_term_list( $id = 0, $taxonomy, $before = '', $sep = '', $after = '' ) {
    532828    $terms = get_the_terms( $id, $taxonomy );
    … …  
    550846}
    551847
     848/**
     849 * Display the terms in a list.
     850 *
     851 * @since 2.5.0
     852 *
     853 * @param int $id Term ID.
     854 * @param string $taxonomy Taxonomy name.
     855 * @param string $before Optional. Before list.
     856 * @param string $sep Optional. Separate items using this.
     857 * @param string $after Optional. After list.
     858 * @return null|bool False on WordPress error. Returns null when displaying.
     859 */
    552860function the_terms( $id, $taxonomy, $before = '', $sep = '', $after = '' ) {
    553861    $return = get_the_term_list( $id, $taxonomy, $before, $sep, $after );
    … …  
    559867
    560868/**
    561  * Check if the current post has the given tag
    562  *
    563  * @package WordPress
    564  * @since 2.6
     869 * Check if the current post has the given tag.
     870 *
     871 * This function is only for use within the WordPress Loop.
     872 *
     873 * @since 2.6.0
    565874 *
    566875 * @uses wp_get_object_terms() Gets the tags.
    567876 *
    568  * @param string|int|array $tag Optional. The tag name/id/slug or array of them to check for
    569  * @return bool True if the current post has the given tag, or any tag, if no tag specified
     877 * @param string|int|array $tag Optional. The tag name/id/slug or array of them to check for.
     878 * @return bool True if the current post has the given tag, or any tag, if no tag specified.
    570879 */
    571880function has_tag( $tag = '' ) {
Note: See TracChangeset for help on using the changeset viewer.