WordPress.org

Ready to get started?Download WordPress

Codex

Function Reference/wp list bookmarks

Contents

Description

Displays bookmarks found in the Administration > Links panel. This Template Tag allows the user to control how the bookmarks are sorted and displayed.

NOTE: wp_list_bookmarks() replaces the deprecated Template tags get_links_list() and get_links().

Usage

 <?php wp_list_bookmarks$args ); ?> 

Default Usage

<?php $args = array(
    
'orderby'          => 'name',
    
'order'            => 'ASC',
    
'limit'            => -1,
    
'category'         => ' ',
    
'exclude_category' => ' ',
    
'category_name'    => ' ',
    
'hide_invisible'   => 1,
    
'show_updated'     => 0,
    
'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 function shows:

  • Bookmarks divided into Categories with a Category name heading
  • All bookmarks included, regardless of 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

Parameters

categorize 
(boolean) Bookmarks should be shown within their assigned Categories or not.
  • 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).
exclude_category 
(string) Comma separated list of numeric Category IDs to be excluded from display. Defaults to '' (no categories excluded).
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 place before each category. Defaults to '<li id="[category id]" class="linkcat">' .
category_after 
(string) Text to place after each category. Defaults to '</li>' .
class 
(string) The class each category li will have on it. Defaults to 'linkcat' . (This parameter was added with Version 2.2)
category_orderby 
(string) Value to sort Categories on. 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 when 'categorize' are set to 0 [false] (else the category names will be used instead). If 'title_li' is set to null (0) value, no heading is displayed, and the list will not be wrapped with <ul>, </ul> tags (be sure to pass the 'categorize' option to 0 [false] to this option takes effect).
title_before 
(string) Text to place before each Category description if 'categorize' is 1 [true], or text defined in "title_li" if 'categorize' is 0 [false]. Defaults to '<h2>'.
title_after 
(string) Text to place after each Category description if 'categorize' is 1 [true], or text defined in "title_li" if 'categorize' is 0 [false]. 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).
  • 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. This can be a COMMA separated list of values. Defaults to 'name' unless you pass the value of '' (empty), in which case it sets to 'id'. Valid options:
  • 'link_id' - Before WordPress 3.2: 'id'
  • 'url'
  • 'name' - Default
  • 'target'
  • 'description'
  • 'owner' - User who added bookmark through bookmarks Manager.
  • 'rating'
  • 'updated' Note: the link_updated field does not track local modifications. It tracks when whatever the link points to is updated via remote requests to pingomatic.
  • 'rel' - bookmark relationship (XFN).
  • 'notes'
  • 'rss'
  • 'length' - The length of the bookmark name, shortest to longest.
  • 'rand' - Display bookmarks in random order.
order 
(string) Bookmarks display sorting order, ascending or descending as defined in the 'orderby' parameter. Valid values:
  • ASC - Default
  • DESC
limit 
(integer) Maximum number of bookmarks to display. Default is -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>'.
link_before 
(string) Text to place before the text of each bookmark, inside the hyperlink code. There is no set default. (This parameter was added with Version 2.7)
link_after 
(string) Text to place after the text of each bookmark. There is no set default. (This parameter was added with Version 2.7)
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).
  • 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.
  • 1 (True)
  • 0 (False) - Default
show_name 
(boolean) Displays the text of a link when (TRUE). Works when show_images is TRUE. (This parameter was added with Version 2.7)
  • 1 (True)
  • 0 (False) - Default
show_rating 
(boolean) Should rating stars/characters be displayed (TRUE) or not (FALSE).
  • 1 (True)
  • 0 (False) - Default
show_updated 
(boolean) Should the last updated timestamp be displayed (TRUE) or not (FALSE). Note that link_updated does not track local modifications. It tracks when whatever the link points to is updated via remote requests to pingomatic.
  • 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).
  • 1 (True) - Default
  • 0 (False)
echo 
(boolean) Display bookmarks (TRUE) or return them for use by PHP (FALSE).
  • 1 (True) - Default
  • 0 (False)

Examples

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 (Note that the last updated timestamp does not track local modifications. It tracks when whatever the link points to is updated via remote requests to pingomatic.)

<ol>
<?php wp_list_bookmarks('between=<br />&show_images=0&orderby=id&show_rating=1&show_updated=1'); ?>
</ol>

Replaces Heading with Image

Uses an image from the theme folder instead of plain text.

<?php wp_list_bookmarks('categorize=0&title_before=&title_after=&title_li=<img src="'.get_bloginfo("stylesheet_directory").'/images/blogroll.gif" alt="blogroll" />'); ?>

Changelog

  • 2.7.0 : Added the link_before, link_after and show_name parameters.
  • 2.2.0 : Added the class parameter.
  • Since: 2.1.0

Source File

wp_list_bookmarks() is located in wp-includes/bookmark-template.php.

Related

get_bookmark(), get_bookmark_field(), get_bookmarks(), wp_list_bookmarks()

List & Dropdown Functions

See also index of Function Reference and index of Template Tags.