X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=README;h=1438432076cc0a6c7b97ae639b564fab3ef33b87;hp=b8f4f88f68782b702b8c12f9de229782bed570e4;hb=gsoc_breadboard;hpb=b993339edf953ca4eb594e17527721721fc082c6 diff --git a/README b/README index b8f4f88..1438432 100644 --- a/README +++ b/README @@ -1,591 +1,14 @@ -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.