-NAME
- Catalyst - The Elegant MVC Web Application Framework
+Catalyst-Runtime
+================
+This is the Runtime distribution for the Catalyst MVC framework.
+For more information about Catalyst, write
-SYNOPSIS
- # use the helper to start a new application
- catalyst.pl MyApp
+$ perldoc Catalyst
- # add models, views, controllers
- 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 -- use -r to restart automatically on changes
- script/myapp_server.pl
-
- # command line testing interface
- script/myapp_test.pl /yada
-
- ### 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') { ... }
-
- # 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 Catalyst::Manual::Intro for additional information.
-
-DESCRIPTION
- The key concept of Catalyst is DRY (Don't Repeat Yourself).
-
- See Catalyst::Manual for more documentation.
-
- 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 qw/My::Module/;
-
- 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 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.
-
- $c->finalize_output
- An alias for finalize_body.
-
- $c->finalize_read
- Finalizes the input after reading is complete.
-
- $c->finalize_uploads
- Finalizes uploads. Cleans up any temporary files.
-
- $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 )
- Called to handle each HTTP request.
-
- $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:
-
- 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 - 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"
-
-LICENSE
- This library is free software, you can redistribute it and/or modify it
- under the same terms as Perl itself.
+at the command line, or visit http://www.catalystframework.org/.
+You can also install Catalyst::Manual from CPAN for more
+comprehensive information.
+If you are going to write your own Catalyst application, you will
+need to install Catalyst::Devel. Afterwards run catalyst.pl
+for more information about creating your first app.
projects / catagits/Catalyst-Runtime.git / blobdiff