WordPress:Template Tags/wp list bookmarks
Description
This function was introduced in WordPress v2.1 . wp_list_bookmarks(), displays bookmarks found in the Administration > Blogroll > Manage Blogroll panel. This Template Tag allows the user to control how the bookmarks are sorted and displayed and is intended to replace the Template tags 'get_links_list()' and 'get_links()'.
Usage
%%% <?php wp_list_bookmarks('arguments'); ?> %%%
Examples
Default Usage
$defaults = array( 'orderby' => 'name', 'order' => 'ASC', 'limit' => -1, 'category' => '', 'category_name' => '', 'hide_invisible' => 1, 'show_updated' => 0, 'show_description' => 1, 'echo' => 1, 'categorize' => 1, 'title_li' => __('Bookmarks'), 'title_before' => '<h2>', 'title_after' => '</h2>', 'category_orderby' => 'name', 'category_order' => 'ASC', 'class' => 'linkcat', 'category_before' => '<li id="%id" class="%class">', 'category_after' => '</li>' );
By default, the usage shows:
- Bookmarks divided into Categories with a Category name heading
- All bookmarks included, regardless of Category ID, Category Name, or Category ID
- Sorts the list by name
- An image if one is included
- A space between the image and the text
- Shows the description of the bookmark
- Does not show the ratings
- Unless limit is set, shows all bookmarks
- Displays bookmarks
<?php wp_list_bookmarks(); ?>
Simple List
Displays all bookmarks with the title "Bookmarks" and with items wrapped in <li> tags. The title is wrapped in h2 tags.
<?php wp_list_bookmarks('title_li=&category_before=&category_after='); ?>
Simple List without the Heading
Displays all bookmarks as above, but does not include the default heading.
<?php wp_list_bookmarks('title_li=&categorize=0'); ?>
Specific Category Sorted by URL
Displays bookmarks for Category ID 2 in span tags, uses images for bookmarks, does not show descriptions, sorts by bookmark URL.
<?php wp_list_bookmarks('categorize=0&category=2&before=<span>&after=</span>&show_images=1&show_description=0&orderby=url'); ?>
Shows Ratings and Timestamp
Displays all bookmarks in an ordered list with descriptions on a new line, does not use images for bookmarks, sorts by bookmark id, shows ratings and last-updated timestamp.
<ol> <?php wp_list_bookmarks('between=<br />&show_images=0&orderby=id&show_rating=1&show_updated=1'); ?> </ol>
Parameters
- categorize
- (boolean) Bookmarks should be shown within their assigned Categories (TRUE) or not (FALSE). Defaults to TRUE.
- 1 (True - default)
- 0 (False)
- category
- (string) Comma separated list of numeric Category IDs to be displayed. If none is specified, all Categories with bookmarks are shown. Defaults to (all Categories).
- category_name
- (string) The name of a Category whose bookmarks will be displayed. If none is specified, all Categories with bookmarks are shown. Defaults to (all Categories).
- category_before
- (string) Text to put before each category. Defaults to '<li id="[category id]" class="linkcat">' .
- category_after
- (string) Text to put before each category. Defaults to '<'/li>' .
- class
- (string) The class each cateogory li will have on it. Defaults to 'linkcat' .
- category_orderby
- (string) Value to sort Categories on. Defaults to 'name'. Valid options:
- 'name' (Default)
- 'id'
- 'slug'
- 'count'
- 'term_group' (not used yet)
- category_order
- (string) Sort order, ascending or descending for the category_orderby parameter. Valid values:
- ASC (Default)
- DESC
- title_li
- (string) Text for the heading of the links list. Defaults to '__('Bookmarks')', which displays "Bookmarks" (the __('') is used for localization purposes). Only used with categorize set to 0 (else the category names will be used instead). If passed a null (0) value, no heading is displayed, and the list will not be wrapped with <ul>, </ul> tags.
- title_before
- (string) Text to place before each Category description if 'categorize' is TRUE. Defaults to '<h2>'.
- title_after
- (string) Text to place after each Category description if 'categorize' is TRUE. Defaults to '</h2>'.
- show_private
- (boolean) Should a Category be displayed even if the Category is considered private. Ignore the admin setting and show private Categories (TRUE) or do NOT show private Categories (FALSE). Defaults to FALSE.
- 1 (True)
- 0 (False - default)
- include
- (string) Comma separated list of numeric bookmark IDs to include in the output. For example, 'include=1,3,6' means to return or echo bookmark IDs 1, 3, and 6. If the include string is used, the category, category_name, and exclude parameters are ignored. Defaults to (all Bookmarks).
- exclude
- (string) Comma separated list of numeric bookmark IDs to exclude. For example, 'exclude=4,12' means that bookmark IDs 4 and 12 will NOT be returned or echoed. Defaults to (exclude nothing).
- orderby
- (string) Value to sort bookmarks on. Defaults to 'name' unless you pass the value of '' (empty), in which case it sets to 'id'. Valid options:
- 'id'
- 'url'
- 'name'
- 'target'
- 'description'
- 'owner' - User who added bookmark through bookmarks Manager.
- 'rating'
- 'updated'
- 'rel' - bookmark relationship (XFN).
- 'notes'
- 'rss'
- 'length' - The length of the bookmark name, shortest to longest.
- 'rand' - Display bookmarks in random order.
- order
- (string) Sort order, ascending or descending for the orderby parameter. Valid values:
- ASC (Default)
- DESC
- limit
- (integer) Maximum number of bookmarks to display. Defaults to -1 (all bookmarks).
- before
- (string) Text to place before each bookmark. Defaults to '<li>'.
- after
- (string) Text to place after each bookmark. Defaults to '</li>'.
- category_before
- (string) Text to place before each category. Defaults to '<li>' with an appropriate id and class.
- category_after
- (string) Text to place after each category. Defaults to '</li>'.
- between
- (string) Text to place between each bookmark/image and its description. Defaults to '\n' (newline).
- show_images
- (boolean) Should images for bookmarks be shown (TRUE) or not (FALSE). Defaults to TRUE.
- 1 (True - default)
- 0 (False)
- show_description
- (boolean) Should the description be displayed (TRUE) or not (FALSE). Valid when show_images is FALSE, or an image is not defined. Defaults to FALSE.
- 1 (True)
- 0 (False - default)
- show_rating
- (boolean) Should rating stars/characters be displayed (TRUE) or not (FALSE). Defaults to FALSE.
- 1 (True)
- 0 (False - default)
- show_updated
- (boolean) Should the last updated timestamp be displayed (TRUE) or not (FALSE). Defaults to FALSE.
- 1 (True)
- 0 (False - default)
- hide_invisible
- (boolean) Should bookmark be displayed even if it's Visible setting is No. Abides by admin setting (TRUE) or does no abide by admin setting (FALSE). Defaults to TRUE.
- 1 (True - default)
- 0 (False)
- echo
- (boolean) Display bookmarks (TRUE) or return them for use by PHP (FALSE). Defaults to TRUE.
- 1 (True - default)
- 0 (False)