Each Textpattern CMS article has one, two or three timestamps. Every article has, by definition, a publication timestamp when it becomes visible. If that article is subsequently modified, an additional timestamp is enabled which is updated to indicate the most recent edit or modification. Finally, if the article is set to expire at a given point, then an expiry date is also applied. If the article is never modified, and is not set to expire, only the publication timestamp is set.
The timestamps can be retrieved from a given article with the use of three discrete Textpattern tags:
- <txp:posted />
- <txp:modified />
- <txp:expires />
These three tags behave in a very similar way, hence my combining them into a single blog post here. Each tag outputs a timestamp according to the posted, modified or expiry date. Each tag has a few simple attributes that can fine-tune its output. The attributes are, perhaps unsurprisingly, identical across the three tags:
- class=”class name” (default: unset)
- format=”format string” (default: unset, takes admin preferences setting)
- gmt=”boolean” (default: 0 (local time, per admin preferences setting)
- lang=”ISO language code” (default: unset, takes admin preferences setting)
- wraptag=”tag” (default: unset)
There’s a lot of scope for customising the output with these tags. The `class` attribute follows other tags with the same and is used to assign a CSS class to the container tag, which is set by `wraptag`. The `gmt` attribute is, as the name implies, a boolean check to tell Textpattern to display the article time in Greenwich Mean Time (UTC, if you prefer – they are the same thing). The fun stuff really starts with `format` and `lang`.
If no `format` attribute value is specified, the timestamp is formatted according to the (limited) selection in the admin-side preferences. That is to say, your choice there will dictate how timestamps are displayed throughout the site. Should you choose to change the format of the date in the admin-side, the changes will happen across the site; no code needs to be updated. That said, the options for timestamps are limited to common choices, and you may wish to fine-tune the output beyond the scope of a one-size-fits-all approach in the admin-side.
Timestamps can be formatted with the following values:
- strftime() values
You do know all those by heart, right? No, neither do I.
I tend to use strftime() values because, frankly, the documentation is good and I’ve been doing it long enough that I can create the format I want. Using the `since` value shows an approximate figure of how long ago the post was posted/modified or when it expired. Anecdotally, I can tell you that strftime() and `since` are the most commonly used options for front-side dates. Some Textpattern folks like to use the others and live dangerously (or to show off at dinner parties, I am told…), but you can get to know the formatting for each method and use the best fit for you.
All three are simple tags to use. Look:
<txp:posted format="since" />
…would result in `3 days ago`, assuming the post was made about three days ago. This value will increase as time passes. Taking the strftime() values approach:
<txp:modifed format="%b %d, %Y" />
…would show the absolute date that the post was most recently modified:
July 14, 2010
And finally, using the wraptag approach you can change how a timestamp is formatted with CSS classes:
<p>Posted: <txp:posted format="%Y" wraptag="span" class="year" /> <txp:posted format="%B" wraptag="span" class="month" /> <txp:posted format="%e" wraptag="span" class="day" /></p>
…this would output something like the following on the front-side:
<p>Posted: <span class="year">2010</span> <span class="month">Jul</span> <span class="day">14</span></p>
Huge amounts of fun can be had with these tags, it’s just a matter of trying things out to see what works for you.