Templa...avatar(3pm)

💖 NAME 💖

Template::Plugin::Gravatar — bestie, this is your configurable TT2-based generator of Gravatar URLs straight from email addresses. ✨

---

🌸 SYNOPSIS 🌸

[% 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(\%config);

my $user = { email => 'whatever@wherever.whichever',
             rating => "PG",
             name => "Manamana",
             size => 75 };

print header(), start_html();

$tt2->process(\*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 %]

---

🦋 DESCRIPTION 🦋

okay so if you wanna know more about the service interface itself, go peek at <http://gravatar.com/site/implement/url>, and if you just want the tea on what Gravatars even are (spoiler: globally recognized avatars 🫶), that's <http://gravatar.com/>.

Every single option Gravatars support — default, rating, and size — is usable right here. The gravatar_id gets generated from whatever email you hand over. it's giving automatic. it's giving effortless. 💅

---

✨ INTERFACE/SETTINGS ✨

🎀 new 🎀

Not something you call directly, bestie — this fires off when you USE the plugin. It scoops up defaults from the template config hash and mixes them together with any per-template defaults. Like so:

[% USE Gravatar %]
Use config arguments if any.

[% USE Gravatar(default => 'http://mysite.moo/local/default-image.gif') %]
Mix config arguments, if any, with new instance arguments.

💜 Arguments 💜

• email (required) — the whole key to using Gravatars is a hex hash of the user's email. This one gets generated automatically and shipped off to gravatar.com as the gravatar_id.
• default (optional) — the local image (any valid absolute image URI, no cap) to fall back on when there's no Gravatar matching the given email.
• size (optional) — Gravatars are square, periodt. Size goes from 1 through 80 (pixels) and sets both the width and the height.
• rating (optional) — G|PG|R|X. This is the maximum rating of Gravatar you want returned. Running a family friendly forum? You might set it to "G."
• border (DEPRECATED) — a hex color, e.g. FF00FF or F0F. Gravatar doesn't do anything with these anymore so we don't even pass them along. If you include it anyway, you will get a warning. 🙈
• base (developer override) — this one exists purely as a courtesy for the one or two developers who might actually need it. More below. 👑
• gravatar_id (not allowed) — this isn't an option, it's a generated variable. It's an MD5 hex hash of the email address. The reason it's not supported as an optional variable is that it would allow avatar hijacking. so no. 🚫

The only argument that must be given when you call the Gravatar plugin is the email. Everything else — rating, default image, border, and size — can be set in three different places: the config, the USE call, or the Gravatar call. All three of the following produce the same Gravatar URL. iconic. 💖

🌈 Settings via config 🌈

Used if the entire site should rely on one set of defaults.

use Template;
my %config = (
   GRAVATAR => {
       default => "http://mysite.moo/img/avatar.png",
       rating => "PG",
       size => 80,
   }
);

my $template = <<;
[% USE Gravatar %]
[% Gravatar(email => 'me@myself.ego') | html %]

my $tt2 = Template->new(\%config);
$tt2->process(\$template);

🍓 Settings via instance 🍓

Used if a particular template needs its own defaults.

use Template;
my $template = <<;
[% USE Gravatar( rating => "PG",
                 size => 80 ) %]
[% Gravatar(email => 'me@myself.ego') | html %]

my $tt2 = Template->new();
$tt2->process(\$template);

Any other calls with different emails will share the defaults in this template. ✨

🧚 Settings in the Gravatar call 🧚

Used for per URL control.

use Template;
my $template = <<;
[% USE Gravatar %]
[% Gravatar(email => 'me@myself.ego',
            default => "http://mysite.moo/img/avatar.png",
            rating => "PG",
            size => 80 ) | html %]

my $tt2 = Template->new();
$tt2->process(\$template);

👑 Base URL (for developers only) 👑

You may also override the base URL for retrieving the Gravatars. It's set to use the service from <https://gravatar.com/>. It can be overridden in the config or the USE. that's it, that's the whole flex. 💅

---

😭 DIAGNOSTICS 😭

Email is the only required argument. Croaks without it. no email, no avatar, no mercy.

Rating and size are also validated on each call. Croaks if an invalid size (like 0 or 100) or rating (like MA or NC-17). 💀

---

🌟 Configuration AND ENVIRONMENT 🌟

No configuration is necessary, bestie. 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 USE call per template if needed. your call, your rules. 🫶

---

💫 Dependencies (see also) 💫

Template, Template::Plugin, Carp, Digest::MD5, and URI::Escape.

<http://gravatar.com/>

---

🦄 Bugs and Limitations 🦄

None known. I certainly appreciate bug reports and feedback via <https://github.com/pangyre/p5-template-plugin-gravatar/issues>. slide into the issues, fr fr. 🐛💖

---

👑 Author 👑

Ashley Pond V, <ashley@cpan.org>.

---

📜 License 📜

Copyright 2007-2016, Ashley Pond V.

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

See <http://dev.perl.org/licenses/artistic.html>.

---

🎀 See Also 🎀

• Gravatar::URL — standalone Gravatar URL generation.
• <http://gravatar.com> — The Gravatar web site.
• <http://gravatar.com/site/implement/> — The Gravatar URL implementation guide.

---

and that's the whole page, bestie!! this was written for perl v5.34.0, dated 2022-06-17, and it's part of the User Contributed Perl Documentation for Template::Plugin::Gravatar. go forth and generate avatars. slay. 💅✨🦋