LocalTime Plugin

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

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

Introduction

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

• 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. Supported date/time formatsSupported date/time formats 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.12.31.23.59.59 UTC Notes: 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.

Examples

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:

• LOCALTIMEPLUGIN_DATEFORMAT is: $longdate
• LOCALTIMEPLUGIN_LOCALE is: en_US
• LOCALTIMEPLUGIN_TIMEZONE is: UTC

You want:	You type:	You get:
Current time:	%LOCALTIME%	05 Sep 2024 - 10:20
Current time in Tokyo:	%LOCALTIME{"Asia/Tokyo"}%	05 Sep 2024 - 19:20
Current time in US Central Time Zone:	%LOCALTIME{"CST6CDT"}%	05 Sep 2024 - 05:20
Current time in Internet format:	%LOCALTIME{format="$rfc"}%	Thu, 05 Sep 2024 10:20:11 +0000
Current time in Paris, France:	%LOCALTIME{"Europe/Paris" locale="fr_FR" format="$rfc"}%	Thu, 05 Sep 2024 12:20:11 +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.

   * Set LOCALTIMEPLUGIN_DATEFORMAT = $longdate
   * Set LOCALTIMEPLUGIN_DEBUG = off
   * Set LOCALTIMEPLUGIN_LOCALE = en_US
   * Set LOCALTIMEPLUGIN_TIMEZONE = UTC

Installation

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.

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
Dependencies:	Name Version Description APR::Base64 >=0 Optional. (Required if using mod_perl2, included with mod_perl2) CPAN:APR::Base64 Date::Handler >=0 Required. CPAN:Date::Handler Date::Parse >=0 Required. 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"}