From: Marcus Ramberg Date: Thu, 7 Apr 2005 14:40:03 +0000 (+0000) Subject: revised documentation for 5.0 X-Git-Tag: 5.7099_04~1593 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=61b1e958102e2371a79e07a7e2cdbb371797d202 revised documentation for 5.0 Made abstract process method die. --- diff --git a/lib/Catalyst.pm b/lib/Catalyst.pm index 2bba938..d198446 100644 --- a/lib/Catalyst.pm +++ b/lib/Catalyst.pm @@ -237,8 +237,21 @@ Mailing-Lists: =head1 SEE ALSO -L, L, L, -L, L +=over 4 + +=item L - The Catalyst Manual + +=item L - Core Engine + +=item L - The Log Class. + +=item L - The Request Object + +=item L - The Response Object + +=item L - The test suite. + +=back =head1 AUTHOR diff --git a/lib/Catalyst/Base.pm b/lib/Catalyst/Base.pm index a2710e3..1e1d585 100644 --- a/lib/Catalyst/Base.pm +++ b/lib/Catalyst/Base.pm @@ -7,6 +7,7 @@ use NEXT; __PACKAGE__->mk_classdata($_) for qw/_cache _config/; __PACKAGE__->_cache( [] ); +# note - see attributes(3pm) sub MODIFY_CODE_ATTRIBUTES { my ( $class, $code, @attrs ) = @_; push @{ $class->_cache }, [ $code, [@attrs] ]; @@ -40,7 +41,6 @@ Catalyst::Base - Catalyst Universal Base Class # Methods can be a request step $c->forward(qw/MyApp::Model::Something forward_to_me/); - MyApp->action( 'index.html' => \&MyApp::Model::Something::forward_to_me ); # Or just methods print $c->comp('MyApp::Model::Something')->test; @@ -95,7 +95,7 @@ sub config { =cut -sub process { 1 } +sub process { die __PACKAGE__." did not override process."; } =back @@ -106,6 +106,7 @@ L. =head1 AUTHOR Sebastian Riedel, C +Marcus Ramberg, C =head1 COPYRIGHT diff --git a/lib/Catalyst/Engine.pm b/lib/Catalyst/Engine.pm index b7d525e..57e73ee 100644 --- a/lib/Catalyst/Engine.pm +++ b/lib/Catalyst/Engine.pm @@ -47,6 +47,9 @@ See L. =head1 DESCRIPTION +This is the core of catalyst. The various drivers are subclasses +of this class. + =head1 METHODS =over 4 @@ -71,6 +74,8 @@ sub benchmark { =item $c->comp($name) +Shortcut for $c->component + =item $c->component($name) Get a component object by name. @@ -218,7 +223,8 @@ sub execute { =item $c->finalize -Finalize request. +Finalize request. This function can typically be overloaded with +NEXT by plugins that need to do something at the end of the request. =cut @@ -276,7 +282,8 @@ sub finalize_cookies { =item $c->finalize_error -Finalize error. +This is the default error screen displayed from finalize. Override +with your own output if you need something special. =cut @@ -379,7 +386,7 @@ sub finalize_error { =item $c->finalize_headers -Finalize headers. +Finalize headers. Null action by default. =cut @@ -387,7 +394,7 @@ sub finalize_headers { } =item $c->finalize_output -Finalize output. +Finalize output. Null action by default =cut @@ -399,6 +406,7 @@ Forward processing to a private action or a method from a class. If you define a class without method it will default to process(). $c->forward('/foo'); + $c->forward('/controller/action'); $c->forward('index'); $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/); $c->forward('MyApp::View::TT'); @@ -508,7 +516,7 @@ sub get_action { =item $c->handler( $class, $r ) -Handles the request. +The main request handler. =cut @@ -616,7 +624,7 @@ sub prepare { =item $c->prepare_action -Prepare action. +Prepare action for processing. =cut @@ -661,7 +669,7 @@ sub prepare_action { =item $c->prepare_connection -Prepare connection. +Prepare connection. Null action by default =cut @@ -669,7 +677,7 @@ sub prepare_connection { } =item $c->prepare_cookies -Prepare cookies. +Prepare cookies. =cut @@ -683,7 +691,7 @@ sub prepare_cookies { =item $c->prepare_headers -Prepare headers. +Prepare headers. Null action by default =cut @@ -691,7 +699,7 @@ sub prepare_headers { } =item $c->prepare_parameters -Prepare parameters. +Prepare parameters. Null action by default =cut @@ -699,7 +707,7 @@ sub prepare_parameters { } =item $c->prepare_path -Prepare path and base. +Prepare path and base. Null action by default =cut @@ -707,7 +715,7 @@ sub prepare_path { } =item $c->prepare_request -Prepare the engine request. +Prepare the engine request. Null action by default =cut @@ -715,7 +723,7 @@ sub prepare_request { } =item $c->prepare_uploads -Prepare uploads. +Prepare uploads. Null action by default =cut @@ -723,31 +731,36 @@ sub prepare_uploads { } =item $c->run -Starts the engine. +Starts the engine. Null action by default =cut sub run { } -=item $c->request - =item $c->req -Returns a C object. +Shortcut for $c->request - my $req = $c->req; +=item $c->request -=item $c->response +Returns a C object. + + my $req = $c->request; =item $c->res +Shortcut for $c->response + +=item $c->response + Returns a C object. my $res = $c->res; =item $c->set_action( $action, $code, $namespace, $attrs ) -Set an action in a given namespace. +Set an action in a given namespace. Used to defined the actions +in the attribute handlers. =cut @@ -821,7 +834,7 @@ sub set_action { =item $class->setup -Setup. +Setup the application. required to initialize actions. MyApp->setup; @@ -873,7 +886,7 @@ sub setup_actions { =item $class->setup_components -Setup components. +Setup all the components in YourApp::(M|V|C|Model|View|Controller)::* =cut @@ -964,7 +977,8 @@ Contains the return value of the last executed action. =item $c->stash -Returns a hashref containing all your data. +The stash is a global hash which can be used to pass around data +between your components. $c->stash->{foo} ||= 'yada'; print $c->stash->{foo}; @@ -1001,9 +1015,22 @@ sub _class2prefix { =back +=head1 SEE ALSO + +=over 4 + +=item L - Apache Engines for MP1/2 +=item L - CGI Engine +=item L - FastCGI Engine +=item L - Standalone Catalyst Server +=item L - Engine for testing + +=back + =head1 AUTHOR Sebastian Riedel, C +Marcus Ramberg, C =head1 COPYRIGHT diff --git a/lib/Catalyst/Log.pm b/lib/Catalyst/Log.pm index 833087b..f2a6aee 100644 --- a/lib/Catalyst/Log.pm +++ b/lib/Catalyst/Log.pm @@ -22,8 +22,10 @@ See L. =head1 DESCRIPTION -This module provides the default, simple logging functionality for Catalyst. -If you want something different set C<$c->log> in your application module, e.g.: +This module provides the default, simple logging functionality for +Catalyst. +If you want something different set C<$c->log> in your application +module, e.g.: $c->log( MyLogger->new ); @@ -76,19 +78,11 @@ sub _format { =back -=head1 DEPRECATED METHODS - -=over 4 - -=item $log->dump($reference) - -Logs a Data::Dumper of reference. - =cut -sub dump { shift->_format( 'dump', Dumper( $_[0] ) ) } +# Private - Logs a Data::Dumper of reference. +sub _dump { shift->_format( 'dump', Dumper( $_[0] ) ) } -=back =head1 SEE ALSO @@ -97,11 +91,12 @@ L. =head1 AUTHOR Sebastian Riedel, C +Marcus Ramberg, C =head1 COPYRIGHT -This program is free software, you can redistribute it and/or modify it under -the same terms as Perl itself. +This program is free software, you can redistribute it and/or modify +it under the same terms as Perl itself. =cut diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod index d4641fc..68d66d8 100644 --- a/lib/Catalyst/Manual/Cookbook.pod +++ b/lib/Catalyst/Manual/Cookbook.pod @@ -13,12 +13,10 @@ Yummy code like your mum used to bake! You can force Catalyst to display the debug screen at the end of the request by placing a die() call in the _end action. - __PACKAGE__->action( - '!end' => sub { - my ( $self, $c ) = @_; - die "testing"; - } - ); + sub end : Private { + my ( $self, $c ) = @_; + die "testing"; + } If you're tired of removing and adding this all the time, you can easily add a condition. for example: @@ -60,44 +58,17 @@ Just use Catalyst::Model::CDBI::CRUD as baseclass. root => '/home/joeuser/myapp/root' ); - __PACKAGE__->action( - 'table' => sub { - my ( $self, $c ) = @_; - $c->form( optional => [ MyApp::Model::CDBI::Table->columns ] ); - $c->forward('MyApp::Model::CDBI::Table'); - } - ); + sub my_table : Global { + my ( $self, $c ) = @_; + $c->form( optional => [ MyApp::Model::CDBI::Table->columns ] ); + $c->forward('MyApp::Model::CDBI::Table'); + } 1; Modify the $c->form() parameters to match your needs, and don't forget to copy the templates. ;) -=head2 Serving static files and CSS as text/css - -If you want to serve static content (like images, txt or CSS) via Catalyst, -then all you need is the plugin Catalyst::Plugin::Static as well as a small -regex to set the MIME type for CSS to text/css. - - # lib/MyApp.pm - package MyApp; - - use strict; - use Catalyst qw/-Debug Static/; - - __PACKAGE__->action( - - '!default' => sub { - my ( $self, $c ) = @_; - $c->serve_static; - }, - - '/^.*\.css$/' => sub { - my ( $self, $c ) = @_; - $c->serve_static('text/css'); - }, - ); - =head2 Uploads with Catalyst To implement uploads in Catalyst you need to have a HTML form similiar to @@ -114,9 +85,7 @@ if it's not there, uploads just don't work. Catalyst Controller module 'upload' action: - MyApp->action( - - 'upload' => sub { + sub upload : Global { my ($self, $c) = @_; if ($c->req->parameters->{form_submit} eq 'yes') { my $filename = $c->req->parameters->{my_file}; @@ -132,8 +101,7 @@ Catalyst Controller module 'upload' action: } $c->stash->{template} = 'upload_form.tt'; $c->forward('MyApp::V::View'); - }, - ); + } If you want to upload bigger files than 1MB, then just add to your Controller module: @@ -177,25 +145,26 @@ We'll discuss the first variant for now: To log in a user you might use a action like this: - '?login' => sub { + sub 'login' : Local { my ($self, $c) = @_; if ($c->req->params->{username}) { $c->session_login($c->req->params->{username}, - $c->req->params->{password} ); + $c->req->params->{password} ); if ($c->req->{user}) { $c->forward('?restricted_area'); } } - }, + } $c->req->params->{username} and $c->req->params->{password} are html -form parameters from a login form. If login succeeds, then $c->req->{user} -contains the username of the authenticated user. +form parameters from a login form. If login succeeds, then +$c->req->{user} contains the username of the authenticated user. -If you want to remember the users login status inbetween further requests, -then just use the $c->session_login method, Catalyst will create a session -id, session cookie and automatically append session id to all urls. So -all you have to do, is just check $c->req->{user} where needed. +If you want to remember the users login status inbetween further +requests, then just use the $c->session_login method, Catalyst will +create a session id, session cookie and automatically append session +id to all urls. So all you have to do, is just check $c->req->{user} +where needed. To log out user, just call $c->session_logout. @@ -227,39 +196,40 @@ CREATE TABLE user_roles ( foreign key(role_id) references roles(role_id) ); -The 'roles' table is a list of role names and the 'user_role' table is used for -the user -> role lookup. +The 'roles' table is a list of role names and the 'user_role' table is +used for the user -> role lookup. -Now if a logged in user wants to see a location which is allowed only for -people with 'admin' role then in you controller you can check it with: +Now if a logged in user wants to see a location which is allowed only +for people with 'admin' role then in you controller you can check it +with: - '?add' => sub { + sub add : Local { my ($self, $c) = @_; if ($c->roles(qw/admin/)) { $c->req->output("Your account has the role 'admin.'"); } else { $c->req->output("You're not allowed to be here"); } - }, + } One thing you might need is to forward non-authenticated users to login form, if they try to access restricted areas. If you want to do this controller-wide (if you have one controller for admin section) then it's best to add user check to '!begin' action: - '!begin' => sub { + sub begin : Private { my ($self, $c) = @_; unless ($c->req->{user}) { $c->req->action(undef); ## notice this!! $c->forward('?login'); } - }, + } Pay attention to $c->req->action(undef). This is needed, because of the way $c->forward works - forward to login gets called, but after that -Catalyst executes anyway the action defined in the uri (eg. if you tried to -watch /add, then first '!begin' forwards to '?login', but after that -anyway '?add' is executed). So $c->req->action(undef) undefines any +Catalyst executes anyway the action defined in the uri (eg. if you +tried to watch /add, then first 'begin' forwards to 'login', but after +that anyway 'add' is executed). So $c->req->action(undef) undefines any actions that were to be called and forwards user where we want him/her to be. @@ -269,20 +239,20 @@ And this is all you need to do, isn't Catalyst wonderful? =head2 How to use Catalyst without mod_perl Catalyst applications give optimum performance when run under mod_perl. -However sometimes mod_perl is not an option, and running under CGI is just too -slow. There are two alternatives to mod_perl that give reasonable -performance: FastCGI and PersistentPerl. +However sometimes mod_perl is not an option, and running under CGI is +just too slow. There are two alternatives to mod_perl that give +reasonable performance: FastCGI and PersistentPerl. B -To quote from L: "FastCGI is a language independent, -scalable, extension to CGI that provides high performance without the -limitations of specific server APIs." Web server support is provided for -Apache in the form of C and there is Perl support in the C -module. To convert a CGI Catalyst application to FastCGI one needs to -initialize an C object and loop while the C method -returns zero. The following code shows how it is done - and it also works as -a normal, single-shot CGI script. +To quote from L: "FastCGI is a language +independent, scalable, extension to CGI that provides high performance +without the limitations of specific server APIs." Web server support +is provided for Apache in the form of C and there is Perl +support in the C module. To convert a CGI Catalyst application +to FastCGI one needs to initialize an C object and loop +while the C method returns zero. The following code shows how +it is done - and it also works as a normal, single-shot CGI script. #!/usr/bin/perl use strict; @@ -294,17 +264,21 @@ a normal, single-shot CGI script. MyApp->run; } -Any initialization code should be included outside the request-accept loop. +Any initialization code should be included outside the request-accept +loop. There is one little complication, which is that Crun> outputs a -complete HTTP response including the status line (e.g.: "C"). -FastCGI just wants a set of headers, so the sample code captures the output -and drops the first line if it is an HTTP status line (note: this may change). - -The Apache C module is provided by a number of Linux distros and -is straightforward to compile for most Unix-like systems. The module provides -a FastCGI Process Manager, which manages FastCGI scripts. You configure your -script as a FastCGI script with the following Apache configuration directives: +complete HTTP response including the status line (e.g.: +"C"). +FastCGI just wants a set of headers, so the sample code captures the +output and drops the first line if it is an HTTP status line (note: +this may change). + +The Apache C module is provided by a number of Linux +distros and is straightforward to compile for most Unix-like systems. +The module provides a FastCGI Process Manager, which manages FastCGI +scripts. You configure your script as a FastCGI script with the +following Apache configuration directives: AddHandler fastcgi-script fcgi @@ -321,26 +295,27 @@ C provides a number of options for controlling the FastCGI scripts spawned; it also allows scripts to be run to handle the authentication, authorization and access check phases. -For more information see the FastCGI documentation, the C module and -L. +For more information see the FastCGI documentation, the C module +and L. B -PersistentPerl (previously known as C) is a persistent Perl -interpreter. After the script is initially run, instead of exiting, the perl -interpreter is kept running. During subsequent runs, this interpreter is used -to handle new executions instead of starting a new perl interpreter each -time. A very fast frontend program contacts the persistent Perl process, which -is usually already running, to do the work and return the results. -PersistentPerl can be used to speed up perl CGI scripts. It also provides an -Apache module so that scripts can be run without the overhead of doing a -fork/exec for each request. +PersistentPerl (previously known as C) is a persistent +Perl interpreter. After the script is initially run, instead of +exiting, the perl interpreter is kept running. During subsequent runs, +this interpreter is used to handle new executions instead of starting +a new perl interpreter each time. A very fast frontend program contacts +the persistent Perl process, which is usually already running, to do +the work and return the results. +PersistentPerl can be used to speed up perl CGI scripts. It also +provides an Apache module so that scripts can be run without the +overhead of doing a fork/exec for each request. -The code for PersistentPerl is simpler than for FastCGI; rather than waiting -in an accept loop the script runs to completion, however variables are not -reinitialized on subsequent runs but maintain their values from the previous -run. +The code for PersistentPerl is simpler than for FastCGI; rather than +waiting in an accept loop the script runs to completion, however +variables are not reinitialized on subsequent runs but maintain their +values from the previous run. #!/usr/bin/perperl @@ -366,8 +341,9 @@ For more information see the C documentation. Sebastian Riedel, C Danijel Milicevic C Viljo Marrandi C +Marcus Ramberg C =head1 COPYRIGHT -This program is free software, you can redistribute it and/or modify it under -the same terms as Perl itself. +This program is free software, you can redistribute it and/or modify it +under the same terms as Perl itself. diff --git a/lib/Catalyst/Manual/Tutorial.pod b/lib/Catalyst/Manual/Tutorial.pod index dea503e..eb1af71 100644 --- a/lib/Catalyst/Manual/Tutorial.pod +++ b/lib/Catalyst/Manual/Tutorial.pod @@ -6,26 +6,24 @@ Catalyst::Manual::Tutorial - Getting started with Catalyst This document aims to get you up and running with Catalyst. -NOTE: THIS DOCUMENT IS STILL VERY MUCH IN AN EARLY DRAFT STATE. SEE THE NOTES -AT THE BOTTOM OF THE DOCUMENT. - - +NOTE: THIS DOCUMENT IS STILL VERY MUCH IN AN EARLY DRAFT STATE. SEE +THE NOTES AT THE BOTTOM OF THE DOCUMENT. =head2 Installation -The first step is to install Catalyst, and the simplest way to do this is to -install the Catalyst bundle from CPAN: +The first step is to install Catalyst, and the simplest way to do this +is to install the Catalyst bundle from CPAN: $ perl -MCPAN -e 'install Bundle::Catalyst' -This will retrieve Catalyst and a number of useful extensions and install them -for you. +This will retrieve Catalyst and a number of useful extensions and +install them for you. =head2 Setting up your application -Catalyst includes a helper script, C, that will set up a skeleton -application for you: +Catalyst includes a helper script, C, that will set up a +skeleton application for you: $ catalyst.pl My::App created "My-App" @@ -53,7 +51,8 @@ application for you: created "My-App/script/test.pl" created "My-App/script/create.pl" -This creates the directory structure shown, populated with skeleton files. +This creates the directory structure shown, populated with skeleton +files. @@ -65,18 +64,24 @@ catalyst provides: $ cd My-App $ script/server.pl [...] [catalyst] [debug] Debug messages enabled - [...] [catalyst] [debug] Loaded engine "Catalyst::Engine::CGI" - [...] [catalyst] [debug] Initialized components "" - [...] [catalyst] [info] My::App powered by Catalyst 4.26 - [...] [catalyst] [debug] "My::App" defined "!default" as "CODE(0x83fd570)" + [...] [catalyst] [debug] Loaded engine "Catalyst::Engine::HTTP" + [...] [catalyst] [debug] Loaded private actions + .=----------------------+----------------------+---------------=. + | Private | Class | Code | + |=----------------------+----------------------+---------------=| + | /default | MyApp | CODE(0x86f08ac | + '=----------------------+----------------------+---------------=' + "My::App" defined "!default" as "CODE(0x83fd570)" + [...] [catalyst] [info] My::App powered by Catalyst 5.00 You can connect to your server at http://localhost:3000 -(Note that each line logged by Catalyst includes a timestamp, which has been -replaced here with "C<...>" so that the text fits onto the lines.) +(Note that each line logged by Catalyst includes a timestamp, which has +been replaced here with "C<...>" so that the text fits onto the lines.) -The server is now waiting for you to make requests of it. Try using telnet to -manually make a simple GET request of the server (when telnet responds with -"Escape character is '^]'.", type "GET / HTTP/1.0" and hit return twice): +The server is now waiting for you to make requests of it. Try using +telnet to manually make a simple GET request of the server (when +telnet responds with "Escape character is '^]'.", type "GET / HTTP/1.0" +and hit return twice): $ telnet localhost 3000 Trying 127.0.0.1... @@ -85,10 +90,10 @@ manually make a simple GET request of the server (when telnet responds with GET / HTTP/1.0 HTTP/1.0 200 - Server: Catalyst/4.26 + Server: Catalyst/5.00 Status: 200 Date: Sun, 20 Mar 2005 12:31:55 GMT - X-catalyst: 4.26 + X-catalyst: 5.00 Content-length: 40 Content-Type: text/html; charset=ISO-8859-1 @@ -101,10 +106,13 @@ More trace messages will appear in the original terminal window: [...] [catalyst] [debug] ******************************** [...] [catalyst] [debug] * Request 1 (0.027/s) [9818] [...] [catalyst] [debug] ******************************** - [...] [catalyst] [debug] "GET" request for "" - [...] [catalyst] [debug] Using default action - [...] [catalyst] [info] Processing "!default" took 0.000033s + [...] [catalyst] [debug] "GET" request for "" from localhost [...] [catalyst] [info] Request took 0.051399s (19.456/s) + .=--------------------------------------------------+----------=. + | Action | Time | + |=--------------------------------------------------+----------=| + | /default | 0.000026s | + '=--------------------------------------------------+----------=' The server will continue running until you interrupt it. @@ -114,11 +122,11 @@ helper script, C