Recently I released a WordPress plugin for Google Analytics that adds a tracking code and dozens of various pieces of meta data to blogs. Since the release of version 4, I’ve updated it 6 times, to the point where it’s now at version 4.0.6. In this article I would like to share with you my experiences in maintaining this and other WordPress plug-ins and common good practices that I’ve distilled from that work.The updates that I released had a couple of purposes, ranging from bug fixes to new features and fixes in documentation. While all of these are nice to talk about, the bug fixes are the ones you’ll learn the most from, so let’s start by going through these.Website and Account ConfigurationAlmost as soon as I released the plug-in, people who updated were telling me that it worked wonderfully, and others were telling me that it didn’t work for them. Turns out I hadn’t tested the plug-in with a Google Analytics account that has only one website registered; I expected the websites to be an array. Fixing this bug was easy, but determining that this was the problem took a while.Being able to log into a few hosts of people who gave me access to their back end and FTP so that I could test my fix proved invaluable. This enabled me to release 4.0.1 within an hour of the 4.0 release.Another mistake I made was forcing everyone to reconfigure the plug-in. I assumed it wouldn’t be too much work for people, and it wanted to be sure the settings were clean, but it turns out quite a few people didn’t want to reconfigure. With 4.0.2, I came up with a way to inherit some of the settings and clean up the mess I made, and in 4.0.4 I made a change that I will add to all of my plug-ins:Large viewGood practice #1: Don’t assume anything about people’s websites and external accounts.Versioning Option ArraysAs a seasoned WordPress developer, I store all of the options for my plug-in in one option in the database, which is basically a big array. Why I hadn’t ever added a version number to these options is a mystery to me. Doing so makes it possible to do some very cool things: I can now add new features and set a default for these new features as soon as a user upgrades; I can show the user different messages based on the version they had before they upgraded; and more.Good practice #2: Add a version number to your option arrays.I’m still not using the WordPress option API stuff (check out this post by Ozh to learn all about it), which I probably should, but for now I find it easier to handle the saving and validation of options myself.Don’t Release Too SoonIf you’ve got a bug that’s bugging a lot of your plug-in’s users, you’ll probably want to release a bug fix as soon as possible. I know I do. This caused an issue with my 4.0.3 release, though, because I didn’t properly test some of the code I introduced, causing me to have to release 4.0.4 just two hours later to fix a stupid mistake I’d made with booleans. Nothing is as painful as 500 people downloading a version of your plug-in that doesn’t actually work.Good practice #3: Test, test, test before you release, even when you’re in a hurry.Know Which Version People Are OnOver the past two weeks, I’ve been helping several people who said they were on the latest version of my plug-in but in fact were not. To remedy this, I’ve started outputting the version number in the comment that the plug-in outputs before the tracking code. Problem is, if people run a plug-in such as W3 Total Cache (which everyone should use by the way) or anything else that minifies their output, that comment will get lost.There’s a solution for that, too: I’d already wrapped the script in <CDATA> tags, to help with Strict XHTML validation. Minifying will not occur within those CDATA tags, so I moved my “branding” comment to the CDATA section, and I can now always see, first, that my plug-in is active and, secondly, which version of the plug-in they’re using.Good practice #4: Make sure you can see which version of your plug-in people are running.URLs in WordPressOne of these things that can generate pretty awful bugs is a blog’s URL. Whether it’s due to people running their entire blog on https or “simply” running their blog in a sub-directory, it can cause headaches. It did for me in version 4.0.2 when I added URL sanitization: all relative URLs in posts and text widgets starting with a / were made absolute, in order to properly track these URLs. Tiny issue: I forgot about blogs in sub-directories, so a tiny portion of people would end up with links that used to go to /home but that now went to http://example.com/blog/home. I know, that was stupid; but that’s why I’m telling you: so you don’t make the same mistake.Good practice #5: Make sure all URLs you use will work in all circumstances, whether WordPress is in a sub-directory, on a subdomain or just in the root.Writing to the Root DirectorySomewhat related to the last issue, although I encountered this while developing my WordPress SEO plug-in, not the Google Analytics plug-in: if you write a file — say, an XML site map file — to the root of a website, and the website is actually a WordPress multi-site installation, things can go horribly wrong.Check out the following scenario:User 1 writes and publishes a post on example.com/blog-1/.An updated XML site map for example.com/blog-1/ is generated, and example.com/sitemap.xml is updated.User 2 writes and publishes a post on example.com/blog-2/.An updated XML site map for example.com/blog-2/ is generated and example.com/sitemap.xml is overwritten.See what just happened? The XML site map now contains only the posts from blog-2… This is exactly why the wp-content directory was created. There’s hardly ever a need to put a file in the root of an installation, and by not doing so, you make it far easier to run your plug-in in a multi-site/WordPress MU environment.Good practice #6: If you’re generating files, generate them in the wp-content directory of your blog. Do not write files to the root directory unless you absolutely, positively have to. And if you do have to do it, make sure it doesn’t go wrong when your plug-in is active on multiple blogs in the same multi-site instance.Rethink Your FiltersOn the day that I released 4.0, I got quite a few feature requests, ranging from very simple to somewhat more complex. One that came in quite rapidly and caught my eye happened to be quite simple: the user wanted the same outbound link that in my plug-in tracks the content of an article to track in text widgets. Because I don’t use text widgets that much, it never occurred to me to do this. It was a valuable lesson, though:Large viewGood practice #7: If you’re filtering content, try to filter it in as many places as you can, so that users get consistent results all over WordPress.[Offtopic: by the way, did you already get your copy of the Smashing Book?]Never AssumeIt’s true for everything, I guess, but especially true for WordPress developers: never assume. The seven best practices above mostly boil down to abandoning all assumptions about states, URLs and locations, and even about people knowing which version of a plug-in they’re using. Take all these matters into your own hands; your plug-in will be the better for it!(al)© Joost de Valk for Smashing Magazine, 2010. | Permalink | Post a comment | Add to del.icio.us | Digg this | Stumble on StumbleUpon! | Tweet it! | Submit to Reddit | Forum Smashing Magazine Post tags: plugin, wordpress
-
I posted to smashingmagazine.com
Lessons Learned From Maintaining a WordPress Plug-In
http://feedproxy.google.com/~r/SmashingMagazine/~3/GEGoKQ8VDXo/
July 30 2010, 9:04am | Comments »
-
I posted to smashingmagazine.com
Introducing Tweetbacks Plugin for Wordpress
http://www.smashingmagazine.com/2009/01/09/tweetbacks-plugin-for-wordpress/
Just yesterday we introduced Twitter Avatars In Comments plugin for Wordpress that enables bloggers to have both Twitter and Gravatar avatars in blog comments. We are certainly not going to turn Smashing Magazine into a repository of Twitter plugins for Wordpress, but we are confident that it does make sense to introduce another plugin that enables another kind of Twitter integration in blogs.
This is why this post releases the Twittbacks WordPress Plugin that was developed and released especially for Smashing Magazine — this plugin imports tweets about your posts as comments. You can display them in between the other comments on your blog, or display them separately. Advantages of our implementation This implementation is inspired by Dan Zarrella’s great work on TweetBacks. Although his implementation does what it promises, we felt that it could be done in another way and offer users an alternative to display tweets in a more convenient way. Dan’s solution uses JavaScript, which will work on more platforms, but we felt that it would be useful to actually store the tweets in the database instead of using JavaScript to display them. Because our implementation stores Tweets in the database, you can create new plugins that use this data on the top of our plugin. Besides, our implemenation does not does not require JavaScript and requires significantly less time to load (server-side, not client-side). (Because we know you want to test this, and be able to ditch the plugin if you don’t like it, we’ve added an uninstall function, which will delete all the stored tweets from your WordPress database.) Installation The installation couldn’t be simpler:
download the plugin from Joost de Valk’s release post, copy the “tweetbacks” folder to your plugin folder (wp_root/wp-content/plugins); login inside your WordPress administrator panel and activate this plugin (Click “Plugins” and then “Activate” near to the plugin title); if you are using Wordpress 2.7, just add the code presented in the next section of this post (Styling and Adding Tweetbacks in Wordpress 2.7) and you are done. otherwise if you are using older versions of Wordpress, you can add Twitterbacks similarly to the way it is presented in this tutorial:
Access your comments.php file and locate the following code:
<?php foreach ($comments as $comment) : ?>
Immediately after the above code, place this code:
<?php $comment_type = get_comment_type(); if($comment_type == 'comment') { ?>
Next, scroll down a little bit and locate the following code:
<?php endforeach; /* end for each comment */ ?>
Put the following code right before the above code:
<?php } /* End of is_comment statement */ ?>
This will filter out all of the tweetbacks, trackbacks and pingbacks from your main comments loop. Now we need to create a second comments loop to display tweetbacks, and a third loop to display the trackbacks and pingbacks.
Right under the code from step 2 you should find this code:
<?php else : // this is displayed if there are no comments so far ?>
Put the following code right before the above code:
<h3>Tweetbacks</h3> <ol>
<?php foreach ($comments as $comment) : ?> <?php $comment_type = get_comment_type(); ?> <?php if($comment_type = 'tweetback') { ?> <li><?php comment_author_link() ?>: <?php comment_text() ?></li> <?php } ?> <?php endforeach; ?>
Followed by this:
<h3>Trackbacks</h3> <ol> <?php foreach ($comments as $comment) : ?> <?php $comment_type = get_comment_type(); ?> <?php if($comment_type != 'comment') { ?> <li><?php comment_author_link() ?></li> <?php } ?> <?php endforeach; ?> </ol>
And you are done.
Styling and Adding Tweetbacks in Wordpress 2.7 As the plugin will import these tweets into your comments, they will by default be shown as normal comments on your blog. They will get the class tweetback. If you’re using WordPress 2.7 and the default theme, or any other theme that has taken the styling from the comments from the default theme (which is a sensible thing to do), you could style these tweetbacks by adding something like this to your stylesheet:
.commentlist li.tweetback { background-color: #94E4E8; } If you want to display them separately, you’ll have to separate your comments, pingbacks and tweetbacks from each other. A great tutorial on how to do that is Separating Pings from Comments in WordPress 2.7. After you’ve done that, you can add the following code to display the tweetbacks:
if ( ! empty($comments_by_type['tweetback']) ) :?> <h2 id="tweetbacks"><?php echo count($comments_by_type['tweetback']);?> Tweetbacks to “<?php the_title(); ?>”</h2> <ul class="commentslist tweets"> <?php wp_list_comments('type=tweetback'); ?> </ul> <?php endif;
If you want to give that list of tweetbacks a different look and feel, you can add a callback to the wp_list_comments call above. The callback could make them look like this, for instance:
The code for the callback used above looks like this:
function yoast_list_tweetbacks($comment, $args, $depth) { $GLOBALS['comment'] = $comment; $avatarurl = str_replace("twitter:","http://s3.amazonaws.com/twitter_production/profile_images/",$comment->comment_author_email); ?> <li class="tweetback" id="comment-<?php comment_ID(); ?>"> <div id="div-comment-<?php comment_ID(); ?>"> <div class="comment-author vcard"> <img alt='' src='<?php echo $avatarurl ?>' class='avatar avatar-40 photo avatar-default' height='40' width='40' /> <cite class="fn"><a href="<?php echo $comment->comment_author_url; ?>" rel='external nofollow' class='url'><?php comment_author(); ?></a></cite> <span class="says">says:</span> </div> <div class="comment-meta commentmetadata"><a href="#comment-<?php comment_ID(); ?>"><?php comment_date('F jS, Y'); ?> at <?php comment_date('H:i:s'); ?></a></div> <p><?php comment_text(); ?></p> </div> </li> <?php }
Because these tweetbacks are stored as comments in your database, you can all sorts of cool things with them. Improving the Web has written a Widget pack that will work with this plugin, called Tweet Stats. It allows you to add widgets with “Recently tweeted posts” and “Most tweeted posts” (see examples below).
If you have any installation problems, questions or suggestions for this plugin, please either comment on this post or add your suggestions in the support forum on Wordpress.org. About the author The plugin was developed by Joost de Valk, a Dutch geek and WordPress developer. You can follow him on Twitter.
January 9 2009, 3:42am | Comments »
1