<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[27666] trunk/src/wp-includes/category-template.php: Inline documentation for hooks in wp-includes/category-template.php.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/27666">27666</a></dd>
<dt>Author</dt> <dd>DrewAPicture</dd>
<dt>Date</dt> <dd>2014-03-24 01:34:46 +0000 (Mon, 24 Mar 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>Inline documentation for hooks in wp-includes/category-template.php.
Props kpdesign for the cleanup.
Fixes <a href="http://core.trac.wordpress.org/ticket/27432">#27432</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludescategorytemplatephp">trunk/src/wp-includes/category-template.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludescategorytemplatephp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/category-template.php (27665 => 27666)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/category-template.php 2014-03-24 01:02:06 UTC (rev 27665)
+++ trunk/src/wp-includes/category-template.php 2014-03-24 01:34:46 UTC (rev 27666)
</span><span class="lines">@@ -82,7 +82,13 @@
</span><span class="cx"> _make_cat_compat( $categories[$key] );
</span><span class="cx"> }
</span><span class="cx">
</span><del>- // Filter name is plural because we return alot of categories (possibly more than #13237) not just one
</del><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> return apply_filters( 'get_the_categories', $categories );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -155,12 +161,16 @@
</span><span class="cx"> */
</span><span class="cx"> function get_the_category_list( $separator = '', $parents='', $post_id = false ) {
</span><span class="cx"> global $wp_rewrite;
</span><del>- if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) )
</del><ins>+ if ( ! is_object_in_taxonomy( get_post_type( $post_id ), 'category' ) ) {
+ /** This filter is documented in wp-includes/category-template.php */
</ins><span class="cx"> return apply_filters( 'the_category', '', $separator, $parents );
</span><ins>+ }
</ins><span class="cx">
</span><span class="cx"> $categories = get_the_category( $post_id );
</span><del>- if ( empty( $categories ) )
</del><ins>+ if ( empty( $categories ) ) {
+ /** This filter is documented in wp-includes/category-template.php */
</ins><span class="cx"> return apply_filters( 'the_category', __( 'Uncategorized' ), $separator, $parents );
</span><ins>+ }
</ins><span class="cx">
</span><span class="cx"> $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"';
</span><span class="cx">
</span><span class="lines">@@ -211,6 +221,17 @@
</span><span class="cx"> ++$i;
</span><span class="cx"> }
</span><span class="cx"> }
</span><ins>+
+ /**
+ * 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.
+ */
</ins><span class="cx"> return apply_filters( 'the_category', $thelist, $separator, $parents );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -344,6 +365,21 @@
</span><span class="cx"> $output = '';
</span><span class="cx">
</span><span class="cx"> if ( empty($categories) && ! $r['hide_if_empty'] && !empty($show_option_none) ) {
</span><ins>+
+ /**
+ * 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.
+ */
</ins><span class="cx"> $show_option_none = apply_filters( 'list_cats', $show_option_none );
</span><span class="cx"> $output .= "\t<option value='-1' selected='selected'>$show_option_none</option>\n";
</span><span class="cx"> }
</span><span class="lines">@@ -351,12 +387,16 @@
</span><span class="cx"> if ( ! empty( $categories ) ) {
</span><span class="cx">
</span><span class="cx"> if ( $show_option_all ) {
</span><ins>+
+ /** This filter is documented in wp-includes/category-template.php */
</ins><span class="cx"> $show_option_all = apply_filters( 'list_cats', $show_option_all );
</span><span class="cx"> $selected = ( '0' === strval($r['selected']) ) ? " selected='selected'" : '';
</span><span class="cx"> $output .= "\t<option value='0'$selected>$show_option_all</option>\n";
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> if ( $show_option_none ) {
</span><ins>+
+ /** This filter is documented in wp-includes/category-template.php */
</ins><span class="cx"> $show_option_none = apply_filters( 'list_cats', $show_option_none );
</span><span class="cx"> $selected = ( '-1' === strval($r['selected']) ) ? " selected='selected'" : '';
</span><span class="cx"> $output .= "\t<option value='-1'$selected>$show_option_none</option>\n";
</span><span class="lines">@@ -374,12 +414,12 @@
</span><span class="cx"> $output .= "</select>\n";
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Filter the result of wp_dropdown_categories().
</del><ins>+ * Filter the taxonomy drop-down output.
</ins><span class="cx"> *
</span><span class="cx"> * @since 2.1.0
</span><span class="cx"> *
</span><del>- * @param $output HTML content.
- * @param $r Arguments used to build the dropdown.
</del><ins>+ * @param string $output HTML output.
+ * @param array $r Arguments used to build the drop-down.
</ins><span class="cx"> */
</span><span class="cx"> $output = apply_filters( 'wp_dropdown_cats', $output, $r );
</span><span class="cx">
</span><span class="lines">@@ -493,6 +533,14 @@
</span><span class="cx"> if ( $title_li && 'list' == $style )
</span><span class="cx"> $output .= '</ul></li>';
</span><span class="cx">
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> $output = apply_filters( 'wp_list_categories', $output, $args );
</span><span class="cx">
</span><span class="cx"> if ( $echo )
</span><span class="lines">@@ -559,6 +607,14 @@
</span><span class="cx">
</span><span class="cx"> $return = wp_generate_tag_cloud( $tags, $args ); // Here's where those top tags get sorted according to $args
</span><span class="cx">
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> $return = apply_filters( 'wp_tag_cloud', $return, $args );
</span><span class="cx">
</span><span class="cx"> if ( 'array' == $args['format'] || empty($args['echo']) )
</span><span class="lines">@@ -644,8 +700,16 @@
</span><span class="cx"> $translate_nooped_plural = _n_noop( '%s topic', '%s topics' );
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+ /**
+ * 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.
+ */
</ins><span class="cx"> $tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args );
</span><del>- if ( $tags_sorted != $tags ) { // the tags have been sorted by a plugin
</del><ins>+ if ( $tags_sorted != $tags ) {
</ins><span class="cx"> $tags = $tags_sorted;
</span><span class="cx"> unset($tags_sorted);
</span><span class="cx"> } else {
</span><span class="lines">@@ -716,8 +780,24 @@
</span><span class="cx"> break;
</span><span class="cx"> endswitch;
</span><span class="cx">
</span><del>- if ( $filter )
</del><ins>+ 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.
+ */
</ins><span class="cx"> return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args );
</span><ins>+ }
+
</ins><span class="cx"> else
</span><span class="cx"> return $return;
</span><span class="cx"> }
</span><span class="lines">@@ -866,12 +946,25 @@
</span><span class="cx"> extract($args);
</span><span class="cx">
</span><span class="cx"> $cat_name = esc_attr( $category->name );
</span><ins>+
+ /** This filter is documented in wp-includes/category-template.php */
</ins><span class="cx"> $cat_name = apply_filters( 'list_cats', $cat_name, $category );
</span><ins>+
</ins><span class="cx"> $link = '<a href="' . esc_url( get_term_link($category) ) . '" ';
</span><del>- if ( $use_desc_for_title == 0 || empty($category->description) )
</del><ins>+ if ( $use_desc_for_title == 0 || empty($category->description) ) {
</ins><span class="cx"> $link .= 'title="' . esc_attr( sprintf(__( 'View all posts filed under %s' ), $cat_name) ) . '"';
</span><del>- else
</del><ins>+ } else {
+ /**
+ * Filter the category description for display.
+ *
+ * @since 1.2.0
+ *
+ * @param string $description Category description.
+ * @param object $category Category object.
+ */
</ins><span class="cx"> $link .= 'title="' . esc_attr( strip_tags( apply_filters( 'category_description', $category->description, $category ) ) ) . '"';
</span><ins>+ }
+
</ins><span class="cx"> $link .= '>';
</span><span class="cx"> $link .= $cat_name . '</a>';
</span><span class="cx">
</span><span class="lines">@@ -983,7 +1076,9 @@
</span><span class="cx"> function start_el( &$output, $category, $depth = 0, $args = array(), $id = 0 ) {
</span><span class="cx"> $pad = str_repeat(' ', $depth * 3);
</span><span class="cx">
</span><del>- $cat_name = apply_filters('list_cats', $category->name, $category);
</del><ins>+ /** This filter is documented in wp-includes/category-template.php */
+ $cat_name = apply_filters( 'list_cats', $category->name, $category );
+
</ins><span class="cx"> $output .= "\t<option class=\"level-$depth\" value=\"".$category->term_id."\"";
</span><span class="cx"> if ( $category->term_id == $args['selected'] )
</span><span class="cx"> $output .= ' selected="selected"';
</span><span class="lines">@@ -1024,12 +1119,21 @@
</span><span class="cx"> * Retrieve the tags for a post.
</span><span class="cx"> *
</span><span class="cx"> * @since 2.3.0
</span><del>- * @uses apply_filters() Calls 'get_the_tags' filter on the list of post tags.
</del><span class="cx"> *
</span><span class="cx"> * @param int $id Post ID.
</span><span class="cx"> * @return array|bool Array of tag objects on success, false on failure.
</span><span class="cx"> */
</span><span class="cx"> function get_the_tags( $id = 0 ) {
</span><ins>+
+ /**
+ * Filter the array of tags for the given post.
+ *
+ * @since 2.3.0
+ *
+ * @see get_the_terms()
+ *
+ * @param array $terms An array of tags for the given post.
+ */
</ins><span class="cx"> return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -1037,7 +1141,6 @@
</span><span class="cx"> * Retrieve the tags for a post formatted as a string.
</span><span class="cx"> *
</span><span class="cx"> * @since 2.3.0
</span><del>- * @uses apply_filters() Calls 'the_tags' filter on string list of tags.
</del><span class="cx"> *
</span><span class="cx"> * @param string $before Optional. Before tags.
</span><span class="cx"> * @param string $sep Optional. Between tags.
</span><span class="lines">@@ -1046,6 +1149,18 @@
</span><span class="cx"> * @return string|bool|WP_Error A list of tags on success, false or WP_Error on failure.
</span><span class="cx"> */
</span><span class="cx"> function get_the_tag_list( $before = '', $sep = '', $after = '', $id = 0 ) {
</span><ins>+
+ /**
+ * Filter the tags list for a given post.
+ *
+ * @since 2.3.0
+ *
+ * @param string $tag_list List of tags.
+ * @param string $before String to use before tags.
+ * @param string $sep String to use between the tags.
+ * @param string $after String to use after tags.
+ * @param int $id Post ID.
+ */
</ins><span class="cx"> return apply_filters( 'the_tags', get_the_term_list( $id, 'post_tag', $before, $sep, $after ), $before, $sep, $after, $id );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="lines">@@ -1116,6 +1231,15 @@
</span><span class="cx"> wp_cache_add($post->ID, $terms, $taxonomy . '_relationships');
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+ /**
+ * Filter the list of terms attached to the given post.
+ *
+ * @since 3.1.0
+ *
+ * @param array $terms List of attached terms.
+ * @param int $post_id Post ID.
+ * @param string $taxonomy Name of the taxonomy.
+ */
</ins><span class="cx"> $terms = apply_filters( 'get_the_terms', $terms, $post->ID, $taxonomy );
</span><span class="cx">
</span><span class="cx"> if ( empty( $terms ) )
</span><span class="lines">@@ -1152,6 +1276,16 @@
</span><span class="cx"> $term_links[] = '<a href="' . esc_url( $link ) . '" rel="tag">' . $term->name . '</a>';
</span><span class="cx"> }
</span><span class="cx">
</span><ins>+ /**
+ * Filter the term links for a given taxonomy.
+ *
+ * The dynamic portion of the filter name, $taxonomy, refers
+ * to the taxonomy slug.
+ *
+ * @since 2.5.0
+ *
+ * @param array $term_links An array of term links.
+ */
</ins><span class="cx"> $term_links = apply_filters( "term_links-$taxonomy", $term_links );
</span><span class="cx">
</span><span class="cx"> return $before . join( $sep, $term_links ) . $after;
</span><span class="lines">@@ -1175,7 +1309,18 @@
</span><span class="cx"> if ( is_wp_error( $term_list ) )
</span><span class="cx"> return false;
</span><span class="cx">
</span><del>- echo apply_filters('the_terms', $term_list, $taxonomy, $before, $sep, $after);
</del><ins>+ /**
+ * Filter the list of terms to display.
+ *
+ * @since 2.9.0
+ *
+ * @param array $term_list List of terms to display.
+ * @param string $taxonomy The taxonomy name.
+ * @param string $before String to use before the terms.
+ * @param string $sep String to use between the terms.
+ * @param string $after String to use after the terms.
+ */
+ echo apply_filters( 'the_terms', $term_list, $taxonomy, $before, $sep, $after );
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span></span></pre>
</div>
</div>
</body>
</html>