diff --git a/wp-includes/category-template.php b/wp-includes/category-template.php
index 1e545ee69a..6cf21a20d8 100644
--- a/wp-includes/category-template.php
+++ b/wp-includes/category-template.php
@@ -82,7 +82,13 @@ function get_the_category( $id = false ) {
_make_cat_compat( $categories[$key] );
}
- // Filter name is plural because we return alot of categories (possibly more than #13237) not just one
+ /**
+ * Filter the array of categories to return for a post.
+ *
+ * @since 3.1.0
+ *
+ * @param array $categories An array of categories to return for the post.
+ */
return apply_filters( 'get_the_categories', $categories );
}
@@ -155,12 +161,16 @@ function get_the_category_by_ID( $cat_ID ) {
*/
function get_the_category_list( $separator = '', $parents='', $post_id = false ) {
global $wp_rewrite;
- if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) )
+ if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) {
+ /** This filter is documented in wp-includes/category-template.php */
return apply_filters( 'the_category', '', $separator, $parents );
+ }
$categories = get_the_category( $post_id );
- if ( empty( $categories ) )
+ if ( empty( $categories ) ) {
+ /** This filter is documented in wp-includes/category-template.php */
return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
+ }
$rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';
@@ -211,6 +221,17 @@ function get_the_category_list( $separator = '', $parents='', $post_id = false )
++$i;
}
}
+
+ /**
+ * Filter the category or list of categories.
+ *
+ * @since 1.2.0
+ *
+ * @param array $thelist List of categories for the current post.
+ * @param string $separator Separator used between the categories.
+ * @param string $parents How to display the category parents. Accepts 'multiple',
+ * 'single', or empty.
+ */
return apply_filters( 'the_category', $thelist, $separator, $parents );
}
@@ -344,6 +365,21 @@ function wp_dropdown_categories( $args = '' ) {
$output = '';
if ( empty($categories) && ! $r['hide_if_empty'] && !empty($show_option_none) ) {
+
+ /**
+ * Filter a taxonomy drop-down display element.
+ *
+ * A variety of taxonomy drop-down display elements can be modified
+ * just prior to display via this filter. Filterable arguments include
+ * 'show_option_none', 'show_option_all', and various forms of the
+ * term name.
+ *
+ * @since 1.2.0
+ *
+ * @see wp_dropdown_categories()
+ *
+ * @param string $element Taxonomy element to list.
+ */
$show_option_none = apply_filters( 'list_cats', $show_option_none );
$output .= "\t\n";
}
@@ -351,12 +387,16 @@ function wp_dropdown_categories( $args = '' ) {
if ( ! empty( $categories ) ) {
if ( $show_option_all ) {
+
+ /** This filter is documented in wp-includes/category-template.php */
$show_option_all = apply_filters( 'list_cats', $show_option_all );
$selected = ( '0' === strval($r['selected']) ) ? " selected='selected'" : '';
$output .= "\t\n";
}
if ( $show_option_none ) {
+
+ /** This filter is documented in wp-includes/category-template.php */
$show_option_none = apply_filters( 'list_cats', $show_option_none );
$selected = ( '-1' === strval($r['selected']) ) ? " selected='selected'" : '';
$output .= "\t\n";
@@ -374,12 +414,12 @@ function wp_dropdown_categories( $args = '' ) {
$output .= "\n";
/**
- * Filter the result of wp_dropdown_categories().
+ * Filter the taxonomy drop-down output.
*
* @since 2.1.0
*
- * @param $output HTML content.
- * @param $r Arguments used to build the dropdown.
+ * @param string $output HTML output.
+ * @param array $r Arguments used to build the drop-down.
*/
$output = apply_filters( 'wp_dropdown_cats', $output, $r );
@@ -493,6 +533,14 @@ function wp_list_categories( $args = '' ) {
if ( $title_li && 'list' == $style )
$output .= '';
+ /**
+ * Filter the HTML output of a taxonomy list.
+ *
+ * @since 2.1.0
+ *
+ * @param string $output HTML output.
+ * @param array $args An array of taxonomy-listing arguments.
+ */
$output = apply_filters( 'wp_list_categories', $output, $args );
if ( $echo )
@@ -559,6 +607,14 @@ function wp_tag_cloud( $args = '' ) {
$return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args
+ /**
+ * Filter the tag cloud output.
+ *
+ * @since 2.3.0
+ *
+ * @param string $return HTML output of the tag cloud.
+ * @param array $args An array of tag cloud arguments.
+ */
$return = apply_filters( 'wp_tag_cloud', $return, $args );
if ( 'array' == $args['format'] || empty($args['echo']) )
@@ -644,8 +700,16 @@ function wp_generate_tag_cloud( $tags, $args = '' ) {
$translate_nooped_plural = _n_noop( '%s topic', '%s topics' );
}
+ /**
+ * Filter how the items in a tag cloud are sorted.
+ *
+ * @since 2.8.0
+ *
+ * @param array $tags Ordered array of terms.
+ * @param array $args An array of tag cloud arguments.
+ */
$tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args );
- if ( $tags_sorted != $tags ) { // the tags have been sorted by a plugin
+ if ( $tags_sorted != $tags ) {
$tags = $tags_sorted;
unset($tags_sorted);
} else {
@@ -716,8 +780,24 @@ function wp_generate_tag_cloud( $tags, $args = '' ) {
break;
endswitch;
- if ( $filter )
+ if ( $filter ) {
+ /**
+ * Filter the generated output of a tag cloud.
+ *
+ * The filter is only evaluated if a true value is passed
+ * to the $filter argument in wp_generate_tag_cloud().
+ *
+ * @since 2.3.0
+ *
+ * @see wp_generate_tag_cloud()
+ *
+ * @param string $return Generated HTML output of the tag cloud.
+ * @param array $tags An array of terms used in the tag cloud.
+ * @param array $args An array of wp_generate_tag_cloud() arguments.
+ */
return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args );
+ }
+
else
return $return;
}
@@ -866,12 +946,25 @@ class Walker_Category extends Walker {
extract($args);
$cat_name = esc_attr( $category->name );
+
+ /** This filter is documented in wp-includes/category-template.php */
$cat_name = apply_filters( 'list_cats', $cat_name, $category );
+
$link = 'description) )
+ if ( $use_desc_for_title == 0 || empty($category->description) ) {
$link .= 'title="' . esc_attr( sprintf(__( 'View all posts filed under %s' ), $cat_name) ) . '"';
- else
+ } else {
+ /**
+ * Filter the category description for display.
+ *
+ * @since 1.2.0
+ *
+ * @param string $description Category description.
+ * @param object $category Category object.
+ */
$link .= 'title="' . esc_attr( strip_tags( apply_filters( 'category_description', $category->description, $category ) ) ) . '"';
+ }
+
$link .= '>';
$link .= $cat_name . '';
@@ -983,7 +1076,9 @@ class Walker_CategoryDropdown extends Walker {
function start_el( &$output, $category, $depth = 0, $args = array(), $id = 0 ) {
$pad = str_repeat(' ', $depth * 3);
- $cat_name = apply_filters('list_cats', $category->name, $category);
+ /** This filter is documented in wp-includes/category-template.php */
+ $cat_name = apply_filters( 'list_cats', $category->name, $category );
+
$output .= "\t