bookmark-template.php (12717B)
1 <?php 2 /** 3 * Bookmark Template Functions for usage in Themes 4 * 5 * @package WordPress 6 * @subpackage Template 7 */ 8 9 /** 10 * The formatted output of a list of bookmarks. 11 * 12 * The $bookmarks array must contain bookmark objects and will be iterated over 13 * to retrieve the bookmark to be used in the output. 14 * 15 * The output is formatted as HTML with no way to change that format. However, 16 * what is between, before, and after can be changed. The link itself will be 17 * HTML. 18 * 19 * This function is used internally by wp_list_bookmarks() and should not be 20 * used by themes. 21 * 22 * @since 2.1.0 23 * @access private 24 * 25 * @param array $bookmarks List of bookmarks to traverse. 26 * @param string|array $args { 27 * Optional. Bookmarks arguments. 28 * 29 * @type int|bool $show_updated Whether to show the time the bookmark was last updated. 30 * Accepts 1|true or 0|false. Default 0|false. 31 * @type int|bool $show_description Whether to show the bookmark description. Accepts 1|true, 32 * Accepts 1|true or 0|false. Default 0|false. 33 * @type int|bool $show_images Whether to show the link image if available. Accepts 1|true 34 * or 0|false. Default 1|true. 35 * @type int|bool $show_name Whether to show link name if available. Accepts 1|true or 36 * 0|false. Default 0|false. 37 * @type string $before The HTML or text to prepend to each bookmark. Default `<li>`. 38 * @type string $after The HTML or text to append to each bookmark. Default `</li>`. 39 * @type string $link_before The HTML or text to prepend to each bookmark inside the anchor 40 * tags. Default empty. 41 * @type string $link_after The HTML or text to append to each bookmark inside the anchor 42 * tags. Default empty. 43 * @type string $between The string for use in between the link, description, and image. 44 * Default "\n". 45 * @type int|bool $show_rating Whether to show the link rating. Accepts 1|true or 0|false. 46 * Default 0|false. 47 * 48 * } 49 * @return string Formatted output in HTML 50 */ 51 function _walk_bookmarks( $bookmarks, $args = '' ) { 52 $defaults = array( 53 'show_updated' => 0, 54 'show_description' => 0, 55 'show_images' => 1, 56 'show_name' => 0, 57 'before' => '<li>', 58 'after' => '</li>', 59 'between' => "\n", 60 'show_rating' => 0, 61 'link_before' => '', 62 'link_after' => '', 63 ); 64 65 $parsed_args = wp_parse_args( $args, $defaults ); 66 67 $output = ''; // Blank string to start with. 68 69 foreach ( (array) $bookmarks as $bookmark ) { 70 if ( ! isset( $bookmark->recently_updated ) ) { 71 $bookmark->recently_updated = false; 72 } 73 $output .= $parsed_args['before']; 74 if ( $parsed_args['show_updated'] && $bookmark->recently_updated ) { 75 $output .= '<em>'; 76 } 77 $the_link = '#'; 78 if ( ! empty( $bookmark->link_url ) ) { 79 $the_link = esc_url( $bookmark->link_url ); 80 } 81 $desc = esc_attr( sanitize_bookmark_field( 'link_description', $bookmark->link_description, $bookmark->link_id, 'display' ) ); 82 $name = esc_attr( sanitize_bookmark_field( 'link_name', $bookmark->link_name, $bookmark->link_id, 'display' ) ); 83 $title = $desc; 84 85 if ( $parsed_args['show_updated'] ) { 86 if ( '00' !== substr( $bookmark->link_updated_f, 0, 2 ) ) { 87 $title .= ' ('; 88 $title .= sprintf( 89 /* translators: %s: Date and time of last update. */ 90 __( 'Last updated: %s' ), 91 gmdate( 92 get_option( 'links_updated_date_format' ), 93 $bookmark->link_updated_f + ( get_option( 'gmt_offset' ) * HOUR_IN_SECONDS ) 94 ) 95 ); 96 $title .= ')'; 97 } 98 } 99 $alt = ' alt="' . $name . ( $parsed_args['show_description'] ? ' ' . $title : '' ) . '"'; 100 101 if ( '' !== $title ) { 102 $title = ' title="' . $title . '"'; 103 } 104 $rel = $bookmark->link_rel; 105 if ( '' !== $rel ) { 106 $rel = ' rel="' . esc_attr( $rel ) . '"'; 107 } 108 $target = $bookmark->link_target; 109 if ( '' !== $target ) { 110 $target = ' target="' . $target . '"'; 111 } 112 $output .= '<a href="' . $the_link . '"' . $rel . $title . $target . '>'; 113 114 $output .= $parsed_args['link_before']; 115 116 if ( null != $bookmark->link_image && $parsed_args['show_images'] ) { 117 if ( strpos( $bookmark->link_image, 'http' ) === 0 ) { 118 $output .= "<img src=\"$bookmark->link_image\" $alt $title />"; 119 } else { // If it's a relative path. 120 $output .= '<img src="' . get_option( 'siteurl' ) . "$bookmark->link_image\" $alt $title />"; 121 } 122 if ( $parsed_args['show_name'] ) { 123 $output .= " $name"; 124 } 125 } else { 126 $output .= $name; 127 } 128 129 $output .= $parsed_args['link_after']; 130 131 $output .= '</a>'; 132 133 if ( $parsed_args['show_updated'] && $bookmark->recently_updated ) { 134 $output .= '</em>'; 135 } 136 137 if ( $parsed_args['show_description'] && '' !== $desc ) { 138 $output .= $parsed_args['between'] . $desc; 139 } 140 141 if ( $parsed_args['show_rating'] ) { 142 $output .= $parsed_args['between'] . sanitize_bookmark_field( 143 'link_rating', 144 $bookmark->link_rating, 145 $bookmark->link_id, 146 'display' 147 ); 148 } 149 $output .= $parsed_args['after'] . "\n"; 150 } // End while. 151 152 return $output; 153 } 154 155 /** 156 * Retrieve or echo all of the bookmarks. 157 * 158 * List of default arguments are as follows: 159 * 160 * These options define how the Category name will appear before the category 161 * links are displayed, if 'categorize' is 1. If 'categorize' is 0, then it will 162 * display for only the 'title_li' string and only if 'title_li' is not empty. 163 * 164 * @since 2.1.0 165 * 166 * @see _walk_bookmarks() 167 * 168 * @param string|array $args { 169 * Optional. String or array of arguments to list bookmarks. 170 * 171 * @type string $orderby How to order the links by. Accepts post fields. Default 'name'. 172 * @type string $order Whether to order bookmarks in ascending or descending order. 173 * Accepts 'ASC' (ascending) or 'DESC' (descending). Default 'ASC'. 174 * @type int $limit Amount of bookmarks to display. Accepts 1+ or -1 for all. 175 * Default -1. 176 * @type string $category Comma-separated list of category IDs to include links from. 177 * Default empty. 178 * @type string $category_name Category to retrieve links for by name. Default empty. 179 * @type int|bool $hide_invisible Whether to show or hide links marked as 'invisible'. Accepts 180 * 1|true or 0|false. Default 1|true. 181 * @type int|bool $show_updated Whether to display the time the bookmark was last updated. 182 * Accepts 1|true or 0|false. Default 0|false. 183 * @type int|bool $echo Whether to echo or return the formatted bookmarks. Accepts 184 * 1|true (echo) or 0|false (return). Default 1|true. 185 * @type int|bool $categorize Whether to show links listed by category or in a single column. 186 * Accepts 1|true (by category) or 0|false (one column). Default 1|true. 187 * @type int|bool $show_description Whether to show the bookmark descriptions. Accepts 1|true or 0|false. 188 * Default 0|false. 189 * @type string $title_li What to show before the links appear. Default 'Bookmarks'. 190 * @type string $title_before The HTML or text to prepend to the $title_li string. Default '<h2>'. 191 * @type string $title_after The HTML or text to append to the $title_li string. Default '</h2>'. 192 * @type string|array $class The CSS class or an array of classes to use for the $title_li. 193 * Default 'linkcat'. 194 * @type string $category_before The HTML or text to prepend to $title_before if $categorize is true. 195 * String must contain '%id' and '%class' to inherit the category ID and 196 * the $class argument used for formatting in themes. 197 * Default '<li id="%id" class="%class">'. 198 * @type string $category_after The HTML or text to append to $title_after if $categorize is true. 199 * Default '</li>'. 200 * @type string $category_orderby How to order the bookmark category based on term scheme if $categorize 201 * is true. Default 'name'. 202 * @type string $category_order Whether to order categories in ascending or descending order if 203 * $categorize is true. Accepts 'ASC' (ascending) or 'DESC' (descending). 204 * Default 'ASC'. 205 * } 206 * @return void|string Void if 'echo' argument is true, HTML list of bookmarks if 'echo' is false. 207 */ 208 function wp_list_bookmarks( $args = '' ) { 209 $defaults = array( 210 'orderby' => 'name', 211 'order' => 'ASC', 212 'limit' => -1, 213 'category' => '', 214 'exclude_category' => '', 215 'category_name' => '', 216 'hide_invisible' => 1, 217 'show_updated' => 0, 218 'echo' => 1, 219 'categorize' => 1, 220 'title_li' => __( 'Bookmarks' ), 221 'title_before' => '<h2>', 222 'title_after' => '</h2>', 223 'category_orderby' => 'name', 224 'category_order' => 'ASC', 225 'class' => 'linkcat', 226 'category_before' => '<li id="%id" class="%class">', 227 'category_after' => '</li>', 228 ); 229 230 $parsed_args = wp_parse_args( $args, $defaults ); 231 232 $output = ''; 233 234 if ( ! is_array( $parsed_args['class'] ) ) { 235 $parsed_args['class'] = explode( ' ', $parsed_args['class'] ); 236 } 237 $parsed_args['class'] = array_map( 'sanitize_html_class', $parsed_args['class'] ); 238 $parsed_args['class'] = trim( implode( ' ', $parsed_args['class'] ) ); 239 240 if ( $parsed_args['categorize'] ) { 241 $cats = get_terms( 242 array( 243 'taxonomy' => 'link_category', 244 'name__like' => $parsed_args['category_name'], 245 'include' => $parsed_args['category'], 246 'exclude' => $parsed_args['exclude_category'], 247 'orderby' => $parsed_args['category_orderby'], 248 'order' => $parsed_args['category_order'], 249 'hierarchical' => 0, 250 ) 251 ); 252 if ( empty( $cats ) ) { 253 $parsed_args['categorize'] = false; 254 } 255 } 256 257 if ( $parsed_args['categorize'] ) { 258 // Split the bookmarks into ul's for each category. 259 foreach ( (array) $cats as $cat ) { 260 $params = array_merge( $parsed_args, array( 'category' => $cat->term_id ) ); 261 $bookmarks = get_bookmarks( $params ); 262 if ( empty( $bookmarks ) ) { 263 continue; 264 } 265 $output .= str_replace( 266 array( '%id', '%class' ), 267 array( "linkcat-$cat->term_id", $parsed_args['class'] ), 268 $parsed_args['category_before'] 269 ); 270 /** 271 * Filters the category name. 272 * 273 * @since 2.2.0 274 * 275 * @param string $cat_name The category name. 276 */ 277 $catname = apply_filters( 'link_category', $cat->name ); 278 279 $output .= $parsed_args['title_before']; 280 $output .= $catname; 281 $output .= $parsed_args['title_after']; 282 $output .= "\n\t<ul class='xoxo blogroll'>\n"; 283 $output .= _walk_bookmarks( $bookmarks, $parsed_args ); 284 $output .= "\n\t</ul>\n"; 285 $output .= $parsed_args['category_after'] . "\n"; 286 } 287 } else { 288 // Output one single list using title_li for the title. 289 $bookmarks = get_bookmarks( $parsed_args ); 290 291 if ( ! empty( $bookmarks ) ) { 292 if ( ! empty( $parsed_args['title_li'] ) ) { 293 $output .= str_replace( 294 array( '%id', '%class' ), 295 array( 'linkcat-' . $parsed_args['category'], $parsed_args['class'] ), 296 $parsed_args['category_before'] 297 ); 298 $output .= $parsed_args['title_before']; 299 $output .= $parsed_args['title_li']; 300 $output .= $parsed_args['title_after']; 301 $output .= "\n\t<ul class='xoxo blogroll'>\n"; 302 $output .= _walk_bookmarks( $bookmarks, $parsed_args ); 303 $output .= "\n\t</ul>\n"; 304 $output .= $parsed_args['category_after'] . "\n"; 305 } else { 306 $output .= _walk_bookmarks( $bookmarks, $parsed_args ); 307 } 308 } 309 } 310 311 /** 312 * Filters the bookmarks list before it is echoed or returned. 313 * 314 * @since 2.5.0 315 * 316 * @param string $html The HTML list of bookmarks. 317 */ 318 $html = apply_filters( 'wp_list_bookmarks', $output ); 319 320 if ( $parsed_args['echo'] ) { 321 echo $html; 322 } else { 323 return $html; 324 } 325 }