Name

time — display formatted date, similar to strftime POSIX function

ATTRIBUTES

Attribute Pos. Req. Default Description
locale Yes Format date and time according to the named locale (assuming that the locale is available on your system).
tz Specify the timezone. Note that the first alphabetical string is the zone name to be used when not under daylight-savings time. The following digit is the number of hours displacement from GMT, and the second alphabetical string is the zone name when in daylight savings time. (This may not work on all operating systems.)
time Specify the date/time manually, instead of letting Interchange call Perl time() function.
sortable 0 Display date in "sortable" format? Sortable format is predefined format= string that displays the date in " YYYY/ MM/ DD
adjust For the display purpose, adjust the time for the specified value. In most cases, the value will represent hours. If the value ends in 0 and contains three or more digits, then it is assumed to be in timezone format. The offset can also be specified using interval format. See the section called “EXAMPLES” for clarification.
hours 0 Force the adjust= argument to always represent hours.
format | fmt POSIX strftime format specifier; see time glossary entry.
gmt 0 Display GMT (UTC) time?
zerofix 0 Strip leading zeros from numbers?
interpolate     0 interpolate input?
reparse     1 interpolate output?
hide     0 Hide the tag return value?

DESCRIPTION

The tag displays date and time values, formatted similar to the strftime(3) function. The date can be specified with the time= parameter and adjusted with the adjust= parameter. The current date and time is the assumed default.

See time glossary entry for a list and description of format specifiers.

BEHAVIOR

This tag does not appear to be affected by, or affect, the rest of Interchange.

EXAMPLES

Example: Basic example

[time]%am %B %d, %Y[/time]

This tag would return a date such as Sunday, September 4, 2005.


Example: Specifying adjust= attribute in number of hours

[time adjust="-3"]%c[/time]

With a base date of Mon 01 Jan 2001 11:29:03 AM EST, this tag would display Mon 01 Jan 2001 08:29:03 AM EST.


Example: ISO 8601 date suitable for MySQL datetime and PostgreSQL timestamp fields

[time]%Y-%m-%d %H:%M:%S[/time]

Example: Convert epoch value to ISO 8601 date

Time values as seconds since epoch can be converted by passing the value as time attribute.

[time time="1261306319"]%Y-%m-%d %H:%M:%S[/time]

Example: Specifying adjust= attribute in timezone format

[time]%c[/time]
[time adjust="-330"]%c[/time]
[time adjust="-300"]%c[/time]

With a base date of Mon 01 Jan 2001 11:29:03 AM EST, this tag would display second date offset by 3 hours and 30 minutes, and the third date offset by 3 hours.

Mon 01 Jan 2001 11:29:03 AM EST
Mon 01 Jan 2001 07:59:03 AM EST
Mon 01 Jan 2001 08:29:03 AM EST

Example: Specifying adjust= attribute in interval format

[time adjust="2 days"]%c[/time]

Example: Displaying locale-specific date

[time locale=en_US]%B %d, %Y[/time]
[time locale=fr_FR]%B %d, %Y[/time]

would result in

January 01, 2001
janvier 01, 2001

Example: Specifying tz= attribute

[time tz=GMT0]
[time tz=CST6CDT]
[time tz=PST8PDT]

would result in

Mon 01 Jan 2001 04:43:02 PM GMT
Mon 01 Jan 2001 10:43:02 AM CST
Mon 01 Jan 2001 08:43:02 AM PST

NOTES

In all adjust= manipulations, the offset will just be applied at the end (the timezone will not be changed for the invocation of time function). This means you shouldn't use any format that uses timezone information. For the timezone to enter calculations, either use tz=, or manage the calculation yourself.

The timezone can be set globally for the Interchange installation by defining the TZ environment variable and restarting Interchange.

AVAILABILITY

time is available in Interchange versions:

4.6.0-5.7.0 (git-head)

SOURCE

Interchange 5.7.0:

Source: code/SystemTag/time.coretag
Lines: 15


# Copyright 2002-2007 Interchange Development Group and others
# 
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.  See the LICENSE file for details.
# 
# $Id: time.coretag,v 1.4 2007-03-30 23:40:49 pajamian Exp $

UserTag time                Order        locale
UserTag time                addAttr
UserTag time                hasEndTag
UserTag time                PosNumber    1
UserTag time                Version      $Revision: 1.4 $
UserTag time                MapRoutine   Vend::Interpolate::mvtime

Source: lib/Vend/Interpolate.pm
Lines: 2113

sub mvtime {
my ($locale, $opt, $fmt) = @_;
my $current;

if($locale) {
  $current = POSIX::setlocale(&POSIX::LC_TIME);
  POSIX::setlocale(&POSIX::LC_TIME, $locale);
}

local($ENV{TZ}) = $opt->{tz} if $opt->{tz};

my $now = $opt->{time} || time();
$fmt = '%Y%m%d' if $opt->{sortable};

if($opt->{adjust} || $opt->{hours}) {
  my $adjust = $opt->{adjust};
  if ($opt->{hours}) {
    $adjust ||= $opt->{hours};
    $adjust .= ' hours';
  }

  elsif ($adjust !~ /[A-Za-z]/) {
    $adjust =~ s/(?<=\d)(\d[05])// and $adjust += $1 / 60;
    $adjust .= ' hours';
  }

  $now = adjust_time($adjust, $now, $opt->{compensate_dst});
}

$fmt ||= $opt->{format} || $opt->{fmt} || '%c';
  my $out = $opt->{gmt} ? ( POSIX::strftime($fmt, gmtime($now)    ))
                        : ( POSIX::strftime($fmt, localtime($now) ));
$out =~ s/\b0(\d)\b/$1/g if $opt->{zerofix};
POSIX::setlocale(&POSIX::LC_TIME, $current) if defined $current;
return $out;
}

AUTHORS

Interchange Development Group

SEE ALSO

date(7ic), strftime(7ic)

DocBook! Interchange!