Converge Date and Time Formatting Models

This topic was moved here by Kenneth Lavrsen because several plugins refer to it and it seems updated recently and appears to be a resource to developers

Some developers (like me) forget to look for default names of variables when creating a plugin that formats date and time. And it is difficult to know what was made by others. So, this is the topic to put the default date and time formatting models (not just variables, but every thing that needs to be converged).

---

Converging Variables Names and Values

Name	strftime Equivalent	CPAN:Time::Format Equivalent	Value	Example	Comment
$seconds	%S	ss	seconds	59	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%, DateTimePlugin (aliases: $sec), SpreadSheetPlugin ( $FORMATTIME() - aliases: $second, $sec). Both zero-fill to 2 digits.
		s	seconds	1	Seconds, no leading zero.
		?s	seconds	1	Seconds, leading space if less than 10.
$minutes	%M	mm	minutes	59	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%, DateTimePlugin (aliases: $min), SpreadSheetPlugin ( $FORMATTIME() - aliases: $minute, $min). Both zero-fill to 2 digits.
		m	minutes	1	Minutes, no leading zero. Note that the Time::Format code is ambiguous; it is the same as the code for the month.
		?m	minutes	1	Minutes, leading space if less than 10. Note that the Time::Format code is ambiguous; it is the same as the code for the month.
$hours	%H	hh	hours (24-hour clock)	23	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%, DateTimePlugin (aliases: $hour), SpreadSheetPlugin ( $FORMATTIME() - aliases: $hour). Both zero-fill to 2 digits.
		h	hours	1	Hours, no leading zero.
		?h	hours	1	Hours, leading space if less than 10.
	%I	HH	hours (12-hour clock)	11
		H	hours (12-hour clock)	1	Hours, no leading zero.
		?H	hours (12-hour clock)	1	Hours, leading space if less than 10.
		am	am/pm designation (for 12-hour clock)	am	Displays "pm" if noon or later. Aliases: pm
		a.m.	am/pm designation, with periods (for 12-hour clock)	a.m.	Displays "p.m." if noon or later. Aliases: p.m.
		AM	AM/PM designation (for 12-hour clock)	AM	Displays "PM" if noon or later. Aliases: PM
		A.M.	AM/PM designation, with periods (for 12-hour clock)	A.M.	Displays "P.M." if noon or later. Aliases: P.M.
$day	%d	dd	day of month	31	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%. Zero-filled to 2 digits.
		d	day of month	1	Single digit days have no leading fill characters.
	%e	?d	day of month	1	Single digit days have a leading space (instead of zero).
$wday	%a	Day	Day of the week abbreviation (Sun, Mon, Tue, Wed, Thu, Fri, Sat)	Thu	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%, SpreadSheetPlugin
		DAY	Day of the week abbreviation, uppercase	THU
		day	Day of the week abbreviation, lowercase	thu
$weekday	%A	Weekday	Day of the week (Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday)	Thursday	Used by SpreadSheetPlugin
$lwday	%A	Weekday	Day of the week (Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday)	Thursday	Used by DateTimePlugin
		WEEKDAY	Day of the week, uppercase	THURSDAY
		weekday	Day of the week, lowercase	thursday
$month	%b		Abbreviated month name	Dec	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%, DateTimePlugin.
$month	%m		2 digit month	12	Used by SpreadSheetPlugin. Zero filled.
$mo	%m	mm	2 digit month	12	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%. Zero filled.
		m	month	1	Month, no leading zero. Note that the Time::Format code is ambiguous; it is the same as the code for the minute.
		?m	month	1	Month, leading space if less than 10. Note that the Time::Format code is ambiguous; it is the same as the code for the minute.
$year	%Y	yyyy	4 digit year	1999	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%, DateTimePlugin, SpreadSheetPlugin ( $FORMATTIME()).
$ye	%y	yy	2 digit year	99	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%, DateTimePlugin, SpreadSheetPlugin ( $FORMATTIME()).
$tz			either "GMT" (if set to gmtime), or "Local" (if set to servertime)	GMT	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%
	%Z	tz	Time zone abbreviation	GMT	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%
$iso	%Y-%m-%dT%H:%MZ		ISO format timestamp	2005-03-31T22:08Z	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%
$rcs	%Y/%m/%d %H:%M:%S		RCS format timestamp	2005/03/31 22:08:24	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%
$http			E-mail & http format timestamp	Thu, 31 Mar 2005 22:08:24 GMT	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME%
$epoch			Seconds since the epoch	1125594288	Used by %DISPLAYTIME%, %GMTIME%, %SERVERTIME% (Dakar and later)
$date			Time stamp of last topic update	31 Mar 2005 - 22:08	Used by %SEARCH% format parameter.
$isodate			Time stamp of last topic update	2005-03-31T22:08Z	Used by %SEARCH% format parameter.
...	...	...	...	...	...

---

Example: %SERVERTIME{"The current date is: $wday, $month $day, $year ($year-$mo-$day or $ye-$mo-$day). The current time is $hour:$minutes:$seconds ($tz) ($epoch seconds since the epoch)"}%

Yields: The current date is: Fri, Apr 19, 2024 (2024-04-19 or 24-04-19). The current time is 22:37:01 (Local) (1713559021 seconds since the epoch)

Converging some other need...

-- AurelioAHeckert - 31 Mar 2005

---

Discussion

Need reasons for using the ISO Date/Time format?

-- FranzJosefSilli - 01 Apr 2005

Hummm... Put it in "Converging some other need..."!
( with more words )

-- AurelioAHeckert - 01 Apr 2005

I augmented the table with the strftime() equivalent format specifier (when there is one) and where these specifiers are used. Note that there are some incompatible usages among the sources that I could find: SpreadSheetPlugin, DateTimePlugin, and the built-in functions %DISPLAYTIME%, %GMTIME%, and %SERVERTIME%.

-- DavidBright - 06 Apr 2005

Wow, this is great. Now if we could just do something about this....

-- ThomasWeigert - 06 Apr 2005

The table now contains codes from three sources: TWiki, the POSIX strftime() function, and the CPAN:Time::Format module. CPAN:Time::Format uses formatting codes that (quoting from the module documentation): "are designed to be easy to remember and use, and to take up just as manu characters as the output time value whenever possible. [...] This module is for everyone who is weary of trying to remember strftime(3) 's arcane codes...." The table isn't quite complete, as there are some strftime() and CPAN:Time::Format codes that I didn't include; also, there is no guarantee that I haven't missed codes in use within TWiki.

So, where is this going? Here are my current thoughts on getting some more complete and consistent date/time formatting codes into use in TWiki:

• I think we need to continue to support the existing codes where they are used for backward compatibility. It may be appropriate to deprecate them, however, and start prompting people to move to newer formats (should we decide that they are a good idea!).
• The strftime() format codes are potentially confusing, if not an outright parsing problem, due to the use of the % sign. If we want to use the strftime() codes, we could use a $ instead of % to avoid the potential parsing ambiguity. This would also be more consistent with the other string replacement instances in TWiki.
• I would agree that the format codes of strftime() are obtuse. The CPAN:Time::Format codes are easier to remember. My inclination is to move toward using them. However, there is one drawback: the lack of a distinguished character for disambiguating the occurence of the format code vs. plain text. For example, a format of "The current month is: Month" would yield (today, assuming this is formatted exactly on the minute): "The current april i00: April". There are at least two ways of handling this:
  • CPAN:Time::Format uses a perl-ish quoting mechanism whereby anything between \Q and \E (or the end of the format string) is protected from substitution. So, the previous example format would be written: "\QThe current month is:\E Month"
  • We could use the CPAN:Time::Format codes, but prepend them with $. This has the advantage of being consistent with existing TWiki usage, but carries the disadvantage that it defeats one of the goals of the codes, which was to take up exactly as much space as the rendered text (whenever possible).
• I would like to see this code embedded in the core so that it can be reused by core and plugins.

Other thoughts and comments?

-- DavidBright - 13 Apr 2005

DakarRelease adds the TWiki::Time module, which exports a number of time formatting methods. This module also adds $epoch (the number of seconds since 1st Jan 1970, useful for building unique URLs).

-- CrawfordCurrie - 01 Sep 2005

Yes, I've looked at that and thought of using it for CalendarPlugin. However, it doesn't allow for localization (as far as I can see), nor for times before the epoch. These are capabilities of the current plugin. However, I do think that the creation of the TWiki::Time module is a good thing. Perhaps it can be extended in the future to provide these capabilities.

-- DavidBright - 01 Sep 2005

Anything you can do to improve it would be most welcome. I started to, but was put off by the need (as I saw it) to import yet another CPAN dependency. I suppose I shouldn't have been, but it dropped below the radar after that. I'm not sure what other localisation is required. Month names, for example? Alternative calendars?

Interestingly enough I came across a real need for dates before the epoch. I wanted to build a demo of the FormQueryPlugin using my family tree as the database, and soon ran into problems.

-- CrawfordCurrie - 02 Sep 2005

http://koala.ilog.fr/twikiirc/bin/irclogger_log/twiki?date=2006-06-18,Sun&sel=36#l32

-- MartinCleaver - 18 Jun 2006

I realise this is an old topic revived by TWikiJanitor, but if anyone's going to have a look at this, it's worth reading some older topics as well, in particular SettingCorrectTimeZone and TimeZone which discuss showing local time (which can differ between users and should be configurable per-user). And if anyone is doing this, it would be great to include I18N so that the user can see a native language date/time format that is appropriate to their locale.

-- RichardDonkin - 15 Sep 2008

Also note that there are (at least?) two config parameters for setting the default format, and they use different syntaxes. E.g., to select the ISO format:

$TWiki::cfg{JSCalendarContrib}{format} = '%Y-%m-%d';
$TWiki::cfg{DefaultDateFormat} = $year-$mo-$day';

The first one (which is used by forms) doesn't appear in the configure application and so was unknown to me until mentioned by Peter in DateFormatInForms.

Even so, those parameters don't cover all date displays: e.g., see my bug report at TWikibug:Item5606, "ActionTracker: ActionSearch not using DefaultDateFormat".

Related content: UseIsoDates.

-- SeanCMorgan - 16 Sep 2008