/ 
Catalyst-View-CSV-1.8
River stage zero No dependents
/ Catalyst::View::CSV

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.

content_type

The Content-Type header to be set for the downloaded file. Defaults to text/csv.

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.