WordPress.org
Get WordPress

Make WordPress Core

Changeset 27666


Ignore:
Timestamp:
03/24/2014 01:34:46 AM (11 years ago)
Author:
DrewAPicture
Message:

Inline documentation for hooks in wp-includes/category-template.php.

Props kpdesign for the cleanup.
Fixes #27432.

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r27521 r27666  
    8383    }
    8484
    85     // Filter name is plural because we return alot of categories (possibly more than #13237) not just one
     85    /**
     86     * Filter the array of categories to return for a post.
     87     *
     88     * @since 3.1.0
     89     *
     90     * @param array $categories An array of categories to return for the post.
     91     */
    8692    return apply_filters( 'get_the_categories', $categories );
    8793}
    … …  
    156162function get_the_category_list( $separator = '', $parents='', $post_id = false ) {
    157163    global $wp_rewrite;
    158     if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) )
     164    if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) {
     165        /** This filter is documented in wp-includes/category-template.php */
    159166        return apply_filters( 'the_category', '', $separator, $parents );
     167    }
    160168
    161169    $categories = get_the_category( $post_id );
    162     if ( empty( $categories ) )
     170    if ( empty( $categories ) ) {
     171        /** This filter is documented in wp-includes/category-template.php */
    163172        return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
     173    }
    164174
    165175    $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';
    … …  
    212222        }
    213223    }
     224
     225    /**
     226     * Filter the category or list of categories.
     227     *
     228     * @since 1.2.0
     229     *
     230     * @param array  $thelist   List of categories for the current post.
     231     * @param string $separator Separator used between the categories.
     232     * @param string $parents   How to display the category parents. Accepts 'multiple',
     233     *                          'single', or empty.
     234     */
    214235    return apply_filters( 'the_category', $thelist, $separator, $parents );
    215236}
    … …  
    345366
    346367    if ( empty($categories) && ! $r['hide_if_empty'] && !empty($show_option_none) ) {
     368
     369        /**
     370         * Filter a taxonomy drop-down display element.
     371         *
     372         * A variety of taxonomy drop-down display elements can be modified
     373         * just prior to display via this filter. Filterable arguments include
     374         * 'show_option_none', 'show_option_all', and various forms of the
     375         * term name.
     376         *
     377         * @since 1.2.0
     378         *
     379         * @see wp_dropdown_categories()
     380         *
     381         * @param string $element Taxonomy element to list.
     382         */
    347383        $show_option_none = apply_filters( 'list_cats', $show_option_none );
    348384        $output .= "\t<option value='-1' selected='selected'>$show_option_none</option>\n";
    … …  
    352388
    353389        if ( $show_option_all ) {
     390
     391            /** This filter is documented in wp-includes/category-template.php */
    354392            $show_option_all = apply_filters( 'list_cats', $show_option_all );
    355393            $selected = ( '0' === strval($r['selected']) ) ? " selected='selected'" : '';
    … …  
    358396
    359397        if ( $show_option_none ) {
     398
     399            /** This filter is documented in wp-includes/category-template.php */
    360400            $show_option_none = apply_filters( 'list_cats', $show_option_none );
    361401            $selected = ( '-1' === strval($r['selected']) ) ? " selected='selected'" : '';
    … …  
    375415
    376416    /**
    377      * Filter the result of wp_dropdown_categories().
     417     * Filter the taxonomy drop-down output.
    378418     *
    379419     * @since 2.1.0
    380420     *
    381      * @param $output HTML content.
    382      * @param $r      Arguments used to build the dropdown.
     421     * @param string $output HTML output.
     422     * @param array  $r      Arguments used to build the drop-down.
    383423     */
    384424    $output = apply_filters( 'wp_dropdown_cats', $output, $r );
    … …  
    494534        $output .= '</ul></li>';
    495535
     536    /**
     537     * Filter the HTML output of a taxonomy list.
     538     *
     539     * @since 2.1.0
     540     *
     541     * @param string $output HTML output.
     542     * @param array  $args   An array of taxonomy-listing arguments.
     543     */
    496544    $output = apply_filters( 'wp_list_categories', $output, $args );
    497545
    … …  
    560608    $return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args
    561609
     610    /**
     611     * Filter the tag cloud output.
     612     *
     613     * @since 2.3.0
     614     *
     615     * @param string $return HTML output of the tag cloud.
     616     * @param array  $args   An array of tag cloud arguments.
     617     */
    562618    $return = apply_filters( 'wp_tag_cloud', $return, $args );
    563619
    … …  
    645701    }
    646702
     703    /**
     704     * Filter how the items in a tag cloud are sorted.
     705     *
     706     * @since 2.8.0
     707     *
     708     * @param array $tags Ordered array of terms.
     709     * @param array $args An array of tag cloud arguments.
     710     */
    647711    $tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args );
    648     if ( $tags_sorted != $tags  ) { // the tags have been sorted by a plugin
     712    if ( $tags_sorted != $tags  ) {
    649713        $tags = $tags_sorted;
    650714        unset($tags_sorted);
    … …  
    717781    endswitch;
    718782
    719     if ( $filter )
     783    if ( $filter ) {
     784        /**
     785         * Filter the generated output of a tag cloud.
     786         *
     787         * The filter is only evaluated if a true value is passed
     788         * to the $filter argument in wp_generate_tag_cloud().
     789         *
     790         * @since 2.3.0
     791         *
     792         * @see wp_generate_tag_cloud()
     793         *
     794         * @param string $return Generated HTML output of the tag cloud.
     795         * @param array  $tags   An array of terms used in the tag cloud.
     796         * @param array  $args   An array of wp_generate_tag_cloud() arguments.
     797         */
    720798        return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args );
     799    }
     800
    721801    else
    722802        return $return;
    … …  
    867947
    868948        $cat_name = esc_attr( $category->name );
     949
     950        /** This filter is documented in wp-includes/category-template.php */
    869951        $cat_name = apply_filters( 'list_cats', $cat_name, $category );
     952
    870953        $link = '<a href="' . esc_url( get_term_link($category) ) . '" ';
    871         if ( $use_desc_for_title == 0 || empty($category->description) )
     954        if ( $use_desc_for_title == 0 || empty($category->description) ) {
    872955            $link .= 'title="' . esc_attr( sprintf(__( 'View all posts filed under %s' ), $cat_name) ) . '"';
    873         else
     956        } else {
     957            /**
     958             * Filter the category description for display.
     959             *
     960             * @since 1.2.0
     961             *
     962             * @param string $description Category description.
     963             * @param object $category    Category object.
     964             */
    874965            $link .= 'title="' . esc_attr( strip_tags( apply_filters( 'category_description', $category->description, $category ) ) ) . '"';
     966        }
     967
    875968        $link .= '>';
    876969        $link .= $cat_name . '</a>';
    … …  
    9841077        $pad = str_repeat('&nbsp;', $depth * 3);
    9851078
    986         $cat_name = apply_filters('list_cats', $category->name, $category);
     1079        /** This filter is documented in wp-includes/category-template.php */
     1080        $cat_name = apply_filters( 'list_cats', $category->name, $category );
     1081
    9871082        $output .= "\t<option class=\"level-$depth\" value=\"".$category->term_id."\"";
    9881083        if ( $category->term_id == $args['selected'] )
    … …  
    10251120 *
    10261121 * @since 2.3.0
    1027  * @uses apply_filters() Calls 'get_the_tags' filter on the list of post tags.
    10281122 *
    10291123 * @param int $id Post ID.
    … …  
    10311125 */
    10321126function get_the_tags( $id = 0 ) {
     1127
     1128    /**
     1129     * Filter the array of tags for the given post.
     1130     *
     1131     * @since 2.3.0
     1132     *
     1133     * @see get_the_terms()
     1134     *
     1135     * @param array $terms An array of tags for the given post.
     1136     */
    10331137    return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) );
    10341138}
    … …  
    10381142 *
    10391143 * @since 2.3.0
    1040  * @uses apply_filters() Calls 'the_tags' filter on string list of tags.
    10411144 *
    10421145 * @param string $before Optional. Before tags.
    … …  
    10471150 */
    10481151function get_the_tag_list( $before = '', $sep = '', $after = '', $id = 0 ) {
     1152
     1153    /**
     1154     * Filter the tags list for a given post.
     1155     *
     1156     * @since 2.3.0
     1157     *
     1158     * @param string $tag_list List of tags.
     1159     * @param string $before   String to use before tags.
     1160     * @param string $sep      String to use between the tags.
     1161     * @param string $after    String to use after tags.
     1162     * @param int    $id       Post ID.
     1163     */
    10491164    return apply_filters( 'the_tags', get_the_term_list( $id, 'post_tag', $before, $sep, $after ), $before, $sep, $after, $id );
    10501165}
    … …  
    11171232    }
    11181233
     1234    /**
     1235     * Filter the list of terms attached to the given post.
     1236     *
     1237     * @since 3.1.0
     1238     *
     1239     * @param array  $terms    List of attached terms.
     1240     * @param int    $post_id  Post ID.
     1241     * @param string $taxonomy Name of the taxonomy.
     1242     */
    11191243    $terms = apply_filters( 'get_the_terms', $terms, $post->ID, $taxonomy );
    11201244
    … …  
    11531277    }
    11541278
     1279    /**
     1280     * Filter the term links for a given taxonomy.
     1281     *
     1282     * The dynamic portion of the filter name, $taxonomy, refers
     1283     * to the taxonomy slug.
     1284     *
     1285     * @since 2.5.0
     1286     *
     1287     * @param array $term_links An array of term links.
     1288     */
    11551289    $term_links = apply_filters( "term_links-$taxonomy", $term_links );
    11561290
    … …  
    11761310        return false;
    11771311
    1178     echo apply_filters('the_terms', $term_list, $taxonomy, $before, $sep, $after);
     1312    /**
     1313     * Filter the list of terms to display.
     1314     *
     1315     * @since 2.9.0
     1316     *
     1317     * @param array  $term_list List of terms to display.
     1318     * @param string $taxonomy  The taxonomy name.
     1319     * @param string $before    String to use before the terms.
     1320     * @param string $sep       String to use between the terms.
     1321     * @param string $after     String to use after the terms.
     1322     */
     1323    echo apply_filters( 'the_terms', $term_list, $taxonomy, $before, $sep, $after );
    11791324}
    11801325
Note: See TracChangeset for help on using the changeset viewer.