<!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('&nbsp;', $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>