| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Summary view] [Print] [Text view]
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 ( ! str_starts_with( $bookmark->link_updated_f, '00' ) ) { 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 + (int) ( (float) 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 106 $target = $bookmark->link_target; 107 if ( '' !== $target ) { 108 $target = ' target="' . $target . '"'; 109 } 110 111 if ( '' !== $rel ) { 112 $rel = ' rel="' . esc_attr( $rel ) . '"'; 113 } 114 115 $output .= '<a href="' . $the_link . '"' . $rel . $title . $target . '>'; 116 117 $output .= $parsed_args['link_before']; 118 119 if ( '' !== $bookmark->link_image && $parsed_args['show_images'] ) { 120 if ( str_starts_with( $bookmark->link_image, 'http' ) ) { 121 $output .= '<img src="' . $bookmark->link_image . '"' . $alt . $title . ' />'; 122 } else { // If it's a relative path. 123 $output .= '<img src="' . get_option( 'siteurl' ) . $bookmark->link_image . '"' . $alt . $title . ' />'; 124 } 125 if ( $parsed_args['show_name'] ) { 126 $output .= " $name"; 127 } 128 } else { 129 $output .= $name; 130 } 131 132 $output .= $parsed_args['link_after']; 133 134 $output .= '</a>'; 135 136 if ( $parsed_args['show_updated'] && $bookmark->recently_updated ) { 137 $output .= '</em>'; 138 } 139 140 if ( $parsed_args['show_description'] && '' !== $desc ) { 141 $output .= $parsed_args['between'] . $desc; 142 } 143 144 if ( $parsed_args['show_rating'] ) { 145 $output .= $parsed_args['between'] . sanitize_bookmark_field( 146 'link_rating', 147 $bookmark->link_rating, 148 $bookmark->link_id, 149 'display' 150 ); 151 } 152 $output .= $parsed_args['after'] . "\n"; 153 } // End while. 154 155 return $output; 156 } 157 158 /** 159 * Retrieves or echoes all of the bookmarks. 160 * 161 * List of default arguments are as follows: 162 * 163 * These options define how the Category name will appear before the category 164 * links are displayed, if 'categorize' is 1. If 'categorize' is 0, then it will 165 * display for only the 'title_li' string and only if 'title_li' is not empty. 166 * 167 * @since 2.1.0 168 * 169 * @see _walk_bookmarks() 170 * 171 * @param string|array $args { 172 * Optional. String or array of arguments to list bookmarks. 173 * 174 * @type string $orderby How to order the links by. Accepts post fields. Default 'name'. 175 * @type string $order Whether to order bookmarks in ascending or descending order. 176 * Accepts 'ASC' (ascending) or 'DESC' (descending). Default 'ASC'. 177 * @type int $limit Amount of bookmarks to display. Accepts 1+ or -1 for all. 178 * Default -1. 179 * @type string $category Comma-separated list of category IDs to include links from. 180 * Default empty. 181 * @type string $category_name Category to retrieve links for by name. Default empty. 182 * @type int|bool $hide_invisible Whether to show or hide links marked as 'invisible'. Accepts 183 * 1|true or 0|false. Default 1|true. 184 * @type int|bool $show_updated Whether to display the time the bookmark was last updated. 185 * Accepts 1|true or 0|false. Default 0|false. 186 * @type int|bool $echo Whether to echo or return the formatted bookmarks. Accepts 187 * 1|true (echo) or 0|false (return). Default 1|true. 188 * @type int|bool $categorize Whether to show links listed by category or in a single column. 189 * Accepts 1|true (by category) or 0|false (one column). Default 1|true. 190 * @type int|bool $show_description Whether to show the bookmark descriptions. Accepts 1|true or 0|false. 191 * Default 0|false. 192 * @type string $title_li What to show before the links appear. Default 'Bookmarks'. 193 * @type string $title_before The HTML or text to prepend to the $title_li string. Default '<h2>'. 194 * @type string $title_after The HTML or text to append to the $title_li string. Default '</h2>'. 195 * @type string|array $class The CSS class or an array of classes to use for the $title_li. 196 * Default 'linkcat'. 197 * @type string $category_before The HTML or text to prepend to $title_before if $categorize is true. 198 * String must contain '%id' and '%class' to inherit the category ID and 199 * the $class argument used for formatting in themes. 200 * Default '<li id="%id" class="%class">'. 201 * @type string $category_after The HTML or text to append to $title_after if $categorize is true. 202 * Default '</li>'. 203 * @type string $category_orderby How to order the bookmark category based on term scheme if $categorize 204 * is true. Default 'name'. 205 * @type string $category_order Whether to order categories in ascending or descending order if 206 * $categorize is true. Accepts 'ASC' (ascending) or 'DESC' (descending). 207 * Default 'ASC'. 208 * } 209 * @return void|string Void if 'echo' argument is true, HTML list of bookmarks if 'echo' is false. 210 */ 211 function wp_list_bookmarks( $args = '' ) { 212 $defaults = array( 213 'orderby' => 'name', 214 'order' => 'ASC', 215 'limit' => -1, 216 'category' => '', 217 'exclude_category' => '', 218 'category_name' => '', 219 'hide_invisible' => 1, 220 'show_updated' => 0, 221 'echo' => 1, 222 'categorize' => 1, 223 'title_li' => __( 'Bookmarks' ), 224 'title_before' => '<h2>', 225 'title_after' => '</h2>', 226 'category_orderby' => 'name', 227 'category_order' => 'ASC', 228 'class' => 'linkcat', 229 'category_before' => '<li id="%id" class="%class">', 230 'category_after' => '</li>', 231 ); 232 233 $parsed_args = wp_parse_args( $args, $defaults ); 234 235 $output = ''; 236 237 if ( ! is_array( $parsed_args['class'] ) ) { 238 $parsed_args['class'] = explode( ' ', $parsed_args['class'] ); 239 } 240 $parsed_args['class'] = array_map( 'sanitize_html_class', $parsed_args['class'] ); 241 $parsed_args['class'] = trim( implode( ' ', $parsed_args['class'] ) ); 242 243 if ( $parsed_args['categorize'] ) { 244 $cats = get_terms( 245 array( 246 'taxonomy' => 'link_category', 247 'name__like' => $parsed_args['category_name'], 248 'include' => $parsed_args['category'], 249 'exclude' => $parsed_args['exclude_category'], 250 'orderby' => $parsed_args['category_orderby'], 251 'order' => $parsed_args['category_order'], 252 'hierarchical' => 0, 253 ) 254 ); 255 if ( empty( $cats ) ) { 256 $parsed_args['categorize'] = false; 257 } 258 } 259 260 if ( $parsed_args['categorize'] ) { 261 // Split the bookmarks into ul's for each category. 262 foreach ( (array) $cats as $cat ) { 263 $params = array_merge( $parsed_args, array( 'category' => $cat->term_id ) ); 264 $bookmarks = get_bookmarks( $params ); 265 if ( empty( $bookmarks ) ) { 266 continue; 267 } 268 $output .= str_replace( 269 array( '%id', '%class' ), 270 array( "linkcat-$cat->term_id", $parsed_args['class'] ), 271 $parsed_args['category_before'] 272 ); 273 /** 274 * Filters the category name. 275 * 276 * @since 2.2.0 277 * 278 * @param string $cat_name The category name. 279 */ 280 $catname = apply_filters( 'link_category', $cat->name ); 281 282 $output .= $parsed_args['title_before']; 283 $output .= $catname; 284 $output .= $parsed_args['title_after']; 285 $output .= "\n\t<ul class='xoxo blogroll'>\n"; 286 $output .= _walk_bookmarks( $bookmarks, $parsed_args ); 287 $output .= "\n\t</ul>\n"; 288 $output .= $parsed_args['category_after'] . "\n"; 289 } 290 } else { 291 // Output one single list using title_li for the title. 292 $bookmarks = get_bookmarks( $parsed_args ); 293 294 if ( ! empty( $bookmarks ) ) { 295 if ( ! empty( $parsed_args['title_li'] ) ) { 296 $output .= str_replace( 297 array( '%id', '%class' ), 298 array( 'linkcat-' . $parsed_args['category'], $parsed_args['class'] ), 299 $parsed_args['category_before'] 300 ); 301 $output .= $parsed_args['title_before']; 302 $output .= $parsed_args['title_li']; 303 $output .= $parsed_args['title_after']; 304 $output .= "\n\t<ul class='xoxo blogroll'>\n"; 305 $output .= _walk_bookmarks( $bookmarks, $parsed_args ); 306 $output .= "\n\t</ul>\n"; 307 $output .= $parsed_args['category_after'] . "\n"; 308 } else { 309 $output .= _walk_bookmarks( $bookmarks, $parsed_args ); 310 } 311 } 312 } 313 314 /** 315 * Filters the bookmarks list before it is echoed or returned. 316 * 317 * @since 2.5.0 318 * 319 * @param string $html The HTML list of bookmarks. 320 */ 321 $html = apply_filters( 'wp_list_bookmarks', $output ); 322 323 if ( $parsed_args['echo'] ) { 324 echo $html; 325 } else { 326 return $html; 327 } 328 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated : Wed May 7 08:20:01 2025 | Cross-referenced by PHPXref |