NAME

CGI::Application::Plugin::Thumbnail - have a runmode that makes thumbnails

DESCRIPTION

These methods allow your cgi app to have a runmmode that makes a thumbnail

SYNOPSIS

   use CGI::Application::Plugin::Thumbnail ':all';
   use CGI::Application::Plugin::Stream 'stream_file';


   sub thumbnail : Runmode {
           my $self = shift;

      # was an original image requested, and did it exist on disk?
      $self->get_abs_image('rel_path') or return;
         
      # get the corresponding abs pathto the thumbnail, create if not exists
      $self->abs_thumbnail or return;
      
      # stream the thumbnail image
      $self->stream_file( $self->abs_thumbnail ) 
         or warn("cant stream");
         
      return;
   }

METHODS

get_abs_image()

Optional argument is what query string param (field name) will hold the relative path to the image we want to make a thumb for. If none specified, uses 'rel_path'. Returns boolean, if it found something or not. calling this method is optional.

   $self->get_abs_image('rel_path');   
   $self->get_abs_image;   

set_abs_image()

optional argument is absolute path to original image if none provided, will resolve with get_rel_path() calling this method is optional

   $self->set_abs_image('/home/myself/images/image1.jpg');   

abs_image()

returns absolute path to image we want to make a thumb of if you set via set_abs_image() or specified query param via get_abs_image() , will mirror this. you will likely call this method in your thumbnail runmode

   $self->abs_image or warn("you did not ask for an image or that image does not exist");
   

abs_thumbnail()

returns absolute path to thumbnail if it did not exist, we would try to make it, if we could not make it, returns undef and warns this is the minimum method you need to call, to stream the image

   $self->abs_thumbnail or warn("no thumbnail was made or no image requested");

__thumbnail_style()

Does nothing. You can override this to change your thumbnail it is called when a thumbnail is creted, *after* the original is resized, but *before* it is saved. receives $thumb image magick object. You do not need to return the object. See "CHANGING THUMBNAIL BEFORE SAVING"

CHANGING THUMBNAIL BEFORE SAVING

What if you want to provide your own funky style to the thumbnail before saving??

then override __thumbnail_style()

Example:

   use CGI::Application::Plugin::Thumbnail;
   use CGI::Application::Plugin::Stream;


   sub __thumbnail_style {
      my ($self,$thumb) = @_;
      
      $thumb->Quantize( colorspace => 'gray' ); 
                $thumb->Set( compression => '8' );
      return 1;   
   }




   sub thumbnail : Runmode {
           my $self = shift;
      $self->get_abs_image('rel_path') or return;   
      
      $self->abs_thumbnail or return;  
   
      $self->stream_file( $self->abs_thumbnail ) 
         or warn("thumbnail runmode: could not stream thumb ".$self->abs_thumbnail);
      return;
   }

PARAMS TO CONSTRUCTOR

   new My::Cgiapp(
      PARAMS => {       
         thumbnail_rel_dir => '.thumbnails',                  
         thumbnail_restriction => '100x100',
      },   
   );

You do not have to provide parameters. Defaults are provided.

WHAT PICTURE?

What you tell the runmode thumbnail is not what thumbnail you want, but what original picture you want a thumbnail *of*.

The way you tell it is via the query string, if you want a thumbnail of /home/me/public_html/img/one.jpg, then the query string would read one of these:

   ?rm=thumbnail&rel_path=img/one.jpg
   ?rm=thumbnail&rel_path=/img/one.jpg

THUMBNAIL DOCROOT

You can define where the thumbnails are stored via parameter to constructor. We attempt to create if not there.

   new My::Cgiapp(
      PARAMS => { 
         thumbnail_rel_dir => '/.thumbnails' },
   );

Default is shown above.

THUMBNAIL RESTRICTION, DIMENSIONS

We define dimensions as maximum width and maximum height. If you do not define dimensions, default is 100x100. You may also defined dimmensions via the query string:

   ?rm=thumbnail&rel_path=img/one.jpg&thumbnail_restriction=100x100

We store thumbs by dimension for example these are requests and their destinations Keep in mind that if the thumbnail dimensions are larger then the image, no thumbnail is made, the original is streamed back.

   ?rm=thumbnail&rel_path=img/one.jpg
   DOCUMENT_ROOT/.thumbnails/100x100/img/one.jpg
   
   ?rm=thumbnail&rel_path=img/one.jpg&thumbnail_restriction=100x100
   DOCUMENT_ROOT/.thumbnails/100x100/img/one.jpg

   ?rm=thumbnail&rel_path=img/one.jpg&thumbnail_restriction=600x600
   DOCUMENT_ROOT/.thumbnails/600x600/img/one.jpg

CHANGES

Since version 1.03, instead of using Image::Magick::Thumbnail, we use Image::Thumbnail. You must have GD, Image::Magick, or Imager installed. Requested by Lyle.

For more changes, see the 'Changes' file included in this distribution.

REVISION

$Revision: 1.1 $

CAVEATS & BUGS

Still a work in progress. If you want any changes in this module, please contact the AUTHOR.

AUTHOR

Leo Charre leocharre at cpan dot org

COPYRIGHT

Copyright (c) 2009 Leo Charre. All rights reserved.

LICENSE

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e., under the terms of the "Artistic License" or the "GNU General Public License".

DISCLAIMER

This package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

See the "GNU General Public License" for more details.

cpanm CGI::Application::Plugin::Thumbnail

perl -MCPAN -e shell
install CGI::Application::Plugin::Thumbnail