X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=06a6dbe8bebaf70626fde3b1e92a4b99ba7a38f5;hb=e1576f62c7ed3becfc6fa7465e0922507d254f31;hp=400d589fe5e3c771de7b66a1370d2ca64888522e;hpb=28dc3f0e62df58f17417c169c9f66068f525bc09;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod index 400d589..06a6dbe 100644 --- a/lib/Catalyst/Manual/Cookbook.pod +++ b/lib/Catalyst/Manual/Cookbook.pod @@ -1,4 +1,4 @@ -=head1 NAME +S=head1 NAME Catalyst::Manual::Cookbook - Cooking with Catalyst @@ -205,6 +205,28 @@ This is equivalent to: See also L. +=head1 Skipping your VCS's directories + +Catalyst uses Module::Pluggable to load Models, Views and Controllers. +Module::Pluggable will scan through all directories and load modules +it finds. Sometimes you might want to skip some of these directories, +for example when your version control system makes a subdirectory with +meta-information in every version-controlled directory. While +Catalyst skips subversion and CVS directories already, there are other +source control systems. Here is the configuration you need to add +their directories to the list to skip. + +You can make catalyst skip these directories using the Catalyst config: + + # Configure the application + __PACKAGE__->config( + name => 'MyApp', + setup_components => { except => qr/SCCS/ }, + ); + +See the Module::Pluggable manual page for more information on B +and other options. + =head1 Users and Access Control Most multiuser, and some single user web applications require that @@ -573,12 +595,6 @@ C, etc will also be restricted. will create rules that permit access to C, C, and C in the root of your app (but not in any other controller). -=head1 COPYRIGHT - -This program is free software, you can redistribute it and/or modify it -under the same terms as Perl itself. - - =head1 Models Models are where application data belongs. Catalyst is exteremely @@ -997,6 +1013,45 @@ variable, so you can generate Atom feeds with the same code. 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 controller which generates a CSV file +in the C action (i.e., C): + + 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. + +Luckily you can have the browser download the content with a specific +filename by setting the C 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 instead of +C. + +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 @@ -1357,13 +1412,11 @@ including web server engines and tips to improve application efficiency. =head2 mod_perl Deployment -=head3 Pros & Cons - -mod_perl is the best solution for many applications, but I'll list some pros +mod_perl is the best solution for many applications, but we'll list some pros and cons so you can decide for yourself. The other production deployment -option is FastCGI, which I'll talk about in a future calendar article. +option is FastCGI, for which see below. -=head4 Pros +=head3 Pros =head4 Speed @@ -1375,7 +1428,7 @@ within each Apache process. If you need to run several Catalyst apps on the same server, mod_perl will share the memory for common modules. -=head4 Cons +=head3 Cons =head4 Memory usage @@ -1626,6 +1679,64 @@ Now, we simply configure Apache to connect to the running server. L. +=head2 Development server deployment + +The developemnt server is a mini web server written in perl. If you +expect a low number of hits or you don't need mod_perl/FastCGI speed, +you could use the development server as the application server with a +lightweight proxy web server at the front. However, be aware that +there are known issues, especially with Internet Explorer. Many of +these issues can be dealt with by running the server with the -k +(keepalive) option but be aware for more complex applications this may +not be suitable. Consider using Catalyst::Engine::POE. This recipe +is easily adapted for POE as well. + +=head3 Pros + +As this is an application server setup, the pros are the same as +FastCGI (with the exception of speed). +It is also: + +=head4 Simple + +The development server is what you create your code on, so if it works here, it should work in production! + +=head3 Cons + +=head4 Speed + +Not as fast as mod_perl or FastCGI. Needs to fork for each request +that comes in - make sure static files are served by the web server to +save forking. + +=head3 Setup + +=head4 Start up the development server + + script/myapp_server.pl -p 8080 -k -f -pidfile=/tmp/myapp.pid -daemon + +You will probably want to write an init script to handle stop/starting +the app using the pid file. + +=head4 Configuring Apache + +Make sure mod_proxy is enabled and add: + + # Serve static content directly + DocumentRoot /var/www/MyApp/root + Alias /static /var/www/MyApp/root/static + + ProxyRequests Off + + Order deny,allow + Allow from all + + ProxyPass / http://localhost:8080/ + ProxyPassReverse / http://localhost:8080/ + +You can wrap the above within a VirtualHost container if you want +different apps served on the same host. + =head2 Quick deployment: Building PAR Packages You have an application running on your development box, but then you @@ -2217,13 +2328,28 @@ L =head1 AUTHORS -Sebastian Riedel, C -Danijel Milicevic, C -Viljo Marrandi, C -Marcus Ramberg, C -Jesse Sheidlower, C -Andy Grundman, C -Chisel Wright, C -Will Hawes, C -Gavin Henry, C +Sebastian Riedel C + +Danijel Milicevic C + +Viljo Marrandi C + +Marcus Ramberg C + +Jesse Sheidlower C + +Andy Grundman C + +Chisel Wright C + +Will Hawes C + +Gavin Henry C + Kieren Diment C + +=head1 COPYRIGHT + +This document is free, you can redistribute it and/or modify it +under the same terms as Perl itself. +