Lessons Learned From Maintaining a WordPress Plug-In

Recently I released a WordPress plug-in 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 my experiences in maintaining this and other WordPress plug-ins and other common practices that I’ve distilled from this work.

The updates that I released had a couple of reasons, ranging from bug fixes to new features and also fixes in documentation.

Website and Account Configuration

Almost as soon as I released the plug-in, people who updated it told me that it worked wonderfully, and others were said that it didn’t work for them. I later figured that I hadn’t tested the plug-in with a Google Analytics account that only had one website registered. Fixing this bug was easy, but determining this problem took a while.

Being able to log into a few hosts gave me access to back end and FTP of these people was invaluable as it helped me to test my fix. 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 to make sure the settings were clean, but it turned out that a lot of 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:

Good practice #1: Don’t assume anything about people’s websites and external accounts.

Versioning Option Arrays

As 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 Soon

If you’ve got a bug that’s bugging your plug-in’s users, you’ll probably want to release a bug fix as soon as possible. This caused an issue with my 4.0.3 release, 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 On

Over 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, which 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 the people are running.

URLs in WordPress

One of the 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 sub domain or just in the root.

Writing to the Root Directory

Somewhat 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 Filters

On 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 users 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:

30 Tutorials Combining Both WordPress and jQuery

Take the most popular CMS, WordPress, and then take the easiest and most versatile of Javscript libraries, jQuery, and you have a match made in heaven. Implementing jQuery within WordPress is a lot easier than you would think, all you need is a little support from the huge WP community and a little patience, and you are good to go. Below you will find 30 Tutorials Combining both WordPress and jQuery.

Including jQuery in WordPress (The Right Way)

When you download jQuery, put it on your server and link to it from your header.php file in the <head> section, this can cause you problems. Some plugins use the jQuery library, and they are going to load it as well and on top of that already has the jQuery library included. This can cause problems.
In this tutorial you will learn how to load up jQuery in your theme the smart (and intended) way, avoiding conflicts.

Display a Random Post (with AJAX Refresh)

In this tutorial you will learn how to display a random post with Ajax refresh, and you will be surprised at how easy this is to do. You are going to leverage some serious smartness from both WordPress and from the JavaScript library jQuery.

Design An Elegant Featured Content Slider for WordPress

In this tutorial, you’ll create an elegant featured content slider for WordPress based on The Coda Slider, a neat device used by Panic Software to display information about their “Coda” product on their website. This effect is beautiful, flexible, and often emulated.

Create an Attractive jQuery Menu with Fadein and Fadeout Effect

In this tutorial you will create a jQuery menu using the Fadein and Fadeout effect. To develop the menu it requires a lot of CSS works, so roll up your sleeves.

How to Highlight Search Terms with jQuery

A nice way to spice up your WordPress search page is to highlight search terms within your search results. In this tutorial you will learn to highlight both title and post content.

WordPress Featured Post Slideshow

In this tut you’ll be learning how to create a featured and “latest posts” section within WordPress, and animate it with jQuery. You will be using the jQuery Cycle plugin built for slideshows. To make it work you give it an element and it turns every child of that element into a slide.

Implement a Nice & Clean jQuery Sliding Panel in WordPress

In this tutorial, you will learn how to create a smooth sliding login/signup panel for your WordPress site using jQuery.

Build a Basic Newspaper style layout with WordPress and jQuery

Grid and Magazine templates are becoming more and more popular in WordPress development, so, in this tutorial you will use jQuery to create a grid layout with size-degrading headers.

Build the ANidea Theme Switcher using jQuery

This tutorial will teach you how to create the cool theme switcher that is used on the ANidea web site. In the tutorial, you’ll cover the client side of Theme Switcher, which consists of the HTML, CSS and JavaScript (jQuery).

How To Create Tabs Using jQuery

This tutorial is primarily for WordPress, but can easily be ported anywhere else. You will be creating a tabs section within the sidebar, a popular and useful feature in WordPress themes.

Use jQuery to Jazz Up Your List of Latest Posts

A lot of blogs display a list of their most recent or popular posts in their sidebar, more often than not just showing the title of each one. But how can you give your reader an idea of what that post is about by using the excerpt, without taking up too much room? Using a little jQuery, you can.

Create a jQuery Carousel with WordPress Posts

This tutorial will give you a quick run down of how to easily add a simple and easily customizable carousel with WordPress posts from a specified category, using the jQuery plugin jFlow.

Adding Form Validation to WordPress Comments using jQuery

When it comes to simpler user experience, having your form validation happen instantly on the same page is a lot cleaner than reloading pages and possibly losing some form content. In this tutorial you’ll be shown how to use jQuery to do some instant checking on a comment form.

Using jQuery to liven up your WordPress Login

Using the jQuery principal “less is more…”, in this tutorial you will learn a quick method of simplifying the clients login process using a jQuery lightbox.

Drupal Cheat Sheet Desktop Wallpaper

In this post we release a yet another freebie: a Drupal Cheat Sheet Desktop Wallpaper, a desktop wallpaper that features most popular variables of the open source content management system Drupal. The wallpaper was created by Giovanni Scala for Smashing Magazine and its readers.

Release in Drupal Cheat Sheet Desktop Wallpaper

Download the wallpapers for free!

Preview in Drupal Cheat Sheet Desktop Wallpaper
Continue reading