/wp-includes/bookmark-template.php

  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 bookmakr 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, 'show_description' => 0,  
  54. 'show_images' => 1, 'show_name' => 0,  
  55. 'before' => '<li>', 'after' => '</li>', 'between' => "\n",  
  56. 'show_rating' => 0, 'link_before' => '', 'link_after' => '' 
  57. ); 
  58.  
  59. $r = wp_parse_args( $args, $defaults ); 
  60.  
  61. $output = ''; // Blank string to start with. 
  62.  
  63. foreach ( (array) $bookmarks as $bookmark ) { 
  64. if ( ! isset( $bookmark->recently_updated ) ) { 
  65. $bookmark->recently_updated = false; 
  66. $output .= $r['before']; 
  67. if ( $r['show_updated'] && $bookmark->recently_updated ) { 
  68. $output .= '<em>'; 
  69. $the_link = '#'; 
  70. if ( ! empty( $bookmark->link_url ) ) { 
  71. $the_link = esc_url( $bookmark->link_url ); 
  72. $desc = esc_attr( sanitize_bookmark_field( 'link_description', $bookmark->link_description, $bookmark->link_id, 'display' ) ); 
  73. $name = esc_attr( sanitize_bookmark_field( 'link_name', $bookmark->link_name, $bookmark->link_id, 'display' ) ); 
  74. $title = $desc; 
  75.  
  76. if ( $r['show_updated'] ) { 
  77. if ( '00' != substr( $bookmark->link_updated_f, 0, 2 ) ) { 
  78. $title .= ' ('; 
  79. $title .= sprintf( 
  80. __('Last updated: %s'),  
  81. date( 
  82. get_option( 'links_updated_date_format' ),  
  83. $bookmark->link_updated_f + ( get_option( 'gmt_offset' ) * HOUR_IN_SECONDS ) 
  84. ); 
  85. $title .= ')'; 
  86. $alt = ' alt="' . $name . ( $r['show_description'] ? ' ' . $title : '' ) . '"'; 
  87.  
  88. if ( '' != $title ) { 
  89. $title = ' title="' . $title . '"'; 
  90. $rel = $bookmark->link_rel; 
  91. if ( '' != $rel ) { 
  92. $rel = ' rel="' . esc_attr($rel) . '"'; 
  93. $target = $bookmark->link_target; 
  94. if ( '' != $target ) { 
  95. $target = ' target="' . $target . '"'; 
  96. $output .= '<a href="' . $the_link . '"' . $rel . $title . $target . '>'; 
  97.  
  98. $output .= $r['link_before']; 
  99.  
  100. if ( $bookmark->link_image != null && $r['show_images'] ) { 
  101. if ( strpos( $bookmark->link_image, 'http' ) === 0 ) { 
  102. $output .= "<img src=\"$bookmark->link_image\" $alt $title />"; 
  103. } else { // If it's a relative path 
  104. $output .= "<img src=\"" . get_option('siteurl') . "$bookmark->link_image\" $alt $title />"; 
  105. if ( $r['show_name'] ) { 
  106. $output .= " $name"; 
  107. } else { 
  108. $output .= $name; 
  109.  
  110. $output .= $r['link_after']; 
  111.  
  112. $output .= '</a>'; 
  113.  
  114. if ( $r['show_updated'] && $bookmark->recently_updated ) { 
  115. $output .= '</em>'; 
  116.  
  117. if ( $r['show_description'] && '' != $desc ) { 
  118. $output .= $r['between'] . $desc; 
  119.  
  120. if ( $r['show_rating'] ) { 
  121. $output .= $r['between'] . sanitize_bookmark_field( 
  122. 'link_rating',  
  123. $bookmark->link_rating,  
  124. $bookmark->link_id,  
  125. 'display' 
  126. ); 
  127. $output .= $r['after'] . "\n"; 
  128. } // end while 
  129.  
  130. return $output; 
  131.  
  132. /** 
  133. * Retrieve or echo all of the bookmarks. 
  134. * 
  135. * List of default arguments are as follows: 
  136. * 
  137. * These options define how the Category name will appear before the category 
  138. * links are displayed, if 'categorize' is 1. If 'categorize' is 0, then it will 
  139. * display for only the 'title_li' string and only if 'title_li' is not empty. 
  140. * 
  141. * @since 2.1.0 
  142. * 
  143. * @see _walk_bookmarks() 
  144. * 
  145. * @param string|array $args { 
  146. * Optional. String or array of arguments to list bookmarks. 
  147. * 
  148. * @type string $orderby How to order the links by. Accepts post fields. Default 'name'. 
  149. * @type string $order Whether to order bookmarks in ascending or descending order. 
  150. * Accepts 'ASC' (ascending) or 'DESC' (descending). Default 'ASC'. 
  151. * @type int $limit Amount of bookmarks to display. Accepts 1+ or -1 for all. 
  152. * Default -1. 
  153. * @type string $category Comma-separated list of category ids to include links from. 
  154. * Default empty. 
  155. * @type string $category_name Category to retrieve links for by name. Default empty. 
  156. * @type int|bool $hide_invisible Whether to show or hide links marked as 'invisible'. Accepts 
  157. * 1|true or 0|false. Default 1|true. 
  158. * @type int|bool $show_updated Whether to display the time the bookmark was last updated. 
  159. * Accepts 1|true or 0|false. Default 0|false. 
  160. * @type int|bool $echo Whether to echo or return the formatted bookmarks. Accepts 
  161. * 1|true (echo) or 0|false (return). Default 1|true. 
  162. * @type int|bool $categorize Whether to show links listed by category or in a single column. 
  163. * Accepts 1|true (by category) or 0|false (one column). Default 1|true. 
  164. * @type int|bool $show_description Whether to show the bookmark descriptions. Accepts 1|true or 0|false. 
  165. * Default 0|false. 
  166. * @type string $title_li What to show before the links appear. Default 'Bookmarks'. 
  167. * @type string $title_before The HTML or text to prepend to the $title_li string. Default '<h2>'. 
  168. * @type string $title_after The HTML or text to append to the $title_li string. Default '</h2>'. 
  169. * @type string $class The CSS class to use for the $title_li. Default 'linkcat'. 
  170. * @type string $category_before The HTML or text to prepend to $title_before if $categorize is true. 
  171. * String must contain '%id' and '%class' to inherit the category ID and 
  172. * the $class argument used for formatting in themes. 
  173. * Default '<li id="%id" class="%class">'. 
  174. * @type string $category_after The HTML or text to append to $title_after if $categorize is true. 
  175. * Default '</li>'. 
  176. * @type string $category_orderby How to order the bookmark category based on term scheme if $categorize 
  177. * is true. Default 'name'. 
  178. * @type string $category_order Whether to order categories in ascending or descending order if 
  179. * $categorize is true. Accepts 'ASC' (ascending) or 'DESC' (descending). 
  180. * Default 'ASC'. 
  181. * } 
  182. * @return string|void Will only return if echo option is set to not echo. Default is not return anything. 
  183. */ 
  184. function wp_list_bookmarks( $args = '' ) { 
  185. $defaults = array( 
  186. 'orderby' => 'name', 'order' => 'ASC',  
  187. 'limit' => -1, 'category' => '', 'exclude_category' => '',  
  188. 'category_name' => '', 'hide_invisible' => 1,  
  189. 'show_updated' => 0, 'echo' => 1,  
  190. 'categorize' => 1, 'title_li' => __('Bookmarks'),  
  191. 'title_before' => '<h2>', 'title_after' => '</h2>',  
  192. 'category_orderby' => 'name', 'category_order' => 'ASC',  
  193. 'class' => 'linkcat', 'category_before' => '<li id="%id" class="%class">',  
  194. 'category_after' => '</li>' 
  195. ); 
  196.  
  197. $r = wp_parse_args( $args, $defaults ); 
  198.  
  199. $output = ''; 
  200.  
  201. if ( ! is_array( $r['class'] ) ) { 
  202. $r['class'] = explode( ' ', $r['class'] ); 
  203. $r['class'] = array_map( 'sanitize_html_class', $r['class'] ); 
  204. $r['class'] = trim( join( ' ', $r['class'] ) ); 
  205.  
  206. if ( $r['categorize'] ) { 
  207. $cats = get_terms( 'link_category', array( 
  208. 'name__like' => $r['category_name'],  
  209. 'include' => $r['category'],  
  210. 'exclude' => $r['exclude_category'],  
  211. 'orderby' => $r['category_orderby'],  
  212. 'order' => $r['category_order'],  
  213. 'hierarchical' => 0 
  214. ) ); 
  215. if ( empty( $cats ) ) { 
  216. $r['categorize'] = false; 
  217.  
  218. if ( $r['categorize'] ) { 
  219. // Split the bookmarks into ul's for each category 
  220. foreach ( (array) $cats as $cat ) { 
  221. $params = array_merge( $r, array( 'category' => $cat->term_id ) ); 
  222. $bookmarks = get_bookmarks( $params ); 
  223. if ( empty( $bookmarks ) ) { 
  224. continue; 
  225. $output .= str_replace( 
  226. array( '%id', '%class' ),  
  227. array( "linkcat-$cat->term_id", $r['class'] ),  
  228. $r['category_before'] 
  229. ); 
  230. /** 
  231. * Filters the bookmarks category name. 
  232. * 
  233. * @since 2.2.0 
  234. * 
  235. * @param string $cat_name The category name of bookmarks. 
  236. */ 
  237. $catname = apply_filters( 'link_category', $cat->name ); 
  238.  
  239. $output .= $r['title_before']; 
  240. $output .= $catname; 
  241. $output .= $r['title_after']; 
  242. $output .= "\n\t<ul class='xoxo blogroll'>\n"; 
  243. $output .= _walk_bookmarks( $bookmarks, $r ); 
  244. $output .= "\n\t</ul>\n"; 
  245. $output .= $r['category_after'] . "\n"; 
  246. } else { 
  247. //output one single list using title_li for the title 
  248. $bookmarks = get_bookmarks( $r ); 
  249.  
  250. if ( ! empty( $bookmarks ) ) { 
  251. if ( ! empty( $r['title_li'] ) ) { 
  252. $output .= str_replace( 
  253. array( '%id', '%class' ),  
  254. array( "linkcat-" . $r['category'], $r['class'] ),  
  255. $r['category_before'] 
  256. ); 
  257. $output .= $r['title_before']; 
  258. $output .= $r['title_li']; 
  259. $output .= $r['title_after']; 
  260. $output .= "\n\t<ul class='xoxo blogroll'>\n"; 
  261. $output .= _walk_bookmarks( $bookmarks, $r ); 
  262. $output .= "\n\t</ul>\n"; 
  263. $output .= $r['category_after'] . "\n"; 
  264. } else { 
  265. $output .= _walk_bookmarks( $bookmarks, $r ); 
  266.  
  267. /** 
  268. * Filters the bookmarks list before it is echoed or returned. 
  269. * 
  270. * @since 2.5.0 
  271. * 
  272. * @param string $html The HTML list of bookmarks. 
  273. */ 
  274. $html = apply_filters( 'wp_list_bookmarks', $output ); 
  275.  
  276. if ( ! $r['echo'] ) { 
  277. return $html; 
  278. echo $html; 
.