Page date & date-time formats

For some projects it seems prudent to display or otherwise utilize "the Page Date": moreover, specifically a custom, explicitly-set one (effectively equivalent to "this is hereby decreed to have really been authored/published on..") rather than one blindly parroting the OS-set file-last-modified timestamp (often de-facto equivalent to "this minor typo of no substantive import was belatedly fixed up quickly on..").

Page Dates are for instance output during processing by embedded {P|date|} P-tags; likewise the Page Date is accessed while generating XML outputs or potentially (possibly sooner-than-hoped) with a custom setup of hax.iterator and hax.snippet X-renderers (particularly in auto-generated Blok index page files).

Setting custom Page Dates: 2 ways

Option 1: content source file name

• Rename content source files: eg. from page.htm to date.page.htm (without repeating this change anywhere else such as hyperlink references pointing to it etc.) — IF this date prefix is recognizable as a date-time via a "well-known" date-time format:
• then the output file name will still continue to be page.htm (with all references to it remaining intact)
• (in fact, the file will continue to be identified throughout the entire processing pipeline simply as if its original source file name was still just page.html, as this date detection & subsequent elimination occurs immediately prior to "encountering" the content source file during the early scanning&planning stage)
• and the custom page date is active and will be accessible via {P|date|} etc.
• What's a "well-known" date-time format here?
  • Either: simply ensure YYYY-MM-DD in file name prefixes (eg. 2016-12-24.page.html),
  • or: if a different date-time format in file name prefixes is indeed called for, be sure to declare a *.haxproj |C|dtformat: directive defining it correctly under the exact custom-date-time-format name _hax_dtformat_pagefilenames

Option 2: in-page custom P-tag

The Page Date can be set for any page on-the-fly during its processing by placing anywhere in its content source file a custom P-tag (aka. "per-page variable") of the form {%P|date=2016-12-24|%} or indeed, if custom date-time formats are once again necessary for some reason, {%P|date:dtformatname=date-time-here|%}

Which is "better"?

• Option 1 will properly propagate over to <lastmod> values in generated sitemap.xml (if any), option 2 won't.
• Unless a full rebuild is forced, option 1 possibly won't get "picked up" during processing if no other change was also made to the same content source file since the last run. (That's because HaXtatic compares file-modification timestamps for a faster incremental minimal rebuild, which the OS won't typically set just due to moving-aka.-renaming a file.) Option 2 will.
• The likelihood of a project needing to adjust individual custom Page Dates all that frequently is assessed as low.
• In any event, both approaches can be used in tandem and for any given file, option 2 if present will override whatever was first set via option 1, if anything.

As already alluded to, custom date-time formats have a modicum of support in HaXtatic. In fact, most-anywhere date values are accessed, a custom format can be specified. But it first needs to be defined correctly, and that means declaring a corresponding *.haxproj |C|dtformat: directive (which in turn commands an adequate grasp of the link to parseable date-time format-strings referenced right there).

But to simply try out utilizing (not defining) "named date-time formats", anywhere these are supported the built-in date-time format name _hax_dtformat_iso8601 will perform the deed the same as any custom one. To wit, embedding {P|date:_hax_dtformat_iso8601|} right here, right now produces: 2016-12-16T00:00:00 — the conspicuous day-time a consequence of none-whatsoever having been set with the custom Page Date (using option 1) for this very pages/basics/2016-12-16.datetime.html.

To output to any target format date/time values in any input format, set up X-tag(s) invoking hax.dtFormat