view release on metacpan or  search on metacpan

lib/CGI/Uploader/Cookbook.pod  view on Meta::CPAN

The release of this module represents a culmination of seven years of experience 
managing file uploads as a professional website developer for
Summersault, LLC (L<http://www.summersault.com/>). Over that time I noticed patterns 
that were re-usable from project to project. I went through several versions
and rewrites of modules that attempted to be 'generic' and not need
modification when the next project came along. With CGI::Uploader, I believe I
finally have a solution that I will continue to be happy with and I think others 
will be find generally useful. Enjoy!

=head2 Freedom of Choice

I endeavored to make CGI::Uploader to work within a variety of system designs.
It offers you freedom choice in the following areas:

=over

=item * Database Choice

MySQL and Postgres are supported directly. The SQL used is very simple-- support 
for additional databases should be trivial.

=item * Choice of Query Provider

The query object used may provided by C<CGI.pm>, C<CGI::Simple> or
C<Apache::Request>. Another source could be used by overriding the C<upload>
method.

=item * File Storage Schemes for Large and Small Projects

For small projects, all uploads can be stored in a single directory. For large
projects, we provide the C<md5> file scheme, which should scale well to
millions of images, without burdening any single directory with storing too
many of them.

=item * Choice of Data Display

Because the meta data is stored in a straightforward SQL database table, you
can retrieve your data and display in any number of custom ways. Several functions
are also built in to help with common display tasks. The C<build_loc()> method is
used to construct the file system or URL path of an image, given it's ID and extension.

C<fk_meta()> provides an easy way to get the meta data of an upload by relating it to a foreign
key in another table.

Finally, C<transform_meta()> is a basic function which transforms a hashref of data from the database
into a format more useful for display, producing a hash that looks like this:


 {
     my_custom_prefix_id     => 523,
     my_custom_prefix_url    => 'http://localhost/images/uploads/523.pdf',
	 my_custom_prefix_width  => 23,
	 my_custom_prefix_height => 46,
 }

=item * Image Processor

While C<CGI::Uploader> works with all types of file uploads, it contains a number
of features to help with common tasks associated with image uploads.

C<Image::Magick> is the preferred image processing module for to use when
creating the thumbnails. Support for C<GD> is in progress. C<GD> supports many
fewer formats, but also has much fewer dependencies to get installed than
C<Image::Magick> does. Another providers could be used by extending or
overriding the C<gen_thumb()> method.

=back

=head2 Just Three Essential Methods to Learn

A goal of <CGI::Uploader> is to provide a high-level interface to make managing
file uploads easy. Only three methods are needed to manage all the functions needed
to store, update, delete and view the uploads attached to some database entity. Those
methods are C<store_uploads()>, C<delete_checked_uploads()> and C<fk_meta>.

=head2 More methods when you need them 

When your needs before more complex, you can call the lower-level functions in C<CGI::Uploader> 
to meet your needs. Most functions use file names to access file uploads, so it's easy to use the
module to manipulate files from other sources than the browser upload field.

For example, the C<gen_thumb()> method is general purpose thumbnail creating routine.

=head1 Browse, Read, Edit, Add, Delete (BREAD) Example Application

The following sections will provide a walk through of a simple application
using CGI::Uploader. This is intended to provide the picture of how this module
can be used. Some details have been glossed over. For a complete, working
example application, please see the C<examples> directory of the distribution.

Before C<CGI::Uploader> can be useful, some setup needs to be done.
You need some database tables to store the information in.

=head2 Example Database 

For these examples, we'll set up some tables to manage photos of friends.
Here is the SQL to create such tables with Postgres:

	-- Note the Postgres specific syntax here
    CREATE SEQUENCE upload_id_seq;
	CREATE TABLE uploads (
		upload_id   int primary key not null 
		                default nextval('upload_id_seq'),
		mime_type   character varying(64),
		extension   character varying(8), -- file extension
		width       integer,                 
		height      integer,
		gen_from_id integer
	);

 CREATE SEQUENCE friend_id_seq;
 CREATE TABLE address_book (
    friend_id       int primary key NOT NULL DEFAULT nextval('friend_id_seq'),
    full_name       varchar(64),

    -- these two reference uploads('upload_id'),
    photo_id            int,  
    photo_thumbnail_id  int 
 );

(I<MySQL> is also supported. Check in the distribution for sample SQL 'Create'
scripts for both I<MySQL> and I<Postgresql> databases).

=head2 Object Creation