/ 
App-ZofCMS-Plugin-FileUpload-0.0101
/ App::ZofCMS::Plugin::FileUpload

NAME

App::ZofCMS::Plugin::FileUpload - ZofCMS plugin to handle file uploads

SYNOPSIS

In your ZofCMS template:

file_upload => {
    query   => 'uploaded_file',
},
plugins => [ qw/FileUpload/ ],

In your HTML::Template template:

<tmpl_if name="upload_error">
    <p class="error">Upload failed: <tmpl_var name="upload_error">
</tmpl_if>
<tmpl_if name="upload_success">
    <p>Upload succeeded: <tmpl_var name="upload_filename"></p>
</tmpl_if>

<form action="" method="POST" enctype="multipart/form-data">
<div>
    <input type="file" name="uploaded_file">
    <input type="submit" value="Upload">
</div>
</form>

DESCRIPTION

The module is a ZofCMS plugin which provides means to easily handle file uploads.

This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template

FIRST-LEVEL ZofCMS TEMPLATE KEYS

plugins

plugins => [ qw/FileUpload/ ],

First and obvious, you need to stick FileUpload in the list of your plugins.

file_upload

file_upload => {
    query   => 'upload',
    path    => 'zofcms_upload',
    name    => 'foos',
    ext     => '.html',
    content_type => 'text/html',
    on_success => sub {
        my ( $uploaded_file_name, $template, $query, $conf ) = @_;
        # do something useful
    }
},

# or

file_upload => [
    { query   => 'upload1', },
    { query   => 'upload2', },
    {}, # all the defaults
    {
        query   => 'upload4',
        name    => 'foos',
        ext     => '.html',
        content_type => 'text/html',
        on_success => sub {
            my ( $uploaded_file_name, $template, $query, $conf ) = @_;
            # do something useful
        }
    },
],

Plugin takes input from file_upload first level ZofCMS template key which takes an arrayref or a hashref as a value. Passing a hashref as a value is the same as passing an arrayref with just that hashref as an element. Each element of the given arrayref is a hashref which represents one file upload. The possible keys/values of those hashrefs are as follows:

query

{ query => 'zofcms_upload' },

Optional. Specifies the query parameter which is the file being uploaded, in other words, this is the value of the name="" attribute of the <input type="file".... Defaults to: zofcms_upload

path

{ path => 'zofcms_upload', }

Optional. Specifies directory (relative to index.pl) into which the plugin will store uploaded files. Defaults to: zofcms_upload

name

{ name => 'foos', }

Optional. Specifies the name (without the extension) of the local file into which save the uploaded file. Special value of [rand] specifies that the name should be random, in which case it will be created by calling rand() and time() and removing any dots from the concatenation of those two. Defaults to: [rand]

ext

{ ext => '.html', }

Optional. Specifies the extension to use for the name of local file into which the upload will be stored. By default is not specified and therefore the extension will be obtained from the name of the remote file.

content_type

{ content_type => 'text/html', }

{ content_type => [ 'text/html', 'image/jpeg' ], }

Optional. Takes either a scalar string or an arrayref of strings. Specifying a string is equivalent to specifying an arrayref with just that string as an element. Each element of the given arrayref indicates the allowed Content-Type of the uploaded files. If the Content-Type does not match allowed types the error will be shown (see HTML TEMPLATE VARS section below). By default all Content-Types are allowed.

on_success

on_success => sub {
    my ( $uploaded_file_name, $template, $query, $config ) = @_;
    # do something useful
}

Optional. Takes a subref as a value. The specified sub will be executed upon a successful upload. The @_ will contain the following elements: $uploaded_file_name, $template, $query, $config where $uploaded_file_name is the directory + name + extension of the local file into which the upload was stored, $template is a hashref of your ZofCMS template, $query is a hashref of query parameters and $config is the App::ZofCMS::Config object. By default is not specified.

HTML TEMPLATE VARS

Single upload:

<tmpl_if name="upload_error">
    <p class="error">Upload failed: <tmpl_var name="upload_error">
</tmpl_if>
<tmpl_if name="upload_success">
    <p>Upload succeeded: <tmpl_var name="upload_filename"></p>
</tmpl_if>

<form action="" method="POST" enctype="multipart/form-data">
<div>
    <input type="file" name="upload">
    <input type="submit" value="Upload">
</div>
</form>

Multi upload:

<tmpl_if name="upload_error0">
    <p class="error">Upload 1 failed: <tmpl_var name="upload_error0">
</tmpl_if>
<tmpl_if name="upload_success0">
    <p>Upload 1 succeeded: <tmpl_var name="upload_filename0"></p>
</tmpl_if>

<tmpl_if name="upload_error1">
    <p class="error">Upload 2 failed: <tmpl_var name="upload_error1">
</tmpl_if>
<tmpl_if name="upload_success1">
    <p>Upload 2 succeeded: <tmpl_var name="upload_filename1"></p>
</tmpl_if>

<form action="" method="POST" enctype="multipart/form-data">
<div>
    <input type="file" name="upload">
    <input type="file" name="upload2">
    <input type="submit" value="Upload">
</div>
</form>

NOTE: upload of multiple files from a single <input type="file"... is currently not supported. Let me know if you need such functionality. The folowing <tmpl_var name="">s will be set in your HTML::Template template.

SINGLE AND MULTI

If you are handling only one upload, i.e. you have only one hashref in file_upload ZofCMS template key and you have only one <input type="file"... then the HTML::Template variables described below will NOT have any trailing numbers, otherwise each of them will have a trailing number indicating the number of the upload. This number will starts from zero and it will correspond to the index of hashref of file_upload arrayref.

upload_error

# single
<tmpl_if name="upload_error">
    <p class="error">Upload failed: <tmpl_var name="upload_error">
</tmpl_if>

# multi
<tmpl_if name="upload_error0">
    <p class="error">Upload 1 failed: <tmpl_var name="upload_error0">
</tmpl_if>

The upload_error will be set if some kind of an error occurred during the upload of the file. This also includes if the user tried to upload a file of type which is not listed in content_type arrayref.

upload_success

# single
<tmpl_if name="upload_success">
    <p>Upload succeeded: <tmpl_var name="upload_filename"></p>
</tmpl_if>

# multi
<tmpl_if name="upload_success0">
    <p>Upload 1 succeeded: <tmpl_var name="upload_filename0"></p>
</tmpl_if>

The upload_success will be set to a true value upon successful upload.

upload_filename

# single
<tmpl_if name="upload_success">
    <p>Upload succeeded: <tmpl_var name="upload_filename"></p>
</tmpl_if>

# multi
<tmpl_if name="upload_success0">
    <p>Upload 1 succeeded: <tmpl_var name="upload_filename0"></p>
</tmpl_if>

The upload_filename will be set to directory + name + extension of the local file into which the upload was saved.

AUTHOR

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

BUGS

Please report any bugs or feature requests to bug-app-zofcms-plugin-fileupload at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-ZofCMS-Plugin-FileUpload. I will be notified, and then you'll 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 App::ZofCMS::Plugin::FileUpload

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Zoffix Znet, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.