LocalTime Plugin

Provides the %LOCALTIME% macro to display a formatted date and/or time

Related topics: DATE, DISPLAYTIME{"format"}, GMTIME{"format"}, SERVERTIME{"format"}


Use the %LOCALTIME% macro anywhere in your topic to insert a formatted date and/or time for display. The macro can display either the current time or an arbitrary time of your choosing. Options to control the format, time zone, and locale to use when displaying the date/time may be specified when the macro is used or determined by plugin preference settings.


  • Syntax: %LOCALTIME% or %LOCALTIME{…}%
  • %LOCALTIME% expands to the current date and time using the default format, time zone, and locale
  • %LOCALTIME{…}% expands to a date and time allowing the default behavior to be overridden according to any parameters supplied
  • Supported parameters:
    Parameter: Description: Default
    "timezone" The name of the desired time zone such as "Asia/Tokyo" or "CST6CDT" or "UTC" "UTC"
    datetime="…" The date and time to display. This parameter is assumed to be in UTC unless it contains a time zone specifier.
    • Foswiki default:
      • 31 Dec 2001 - 23:59 GMT
    • ISO 8601:
      • 2001-12-31T23:59:59-0500
    • Internet (RFC 822/1123/2616/2822/5322):
      • Fri, 31 Dec 1999 23:59:59 -0500 (EST)
    • RCS:
      • 1999/12/31 23:59:59 UTC
    • Dotted decimal:
      • 1999. UTC

    • Dates must be between 1901-12-17 00:00:00 UTC and 2038-01-16 23:59:59 UTC
    • Text in ()'s is ignored as are the day of the week and comma, if present.
    • The time component is optional and defaults to midnight. If supplied, both hour and minute fields are required while seconds are optional.
    • Time zone specifiers are optional and default to UTC. When specified as an offset from UTC, they may be specified as ±HHMM or ±HH:MM
    • Time zones are part of the time specification, so you must specify a time in order to specify a time zone. If you desire a date to be interpreted locally, explicitly indicate midnight and the local time zone as in 2010-03-24 00:00 -0600
    • Years may be specified using 2 or 4 digits. When only 2 digits are supplied:
      • 00 to 38 are interpreted as the years 2000 to 2038
      • 39 to 60 are invalid and result in an error
      • 61 to 99 are interpreted as 1961 to 1999
    • Months may be specified as numbers (1-12), short names (Jan-Dec), or long names (January-December), English month names only
    • When both the month and day are specified as numbers, they are always interpreted assuming an American-style date format where the month comes before the day. (i.e. MM/DD/CCYY)
    • When only a month and day are specified, the year is assumed to be the current year if the date falls within the current or a prior month and the prior year if the date falls within a subsequent month.
    • When only a year is specified, January 1st is assumed.
    Current time
    format="…" The format specifier string defining how to display the date and/or time "$longdate"
    locale="…" The locale to use when displaying the date/time "en_US"

  • Deprecated parameters:
    Parameter: Description: Deprecated
    dateGMT="…" The same as datetime, use datetime instead Since 1.1
    fromtopic="…" The web.topic from which to get the value of the TIMEZONE variable, use the preference setting LOCALTIMEPLUGIN_TIMEZONE instead Since 1.1

  • Supported format tokens:
    Token: Unit: Example
    $seconds seconds 59
    $minutes minutes 59
    $hours hours 23
    $day day of month 31
    $wday day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat) Thu
    $dow day of the week (Sun = 0) 2
    $week number of week in year (ISO 8601) 34
    $month short name of month Dec
    $mo 2 digit month 12
    $year 4 digit year 1999
    $ye 2 digit year 99
    $tziso time zone as offset from UTC ±HHMM -0500
    $tz time zone identifier UTC
    $epoch seconds since 1970-01-01T00:00:00Z 1057159140
    $iso ISO format timestamp 1999-12-31T23:59:59-0500
    $rcs RCS format timestamp 1999/12/31 23:59:59
    $http RFC 2616 timestamp, same as $email Fri, 31 Dec 1999 23:59:59 EST
    $email RFC 822/1123 timestamp, same as $http Fri, 31 Dec 1999 23:59:59 EST
    $rfc RFC 2822/5322 timestamp Fri, 31 Dec 1999 23:59:59 -0500
    $longdate Site default date format followed by " - HH:MM" 31 Dec 1999 - 23:59
    • Tokens can be shortened to $ followed by 3 characters ($sec for $seconds)
    • The singular versions $second, $minute, and $hour are also accepted
    • format also accepts strftime format specifiers. However, since the percent sign is significant to Foswiki, the $percnt token must be used instead of an actual percent sign. For example: the default locale timestamp specifier %c would be specified as $percntc in the format string.


If the plugin has been successfully installed, the following examples will show several ways to manipulate the display of dates and times using the plugin.

Current default settings:

You want: You type: You get:
Current time: %LOCALTIME% 22 Jun 2024 - 03:57
Current time in Tokyo: %LOCALTIME{"Asia/Tokyo"}% 22 Jun 2024 - 12:57
Current time in US Central Time Zone: %LOCALTIME{"CST6CDT"}% 21 Jun 2024 - 22:57
Current time in Internet format: %LOCALTIME{format="$rfc"}% Sat, 22 Jun 2024 03:57:54 +0000
Current time in Paris, France: %LOCALTIME{"Europe/Paris" locale="fr_FR" format="$rfc"}% Sat, 22 Jun 2024 05:57:54 +0200
2006-04-05T15:43:50Z in Sydney, Australia (April 6, 2006, 1:43:50 AM): %LOCALTIME{"Australia/Sydney" datetime="2006-04-05T15:43:50Z"}% 06 Apr 2006 - 01:43
Sun, 28 Mar 2010 05:58:38 -0500 (CDT) in Sydney, Australia in HTTP format (Sun, 28 Mar 2010 21:58:38 EST): %LOCALTIME{"Australia/Sydney" datetime="Sun, 28 Mar 2010 05:58:38 -0500 (CDT)" format="$http"}% Sun, 28 Mar 2010 21:58:38 AEDT

Preference Settings

The default expansion of the %LOCALTIME% macro may be altered by setting Foswiki preference settings. These settings can be placed in your wiki's Site Preferences topic, your web's Web Preferences topic, your own User Preferences topic, or the topic in which the %LOCALTIME% macro is used.

Setting Description Default
DATEFORMAT The default output format specifier to use when formatting dates and/or times $longdate
DEBUG Enable/disable logging of debug traces to the Foswiki Debug Log off
LOCALE The default locale to use when formatting dates and/or times en_US
TIMEZONE The default time zone to use when interpreting the value of the datetime parameter when no time zone is provided. UTC

Note: In the table above, the "LOCALTIMEPLUGIN_" prefix has been omitted from each of the setting names for brevity. In order to make use of a setting, you must use the full name of the setting including the prefix (e.g., "LOCALTIMEPLUGIN_DATEFORMAT").

Setting Plugin Preferences

Use TML assignment statements in the body content or the topic preferences of a topic to set the value of a plugin preference. You can copy one or more of the example assignment statements below to set the desired preference value.



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

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.

Manual Installation

This plugin may be installed manually by downloading the distribution package attached to the Foswiki:Extensions.LocalTimePlugin topic.
  1. Install/upgrade any packages listed in Dependencies below
  2. Download the .zip or .tgz distribution package and place it in the root directory of your Foswiki installation.
  3. Unpack the distribution package
  4. Using the Foswiki configuration utility, configure the values described in Configuration Settings below and enable the plugin. (If using an accellerator such as mod_perl, it may be necessary to restart your server before your configuration changes will take effect.)
  5. Set any default preference values in Site, Web, and User Preference topics as desired.

Configuration Settings

LocalTimePlugin makes use of the following configuration settings which may be set to adapt the plugin to work in your particular environment.

Setting Description
{UseLocale} Enable/Disable use of locales for the site
{Site}{Locale} The default locale for the site. This setting will be ignored if {UseLocale} is disabled.
{DefaultDateFormat} The default date format for the site
{Tools}{perlCmd} The path to the Perl interpreter if it isn't on the default path
{Plugins}{LocalTimePlugin}{perlCmd} The path to the Perl interpreter if it isn't on the default path. If present, overrides the setting of {Tools}{perlCmd}

Installation Test

Current time (UTC): 22 Jun 2024 - 03:57
Current time (Asia/Tokyo): 22 Jun 2024 - 12:57
Current time (CST6CDT): Fri, 21 Jun 2024 22:57:54 -0500
2010-03-24T12:34:56Z: 2010-03-24T12:34:56+0000


File: Description:
data/System/LocalTimePlugin.txt Plugin documentation topic
data/System/VarLOCALTIME.txt Syntax summary for the LOCALTIME macro
lib/Foswiki/Plugins/LocalTimePlugin.pm Plugin module
lib/Foswiki/Plugins/LocalTimePlugin/Config.spec Config template

Plugin Info

Author: TWiki:Main.NathanOllerenshaw, Foswiki:Main.SvenDowideit, & Foswiki:Main.BryanThale
Copyright: © 2010, Foswiki Contributors
License: GPL (GNU General Public License, Version 3)
Release: 1.1.1
Version: 7117 (2010-04-07)
Home: Foswiki:Extensions.LocalTimePlugin
Support: Foswiki:Support.LocalTimePlugin
APR::Base64>=0Optional. (Required if using mod_perl2, included with mod_perl2) CPAN:APR::Base64
Date::Handler>=0Required. CPAN:Date::Handler
Date::Parse>=0Required. CPAN:Date::Parse
Change History:  
07 Apr 2010 (1.1.1): Foswikitask:Item8853 - Remove leak of server path information in error messages and require Foswiki Plugin API v2.0+
03 Apr 2010 (1.1): Foswikitask:Item8805 - Correct handling of parameters and formatting tokens
Foswikitask:Item8806 - Change default time zone to UTC, add datetime parameter, deprecate fromtopic and dateGMT parameters
Foswikitask:Item8757 - Add support for mod_perl2
Foswikitask:Item8807 - Add support for user locale
Foswikitask:Item1854 - Use published Plugin API calls
20 Feb 2009 (1.0): port to Foswiki
05 Mar 2006 (Dakar): SvenDowideit@WikiRing.com - updated to use registerHandler, added format= and dateGMT parameters
02 Jul 2003: Initial version

Related Topics: DATE, DISPLAYTIME{"format"}, GMTIME{"format"}, SERVERTIME{"format"}
Topic revision: r3 - 02 Jun 2016, MartinDiehl
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 DAMASK? Send feedback