Here's the complete text for the download you were just reading about. For those that hate to read documentation, here's a link to DOWNLOAD permtimez 0.5.

To return to the Downloads page, click the Downloads button at left.

permtimez 0.5

The permtimez plugin uses date information conveyed in entry file names (as in 20041231NewYearEve.txt) to provide blosxom with stable time values for sorting and dating your blog entries. At the "cost" of including a minimum of 6 digits in your entry file names, permtimez allows you to edit, re-upload, or otherwise change your entry files' modification times without changing their sort order or "posted on" dates.

If you're already using date-info in your entry file names, chances are good that you won't have to make any changes to your files—permtimez can be configured to read any one of eight different date-info formats. In fact, selecting a date-info format is all the configuration there is—select a format, drop permtimez into your plugins folder, and enjoy stable entry dates and predictable sorts.

If you're not already using date-info in your entry file names, I strongly advise that you test the permtimez plugin before making changes to your entry files. Adding date info to your entry file names may change their mtimes, which affects your entire blog; there's no undo. You should only take the step of adding date info to your entry file names after you know that permtimez will run on your server(s); download a simple compatibility test.


Testing permtimez Before Installing
I strongly advise that you test permtimez before you make changes to your entry file names. (Since if you add date-info to your entry file names and then find that permtimez doesn't work on your system, all your entry files will have changed mtimes, which will change their sort order and posting dates.)

This testing procedure involves no changes to your blosxom setup, and should take just a few minutes of your time:

  • If you're using a sorting plugin, remove it from your plugins folder, or disable it by appending a - to its name. Also, remove or disable any entry-date "fixer" plugin you're using, such as entries_cache or entries_index_tagged.
  • Download this zipped file: permtimez_compatibility.zip
    The file will un-zip into a folder named permtimez_compatibility. Inside the folder you'll find four files: two plugins and two test entry files. With the folder open, proceed:
  • The two plugins — permtimez and 000aaa — are already configured for the test; upload them straight into the plugins folder of the blosxom installation you're testing. Don't open or edit these files before uploading.
  • The two test entry files — 040915First.aaa and 990602Second.aaa — should be uploaded to any directory where you normally keep entry files, following this procedure: upload the file 040915First.aaa first; then wait a couple of minutes; then upload the file 990602Second.aaa second. Don't open or edit these files before uploading.
  • Now, call your blog using the simplest possible URL; e.g
    www.example.com/cgi-bin/blosxom.cgi as opposed to
    www.example.com/cgi-bin/blosxom.cgi/category/filename.flavour

If permtimez is compatible with your system, your blog page should contain two posts. One will be dated Sept 15, 2004; the other will be dated June 2, 1999. (And, of course, the 2004 post should appear before the 1999 post.)

If permtimez is incompatible with your system, instead of a blog page you'll see some sort of server error page (500 error).

If the test seems to fail, please try it once more after disabling all your plugins. (More to the point, the 000aaa plugin must run before any other plugins, or all bets are off.)

If permtimez is incompatible with your system, or if its results seem wrong (out of order, wrong dates), please let me know:

What the test does:
The 000aaa plugin sets blosxom's file_extension property to 'aaa'; this has the effect of ignoring all your current entries and reading only the two test files you uploaded. The permtimez plugin is pre-configured to the date-info format of the test files. Nothing in your blosxom setup is changed; when testing is done, you can delete the 000aaa plugin and the two test files.

What's Up with Testing?
Q: Do you recommend testing because this plugin is half-baked or "dangerous"?
A: No, not at all; the only work this plugin actually does is to loop through blosxom's list of files, performing some regular expression matching and calling localtime(); none of that should be "risky" in the slightest. However, one v0.4 user reported that the plugin wouldn't run on his system; he didn't find this out until after adding date-info to all his entry file names. The problem was resolved by accommodating the Perl 5.004 on his server, but it was a twitchy couple of days. I recommend testing in order to prevent this from happening to anyone else.

With luck, this was just a silly problem that's been fully resolved. This whole "testing" box will go away, and the world will continue to run on greased grooves.

The Schtick

A big chunk of blosxom's zen is its use of the filesystem-as-database. It's easy, automatic, and comes standard with every computer; there's nothing extra to install or learn.

A key piece of filesystem functionality that blosxom bums a ride from is the "modification time" (mtime) of files. Every time a file is created, or its contents change, the filesystem makes a note of the time and attaches that info to the file. Blosxom uses entry file mtimes for two purposes:

Using mtime to derive date and time-of-day (TOD) is wonderfully convenient; users don't have to type any extra bits into entry files, and perl is adept at turning mtimes into human-readable dates and times.

There's a problem with all this automatic convenience, however: mtime is volatile. When you edit an entry file, or move files onto a new server, or restore files from a backup, or even just post a file a couple of days late, the mtime values no longer reflect the dates you intended the posts to have. Your blog doesn't sort the way you want, and your posts show up with the wrong dates. Not good.

There have typically been two solutions for these filesystem-induced problems:

  1. use the touch command or similar to modify mtime on the server's filesystem
  2. use one of several plugins that read date info from within entry files, calculate mtimes from that info, and then overwrite the "real" mtimes in blosxom's list of entry files.

Both methods can be effective, but they also have drawbacks that can make them less-than-ideal. Using the touch command requires access, geekly know-how, and time; while the tag-reading plugins impose a special requirement on entry file format, and potentially add needless cycles to the server's work load or demand special attention from you every time a new post is added....

The permtimez plugin provides a third solution. It uses date information in entry file names to provide mtime info that blosxom can use for sorting and dating entries. You can edit posts, re-upload your site, post a file a day late... and to blosxom's mind, nothing has changed. Your blog will always sort the way you want, and your posts will always display the "correct" dates.

Lest this sound too easy, please be aware that permtimez does impose a "cost" on you: you have to add the date info to your entry files names. For extensive pre-existing sites, this can take some time — but p'bly no more time than touching all your files, or adding a special date-tag to every entry. And with permtimez, this "cost" only needs to be paid once; there's no ongoing maintenance or extra effort in the future.

Using permtimez

The first step to using permtimez is making sure there's date info in your entry file names. For permtimez to makes sense of this info, it must be consistently formatted across all your entry files. You can pretty much use any format you like, as long as you use the same format.

These are the date info formats that permtimez recognizes:
YYYYMMDD -- ex: 20040620 as in 2004, June 20
YYYYDDMM -- ex: 20042006 as in 2004, 20 June
MMDDYYYY -- ex: 06202004 as in June 20, 2004
DDMMYYYY -- ex: 20062004 as in 20 June, 2004
YYMMDD   -- ex: 040620 as in '04, June 20
YYDDMM   -- ex: 042006 as in '04, 20 June
MMDDYY   -- ex: 062004 as in June 20, '04
DDMMYY   -- ex: 200604 as in 20 June, '04

Date info must appear at the start of the file name. If you enter silly date info (say, 20041515, you'll get silly results. If you forget to add date info, permtimez will just skip your file, and blosxom will use that file's "real" mtime.

File names can still be descriptive; they just have to start with date info. So it's perfectly O.K. to have file names like 040620Short_Vacation_Starts.txt and 040621Short_Vacation_Ends.txt.

Date info can also include time-of-day (TOD) info if you wish. TOD info is always optional; you're never required to include it. There's only one format for time info: HHMMSS, but the amount of info you use is totally up to you. That is, if you just want to specify hours, then just add two digits; to specify hours and minutes, add four digits. Here are some examples using TOD:

Configuration

Before dropping permtimez into your plugins folder, you must tell it which format you're using for date info in your entry file names. You can key it in, or just copy from here:

YYYYMMDD
YYYYDDMM
MMDDYYYY
DDMMYYYY
YYMMDD
YYDDMM
MMDDYY
DDMMYY

Now just copy or place permtimez into your plugins folder, and blog on!

Flavour variable $permtimez::tod

As always, entry file date info is available to flavour files through the normal blosxom variables ($yr, $mo, $ti, etc.) The plugin also makes available $permtimez::tod, which contains time strings built out of blosxom's $hr12, $min, and $ampm variables. (For example, for a file named "200412311159.txt" the $tod variable would contain the string 11:59pm.)

However, the $permtimez::tod variable also uses a bit of filtering:

Thus, a line in a story flavour that looks like this:
<h4>$mo $da, $yr&nbsp;&nbsp;$permtimez::tod</h4>
will seamlessly display a time of day if one seems warranted.

(In order to keep this fast, the actual file name is never checked. When you add it all up, it means that $permtimez::tod can never contain the time 12am.

Bugs

Address bug reports and comments to the Blosxom mailing list:
http://www.yahoogroups.com/group/blosxom

License & Copyright

this Blosxom Plug-in
Copyright 2004, Stu MacKenzie (S2_Mac, HyperSTUff)

Version: v0.5 2004-11-20
License: MIT/Public Domain
See plugin file for complete details and restrictions

 

DOWNLOAD permtimez 0.5