Social Bookmarking with WordPress Plugin Part II: Displaying a Digg button

Now it’s time to expand our plugin with concrete functionality and add a Digg link to every post on our blog.

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 Digglink:
    /* 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 'Digg This';
    }
  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 Thislink 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;

 

‘); ?>
<b><?php if (function_exists(WPDiggThis_Link)) echo WPDiggThis_
Link(); ?></b>

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.

 

 

File

PAGE

DESCRIPTION

index.php

Main index file

This is the main theme file; it is used to render any page as a replacement if the ‘specialised’ file listed below is missing

home.php

Home page

Used to display contents of the home page of the blog, which usually includes a list of recent posts.

single.php

Single post

Called when you click on a single post to display post comments; usually includes comments template at the end.

page.php

Page Template

Same as single post, but is used for displaying pages

archive.php

Archives

Displays blog archives, such as earlier posts, posts by month or categories.

comments.php

Comments

Template responsible for showing user comments and the comment area for new comments

header.php

Header

Outputs the header for every page, usually containing information such as title and navigation, and includes theme style sheets and so on

footer.php

Footer

The footer of every page, usually containing copyright information and useful links

search.php

Search results

This template is used to show search results for your blog; It is usually similar to archive.php but also includes information about the searched phrase

sidebar.php

Sidebar

Shows the blog sidebar; if the theme supports widgets, it will also include widget support functions

404.php

404 file not found page

Default page for showing missing (404) pages on your blog

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.

WordPress Plugin Development (Beginner’s Guide)
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


About the Author