Post Changelog Plugin for WordPress

Post ChangeLog Plugin (PCP) is a WordPress plugin which gives authors a set of tags to ease the writing of changelogs for posts and pages. You should see a live example of this at the end of this page.

Requirements

I’m really talking out of my hat here, since I haven’t done much testing, but it should work on and probably requires a WordPress 2 (or later) installation. I personally use Firefox, so it’s supported best, but Opera seemed to manage equally well in my brief testing. Internet Explorer support is somewhat limited, but it works… more or less. I have no experience in Macs and no access to such things, so Mac users are, at least for now, on their own with this. Sorry.

JavaScript support is only necessary if you want the changelog to be hideable; without JavaScript, the changelog will always be shown.

A note before installing

A word of caution: once you start using PCP, you’re stuck with it. The tags introduced by the plugin are not converted permanently but on-the-fly when the page is rendered, and thus, if you disable the plugin, all the tags will be left as they are, and your changelogs will end up looking pretty strange (at least for as long as <history>, <edit> and <at> are not part of any W3C specs implemented in browsers). So, it is safe to try, but think twice before you start using it continuously, because once you do, you’ll come to rely on this piece of code which might (and probably will, as all software does) eventually become obsolete.

Installation

Just drop it in your plugins directory, activate it from the dashboard and you should be go. Then skip to the Usage section below.

If the plugin doesn’t seem to work, make sure you have <?php wp_head(); ?> somewhere in your header template. The JavaScript and the CSS code used to show/hide the elements are provided by the plugin using wp_head hook, which requires that you have a wp_head(); call inside the <head>...</head> section, like in the default templates. So if you are using a third party theme or have done extensive modifications in the header template yourself, check to be sure it’s there. If it’s not, add it.

Usage

The structure for writing a changelog (or history) within a post, when using PCP, is shown in the following example:

<history>
  <edit><at>01:23</at> Added a link.</edit>
  <edit><at>12:34</at> Fixed a typo.</edit>
</history>

I believe the tag names are self-explanatory. When the post containing the above is published, the HTML code generated will, somewhat simplified, look something like this:

<p class="history"><a class="history" href="javascript:void(toggleD('pp2390'));"></a></p>

<div class="history" id="pp2390">
<p><span class="edit">01:23:</span>  Added a link.</p>
<p><span class="edit">12:34:</span>  Fixed a typo.</p>
</div>

The somewhat ugly-looking JavaScript bit associates a toggling function with an <a> element, just above the actual changelog. If the user is running a JavaScript enabled browser, the changelog is hidden by default, and its visibility can be toggled by using (clicking) the <a> element. If JavaScript is disabled, the changelog is visible by default.

From the generated code you can pretty much see what goes where. As you see, there’s no limit to what you can write between the <at>…</at> tags or the <edit>…</edit> tags – the latter is typically a description of the changes you have made, and the former the time (and date) you made them at, but you could just as well use it for a version number, for example.

Background

I’ve been using the code generated by this plugin in my blogs for years now by typing it in manually. When I saw Kafkaesque’s My Tags example I knew I could use it as a starting point for making a plugin which should ease the typing.

I have little experience in PHP and even less in hacking WP plugins, and despite that I whipped this up in a single day, so it’s more than likely that the code has bugs in it. However, the actions the plugin does aren’t that dangerous in themselves and there’s no accessing of your database at all, so at worst it should probably just fail at providing you with the new tags (possibly rendering the output of your posts a little weird). But despite this, so that you know, the plugin is provided as-is and comes with no warranty whatsoever.

Non-vital technical mumbo jumbo for the savvy and curious

The ppNumber ID for the changelog <div> element is derived from the post’s ID, so that it’ll be unique for each post. This also limits the amount of change logs for one post to one, since creating two in this way would make their names identical and thus conflicting with one another. I don’t think there’s a real need for multiple changelogs for a single post, however, so I’ve completely ignored this limitation while developing the plugin.

The pp in the ID stands for post-post, as I always position the changelogs trailing the post, but there’s no hard-coded reason why it couldn’t be the first element within a post either, so the pp is just harmless legacy.

The prompt for showing/hiding the changelog is generated using CSS rather than printing it straight inside the prompting <a> element in the code. The reason for this is that this way it is possible to change all instances of the prompt ever published simply by changing the contents of the right variable ($htp_toggler) in the code. If this variable was used to generate the link text directly (and not by manipulating a :after pseudoelement in the CSS), the change would only affect any posts made thereafter, leaving all previous instances of changelog prompts with their old link texts.

This trickery does have the unfortunate side-effect of leaving the prompt entirely unrendered in Internet Explorer (at least up to and including V6), which doesn’t support the required CSS pseudoelements. Therefore the changelog will always be visible if viewed using IE. If you need to support IE and are willing to sacrifice the quick changing of all prompts ever published, it should be easy enough to tweak the code to do so. Or better yet, make it so that IE is detected and treated separately. If and how this is possible, I have no idea and frankly, no interest either, since IE is so badly outdated anyway (at least in versions < 7).

As for the future, maybe a configuration interface for the prompt/title text would be handy, but I’m not sure if I could be bothered. As seldom as I need to do it, changing those texts directly from the code not that much harder than it would be through the dashboard.

15:11 Added activation from dashboard under Installation.