NAME

       Catalyst::View::CSV - CSV view class

SYNOPSIS

           # Create MyApp::View::CSV using the helper:
           script/create.pl view CSV CSV

           # Create MyApp::View::CSV manually:
           package MyApp::View::CSV;
           use base qw ( Catalyst::View::CSV );
           __PACKAGE__->config ( sep_char => ",", suffix => "csv" );
           1;

           # Return a CSV view from a controller:
           $c->stash ( columns => [ qw ( Title Date ) ],
                       cursor => $c->model ( "FilmDB::Film" )->cursor,
                       current_view => "CSV" );
           # or
           $c->stash ( columns => [ qw ( Title Date ) ],
                       data => [
                         [ "Dead Poets Society", "1989" ],
                         [ "Stage Beauty", "2004" ],
                         ...
                       ],
                       current_view => "CSV" );

DESCRIPTION

       Catalyst::View::CSV provides a Catalyst view that generates CSV files.

       You can use either a Perl array of arrays, an array of hashes, an array of objects, or a
       database cursor as the source of the CSV data.  For example:

           my $data = [
             [ "Dead Poets Society", "1989" ],
             [ "Stage Beauty", "2004" ],
             ...
           ];
           $c->stash ( data => $data );

       or

           my $resultset = $c->model ( "FilmDB::Film" )->search ( ... );
           $c->stash ( cursor => $resultset->cursor );

       The CSV file is generated using Text::CSV.

FILENAME

       The filename for the generated CSV file defaults to the last segment of the request URI
       plus a ".csv" suffix.  For example, if the request URI is "http://localhost:3000/report"
       then the generated CSV file will be named "report.csv".

       You can use the "suffix" configuration parameter to specify the suffix of the generated
       CSV file.  You can also use the "filename" stash parameter to specify the filename on a
       per-request basis.

CONFIGURATION PARAMETERS

   suffix
       The filename suffix that will be applied to the generated CSV file.  Defaults to "csv".
       For example, if the request URI is "http://localhost:3000/report" then the generated CSV
       file will be named "report.csv".

       Set to "undef" to prevent any manipulation of the filename suffix.

   charset
       The character set stated in the MIME type of the downloaded CSV file.  Defaults to
       "utf-8".

   eol, quote_char, sep_char, etc.
       Any remaining configuration parameters are passed directly to Text::CSV.

STASH PARAMETERS

   data
       An array containing the literal data to be included in the generated CSV file.  For
       example:

           # Array of arrays
           my $data = [
             [ "Dead Poets Society", "1989" ],
             [ "Stage Beauty", "2004" ],
           ];
           $c->stash ( data => $data );

       or

           # Array of hashes
           my $columns = [ qw ( Title Date ) ];
           my $data = [
             { Title => "Dead Poets Society", Date => 1989 },
             { Title => "Stage Beauty", Date => 2004 },
           ];
           $c->stash ( data => $data, columns => $columns );

       or

           # Array of objects
           my $columns = [ qw ( Title Date ) ];
           my $data = [
             Film->new ( Title => "Dead Poets Society", Date => 1989 ),
             Film->new ( Title => "Stage Beauty", Date => 2004 ),
           ];
           $c->stash ( data => $data, columns => $columns );

       will all (assuming the default configuration parameters) generate the CSV file body:

           "Dead Poets Society",1989
           "Stage Beauty",2004

       You must specify either "data" or "cursor".

   cursor
       A database cursor providing access to the data to be included in the generated CSV file.
       If you are using DBIx::Class, then you can obtain a cursor from any result set using the
       "cursor()" method.  For example:

           my $resultset = $c->model ( "FilmDB::Film" )->search ( ... );
           $c->stash ( cursor => $resultset->cursor );

       You must specify either "data" or "cursor".  For large data sets, using a cursor may be
       more efficient since it avoids copying the whole data set into memory.

   columns
       An optional list of column headings.  For example:

           $c->stash ( columns => [ qw ( Title Date ) ] );

       will produce the column heading row:

           Title,Date

       If no column headings are provided, the CSV file will be generated without a header row
       (and the MIME type attributes will indicate that no header row is present).

       If you are using literal data in the form of an array of hashes or an array of objects,
       then you must specify "columns".  You do not need to specify "columns" when using literal
       data in the form of an array of arrays, or when using a database cursor.

       Extracting the column names from a DBIx::Class result set is surprisingly non-trivial.
       The closest approximation is

           $c->stash ( columns => $resultset->result_source->columns );

       This will use the column names from the primary result source associated with the result
       set.  If you are doing anything even remotely sophisticated, then this will not be what
       you want.  There does not seem to be any supported way to properly extract a list of
       column names from the result set itself.

   filename
       An optional filename for the generated CSV file.  For example:

           $c->stash ( data => $data, filename => "films.csv" );

       If this is not specified, then the filename will be generated from the request URI and the
       "suffix" configuration parameter as described above.

AUTHOR

       Michael Brown <mbrown@fensystems.co.uk>

LICENSE

       This library is free software. You can redistribute it and/or modify it under the same
       terms as Perl itself.