.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Template::Plugin::Gravatar 3pm"
.TH Template::Plugin::Gravatar 3pm "2021-01-07" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "Name"
.IX Header "Name"
Template::Plugin::Gravatar \- Configurable TT2\-based generation of Gravatar URLs from email addresses.
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 5
\&  [% USE Gravatar %]
\&  [% FOR user IN user_list %]
\&   <img src="[% Gravatar( email => user.email ) | html %]"
\&     alt="[% user.name | html %]" />
\&  [% END %]
\&
\&  # OR a mini CGI example
\&  use strict;
\&  use CGI qw( header start_html end_html );
\&  use Template;
\&
\&  my %config = ( # ... your other config stuff
\&                GRAVATAR => { default => "http://myhost.moo/local/image.png",
\&                              size => 80,
\&                              rating => "R" },
\&                );
\&  # note the "default" must be an absolute URI to work correctly
\&
\&  my $tt2 = Template\->new(\e%config);
\&
\&  my $user = { email => \*(Aqwhatever@wherever.whichever\*(Aq,
\&               rating => "PG",
\&               name => "Manamana",
\&               size => 75 };
\&
\&  print header(), start_html();
\&
\&  $tt2\->process(\e*DATA, { user => $user })
\&      or warn $Template::ERROR;
\&
\&  print end_html();
\&
\&  _\|_DATA_\|_
\&  [% USE Gravatar %]
\&  [% FILTER html %]
\&   <img src="[% Gravatar( user ) | html %]"
\&     alt="[% user.name | html %]" />
\&  [% END %]
.Ve
.SH "Description"
.IX Header "Description"
Please see <http://gravatar.com/site/implement/url> for more on the
service interface and <http://gravatar.com/> for information
about Gravatars (globally recognized avatars) in general.
.PP
All of the options supported in Gravatars—default, rating, and
size—can be used here. The \f(CW\*(C`gravatar_id\*(C'\fR is generated from a given
email.
.SH "Interface/Settings"
.IX Header "Interface/Settings"
.SS "new"
.IX Subsection "new"
Not called directly. Called when you \f(CW\*(C`USE\*(C'\fR the plugin. Takes defaults
from the template config hash and mixes them with any per template
defaults. E.g.–
.PP
.Vb 2
\&  [% USE Gravatar %]
\&  Use config arguments if any.
\&
\&  [% USE Gravatar(default => \*(Aqhttp://mysite.moo/local/default\-image.gif\*(Aq) %]
\&  Mix config arguments, if any, with new instance arguments.
.Ve
.SS "Arguments"
.IX Subsection "Arguments"
.IP "email (required)" 4
.IX Item "email (required)"
The key to using Gravatars is a hex hash of the user's email. This is
generated automatically and sent to gravatar.com as the \f(CW\*(C`gravatar_id\*(C'\fR.
.IP "default (optional)" 4
.IX Item "default (optional)"
The local (any valid absolute image \s-1URI\s0) image to use if there is no
Gravatar corresponding to the given email.
.IP "size (optional)" 4
.IX Item "size (optional)"
Gravatars are square. Size is 1 through 80 (pixels) and sets the width
and the height.
.IP "rating (optional)" 4
.IX Item "rating (optional)"
G|PG|R|X. The \fBmaximum\fR rating of Gravatar you wish returned. If you
have a family friendly forum, for example, you might set it to \*(L"G.\*(R"
.IP "border (\s-1DEPRECATED\s0)" 4
.IX Item "border (DEPRECATED)"
A hex color, e.g. \s-1FF00FF\s0 or F0F. Gravatar no longer does anything with
these so we don't even pass them along. If included they will give a
warning.
.IP "base (developer override)" 4
.IX Item "base (developer override)"
This is provided as a courtesy for the one or two developers who might
need it. More below.
.IP "gravatar_id (not allowed)" 4
.IX Item "gravatar_id (not allowed)"
This is \fBnot\fR an option but a generated variable. It is an \s-1MD5\s0 hex
hash of the email address. The reason is it not supported as an
optional variable is it would allow avatar hijacking.
.PP
The only argument that must be given when you call the \f(CW\*(C`Gravatar\*(C'\fR
plugin is the email. Everything else—rating, default image,
border, and size—can be set in three different places: the
config, the \f(CW\*(C`USE\*(C'\fR call, or the \f(CW\*(C`Gravatar\*(C'\fR call. All three of the
following produce the same Gravatar \s-1URL.\s0
.SS "Settings via config"
.IX Subsection "Settings via config"
Used if the entire \*(L"site\*(R" should rely on one set of defaults.
.PP
.Vb 8
\&  use Template;
\&  my %config = (
\&     GRAVATAR => {
\&         default => "http://mysite.moo/img/avatar.png",
\&         rating => "PG",
\&         size => 80,
\&     }
\&  );
\&
\&  my $template = <<;
\&  [% USE Gravatar %]
\&  [% Gravatar(email => \*(Aqme@myself.ego\*(Aq) | html %]
\&  
\&  my $tt2 = Template\->new(\e%config);
\&  $tt2\->process(\e$template);
.Ve
.SS "Settings via instance"
.IX Subsection "Settings via instance"
Used if a particular template needs its own defaults.
.PP
.Vb 5
\&  use Template;
\&  my $template = <<;
\&  [% USE Gravatar( rating => "PG",
\&                   size => 80 ) %]
\&  [% Gravatar(email => \*(Aqme@myself.ego\*(Aq) | html %]
\&  
\&  my $tt2 = Template\->new();
\&  $tt2\->process(\e$template);
.Ve
.PP
Any other calls with different emails will share the defaults in this
template.
.SS "Settings in the Gravatar call"
.IX Subsection "Settings in the Gravatar call"
Used for per \s-1URL\s0 control.
.PP
.Vb 7
\&  use Template;
\&  my $template = <<;
\&  [% USE Gravatar %]
\&  [% Gravatar(email => \*(Aqme@myself.ego\*(Aq,
\&              default => "http://mysite.moo/img/avatar.png",
\&              rating => "PG",
\&              size => 80 ) | html %]
\&  
\&  my $tt2 = Template\->new();
\&  $tt2\->process(\e$template);
.Ve
.SS "Base \s-1URL\s0 (for developers only)"
.IX Subsection "Base URL (for developers only)"
You may also override the base \s-1URL\s0 for retrieving the Gravatars. It's
set to use the service from <https://gravatar.com/>. It can be
overridden in the config or the \f(CW\*(C`USE\*(C'\fR.
.SH "Diagnostics"
.IX Header "Diagnostics"
Email is the only required argument. Croaks without it.
.PP
Rating and size are also validated on each call. Croaks if an
invalid size (like 0 or 100) or rating (like \s-1MA\s0 or \s-1NC\-17\s0).
.SH "Configuration AND ENVIRONMENT"
.IX Header "Configuration AND ENVIRONMENT"
No configuration is necessary. You may use the configuration hash of
your new template to pass default information like the default image
location for those without Gravatars. You can also set it in the \f(CW\*(C`USE\*(C'\fR
call per template if needed.
.SH "Dependencies (see also)"
.IX Header "Dependencies (see also)"
Template, Template::Plugin, Carp, Digest::MD5, and
URI::Escape.
.PP
<http://gravatar.com/>
.SH "Bugs and Limitations"
.IX Header "Bugs and Limitations"
None known. I certainly appreciate bug reports and feedback via
<https://github.com/pangyre/p5\-template\-plugin\-gravatar/issues>.
.SH "Author"
.IX Header "Author"
Ashley Pond V, \f(CW\*(C`<ashley@cpan.org>\*(C'\fR.
.SH "License"
.IX Header "License"
Copyright 2007\-2016, Ashley Pond V.
.PP
This program is free software; you can redistribute it and modify it
under the same terms as Perl itself.
.PP
See <http://dev.perl.org/licenses/artistic.html>.
.SH "See Also"
.IX Header "See Also"
Gravatar::URL \- standalone Gravatar \s-1URL\s0 generation.
.PP
<http://gravatar.com> \- The Gravatar web site.
.PP
<http://gravatar.com/site/implement/> \- The Gravatar \s-1URL\s0 implementation guide.