WordPress — get_bookmarks VS wp_list_bookmarks

Recently I decided to replace a small piece of content on my about page where I listed all the links to the different profiles I have throughout the internet. Sites like Flickr, Delicious, Twitter, StumbleUpon.

I got pretty tired of going into the code of the post and replacing the links whenever they changed or whenever I got a new site I wanted to share out. There had to be a better way, especially when using WordPress.

I always thought of using the links section to manage groups of links, especially for cases like this one so I decided to give it a stab.

What I found is that you have a few ways of getting that information out of WordPress. Namely, there are two functions that will do the job for you, depending on what you need and what you want. The only issue I had with it was that the two different and distinct functions almost seemed like the same thing. Obviously they aren't or the development community in WordPress would have done away with one.

The two functions are:
get_bookmarks and wp_list_bookmarks. At first glance they seem like the same thing, and they take a lot of the same arguments and give you similar output, but they're not the same. I've noticed this happens a lot in the OpenSource world, where two methods or calls are very similar but differ in function at a fundamental level. Such is the case with this. And perhaps its just me in being naive and really not even a programmer, that even notices these things. I'm sure experienced programmers don't give this a second thought.

For the rest of us hacking away at WordPress the key here is in the description of each function.

The description for get_bookmarks in the Codex reads:

This function returns an array of bookmarks found in the Administration > Links > Edit panel.

while wp_list_bookmarks' reads:

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

It is important to note that one says "... returns an array" while the other one says "Displays bookmarks." The difference here is that get_bookmarks is just going to get those bookmarks directly from the database and let you manipulate them till your heart's content, and wp_list_bookmarks goes one step further and actually creates a nice display of the bookmarks.

get_bookmarks requires that you format your data so it can actually be displayed on your site, you have to explicitly tell the code that you want the bookmarks in a list format, or in a paragraph, and it lets you add other code with which to manipulate the actual data before presenting it to the user.

wp_list_bookmarks goes one step further and if you don't change any of the defaults, its smart enough to give you the list of bookmarks you asked in a nicely formatted manner.

Both functions allow for basic things like sorting and using the descriptions and titles for both individual bookmarks and categories.

So how do you know which one to use? If you are developing a theme, creating a plugin, you might want to use get_bookmarks. And if you're just trying to get the bookmarks and list them somewhere without a lot of thrills or frills, you should just wp_list_bookmarks.

For my purposes in my About page, and in the post: Adding a Social media icon box anywhere on your blog, I use wp_list_bookmarks.

Other use cases I can think of go along these lines.

• A nicely formatted blogroll page, instead of a whimpy widget.
• Links to your favorite books in Amazon.

A top 10 list of anything you want. (go crazy with this and power an entire WordPress site with it). All you have to do is add categories, links with descriptions, and pages for each one. Then copy/paste code and change the ID.

An alternative and more sophisiticated solution to this would be a custom post type and a custom post type form and theme logic built in, but that's a topic for another day. Thanks for reading!

Good luck and let me know if you have any questions I can help you with.