How to Further Master the WordPress Links Manager API

April 29, 2015

We’ve previously showed you how to use the WordPress Links Manager to store and manage a list of links, we’ve also covered how to use wp_list_bookmarks() from the Links Manager API.

We saw that we can do many things with this function, but it’s not perfect for all cases. In this article, I’ll show you how to use the other functions contained in the WordPress Links Manager API.

Contrary to wp_list_bookmarks(), these functions don’t display the links: they return them and you decide if you want to display them and how, in a much more precise way than using the options of wp_list_bookmarks().

Retrieving One Link

Before looking at how to retrieve a list of links, we’ll first retrieve one link. In fact, playing with only one link is a more practical way to understand how the objects returned by the functions we will use are built.

A Function to Retrieve All Data about a Link

The first function we’ll study here is get_bookmark(). It’s used to retrieve all the data about a link and requires one parameter: the wanted link’s ID. To retrieve this ID you can, for example, go to your administration panel and edit the link: the ID can be seen in the link_id variable in the URL.

Retrieving a link ID

The Link Object

To retrieve the data we’re after, indicate this ID as a parameter in get_bookmark().

$link = get_bookmark(8);

The $link variable is an object listing of all the data about the targeted link: for each piece of information you can add when you create a link, this object has a corresponding property. This is, for example, the content of the object I got with the previous line.

stdClass Object
(
    [link_id] => 8
    [link_url] => http://jeremyheleine.me
    [link_name] => Jérémy Heleine
    [link_image] => 
    [link_target] => 
    [link_description] => My personal webpage.
    [link_visible] => Y
    [link_owner] => 1
    [link_rating] => 7
    [link_updated] => 0000-00-00 00:00:00
    [link_rel] => me
    [link_notes] => 
    [link_rss] => 
    [link_category] => Array
        (
            [0] => 5
        )
)

Most of these properties are clear, as their name is same as the corresponding fields in the ‘Add Link’ form: link_url is the URL of the link, link_name is its name, etc. Note that you can get the link’s ID with the property link_id: it seems a bit useless here as you already know this, but later on I’ll show you that it can be useful.

echo '<a href="' . $link->link_url . '">' . $link->link_name . '</a>';

I’ll now describe some of the properties in further detail. For example, the link_category: why is this property an array? This is because in the ‘Add Link’ form, you can select several categories for your link: this property lists all the selected category IDs in an array (even if you selected only one category).

The link_owner property gives us the ID of the user who added the link. If you need to display more information about this user, you can use the get_user_by() function.

// Get the owner's name
$owner_name = get_user_by('id', $link->link_owner)->display_name;

// Echoes a string containing the owner's name and their link
echo 'Here is ' . $owner_name . '\'s link: <a href="' . $link->link_url . '">' . $link->link_name . '</a>';

The link_target property contains the value you indicated in the ‘Target’ section of the ‘Add Link’ form. You can display its value directly in the target attribute of your link.

echo '<a href="' . $link->link_url . '" target="' . $link->link_target . '">' . $link->link_name . '</a>';

Note, if you chose to open the link in the same tab, WordPress stores an empty string in link_target, so you can easily detect it if you don’t want to display the target attribute.

// Build the target attribute
$target = (empty($link->link_target)) ? '' : ' target="' . $link->link_target . '"';

// Echoes the link with its target attribute (if it needs one)
echo '<a href="' . $link->link_url . '"' . $target . '>' . $link->link_name . '</a>';

Like the link_target property, the link_rel property contains the value to indicate in the rel attribute so you don’t have to do anything before displaying it.

The link_image and link_rss properties contain the URLs you indicated in the corresponding fields. That means their values are URLs: in particular, you must generate your own img tag if you want to display an image. The advantage is that you can do what you want with this image, even displaying it as a background image for example. In the example below, we don’t display the links name, only its image.

<a href="<?php echo $link->link_url; ?>">
	<img src="<?php echo $link->link_image; ?>" alt="<?php echo $link->link_name; ?>" />
</a>

Note that this example doesn’t test if the link_image property is empty. If the script you built is not only for you (e.g. if it is for a plugin or theme), you should test this before generating an img tag.

Finally, we find the link_visible property to know if the link is a private one or not. Sadly its value is not a boolean, but a string: if the link is visible (i.e. if it is not a private link), link_visible is set to 'Y', otherwise it is set to 'N'. Below we’ll display the link, only if it is visible.

if ($link->link_visible == 'Y')
	echo '<a href="' . $link->link_url . '">' . $link->link_name . '</a>';

What If I Want an Array?

We described the properties of the object returned by get_bookmark(). However, this function does not always return an object: it is the default behavior, but you can choose to retrieve an array if you prefer or if you don’t have a choice, for whatever reason.

To choose the type of the data you’ll get with this function, you can use the second parameter. It accepts a PHP constant as a value and is set by default to OBJECT.

To get an associative array, you can set it to ARRAY_A. The keys of this array will be the properties we saw in the object above so you should be familiar with this.

$link = get_bookmark(8, ARRAY_A);
echo '<a href="' . $link['link_url'] . '">' . $link['link_name'] . '</a>';

You can also choose to get a numbered array with ARRAY_N. It will then be more difficult to get a specific data but the data is ordered in the same way that they were in the associative array or in the object: we will find the ID in the first entry, then the URL, then the name, and so on.

The Not so Useless Filter

To finish with get_bookmark(), you should know that this function admits a third parameter: the filter to apply to the retrieved data.

WordPress does not give you the data directly returned by the database. In fact, it applies some filters to be sure that you have the right data in the right format. For example, the link ID is not a string containing the ID but a real number, and these filters are the reason why the link target is empty if it is set to _none.

By default, the third parameter of get_bookmark() is set to 'raw' and WordPress returns the data right after its default filters. Most of the time, it is enough, but you can also choose to apply other filters.

There is essentially one reason for choosing another filter other than raw: you want to retrieve the data to display in a form to let the users edit them. That can be useful if you want to use the Links Manager in your theme for example.

In this case, you can use the edit filter. Then, WordPress will apply some other modifications, especially for escaping the HTML characters so you don’t have to do it yourself.

$link = get_bookmark(2, OBJECT, 'edit');
echo '<textarea>' . $link->link_notes . '</textarea>';

A Function to Retrieve Specific Information

Now that we’ve seen what information we can retrieve for one link, it’s time to look at a new function: get_bookmark_field(). This function is useful in the case you want to retrieve specific information for one link, without retrieving the other information.

The get_bookmark_field() function requires two parameters: the field (i.e. the information to retrieve) and the ID of the link in question. The field is a string corresponding with the properties of the object (or the keys of the associative array) returned by get_bookmark(). For example, if you want to retrieve the URL of a link, you’ll write the line below:

$url = get_bookmark_field('link_url', 8);

which is equivalent to this one:

$url = get_bookmark(8)->link_url;

Retrieving Several Links

Above, we looked at how we can retrieve one link, but what about retrieving several links? Good news: there’s a function for this: get_bookmarks().

Known Output

You can try get_bookmarks() without any parameters: it will then return an array containing all the links stored in the Links Manager.

This array is a numbered, each entry an object representing one link. This object is the same as we’ve covered above. For example, we can list all the links, regardless of their categories.

$links = get_bookmarks();

echo '<ul>';

foreach ($links as $link)
	echo '<li><a href="' . $link->link_url . '">' . $link->link_name . '</a></li>';

echo '</ul>';

Filtering

If you don’t need all the links, filtering the output of get_bookmarks() can be a good idea. That can be achieved easily, as only parameter is accepted by this function. Once again, you should be familiar with this as this parameter is similar to the one we covered in wp_list_bookmarks().

In fact, this parameter is an array listing all the options we need to filter the output. We described most of these options when we looked at wp_list_bookmarks(). Here’s the list of the known options:

orderby to sort the links,
order to reverse (or not) the order,
limit to only retrieve a limited number of links for each category,
category to choose the categories to retrieve,
category_name to choose only one category to retrieve (by using its name),
hide_invisible don’t retrieve the private links.

In addition to these options, we find three new options. First, we have include which is a string in which you indicate a list of link IDs you want to retrieve. Note that if you use this option WordPress will ignore the values in category, category_name and exclude (the next option we’ll cover).

The example below retrieves three links and orders the output following the rating given to these links.

$args = array(
		'orderby' => 'rating',
		'order' => 'DESC',
		'include' => '4,5,10'
	);
$links = get_bookmarks($args);

The exclude option allows us to exclude a list of links using their IDs. You can combine this option with the other filters (except for include) to, for example, retrieve a category without a given link.

$args = array(
		'category_name' =&gt; 'tools',
		'exclude' =&gt; '6'
	);

Finally, we find the option search which accepts a string to search links, URLs, names and descriptions. The example below will get all the links containing the word ‘sitepoint’ in the previously listed fields.

$args = array(
		'search' => 'sitepoint'
	);

Note that you can combine this option, for example, to only search in some categories. The search is case-insensitive.

In Conclusion

Managing a list of links is easy with the WordPress Links Manager. By default, the CMS provides us some useful tools but now, with the API we’ve explored, you can create your own tools.

For example, you can integrate a carousel into your theme, with two images per link: one in background, one in foreground, positioned by the user, using a parameter stored in the link’s notes. You can now do whatever you want, as you now know how to create your own forms.