Tags

DateTimePlugin

Display date and time with formatting options, relative date parameters and localized dates

This plugin is an extension of the macro GMTIME{"format"} (that only allows to show the current date date and time).
DateTimePlugin lets you show any date and time before or after 'now', and it will return any part of a date such as the month name.

With DateTimePlugin you can write:
In five days will be: %DATETIME{incdays="5"}% and will have a always coherent phrase.

Syntax Rules

Use %DATETIME{}% to show the current date and time in default date format (as set in configure).

For more options use: %DATETIME{"format" <optional parameters>}%

Parameters

Parameter Description Example
"..." or format="..." Format of date string; see GMTIME{"format"} for formatting variables. Without setting the date explicitly, uses the current time and date. %DATETIME{"$wday"}%
language="..." Optionally localize the output. Supported languages are: English, Portuguese, Dutch. Overrides the LANGUAGE preference (which is currently set to: en). %DATETIME{"$wday" language="pt"}%
date="..." Before formatting, set the date in one of the following formats:

Default Foswiki format
    31 Dec 2001 - 23:59

Foswiki format without time (defaults to 00:00)
    31 Dec 2001

Date seperated by '/', '.' or '-', time with '.' or ':'
Date and time separated by ' ', '.' and/or '-'
    2001/12/31 23:59:59
    2001.12.31.23.59.59
    2001/12/31 23:59
    2001.12.31.23.59
    2001-12-31 23:59
    2001-12-31 - 23:59

ISO format
    2001-12-31T23:59:59
ISO dates may have a timezone specifier, either Z or a signed difference in hh:mm format. For example:
    2001-12-31T23:59:59+01:00
    2001-12-31T23:59Z
The local timezone will be assumed.

Seconds since 1970 (UNIX time)
    1218930300

Note: will not handle dates before 1970!
%DATETIME{date="2001/12/31"}%
incdays="..." Increase the date by any number of days (may be a negative number) %DATETIME{date="31 Dec 2001" incdays="1"}%
inchours="..." Increase the date by any number of hours (may be a negative number) %DATETIME{date="31 Dec 2001 - 07:00" format="$hours" inchours="-1"}%
incminutes="..." Increase the date by any number of minutes (may be a negative number) %DATETIME{date="31 Dec 2001" format="$minutes" incminutes="15"}%
incseconds="..." Increase the date by any number of seconds (may be a negative number) %DATETIME{date="31 Dec 2001" format="$seconds" incseconds="20"}%
timezoneoffset="..." Increase the date by any number of hours (may be a negative number). Overrides the default value in configure. %DATETIME{date="31 Dec 2001" format="$seconds" timezoneoffset="20"}%

Formatting parameters

See GMTIME{"format"} for general date and time formatting parameters to pass to format. DateTimePlugin supports the following additional parameters:

Parameter Description Example
$month_long The long name of the month. July
$wday_long The long name of the day of the week. Wednesday

Localized formatting parameters

Either set preference LANGUAGE to your language of choice, or use the DATETIME parameter language.

Parameter Description Example
$month with language="..." The localized short name of the month. Out
$month_long with language="..." The localized long name of the month. Outubro
$wday with language="..." The localized short name of the day of the week. Seg
$wday_long with language="..." The localized long name of the day of the week. Segunda-feira

Deprecated formatting parameters

These parameters will continue to work, but we advice to use the parameters above.

Deprecated parameter Explanation Suggestion
$i_month The localized short name of the month. Use $month with a language="..." setting.
$i_lmonth The localized long name of the month. Use $month_long with a language="..." setting.
$lmonth The English long name of the month. Use $month_long with a language="en" setting.
$i_wday The localized short name of the day of the week. Use $wday with a language="..." setting.
$i_lwday The localized long name of the day of the week. Use $wday_long with a language="..." setting.
$lwday The English long name of the day of the week. Use $wday_long with a language="en" setting.
$sec Undocumented notation for seconds. Use $seconds.
$min Undocumented notation for minutes. Use $minutes.
$hour Undocumented notation for hours. Use $hours.
$day2 Undocumented notation for day. Use $day.

Overview of all formatting variables

$seconds 06
$minutes 25
$hours 04
$day 19
$wday Ter
$wday_long Terça-feira
$dow 2
$week 12
$month Mar
$month_long Março
$mo 03
$year 2024
$ye 24
$tz GMT
$iso 2024-03-19T04:25:06Z
$rcs 2024/03/19 04:25:06
$http Tue, 19 Mar 2024 04:25:06 GMT
$epoch 1710822306

Examples

Yesterday was %DATETIME{"$day $month $year" incdays="-1"}%

results in:

Yesterday was Monday, 18 Mar 2024


One week from now is %DATETIME{"$wday, $day $month $year" incdays="7"}%

results in:

One week from now is Tue, 26 Mar 2024


To create time-based topics:

%DATETIME{
"Create TODO topic for tomorrow: [[ToDo$year$mo$day]] ($lwday, $day $lmonth)"
incdays="1"
}%

results in:

Create TODO topic for tomorrow: ToDo20240320 (Wednesday, 20 March)

Limitations

Due to date handling in Perl, DateTimePlugin cannot reliably handle dates earlier than 1970.

Plugin Settings

Localization

Localized dates are read from configure - see settings with {DateTimePlugin}.

Debugging

Visit configure and set {DateTimePlugin}{Debug} to 1.

Plugin Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Plugin Author: TWiki:Main.AurelioAHeckert (2004), Foswiki:Main.ArthurClemens (2008, 2009)
Version: 4740
Release: 1.2
Change History:  
31 Aug 2009 1.2 Arthur Clemens
New features:
• Added format parameter $epoch to pass seconds since 1970 (UNIX time).
• Added parameter language.
• Added parameter timezoneoffset.
• Changed the 'localized' formatting parameters; now use language="..." to localize output.
• Made configuration of localized strings in configure more coherent.
• Completed unit test coverage.
Bug fixes:
• Fixed 'bug' in timezone offset that intentionally only uses the configure setting {TimezoneOffset} with current dates. To use a timezone offset with a set date, add parameter timezoneoffset.
11 Mar 2009 1.1 Foswiki release
28 Feb 2008 1.0 Arthur Clemens: Major rewrite to make this plugin compatible with (and use from) TWiki::Time. Localized language strings are now read from configure.
27 Jul 2004 0.90 Aurelio A Heckert: First release
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
License: GPL (GNU General Public License)
Plugin Home: http://foswiki.org/Extensions/DateTimePlugin
Support: http://foswiki.org/Support/DateTimePlugin
Topic revision: r1 - 01 Sep 2009, UnknownUser
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding CLASSE Wiki? Send feedback