Custom WordPress Arrays: Creating a favicon fueled link list

Ed: Today’s article is part of the 21 Days of WordPress Tips and was written by Adii, the WordPress Rockstar. Adii runs a boutique design firm at {radiiate} and a premium theme shop at WooThemes.

One of the main reasons why designers & developers love WordPress, is because it is simply so easy to use the variety of template tags in order to achieve a desired outcome. Having worked with WordPress for the past 2 years – at both WooThemes & {radiiate} – one of the biggest stumbling blocks I’ve encountered with WP, is that some template tags simply just don’t allow for the level of customizability that I’m after. This should however never be a problem… Let me explain…

Basically the template tags are just outputting the data that you have entered into your WP database. But since MySQL database queries and not everyone’s cup of suit, the WP core offers you easy-to-use, logical (from a layman’s perspective) template tags with a few allowed parameters to control the output. But as I mentioned above – in certain instances I’ve still found the template tags to be limiting, which has prompted me to delve a little deeper into the WP core.

So along with the more user-friendly template tags like wp_list_categories, wp_list_pages & wp_list_bookmarks, you will also find more advanced functions like get_categories, get_pages & get_bookmarks (more of these lesser known functions can be found via the WordPress Function Reference). These functions do not have an output, but instead it queries the requested data (as specified by you) from the WP database and assigns that to a PHP array. And it is when we have that “raw”, unformatted data in an array, that we can start taking control over the output thereof – thus customizing it 100% to our liking

The Example – Favicon fueled link lists

I’d thus like to take you through a foolproof example of how you can use this newly acquired knowledge about the custom WordPress functions and arrays. The example that I’m showing you will render a similar result as the “Kudo’s & Respect” links list in the sidebar on my own blog.

Generally, you would’ve been able to use the wp_list_bookmarks template tag to display the links from a specific category, but the function doesn’t allow you to display both the title & the image associated to a link. You could bypass this by displaying the description of the link in place of the title, but then the function doesn’t hyperlink that and you have no control over the HTML output (and subsequently the CSS styling) thereof. So therein is the need for a custom function… Here’s how you go about it:

Step 1 – Get the array

The first thing you want to do is to specify the array variable to contain the bookmarks you’d like to be listed. This code snippet takes care of this:

<?php
$bookmarks = array();
$bookmarks = get_bookmarks('category=111&orderby=rand');
?>

You can use any of the parameters (found here) to tweak the data you are requesting from the database. In this example above, I’m pulling the links from the category with an ID of 111 and I’m telling the function to display the links in random order.

Step 2 – What’s in the array?

Now, when you’re doing this the first time, you will have no idea of what the content of that array looks like. So to display the content from the array, you’d simply do this:

<?php
$bookmarks = array();
$bookmarks = get_bookmarks('category=111&orderby=rand');

print_r($bookmarks);
?>

When you view your template in WP now, you’ll see a big section of odd-looking data, which looks something like this:

“Array ( [0] => stdClass Object ( [link_id] => 7 [link_url] => http://planet.wordpress.org/ [link_name] => WordPress Planet [link_image] => [link_target] => [link_category] => 0 [link_description] => [link_visible] => Y [link_owner] => 1 [link_rating] => 0 [link_updated] => 0000-00-00 00:00:00 [link_rel] => [link_notes] => [link_rss] => [object_id] => 7 [term_taxonomy_id] => 2 [term_order] => 0 [term_id] => 2 [taxonomy] => link_category [description] => [parent] => 0 [count] => 7 [recently_updated] => 0 )”

This data may seem completely useless at this stage (and functionality-wise it is), but we will reference this output just now when we construct our links list. Just as an example – [link_url] & [link_image] are examples of variables that you can call on for each bookmark that was queried. The above data dump is also only the data associated with one bookmark from the array.

Step 3 – Constructing the platform

So next up, we want to start building the HTML around the list itself – before we code the output of the individual links. Using the same code as above (but removing the code added in Step 2, since this was for reference-use only), we will build it out as follows:

<div id="links" class="widget">
<h3>Kudo's & Respect</h3>
<ul> <?php
$bookmarks = array();
$bookmarks = get_bookmarks('category=111&orderby=rand');
foreach ( $bookmarks as $bookmark ) {
?>

***The link output will be here***</ul>
</div>
<!--widget-->

If you work through that code snippet, you’ll see that we’ve just added the HTML to allow us to style this widget specifically later on. The only new dynamic code that we’ve added is the foreach loop, which will be cycling through the $bookmarks array to display the links.

Step 4 – The Output

Now we need to include the output code for each bookmark. The code for this will be included within the foreach loop – so we only need to include it once, as the foreach loop will cycle through the array and display each link according to our specification.

This is what that code looks like:

<li>
<a title="<?php echo $bookmark->link_name; ?>" href="<?php echo clean_url($bookmark->link_url); ?>" target="_blank">link_name; ?></a>
</li>

Within that code snippet, we’ve used 3 variables (from the data dump we produced in Step 2) to dynamically construct the output of each link. This tutorial assumes that you’re comfortable with the HTML involved here – so I won’t be covering that. But I would like to just define the 3 variables we’ve used:


<ul>
<li>$bookmark->link_url - The external URL of the link</li>
<li>$bookmark->link_name - The name / title of the link</li>
<li>$bookmark->link_image - The image of the link (in this case it'd be the favicon we'd like to display</li>
</ul>

So if you include this code in our global code snippet, you would have the following complete, custom widget function:

<div id="links" class="widget">
<h3>Kudo's & Respect</h3>
<ul>$bookmarks = array();
$bookmarks = get_bookmarks('category=111&orderby=rand');
foreach ( $bookmarks as $bookmark ) {
?>
<li><a title="<?php echo $bookmark->link_name; ?>" href="<?php echo clean_url($bookmark->link_url); ?>" target="_blank"><?php echo $bookmark->link_name; ?></a></li>
</ul>
</div>
<!--widget-->

Step 5 – The Style

The last step is to add some simple styling to align the favicon & link appropriately. Here’s some similar CSS to which I use to construct the “Kudo’s & Respect” widget on my own blog:

#links ul li {
float: left;
display: inline;
margin: 0 20px 0 0;
line-height: 30px;
}

#links ul li a {
color: #000;
text-decoration: none;
font-size: 12px;
line-height: 16px !important;
padding: 1px 0 1px 26px;
}

#links ul li a:hover {
color: #666;
}

Conclusion

As you will see from the above example, it is not overly advanced to create a custom output function using arrays and custom queries in WordPress (the HTML & PHP involved are both only at an intermediate level). Even though most WP users will never find the need to use a custom function like this, it is helpful to those of us that likes to push WP’s boundaries.

Using the exact same method as I’ve used, you can create similar custom functions for categories, pages & posts. The easiest way of determining how to construct one’s own output is by simply dumping the data from your queried array to the screen (as in Step 2 in the example) and using that as a reference point for your output.

Comments

comments