WordPress.org

Make WordPress Core

Ticket #10443: links-template.php

File links-template.php, 9.4 KB (added by thee17, 6 years ago)

New file to replace bookmarks-template.php

Line 
1<?php
2/**
3 * Links Template Functions for usage in Themes
4 *
5 * @package WordPress
6 * @subpackage Template
7 */
8
9/**
10 * The formatted output of a list of links.
11 *
12 * The $bookmarks array must contain link objects and will be iterated over
13 * to retrieve the link 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_link() 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 *              link was last updated.
25 * 'show_description' - Default is 0 (integer). Whether to show the description
26 *              of the link.
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 *              links.
33 * 'after' - Default is '</li>' (string). The html or text to append to each
34 *              links.
35 * 'link_before' - Default is '' (string). The html or text to prepend to each
36 *              links inside the <a> tag.
37 * 'link_after' - Default is '' (string). The html or text to append to each
38 *              links 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.9.0
44 * @access private
45 * @usedby wp_list_links()
46 *
47 * @param array $bookmarks List of links to traverse
48 * @param string|array $args Optional. Overwrite the defaults.
49 * @return string Formatted output in HTML
50 */
51function _walk_links($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="' . $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 links.
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 link 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 links 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 *
157 * These options define how the Category name will appear before the category
158 * links are displayed, if 'categorize' is 1. If 'categorize' is 0, then it will
159 * display for only the 'title_li' string and only if 'title_li' is not empty.
160 * 'title_li' - Default is 'Links' (translatable string). What to show
161 *              before the links appear.
162 * 'title_before' - Default is '<h2>' (string). The HTML or text to show before
163 *              the 'title_li' string.
164 * 'title_after' - Default is '</h2>' (string). The HTML or text to show after
165 *              the 'title_li' string.
166 * 'class' - Default is 'linkcat' (string). The CSS class to use for the
167 *              'title_li'.
168 *
169 * 'category_before' - Default is '<li id="%id" class="%class">'. String must
170 *              contain '%id' and '%class' to get
171 * the id of the category and the 'class' argument. These are used for
172 *              formatting in themes.
173 * Argument will be displayed before the 'title_before' argument.
174 * 'category_after' - Default is '</li>' (string). The HTML or text that will
175 *              appear after the list of links.
176 *
177 * These are only used if 'categorize' is set to 1 or true.
178 * 'category_orderby' - Default is 'name'. How to order the link category
179 *              based on term scheme.
180 * 'category_order' - Default is 'ASC'. Set the order by either ASC (ascending)
181 *              or DESC (descending).
182 *
183 * @see _walk_links() For other arguments that can be set in this function
184 *              and passed to _walk_links().
185 * @see get_links() For other arguments that can be set in this function and
186 *              passed to get_links().
187 * @link http://codex.wordpress.org/Template_Tags/wp_list_links
188 *
189 * @since 2.9.0
190 * @uses _list_links() Used to iterate over all of the links and return
191 *              the html
192 * @uses get_terms() Gets all of the categories that are for links.
193 *
194 * @param string|array $args Optional. Overwrite the defaults of the function
195 * @return string|null Will only return if echo option is set to not echo.
196 *              Default is not return anything.
197 */
198function wp_list_links($args = '') {
199        $defaults = array(
200                'orderby' => 'name', 'order' => 'ASC',
201                'limit' => -1, 'category' => '', 'exclude_category' => '',
202                'category_name' => '', 'hide_invisible' => 1,
203                'show_updated' => 0, 'echo' => 1,
204                'categorize' => 1, 'title_li' => __('Links'),
205                'title_before' => '<h2>', 'title_after' => '</h2>',
206                'category_orderby' => 'name', 'category_order' => 'ASC',
207                'class' => 'linkcat', 'category_before' => '<li id="%id" class="%class">',
208                'category_after' => '</li>'
209        );
210
211        $r = wp_parse_args( $args, $defaults );
212        extract( $r, EXTR_SKIP );
213
214        $output = '';
215
216        if ( $categorize ) {
217                //Split the links into ul's for each category
218                $cats = get_terms('link_category', array('name__like' => $category_name, 'include' => $category, 'exclude' => $exclude_category, 'orderby' => $category_orderby, 'order' => $category_order, 'hierarchical' => 0));
219
220                foreach ( (array) $cats as $cat ) {
221                        $params = array_merge($r, array('category'=>$cat->term_id));
222                        $bookmarks = get_links($params);
223                        if ( empty($bookmarks) )
224                                continue;
225                        $output .= str_replace(array('%id', '%class'), array("linkcat-$cat->term_id", $class), $category_before);
226                        $catname = apply_filters( "link_category", $cat->name );
227                        $output .= "$title_before$catname$title_after\n\t<ul class='xoxo blogroll'>\n";
228                        $output .= _walk_links($bookmarks, $r);
229                        $output .= "\n\t</ul>\n$category_after\n";
230                }
231        } else {
232                //output one single list using title_li for the title
233                $bookmarks = get_links($r);
234
235                if ( !empty($bookmarks) ) {
236                        if ( !empty( $title_li ) ){
237                                $output .= str_replace(array('%id', '%class'), array("linkcat-$category", $class), $category_before);
238                                $output .= "$title_before$title_li$title_after\n\t<ul class='xoxo blogroll'>\n";
239                                $output .= _walk_links($bookmarks, $r);
240                                $output .= "\n\t</ul>\n$category_after\n";
241                        } else {
242                                $output .= _walk_links($bookmarks, $r);
243                        }
244                }
245        }
246
247        $output = apply_filters( 'wp_list_links', $output );
248
249        if ( !$echo )
250                return $output;
251        echo $output;
252}
253
254?>