WP 2.1 API Primer: get_bookmarks() and wp_list_bookmarks()

As I mentioned back in February, links management has been overhauled in 2.1. Along with this overhaul comes some new API for retrieving and listing links/bookmarks. get_bookmarks() fetches bookmark objects from the database, and wp_list_bookmarks() lists the bookmarks in your sidebar. These new functions are more flexible and featureful than the previous links API (which still remains for backwards compatibility). Hopefully this added power will mean that theme authors won't need to write their own custom functions and database SELECTs. Using SELECTs in a theme rather than using API means that theme is not protected from database schema changes and might not work correctly with future versions of WP. Something I've seen in several themes is this:

$wpdb->get_results("SELECT cat_id, cat_name FROM $wpdb->linkcategories");

That will not work in WP 2.1 because there is no longer a linkcategories table. Link categories now live in the categories table along with post categories. If you use the API, you won't notice the difference. Themes that do the SELECT shown above will need to add some compatibility code if they want to support both 2.1 and versions prior to 2.1. Example:

if ( function_exists('wp_list_bookmarks') ) {
} else {
	$cats = $wpdb->get_results("SELECT cat_id, cat_name FROM $wpdb->linkcategories");

If your theme uses the get_links_list() function you are safe and don't need to do anything to your theme. If you are doing something custom that involves direct SELECTs from the database, however, look into the new bookmarks API. get_bookmarks() and wp_list_bookmarks() are still under development but are coming along nicely. If you are testing 2.1 alpha, try them out in your theme and help us shake out the bugs.

6 thoughts on “WP 2.1 API Primer: get_bookmarks() and wp_list_bookmarks()

  1. thank you for updating this, it’s been a long time coming. i assume that wp_list_bookmarks() doesn’t have h2’s and li’s hardcoded?

    the reason so many themes use use $wpdb queries is because it’s listed in the codex. most theme authors don’t read the plugin section, so they don’t realize that the coding standards forbid that sort of thing.

  2. Great to see the new bookmarks stuff nearly released, someone using the nightlies mentioned it back when we first released Tarski and I spent a couple of days worrying about it breaking the theme before realising it would probably take a while before it made it into an official release.

    On a tangential note, I’ve styled the pre element for the next Tarski release, apparantly I managed to overlook it.

  3. Thank you for this post, it has been very useful to me. I just upgraded to WP 2.1 and the link list broke because the theme didn’t use the APIs.
    Thank you again!

Leave a Reply