WordPress 3.4
[autoinstalls/wordpress.git] / 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  * The defaults for overwriting are:
23  * 'show_updated' - Default is 0 (integer). Will show the time of when the
24  *              bookmark was last updated.
25  * 'show_description' - Default is 0 (integer). Whether to show the description
26  *              of the bookmark.
27  * 'show_images' - Default is 1 (integer). Whether to show link image if
28  *              available.
29  * 'show_name' - Default is 0 (integer). Whether to show link name if
30  *              available.
31  * 'before' - Default is '<li>' (string). The html or text to prepend to each
32  *              bookmarks.
33  * 'after' - Default is '</li>' (string). The html or text to append to each
34  *              bookmarks.
35  * 'link_before' - Default is '' (string). The html or text to prepend to each
36  *              bookmarks inside the <a> tag.
37  * 'link_after' - Default is '' (string). The html or text to append to each
38  *              bookmarks inside the <a> tag.
39  * 'between' - Default is '\n' (string). The string for use in between the link,
40  *              description, and image.
41  * 'show_rating' - Default is 0 (integer). Whether to show the link rating.
42  *
43  * @since 2.1.0
44  * @access private
45  * @usedby wp_list_bookmarks()
46  *
47  * @param array $bookmarks List of bookmarks to traverse
48  * @param string|array $args Optional. Overwrite the defaults.
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         extract( $r, EXTR_SKIP );
61
62         $output = ''; // Blank string to start with.
63
64         foreach ( (array) $bookmarks as $bookmark ) {
65                 if ( !isset($bookmark->recently_updated) )
66                         $bookmark->recently_updated = false;
67                 $output .= $before;
68                 if ( $show_updated && $bookmark->recently_updated )
69                         $output .= get_option('links_recently_updated_prepend');
70
71                 $the_link = '#';
72                 if ( !empty($bookmark->link_url) )
73                         $the_link = esc_url($bookmark->link_url);
74
75                 $desc = esc_attr(sanitize_bookmark_field('link_description', $bookmark->link_description, $bookmark->link_id, 'display'));
76                 $name = esc_attr(sanitize_bookmark_field('link_name', $bookmark->link_name, $bookmark->link_id, 'display'));
77                 $title = $desc;
78
79                 if ( $show_updated )
80                         if ( '00' != substr($bookmark->link_updated_f, 0, 2) ) {
81                                 $title .= ' (';
82                                 $title .= sprintf(__('Last updated: %s'), date(get_option('links_updated_date_format'), $bookmark->link_updated_f + (get_option('gmt_offset') * 3600)));
83                                 $title .= ')';
84                         }
85
86                 $alt = ' alt="' . $name . ( $show_description ? ' ' . $title : '' ) . '"';
87
88                 if ( '' != $title )
89                         $title = ' title="' . $title . '"';
90
91                 $rel = $bookmark->link_rel;
92                 if ( '' != $rel )
93                         $rel = ' rel="' . esc_attr($rel) . '"';
94
95                 $target = $bookmark->link_target;
96                 if ( '' != $target )
97                         $target = ' target="' . $target . '"';
98
99                 $output .= '<a href="' . $the_link . '"' . $rel . $title . $target . '>';
100
101                 $output .= $link_before;
102
103                 if ( $bookmark->link_image != null && $show_images ) {
104                         if ( strpos($bookmark->link_image, 'http') === 0 )
105                                 $output .= "<img src=\"$bookmark->link_image\" $alt $title />";
106                         else // If it's a relative path
107                                 $output .= "<img src=\"" . get_option('siteurl') . "$bookmark->link_image\" $alt $title />";
108
109                         if ( $show_name )
110                                 $output .= " $name";
111                 } else {
112                         $output .= $name;
113                 }
114
115                 $output .= $link_after;
116
117                 $output .= '</a>';
118
119                 if ( $show_updated && $bookmark->recently_updated )
120                         $output .= get_option('links_recently_updated_append');
121
122                 if ( $show_description && '' != $desc )
123                         $output .= $between . $desc;
124
125                 if ( $show_rating )
126                         $output .= $between . sanitize_bookmark_field('link_rating', $bookmark->link_rating, $bookmark->link_id, 'display');
127
128                 $output .= "$after\n";
129         } // end while
130
131         return $output;
132 }
133
134 /**
135  * Retrieve or echo all of the bookmarks.
136  *
137  * List of default arguments are as follows:
138  * 'orderby' - Default is 'name' (string). How to order the links by. String is
139  *              based off of the bookmark scheme.
140  * 'order' - Default is 'ASC' (string). Either 'ASC' or 'DESC'. Orders in either
141  *              ascending or descending order.
142  * 'limit' - Default is -1 (integer) or show all. The amount of bookmarks to
143  *              display.
144  * 'category' - Default is empty string (string). Include the links in what
145  *              category ID(s).
146  * 'category_name' - Default is empty string (string). Get links by category
147  *              name.
148  * 'hide_invisible' - Default is 1 (integer). Whether to show (default) or hide
149  *              links marked as 'invisible'.
150  * 'show_updated' - Default is 0 (integer). Will show the time of when the
151  *              bookmark was last updated.
152  * 'echo' - Default is 1 (integer). Whether to echo (default) or return the
153  *              formatted bookmarks.
154  * 'categorize' - Default is 1 (integer). Whether to show links listed by
155  *              category (default) or show links in one column.
156  * 'show_description' - Default is 0 (integer). Whether to show the description
157  *              of the bookmark.
158  *
159  * These options define how the Category name will appear before the category
160  * links are displayed, if 'categorize' is 1. If 'categorize' is 0, then it will
161  * display for only the 'title_li' string and only if 'title_li' is not empty.
162  * 'title_li' - Default is 'Bookmarks' (translatable string). What to show
163  *              before the links appear.
164  * 'title_before' - Default is '<h2>' (string). The HTML or text to show before
165  *              the 'title_li' string.
166  * 'title_after' - Default is '</h2>' (string). The HTML or text to show after
167  *              the 'title_li' string.
168  * 'class' - Default is 'linkcat' (string). The CSS class to use for the
169  *              'title_li'.
170  *
171  * 'category_before' - Default is '<li id="%id" class="%class">'. String must
172  *              contain '%id' and '%class' to get
173  * the id of the category and the 'class' argument. These are used for
174  *              formatting in themes.
175  * Argument will be displayed before the 'title_before' argument.
176  * 'category_after' - Default is '</li>' (string). The HTML or text that will
177  *              appear after the list of links.
178  *
179  * These are only used if 'categorize' is set to 1 or true.
180  * 'category_orderby' - Default is 'name'. How to order the bookmark category
181  *              based on term scheme.
182  * 'category_order' - Default is 'ASC'. Set the order by either ASC (ascending)
183  *              or DESC (descending).
184  *
185  * @see _walk_bookmarks() For other arguments that can be set in this function
186  *              and passed to _walk_bookmarks().
187  * @see get_bookmarks() For other arguments that can be set in this function and
188  *              passed to get_bookmarks().
189  * @link http://codex.wordpress.org/Template_Tags/wp_list_bookmarks
190  *
191  * @since 2.1.0
192  * @uses _list_bookmarks() Used to iterate over all of the bookmarks and return
193  *              the html
194  * @uses get_terms() Gets all of the categories that are for links.
195  *
196  * @param string|array $args Optional. Overwrite the defaults of the function
197  * @return string|null Will only return if echo option is set to not echo.
198  *              Default is not return anything.
199  */
200 function wp_list_bookmarks($args = '') {
201         $defaults = array(
202                 'orderby' => 'name', 'order' => 'ASC',
203                 'limit' => -1, 'category' => '', 'exclude_category' => '',
204                 'category_name' => '', 'hide_invisible' => 1,
205                 'show_updated' => 0, 'echo' => 1,
206                 'categorize' => 1, 'title_li' => __('Bookmarks'),
207                 'title_before' => '<h2>', 'title_after' => '</h2>',
208                 'category_orderby' => 'name', 'category_order' => 'ASC',
209                 'class' => 'linkcat', 'category_before' => '<li id="%id" class="%class">',
210                 'category_after' => '</li>'
211         );
212
213         $r = wp_parse_args( $args, $defaults );
214         extract( $r, EXTR_SKIP );
215
216         $output = '';
217
218         if ( $categorize ) {
219                 //Split the bookmarks into ul's for each category
220                 $cats = get_terms('link_category', array('name__like' => $category_name, 'include' => $category, 'exclude' => $exclude_category, 'orderby' => $category_orderby, 'order' => $category_order, 'hierarchical' => 0));
221
222                 foreach ( (array) $cats as $cat ) {
223                         $params = array_merge($r, array('category'=>$cat->term_id));
224                         $bookmarks = get_bookmarks($params);
225                         if ( empty($bookmarks) )
226                                 continue;
227                         $output .= str_replace(array('%id', '%class'), array("linkcat-$cat->term_id", $class), $category_before);
228                         $catname = apply_filters( "link_category", $cat->name );
229                         $output .= "$title_before$catname$title_after\n\t<ul class='xoxo blogroll'>\n";
230                         $output .= _walk_bookmarks($bookmarks, $r);
231                         $output .= "\n\t</ul>\n$category_after\n";
232                 }
233         } else {
234                 //output one single list using title_li for the title
235                 $bookmarks = get_bookmarks($r);
236
237                 if ( !empty($bookmarks) ) {
238                         if ( !empty( $title_li ) ){
239                                 $output .= str_replace(array('%id', '%class'), array("linkcat-$category", $class), $category_before);
240                                 $output .= "$title_before$title_li$title_after\n\t<ul class='xoxo blogroll'>\n";
241                                 $output .= _walk_bookmarks($bookmarks, $r);
242                                 $output .= "\n\t</ul>\n$category_after\n";
243                         } else {
244                                 $output .= _walk_bookmarks($bookmarks, $r);
245                         }
246                 }
247         }
248
249         $output = apply_filters( 'wp_list_bookmarks', $output );
250
251         if ( !$echo )
252                 return $output;
253         echo $output;
254 }