NP_Revision 0.5 0.6

A complete revisioning system for Nucleus CMS stories

Thanks to my job I regularly come into contact with code management systems like CVS and Subversion. These tools basically offer a repository where different revisions of source code files are stored. Once a change is made to any of those source code files that particular file is send back to the repository, but unlike a regular file system, every other older version of that particular file is still available and thanks to a build in diff algorithm it is easy to see what changes were made to a particular file over time.

Last week I suddenly wondered if it would be possible to use a similar system for my weblog. Normally, everytime I make a change, the older version will be lost forever. What I wanted is that if I make a change to a story a new revision of that story will be created and that revision will be the default revision that is shown to visitors, but all the other revisions must still be available. I want to be able to quickly and easily see the changes between revisions and I want to be able to revert back to an older revision in case I do not like one of the changes I have made.

The breakthrough was the discovery of a diff algorithm in PHP. The algorithm was created for phpWiki and adapted by the people at MediaWiki. It was perfect for the job I wanted it to perform, although it was an important part, it was only a small part of the plugin I now was going to write. That same day I started writing the code for the implementation of the actual revision system. The code is now ready, is called NP_Revision and will be released as a beta version.

What does it do exactly?

Every time you make a change to a story it will store that change and assign a revision number to that change. For example, the first draft you create for a story will have the revision number of 0.1, the next time you make a change the number will be increased to 0.2, then to 0.3 and so on. If you publish your draft the revision number will be increased to 1.0 and once again, every additional change will increase the revision number. The beauty of this system is that every older revision will still be available.

Take for example the story PearPC needs help on my weblog. It has to following URL: http://www.rakaz.nl/nucleus/item/60. This URL will take you to the last revision – revision 1.2 – of that story. This means there are at least two other revisions available, revision 1.1 and 1.0. To access these revisions you can simply append something to the URL. If you have FancyURLs enabled, like I have, you can simply append /revision/1.1:

http://www.rakaz.nl/nucleus/item/60/revision/1.1

If you are using regular URLs you must append a parameter called rev:

http://www.rakaz.nl/nucleus/index.php?itemid=60&rev=1.1

If you visit one of the URLs above you will notice a red warning message at the top. It basically tells the visitor that the page they are seeing is not the latest revision. This warning is shown by default on all older revisions, but it can also be customized or even disabled in the admin settings of the plugin.

The warning message also contains a link to a diff between the revision you are currently seeing and the latest revision. If you look at the diff you will quickly see the changes that were made between these revisions.

Revision administration

The only place in the Admin area where you will notice the Revision plugin is on the Edit Item page. Every time you make a change to an item you can leave a little comment in the ‘Comment for next change’ field, describing the change you are making. This comment is shown together with the diffs and in the revision overview on the Edit Item page. Leaving comments is not a requirement, but it will help you keep track of the changes you made.

Just below the comment field is an overview of all revisions that are available. For each revision you can see the revision number, the date on which that revision was created and the comment you left for that change. It is also possible to revert back to an older revision or see a diff between two revisions.

If you revert back to an older revision, you are basically creating a new revision which will change back all options and fields to the state they had in the earlier revision. All changes will be reverted, including the title, the body text, the extended text, but also whether or not comments are allowed. If the revision you are reverting to is still a draft, the story will become a draft again. This means that the story will not be visible to visitors anymore.

Templates and Skins

This plugin offers several variables you can use in your templates and skins.

<%Revision(current)%>
Insert the revision number of the revision that is shown at this moment. This is the last revision by default, but if the user is viewing an older revision that revision number is shown.

<%Revision(currentdate)%>