.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Catalyst::View::CSV 3pm"
.TH Catalyst::View::CSV 3pm "2021-02-27" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::View::CSV \- CSV view class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # 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" );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Catalyst::View::CSV provides a Catalyst view that generates \s-1CSV\s0
files.
.PP
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 \s-1CSV\s0 data.
For example:
.PP
.Vb 6
\&    my $data = [
\&      [ "Dead Poets Society", "1989" ],
\&      [ "Stage Beauty", "2004" ],
\&      ...
\&    ];
\&    $c\->stash ( data => $data );
.Ve
.PP
or
.PP
.Vb 2
\&    my $resultset = $c\->model ( "FilmDB::Film" )\->search ( ... );
\&    $c\->stash ( cursor => $resultset\->cursor );
.Ve
.PP
The \s-1CSV\s0 file is generated using Text::CSV.
.SH "FILENAME"
.IX Header "FILENAME"
The filename for the generated \s-1CSV\s0 file defaults to the last segment
of the request \s-1URI\s0 plus a \f(CW\*(C`.csv\*(C'\fR suffix.  For example, if the request
\&\s-1URI\s0 is \f(CW\*(C`http://localhost:3000/report\*(C'\fR then the generated \s-1CSV\s0 file
will be named \f(CW\*(C`report.csv\*(C'\fR.
.PP
You can use the \f(CW\*(C`suffix\*(C'\fR configuration parameter to specify the
suffix of the generated \s-1CSV\s0 file.  You can also use the \f(CW\*(C`filename\*(C'\fR
stash parameter to specify the filename on a per-request basis.
.SH "CONFIGURATION PARAMETERS"
.IX Header "CONFIGURATION PARAMETERS"
.SS "suffix"
.IX Subsection "suffix"
The filename suffix that will be applied to the generated \s-1CSV\s0 file.
Defaults to \f(CW\*(C`csv\*(C'\fR.  For example, if the request \s-1URI\s0 is
\&\f(CW\*(C`http://localhost:3000/report\*(C'\fR then the generated \s-1CSV\s0 file will be
named \f(CW\*(C`report.csv\*(C'\fR.
.PP
Set to \f(CW\*(C`undef\*(C'\fR to prevent any manipulation of the filename suffix.
.SS "charset"
.IX Subsection "charset"
The character set stated in the \s-1MIME\s0 type of the downloaded \s-1CSV\s0 file.
Defaults to \f(CW\*(C`utf\-8\*(C'\fR.
.SS "content_type"
.IX Subsection "content_type"
The Content-Type header to be set for the downloaded file.
Defaults to \f(CW\*(C`text/csv\*(C'\fR.
.SS "eol, quote_char, sep_char, etc."
.IX Subsection "eol, quote_char, sep_char, etc."
Any remaining configuration parameters are passed directly to
Text::CSV.
.SH "STASH PARAMETERS"
.IX Header "STASH PARAMETERS"
.SS "data"
.IX Subsection "data"
An array containing the literal data to be included in the generated
\&\s-1CSV\s0 file.  For example:
.PP
.Vb 6
\&    # Array of arrays
\&    my $data = [
\&      [ "Dead Poets Society", "1989" ],
\&      [ "Stage Beauty", "2004" ],
\&    ];
\&    $c\->stash ( data => $data );
.Ve
.PP
or
.PP
.Vb 7
\&    # 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 );
.Ve
.PP
or
.PP
.Vb 7
\&    # 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 );
.Ve
.PP
will all (assuming the default configuration parameters) generate the
\&\s-1CSV\s0 file body:
.PP
.Vb 2
\&    "Dead Poets Society",1989
\&    "Stage Beauty",2004
.Ve
.PP
You must specify either \f(CW\*(C`data\*(C'\fR or \f(CW\*(C`cursor\*(C'\fR.
.SS "cursor"
.IX Subsection "cursor"
A database cursor providing access to the data to be included in the
generated \s-1CSV\s0 file.  If you are using DBIx::Class, then you can
obtain a cursor from any result set using the \f(CW\*(C`cursor()\*(C'\fR method.  For
example:
.PP
.Vb 2
\&    my $resultset = $c\->model ( "FilmDB::Film" )\->search ( ... );
\&    $c\->stash ( cursor => $resultset\->cursor );
.Ve
.PP
You must specify either \f(CW\*(C`data\*(C'\fR or \f(CW\*(C`cursor\*(C'\fR.  For large data sets,
using a cursor may be more efficient since it avoids copying the whole
data set into memory.
.SS "columns"
.IX Subsection "columns"
An optional list of column headings.  For example:
.PP
.Vb 1
\&    $c\->stash ( columns => [ qw ( Title Date ) ] );
.Ve
.PP
will produce the column heading row:
.PP
.Vb 1
\&    Title,Date
.Ve
.PP
If no column headings are provided, the \s-1CSV\s0 file will be generated
without a header row (and the \s-1MIME\s0 type attributes will indicate that
no header row is present).
.PP
If you are using literal data in the form of an \fBarray of hashes\fR or
an \fBarray of objects\fR, then you must specify \f(CW\*(C`columns\*(C'\fR.  You do not
need to specify \f(CW\*(C`columns\*(C'\fR when using literal data in the form of an
\&\fBarray of arrays\fR, or when using a database cursor.
.PP
Extracting the column names from a DBIx::Class result set is
surprisingly non-trivial.  The closest approximation is
.PP
.Vb 1
\&    $c\->stash ( columns => $resultset\->result_source\->columns );
.Ve
.PP
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.
.SS "filename"
.IX Subsection "filename"
An optional filename for the generated \s-1CSV\s0 file.  For example:
.PP
.Vb 1
\&    $c\->stash ( data => $data, filename => "films.csv" );
.Ve
.PP
If this is not specified, then the filename will be generated from the
request \s-1URI\s0 and the \f(CW\*(C`suffix\*(C'\fR configuration parameter as described
above.
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael Brown <mbrown@fensystems.co.uk>
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software. You can redistribute it and/or modify
it under the same terms as Perl itself.