X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/177fd6fefd2e3d5a0ea6591c71d660cabdb3c1a4..073c5ed6408e2f00dc1863b463fe205467628905:/wp-includes/category-template.php diff --git a/wp-includes/category-template.php b/wp-includes/category-template.php index ba243020..7063c2d4 100644 --- a/wp-includes/category-template.php +++ b/wp-includes/category-template.php @@ -1,98 +1,135 @@ parent == $id ) { - $chain .= $before.$category->term_id.$after; - $chain .= get_category_children($category->term_id, $before, $after); - } - } - return $chain; -} - -function get_category_link($category_id) { - global $wp_rewrite; - $catlink = $wp_rewrite->get_category_permastruct(); +/** + * Retrieve category link URL. + * + * @since 1.0.0 + * @see get_term_link() + * + * @param int|object $category Category ID or object. + * @return string Link on success, empty string if category does not exist. + */ +function get_category_link( $category ) { + if ( ! is_object( $category ) ) + $category = (int) $category; - if ( empty($catlink) ) { - $file = get_option('home') . '/'; - $catlink = $file . '?cat=' . $category_id; - } else { - $category = &get_category($category_id); - if ( is_wp_error( $category ) ) - return $category; - $category_nicename = $category->slug; + $category = get_term_link( $category, 'category' ); - if ( $parent = $category->parent ) - $category_nicename = get_category_parents($parent, false, '/', true) . $category_nicename; + if ( is_wp_error( $category ) ) + return ''; - $catlink = str_replace('%category%', $category_nicename, $catlink); - $catlink = get_option('home') . user_trailingslashit($catlink, 'category'); - } - return apply_filters('category_link', $catlink, $category_id); + return $category; } -function get_category_parents($id, $link = FALSE, $separator = '/', $nicename = FALSE){ +/** + * Retrieve category parents with separator. + * + * @since 1.2.0 + * + * @param int $id Category ID. + * @param bool $link Optional, default is false. Whether to format with link. + * @param string $separator Optional, default is '/'. How to separate categories. + * @param bool $nicename Optional, default is false. Whether to use nice name for display. + * @param array $visited Optional. Already linked to categories to prevent duplicates. + * @return string|WP_Error A list of category parents on success, WP_Error on failure. + */ +function get_category_parents( $id, $link = false, $separator = '/', $nicename = false, $visited = array() ) { $chain = ''; - $parent = &get_category($id); + $parent = get_term( $id, 'category' ); if ( is_wp_error( $parent ) ) return $parent; if ( $nicename ) $name = $parent->slug; else - $name = $parent->cat_name; + $name = $parent->name; - if ( $parent->parent && ($parent->parent != $parent->term_id) ) - $chain .= get_category_parents($parent->parent, $link, $separator, $nicename); + if ( $parent->parent && ( $parent->parent != $parent->term_id ) && !in_array( $parent->parent, $visited ) ) { + $visited[] = $parent->parent; + $chain .= get_category_parents( $parent->parent, $link, $separator, $nicename, $visited ); + } if ( $link ) - $chain .= 'cat_name) . '">'.$name.'' . $separator; + $chain .= ''.$name.'' . $separator; else $chain .= $name.$separator; return $chain; } -function get_the_category($id = false) { - global $post; - - $id = (int) $id; - if ( !$id ) - $id = (int) $post->ID; - - $categories = get_object_term_cache($id, 'category'); - if ( false === $categories ) - $categories = wp_get_object_terms($id, 'category'); - - if ( !empty($categories) ) - usort($categories, '_usort_terms_by_name'); - else +/** + * Retrieve post categories. + * + * This tag may be used outside The Loop by passing a post id as the parameter. + * + * Note: This function only returns results from the default "category" taxonomy. + * For custom taxonomies use get_the_terms(). + * + * @since 0.71 + * + * @param int $id Optional, default to current post ID. The post ID. + * @return array Array of WP_Term objects, one for each category assigned to the post. + */ +function get_the_category( $id = false ) { + $categories = get_the_terms( $id, 'category' ); + if ( ! $categories || is_wp_error( $categories ) ) $categories = array(); - foreach(array_keys($categories) as $key) { - _make_cat_compat($categories[$key]); + $categories = array_values( $categories ); + + foreach ( array_keys( $categories ) as $key ) { + _make_cat_compat( $categories[$key] ); } - return $categories; + /** + * Filters the array of categories to return for a post. + * + * @since 3.1.0 + * @since 4.4.0 Added `$id` parameter. + * + * @param array $categories An array of categories to return for the post. + * @param int $id ID of the post. + */ + return apply_filters( 'get_the_categories', $categories, $id ); } -function _usort_terms_by_name($a, $b) { - return strcmp($a->name, $b->name); +/** + * Sort categories by name. + * + * Used by usort() as a callback, should not be used directly. Can actually be + * used to sort any term object. + * + * @since 2.3.0 + * @access private + * + * @param object $a + * @param object $b + * @return int + */ +function _usort_terms_by_name( $a, $b ) { + return strcmp( $a->name, $b->name ); } -function _usort_terms_by_ID($a, $b) { +/** + * Sort categories by ID. + * + * Used by usort() as a callback, should not be used directly. Can actually be + * used to sort any term object. + * + * @since 2.3.0 + * @access private + * + * @param object $a + * @param object $b + * @return int + */ +function _usort_terms_by_ID( $a, $b ) { if ( $a->term_id > $b->term_id ) return 1; elseif ( $a->term_id < $b->term_id ) @@ -101,42 +138,81 @@ function _usort_terms_by_ID($a, $b) { return 0; } -function get_the_category_by_ID($cat_ID) { +/** + * Retrieve category name based on category ID. + * + * @since 0.71 + * + * @param int $cat_ID Category ID. + * @return string|WP_Error Category name on success, WP_Error on failure. + */ +function get_the_category_by_ID( $cat_ID ) { $cat_ID = (int) $cat_ID; - $category = &get_category($cat_ID); + $category = get_term( $cat_ID, 'category' ); + if ( is_wp_error( $category ) ) return $category; - return $category->name; + + return ( $category ) ? $category->name : ''; } -function get_the_category_list($separator = '', $parents='', $post_id = false) { +/** + * Retrieve category list in either HTML list or custom format. + * + * @since 1.5.1 + * + * @global WP_Rewrite $wp_rewrite + * + * @param string $separator Optional, default is empty string. Separator for between the categories. + * @param string $parents Optional. How to display the parents. + * @param int $post_id Optional. Post ID to retrieve categories. + * @return string + */ +function get_the_category_list( $separator = '', $parents='', $post_id = false ) { global $wp_rewrite; - $categories = get_the_category($post_id); - if (empty($categories)) - return apply_filters('the_category', __('Uncategorized'), $separator, $parents); + 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 ); + } + + /** + * Filters the categories before building the category list. + * + * @since 4.4.0 + * + * @param array $categories An array of the post's categories. + * @param int|bool $post_id ID of the post we're retrieving categories for. When `false`, we assume the + * current post in the loop. + */ + $categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id ); + + 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"'; + $rel = ( is_object( $wp_rewrite ) && $wp_rewrite->using_permalinks() ) ? 'rel="category tag"' : 'rel="category"'; $thelist = ''; if ( '' == $separator ) { $thelist .= ''; @@ -144,362 +220,997 @@ function get_the_category_list($separator = '', $parents='', $post_id = false) { $i = 0; foreach ( $categories as $category ) { if ( 0 < $i ) - $thelist .= $separator . ' '; - switch ( strtolower($parents) ) { + $thelist .= $separator; + switch ( strtolower( $parents ) ) { case 'multiple': if ( $category->parent ) - $thelist .= get_category_parents($category->parent, TRUE); - $thelist .= 'name) . '" ' . $rel . '>' . $category->cat_name.''; + $thelist .= get_category_parents( $category->parent, true, $separator ); + $thelist .= '' . $category->name.''; break; case 'single': - $thelist .= 'name) . '" ' . $rel . '>'; + $thelist .= ''; if ( $category->parent ) - $thelist .= get_category_parents($category->parent, FALSE); - $thelist .= "$category->cat_name"; + $thelist .= get_category_parents( $category->parent, false, $separator ); + $thelist .= "$category->name"; break; case '': default: - $thelist .= 'name) . '" ' . $rel . '>' . $category->name.''; + $thelist .= '' . $category->name.''; } ++$i; } } - return apply_filters('the_category', $thelist, $separator, $parents); + + /** + * Filters 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 ); } -/* - * in_category() - Checks whether the current post is within a particular category +/** + * Check if the current post in within any of the given categories. * - * This function checks to see if the post is within the supplied category. The categoy - * can be specified by number or name and will be checked as a name first to allow for categories with numeric names. - * Note: Prior to v2.5 of WordPress category names where not supported. + * The given categories are checked against the post's categories' term_ids, names and slugs. + * Categories given as integers will only be checked against the post's categories' term_ids. + * + * Prior to v2.5 of WordPress, category names were not supported. + * Prior to v2.7, category slugs were not supported. + * Prior to v2.7, only one category could be compared: in_category( $single_category ). + * Prior to v2.7, this function could only be used in the WordPress Loop. + * As of 2.7, the function can be used anywhere if it is provided a post ID or post object. * * @since 1.2.0 * - * @param int|string $category - * @return bool true if the post is in the supplied category -*/ -function in_category( $category ) { // Check if the current post is in the given category - global $post; - - if ( empty($category) ) + * @param int|string|array $category Category ID, name or slug, or array of said. + * @param int|object $post Optional. Post to check instead of the current post. (since 2.7.0) + * @return bool True if the current post is in any of the given categories. + */ +function in_category( $category, $post = null ) { + if ( empty( $category ) ) return false; - $cat_ID = get_cat_ID($category); - if ( $cat_ID ) - $category = $cat_ID; - - $categories = get_object_term_cache($post->ID, 'category'); - if ( false === $categories ) - $categories = wp_get_object_terms($post->ID, 'category'); - if ( array_key_exists($category, $categories) ) - return true; - else - return false; + return has_category( $category, $post ); } -function the_category($separator = '', $parents='', $post_id = false) { - echo get_the_category_list($separator, $parents, $post_id); +/** + * Display the category list for the post. + * + * @since 0.71 + * + * @param string $separator Optional, default is empty string. Separator for between the categories. + * @param string $parents Optional. How to display the parents. + * @param int $post_id Optional. Post ID to retrieve categories. + */ +function the_category( $separator = '', $parents='', $post_id = false ) { + echo get_the_category_list( $separator, $parents, $post_id ); } -function category_description($category = 0) { - global $cat; - if ( !$category ) - $category = $cat; - - return get_term_field('description', $category, 'category'); +/** + * Retrieve category description. + * + * @since 1.0.0 + * + * @param int $category Optional. Category ID. Will use global category ID by default. + * @return string Category description, available. + */ +function category_description( $category = 0 ) { + return term_description( $category, 'category' ); } -function wp_dropdown_categories($args = '') { +/** + * Display or retrieve the HTML dropdown list of categories. + * + * The 'hierarchical' argument, which is disabled by default, will override the + * depth argument, unless it is true. When the argument is false, it will + * display all of the categories. When it is enabled it will use the value in + * the 'depth' argument. + * + * @since 2.1.0 + * @since 4.2.0 Introduced the `value_field` argument. + * @since 4.6.0 Introduced the `required` argument. + * + * @param string|array $args { + * Optional. Array or string of arguments to generate a categories drop-down element. + * + * @type string $show_option_all Text to display for showing all categories. Default empty. + * @type string $show_option_none Text to display for showing no categories. Default empty. + * @type string $option_none_value Value to use when no category is selected. Default empty. + * @type string $orderby Which column to use for ordering categories. See get_terms() for a list + * of accepted values. Default 'id' (term_id). + * @type string $order Whether to order terms in ascending or descending order. Accepts 'ASC' + * or 'DESC'. Default 'ASC'. + * @type bool $pad_counts See get_terms() for an argument description. Default false. + * @type bool|int $show_count Whether to include post counts. Accepts 0, 1, or their bool equivalents. + * Default 0. + * @type bool|int $hide_empty Whether to hide categories that don't have any posts. Accepts 0, 1, or + * their bool equivalents. Default 1. + * @type int $child_of Term ID to retrieve child terms of. See get_terms(). Default 0. + * @type array|string $exclude Array or comma/space-separated string of term ids to exclude. + * If `$include` is non-empty, `$exclude` is ignored. Default empty array. + * @type bool|int $echo Whether to echo or return the generated markup. Accepts 0, 1, or their + * bool equivalents. Default 1. + * @type bool|int $hierarchical Whether to traverse the taxonomy hierarchy. Accepts 0, 1, or their bool + * equivalents. Default 0. + * @type int $depth Maximum depth. Default 0. + * @type int $tab_index Tab index for the select element. Default 0 (no tabindex). + * @type string $name Value for the 'name' attribute of the select element. Default 'cat'. + * @type string $id Value for the 'id' attribute of the select element. Defaults to the value + * of `$name`. + * @type string $class Value for the 'class' attribute of the select element. Default 'postform'. + * @type int|string $selected Value of the option that should be selected. Default 0. + * @type string $value_field Term field that should be used to populate the 'value' attribute + * of the option elements. Accepts any valid term field: 'term_id', 'name', + * 'slug', 'term_group', 'term_taxonomy_id', 'taxonomy', 'description', + * 'parent', 'count'. Default 'term_id'. + * @type string|array $taxonomy Name of the category or categories to retrieve. Default 'category'. + * @type bool $hide_if_empty True to skip generating markup if no categories are found. + * Default false (create select element even if no categories are found). + * @type bool $required Whether the `\n"; + $name = esc_attr( $r['name'] ); + $class = esc_attr( $r['class'] ); + $id = $r['id'] ? esc_attr( $r['id'] ) : $name; + $required = $r['required'] ? 'required' : ''; - if ( $show_option_all ) { - $show_option_all = apply_filters('list_cats', $show_option_all); - $output .= "\t\n"; + if ( ! $r['hide_if_empty'] || ! empty( $categories ) ) { + $output = "\n"; } - - $output = apply_filters('wp_dropdown_cats', $output); - - if ( $echo ) + /** + * Filters the taxonomy drop-down output. + * + * @since 2.1.0 + * + * @param string $output HTML output. + * @param array $r Arguments used to build the drop-down. + */ + $output = apply_filters( 'wp_dropdown_cats', $output, $r ); + + if ( $r['echo'] ) { echo $output; - + } return $output; } -function wp_list_categories($args = '') { +/** + * Display or retrieve the HTML list of categories. + * + * @since 2.1.0 + * @since 4.4.0 Introduced the `hide_title_if_empty` and `separator` arguments. The `current_category` argument was modified to + * optionally accept an array of values. + * + * @param string|array $args { + * Array of optional arguments. + * + * @type int $child_of Term ID to retrieve child terms of. See get_terms(). Default 0. + * @type int|array $current_category ID of category, or array of IDs of categories, that should get the + * 'current-cat' class. Default 0. + * @type int $depth Category depth. Used for tab indentation. Default 0. + * @type bool|int $echo True to echo markup, false to return it. Default 1. + * @type array|string $exclude Array or comma/space-separated string of term IDs to exclude. + * If `$hierarchical` is true, descendants of `$exclude` terms will also + * be excluded; see `$exclude_tree`. See get_terms(). + * Default empty string. + * @type array|string $exclude_tree Array or comma/space-separated string of term IDs to exclude, along + * with their descendants. See get_terms(). Default empty string. + * @type string $feed Text to use for the feed link. Default 'Feed for all posts filed + * under [cat name]'. + * @type string $feed_image URL of an image to use for the feed link. Default empty string. + * @type string $feed_type Feed type. Used to build feed link. See get_term_feed_link(). + * Default empty string (default feed). + * @type bool|int $hide_empty Whether to hide categories that don't have any posts attached to them. + * Default 1. + * @type bool $hide_title_if_empty Whether to hide the `$title_li` element if there are no terms in + * the list. Default false (title will always be shown). + * @type bool $hierarchical Whether to include terms that have non-empty descendants. + * See get_terms(). Default true. + * @type string $order Which direction to order categories. Accepts 'ASC' or 'DESC'. + * Default 'ASC'. + * @type string $orderby The column to use for ordering categories. Default 'ID'. + * @type string $separator Separator between links. Default '
'. + * @type bool|int $show_count Whether to show how many posts are in the category. Default 0. + * @type string $show_option_all Text to display for showing all categories. Default empty string. + * @type string $show_option_none Text to display for the 'no categories' option. + * Default 'No categories'. + * @type string $style The style used to display the categories list. If 'list', categories + * will be output as an unordered list. If left empty or another value, + * categories will be output separated by `
` tags. Default 'list'. + * @type string $taxonomy Taxonomy name. Default 'category'. + * @type string $title_li Text to use for the list title `
  • ` element. Pass an empty string + * to disable. Default 'Categories'. + * @type bool|int $use_desc_for_title Whether to use the category description as the title attribute. + * Default 1. + * } + * @return false|string HTML content only if 'echo' argument is 0. + */ +function wp_list_categories( $args = '' ) { $defaults = array( - 'show_option_all' => '', 'orderby' => 'name', - 'order' => 'ASC', 'show_last_update' => 0, - 'style' => 'list', 'show_count' => 0, - 'hide_empty' => 1, 'use_desc_for_title' => 1, - 'child_of' => 0, 'feed' => '', 'feed_type' => '', - 'feed_image' => '', 'exclude' => '', - 'hierarchical' => true, 'title_li' => __('Categories'), - 'echo' => 1, 'depth' => 0 + 'child_of' => 0, + 'current_category' => 0, + 'depth' => 0, + 'echo' => 1, + 'exclude' => '', + 'exclude_tree' => '', + 'feed' => '', + 'feed_image' => '', + 'feed_type' => '', + 'hide_empty' => 1, + 'hide_title_if_empty' => false, + 'hierarchical' => true, + 'order' => 'ASC', + 'orderby' => 'name', + 'separator' => '
    ', + 'show_count' => 0, + 'show_option_all' => '', + 'show_option_none' => __( 'No categories' ), + 'style' => 'list', + 'taxonomy' => 'category', + 'title_li' => __( 'Categories' ), + 'use_desc_for_title' => 1, ); $r = wp_parse_args( $args, $defaults ); - if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) { + if ( !isset( $r['pad_counts'] ) && $r['show_count'] && $r['hierarchical'] ) $r['pad_counts'] = true; + + // Descendants of exclusions should be excluded too. + if ( true == $r['hierarchical'] ) { + $exclude_tree = array(); + + if ( $r['exclude_tree'] ) { + $exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $r['exclude_tree'] ) ); + } + + if ( $r['exclude'] ) { + $exclude_tree = array_merge( $exclude_tree, wp_parse_id_list( $r['exclude'] ) ); + } + + $r['exclude_tree'] = $exclude_tree; + $r['exclude'] = ''; } - if ( isset( $r['show_date'] ) ) { - $r['include_last_update_time'] = $r['show_date']; + if ( ! isset( $r['class'] ) ) + $r['class'] = ( 'category' == $r['taxonomy'] ) ? 'categories' : $r['taxonomy']; + + if ( ! taxonomy_exists( $r['taxonomy'] ) ) { + return false; } - extract( $r ); + $show_option_all = $r['show_option_all']; + $show_option_none = $r['show_option_none']; - $categories = get_categories($r); + $categories = get_categories( $r ); $output = ''; - if ( $title_li && 'list' == $style ) - $output = '
  • ' . $r['title_li'] . '