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