Cataly...ew::CSV(3pm)

✨ NAME ✨

Catalyst::View::CSV — the CSV view class, bestie 💖

(It's a Perl module, it lives in the User Contributed Perl Documentation corner of the manual, and it's here to make your Catalyst app spit out CSV files like it's nothing.)

---

🦋 SYNOPSIS 🦋

okay so first things first, you can let the helper build the whole view for you:

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

or, if you're feeling main character and wanna do it by hand:

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

then in your controller you just yeet it into the stash and pick the CSV view:

# 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" );

periodt 💅

---

🌸 DESCRIPTION 🌸

Catalyst::View::CSV gives you a Catalyst view that generates CSV files. That's the whole vibe.

For the source of your CSV data you've got options, and honestly? iconic. You can use any of these:

• a Perl array of arrays 🍓
• an array of hashes
• an array of objects
• a database cursor

like, for example:

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

orrrr:

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

The CSV file itself is generated using Text::CSV — no cap. ✨

---

🎀 FILENAME 🎀

So the filename for your generated CSV file? By default it's the last segment of the request URI plus a .csv suffix. Example time: if your request URI is http://localhost:3000/report, then the generated CSV file will be named report.csv. slay.

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. Choices! We love choices. 💖

---

👑 CONFIGURATION PARAMETERS 👑

suffix

The filename suffix that gets applied to the generated CSV file. Defaults to csv. So like, if the request URI is http://localhost:3000/report, then the generated CSV file will be named report.csv. (Yes, same example. It's a good example.)

Set it to undef if you want to prevent any manipulation of the filename suffix. Zero touching. Hands off. 🙈

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. Straight through. No middleman. ✨

---

💜 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. Not optional. Not negotiable. 💀

cursor

A database cursor providing access to the data to be included in the generated CSV file. If you're 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. (Yes, same rule as above — it's that serious.) For large data sets, using a cursor may be more efficient since it avoids copying the whole data set into memory. Memory said "not today." 🧚

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). iykyk.

If you're 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.

okay so real talk: 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're 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. 😭 That's just the situation. We're all living in it together.

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. (Scroll up, bestie, the FILENAME section has the whole story. ⭐)

---

🌈 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. 🫶

---

and that's the whole page, bestie!! this was perl v5.32.1, dated 2021-02-27, straight outta the User Contributed Perl Documentation section of the manual. go forth and generate CSV files, you absolute icon 👑✨💖