xybermatthew

In our last article we built our first WordPress plugin that simply described what the plugin does for the user and checks whether it works on the currently installed version of WordPress. Lets continue on with our part two of our four part series.

Displaying a Digg button

In order to create a link we will need to extract post’s permalink URL, title, and description. Luckily, WordPress provides us with a variety of ways to do this.

Time for Action – Implement a Digg link

Let’s create a function to display a Digg submit link using information from the post.

1. Add a function to our plugin to display a Digg link:

   /* Show a Digg This link */
   function WPDiggThis_Link()
   {
    global $post;
   
    // get the URL to the post
    $link=urlencode(get_permalink($post->ID));
   
    // get the post title
    $title=urlencode($post->post_title);
   
    // get first 350 characters of post and strip it off
    // HTML tags
    $text=urlencode(substr(strip_tags($post->post_content),
     0, 350));
   
    // create a Digg link and return it
    return '<a href="http://digg.com/submit?
     url='.$link.'&amp;title='.$title.'
     &amp;bodytext='.$text.'">Digg This</a>';
   }
   

2. Open your theme’s single.php file and add a call to our function just below the line with the_content(). If you are not sure how to do this, see the forthcoming section on “Editing the theme files”.

   <?php if (function_exists(WPDiggThis_Link))
     echo WPDiggThis_Link();?>
   

3. With the default WordPress theme, this change will look something like this (you can also refer to the following image):

   

4. After you save the theme file, your blog posts will now automatically have the Digg This link shown after the content:

   

5. Clicking the link will take the user directly to the Digg site, with all the required information already filled in:

   

Well done! You have created your first working WordPress plugin!

What just happened?

When WordPress loads a post, the single.php template file from the currently active WordPress theme is ran. We added a line to this file that calls our plugin function WPDiggThis_Link() just after the content of the post is displayed:

<?php the_content('<p class="serif">Read the rest of this entry
  &raquo;</p>');?>

<?php if (function_exists(WPDiggThis_Link))
  echo WPDiggThis_Link();?>

We use function_exists() to check our function because it exists only if our plugin is installed and activated. PHP will generate an error if we try to run a nonexistent function. But if we deactivate the plugin later, we don’t want to cause errors with our theme. So, we make sure that the function exists before we attempt to run it.

Assuming that the plugin is present and activated, the WPDiggThis_Link() function from our plugin is ran. The first part of the following function gets information about our post and assigns it to variables:

/* Show a Digg This link */
function WPDiggThis_Link()
{
global $post;

// get the URL to the post
$link=urlencode(get_permalink($post->ID));

// get the post title
$title=urlencode($post->post_title);

// get first 350 characters of post and strip it off HTML tags
$text=urlencode(substr(strip_tags($post->post_content), 0, 350));

We use the urlencode() PHP function for all the parameters that we will pass to the final link. This will ensure that all the values are formatted properly.

The second part uses this information to construct a Digg submit link:

// create a Digg link and return it
return '<a href="http://digg.com/submit?
  url='.$link.'&amp;title='.$amp;title.'
  &bodytext='.$text.'">Digg This</a>';
}

It returns this HTML text so that it gets added to the WordPress output at the point where the function is called – just after the post is displayed. Therefore, the link appears right after each post — which is convenient for the user who has just finished reading the post.

Using the Digg API

Usually, when using the functionalities of third-party sites, as we are doing in our example with Digg, we would search for the API documentation first. Almost all the major sites have extensive documentation available to help developers use their services in an effective way.

Digg is no exception, and if you search the Internet for the digg button api you will find a page at http://digg.com/tools/integrate that will have all the details we need in order to implement our Digg functionality.

Digg allows us to use several different ways of using their service.

For the start, we will display just a Digg link. Later, we will expand it and also display a normal button.

Here is what the Digg documentation says about formatting a submit link.

Submit URL:

http://digg.com/submit?
url=example.com&title=TITLE
&bodytext=DESCRIPTION&media=MEDIA
&topic=TOPIC

Submit URL Details:

• url =example.com
  
  Maximum length is 255 characters
  
  Story URL should be unique and devoid of session or user-specific data
  
  Please URL-encode all strings as appropriate. For example:
  
  http%3A%2F%2Fyourwebsite%2Fyourstoryurl%2Fstorypagedetails.html
• title =TITLE
  
  Maximum length is 75 characters
  
  Please also URL-encode the story title
• bodytext =DESCRIPTION
  
  Maximum length is 350 characters
  
  Please also URL-encode the body text

Using this information, we are able to create a valid link for the Digg service from the information available in our post.

Acquiring post information

WordPress provides a number of ways to get information about the current post.

One of them involves using the global variable $post, which stores all the relevant information for the current post. We have used it in our example to extract the post title and content, but it can also be used to get other information such as post category, status and so on.

WordPress also offers an array of functions we could have used to access post information such as get_the_title() and get_the_content().

The main difference between using these functions and accessing post data directly using $post variable is in the end information we get. The $post variable contains raw information about the post, just as the user wrote it. The functions mentioned above take the same raw information as a starting point, but could have the final output modified by external factors such as other active plugins.

You can browse through the wp-includes/post-template.php file of your WordPress installation to get a better understanding of the differences between using the $post variable and the WordPress provided functions.

Post permalink URL

In order to obtain post URL we used the get_permalink() WordPress function. This function accepts the post ID as a parameter, and as a result, returns post’s actual URL on the blog. It will always return a valid URL to your post no matter what permalink structure your blog is using.

Editing the theme files

In our example, we had to edit our theme in order to place the Digg link under the post content. WordPress allows for easy theme editing through the built-in Theme Editor panel.

After selecting the theme you want to edit, you will be presented with a number of options. Every theme consists of various PHP template files, each covering different blog functionalities.

Here is a reference table detailing the most commonly used template files.

Always be careful when editing the theme files as any kind of mistake in your syntax can cause an error in displaying the page. It is therefore good practice to first backup theme files, so you can safely revert to them afterwards.

Quick reference

$post: A global WordPress variable containing information about the currently processed post.

get_permalink($post_id): Returns the full URL to the post given by its ID (for example $post->ID).

function_exists($function): Helps the PHP function to check if the given function exists. It is useful in themes when we want to include our function.

urlencode($string): Helps the PHP function to properly format the parameters to be used in a URL query.

Have a go Hero

Our plugin already has useful functionality. Try to customize it by:

• Calling our Digg link function from different places in the theme template, for example, before the content or after the tags are displayed (look for the_tags() line in the template).
• Adding the function to other theme templates such as the main index file and archive pages to display the Digg links on the home page and blog archives as well.
• Using the get_the_title() and get_the_content() functions to obtain post title and content instead of using the $post variable.

In our next article we will continue to expand our plugin and update it for other themes and begin using some plugin hooks.

WordPress Plugin Development (Beginner’s Guide)

Build powerful, interactive plug-ins for your blog and to share online Everything you need to create and distribute your own plug-ins following WordPress coding standards Walk through the development of six complete, feature-rich, real-world plug-ins that are being used by thousands of WP users Written by Vladimir Prelovac, WordPress expert and developer of WordPress plug-ins such as Smart YouTube and Plugin Central Part of Packt’s Beginners Guide series:expect step-by-step instructions with an emphasis on experimentation and tweaking code http://www.packtpub.com/wordpress-plug-in-development/book