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') ) {
	wp_list_bookmarks('arg1=x&arg2=y');
} 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.