Template::Plugin::Date
Author: Andy Wardley

TT2 Home Page

- Modules
- Template::*
- Plugin::*
- Date.pm

Click to view the menu. It's very nice. Click to hide the menu and go all widescreen!
Back

#### Template::Plugin::Datafile

Plugin to construct records from a simple data file Up

#### Template::Plugin::* Modules

Next

#### Template::Plugin::Directory

Plugin for generating directory listings

# Template::Plugin::Date

## Plugin to generate formatted date strings

# Contents

Top

# SYNOPSIS

Top

    [% USE date %]

    # use current time and default format
    [% date.format %]

    # specify time as seconds since epoch
    # or as a 'h:m:s d-m-y' or 'y-m-d h:m:s' string
    [% date.format(960973980) %]
    [% date.format('4:20:36 21/12/2000') %]
    [% date.format('2000/12/21 4:20:36') %]

    # specify format
    [% date.format(mytime, '%H:%M:%S') %]

    # specify locale
    [% date.format(date.now, '%a %d %b %y', 'en_GB') %]

    # named parameters
    [% date.format(mytime, format = '%H:%M:%S') %]
    [% date.format(locale = 'en_GB') %]
    [% date.format(time   = date.now,
                   format = '%H:%M:%S',
                   locale = 'en_GB) %]

    # specify default format to plugin
    [% USE date(format = '%H:%M:%S', locale = 'de_DE') %]

    [% date.format %]
    ...

# DESCRIPTION

Top

The `Date` plugin provides an easy way to generate formatted time and date strings by delegating to the `POSIX` `strftime()` routine.

The plugin can be loaded via the familiar USE directive.

    [% USE date %]

This creates a plugin object with the default name of '`date`'. An alternate name can be specified as such:

    [% USE myname = date %]

The plugin provides the `format()` method which accepts a time value, a format string and a locale name. All of these parameters are optional with the current system time, default format ('`%H:%M:%S %d-%b-%Y`') and current locale being used respectively, if undefined. Default values for the time, format and/or locale may be specified as named parameters in the `USE` directive.

    [% USE date(format = '%a %d-%b-%Y', locale = 'fr_FR') %]

When called without any parameters, the `format()` method returns a string representing the current system time, formatted by `strftime()` according to the default format and for the default locale (which may not be the current one, if locale is set in the `USE` directive).

    [% date.format %]

The plugin allows a time/date to be specified as seconds since the epoch, as is returned by `time()`.

    File last modified: [% date.format(filemod_time) %]

The time/date can also be specified as a string of the form `h:m:s d/m/y` or `y/m/d h:m:s`. Any of the characters : / - or space may be used to delimit fields.

    [% USE day = date(format => '%A', locale => 'en_GB') %]
    [% day.format('4:20:00 9-13-2000') %]

Output:

    Tuesday

A format string can also be passed to the `format()` method, and a locale specification may follow that.

    [% date.format(filemod, '%d-%b-%Y') %]
    [% date.format(filemod, '%d-%b-%Y', 'en_GB') %]

A fourth parameter allows you to force output in GMT, in the case of seconds-since-the-epoch input:

    [% date.format(filemod, '%d-%b-%Y', 'en_GB', 1) %]

Note that in this case, if the local time is not GMT, then also specifying '`%Z`' (time zone) in the format parameter will lead to an extremely misleading result.

Any or all of these parameters may be named. Positional parameters should always be in the order `($time, $format, $locale)`.

    [% date.format(format => '%H:%M:%S') %]
    [% date.format(time => filemod, format => '%H:%M:%S') %]
    [% date.format(mytime, format => '%H:%M:%S') %]
    [% date.format(mytime, format => '%H:%M:%S', locale => 'fr_FR') %]
    [% date.format(mytime, format => '%H:%M:%S', gmt => 1) %]
    ...etc...

The `now()` method returns the current system time in seconds since the epoch.

    [% date.format(date.now, '%A') %]

The `calc()` method can be used to create an interface to the `Date::Calc` module (if installed on your system).

    [% calc = date.calc %]
    [% calc.Monday_of_Week(22, 2001).join('/') %]

The `manip()` method can be used to create an interface to the `Date::Manip` module (if installed on your system).

    [% manip = date.manip %]
    [% manip.UnixDate("Noon Yesterday","%Y %b %d %H:%M") %]

# AUTHORS

Top

Thierry-Michel Barral wrote the original plugin.

Andy Wardley provided some minor fixups/enhancements, a test script and documentation.

Mark D. Mills cloned `Date::Manip` from the `Date::Calc` sub-plugin.

# COPYRIGHT

Top

Copyright (C) 2000-2007 Thierry-Michel Barral, Andy Wardley.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

# SEE ALSO

Top

Template::Plugin, POSIX

http://template-toolkit.org/docs/modules/Template/Plugin/Date.html