1Catalyst::Manual::CookbUosoekr(3C)ontributed Perl DocumeCnattaatliyosnt::Manual::Cookbook(3)
2
6 Catalyst::Manual::Cookbook - Cooking with Catalyst
7
9 Yummy code like your mum used to bake!
10
13 These recipes cover some basic stuff that is worth knowing for Catalyst
14 developers.
15 Delivering a Custom Error Page
17 By default, Catalyst will display its own error page whenever it
18 encounters an error in your application. When running under "-Debug"
19 mode, the error page is a useful screen including the error message and
20 Data::Dump output of the relevant parts of the $c context object. When
21 not in "-Debug", users see a simple "Please come back later" screen.
22 To use a custom error page, use a special "end" method to short-circuit
24 the error processing. The following is an example; you might want to
25 adjust it further depending on the needs of your application (for
26 example, any calls to "fillform" will probably need to go into this
27 "end" method; see Catalyst::Plugin::FillInForm).
28 sub end : Private {
30 my ( $self, $c ) = @_;
31 if ( scalar @{ $c->error } ) {
33 $c->stash->{errors} = $c->error;
34 for my $error ( @{ $c->error } ) {
35 $c->log->error($error);
36 }
37 $c->stash->{template} = 'errors.tt';
38 $c->forward('MyApp::View::TT');
39 $c->clear_errors;
40 }
41 return 1 if $c->response->status =~ /^3\d\d$/;
43 return 1 if $c->response->body;
44 unless ( $c->response->content_type ) {
46 $c->response->content_type('text/html; charset=utf-8');
47 }
48 $c->forward('MyApp::View::TT');
50 }
51 You can manually set errors in your code to trigger this page by
53 calling
54 $c->error( 'You broke me!' );
56 Disable statistics
58 Just add this line to your application class if you don't want those
59 nifty statistics in your debug messages.
60 sub Catalyst::Log::info { }
62 Enable debug status in the environment
64 Normally you enable the debugging info by adding the "-Debug" flag to
65 your "use Catalyst" statement . However, you can also enable it using
66 environment variable, so you can (for example) get debug info without
67 modifying your application scripts. Just set "CATALYST_DEBUG" or
68 "<MYAPP>_DEBUG" to a true value.
69 Sessions
71 When you have your users identified, you will want to somehow remember
72 that fact, to save them from having to identify themselves for every
73 single page. One way to do this is to send the username and password
74 parameters in every single page, but that's ugly, and won't work for
75 static pages.
76 Sessions are a method of saving data related to some transaction, and
78 giving the whole collection a single ID. This ID is then given to the
79 user to return to us on every page they visit while logged in. The
80 usual way to do this is using a browser cookie.
81 Catalyst uses two types of plugins to represent sessions:
83 State
85 A State module is used to keep track of the state of the session
87 between the users browser, and your application.
88 A common example is the Cookie state module, which sends the browser a
90 cookie containing the session ID. It will use default value for the
91 cookie name and domain, so will "just work" when used.
92 Store
94 A Store module is used to hold all the data relating to your session,
96 for example the users ID, or the items for their shopping cart. You can
97 store data in memory (FastMmap), in a file (File) or in a database
98 (DBI).
99 Authentication magic
101 If you have included the session modules in your application, the
103 Authentication modules will automagically use your session to save and
104 retrieve the user data for you.
105 Using a session
107 Once the session modules are loaded, the session is available as
109 "$c->session", and can be written to and read from as a simple hash
110 reference.
111 EXAMPLE
113 package MyApp;
115 use Moose;
116 use namespace::autoclean;
117 use Catalyst qw/
119 Session
120 Session::Store::FastMmap
121 Session::State::Cookie
122 /;
123 extends 'Catalyst';
124 __PACKAGE__->setup;
125 package MyApp::Controller::Foo;
127 use Moose;
128 use namespace::autoclean;
129 BEGIN { extends 'Catalyst::Controller' };
130 ## Write data into the session
131 sub add_item : Local {
133 my ( $self, $c ) = @_;
134 my $item_id = $c->req->params->{item};
136 push @{ $c->session->{items} }, $item_id;
138 }
139 ## A page later we retrieve the data from the session:
141 sub get_items : Local {
143 my ( $self, $c ) = @_;
144 $c->stash->{items_to_display} = $c->session->{items};
146 }
147 More information
149 Catalyst::Plugin::Session
151 Catalyst::Plugin::Session::State::Cookie
153 Catalyst::Plugin::Session::State::URI
155 Catalyst::Plugin::Session::Store::FastMmap
157 Catalyst::Plugin::Session::Store::File
159 Catalyst::Plugin::Session::Store::DBI
161 Configure your application
163 You configure your application with the "config" method in your
164 application class. This can be hard-coded, or brought in from a
165 separate configuration file.
166 Using Config::General
168 Config::General is a method for creating flexible and readable
170 configuration files. It's a great way to keep your Catalyst application
171 configuration in one easy-to-understand location.
172 Now create myapp.conf in your application home:
174 name MyApp
176 # session; perldoc Catalyst::Plugin::Session::FastMmap
178 <Session>
179 expires 3600
180 rewrite 0
181 storage /tmp/myapp.session
182 </Session>
183 # emails; perldoc Catalyst::Plugin::Email
185 # this passes options as an array :(
186 Mail SMTP
187 Mail localhost
188 This is equivalent to:
190 # configure base package
192 __PACKAGE__->config( name => MyApp );
193 # configure authentication
194 __PACKAGE__->config(
195 'Plugin::Authentication' => {
196 user_class => 'MyApp::Model::MyDB::Customer',
197 ...
198 },
199 _;
200 # configure sessions
201 __PACKAGE__->config(
202 session => {
203 expires => 3600,
204 ...
205 },
206 );
207 # configure email sending
208 __PACKAGE__->config( email => [qw/SMTP localhost/] );
209 Catalyst explains precedence of multiple sources for configuration
211 values, how to access the values in your components, and many 'base'
212 config variables used internally.
213 See also Config::General.
215
217 Catalyst uses Module::Pluggable to load Models, Views, and Controllers.
218 Module::Pluggable will scan through all directories and load modules it
219 finds. Sometimes you might want to skip some of these directories, for
220 example when your version control system makes a subdirectory with
221 meta-information in every version-controlled directory. While Catalyst
222 skips subversion and CVS directories already, there are other source
223 control systems. Here is the configuration you need to add their
224 directories to the list to skip.
225 You can make Catalyst skip these directories using the Catalyst config:
227 # Configure the application
229 __PACKAGE__->config(
230 name => 'MyApp',
231 setup_components => { except => qr/SCCS/ },
232 );
233 See the Module::Pluggable manual page for more information on except
235 and other options.
236
238 Most multiuser, and some single-user web applications require that
239 users identify themselves, and the application is often required to
240 define those roles. The recipes below describe some ways of doing
241 this.
242 Authentication (logging in)
244 This is extensively covered in other documentation; see in particular
245 Catalyst::Plugin::Authentication and the Authentication chapter of the
246 Tutorial at Catalyst::Manual::Tutorial::06_Authorization.
247 Pass-through login (and other actions)
249 An easy way of having assorted actions that occur during the processing
250 of a request that are orthogonal to its actual purpose - logins, silent
251 commands etc. Provide actions for these, but when they're required for
252 something else fill e.g. a form variable __login and have a sub begin
253 like so:
254 sub begin : Private {
256 my ($self, $c) = @_;
257 foreach my $action (qw/login docommand foo bar whatever/) {
258 if ($c->req->params->{"__${action}"}) {
259 $c->forward($action);
260 }
261 }
262 }
263 Authentication/Authorization
265 This is done in several steps:
266 Verification
268 Getting the user to identify themselves, by giving you some piece
269 of information known only to you and the user. Then you can assume
270 that the user is who they say they are. This is called credential
271 verification.
272 Authorization
274 Making sure the user only accesses functions you want them to
275 access. This is done by checking the verified user's data against
276 your internal list of groups, or allowed persons for the current
277 page.
278 Modules
280 The Catalyst Authentication system is made up of many interacting
282 modules, to give you the most flexibility possible.
283 Credential verifiers
285 A Credential module tables the user input, and passes it to a Store, or
287 some other system, for verification. Typically, a user object is
288 created by either this module or the Store and made accessible by a
289 "$c->user" call.
290 Examples:
292 Password - Simple username/password checking.
294 HTTPD - Checks using basic HTTP auth.
295 TypeKey - Check using the typekey system.
296 Storage backends
298 A Storage backend contains the actual data representing the users. It
300 is queried by the credential verifiers. Updating the store is not done
301 within this system; you will need to do it yourself.
302 Examples:
304 DBIC - Storage using a database via DBIx::Class.
306 Minimal - Storage using a simple hash (for testing).
307 User objects
309 A User object is created by either the storage backend or the
311 credential verifier, and is filled with the retrieved user information.
312 Examples:
314 Hash - A simple hash of keys and values.
316 ACL authorization
318 ACL stands for Access Control List. The ACL plugin allows you to
320 regulate access on a path-by-path basis, by listing which users, or
321 roles, have access to which paths.
322 Roles authorization
324 Authorization by roles is for assigning users to groups, which can then
326 be assigned to ACLs, or just checked when needed.
327 Logging in
329 When you have chosen your modules, all you need to do is call the
331 "$c->authenticate" method. If called with no parameters, it will try to
332 find suitable parameters, such as username and password, or you can
333 pass it these values.
334 Checking roles
336 Role checking is done by using the "$c->check_user_roles" method. This
338 will check using the currently logged-in user (via "$c->user"). You
339 pass it the name of a role to check, and it returns true if the user is
340 a member.
341 EXAMPLE
343 package MyApp;
345 use Moose;
346 use namespace::autoclean;
347 extends qw/Catalyst/;
348 use Catalyst qw/
349 Authentication
350 Authorization::Roles
351 /;
352 __PACKAGE__->config(
354 authentication => {
355 default_realm => 'test',
356 realms => {
357 test => {
358 credential => {
359 class => 'Password',
360 password_field => 'password',
361 password_type => 'self_check',
362 },
363 store => {
364 class => 'Htpasswd',
365 file => 'htpasswd',
366 },
367 },
368 },
369 },
370 );
371 package MyApp::Controller::Root;
373 use Moose;
374 use namespace::autoclean;
375 BEGIN { extends 'Catalyst::Controller' }
377 __PACKAGE__->config(namespace => '');
379 sub login : Local {
381 my ($self, $c) = @_;
382 if ( my $user = $c->req->params->{user}
384 and my $password = $c->req->param->{password} )
385 {
386 if ( $c->authenticate( username => $user, password => $password ) ) {
387 $c->res->body( "hello " . $c->user->name );
388 } else {
389 # login incorrect
390 }
391 }
392 else {
393 # invalid form input
394 }
395 }
396 sub restricted : Local {
398 my ( $self, $c ) = @_;
399 $c->detach("unauthorized")
401 unless $c->check_user_roles( "admin" );
402 # do something restricted here
404 }
405 Using authentication in a testing environment
407 Ideally, to write tests for authentication/authorization code one would
409 first set up a test database with known data, then use
410 Test::WWW::Mechanize::Catalyst to simulate a user logging in.
411 Unfortunately this can be rather awkward, which is why it's a good
412 thing that the authentication framework is so flexible.
413 Instead of using a test database, one can simply change the
415 authentication store to something a bit easier to deal with in a
416 testing environment. Additionally, this has the advantage of not
417 modifying one's database, which can be problematic if one forgets to
418 use the testing instead of production database.
419 Alternatively, if you want to authenticate real users, but not have to
421 worry about their passwords, you can use
422 Catalyst::Authentication::Credential::Testing to force all users to
423 authenticate with a global password.
424 More information
426 Catalyst::Plugin::Authentication has a longer explanation.
428 Authorization
430 Introduction
431 Authorization is the step that comes after authentication.
433 Authentication establishes that the user agent is really representing
434 the user we think it's representing, and then authorization determines
435 what this user is allowed to do.
436 Role Based Access Control
438 Under role based access control each user is allowed to perform any
440 number of roles. For example, at a zoo no one but specially trained
441 personnel can enter the moose cage (Mynd you, møøse bites kan be pretty
442 nasti!). For example:
443 package Zoo::Controller::MooseCage;
445 sub feed_moose : Local {
447 my ( $self, $c ) = @_;
448 $c->model( "Moose" )->eat( $c->req->params->{food} );
450 }
451 With this action, anyone can just come into the moose cage and feed the
453 moose, which is a very dangerous thing. We need to restrict this
454 action, so that only a qualified moose feeder can perform that action.
455 The Authorization::Roles plugin lets us perform role based access
457 control checks. Let's load it:
458 use parent qw/Catalyst/;
460 use Catalyst qw/
461 Authentication
462 Authorization::Roles
463 /;
464 And now our action should look like this:
466 sub feed_moose : Local {
468 my ( $self, $c ) = @_;
469 if ( $c->check_roles( "moose_feeder" ) ) {
471 $c->model( "Moose" )->eat( $c->req->params->{food} );
472 } else {
473 $c->stash->{error} = "unauthorized";
474 }
475 }
476 This checks "$c->user", and only if the user has all the roles in the
478 list, a true value is returned.
479 "check_roles" has a sister method, "assert_roles", which throws an
481 exception if any roles are missing.
482 Some roles that might actually make sense in, say, a forum application:
484 • administrator
486 • moderator
488 each with a distinct task (system administration versus content
490 administration).
491 Access Control Lists
493 Checking for roles all the time can be tedious and error prone.
495 The Authorization::ACL plugin lets us declare where we'd like checks to
497 be done automatically for us.
498 For example, we may want to completely block out anyone who isn't a
500 "moose_feeder" from the entire "MooseCage" controller:
501 Zoo->deny_access_unless( "/moose_cage", [qw/moose_feeder/] );
503 The role list behaves in the same way as "check_roles". However, the
505 ACL plugin isn't limited to just interacting with the Roles plugin. We
506 can use a code reference instead. For example, to allow either moose
507 trainers or moose feeders into the moose cage, we can create a more
508 complex check:
509 Zoo->deny_access_unless( "/moose_cage", sub {
511 my $c = shift;
512 $c->check_roles( "moose_trainer" ) || $c->check_roles( "moose_feeder" );
513 });
514 The more specific a role, the earlier it will be checked. Let's say
516 moose feeders are now restricted to only the "feed_moose" action, while
517 moose trainers get access everywhere:
518 Zoo->deny_access_unless( "/moose_cage", [qw/moose_trainer/] );
520 Zoo->allow_access_if( "/moose_cage/feed_moose", [qw/moose_feeder/]);
521 When the "feed_moose" action is accessed the second check will be made.
523 If the user is a "moose_feeder", then access will be immediately
524 granted. Otherwise, the next rule in line will be tested - the one
525 checking for a "moose_trainer". If this rule is not satisfied, access
526 will be immediately denied.
527 Rules applied to the same path will be checked in the order they were
529 added.
530 Lastly, handling access denial events is done by creating an
532 "access_denied" private action:
533 sub access_denied : Private {
535 my ( $self, $c, $action ) = @_;
536 }
537 This action works much like auto, in that it is inherited across
539 namespaces (not like object oriented code). This means that the
540 "access_denied" action which is nearest to the action which was blocked
541 will be triggered.
542 If this action does not exist, an error will be thrown, which you can
544 clean up in your "end" private action instead.
545 Also, it's important to note that if you restrict access to "/" then
547 "end", "default", etc. will also be restricted.
548 MyApp->acl_allow_root_internals;
550 will create rules that permit access to "end", "begin", and "auto" in
552 the root of your app (but not in any other controller).
553
555 Models are where application data belongs. Catalyst is extremely
556 flexible with the kind of models that it can use. The recipes here are
557 just the start.
558 Using existing DBIC (etc.) classes with Catalyst
560 Many people have existing Model classes that they would like to use
561 with Catalyst (or, conversely, they want to write Catalyst models that
562 can be used outside of Catalyst, e.g. in a cron job). It's trivial to
563 write a simple component in Catalyst that slurps in an outside Model:
564 package MyApp::Model::DB;
566 use base qw/Catalyst::Model::DBIC::Schema/;
568 __PACKAGE__->config(
570 schema_class => 'Some::DBIC::Schema',
571 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}],
572 );
573 1;
575 and that's it! Now "Some::DBIC::Schema" is part of your Cat app as
577 "MyApp::Model::DB".
578 DBIx::Class as a Catalyst Model
580 See Catalyst::Model::DBIC::Schema.
581 Create accessors to preload static data once per server instance
583 When you have data that you want to load just once from the model at
584 startup, instead of for each request, use mk_group_accessors to create
585 accessors and tie them to resultsets in your package that inherits from
586 DBIx::Class::Schema:
587 package My::Schema;
589 use base qw/DBIx::Class::Schema/;
590 __PACKAGE__->register_class('RESULTSOURCEMONIKER',
591 'My::Schema::RESULTSOURCE');
592 __PACKAGE__->mk_group_accessors('simple' =>
593 qw(ACCESSORNAME1 ACCESSORNAME2 ACCESSORNAMEn));
594 sub connection {
596 my ($self, @rest) = @_;
597 $self->next::method(@rest);
598 # $self is now a live My::Schema object, complete with DB connection
599 $self->ACCESSORNAME1([ $self->resultset('RESULTSOURCEMONIKER')->all ]);
601 $self->ACCESSORNAME2([ $self->resultset('RESULTSOURCEMONIKER')->search({ COLUMN => { '<' => '30' } })->all ]);
602 $self->ACCESSORNAMEn([ $self->resultset('RESULTSOURCEMONIKER')->find(1) ]);
603 }
604 1;
606 and now in the controller, you can now access any of these without a
608 per-request fetch:
609 $c->stash->{something} = $c->model('My::Schema')->schema->ACCESSORNAME;
611 XMLRPC
613 Unlike SOAP, XMLRPC is a very simple (and elegant) web-services
614 protocol, exchanging small XML messages like these:
615 Request:
617 POST /api HTTP/1.1
619 TE: deflate,gzip;q=0.3
620 Connection: TE, close
621 Accept: text/xml
622 Accept: multipart/*
623 Host: 127.0.0.1:3000
624 User-Agent: SOAP::Lite/Perl/0.60
625 Content-Length: 192
626 Content-Type: text/xml
627 <?xml version="1.0" encoding="UTF-8"?>
629 <methodCall>
630 <methodName>add</methodName>
631 <params>
632 <param><value><int>1</int></value></param>
633 <param><value><int>2</int></value></param>
634 </params>
635 </methodCall>
636 Response:
638 Connection: close
640 Date: Tue, 20 Dec 2005 07:45:55 GMT
641 Content-Length: 133
642 Content-Type: text/xml
643 Status: 200
644 X-Catalyst: 5.70
645 <?xml version="1.0" encoding="us-ascii"?>
647 <methodResponse>
648 <params>
649 <param><value><int>3</int></value></param>
650 </params>
651 </methodResponse>
652 Now follow these few steps to implement the application:
654 1. Install Catalyst (5.61 or later), Catalyst::Plugin::XMLRPC (0.06 or
656 later) and SOAP::Lite (for XMLRPCsh.pl).
657 2. Create an application framework:
659 % catalyst.pl MyApp
661 ...
662 % cd MyApp
663 3. Add the XMLRPC plugin to MyApp.pm
665 use Catalyst qw/-Debug Static::Simple XMLRPC/;
667 4. Add an API controller
669 % ./script/myapp_create.pl controller API
671 5. Add a XMLRPC redispatch method and an add method with Remote
673 attribute to lib/MyApp/Controller/API.pm
674 sub default :Path {
676 my ( $self, $c ) = @_;
677 $c->xmlrpc;
678 }
679 sub add : Remote {
681 my ( $self, $c, $a, $b ) = @_;
682 return $a + $b;
683 }
684 The default action is the entry point for each XMLRPC request. It
686 will redispatch every request to methods with Remote attribute in
687 the same class.
688 The "add" method is not a traditional action; it has no private or
690 public path. Only the XMLRPC dispatcher knows it exists.
691 6. That's it! You have built your first web service. Let's test it
693 with XMLRPCsh.pl (part of SOAP::Lite):
694 % ./script/myapp_server.pl
696 ...
697 % XMLRPCsh.pl http://127.0.0.1:3000/api
698 Usage: method[(parameters)]
699 > add( 1, 2 )
700 --- XMLRPC RESULT ---
701 '3'
702 Tip
704 Your return data type is usually auto-detected, but you can easily
706 enforce a specific one.
707 sub add : Remote {
709 my ( $self, $c, $a, $b ) = @_;
710 return RPC::XML::int->new( $a + $b );
711 }
712
714 Views pertain to the display of your application. As with models,
715 Catalyst is uncommonly flexible. The recipes below are just a start.
716 Catalyst::View::TT
718 One of the first things you probably want to do when starting a new
719 Catalyst application is set up your View. Catalyst doesn't care how you
720 display your data; you can choose to generate HTML, PDF files, or plain
721 text if you wanted.
722 Most Catalyst applications use a template system to generate their
724 HTML, and though there are several template systems available, Template
725 Toolkit is probably the most popular.
726 Once again, the Catalyst developers have done all the hard work, and
728 made things easy for the rest of us. Catalyst::View::TT provides the
729 interface to Template Toolkit, and provides Helpers which let us set it
730 up that much more easily.
731 Creating your View
733 Catalyst::View::TT provides two different helpers for us to use: TT and
735 TTSite.
736 TT
738 Create a basic Template Toolkit View using the provided helper script:
740 script/myapp_create.pl view TT TT
742 This will create lib/MyApp/View/MyView.pm, which is going to be pretty
744 empty to start. However, it sets everything up that you need to get
745 started. You can now define which template you want and forward to your
746 view. For instance:
747 sub hello : Local {
749 my ( $self, $c ) = @_;
750 $c->stash->{template} = 'hello.tt';
752 $c->forward( $c->view('TT') );
754 }
755 In practice you wouldn't do the forwarding manually, but would use
757 Catalyst::Action::RenderView.
758 TTSite
760 Although the TT helper does create a functional, working view, you may
762 find yourself having to create the same template files and changing the
763 same options every time you create a new application. The TTSite helper
764 saves us even more time by creating the basic templates and setting
765 some common options for us.
766 Once again, you can use the helper script:
768 script/myapp_create.pl view TT TTSite
770 This time, the helper sets several options for us in the generated
772 View.
773 __PACKAGE__->config({
775 CATALYST_VAR => 'Catalyst',
776 INCLUDE_PATH => [
777 MyApp->path_to( 'root', 'src' ),
778 MyApp->path_to( 'root', 'lib' )
779 ],
780 PRE_PROCESS => 'config/main',
781 WRAPPER => 'site/wrapper',
782 ERROR => 'error.tt2',
783 TIMER => 0
784 });
785 • "INCLUDE_PATH" defines the directories that Template Toolkit should
787 search for the template files.
788 • "PRE_PROCESS" is used to process configuration options which are
790 common to every template file.
791 • "WRAPPER" is a file which is processed with each template, usually
793 used to easily provide a common header and footer for every page.
794 In addition to setting these options, the TTSite helper also created
796 the template and config files for us! In the 'root' directory, you'll
797 notice two new directories: src and lib.
798 Several configuration files in root/lib/config are called by
800 "PRE_PROCESS".
801 The files in root/lib/site are the site-wide templates, called by
803 "WRAPPER", and display the html framework, control the layout, and
804 provide the templates for the header and footer of your page. Using the
805 template organization provided makes it much easier to standardize
806 pages and make changes when they are (inevitably) needed.
807 The template files that you will create for your application will go
809 into root/src, and you don't need to worry about putting the "<html>"
810 or "<head>" sections; just put in the content. The "WRAPPER" will the
811 rest of the page around your template for you.
812 "$c->stash"
814 Of course, having the template system include the header and footer for
816 you isn't all that we want our templates to do. We need to be able to
817 put data into our templates, and have it appear where and how we want
818 it, right? That's where the stash comes in.
819 In our controllers, we can add data to the stash, and then access it
821 from the template. For instance:
822 sub hello : Local {
824 my ( $self, $c ) = @_;
825 $c->stash->{name} = 'Adam';
827 $c->stash->{template} = 'hello.tt';
829 $c->forward( $c->view('TT') );
831 }
832 Then, in hello.tt:
834 <strong>Hello, [% name %]!</strong>
836 When you view this page, it will display "Hello, Adam!"
838 All of the information in your stash is available, by its name/key, in
840 your templates. And your data don't have to be plain, old, boring
841 scalars. You can pass array references and hash references, too.
842 In your controller:
844 sub hello : Local {
846 my ( $self, $c ) = @_;
847 $c->stash->{names} = [ 'Adam', 'Dave', 'John' ];
849 $c->stash->{template} = 'hello.tt';
851 $c->forward( $c->view('TT') );
853 }
854 In hello.tt:
856 [% FOREACH name IN names %]
858 <strong>Hello, [% name %]!</strong><br />
859 [% END %]
860 This allowed us to loop through each item in the arrayref, and display
862 a line for each name that we have.
863 This is the most basic usage, but Template Toolkit is quite powerful,
865 and allows you to truly keep your presentation logic separate from the
866 rest of your application.
867 "$c->uri_for()"
869 One of my favorite things about Catalyst is the ability to move an
871 application around without having to worry that everything is going to
872 break. One of the areas that used to be a problem was with the http
873 links in your template files. For example, suppose you have an
874 application installed at "http://www.domain.com/Calendar". The links
875 point to ""/Calendar"", ""/Calendar/2005"", ""/Calendar/2005/10"", etc.
876 If you move the application to be at
877 "http://www.mydomain.com/Tools/Calendar", then all of those links will
878 suddenly break.
879 That's where "$c->uri_for()" comes in. This function will merge its
881 parameters with either the base location for the app, or its current
882 namespace. Let's take a look at a couple of examples.
883 In your template, you can use the following:
885 <a href="[% c.uri_for('/login') %]">Login Here</a>
887 Although the parameter starts with a forward slash, this is relative to
889 the application root, not the webserver root. This is important to
890 remember. So, if your application is installed at
891 "http://www.domain.com/Calendar", then the link would be
892 "http://www.mydomain.com/Calendar/Login". If you move your application
893 to a different domain or path, then that link will still be correct.
894 Likewise,
896 <a href="[% c.uri_for('2005','10', '24') %]">October, 24 2005</a>
898 The first parameter does NOT have a forward slash, and so it will be
900 relative to the current namespace. If the application is installed at
901 "http://www.domain.com/Calendar". and if the template is called from
902 "MyApp::Controller::Display", then the link would become
903 "http://www.domain.com/Calendar/Display/2005/10/24".
904 If you want to link to a parent uri of your current namespace you can
906 prefix the arguments with multiple '"../"':
907 <a href="[% c.uri_for('../../view', stashed_object.id) %]">User view</a>
909 Once again, this allows you to move your application around without
911 having to worry about broken links. But there's something else, as
912 well. Since the links are generated by "uri_for", you can use the same
913 template file by several different controllers, and each controller
914 will get the links that its supposed to. Since we believe in Don't
915 Repeat Yourself, this is particularly helpful if you have common
916 elements in your site that you want to keep in one file.
917 Further Reading:
919 Catalyst
921 Catalyst::View::TT
923 Template
925 Adding RSS feeds
927 Adding RSS feeds to your Catalyst applications is simple. We'll see two
928 different approaches here, but the basic premise is that you forward to
929 the normal view action first to get the objects, then handle the output
930 differently.
931 Using XML::Feed
933 Assuming we have a "view" action that populates 'entries' with some
935 DBIx::Class iterator, the code would look something like this:
936 sub rss : Local {
938 my ($self,$c) = @_;
939 $c->forward('view'); # get the entries
940 my $feed = XML::Feed->new('RSS');
942 $feed->title( $c->config->{name} . ' RSS Feed' );
943 $feed->link( $c->req->base ); # link to the site.
944 $feed->description('Catalyst advent calendar'); Some description
945 # Process the entries
947 while( my $entry = $c->stash->{entries}->next ) {
948 my $feed_entry = XML::Feed::Entry->new('RSS');
949 $feed_entry->title($entry->title);
950 $feed_entry->link( $c->uri_for($entry->link) );
951 $feed_entry->issued( DateTime->from_epoch(epoch => $entry->created) );
952 $feed->add_entry($feed_entry);
953 }
954 $c->res->body( $feed->as_xml );
955 }
956 With this approach you're pretty sure to get something that validates.
958 Note that for both of the above approaches, you'll need to set the
960 content type like this:
961 $c->res->content_type('application/rss+xml');
963 Final words
965 You could generalize the second variant easily by replacing 'RSS' with
967 a variable, so you can generate Atom feeds with the same code.
968 Now, go ahead and make RSS feeds for all your stuff. The world *needs*
970 updates on your goldfish!
971 Forcing the browser to download content
973 Sometimes you need your application to send content for download. For
974 example, you can generate a comma-separated values (CSV) file for your
975 users to download and import into their spreadsheet program.
976 Let's say you have an "Orders" controller which generates a CSV file in
978 the "export" action (i.e., "http://localhost:3000/orders/export"):
979 sub export : Local Args(0) {
981 my ( $self, $c ) = @_;
982 # In a real application, you'd generate this from the database
984 my $csv = "1,5.99\n2,29.99\n3,3.99\n";
985 $c->res->content_type('text/comma-separated-values');
987 $c->res->body($csv);
988 }
989 Normally the browser uses the last part of the URI to generate a
991 filename for data it cannot display. In this case your browser would
992 likely ask you to save a file named "export".
993 Luckily you can have the browser download the content with a specific
995 filename by setting the "Content-Disposition" header:
996 my $filename = 'Important Orders.csv';
998 $c->res->header('Content-Disposition', qq[attachment; filename="$filename"]);
999 Note the use of quotes around the filename; this ensures that any
1001 spaces in the filename are handled by the browser.
1002 Put this right before calling "$c->res->body" and your browser will
1004 download a file named Important Orders.csv instead of "export".
1005 You can also use this to have the browser download content which it
1007 normally displays, such as JPEG images or even HTML. Just be sure to
1008 set the appropriate content type and disposition.
1009
1011 Controllers are the main point of communication between the web server
1012 and your application. Here we explore some aspects of how they work.
1013 Action Types
1015 Introduction
1016 A Catalyst application is driven by one or more Controller modules.
1018 There are a number of ways that Catalyst can decide which of the
1019 methods in your controller modules it should call. Controller methods
1020 are also called actions, because they determine how your catalyst
1021 application should (re-)act to any given URL. When the application is
1022 started up, catalyst looks at all your actions, and decides which URLs
1023 they map to.
1024 Type attributes
1026 Each action is a normal method in your controller, except that it has
1028 an attribute attached. These can be one of several types.
1029 Assume our Controller module starts with the following package
1031 declaration:
1032 package MyApp::Controller::Buckets;
1034 and we are running our application on localhost, port 3000 (the test
1036 server default).
1037 Path
1039 A Path attribute also takes an argument, this can be either a
1040 relative or an absolute path. A relative path will be relative to
1041 the controller namespace, an absolute path will represent an exact
1042 matching URL.
1043 sub my_handles : Path('handles') { .. }
1045 becomes
1047 http://localhost:3000/buckets/handles
1049 and
1051 sub my_handles : Path('/handles') { .. }
1053 becomes
1055 http://localhost:3000/handles
1057 See also: Catalyst::DispatchType::Path
1059 Local
1061 When using a Local attribute, no parameters are needed, instead,
1062 the name of the action is matched in the URL. The namespaces
1063 created by the name of the controller package is always part of the
1064 URL.
1065 sub my_handles : Local { .. }
1067 becomes
1069 http://localhost:3000/buckets/my_handles
1071 Global
1073 A Global attribute is similar to a Local attribute, except that the
1074 namespace of the controller is ignored, and matching starts at
1075 root.
1076 sub my_handles : Global { .. }
1078 becomes
1080 http://localhost:3000/my_handles
1082 Regex
1084 By now you should have figured that a Regex attribute is just what
1085 it sounds like. This one takes a regular expression, and matches
1086 starting from root. These differ from the rest as they can match
1087 multiple URLs.
1088 sub my_handles : Regex('^handles') { .. }
1090 matches
1092 http://localhost:3000/handles
1094 and
1096 http://localhost:3000/handles_and_other_parts
1098 etc.
1100 See also: Catalyst::DispatchType::Regex
1102 LocalRegex
1104 A LocalRegex is similar to a Regex, except it only matches below
1105 the current controller namespace.
1106 sub my_handles : LocalRegex(^handles') { .. }
1108 matches
1110 http://localhost:3000/buckets/handles
1112 and
1114 http://localhost:3000/buckets/handles_and_other_parts
1116 etc.
1118 Chained
1120 See Catalyst::DispatchType::Chained for a description of how the
1121 chained dispatch type works.
1122 Private
1124 Last but not least, there is the Private attribute, which allows
1125 you to create your own internal actions, which can be forwarded to,
1126 but won't be matched as URLs.
1127 sub my_handles : Private { .. }
1129 becomes nothing at all..
1131 Catalyst also predefines some special Private actions, which you
1133 can override, these are:
1134 default
1136 The default action will be called, if no other matching action
1137 is found. If you don't have one of these in your namespace, or
1138 any sub part of your namespace, you'll get an error page
1139 instead. If you want to find out where it was the user was
1140 trying to go, you can look in the request object using
1141 "$c->req->path".
1142 sub default :Path { .. }
1144 works for all unknown URLs, in this controller namespace, or
1146 every one if put directly into MyApp.pm.
1147 index
1149 The index action is called when someone tries to visit the
1150 exact namespace of your controller. If index, default and
1151 matching Path actions are defined, then index will be used
1152 instead of default and Path.
1153 sub index :Path :Args(0) { .. }
1155 becomes
1157 http://localhost:3000/buckets
1159 begin
1161 The begin action is called at the beginning of every request
1162 involving this namespace directly, before other matching
1163 actions are called. It can be used to set up variables/data for
1164 this particular part of your app. A single begin action is
1165 called, its always the one most relevant to the current
1166 namespace.
1167 sub begin : Private { .. }
1169 is called once when
1171 http://localhost:3000/bucket/(anything)?
1173 is visited.
1175 end Like begin, this action is always called for the namespace it
1177 is in, after every other action has finished. It is commonly
1178 used to forward processing to the View component. A single end
1179 action is called, its always the one most relevant to the
1180 current namespace.
1181 sub end : Private { .. }
1183 is called once after any actions when
1185 http://localhost:3000/bucket/(anything)?
1187 is visited.
1189 auto
1191 Lastly, the auto action is magic in that every auto action in
1192 the chain of paths up to and including the ending namespace,
1193 will be called. (In contrast, only one of the begin/end/default
1194 actions will be called, the relevant one).
1195 package MyApp::Controller::Root;
1197 sub auto : Private { .. }
1198 and
1200 sub auto : Private { .. }
1202 will both be called when visiting
1204 http://localhost:3000/bucket/(anything)?
1206 A word of warning
1208 You can put root actions in your main MyApp.pm file, but this is
1210 deprecated, please put your actions into your Root controller.
1211 Flowchart
1213 A graphical flowchart of how the dispatcher works can be found on the
1215 wiki at
1216 <http://dev.catalystframework.org/attachment/wiki/WikiStart/catalyst-flow.png>.
1217 DRY Controllers with Chained actions
1219 Imagine that you would like the following paths in your application:
1220 /cd/<ID>/track/<ID>
1222 Displays info on a particular track.
1223 In the case of a multi-volume CD, this is the track sequence.
1225 /cd/<ID>/volume/<ID>/track/<ID>
1227 Displays info on a track on a specific volume.
1228 Here is some example code, showing how to do this with chained
1230 controllers:
1231 package CD::Controller;
1233 use base qw/Catalyst::Controller/;
1234 sub root : Chained('/') PathPart('/cd') CaptureArgs(1) {
1236 my ($self, $c, $cd_id) = @_;
1237 $c->stash->{cd_id} = $cd_id;
1238 $c->stash->{cd} = $self->model('CD')->find_by_id($cd_id);
1239 }
1240 sub trackinfo : Chained('track') PathPart('') Args(0) RenderView {
1242 my ($self, $c) = @_;
1243 }
1244 package CD::Controller::ByTrackSeq;
1246 use base qw/CD::Controller/;
1247 sub track : Chained('root') PathPart('track') CaptureArgs(1) {
1249 my ($self, $c, $track_seq) = @_;
1250 $c->stash->{track} = $self->stash->{cd}->find_track_by_seq($track_seq);
1251 }
1252 package CD::Controller::ByTrackVolNo;
1254 use base qw/CD::Controller/;
1255 sub volume : Chained('root') PathPart('volume') CaptureArgs(1) {
1257 my ($self, $c, $volume) = @_;
1258 $c->stash->{volume} = $volume;
1259 }
1260 sub track : Chained('volume') PathPart('track') CaptureArgs(1) {
1262 my ($self, $c, $track_no) = @_;
1263 $c->stash->{track} = $self->stash->{cd}->find_track_by_vol_and_track_no(
1264 $c->stash->{volume}, $track_no
1265 );
1266 }
1267 Note that adding other actions (i.e. chain endpoints) which operate on
1269 a track is simply a matter of adding a new sub to CD::Controller - no
1270 code is duplicated, even though there are two different methods of
1271 looking up a track.
1272 This technique can be expanded as needed to fulfil your requirements -
1274 for example, if you inherit the first action of a chain from a base
1275 class, then mixing in a different base class can be used to duplicate
1276 an entire URL hierarchy at a different point within your application.
1277 Component-based Subrequests
1279 See Catalyst::Plugin::SubRequest.
1280 File uploads
1282 Single file upload with Catalyst
1283 To implement uploads in Catalyst, you need to have a HTML form similar
1285 to this:
1286 <form action="/upload" method="post" enctype="multipart/form-data">
1288 <input type="hidden" name="form_submit" value="yes">
1289 <input type="file" name="my_file">
1290 <input type="submit" value="Send">
1291 </form>
1292 It's very important not to forget "enctype="multipart/form-data"" in
1294 the form.
1295 Catalyst Controller module 'upload' action:
1297 sub upload : Global {
1299 my ($self, $c) = @_;
1300 if ( $c->request->parameters->{form_submit} eq 'yes' ) {
1302 if ( my $upload = $c->request->upload('my_file') ) {
1304 my $filename = $upload->filename;
1306 my $target = "/tmp/upload/$filename";
1307 unless ( $upload->link_to($target) || $upload->copy_to($target) ) {
1309 die( "Failed to copy '$filename' to '$target': $!" );
1310 }
1311 }
1312 }
1313 $c->stash->{template} = 'file_upload.html';
1315 }
1316 Multiple file upload with Catalyst
1318 Code for uploading multiple files from one form needs a few changes:
1320 The form should have this basic structure:
1322 <form action="/upload" method="post" enctype="multipart/form-data">
1324 <input type="hidden" name="form_submit" value="yes">
1325 <input type="file" name="file1" size="50"><br>
1326 <input type="file" name="file2" size="50"><br>
1327 <input type="file" name="file3" size="50"><br>
1328 <input type="submit" value="Send">
1329 </form>
1330 And in the controller:
1332 sub upload : Local {
1334 my ($self, $c) = @_;
1335 if ( $c->request->parameters->{form_submit} eq 'yes' ) {
1337 for my $field ( $c->req->upload ) {
1339 my $upload = $c->req->upload($field);
1341 my $filename = $upload->filename;
1342 my $target = "/tmp/upload/$filename";
1343 unless ( $upload->link_to($target) || $upload->copy_to($target) ) {
1345 die( "Failed to copy '$filename' to '$target': $!" );
1346 }
1347 }
1348 }
1349 $c->stash->{template} = 'file_upload.html';
1351 }
1352 "for my $field ($c->req->upload)" loops automatically over all file
1354 input fields and gets input names. After that is basic file saving
1355 code, just like in single file upload.
1356 Notice: "die"ing might not be what you want to do, when an error
1358 occurs, but it works as an example. A better idea would be to store
1359 error $! in "$c->stash->{error}" and show a custom error template
1360 displaying this message.
1361 For more information about uploads and usable methods look at
1363 Catalyst::Request::Upload and Catalyst::Request.
1364 Forwarding with arguments
1366 Sometimes you want to pass along arguments when forwarding to another
1367 action. As of version 5.30, arguments can be passed in the call to
1368 "forward"; in earlier versions, you can manually set the arguments in
1369 the Catalyst Request object:
1370 # version 5.30 and later:
1372 $c->forward('/wherever', [qw/arg1 arg2 arg3/]);
1373 # pre-5.30
1375 $c->req->args([qw/arg1 arg2 arg3/]);
1376 $c->forward('/wherever');
1377 (See the Catalyst::Manual::Intro Flow_Control section for more
1379 information on passing arguments via "forward".)
1380 Chained dispatch using base classes, and inner packages.
1382 package MyApp::Controller::Base;
1383 use base qw/Catalyst::Controller/;
1384 sub key1 : Chained('/')
1386 Extending RenderView (formerly DefaultEnd)
1388 The recommended approach for an "end" action is to use
1389 Catalyst::Action::RenderView (taking the place of
1390 Catalyst::Plugin::DefaultEnd), which does what you usually need.
1391 However there are times when you need to add a bit to it, but don't
1392 want to write your own "end" action.
1393 You can extend it like this:
1395 To add something to an "end" action that is called before rendering
1397 (this is likely to be what you want), simply place it in the "end"
1398 method:
1399 sub end : ActionClass('RenderView') {
1401 my ( $self, $c ) = @_;
1402 # do stuff here; the RenderView action is called afterwards
1403 }
1404 To add things to an "end" action that are called after rendering, you
1406 can set it up like this:
1407 sub render : ActionClass('RenderView') { }
1409 sub end : Private {
1411 my ( $self, $c ) = @_;
1412 $c->forward('render');
1413 # do stuff here
1414 }
1415 Serving static content
1417 Serving static content in Catalyst used to be somewhat tricky; the use
1418 of Catalyst::Plugin::Static::Simple makes everything much easier. This
1419 plugin will automatically serve your static content during development,
1420 but allows you to easily switch to Apache (or other server) in a
1421 production environment.
1422 Introduction to Static::Simple
1424 Static::Simple is a plugin that will help to serve static content for
1426 your application. By default, it will serve most types of files,
1427 excluding some standard Template Toolkit extensions, out of your root
1428 file directory. All files are served by path, so if images/me.jpg is
1429 requested, then root/images/me.jpg is found and served.
1430 Usage
1432 Using the plugin is as simple as setting your use line in MyApp.pm to
1434 include:
1435 use Catalyst qw/Static::Simple/;
1437 and already files will be served.
1439 Configuring
1441 Static content is best served from a single directory within your root
1443 directory. Having many different directories such as root/css and
1444 root/images requires more code to manage, because you must separately
1445 identify each static directory--if you decide to add a root/js
1446 directory, you'll need to change your code to account for it. In
1447 contrast, keeping all static directories as subdirectories of a main
1448 root/static directory makes things much easier to manage. Here's an
1449 example of a typical root directory structure:
1450 root/
1452 root/content.tt
1453 root/controller/stuff.tt
1454 root/header.tt
1455 root/static/
1456 root/static/css/main.css
1457 root/static/images/logo.jpg
1458 root/static/js/code.js
1459 All static content lives under root/static, with everything else being
1461 Template Toolkit files.
1462 Include Path
1464 You may of course want to change the default locations, and make
1465 Static::Simple look somewhere else, this is as easy as:
1466 MyApp->config(
1468 static => {
1469 include_path => [
1470 MyApp->path_to('/'),
1471 '/path/to/my/files',
1472 ],
1473 },
1474 );
1475 When you override include_path, it will not automatically append
1477 the normal root path, so you need to add it yourself if you still
1478 want it. These will be searched in order given, and the first
1479 matching file served.
1480 Static directories
1482 If you want to force some directories to be only static, you can
1483 set them using paths relative to the root dir, or regular
1484 expressions:
1485 MyApp->config(
1487 static => {
1488 dirs => [
1489 'static',
1490 qr/^(images|css)/,
1491 ],
1492 },
1493 );
1494 File extensions
1496 By default, the following extensions are not served (that is, they
1497 will be processed by Catalyst): tmpl, tt, tt2, html, xhtml. This
1498 list can be replaced easily:
1499 MyApp->config(
1501 static => {
1502 ignore_extensions => [
1503 qw/tmpl tt tt2 html xhtml/
1504 ],
1505 },
1506 );
1507 Ignoring directories
1509 Entire directories can be ignored. If used with include_path,
1510 directories relative to the include_path dirs will also be ignored:
1511 MyApp->config( static => {
1513 ignore_dirs => [ qw/tmpl css/ ],
1514 });
1515 More information
1517 Catalyst::Plugin::Static::Simple
1519 Serving manually with the Static plugin with HTTP::Daemon
1521 (myapp_server.pl)
1522 In some situations you might want to control things more directly,
1524 using Catalyst::Plugin::Static.
1525 In your main application class (MyApp.pm), load the plugin:
1527 use Catalyst qw/-Debug FormValidator Static OtherPlugin/;
1529 You will also need to make sure your end method does not forward static
1531 content to the view, perhaps like this:
1532 sub end : Private {
1534 my ( $self, $c ) = @_;
1535 $c->forward( 'MyApp::View::TT' )
1537 unless ( $c->res->body || !$c->stash->{template} );
1538 }
1539 This code will only forward to the view if a template has been
1541 previously defined by a controller and if there is not already data in
1542 "$c->res->body".
1543 Next, create a controller to handle requests for the /static path. Use
1545 the Helper to save time. This command will create a stub controller as
1546 lib/MyApp/Controller/Static.pm.
1547 $ script/myapp_create.pl controller Static
1549 Edit the file and add the following methods:
1551 # serve all files under /static as static files
1553 sub default : Path('/static') {
1554 my ( $self, $c ) = @_;
1555 # Optional, allow the browser to cache the content
1557 $c->res->headers->header( 'Cache-Control' => 'max-age=86400' );
1558 $c->serve_static; # from Catalyst::Plugin::Static
1560 }
1561 # also handle requests for /favicon.ico
1563 sub favicon : Path('/favicon.ico') {
1564 my ( $self, $c ) = @_;
1565 $c->serve_static;
1567 }
1568 You can also define a different icon for the browser to use instead of
1570 favicon.ico by using this in your HTML header:
1571 <link rel="icon" href="/static/myapp.ico" type="image/x-icon" />
1573 Common problems with the Static plugin
1575 The Static plugin makes use of the "shared-mime-info" package to
1577 automatically determine MIME types. This package is notoriously
1578 difficult to install, especially on win32 and OS X. For OS X the
1579 easiest path might be to install Fink, then use "apt-get install
1580 shared-mime-info". Restart the server, and everything should be fine.
1581 Make sure you are using the latest version (>= 0.16) for best results.
1583 If you are having errors serving CSS files, or if they get served as
1584 text/plain instead of text/css, you may have an outdated shared-mime-
1585 info version. You may also wish to simply use the following code in
1586 your Static controller:
1587 if ($c->req->path =~ /css$/i) {
1589 $c->serve_static( "text/css" );
1590 } else {
1591 $c->serve_static;
1592 }
1593 Serving Static Files with Apache
1595 When using Apache, you can bypass Catalyst and any Static
1597 plugins/controllers controller by intercepting requests for the
1598 root/static path at the server level. All that is required is to define
1599 a DocumentRoot and add a separate Location block for your static
1600 content. Here is a complete config for this application under mod_perl
1601 1.x:
1602 <Perl>
1604 use lib qw(/var/www/MyApp/lib);
1605 </Perl>
1606 PerlModule MyApp
1607 <VirtualHost *>
1609 ServerName myapp.example.com
1610 DocumentRoot /var/www/MyApp/root
1611 <Location />
1612 SetHandler perl-script
1613 PerlHandler MyApp
1614 </Location>
1615 <LocationMatch "/(static|favicon.ico)">
1616 SetHandler default-handler
1617 </LocationMatch>
1618 </VirtualHost>
1619 And here's a simpler example that'll get you started:
1621 Alias /static/ "/my/static/files/"
1623 <Location "/static">
1624 SetHandler none
1625 </Location>
1626 Caching
1628 Catalyst makes it easy to employ several different types of caching to
1629 speed up your applications.
1630 Cache Plugins
1632 There are three wrapper plugins around common CPAN cache modules:
1634 Cache::FastMmap, Cache::FileCache, and Cache::Memcached. These can be
1635 used to cache the result of slow operations.
1636 The Catalyst Advent Calendar uses the FileCache plugin to cache the
1638 rendered XHTML version of the source POD document. This is an ideal
1639 application for a cache because the source document changes
1640 infrequently but may be viewed many times.
1641 use Catalyst qw/Cache::FileCache/;
1643 ...
1645 use File::stat;
1647 sub render_pod : Local {
1648 my ( self, $c ) = @_;
1649 # the cache is keyed on the filename and the modification time
1651 # to check for updates to the file.
1652 my $file = $c->path_to( 'root', '2005', '11.pod' );
1653 my $mtime = ( stat $file )->mtime;
1654 my $cached_pod = $c->cache->get("$file $mtime");
1656 if ( !$cached_pod ) {
1657 $cached_pod = do_slow_pod_rendering();
1658 # cache the result for 12 hours
1659 $c->cache->set( "$file $mtime", $cached_pod, '12h' );
1660 }
1661 $c->stash->{pod} = $cached_pod;
1662 }
1663 We could actually cache the result forever, but using a value such as
1665 12 hours allows old entries to be automatically expired when they are
1666 no longer needed.
1667 Page Caching
1669 Another method of caching is to cache the entire HTML page. While this
1671 is traditionally handled by a frontend proxy server like Squid, the
1672 Catalyst PageCache plugin makes it trivial to cache the entire output
1673 from frequently-used or slow actions.
1674 Many sites have a busy content-filled front page that might look
1676 something like this. It probably takes a while to process, and will do
1677 the exact same thing for every single user who views the page.
1678 sub front_page : Path('/') {
1680 my ( $self, $c ) = @_;
1681 $c->forward( 'get_news_articles' );
1683 $c->forward( 'build_lots_of_boxes' );
1684 $c->forward( 'more_slow_stuff' );
1685 $c->stash->{template} = 'index.tt';
1687 }
1688 We can add the PageCache plugin to speed things up.
1690 use Catalyst qw/Cache::FileCache PageCache/;
1692 sub front_page : Path ('/') {
1694 my ( $self, $c ) = @_;
1695 $c->cache_page( 300 );
1697 # same processing as above
1699 }
1700 Now the entire output of the front page, from <html> to </html>, will
1702 be cached for 5 minutes. After 5 minutes, the next request will
1703 rebuild the page and it will be re-cached.
1704 Note that the page cache is keyed on the page URI plus all parameters,
1706 so requests for / and /?foo=bar will result in different cache items.
1707 Also, only GET requests will be cached by the plugin.
1708 You can even get that frontend Squid proxy to help out by enabling HTTP
1710 headers for the cached page.
1711 MyApp->config(
1713 page_cache => {
1714 set_http_headers => 1,
1715 },
1716 );
1717 This would now set the following headers so proxies and browsers may
1719 cache the content themselves.
1720 Cache-Control: max-age=($expire_time - time)
1722 Expires: $expire_time
1723 Last-Modified: $cache_created_time
1724 Template Caching
1726 Template Toolkit provides support for caching compiled versions of your
1728 templates. To enable this in Catalyst, use the following
1729 configuration. TT will cache compiled templates keyed on the file
1730 mtime, so changes will still be automatically detected.
1731 package MyApp::View::TT;
1733 use strict;
1735 use warnings;
1736 use base 'Catalyst::View::TT';
1737 __PACKAGE__->config(
1739 COMPILE_DIR => '/tmp/template_cache',
1740 );
1741 1;
1743 More Info
1745 See the documentation for each cache plugin for more details and other
1747 available configuration options.
1748 Catalyst::Plugin::Cache::FastMmap Catalyst::Plugin::Cache::FileCache
1750 Catalyst::Plugin::Cache::Memcached Catalyst::Plugin::PageCache "Caching
1751 and Compiling Options" in Template::Manual::Config
1752
1754 Testing is an integral part of the web application development process.
1755 Tests make multi developer teams easier to coordinate, and they help
1756 ensure that there are no nasty surprises after upgrades or alterations.
1757 Testing
1759 Catalyst provides a convenient way of testing your application during
1760 development and before deployment in a real environment.
1761 Catalyst::Test makes it possible to run the same tests both locally
1763 (without an external daemon) and against a remote server via HTTP.
1764 Tests
1766 Let's examine a skeleton application's t/ directory:
1768 mundus:~/MyApp chansen$ ls -l t/
1770 total 24
1771 -rw-r--r-- 1 chansen chansen 95 18 Dec 20:50 01app.t
1772 -rw-r--r-- 1 chansen chansen 190 18 Dec 20:50 02pod.t
1773 -rw-r--r-- 1 chansen chansen 213 18 Dec 20:50 03podcoverage.t
1774 01app.t
1776 Verifies that the application loads, compiles, and returns a
1777 successful response.
1778 02pod.t
1780 Verifies that all POD is free from errors. Only executed if the
1781 "TEST_POD" environment variable is true.
1782 03podcoverage.t
1784 Verifies that all methods/functions have POD coverage. Only
1785 executed if the "TEST_POD" environment variable is true.
1786 Creating tests
1788 mundus:~/MyApp chansen$ cat t/01app.t | perl -ne 'printf( "%2d %s", $., $_ )'
1790 1 use Test::More tests => 2;
1791 2 BEGIN { use_ok( Catalyst::Test, 'MyApp' ) }
1792 3
1793 4 ok( request('/')->is_success );
1794 The first line declares how many tests we are going to run, in this
1796 case two. The second line tests and loads our application in test mode.
1797 The fourth line verifies that our application returns a successful
1798 response.
1799 Catalyst::Test exports two functions, "request" and "get". Each can
1801 take three different arguments:
1802 A string which is a relative or absolute URI.
1804 request('/my/path');
1805 request('http://www.host.com/my/path');
1806 An instance of URI.
1808 request( URI->new('http://www.host.com/my/path') );
1809 An instance of HTTP::Request.
1811 request( HTTP::Request->new( GET => 'http://www.host.com/my/path') );
1812 "request" returns an instance of HTTP::Response and "get" returns the
1814 content (body) of the response.
1815 Running tests locally
1817 mundus:~/MyApp chansen$ CATALYST_DEBUG=0 TEST_POD=1 prove --lib lib/ t/
1819 t/01app............ok
1820 t/02pod............ok
1821 t/03podcoverage....ok
1822 All tests successful.
1823 Files=3, Tests=4, 2 wallclock secs ( 1.60 cusr + 0.36 csys = 1.96 CPU)
1824 "CATALYST_DEBUG=0" ensures that debugging is off; if it's enabled you
1826 will see debug logs between tests.
1827 "TEST_POD=1" enables POD checking and coverage.
1829 "prove" A command-line tool that makes it easy to run tests. You can
1831 find out more about it from the links below.
1832 Running tests remotely
1834 mundus:~/MyApp chansen$ CATALYST_SERVER=http://localhost:3000/ prove --lib lib/ t/01app.t
1836 t/01app....ok
1837 All tests successful.
1838 Files=1, Tests=2, 0 wallclock secs ( 0.40 cusr + 0.01 csys = 0.41 CPU)
1839 "CATALYST_SERVER=http://localhost:3000/" is the absolute deployment URI
1841 of your application. In "CGI" or "FastCGI" it should be the host and
1842 path to the script.
1843 Test::WWW::Mechanize and Catalyst
1845 Be sure to check out Test::WWW::Mechanize::Catalyst. It makes it easy
1847 to test HTML, forms and links. A short example of usage:
1848 use Test::More tests => 6;
1850 BEGIN { use_ok( Test::WWW::Mechanize::Catalyst, 'MyApp' ) }
1851 my $mech = Test::WWW::Mechanize::Catalyst->new;
1853 $mech->get_ok("http://localhost/", 'Got index page');
1854 $mech->title_like( qr/^MyApp on Catalyst/, 'Got right index title' );
1855 ok( $mech->find_link( text_regex => qr/^Wiki/i ), 'Found link to Wiki' );
1856 ok( $mech->find_link( text_regex => qr/^Mailing-List/i ), 'Found link to Mailing-List' );
1857 ok( $mech->find_link( text_regex => qr/^IRC channel/i ), 'Found link to IRC channel' );
1858 Further Reading
1860 • Catalyst::Test
1862 • Test::WWW::Mechanize::Catalyst
1864 • Test::WWW::Mechanize
1866 • WWW::Mechanize
1868 • LWP::UserAgent
1870 • HTML::Form
1872 • HTTP::Message
1874 • HTTP::Request
1876 • HTTP::Request::Common
1878 • HTTP::Response
1880 • HTTP::Status
1882 • URI
1884 • Test::More
1886 • Test::Pod
1888 • Test::Pod::Coverage
1890 • prove (Test::Harness)
1892 More Information
1894 • Catalyst::Plugin::Authorization::Roles
1896 • Catalyst::Plugin::Authorization::ACL
1898
1900 Catalyst Contributors, see Catalyst.pm
1901
1903 This library is free software. You can redistribute it and/or modify it
1904 under the same terms as Perl itself.
1905perl v5.36.0 2023-01-20 Catalyst::Manual::Cookbook(3)
