WordPress.org

Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/get bookmarks

Description

This function returns an array of bookmarks found in the Administration > Links > Edit panel. This Template Tag allows the user to retrieve the bookmark information directly.

Usage

 <?php get_bookmarks$args ); ?> 

Default Usage

<?php $args = array(
	'orderby'        => 'name', 
	'order'          => 'ASC',
	'limit'          => -1, 
	'category'       => '',
	'category_name'  => '', 
	'hide_invisible' => 1,
	'show_updated'   => 0, 
	'include'        => '',
	'exclude'        => '',
	'search'         => '' ); ?>

By default, the usage gets:

  • All bookmarks ordered by name, ascending
  • Bookmarks marked as hidden are not returned.
  • The link_updated_f field (the update time in the form of a timestamp) is not returned.

Parameters

orderby 
(string) Value to sort bookmarks on. Defaults to 'name'. Valid options:
  • 'link_id' - Before WordPress 3.2: 'id'
  • 'url'
  • 'name' - Default
  • 'owner' - User who added bookmark through bookmarks Manager.
  • 'rating'
  • 'visible'
  • '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).
category 
(string) Comma separated list of bookmark category ID's.
category_name 
(string) Category name of a category of bookmarks to retrieve. Overrides category parameter.
hide_invisible 
(boolean) TRUE causes only bookmarks with link_visible set to 'Y' to be retrieved.
  • 1 (True) - Default
  • 0 (False)
show_updated 
(boolean) TRUE causes an extra column called "link_category_f" to be inserted into the results, which contains the same value as "link_updated", but in a unix timestamp format. Handy for using PHP date functions on this data.
  • 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).
search 
(string) Searches link_url, link_name or link_description like the search string. Defaults to ''.

Return Values

(array) 
List of bookmark row objects. Each bookmark object may contain the following: 'link_id', 'link_url', 'link_name', 'link_image', 'link_target', 'link_category', 'link_description', 'link_visible', 'link_owner', 'link_rating', 'link_updated', 'link_rel', 'link_notes', 'link_rss'

Examples

- Create a link category named "Related Sites"
- Create a few links, adding them to the "Related Sites" category

You may use the following code in your templates to retrieve the links:

<?php
$bookmarks = get_bookmarks( array(
	'orderby'        => 'name',
	'order'          => 'ASC',
	'category_name'  => 'Related Sites'
));

// Loop through each bookmark and print formatted output
foreach ( $bookmarks as $bookmark ) { 
    printf( '<a class="relatedlink" href="%s">%s</a><br />', $bookmark->link_url, $bookmark->link_name );
}
?>

- Create posts from Blogroll or Bookmark Items, useful if you want to migrate any of them before Blogrolls are no longer supported.

// Create posts from blogroll items
// set $test to true so we don't actually create posts
$test = true;

$args = array(
	'orderby'        => 'name', 
	'order'          => 'ASC',
	'limit'          => -1, 
	'hide_invisible' => 1,
	'show_updated'   => 0, 
	'include'        => '',
	'exclude'        => '',
	'search'         => '' ); 
$thelist = get_bookmarks( $args ); 

echo "<PRE>";
//print_r($thelist);
$my_status = 'publish';
$post_type = 'clients';

$errors = array();
$k = 0;
foreach ($thelist as $item) {
	$link_category = $item->link_category;
	//echo "postarr $k\n";
	//print_r($postarr);


	$k++;
	$link_url = $item->link_url;
	$link_id = $item->link_id;
	$link_name = $item->link_name;
	$link_description = $item->link_description;
	$postarr = array(
		'post_type' => $post_type,
		'post_content' => $link_description,
		'post_title' => $link_name,
		'post_excerpt' => $link_description,
		'menu_order' => $link_id,
		'post_status' => $my_status,
		);
	// see if there is an existing post?
	$there_is_one_already = get_page_by_title( $link_name, OBJECT , $post_type );
	if ( $there_is_one_already) {
		echo "there_is_one_already: $link_name, so we are skipping...\n";
		print_r($there_is_one_already);
		continue;
	}
	$newpost_id = '';
	if (!$test) {
		//if ($k>1) {continue;} // only do first
		$newpost_id = wp_insert_post( $postarr);
		if (!$newpost_id) {$errors[] = $link_name; continue;}
		echo "created $post_type id $new_post_id\n";
		//create a custom field with the link_url
		add_post_meta( $newpost_id, 'link_url', $link_url );
	}
	
}

print_r($errors);


Changelog

Since: 2.1.0

Source File

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

Related

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

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