/ 
Image-Empty-0.12
River stage one • 1 direct dependent • 1 total dependent
/ Image::Empty

NAME

Image::Empty - Hassle-free empty/transparent 1x1 pixel images for tracking URLs.

VERSION

Version 0.12

SYNOPSIS

Create 1x1 pixel empty/transparent GIFs to use in tracking URLs without the hassle of actually creating and/or loading image data.

use Image::Empty;

my $cgi = CGI->new;

my $gif = Image::Empty->gif;

print $cgi->header( -type => $gif->type, -Content_length => $gif->length );

print $gif->content;

Or a bit shorter...

my $gif = Image::Empty->gif;

print $gif->render( CGI->new );

Or, if you do not want the dependency on the CGI module...

my $gif = Image::Empty->gif;

print $gif->render;

Or, if you are working with Plack...

my $gif = Image::Empty->gif;

return $gif->render( Plack::Response->new );

METHODS

Class Methods

new

Returns an instance representing an image.

my $empty = Image::Empty->new;

gif

Returns an instance representing an empty GIF for use in an HTTP response.

my $gif = Image::Empty->gif;

Instance Methods

render

The render method can be used as a shortcut to set the HTTP headers and body when responding with the empty GIF.

A string is returned.

Under a CGI environment this would generally be printed direct to STDOUT (ie, the browser).

Chaining the methods together can make the usage very compact.

use Image::Empty;

print Image::Empty->gif->render;

Remember that the render method sets the HTTP headers for you, so you do not need to worry about this yourself.

CGI

If you already have an instance of the CGI object in your code, you can pass this instance to the render method, to have it use the CGI-\header> method.

As above, a string is returned.

print Image::Empty->gif->render( CGI->new );

It is the same as doing...

my $cgi = CGI->new;

my $gif = Image::Empty->gif;

print $cgi->header( -type                => $gif->type,
                    -Content_length      => $gif->length,
                    -Content_disposition => $gif->disposition . '; filename="' . $gif->filename . '"',
                  );

print $gif->content;

Plack

If you are working with Plack, we support that too.

The render method in this scenario returns the finalized Plack::Response object, as a quick one-liner...

my $app = sub {

        return Image::Empty->gif->render( Plack::Response->new );
}

It is the same as doing...

my $app = sub {

        my $gif = Image::Empty->gif;

        my $response = Plack::Response->new;

        $response->status(200);

        $response->content_type( $gif->type );
        $response->content_length( $gif->length );

        $response->header( 'Content-disposition' => $gif->disposition . '; filename="' . $gif->filename . '"' );

        $response->body( $gif->content ); 

        return $response->finalize;
}

Attributes

type

$gif->type;

Returns the mime/type of the image for use in HTTP headers.

length

$gif->length;

Returns the content length for use in HTTP headers.

disposition

$gif->disposition;

Returns the content disposition for use in HTTP headers.

filename

$gif->filename;

Returns the content filename for use in HTTP headers.

content

$gif->content;

Returns the image data to send in the HTTP response body.

TODO

mod_perl support

PNG support

Catalyst support

AUTHOR

Rob Brown, <rob at intelcompute.com>

BUGS

Please report any bugs or feature requests to bug-image-empty at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Image-Empty. I will be notified, and then you will automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Image::Empty

You can also look for information at:

ACKNOWLEDGEMENTS

I can not actually remember where the original line came from to produce the gif content.

LICENSE AND COPYRIGHT

Copyright 2012 Rob Brown.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.