The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

App::ZofCMS::Plugin::DataToExcel - ZofCMS plugin to output data as an Excel file

SYNOPSIS

    plugins => [
        qw/DataToExcel/,
    ],

    plug_data_to_excel => {
        data => [
            [ qw/Foo  Bar  Baz/ ],
            [ qw/Foo1 Bar1 Baz1/ ],
            [ qw/Foo2 Bar2 Baz2/ ],
        ],

        # this argument is optional; by default not specified
        options     => {
            text_wrap           => 1,
            calc_column_widths  => 1,
            width_multiplier    => 1,
            center_first_row    => 1,
        },

        # arguments below are optional; defaults are shown
        trigger     => 1,
        filename    => 'ExcelData.xls',
        no_exit     => 0,
    },

DESCRIPTION

The module is a plugin for App::ZofCMS that provides means to easily export an arrayref of arrayrefs (your data) as an Excel file presented to the user.

This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template. Familarity with Spreadsheet::DataToExcel would be helpful.

FIRST-LEVEL ZofCMS TEMPLATE AND MAIN CONFIG FILE KEYS

plugins

    plugins => [ qw/DataToExcel/ ],

Mandatory. You need to include the plugin in the list of plugins to execute.

plug_data_to_excel

    plug_data_to_excel => {
        data => [
            [ qw/Foo  Bar  Baz/ ],
            [ qw/Foo1 Bar1 Baz1/ ],
            [ qw/Foo2 Bar2 Baz2/ ],
        ],

        # this argument is optional; by default not specified
        options     => {
            text_wrap           => 1,
            calc_column_widths  => 1,
            width_multiplier    => 1,
            center_first_row    => 1,
        },

        # arguments below are optional; defaults are shown
        trigger     => 1,
        filename    => 'ExcelData.xls',
        no_exit     => 0,
    },

    # or
    plug_data_to_excel => sub {
        my ( $t, $q, $config ) = @_;
        return $hashref_to_assign_to_this_key_instead_of_subref;
    },

Mandatory. Takes either a hashref or a subref as a value. If subref is specified, its return value will be assigned to plug_data_to_excel as if it were already there. If sub returns an undef or an empty list, then plugin will stop further processing. The @_ of the subref will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameter hashref, and $config is App::ZofCMS::Config object. Possible keys/values for the hashref are as follows:

data

    plug_data_to_excel => {
        data => [
            [ qw/Foo  Bar  Baz/ ],
            [ qw/Foo1 Bar1 Baz1/ ],
            [ qw/Foo2 Bar2 Baz2/ ],
        ],
    ...

    plug_data_to_excel => {
        data => sub {
            my ( $t, $q, $config ) = @_;
            return $arrayref_to_assign_to_the_key_instead_of_this_subref;
        },
    ...

Mandatory. If not specified, plugin will not execute. Takes an arrayref or a subref as a value. If a subref is specified, it must return either an undef or an empty list, in which case the plugin will not run, or an arrayref that will be assigned to data as if it were there instead of the subref.

If subref is specified, the @_ of the subref will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameter hashref, and $config is App::ZofCMS::Config object.

The arrayref must be in the same format as the second argument of Spreadsheet::DataToExcel's dump() method.

options

    plug_data_to_excel => {
        options => {
            text_wrap           => 1,
            calc_column_widths  => 1,
            width_multiplier    => 1,
            center_first_row    => 1,
        },
    ...

Optional. Takes a hashref of arguments that specify how to format the Excel file. See the third argument for Spreadsheet::DataToExcel's dump()'s method for details. By default is not specified

trigger

    plug_data_to_excel => {
        trigger => 1,
    ...

    plug_data_to_excel => {
        trigger => sub {
            my ( $t, $q, $config ) = @_;
            return $actual_value_for_trigger;
        },
    ...

Optional. Takes either true or false values, or a subref that returns either true or false values. Plugin will run only if trigger is set to a true value. If set to a subref, the @_ of the subref will contain $t, $q, and $config (in that order), where $t is ZofCMS Template hashref, $q is query parameter hashref, and $config is App::ZofCMS::Config object. Defaults to: 1

filename

    plug_data_to_excel => {
        filename => 'ExcelData.xls',
    ...

Optional. Takes a string as a value that specifies the filename that the browser will propose to the user (when saving your Excel file). Defaults to: ExcelData.xls

no_exit

    plug_data_to_excel => {
        no_exit => 0,
    ...

Optional. Takes either true or false values. When plugin finishes outputting the Excel file to the user, it will call exit(), unless no_exit is set to a true value. Should that be the case, it is your responsibility to call exit() at a later time; although, OpenOffice didn't seem to mind extraneous HTML code added to the Excel file. Defaults to: 0

HTML::Template TEMPLATE VARIABLES

plug_data_to_excel_error

    <tmpl_if name='plug_data_to_excel_error'>
        <tmpl_var escape='html' name='plug_data_to_excel_error'>
    </tmpl_if>

Should an error occur (e.g. when you give the plugin invalid data argument), the plugin will place the description of the error into plug_data_to_excel_error key of {t} ZofCMS Template special key.

REQUIRED MODULES

The plugin requires the following modules/versions

    App::ZofCMS::Plugin::Base => 0.0111,
    Spreadsheet::DataToExcel  => 0.0103,

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.