DateTimePlugin < TWiki

Tags: view all tags
---+!! <nop>DateTimePlugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/DateTimePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/DateTimePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky>
<div class="twikiTocFloat">
%TOC{title="Page contents"}%
</div>
</sticky>
%SHORTDESCRIPTION%

---++ Introduction

This plugin is an extension of the TWiki variable [[%SYSTEMWEB%.VarGMTIME2][GMTIME{"format"}]] (that only allows to show the current date and time). %BR%
!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: %BR%
In five days will be: =%<nop>DATETIME{incdays="5"}%= and will have a always coherent phrase.

Date and time are displayed in %IF{"{DisplayTimeValues} = 'gmtime'" then="GMT"
else="the local time zone"}% because of the way ={DisplayTimeValues}= configuration parameter is set. There is no way to specify a time zone in which date and time are displayed.

---++ Syntax Rules

Use =%<nop>DATETIME{}%= to show the current date and time in default date format (as set in [[%SCRIPTURL{configure}%][configure]]).

For more options use: =%<nop>DATETIME{"format" &lt;optional parameters&gt;}%=

---+++ Parameters

| *Parameter* | *Description* | *Example* |
| ="..."= or =format="..."= | Format of date string; see [[%SYSTEMWEB%.VarGMTIME2][GMTIME{"format"}]] for formatting variables | =%<nop>DATETIME{"$wday"}%= |
| =date="..."= | Any date in one of the following formats: %BR%%BR% \
Default TWiki format %BR% \
&nbsp;&nbsp;&nbsp; =31 Dec 2001 - 23:59= %BR%%BR% \
TWiki format without time (defaults to =00:00=) %BR% \
&nbsp;&nbsp;&nbsp; =31 Dec 2001= %BR%%BR% \
Date seperated by '/', '.' or '-', time with '.' or ':' %BR% \
Date and time separated by ' ', '.' and/or '-' %BR% \
&nbsp;&nbsp;&nbsp; =2001/12/31 23:59:59= %BR% \
&nbsp;&nbsp;&nbsp; =2001.12.31.23.59.59= %BR% \
&nbsp;&nbsp;&nbsp; =2001/12/31 23:59= %BR% \
&nbsp;&nbsp;&nbsp; =2001.12.31.23.59= %BR% \
&nbsp;&nbsp;&nbsp; =2001-12-31 23:59= %BR% \
&nbsp;&nbsp;&nbsp; =2001-12-31 - 23:59= %BR%%BR% \
ISO format %BR% \
&nbsp;&nbsp;&nbsp; =2001-12-31T23:59:59= %BR% \
ISO dates may have a timezone specifier, either Z or a signed difference in hh:mm format. For example: %BR% \
&nbsp;&nbsp;&nbsp; =2001-12-31T23:59:59+01:00= %BR% \
&nbsp;&nbsp;&nbsp; =2001-12-31T23:59Z= %BR%%BR% \
In formats other than ISO, GMT time zone is always assumed. %IF{"{DisplayTimeValues} != 'gmtime'" then="This is incosistent with the fact that date and time are displayed in the local time zone."}%%BR%%BR% \
Timestamp (seconds from the epoch) %BR% \
&nbsp;&nbsp;&nbsp; =1009843199= %BR%%BR% \
*Note: will not handle dates before 1970!* | =%<nop>DATETIME{date="2001/12/31"}%= |
| =incdays="..."= | Increase the date by any number of days (may be a negative number) | =%<nop>DATETIME{date="31 Dec 2001" incdays="1"}%= |
| =inchours="..."= | Increase the date by any number of hours (may be a negative number) | =%<nop>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) | =%<nop>DATETIME{date="31 Dec 2001" format="$minutes" incminutes="15"}%= |
| =incseconds="..."= | Increase the date by any number of seconds (may be a negative number) | =%<nop>DATETIME{date="31 Dec 2001" format="$seconds" incseconds="20"}%= |
| =timezone="..."= | Specify the time zone in which the result is displayed. Please note that this parameter affects only display. It doesn't affect how the date parameter value is evaluated. %RED% *As of July 2015, this papameter requires TWiki core downloaded from http://svn.twiki.org to work* %ENDCOLOR% | =%<nop>DATETIME{"$hour:$min $tz" timezone="America/New_York"}%= |

---+++ Formatting parameters

See [[%SYSTEMWEB%.VarGMTIME2][GMTIME{"format"}]] for general date and time formatting parameters to pass to =format=. !DateTimePlugin supports the following additional paramters:

| *Parameter* | *Description* | *Example* |
| =$i_month= | The localized short name of the month. | =Ago= |
| =$lmonth= | The English long name of the month. | =July= |
| =$i_lmonth= | The localized long name of the month. | =Julho= |
| =$i_wday= | The summarized internationalized name of the day of the week. | =Qua= |
| =$lwday= | The English long name of the day of the week. | =Wednesday= |
| =$i_lwday= | The localized long name of the day of the week. | =Quarta-feira= |

---+++ Overview of all formatting variables

%DATETIME{format="
| =$<nop>seconds= | $seconds |
| =$<nop>minutes= | $minutes |
| =$<nop>hours= | $hours |
| =$<nop>day= | $day |
| =$<nop>wday= | $wday |
| =$<nop>i_wday= | $i_wday |
| =$<nop>i_lwday= | $i_lwday |
| =$<nop>dow= | $dow |
| =$<nop>week= | $week |
| =$<nop>month= | $month |
| =$<nop>mo= | $mo |
| =$<nop>i_month= | $i_month |
| =$<nop>i_lmonth= | $i_lmonth |
| =$<nop>year= | $year |
| =$<nop>ye= | $ye |
| =$<nop>tz= | $tz |
| =$<nop>iso= | $iso |
| =$<nop>rcs= | $rcs |
| =$<nop>http= | $http |
| =$<nop>epoch= | $epoch |
"}%

---++ Examples

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

results in:

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

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

results in:

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

---
To create time-based topics:

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

results in:

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

---++ Limitations

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

---+++ Localization

Localized dates are read from [[%SCRIPTURL{configure}%][configure]].

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on your browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running. 
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * Download the ZIP file from the Plugin web (see below)
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
     | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
     | ==data/TWiki/VarDATETIME.txt== | Variable documentation topic |
   * Visit =configure= in your TWiki installation, and enable the plugin in the {Plugins} section.

   * Debugging: Visit [[%SCRIPTURL{configure}%][configure]] and set ={DateTimePlugin}{Debug}= to 1.

%ENDTWISTY%

#PluginInfo
---++ Plugin Info

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Display date and time with formatting options and localized dates

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.AurelioAHeckert, TWiki:Main.ArthurClemens |
|  Copyright: | &copy; 2004 TWiki:Main.AurelioAHeckert %BR% &copy; 2008 TWiki:Main.ArthurClemens %BR% &copy; 2008-2016 TWiki:Main.PeterThoeny %BR%  &copy; 2004-2016 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2016-04-25 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}% "
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2016-04-25: | TWikibug:Item7703: Small tweak in configure setting to avoid horizontal scrolling that affects all other extensions; switch to GPL v3 from v2 -- TWiki:Main.PeterThoeny |
|  2015-07-14: | TWikibug:Item7677: DATETIME{...} now takes the timezone parameter -- TWiki:Main.HideyoImazu |
|  2015-05-18: | TWikibug:Item7655: DATETIME{$epoch} does not take inc* into account -- TWiki:Main.HideyoImazu |
|  2013-03-27: | TWikibug:Item7473: DATETIME{...} showing time in the local time zone regardless of {DisplayTimeValues} -- TWiki:Main.HideyoImazu |
|  2013-04-22: | TWikibug:Item7123: Add twisty to installation instructions and history -- TWiki:Main.PeterThoeny |
|  2013-04-22: | TWikibug:Item7151: Change CALC to CALCULATE in DATETIME related links -- TWiki:Main.PeterThoeny |
|  2012-11-12: | TWikibug:Item7020: Categorize TWiki Variable -- TWiki:Main.PeterThoeny |
|  2012-10-05: | TWikibug:Item6947: Support unix timestamp for the input -- TWiki:Main.MahiroAndo |
|  2011-05-14: | TWikibug:Item6701: Small fix in Config.spec -- TWiki:Main.PeterThoeny |
|  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 |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  TWiki:Plugins.Benchmark: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ VarDATETIME, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.UserDocumentationCategory
Topic revision: r1 - 2016-04-26 - TWikiContributor
Webs
TWiki
Account
- Log In
- Register User
Edit
Attach
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.DateTimePlugin.