X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=README;h=b8f4f88f68782b702b8c12f9de229782bed570e4;hp=8ead33a142518aa1df20639e435ee196f4659533;hb=24d0c6d2eca02cc36ceae9e7fc4747b0150e8bcd;hpb=fbcc39ad23f2bbecf5d84c9ba581e6af86fcd460 diff --git a/README b/README index 8ead33a..b8f4f88 100644 --- a/README +++ b/README @@ -4,42 +4,83 @@ NAME SYNOPSIS # use the helper to start a new application catalyst.pl MyApp - cd MyApp # add models, views, controllers - script/myapp_create.pl model Something - script/myapp_create.pl view Stuff - script/myapp_create.pl controller Yada + script/myapp_create.pl model Database DBIC dbi:SQLite:/path/to/db + script/myapp_create.pl view TT TT + script/myapp_create.pl controller Search - # built in testserver + # built in testserver -- use -r to restart automatically on changes script/myapp_server.pl - # command line interface + # command line testing interface script/myapp_test.pl /yada - use Catalyst; - - use Catalyst qw/My::Module My::OtherModule/; - - use Catalyst '-Debug'; - - use Catalyst qw/-Debug -Engine=CGI/; - - sub default : Private { $_[1]->res->output('Hello') } ); + ### in MyApp.pm + use Catalyst qw/-Debug/; # include plugins here as well + + sub foo : Global { # called for /foo, /foo/1, /foo/1/2, etc. + my ( $self, $c, @args ) = @_; # args are qw/on you/ for /foo/on/you + $c->stash->{template} = 'foo.tt'; + # lookup something from db -- stash vars are passed to TT + $c->stash->{data} = MyApp::Model::Database::Foo->search; + if ( $c->req->params->{bar} ) { # access GET or POST parameters + $c->forward( 'bar' ); # process another action + # do something else after forward returns + } + } + + # The foo.tt TT template can easily use the stash data from the database + [% WHILE (item = data.next) %] + [% item.foo %] + [% END %] + + # called for /bar/of/soap, /bar/of/soap/10, etc. + sub bar : Path('/bar/of/soap') { ... } - sub index : Path('/index.html') { + # called for all actions, from the top-most controller inwards + sub auto : Private { + my ( $self, $c ) = @_; + if ( !$c->user ) { + $c->res->redirect( '/login' ); # require login + return 0; # abort request and go immediately to end() + } + return 1; + } + + # called after the main action is finished + sub end : Private { my ( $self, $c ) = @_; - $c->res->output('Hello'); - $c->forward('foo'); + if ( scalar @{ $c->error } ) { ... } # handle errors + return if $c->res->body; # already have a response + $c->forward( 'MyApp::View::TT' ); # render template } - sub product : Regex('^product[_]*(\d*).html$') { + ### in MyApp/Controller/Foo.pm + # called for /foo/bar + sub bar : Local { ... } + + # called for /blargle + sub blargle : Global { ... } + + # an index action matches /foo, but not /foo/1, etc. + sub index : Private { ... } + + ### in MyApp/Controller/Foo/Bar.pm + # called for /foo/bar/baz + sub baz : Local { ... } + + # first MyApp auto is called, then Foo auto, then this + sub auto : Private { ... } + + # powerful regular expression paths are also possible + sub details : Regex('^product/(\w+)/details$') { my ( $self, $c ) = @_; - $c->stash->{template} = 'product.tt'; - $c->stash->{product} = $c->req->snippets->[0]; + # extract the (\w+) from the URI + my $product = $c->req->snippets->[0]; } - See also Catalyst::Manual::Intro + See Catalyst::Manual::Intro for additional information. DESCRIPTION The key concept of Catalyst is DRY (Don't Repeat Yourself). @@ -48,11 +89,11 @@ DESCRIPTION Catalyst plugins can be loaded by naming them as arguments to the "use Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the - plugin name, so "Catalyst::Plugin::My::Module" becomes "My::Module". + plugin name, i.e., "Catalyst::Plugin::My::Module" becomes "My::Module". - use Catalyst 'My::Module'; + use Catalyst qw/My::Module/; - Special flags like -Debug and -Engine can also be specifed as arguments + Special flags like -Debug and -Engine can also be specified as arguments when Catalyst is loaded: use Catalyst qw/-Debug My::Module/; @@ -63,70 +104,51 @@ DESCRIPTION The following flags are supported: -Debug - enables debug output, i.e.: - - use Catalyst '-Debug'; - - this is equivalent to: - - use Catalyst; - sub debug { 1 } - - -Dispatcher - Force Catalyst to use a specific dispatcher. + Enables debug output. -Engine - Force Catalyst to use a specific engine. Omit the + Forces Catalyst to use a specific engine. Omit the "Catalyst::Engine::" prefix of the engine name, i.e.: - use Catalyst '-Engine=CGI'; + use Catalyst qw/-Engine=CGI/; -Home - Force Catalyst to use a specific home directory. + Forces Catalyst to use a specific home directory. -Log - Specify log level. + Specifies log level. METHODS - $c->comp($name) - $c->component($name) - Get a component object by name. - - $c->comp('MyApp::Model::MyModel')->do_stuff; - - config - Returns a hashref containing your applications settings. - - debug - Overload to enable debug messages. + Information about the current request + $c->action + Returns a Catalyst::Action object for the current action, which + stringifies to the action name. - $c->detach( $command [, \@arguments ] ) - Like "forward" but doesn't return. + $c->namespace + Returns the namespace of the current action, i.e., the uri prefix + corresponding to the controller of the current action. - $c->dispatcher - Contains the dispatcher instance. Stringifies to class. + $c->request + $c->req + Returns the current Catalyst::Request object. - $c->forward( $command [, \@arguments ] ) - Forward processing to a private action or a method from a class. If - you define a class without method it will default to process(). also - takes an optional arrayref containing arguments to be passed to the - new function. $c->req->args will be reset upon returning from the - function. + Processing and response to the current request + $c->forward( $action [, \@arguments ] ) + $c->forward( $class, $method, [, \@arguments ] ) + Forwards processing to a private action. If you give a class name + but no method, process() is called. You may also optionally pass + arguments in an arrayref. The action will receive the arguments in + @_ and $c->req->args. Upon returning from the function, + $c->req->args will be restored to the previous values. $c->forward('/foo'); $c->forward('index'); $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/); $c->forward('MyApp::View::TT'); - $c->setup - Setup. - - $c->setup; - - $c->uri_for($path) - Merges path with $c->request->base for absolute uri's and with - $c->request->match for relative uri's, then returns a normalized URI - object. + $c->detach( $action [, \@arguments ] ) + $c->detach( $class, $method, [, \@arguments ] ) + The same as "forward", but doesn't return. $c->error $c->error($error, ...) @@ -139,147 +161,239 @@ METHODS $c->error('Something bad happened'); + Clear errors. + + $c->error(0); + + $c->response + $c->res + Returns the current Catalyst::Response object. + + $c->stash + Returns a hashref to the stash, which may be used to store data and + pass it between components. You can also set hash keys by passing + arguments. The stash is automatically sent to the view. + + $c->stash->{foo} = $bar; + $c->stash( { moose => 'majestic', qux => 0 } ); + $c->stash( bar => 1, gorch => 2 ); # equivalent to passing a hashref + + # stash is automatically passed to the view for use in a template + $c->forward( 'MyApp::V::TT' ); + + $c->state + Contains the return value of the last executed action. + + Component Accessors + $c->comp($name) + $c->component($name) + Gets a component object by name. This method is no longer + recommended. $c->controller, $c->model, and $c->view should be used + instead. + + $c->controller($name) + Gets a Catalyst::Controller instance by name. + + $c->controller('Foo')->do_stuff; + + $c->model($name) + Gets a Catalyst::Model instance by name. + + $c->model('Foo')->do_stuff; + + $c->view($name) + Gets a Catalyst::View instance by name. + + $c->view('Foo')->do_stuff; + + Class data and helper classes + $c->config + Returns or takes a hashref containing the application's + configuration. + + __PACKAGE__->config({ db => 'dsn:SQLite:foo.db' }); + + $c->debug + Overload to enable debug messages (same as -Debug option). + + $c->dispatcher + Returns the dispatcher instance. Stringifies to class name. + $c->engine - Contains the engine instance. Stringifies to the class. + Returns the engine instance. Stringifies to the class name. $c->log - Contains the logging object. Unless it is already set Catalyst sets - this up with a "Catalyst::Log" object. To use your own log class: + Returns the logging object instance. Unless it is already set, + Catalyst sets this up with a Catalyst::Log object. To use your own + log class: $c->log( MyLogger->new ); - $c->log->info("now logging with my own logger!"); + $c->log->info( 'now logging with my own logger!' ); Your log class should implement the methods described in the - "Catalyst::Log" man page. + Catalyst::Log man page. - $c->plugin( $name, $class, @args ) - Instant plugins for Catalyst. Classdata accessor/mutator will be - created, class loaded and instantiated. + Utility methods + $c->path_to(@path) + Merges @path with $c->config->{home} and returns a Path::Class + object. - MyApp->plugin( 'prototype', 'HTML::Prototype' ); + For example: - $c->prototype->define_javascript_functions; + $c->path_to( 'db', 'sqlite.db' ); - $c->request - $c->req - Returns a "Catalyst::Request" object. + $c->plugin( $name, $class, @args ) + Helper method for plugins. It creates a classdata accessor/mutator + and loads and instantiates the given class. - my $req = $c->req; + MyApp->plugin( 'prototype', 'HTML::Prototype' ); - $c->response - $c->res - Returns a "Catalyst::Response" object. + $c->prototype->define_javascript_functions; - my $res = $c->res; + MyApp->setup + Initializes the dispatcher and engine, loads any plugins, and loads + the model, view, and controller components. You may also specify an + array of plugins to load here, if you choose to not load them in the + "use Catalyst" line. - $c->state - Contains the return value of the last executed action. + MyApp->setup; + MyApp->setup( qw/-Debug/ ); - $c->stash - Returns a hashref containing all your data. + $c->uri_for( $path, [ @args ] ) + Merges path with $c->request->base for absolute uri's and with + $c->request->match for relative uri's, then returns a normalized URI + object. If any args are passed, they are added at the end of the + path. - $c->stash->{foo} ||= 'yada'; - print $c->stash->{foo}; + $c->welcome_message + Returns the Catalyst welcome HTML page. INTERNAL METHODS - $c->benchmark($coderef) + $c->benchmark( $coderef ) Takes a coderef with arguments and returns elapsed time as float. my ( $elapsed, $status ) = $c->benchmark( sub { return 1 } ); $c->log->info( sprintf "Processing took %f seconds", $elapsed ); $c->components - Contains the components. + Returns a hash of components. + + $c->context_class + Returns or sets the context class. $c->counter - Returns a hashref containing coderefs and execution counts. (Needed - for deep recursion detection) + Returns a hashref containing coderefs and execution counts (needed + for deep recursion detection). $c->depth - Returns the actual forward depth. + Returns the number of actions on the current internal execution + stack. $c->dispatch - Dispatch request to actions. + Dispatches a request to actions. + + $c->dispatcher_class + Returns or sets the dispatcher class. + + $c->dump_these + Returns a list of 2-element array references (name, structure) pairs + that will be dumped on the error page in debug mode. + + $c->engine_class + Returns or sets the engine class. - $c->execute($class, $coderef) + $c->execute( $class, $coderef ) Execute a coderef in given class and catch exceptions. Errors are available via $c->error. $c->finalize - Finalize request. + Finalizes the request. $c->finalize_body - Finalize body. + Finalizes body. $c->finalize_cookies - Finalize cookies. + Finalizes cookies. $c->finalize_error - Finalize error. + Finalizes error. $c->finalize_headers - Finalize headers. + Finalizes headers. $c->finalize_output An alias for finalize_body. $c->finalize_read - Finalize the input after reading is complete. + Finalizes the input after reading is complete. $c->finalize_uploads - Finalize uploads. Cleans up any temporary files. + Finalizes uploads. Cleans up any temporary files. - $c->get_action( $action, $namespace, $inherit ) - Get an action in a given namespace. + $c->get_action( $action, $namespace ) + Gets an action in a given namespace. + + $c->get_actions( $action, $namespace ) + Gets all actions of a given name in a namespace and all parent + namespaces. handle_request( $class, @arguments ) - Handles the request. + Called to handle each HTTP request. - $c->prepare(@arguments) - Turns the engine-specific request( Apache, CGI ... ) into a Catalyst - context . + $c->prepare( @arguments ) + Creates a Catalyst context from an engine-specific request (Apache, + CGI, etc.). $c->prepare_action - Prepare action. + Prepares action. $c->prepare_body - Prepare message body. + Prepares message body. + + $c->prepare_body_chunk( $chunk ) + Prepares a chunk of data before sending it to HTTP::Body. $c->prepare_body_parameters - Prepare body parameters. + Prepares body parameters. $c->prepare_connection - Prepare connection. + Prepares connection. $c->prepare_cookies - Prepare cookies. + Prepares cookies. $c->prepare_headers - Prepare headers. + Prepares headers. $c->prepare_parameters - Prepare parameters. + Prepares parameters. $c->prepare_path - Prepare path and base. + Prepares path and base. $c->prepare_query_parameters - Prepare query parameters. + Prepares query parameters. $c->prepare_read - Prepare the input for reading. + Prepares the input for reading. $c->prepare_request - Prepare the engine request. + Prepares the engine request. $c->prepare_uploads - Prepare uploads. + Prepares uploads. $c->prepare_write - Prepare the output for writing. + Prepares the output for writing. + + $c->request_class + Returns or sets the request class. + + $c->response_class + Returns or sets the response class. $c->read( [$maxlength] ) - Read a chunk of data from the request body. This method is designed + Reads a chunk of data from the request body. This method is designed to be used in a while loop, reading $maxlength bytes on every call. $maxlength defaults to the size of the request if not specified. @@ -290,37 +404,50 @@ INTERNAL METHODS Starts the engine. $c->set_action( $action, $code, $namespace, $attrs ) - Set an action in a given namespace. + Sets an action in a given namespace. $c->setup_actions($component) - Setup actions for a component. + Sets up actions for a component. $c->setup_components - Setup components. + Sets up components. $c->setup_dispatcher $c->setup_engine $c->setup_home $c->setup_log $c->setup_plugins + $c->stack + Returns the stack. + $c->write( $data ) Writes $data to the output stream. When using this method directly, you will need to manually set the Content-Length header to the length of your output data, if known. -CASE SENSITIVITY - By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar" - becomes "/foo/bar". + version + Returns the Catalyst version number. Mostly useful for "powered by" + messages in template systems. - But you can activate case sensitivity with a config parameter. +INTERNAL ACTIONS + Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO" + "_ACTION" and "_END". These are by default not shown in the private + action table, but you can make them visible with a config parameter. + + MyApp->config->{show_internal_actions} = 1; + +CASE SENSITIVITY + By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar" is + mapped to "/foo/bar". You can activate case sensitivity with a config + parameter. MyApp->config->{case_sensitive} = 1; - So "MyApp::C::Foo::Bar" becomes "/Foo/Bar". + This causes "MyApp::C::Foo::Bar" to map to "/Foo/Bar". ON-DEMAND PARSER The request body is usually parsed at the beginning of a request, but if - you want to handle input yourself or speed things up a bit you can + you want to handle input yourself or speed things up a bit, you can enable on-demand parsing with a config parameter. MyApp->config->{parse_on_demand} = 1; @@ -329,22 +456,21 @@ PROXY SUPPORT Many production servers operate using the common double-server approach, with a lightweight frontend web server passing requests to a larger backend server. An application running on the backend server must deal - with two problems: the remote user always appears to be '127.0.0.1' and - the server's hostname will appear to be 'localhost' regardless of the - virtual host the user connected through. + with two problems: the remote user always appears to be 127.0.0.1 and + the server's hostname will appear to be "localhost" regardless of the + virtual host that the user connected through. Catalyst will automatically detect this situation when you are running - both the frontend and backend servers on the same machine. The following + the frontend and backend servers on the same machine. The following changes are made to the request. $c->req->address is set to the user's real IP address, as read from the - HTTP_X_FORWARDED_FOR header. + HTTP X-Forwarded-For header. The host value for $c->req->base and $c->req->uri is set to the real host, - as read from the HTTP_X_FORWARDED_HOST header. + as read from the HTTP X-Forwarded-Host header. - Obviously, your web server must support these 2 headers for this to - work. + Obviously, your web server must support these headers for this to work. In a more complex server farm environment where you may have your frontend proxy server(s) on different machines, you will need to set a @@ -371,7 +497,7 @@ SUPPORT Join #catalyst on irc.perl.org. - Mailing-Lists: + Mailing Lists: http://lists.rawmode.org/mailman/listinfo/catalyst http://lists.rawmode.org/mailman/listinfo/catalyst-dev @@ -380,8 +506,13 @@ SUPPORT http://catalyst.perl.org + Wiki: + + http://dev.catalyst.perl.org + SEE ALSO Catalyst::Manual - The Catalyst Manual + Catalyst::Component, Catalyst::Base - Base classes for components Catalyst::Engine - Core Engine Catalyst::Log - The Log Class. Catalyst::Request - The Request Object @@ -393,6 +524,10 @@ CREDITS Andy Wardley + Andreas Marienborg + + Andrew Bramble + Andrew Ford Andrew Ruthven @@ -401,6 +536,8 @@ CREDITS Autrijus Tang + Brian Cassidy + Christian Hansen Christopher Hicks @@ -409,6 +546,8 @@ CREDITS Danijel Milicevic + David Kamholz + David Naughton Gary Ashton Jones @@ -433,14 +572,20 @@ CREDITS Robert Sedlacek + Sam Vilain + + Sascha Kiefer + Tatsuhiko Miyagawa Ulf Edvinsson + Yuval Kogman + AUTHOR Sebastian Riedel, "sri@oook.de" LICENSE - This library is free software . You can redistribute it and/or modify it - under the same terms as perl itself. + This library is free software, you can redistribute it and/or modify it + under the same terms as Perl itself.