SYNOPSIS
# use the helper to start a new application
catalyst.pl MyApp
- cd MyApp
# add models, views, controllers
- script/create.pl model Something
- script/create.pl view Stuff
- script/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
- script/server.pl
+ # built in testserver -- use -r to restart automatically on changes
+ script/myapp_server.pl
- # command line interface
- script/test.pl /yada
+ # 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/;
-
- __PACKAGE__->action( '!default' => sub { $_[1]->res->output('Hello') } );
-
- __PACKAGE__->action(
- 'index.html' => sub {
- my ( $self, $c ) = @_;
- $c->res->output('Hello');
- $c->forward('_foo');
+ ### 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
}
- );
-
- __PACKAGE__->action(
- '/^product[_]*(\d*).html$/' => sub {
- my ( $self, $c ) = @_;
- $c->stash->{template} = 'product.tt';
- $c->stash->{product} = $c->req->snippets->[0];
+ }
+
+ # 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') { ... }
+
+ # 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 ) = @_;
+ if ( scalar @{ $c->error } ) { ... } # handle errors
+ return if $c->res->body; # already have a response
+ $c->forward( 'MyApp::View::TT' ); # render template
+ }
+
+ ### 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 ) = @_;
+ # 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
- Catalyst is based upon Maypole, which you should consider for smaller
- projects.
-
The key concept of Catalyst is DRY (Don't Repeat Yourself).
See Catalyst::Manual for more documentation.
- Omit the Catalyst::Plugin:: prefix from plugins. So
- Catalyst::Plugin::My::Module becomes My::Module.
+ Catalyst plugins can be loaded by naming them as arguments to the "use
+ Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the
+ plugin name, i.e., "Catalyst::Plugin::My::Module" becomes "My::Module".
- use Catalyst 'My::Module';
+ use Catalyst qw/My::Module/;
- You can also set special flags like -Debug and -Engine.
+ Special flags like -Debug and -Engine can also be specified as arguments
+ when Catalyst is loaded:
use Catalyst qw/-Debug My::Module/;
The position of plugins and flags in the chain is important, because
- they are loaded in the same order they appear.
+ they are loaded in exactly the order that they appear.
+
+ The following flags are supported:
+
+ -Debug
+ Enables debug output.
+
+ -Engine
+ Forces Catalyst to use a specific engine. Omit the
+ "Catalyst::Engine::" prefix of the engine name, i.e.:
+
+ use Catalyst qw/-Engine=CGI/;
+
+ -Home
+ Forces Catalyst to use a specific home directory.
+
+ -Log
+ Specifies log level.
+
+METHODS
+ Information about the current request
+ $c->action
+ Returns a Catalyst::Action object for the current action, which
+ stringifies to the action name.
+
+ $c->namespace
+ Returns the namespace of the current action, i.e., the uri prefix
+ corresponding to the controller of the current action.
+
+ $c->request
+ $c->req
+ Returns the current Catalyst::Request object.
+
+ 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->detach( $action [, \@arguments ] )
+ $c->detach( $class, $method, [, \@arguments ] )
+ The same as "forward", but doesn't return.
+
+ $c->error
+ $c->error($error, ...)
+ $c->error($arrayref)
+ Returns an arrayref containing error messages.
+
+ my @error = @{ $c->error };
+
+ Add a new error.
+
+ $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
+ Returns the engine instance. Stringifies to the class name.
+
+ $c->log
+ 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!' );
+
+ Your log class should implement the methods described in the
+ Catalyst::Log man page.
+
+ Utility methods
+ $c->path_to(@path)
+ Merges @path with $c->config->{home} and returns a Path::Class
+ object.
+
+ For example:
+
+ $c->path_to( 'db', 'sqlite.db' );
+
+ $c->plugin( $name, $class, @args )
+ Helper method for plugins. It creates a classdata accessor/mutator
+ and loads and instantiates the given class.
+
+ MyApp->plugin( 'prototype', 'HTML::Prototype' );
+
+ $c->prototype->define_javascript_functions;
+
+ 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.
+
+ MyApp->setup;
+ MyApp->setup( qw/-Debug/ );
+
+ $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->welcome_message
+ Returns the Catalyst welcome HTML page.
+
+INTERNAL METHODS
+ $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
+ 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).
+
+ $c->depth
+ Returns the number of actions on the current internal execution
+ stack.
+
+ $c->dispatch
+ 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 )
+ Execute a coderef in given class and catch exceptions. Errors are
+ available via $c->error.
+
+ $c->finalize
+ Finalizes the request.
+
+ $c->finalize_body
+ Finalizes body.
+
+ $c->finalize_cookies
+ Finalizes cookies.
+
+ $c->finalize_error
+ Finalizes error.
+
+ $c->finalize_headers
+ Finalizes headers.
- -Debug
- use Catalyst '-Debug';
+ $c->finalize_output
+ An alias for finalize_body.
- is equivalent to
+ $c->finalize_read
+ Finalizes the input after reading is complete.
- use Catalyst;
- sub debug { 1 }
+ $c->finalize_uploads
+ Finalizes uploads. Cleans up any temporary files.
- -Engine
- Force Catalyst to use a specific engine. Omit the Catalyst::Engine::
- prefix.
+ $c->get_action( $action, $namespace )
+ Gets an action in a given namespace.
- use Catalyst '-Engine=CGI';
+ $c->get_actions( $action, $namespace )
+ Gets all actions of a given name in a namespace and all parent
+ namespaces.
- METHODS
- debug
- Overload to enable debug messages.
+ handle_request( $class, @arguments )
+ Called to handle each HTTP request.
- config
- Returns a hashref containing your applications settings.
+ $c->prepare( @arguments )
+ Creates a Catalyst context from an engine-specific request (Apache,
+ CGI, etc.).
+
+ $c->prepare_action
+ Prepares action.
+
+ $c->prepare_body
+ Prepares message body.
+
+ $c->prepare_body_chunk( $chunk )
+ Prepares a chunk of data before sending it to HTTP::Body.
+
+ $c->prepare_body_parameters
+ Prepares body parameters.
+
+ $c->prepare_connection
+ Prepares connection.
+
+ $c->prepare_cookies
+ Prepares cookies.
+
+ $c->prepare_headers
+ Prepares headers.
+
+ $c->prepare_parameters
+ Prepares parameters.
+
+ $c->prepare_path
+ Prepares path and base.
+
+ $c->prepare_query_parameters
+ Prepares query parameters.
+
+ $c->prepare_read
+ Prepares the input for reading.
+
+ $c->prepare_request
+ Prepares the engine request.
+
+ $c->prepare_uploads
+ Prepares uploads.
+
+ $c->prepare_write
+ 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] )
+ 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.
+
+ You have to set MyApp->config->{parse_on_demand} to use this
+ directly.
+
+ $c->run
+ Starts the engine.
+
+ $c->set_action( $action, $code, $namespace, $attrs )
+ Sets an action in a given namespace.
+
+ $c->setup_actions($component)
+ Sets up actions for a component.
+
+ $c->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.
+
+ version
+ Returns the Catalyst version number. Mostly useful for "powered by"
+ messages in template systems.
+
+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;
+
+ 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
+ enable on-demand parsing with a config parameter.
+
+ MyApp->config->{parse_on_demand} = 1;
+
+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 that the user connected through.
+
+ Catalyst will automatically detect this situation when you are running
+ 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.
+
+ 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.
+
+ 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
+ configuration option to tell Catalyst to read the proxied data from the
+ headers.
+
+ MyApp->config->{using_frontend_proxy} = 1;
+
+ If you do not wish to use the proxy support at all, you may set:
+
+ MyApp->config->{ignore_frontend_proxy} = 1;
+
+THREAD SAFETY
+ Catalyst has been tested under Apache 2's threading mpm_worker,
+ mpm_winnt, and the standalone forking HTTP server on Windows. We believe
+ the Catalyst core to be thread-safe.
+
+ If you plan to operate in a threaded environment, remember that all
+ other modules you are using must also be thread-safe. Some modules, most
+ notably DBD::SQLite, are not thread-safe.
SUPPORT
IRC:
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
-
+
+ Web:
+
+ http://catalyst.perl.org
+
+ Wiki:
+
+ http://dev.catalyst.perl.org
+
SEE ALSO
- Catalyst::Manual, Catalyst::Test, Catalyst::Request, Catalyst::Response,
- Catalyst::Engine
+ 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
+ Catalyst::Response - The Response Object
+ Catalyst::Test - The test suite.
+
+CREDITS
+ Andy Grundman
+
+ Andy Wardley
+
+ Andreas Marienborg
+
+ Andrew Bramble
+
+ Andrew Ford
+
+ Andrew Ruthven
+
+ Arthur Bergman
+
+ Autrijus Tang
+
+ Brian Cassidy
+
+ Christian Hansen
+
+ Christopher Hicks
+
+ Dan Sully
+
+ Danijel Milicevic
+
+ David Kamholz
+
+ David Naughton
+
+ Gary Ashton Jones
+
+ Geoff Richards
+
+ Jesse Sheidlower
+
+ Jesse Vincent
+
+ Jody Belka
+
+ Johan Lindstrom
+
+ Juan Camacho
+
+ Leon Brocard
+
+ Marcus Ramberg
+
+ Matt S Trout
+
+ Robert Sedlacek
+
+ Sam Vilain
+
+ Sascha Kiefer
+
+ Tatsuhiko Miyagawa
+
+ Ulf Edvinsson
+
+ Yuval Kogman
AUTHOR
Sebastian Riedel, "sri@oook.de"
-THANK YOU
- Andrew Ruthven, Danijel Milicevic, David Naughton, Gary Ashton Jones,
- Jesse Sheidlower, Johan Lindstrom, Marcus Ramberg and all the others
- who've helped.
-
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.
projects / catagits/Catalyst-Runtime.git / blobdiff