NAME

Template::Plugin::AutoDate - Enhance Template Toolkit with easy access to DateTime and DateTime::Format::Flexible

SYNOPSIS

  [% USE AutoDate %]
  
  Yesterday was [% AutoDate.now.subtract(days => 1).ymd("-") %]
  The record is from month [% AutoDate.coerce(foo.bar.datestring).month_name %]
  
  [% USE y2k= AutoDate(year => 2000, month => 1, day => 1) %]
  
  [% datestring= "2016-01-01" %]
  [% datestring.strftime("%M/%d") %]
  [% datestring.coerce_date.year %]

DESCRIPTION

This module allows you to access the full power of DateTime from within Template Toolkit. Since you don't always have date objects in the data, it also allows you to coerce arbitrary strings into DateTime using DateTime::Format::Flexible.

When you use this plugin, it installs two vmethods into your current Template context:

coerce_date

This can be called on any scalar, and it will parse the scalar with DateTime::Format::Flexible. It returns undef if the string cannot be parsed, allowing you to continue chaining calls on it and get TT's behavior for undefined values.

If called on an actual DateTime object, it returns the DateTime object un-altered.

strftime

When called on a scalar, this coerces it to a DateTime, and if defined, then calls the strftime method on it. This means you can now call strftime on any date field you like regardless of whether it's been inflated to a DateTime object by your controller.

It also provides an object (which inherits from DateTime) which you can call methods on.

METHODS

new

  [% USE AutoDate %]
  [% USE x = AutoDate(@args) %]

The first form of using the AutoDate module gives you a variable named Autodate which is a subclass of DateTime containing the value of 'now'. (Since it is a DateTime, you may modify its contents! so there is no guarantee that it still holds the value of 'now'.) The primary purpose here is to be able to call the static class methods of DateTime, which can be called on an object just as well as a package name. (Template toolkit plugins do not have the option of returning a package name, and must return a blessed object.)

In the second form, it calls the DateTime constructor with the arguments of your choice, returning a named date object.

coerce

  [% AutoDate.coerce("January 1, 2000") %]

This class method is a shortcut to "parse_datetime" in DateTime::Format::Flexible. Returns undef if the date can't be parsed.

now_local

  [% AutoDate.now_local %]

Returns DateTime->now(time_zone => "local")

now_floating

  [% AutoDate.now_floating %]

Returns DateTime->now(time_zone => "local")->set_time_zone("floating"), which results in a floating DateTime that contains local time.

THANKS

Thanks to Ellis, Partners in Management Solutions and Clippard Instrument Laboratory Inc. for supporting open source, including portions of this module.

AUTHOR

Michael Conrad <mconrad@intellitree.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by IntelliTree Solutions llc.

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