[Catalyst-dev] [Patch] Cookbook entry for Content-Disposition

[Daniel Westermann-Clark]

At mst's request, here's a patch to add an example of the
Content-Disposition header.  This can be used to force the browser to
download content instead of displaying it.

I wasn't entirely sure where to put the example, but after the RSS
example seemed a decent place.

-- 
Daniel Westermann-Clark
-------------- next part --------------
Patching locally against mirror source http://dev.catalyst.perl.org/repos/Catalyst.
==== Patch <-> level 1
Source: [No source]
Target: 4ad37cd2-5fec-0310-835f-b3785c72a374:/trunk/Catalyst-Runtime:4718
        (http://dev.catalyst.perl.org/repos/Catalyst)
Log:
Add example of Content-Disposition header for forcing downloads
=== lib/Catalyst/Manual/Cookbook.pod
==================================================================
--- lib/Catalyst/Manual/Cookbook.pod	(revision 4718)
+++ lib/Catalyst/Manual/Cookbook.pod	(patch - level 1)
@@ -991,8 +991,47 @@
 Now, go ahead and make RSS feeds for all your stuff. The world *needs*
 updates on your goldfish!
 
+=head2 Forcing the browser to download content
 
+Sometimes you need your application to send content for download. For
+example, you can generate a comma-separated values (CSV) file for your
+users to download and import into their spreadsheet program.
 
+Let's say you have an C<Orders> controller which generates a CSV file
+in the C<export> action (i.e., C<http://localhost:3000/orders/export>):
+
+    sub export : Local Args(0) {
+        my ( $self, $c ) = @_;
+
+        # In a real application, you'd generate this from the database
+        my $csv = "1,5.99\n2,29.99\n3,3.99\n";
+
+        $c->res->content_type('text/comma-separated-values');
+        $c->res->body($csv);
+    }
+
+Normally the browser uses the last part of the URI to generate a
+filename for data it cannot display. In this case your browser would
+likely ask you to save a file named C<export>.
+
+Luckily you can have the browser download the content with a specific
+filename by setting the C<Content-Disposition> header:
+
+    my $filename = 'Important Orders.csv';
+    $c->res->header('Content-Disposition', qq[attachment; filename="$filename"]);
+
+Note the use of quotes around the filename; this ensures that any
+spaces in the filename are handled by the browser.
+
+Put this right before calling C<< $c->res->body >> and your browser
+will download a file named C<Important Orders.csv> instead of
+C<export>.
+
+You can also use this to have the browser download content which it
+normally displays, such as JPEG images or even HTML. Just be sure to
+set the appropriate content type and disposition.
+
+
 =head1 Controllers
 
 Controllers are the main point of communication between the web server
@@ -2229,6 +2268,8 @@
 
 Kieren Diment C<kd at totaldatasolution.com>
 
+Daniel Westermann-Clark C<danieltwc at cpan.org>
+
 =head1 COPYRIGHT
 
 This document is free, you can redistribute it and/or modify it

==== BEGIN SVK PATCH BLOCK ====
Version: svk 1.07 (linux)

eJyFVl1v2zYUDbA3PW/vRKbCDuAvSbZiO4nmwm23dm1X9GsY2sGgRNoiQpMqSSU1qgHr0Me+b+/D
3vbv+gd2SdmKs2WogSA2yXvOveceftxTz09mQZUkg8oPBtWzl99Pp0+wyfJb8MuPK0qYkcofVZxe
UO5HFZcrf1gJvKYwa7BaUZMkAQSP6+C7LmAHMrQYKTZSaH/iwBZGUeoH1WgWV7OwmkUQWgUwKQsq
FkpKA2TBIB6MYHZhc8q41HRhY+36kV0f+sGwDiBM0QwINzY1ljqsXXxk40fb+KuFsKQBim4ACkKL
1J9jg/lGG0f3WciwgRzeBDm5Btl/hEWJueP/LHLUII92Ki0Zp34U3oTZn0t5nsJfr5DEZfNZgmFN
4GZxUfDNwtC3hlBusCMFIrKcpGGQxmkc0phO4iUdx3i4xMNoEE3iIbQjjkbQ/8cHBx/++ObDX198
9XF28P7T64NfP3558Nuf/P2nV38fvPvw+52znGISontSZUyskMkpSpW81FQhIxGRl4JLTFAmhaHC
eN4zuaaGralGG1kiQSmxXxSyebIMGyaFDdRUNEFoKVWD1LNUHn2L1wWnHQeSYYFWVFCFDUUYotZr
3NW0wHaAoAvMS6Brz5+9PEJWaIdnSb0S0tTX8sRAy9aFVAYxARNQD1NIFwqq1DmlBhVKrhRe9zzv
ITUtjTTeuCxyfAHsAs1Pf1AEYBOXvpKcgxSXOcvyJkkNWUI2LhmPCSfa/JS+tbQJwpkToc16tNeB
8dyYYtrvc5lhnkttptFgMOhLR9LfBh1NPQ/BR5cpqofQFD20Eei2Wun24Ai9cwvsZ71BbeRrypcd
5GfoCJ2h2eLEa+a/RvcFZAgl8/22OLFb5EpqkzONlkquXQEEbJtiTfdp/ExfAPph0Bn1JpPXIuyE
E/cl6kTu/+EerZ91E0V1N9m2fWE2BW23rHX7/+ppt+5p6+jkv9GpJJu2Jd5O/uJ5j6VaY84319wJ
vddugGMNXcUgmVy6gRdP71tPXFnKs42yB2TtRCgUMWNtJ6RBhOmC403PiuYUyUCE2tM7qktZcuJx
dk4hB6zPnV+syZ1lak9aeHLlAmuvMjtnfNNY3Blsv4LGtHZwt1cumckBUxc0Y0uWXaWebmBTGbPb
pPPTeR3RvQMFSM1sixNkdzNVWzfZDjbxZ6h1320MDCy1xXugcqtWuZG/Bmi3bkBvddCbN6+wMTjL
1zB3gnbgZ4cNz+HP0DfomKlrhS7Ztrwppds2Spairne3/qQWnQpdKtdQbGAXbjxd4Ax+b3dXUwVW
FIQUhIPY6TVDgOJPSlOjKbbKDUoptBuUBetY1eanp9ddhpLEnRf7vfYuGed7x8n15t4kYAI5agOq
QZ3efv9/2vYdcy2dDi41sM3/G6ExgTtumPHEzvlbl+oOHBEwhTV68OTut3DU4RWoBK6Gx4BA3z1/
9LCHHpTaFo+sosDngW0cHZwFShaK2T2xY7J71IlArvrcu4MFoxz9SKEu4BeiO+dYnYMAxM2Yy2yW
FVj0pFrNhvtvAncPbq+ocRBko4zg6DilQxxHJByTYzoYp6PlKB7gwL0M4qi6TQja3gfWKjcYb+tq
t3uX24tqp5kGmG6ShJUfhvV757l7Ak2nLwS7gB5hfiuu4IFUYJPDk0TRC/hRloz4YVT1jSrFeXNl
d5+Wwl5usGJ4HIz9KK6GmETHGQm7oyXNuoMoGHTH0WjZTaPj8Sg7DqG84T8Wi0Wz
==== END SVK PATCH BLOCK ====