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 button at left.
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.
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:
- as a key for sorting entries by-date
- as a value for deriving an entry's "posted on" date and time
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:
- use the
touchcommand or similar to modify
mtimeon the server's filesystem
- 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.
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
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:
0409150830New_Cat_Arrives.txt-- on Sept. 15 2004, 8:30am a new cat came to your house
04091516New_Couch_Arrives.txt-- by 4pm on the same day, you needed a new sofa
04091520New_Cat_Departs.txt-- by 8pm on the same day, you needed a new cat
040916New_Dog_Arrives.txt-- on Sept. 16 2004 a new dog came to your house....
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:
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 (
$ti, etc.) The plugin also makes available
$permtimez::tod, which contains time strings built out of blosxom's
$ampm variables. (For example, for a file named "
$tod variable would contain the string
$permtimez::tod variable also uses a bit of filtering:
- If Blosxom's
$minvars are both '00',
$todwill be empty
(on the assumption that no date info for time existed in the file name)
- If Blosxom's
$todwill not contain any minutes
2004123111.txtyields the string
Thus, a line in a story flavour that looks like this:
<h4>$mo $da, $yr $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
Address bug reports and comments to the Blosxom mailing list:
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