Templat...n::Image(3)

💅 Template::Plugin::Image — the manual, but make it make sense

okay so bestie, this is the page for Template::Plugin::Image from the User Contributed Perl Documentation. It's giving "let me peek inside your image files and tell you how big they are" and honestly? iconic. 🖼️✨

---

🌸 SYNOPSIS

[% USE Image(filename) %]
[% Image.width %]
[% Image.height %]
[% Image.size.join(', ') %]
[% Image.attr %]
[% Image.tag %]

that's the whole vibe in six lines. slay. 💅

---

🎀 DESCRIPTION

So this plugin is basically a lil bridge to the Image::Info or Image::Size modules, and its whole job is figuring out how big your image files are. no cap.

You can name the plugin either "Image" or "image" — lowercase, uppercase, we don't gatekeep. The plugin object gets created with whatever name you picked, so it matches. And the image filename? You pass it as a positional or named argument. your choice, main character. 🫶

[% # all these are valid, take your pick %]
[% USE Image('foo.gif') %]
[% USE image('bar.gif') %]
[% USE Image 'ping.gif' %]
[% USE image(name='baz.gif') %]
[% USE Image name='pong.gif' %]

There's also a root parameter, which tells the plugin where the image file actually lives:

[% USE Image(root='/path/to/root', name='images/home.png') %]
# image path: /path/to/root/images/home.png
# img src: images/home.png

✨ but here's the thing: if the image path and the image url don't line up (which, same, honestly), just hand over the file name directly:

[% USE Image(file='/path/to/home.png', name='/images/home.png') %]

The alt parameter? That's for giving your image an alternate name, used when you're building an XHTML element (peep the tag() method further down 👀).

[% USE Image('home.png', alt="Home") %]

You can also give your "Image" plugin object a whole other name. multiple images, multiple names, no chaos:

[% USE img1 = image 'foo.gif' %]
[% USE img2 = image 'bar.gif' %]

the methods, bestie 💜

The name method hands you back the image file name:

[% img1.name %]     # foo.gif

The width and height methods do exactly what they say on the tin — width and height of the image. The size method gives you a reference to a 2 element list with width and height in it:

[% USE image 'foo.gif' %]
width: [% image.width %]
height: [% image.height %]
size: [% image.size.join(', ') %]

The modtime method returns the file's modification time — perfect for pairing with the Date plugin, like:

[% USE image 'foo.gif' %]
[% USE date %]
[% date.format(image.modtime, "%B, %e %Y") %]

The attr method gives you the height and width as HTML/XML attributes:

[% USE image 'foo.gif' %]
[% image.attr %]

Typical output is giving:

width="60" height="20"

The tag method returns a whole complete XHTML tag referencing the image:

[% USE image 'foo.gif' %]
[% image.tag %]

Typical output:

<img src="foo.gif" width="60" height="20" alt="" />

And you can throw in any extra attributes you want added to that XHTML tag:

[% USE image 'foo.gif' %]
[% image.tag(class="logo" alt="Logo") %]

Typical output:

<img src="foo.gif" width="60" height="20" alt="Logo" class="logo" />

⚠️ heads up: the alt attribute is mandatory in a strict XHTML img element (even when it's empty!), so it's always added even if you never explicitly give it a value. You can set it as an argument to the tag method like in the last example, or as an argument like this:

[% USE image('foo.gif', alt='Logo') %]

---

😭 CATCHING ERRORS

If the image file can't be found, all those methods above will throw an "Image" error. so rude, but okay. You can wrap your calls in a TRY...CATCH block to catch whatever goes wrong:

[% TRY;
     image.width;
   CATCH;
     error;      # print error
   END
%]

---

🦋 USING Image::Info

At run time, the plugin tries to load Image::Info before Image::Size — it's giving favorites, but fair. If Image::Info is found, you get some extra methods on top of size, width, height, attr, and tag. These extra methods are named after the elements that Image::Info pulls from the image itself, so what you get depends on the image type (check Image::Info for the deets). These ones are always there:

🌈 file_media_type

The MIME type that fits the file format. The value is a string like "image/png" or "image/jpeg".

🌈 file_ext

The suggested file name extension for that file format. The value is a 3 letter, lowercase string like "png" or "jpg".

🌈 color_type

A short string describing what kind of values the pixels encode. It's one of these:

Gray
GrayA
RGB
RGBA
CMYK
YCbCr
CIELab

These names can also get an "Indexed-" prefix when the image is made of indexes into a palette. Of all of them, only "Indexed-RGB" is likely to actually show up.

(it's similar to the TIFF field PhotometricInterpretation, but that name was found to be too long, so they used the PNG inspired term instead. we love a rebrand 💅)

🌈 resolution

This field's value usually gives the physical size of the image on screen or paper. When there's no unit specifier, then this field is denoting the squareness of the pixels in the image.

The syntax is:

<res> <unit>
<xres> "/" <yres> <unit>
<xres> "/" <yres>

The <res>, <xres> and <yres> fields are numbers. The <unit> is a string like dpi, dpm or dpcm (meaning "dots per inch/cm/meter).

🌈 SamplesPerPixel

Says how many channels there are in the image. For some image formats this number might be higher than the number implied by color_type. foreshadowing ✨

🌈 BitsPerSample

Says how many bits are used to encode each of the samples. The value is a reference to an array of numbers, and the number of elements in that array should match SamplesPerPixel.

🌈 Comment

Textual comments found in the file. If there are multiple comments found, the value is a reference to an array.

🌈 Interlace

If the image is interlaced, this returns the interlace type.

🌈 Compression

Returns the name of the compression algorithm that's used.

🌈 Gamma

A number indicating the gamma curve of the image (e.g. 2.2).

---

👑 AUTHOR

Andy Wardley <abw@wardley.org> <http://wardley.org/> — thank you king 🫶

---

🍓 COPYRIGHT

Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved.

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

---

🌸 SEE ALSO

Template::Plugin, Image::Info

---

that's the whole page, no crumbs. this was perl v5.42.0, dated 2024-06-23 — go forth and measure your images, bestie 💖✨🎀