February 24, 2012 archive

Or perhaps you have created a custom theme and you would like to have a way for the users of your theme to receive notifications and updates whenever you update the theme? You can then fix up your theme, post a new version and... ta da... all your clients get the notification and can "update automatically" to the latest version?

If you've been looking to do this... and aren't afraid of (or enjoy!) working with the git version control system and Github, there's a very cool way to do all this that gives a very similar user experience:

In fact, it winds up being a bit better than the normal WordPress theme auto-update process because after you do the update, you actually have the ability to roll back to previous versions of the custom theme if the new one causes problems:

This is something you can't do easily with the normal WordPress theme update process.

Initial Setup / Configuration

If you want to set this up for your own themes, here's the process...

1. Publish Your Theme To A Github Repository

You need an account (which is free) on Github, and you need to create a repository (a.k.a. a "repo") there for your theme. If you've never used git before, Github has some great help pages that explain the process. If you use a Mac, there is also a great Github for Mac app that makes the process super simple of updating your git repo locally and pushing the changes to Github.

The end result is that you need to have a git repo on your local computer that has your theme and that repo is synced up to a corresponding repo on Github.

I'll note that this process only works with public Github repositories, so your code does have to be open to the public. If you want to keep your code private so that only you and your clients see it, this process won't work for you. (Although see the notes at the bottom of the post.)

2. Modify Your Theme To Include a Github URI

The next step is to go into your style.css file in your theme and add one critical line containing a "Github Theme URI":

Theme Name: Example  
Theme URI: http://example.com/  
Github Theme URI: https://github.com/username/repo-name
Description: My Example Theme
Author: person
Version: v1.0.0

You can see an example in a demo theme I have. The URL you use is that of your repository up on Github. That's it.

Now you need to commit this change to your local repo and push the change up to Github.

3. Create a Tag in Your Repository

In your local repo, you need to "tag" the repo with a version number. THAT VERSION NUMBER NEEDS TO MATCH WHAT YOU HAVE IN STYLE.CSS for everything to work right. You then need to push this tag up to Github. Here are the command-line commands you need:

$ git tag v1.0.0
$ git push origin v1.0.0

Obviously with whatever version number you use.

4. Upload Your Theme To WordPress

Now your theme is all ready to be uploaded to your WordPress site. There are a couple of different ways you can do this, but one simple way is:

1. Create a ZIP file of your theme on your local computer.
2. Inside your WordPress admin menu (standalone) or network admin menu (MultiSite) go to the Install Themes panel and click on "Upload".
3. Choose your ZIP file and press "Install Now".

You'll now have the theme installed in your WordPress site. You can now activate it and use the theme for your site.

5. Install the Theme Updater Plugin

Here's the part that makes the "update notifications" piece all work nicely. Some guys down at the University of Central Florida came up with this very cool plugin for WordPress called "Theme Updater" that is available here:

http://wordpress.org/extend/plugins/theme-updater/

You can either download it from that site or, much more simply, just go into the Plugins menu of WordPress, choose "Add New" and search for "Theme Updater".

(NOTE: The plugin does work with WordPress 3.3.1, so you can ignore the warning message about the plugin not being tested with your version. The meta-data for WordPress.org simply didn't get updated when the new version was recently posted. Given that I was doing some of the last testing, I can tell you that I did the testing on WordPress 3.3.1 on both a standalone and a MultiSite installation.)

Once you have installed the plugin, you simply activate it - or in WordPress MultiSite do a "Network Activate".

That's it. There is no configuration panel. No options. It just sits in the background and checks for updates of the Github-hosted theme.

That's all that is involved with the setup. Your installed theme is ready to be automatically updated. So, now you want to do the update...

Updating The Theme

When you have updates, the process is pretty straightforward.

1. Make And Commit Your Theme Updates

Edit your theme, make whatever changes, modifications, additions you need.

Commit your changes to your local git repo and push those changes to Github.

2. Update The Version Number in Style.css

In your style.css file, increment your version number, as in this example:

Theme Name: Example  
Theme URI: http://example.com/  
Github Theme URI: https://github.com/username/repo-name
Description: My Example Theme
Author: person
Version: v1.1.0

Commit the change locally and push the change to Github. (And yes, this could have simply been done as part of step #1.

3. Create a new tag and push the tag

Create a tag in git that matches the version number in step #2 and push that tag up to Github:

$ git tag v1.1.0
$ git push origin v1.1.0

That's it!

Now users of your custom theme will get a notification along the lines of this in WordPress MultiSite:

or this in the "regular" standalone mode of WordPress:

and can simply "update automatically" to get the new version of the theme.

Other Notes

The "Theme Updater" plugin for WordPress is naturally hosted on Github:

https://github.com/UCF/Theme-Updater

You can see the source code there, download the latest, etc. If you are a Github user, you can "watch" the repo, fork it, clone it, etc.

If you find an issue with the plugin or have a feature request or suggestion, you can raise an issue (assuming you are logged in to your own Github account) in the Issues area.

I don't know but I get the sense that the UCF team made this plugin for their own usage and don't necessarily have grand plans for future versions (i.e. it works fine for them now). But if you want to add functionality yourself, like, oh, for instance adding in the ability to connect to private Github repos, you can certainly use the standard Github process of forking the repo, adding in code and then issuing a pull request to get your changes merged in. (And if that last sentence made absolutely no sense to you, don't worry about it and just have a nice day! ;-)

All in all I've found this to be a great process to let me publish a custom theme publicly and then auto-update multiple sites off of that custom theme. Kudos to the UCF team for creating this plugin and making it available!

If you found this post interesting or useful, please consider either:

• following me on Twitter;
• adding me to a circle on Google+;
• subscribing to my email newsletter; or
• subscribing to the RSS feed.