wordpress-generic

Sometimes you may want to design and build a theme that doesn’t use the same boring, standard social sharing buttons that spit iframes out all over your pages. There is a huge selection of social sharing plugins available for WordPress, but I’ve often felt the vast majority of them look and feel too much like… well, plugins. They display like what they are: disparate chunks of third party code that have been Krazy-glued onto your elegant theme.

If you want your own design and are willing to forgo the ability to display a count, you can try building something a little more custom. And if you’ve got a passing knowledge of template tags and Javascript, this is a piece of cake to implement! It also allows you to avoid doing things like wrapping a jQuery plugin (ie., Sharrre) in a WordPress plugin (and then possibly having to wrestle with php.ini files and server settings as well).

This tutorial is going to cover adding buttons to share on Twitter, Facebook, Google+, and Pinterest. Please keep in mind that this is not a technique for your average WordPress user: this is a developer technique for theme-builders who want to create themes with sharing features built directly in. If you’re just looking to add standard sharing buttons to your blog posts, there are plenty of quality plugins for exactly that purpose.

Still in? Then let’s begin! Open up your WordPress theme directory.

Add the HTML to display share links

Find the file where you want to display the sharing links. This would probably be single.php (the single post view) and/or in the loop. Below is some code showing the share links. You can put whatever code you want inside and around the anchor tags. Just make sure the attributes are in place.

<div class="socialShare">

	<a class="twitter shareLink" title="Tweet" 
		href="http://twitter.com/intent/tweet?url=<?php urlencode(the_permalink()); ?>" 
		data-tweet="<?php the_title(); ?>"
		data-hashtags="foo,bar"
		data-via="twitterUsername"
	>
		Tweet
	</a>
	
	<a class="pinterest shareLink" title="Pin It" 
		href="http://pinterest.com/pin/create/button/?url=<?php urlencode(the_permalink()); ?>"
		data-media="<?php echo $image_url; ?>"
		data-description="<?php the_title(); ?> - <?php the_permalink(); ?>"
	>
		Pin It
	</a>
	
	<a class="facebook shareLink" title="Facebook"
		href="http://facebook.com/dialog/feed?link=<?php urlencode(the_permalink()); ?>" 
		data-name="<?php the_title(); ?>"
		data-picture="<?php echo $image_url; ?>"
		data-caption="I just read <?php the_title(); ?> at <?php the_permalink(); ?>"
		data-redir="<?php bloginfo('template_url'); ?>/closeDialog.html"
	>
		Facebook
	</a>
	
	<a class="googleplus shareLink" title="Google+" 
		href="https://plus.google.com/share?url=<?php urlencode(the_permalink()); ?>"
	>
		Google+
	</a>
	
</div>

Now we’re getting down to it. The URLs that were provided by the share links’ href attributes are the base share dialog activation with the shared link encoded with PHP. The details of the content that you’re sharing is in the data- attributes, and will be encoded and appended to the URL via Javascript. The reason the share URL is encoded with PHP and not Javascript is so that the share will still work even if Javascript fails or is disabled.

Data attributes are always prefixed “data-”, but can then be called anything you’d like. I’ve named them to match the URL parameters they are supplying.

The URL parameters that each social share link accepts are as follows:

  • Twitter: ?url=[URL], &text=[tweet text], &hashtags=[comma-separated list of hash tags, no # symbols], &via=[Twitter username, no @ symbol]
  • Pinterest: ?url=[URL], &media=[absolute path to image file], &description=[description text]
  • Facebook: ?link=[URL], &display=[popup], &app_id=[Facebook app ID; see below], &name=[title], &picture=[absolute path to image for thumbnail], &caption=[description text], &redirect_uri=[absolute path to page to go to upon share completion; see below]
  • Google+: ?url=[URL], &hl=[language code] (As of this writing, these are the only parameters that the Google+ share link can be passed. It does the rest on its own.)

We will use PHP’s template tags to populate these data- attributes. Then we can access them with jQuery using the .data() method.

Note: I used my custom code for a featured post image as the data-media and data-picture attributes. You may not have this tag in your theme, or it may be called something different! If you leave the media (Pinterest) or picture (Facebook) parameters empty, the networks will do their best to gather the images on the page automatically.

Close dialog redirect

The Facebook parameter redirect_uri should be a path to an HTML file that contains nothing but a short script to close a window. Facebook uses this to redirect the user to another page when finished sharing. The reason this particular variable is defined in the HTML and not the Javascript file is because I want to be able to use the WP template URL tag. If it’s in the Javascript file, it needs to be a hard-coded absolute path: bad news if you decide to change servers or rename your theme.

Create a new HTML file in your theme root and call it closeDialog.html. Paste the following in and save:

<!DOCTYPE html>
<html>
	<head>
		<title>Close</title>
		<script>window.close();</script>
	</head>
	<body>
	</body>
</html>

As you can see, all this does is close itself. When passed to the Facebook dialog, it closes the popup window when the user has finished sharing. That way you don’t get redirected to your Facebook wall inside the popup window. You don’t have to use this if you’d prefer not to autoclose the window, but it’s become expected behavior, so the user will likely thank you for it.

Include jQuery

To make this actually do anything, we’re going to need jQuery. If jQuery isn’t already enqueued in your theme, there are a few ways to go about it. I won’t go into detail in this post, but there are resources out there as well as a nice Codex article on the wp_enqueue_script function.

Once you have jQuery enqueued, a Javascript file has to be added (if one doesn’t already exist in your theme). I like to create mine as follows: /wp-content/themes/[theme]/js/script.js. Once the file has been created, it needs to be loaded. This can be done by adding the following script tag to the theme’s footer.php file:

<script src="<?php bloginfo('template_url'); ?>/js/script.js"></script>

Note: You may wish to cache-bust this file to ensure that the users are served a fresh copy whenever it has been updated. For more information about cache-busting in WordPress, see this article on WordPress CSS and JS Caching. The cache-busted version of the above script include is as follows:

<?php $cachebustFile = '/js/script.js'; ?>
<script src="<?php echo get_template_directory_uri(); echo $cachebustFile . '?' . filemtime(get_template_directory() . $cachebustFile); ?>"></script>

Write the Javascript

Now that we have the HTML for our buttons and the data to share, it’s time to write the Javascript. Open the script.js file you created.

If you don’t already have custom jQuery scripts on your page and you’re starting this from scratch, you’ll need to use jQuery.noConflict() to relinquish jQuery’s control of the $ variable. If you don’t do this, your scripts will break in WordPress. I like to use $j as a replacement.

var $j = jQuery.noConflict();

$j(function(){
	
	$j('.twitter').on('click', function(e) {
		var $this = $j(this),
			tweet = encodeURI($this.data('tweet')),
			hashtags = $this.data('hashtags'),
			via = $this.data('via');
			
		e.preventDefault();
			
		window.open(
			this.href + '&text=' + tweet + '&hashtags=' + hashtags + '&via=' + via,
			'tweetDialog',
			'height=450, width=550, toolbar=0, status=0'
		);
	});
	
	$j('.pinterest').on('click', function(e) {
		var $this = $j(this),
			media = encodeURI($this.data('media')),
			description = encodeURI($this.data('description'));
			
		e.preventDefault();
		
		window.open(
			this.href + '&media=' + media + '&description=' + description,
			'pinterestDialog',
			'height=400, width=700, toolbar=0, status=0, scrollbars=1'
		);
	});
	
	$j('.facebook').on('click', function(e) {
		var $this = $j(this),
			name = encodeURI($this.data('name')),
			picture = encodeURI($this.data('picture')),
			caption = encodeURI($this.data('caption')),
			redir = encodeURI($this.data('redir')),
			appID = '[ENTER FACEBOOK APP ID HERE - SEE NEXT SECTION]';
			
        e.preventDefault();

        window.open(
            this.href + '&display=popup&app_id=' + appID + '&name=' + name + '&picture=' + picture + '&caption=' + caption + '&redirect_uri=' + redir,
            'facebookDialog',
            'height=300, width=550, toolbar=0, status=0'
        );

	});
	
	$j('.googleplus').on('click', function(e) {	
		e.preventDefault();
		
		window.open(
			this.href, 
			'gplusDialog',
			'height=600, width=600, toolbar=0, status=0'
		);
	});
	
});

This is straightforward jQuery. We’re attaching a click handler to each of our social sharing links and preventing default so that the link doesn’t take the user off the page to the partial URL provided in the HTML. Instead, we’re opening a new popup window (the share dialog). The dialog window will go to the base href link with the contents of the data- attributes appended to it by using the jQuery .data() method. We will encodeURI most of the data in these variables. If they contain links or other special characters and are not encoded, they will not work in the URL.

Now the social network has been given all the information it needs to populate the share dialog. We then give the new window some parameters, like height, width, hide toolbars, hide status bar, show scrollbars if needed.

Get a Facebook App ID for your share dialog

To create a Facebook app ID, you need to enable developer privileges for your personal Facebook account. This is free to do. The only caveat is that you cannot make up a dummy account to be your development account; that is a breach of Facebook’s Terms of Service, and they won’t permit it.

Once you have a developer account, go to the apps dashboard. Click the +Create New App button. Give your app a name (leave the other fields blank) and click Continue. Fill in some information about your app, including Display Name (title of your site), Contact Email, and App Domains. The App Domain should be the domain of your site.

Click the pane titled Website with Facebook Login and enter your site’s URL. Save your changes.

You can also set your app’s images by clicking on the little thumbnail icon at the top next to the app name. It is recommended to upload 16x16px and 75x75px thumbnails representing your site. The 16x16px icon will show up in your Facebook share dialog box.

Below your app’s name, an App ID is listed. Copy this numeric value. Open your script.js file and paste the app ID into the appID variable in the Facebook on(‘click’) handler. It may take a few minutes for Facebook’s servers to update, so be patient if your Facebook dialog throws an error for a little while.

Final Words

Now when the user clicks any of the share links, the appropriate dialog will pop up. They can fill in any additional information and submit. Upon submission, some networks provide confirmation and the option to view the share. The user can then close the dialog window (if it doesn’t autoclose, a la the Facebook autoclose we set up) and return to browsing your site.

At this point, you can see why we’ve done this with Javascript and data attributes instead of embedding the full URLs with all data directly into the href on the page and leaving it at that: the user has come to expect that these social networks open in a dialog window that will then go away. They do not expect to be taken off your site and to the sharing site instead, which is what would happen if we let the link have default behavior.

Some people like to add a target=”_blank” attribute to the HTML links in case the Javascript fails and the dialog doesn’t open in a separate window. I prefer not to, personally, because I dislike when sites open links in new tabs: it disables my use of the back button. I don’t like trying to hit “back”, discovering it doesn’t work, and then having to close a tab—a minor user experience enhancement, in my opinion.

Overall, this is just one way of approaching custom social sharing links. There are other ways to accomplish the same thing, but this method is valuable because it allows you to use several instances of share links on the same page, for example, on each post in an archive, as well as single posts.