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, 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 empty string 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.

AUTHOR

Michael Conrad <mconrad@intellitree.com>

CONTRIBUTOR

Michael Conrad <mike@nrdvana.net>

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.