=pod

=head1 NAME

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

=head1 DESCRIPTION

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

=head1 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;
   }

=head1 METHODS

=head2 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;   

=head2 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');   

=head2 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");
   
=head2 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");

=head2 __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 L<CHANGING THUMBNAIL BEFORE SAVING>

=cut



=head1 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;
   }

=cut





=head1 PARAMS TO CONSTRUCTOR

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


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

=head2 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

=head2 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.

=head2 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

=head1 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.

=head1 REVISION

$Revision: 1.1 $

=head1 CAVEATS & BUGS

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

Leo Charre leocharre at cpan dot org

=head1 COPYRIGHT

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

=head1 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".

=head1 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.

=cut

