.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CGI::Uploader 3pm" .TH CGI::Uploader 3pm "2011-02-02" "perl v5.18.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CGI::Uploader \- Manage CGI uploads using SQL database .SH "Synopsis" .IX Header "Synopsis" .Vb 1 \& use CGI::Uploader::Transform::ImageMagick \*(Aqgen_thumb\*(Aq; \& \& my $u = CGI::Uploader\->new( \& spec => { \& # Upload one image named from the form field \*(Aqimg\*(Aq \& # and create one thumbnail for it. \& img_1 => { \& gen_files => { \& \*(Aqimg_1_thmb_1\*(Aq => gen_thumb({ w => 100, h => 100 }), \& } \& }, \& }, \& \& updir_url => \*(Aqhttp://localhost/uploads\*(Aq, \& updir_path => \*(Aq/home/user/www/uploads\*(Aq, \& temp_dir => \*(Aq/home/user/www/uploads\*(Aq, \& \& dbh => $dbh, \& query => $q, # defaults to CGI\->new(), \& ); \& \& # ... now do something with $u .Ve .SH "Description" .IX Header "Description" This module is designed to help with the task of managing files uploaded through a \s-1CGI\s0 application. The files are stored on the file system, and the file attributes stored in a \s-1SQL\s0 database. .SH "Introduction and Recipes" .IX Header "Introduction and Recipes" The CGI::Uploader::Cookbook provides a slightly more in depth introduction and recipes for a basic \s-1BREAD\s0 web application. (Browse, Read, Edit, Add, Delete). .SH "Constructor" .IX Header "Constructor" .SS "\fInew()\fP" .IX Subsection "new()" .Vb 10 \& my $u = CGI::Uploader\->new( \& spec => { \& # The first image has 2 different sized thumbnails \& img_1 => { \& gen_files => { \& \*(Aqimg_1_thmb_1\*(Aq => gen_thumb({ w => 100, h => 100 }), \& \*(Aqimg_1_thmb_2\*(Aq => gen_thumb({ w => 50, h => 50 }), \& } \& }, \& }, \& \& # Just upload it \& img_2 => {}, \& # Downsize the large image to these maximum dimensions if it\*(Aqs larger \& img_3 => { \& # Besides generating dependent files \& # We can also transform the file itself \& # Here, we shrink the image to be wider than 380 \& transform_method => \e&gen_thumb, \& # demostrating the old\-style param passing \& params => [{ w => 380 }], \& } \& }, \& \& updir_url => \*(Aqhttp://localhost/uploads\*(Aq, \& updir_path => \*(Aq/home/user/www/uploads\*(Aq, \& \& dbh => $dbh, \& query => $q, # defaults to CGI\->new(), \& \& up_table => \*(Aquploads\*(Aq, # defaults to "uploads" \& up_seq => \*(Aqupload_id_seq\*(Aq, # Required for Postgres \& ); .Ve .IP "spec [required]" 4 .IX Item "spec [required]" The specification described the examples above. The keys correspond to form field names for upload fields. .Sp The values are hash references. The simplest case is an empty hash reference, which means to just upload the image and apply no transformations. .Sp ##### .Sp Each key in the hash is the corresponds to a file upload field. The values are hash references used provide options for how to transform the file, and possibly generate additional files based on it. .Sp Valid keys here are: .IP "transform_method" 4 .IX Item "transform_method" This is a subroutine reference. This routine can be used to transform the upload before it is stored. The first argument given to the routine will be the CGI::Uploader object. The second will be a full path to a file name containing the upload. .Sp Additional arguments can be passed to the subroutine using \f(CW\*(C`params\*(C'\fR, as in the example above. But don't do that, it's ugly. If you need a custom transform method, write a little closure for it like this: .Sp .Vb 7 \& sub my_transformer { \& my %args = @_; \& return sub { \& my ($self, $file) = shift; \& # do something with $file and %args here... \& return $path_to_new_file_i_made; \& } .Ve .Sp Then in the spec you can put: .Sp .Vb 1 \& transform_method => my_tranformer(%args), .Ve .Sp It must return a full path to a transformed file. .Sp } .IP "params (\s-1DEPRECATED\s0)" 4 .IX Item "params (DEPRECATED)" \&\fB\s-1NOTE:\s0\fR Using a closure based interface provides a cleaner alternative to using params. See CGI::Uploader::Transform::ImageMagick for an example. .Sp Used to pass additional arguments to \f(CW\*(C`transform_method\*(C'\fR. See above. .Sp Each method used may have additional documentation about parameters that can be passed to it. .IP "gen_files" 4 .IX Item "gen_files" A hash reference to describe files generated from a particular upload. The keys are unique identifiers for the generated files. The values are code references (usually closures) that prove a transformation for the file. See CGI::Uploader::Transform::ImageMagick for an an example. .Sp An older interface for \f(CW\*(C`gen_files\*(C'\fR is deprecated. For that, the values are hashrefs, containing keys named \f(CW\*(C`transform_method\*(C'\fR and \f(CW\*(C`params\*(C'\fR, which work as described above to generate a transformed version of the file. .IP "updir_url [required]" 4 .IX Item "updir_url [required]" \&\s-1URL\s0 to upload storage directory. Should not include a trailing slash. .IP "updir_path [required]" 4 .IX Item "updir_path [required]" File system path to upload storage directory. Should not include a trailing slash. .IP "temp_dir" 4 .IX Item "temp_dir" Optional file system path to temporary directory. Default is File::Spec\->\fItmpdir()\fR. This temporary directory will also be used by gen_files during image transforms. .IP "dbh [required]" 4 .IX Item "dbh [required]" \&\s-1DBI\s0 database handle. Required. .IP "query" 4 .IX Item "query" A \s-1CGI\s0.pm\-compatible object, used for the \f(CW\*(C`param\*(C'\fR and \f(CW\*(C`upload\*(C'\fR functions. Defaults to \s-1CGI\-\s0>\fInew()\fR if omitted. .IP "up_table" 4 .IX Item "up_table" Name of the \s-1SQL\s0 table where uploads are stored. See example syntax above or one of the creation scripts included in the distribution. Defaults to \*(L"uploads\*(R" if omitted. .IP "up_table_map" 4 .IX Item "up_table_map" A hash reference which defines a mapping between the column names used in your \&\s-1SQL\s0 table, and those that CGI::Uploader uses. The keys are the CGI::Uploader default names. Values are the names that are actually used in your table. .Sp This is not required. It simply allows you to use custom column names. .Sp .Vb 7 \& upload_id => \*(Aqupload_id\*(Aq, \& mime_type => \*(Aqmime_type\*(Aq, \& extension => \*(Aqextension\*(Aq, \& width => \*(Aqwidth\*(Aq, \& height => \*(Aqheight\*(Aq, \& gen_from_id => \*(Aqgen_from_id\*(Aq, \& file_name => \*(Aqfile_name\*(Aq, .Ve .Sp You may also define additional column names with a value of 'undef'. This feature is only useful if you override the \f(CW\*(C`extract_meta()\*(C'\fR method or pass in \&\f(CW$shared_meta\fR to \fIstore_uploads()\fR. Values for these additional columns will then be stored by \f(CW\*(C`store_meta()\*(C'\fR and retrieved with \f(CW\*(C`fk_meta()\*(C'\fR. .IP "up_seq" 4 .IX Item "up_seq" For Postgres only, the name of a sequence used to generate the upload_ids. Defaults to \f(CW\*(C`upload_id_seq\*(C'\fR if omitted. .IP "file_scheme" 4 .IX Item "file_scheme" .Vb 1 \& file_scheme => \*(Aqmd5\*(Aq, .Ve .Sp \&\f(CW\*(C`file_scheme\*(C'\fR controls how file files are stored on the file system. The default is \f(CW\*(C`simple\*(C'\fR, which stores all the files in the same directory with names like \&\f(CW\*(C`123.jpg\*(C'\fR. Depending on your environment, this may be sufficient to store 10,000 or more files. .Sp As an alternative, you can specify \f(CW\*(C`md5\*(C'\fR, which will create three levels of directories based on the first three letters of the \s-1ID\s0's md5 sum. The result may look like this: .Sp .Vb 1 \& 2/0/2/123.jpg .Ve .Sp This should scale well to millions of files. If you want even more control, consider overriding the \f(CW\*(C`build_loc()\*(C'\fR method, which is used to return the stored file path. .Sp Note that specifying the file storage scheme for the file system is not related to the \f(CW\*(C`file_name\*(C'\fR stored in the database, which is always the original uploaded file name. .SH "Basic Methods" .IX Header "Basic Methods" These basic methods are all you need to know to make effective use of this module. .SS "\fIstore_uploads()\fP" .IX Subsection "store_uploads()" .Vb 1 \& my $entity = $u\->store_uploads($form_data); .Ve .PP Stores uploaded files based on the definition given in \f(CW\*(C`spec\*(C'\fR. .PP Specifically, it does the following: .IP "o" 4 .IX Item "o" possibily transforms the original file according to \f(CW\*(C`transform_method\*(C'\fR .IP "o" 4 .IX Item "o" possibly generates additional files based on those uploaded, according to \&\f(CW\*(C`gen_files\*(C'\fR. .IP "o" 4 .IX Item "o" stores all the files on the file system .IP "o" 4 .IX Item "o" inserts upload details into the database, including upload_id, mime_type and extension. The columns 'width' and 'height' will be populated if that meta data is available. .PP As input, a hash reference of form data is expected. The simplest way to get this is like this: .PP .Vb 3 \& use CGI; \& my $q = new CGI; \& $form_data = $q\->Vars; .Ve .PP However, I recommend that you validate your data with a module with Data::FormValidator, and use a hash reference of validated data, instead of directly using the \s-1CGI\s0 form data. .PP CGI::Uploader is designed to handle uploads that are included as a part of an add/edit form for an entity stored in a database. So, \f(CW$form_data\fR is expected to contain additional fields for this entity as well as the file upload fields. .PP For this reason, the \f(CW\*(C`store_uploads\*(C'\fR method returns a hash reference of the valid data with some transformations. File upload fields will be removed from the hash, and corresponding \*(L"_id\*(R" fields will be added. .PP So for a file upload field named 'img_field', the 'img_field' key will be removed from the hash and 'img_field_id' will be added, with the appropriate upload \s-1ID\s0 as the value. .PP store_uploads takes an optional second argument as well: .PP .Vb 1 \& my $entity = $u\->store_uploads($form_data,$shared_meta); .Ve .PP This is a hash refeference of additional meta data that you want to store for all of the images you storing. For example, you may wish to store an \*(L"uploaded_user_id\*(R". .PP The keys should be column names that exist in your \f(CW\*(C`uploads\*(C'\fR table. The values should be appropriate data for the column. Only the key names defined by the \&\f(CW\*(C`up_table_map\*(C'\fR in \f(CW\*(C`new()\*(C'\fR will be used. Other values in the hash will be ignored. .SS "\fIdelete_checked_uploads()\fP" .IX Subsection "delete_checked_uploads()" .Vb 1 \& my @fk_col_names = $u\->delete_checked_uploads; .Ve .PP This method deletes all uploads and any generated files based on form input. Both files and meta data are removed. .PP It looks through all the field names defined in \f(CW\*(C`spec\*(C'\fR. For an upload named \&\fIimg_1\fR, a field named \fIimg_1_delete\fR is checked to see if it has a true value. .PP A list of the field names is returned, prepended with '_id', such as: .PP .Vb 1 \& img_1_id .Ve .PP The expectation is that you have foreign keys with these names defined in another table. Having the names is format allows you to easily set these fields to \s-1NULL\s0 in a database update: .PP .Vb 1 \& map { $entity\->{$_} = undef } @fk_names; .Ve .PP \&\fB\s-1NOTE:\s0\fR This method can not currently be used to delete a generated file by itself. .SS "\fIfk_meta()\fP" .IX Subsection "fk_meta()" .Vb 4 \& my $href = $u\->fk_meta( \& table => $table, \& where => \e%where, \& prefixes => \e@prefixes, .Ve .PP Returns a hash reference of information about the file, useful for passing to a templating system. Here's an example of what the contents of \f(CW$href\fR might look like: .PP .Vb 4 \& { \& file_1_id => 523, \& file_1_url => \*(Aqhttp://localhost/images/uploads/523.pdf\*(Aq, \& } .Ve .PP If the files happen to be images and have their width and height defined in the database row, template variables will be made for these as well. .PP This is going to fetch the file information from the upload table for using the row where news.item_id = 23 \s-1AND\s0 news.file_1_id = uploads.upload_id. .PP This is going to fetch the file information from the upload table for using the row where news.item_id = 23 \s-1AND\s0 news.file_1_id = uploads.upload_id. .PP The \f(CW%where\fR hash mentioned here is a SQL::Abstract where clause. The complete \s-1SQL\s0 that used to fetch the data will be built like this: .PP .Vb 3 \& SELECT upload_id as id,width,height,extension \& FROM uploads, $table \& WHERE (upload_id = ${prefix}_id AND (%where_clause_expanded here)); .Ve .SH "Class Methods" .IX Header "Class Methods" These are some handy class methods that you can use without the need to first create an object using \f(CW\*(C`new()\*(C'\fR. .SS "\fIupload()\fP" .IX Subsection "upload()" .Vb 3 \& # As a class method \& ($tmp_filename,$uploaded_mt,$file_name) = \& CGI::Uplooader\->upload(\*(Aqfile_field\*(Aq,$q); \& \& # As an object method \& ($tmp_filename,$uploaded_mt,$file_name) = \& $u\->upload(\*(Aqfile_field\*(Aq); .Ve .PP The function is responsible for actually uploading the file. .PP It can be called as a class method or an object method. As a class method, it's necessary to provide a query object as the second argument. As an object method, the query object given the constructor is used. .PP Input: \- file field name .PP Output: \- temporary file name \- Uploaded \s-1MIME\s0 Type \- Name of uploaded file (The value of the file form field) .PP Currently \s-1CGI\s0.pm, CGI::Simple and Apache::Request and are supported. .SH "Upload Methods" .IX Header "Upload Methods" These methods are high level methods to manage the file and meta data parts of an upload, as well its generated files. If you are doing something more complex or customized you may want to call or overide one of the below methods. .SS "\fIstore_upload()\fP" .IX Subsection "store_upload()" .Vb 8 \& my %entity_upload_extra = $u\->store_upload( \& file_field => $file_field, \& src_file => $tmp_filename, \& uploaded_mt => $uploaded_mt, \& file_name => $file_name, \& shared_meta => $shared_meta, # optional \& id_to_update => $id_to_update, # optional \& ); .Ve .PP Does all the processing for a single upload, after it has been uploaded to a temp file already. .PP It returns a hash of key/value pairs as described in \*(L"\fIstore_uploads()\fR\*(R". .SS "\fIcreate_store_gen_files()\fP" .IX Subsection "create_store_gen_files()" .Vb 6 \& my %gen_file_ids = $u\->create_store_gen_files( \& file_field => $file_field, \& meta => $meta_href, \& src_file => $tmp_filename, \& gen_from_id => $gen_from_id, \& ); .Ve .PP This method is responsible for creating and storing any needed thumbnails. .PP Input: \- file_field: file field name \- meta: a hash ref of meta data, as \f(CW\*(C`extract_meta\*(C'\fR would produce \- src_file: path to temporary file of the file upload \- gen_from_id: \s-1ID\s0 of upload that generated files will be made from .SS "\fIdelete_upload()\fP" .IX Subsection "delete_upload()" .Vb 1 \& $u\->delete_upload($upload_id); .Ve .PP This method is used to delete the meta data and file associated with an upload. Usually it's more convenient to use \f(CW\*(C`delete_checked_uploads\*(C'\fR than to call this method directly. .PP This method does not delete generated files for this upload. .SS "\fIdelete_gen_files()\fP" .IX Subsection "delete_gen_files()" .Vb 1 \& $self\->delete_gen_files($id); .Ve .PP Delete the generated files for a given file \s-1ID,\s0 from the file system and the database .SH "Meta-data Methods" .IX Header "Meta-data Methods" .SS "\fIextract_meta()\fP" .IX Subsection "extract_meta()" .Vb 1 \& $meta = $self\->extract_meta($tmp_filename,$file_name,$uploaded_mt); .Ve .PP This method extracts and returns the meta data about a file and returns it. .PP Input: .PP .Vb 3 \& \- Path to file to extract meta data from \& \- the name of the file (as sent through the file upload file) \& \- The mime\-type of the file, as supplied by the browser .Ve .PP Returns: a hash reference of meta data, following this example: .PP .Vb 5 \& { \& mime_type => \*(Aqimage/gif\*(Aq, \& extension => \*(Aq.gif\*(Aq, \& bytes => 60234, \& file_name => \*(Aqhappy.txt\*(Aq, \& \& # only for images \& width => 50, \& height => 50, \& } .Ve .SS "\fIstore_meta()\fP" .IX Subsection "store_meta()" .Vb 1 \& my $id = $self\->store_meta($file_field,$meta); .Ve .PP This function is used to store the meta data of a file upload. .PP Input: .PP .Vb 1 \& \- file field name \& \& \- A hashref of key/value pairs to be stored. Only the key names defined by the \& C in C will be used. Other values in the hash will be \& ignored. \& \& \- Optionally, an upload ID can be passed, causing an \*(AqUpdate\*(Aq to happen instead of an \*(AqInsert\*(Aq .Ve .PP Output: \- The id of the file stored. The id is generated by \fIstore_meta()\fR. .SS "\fIdelete_meta()\fP" .IX Subsection "delete_meta()" .Vb 1 \& my $dbi_rv = $self\->delete_meta($id); .Ve .PP Deletes the meta data for a file and returns the \s-1DBI\s0 return value for this operation. .SS "\fItransform_meta()\fP" .IX Subsection "transform_meta()" .Vb 6 \& my %meta_to_display = $u\->transform_meta( \& meta => $meta_from_db, \& prefix => \*(Aqmy_field\*(Aq, \& prevent_browser_caching => 0, \& fields => [qw/id url width height/], \& ); .Ve .PP Prepares meta data from the database for display. .PP Input: \- meta: A hashref, as might be returned from \*(L"\s-1SELECT\s0 * \s-1FROM\s0 uploads \s-1WHERE\s0 upload_id = ?\*(R" .PP .Vb 2 \& \- prefix: the resulting hashref keys will be prefixed with this, \& adding an underscore as well. \& \& \- prevent_browse_caching: If set to true, a random query string \& will be added, preventing browsings from caching the image. This is very \& useful when displaying an image an \*(Aqupdate\*(Aq page. Defaults to true. \& \& \- fields: An arrayef of fields to format. The values here must be \& keys in the C. Two field names are special. \*(AqC is \& used to denote the upload_id. C combines several fields into \& a URL to link to the upload. .Ve .PP Output: \- A formatted hash. .PP See \*(L"\fIfk_meta()\fR\*(R" for example output. .SS "\fIget_meta()\fP" .IX Subsection "get_meta()" .Vb 1 \& my $meta_href = $self\->get_meta($id); .Ve .PP Returns a hashref of data stored in the uploads database table for the requested file id. .SH "File Methods" .IX Header "File Methods" .SS "\fIstore_file()\fP" .IX Subsection "store_file()" .Vb 1 \& $self\->store_file($file_field,$tmp_file,$id,$ext); .Ve .PP Stores an upload file or dies if there is an error. .PP Input: \- file field name \- path to tmp file for uploaded image \- file id, as generated by \f(CW\*(C`store_meta()\*(C'\fR \- file extension, as discovered by \fIextract_meta()\fR .PP Output: none .SS "\fIdelete_file()\fP" .IX Subsection "delete_file()" .Vb 1 \& $self\->delete_file($id); .Ve .PP Call from within \f(CW\*(C`delete_upload\*(C'\fR, this routine deletes the actual file. Dont' delete the the meta data first, you may need it build the path name of the file to delete. .SH "Utility Methods" .IX Header "Utility Methods" .SS "\fIbuild_loc()\fP" .IX Subsection "build_loc()" .Vb 1 \& my $up_loc = $self\->build_loc($id,$ext); .Ve .PP Builds a path to access a single upload, relative to \f(CW\*(C`updir_path\*(C'\fR. This is used to both file-system and \s-1URL\s0 access. Also see the \f(CW\*(C`file_scheme\*(C'\fR option to \f(CW\*(C`new()\*(C'\fR, which affects it's behavior. .SS "\fIupload_field_names()\fP" .IX Subsection "upload_field_names()" .Vb 2 \& # As a class method \& (@file_field_names) = CGI::Uploader\->upload_field_names($q); \& \& # As an object method \& (@file_field_names) = $u\->upload_field_names(); .Ve .PP Returns the names of all form fields which contain file uploads. Empty file upload fields may be excluded. .PP This can be useful for auto-generating a \f(CW\*(C`spec\*(C'\fR. .PP Input: \- A query object is required as input only when called as a class method. .PP Output: \- an array of the file upload field names. .SS "\fIspec_names()\fP" .IX Subsection "spec_names()" .Vb 1 \& $spec_names = $u\->spec_names(\*(Aqfile_field\*(Aq): .Ve .PP With no arguments, returns an array of all the upload names defined in the spec, including any generated file names. .PP With one argument, a file field from the spec, can also be provided. It then returns that name as well as the names of any related generated files. .SH "Contributing" .IX Header "Contributing" Patches, questions and feedback are welcome. I maintain CGI::Uploader using git. The public repo is here: https://github.com/markstos/CGI\*(--Uploader .SH "Author" .IX Header "Author" Mark Stosberg .SH "Thanks" .IX Header "Thanks" A special thanks to David Manura for his detailed and persistent feedback in the early days, when the documentation was wild and rough. .PP Barbie, for the first patch. .SH "License" .IX Header "License" This program is free software; you can redistribute it and/or modify it under the terms as Perl itself.