NAME

App::ZofCMS::Plugin::SendFile - plugin for flexible sending of files as well as files outside of web-accessible directory

SYNOPSIS

In your ZofCMS Template or Main Config File:

    plugins => [ qw/SendFile/ ],

    plug_send_file => [
        '../zcms_site/config.txt',  # filename to send; this one is outside the webdir
        'attachment',               # optional to set content-disposition to attachment
        'text/plain',               # optional to set content-type instead of guessing one
        'LOL.txt',                  # optional to set filename instead of using same as original
    ],

In your HTML::Template template:

    <tmpl_if name='plug_send_file_error'>
        <p class="error">Got error: <tmpl_var escape='html' name='plug_send_file_error'></p>
    </tmpl_if>

DESCRIPTION

The module is a plugin for App::ZofCMS that provides means for flexible sending of files (e.g. sending it as an attachment (for download) or changing the filename), most important feature of the plugin is that you can use it to send files outside of web-accessible directory which in conjunction with say App::ZofCMS::Plugin::UserLogin can provide user account restricted file sending.

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

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

plugins and notes on exiting

    plugins => [ qw/SendFile/ ],

    plugins => [
        { UserLogin => 200 },
        { SendFile  => 300 },
    ],

We need to include the plugin in the list of plugins to execute; ensure to get the right priority if you're using other plugins.

NOTE: unless an error occurs, the plugins calls exit() when it's done sending the file, make sure that all the required plugins had their chance to execute BEFORE this one.

plug_send_file

    plug_send_file => 'foo.txt', # file to send

    plug_send_file => [
        '../zcms_site/config.txt',  # filename to send; this one is outside the webdir
        'attachment',               # optional to set content-disposition to attachment
        'text/plain',               # optional to set content-type instead of guessing one
        'LOL.txt',                  # optional to set filename instead of using same as original
    ],

    plug_send_file => sub {
        my ( $t, $q, $conf ) = @_;
        return 'foo.txt';
    },

Mandatory. Takes either a string, subref or an arrayref as a value, can be specified in either ZofCMS Template or Main Config File; if set in both, the value in ZofCMS Template is used.

When set to a subref, the sub will be executed and its return value will be assigned to the key; returning undef will stop the plugin from execution. The @_ will contain (in that order): ZofCMS Template hashref, query parameters hashref, App::ZofCMS::Config object.

When set to a string it's the same as setting to an arrayref with just one value in it.

Here are how arrayref elements are interpreted:

FIRST ELEMENT

    plug_send_file => [
        '../zcms_site/config.txt',
    ],

Mandatory. Specifies the name of the file to send. The filename is relative to index.pl and can be outside of webroot. Note that if you're taking this name from the user, it's up to you to ensure that it's safe.

SECOND ELEMENT

    plug_send_file => [
        '../zcms_site/config.txt',
        'attachment',
    ],

Optional. Specifies Content-Disposition type, which can be inline, attachment or an extension-token. See RFC 2183 for details. Note: this parameter only takes the TYPE not the whole header (which isn't supported by the plugin so you'll have to modify it if you need this). Defaults to: inline, you can set this to undef to take it's default value.

THIRD ELEMENT

    plug_send_file => [
        '../zcms_site/config.txt',
        undef,
        'text/plain',
    ]

Optional. Specifies the Content-Type to use. When set to undef, the plugin will try to guess the correct type to use using MIME::Types module. Defauts to: undef

FOURTH ELEMENT

    plug_send_file => [
        '../zcms_site/config.txt',
        undef,
        undef,
        'LOL.txt',
    ],

Optional. Speficies the filename to use when sending the file. Note that this applies even when content disposition type is set to inline for when the user would want to save the file. When set to undef, the plugin will use the same name as the original file. Defaults to: undef.

HTML::Template VARIABLES - ERROR HANDLING

plug_send_file_error

    <tmpl_if name='plug_send_file_error'>
        <p class="error">Got error: <tmpl_var escape='html' name='plug_send_file_error'></p>
    </tmpl_if>

If the plugin cannot read the file you specified for sending, it will set the plug_send_file_error key inside t ZofCMS Template special key to the error message (to the value of $! to be specific) and will stop processing (i.e. won't send any files or exit()).

"default" Content-Type

If plugin was told to derive the right Content-Type of the file, but it couldn't derive one, it will use application/octet-stream

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS/issues

If you can't access GitHub, you can email your request to bug-App-ZofCMS at rt.cpan.org

AUTHOR

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

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.

cpanm App::ZofCMS

perl -MCPAN -e shell
install App::ZofCMS