Project: Catalyst

Revision: 10

Author: sri

Date: 02 Mar 2005 16:19:10

• /trunk/Catalyst/lib/Catalyst/Manual/Intro.pod

  ......	@@ -18,15 +18,15 @@
  18	18
  19	19	=over 4
  20	20
  21		=item * Model
  	21	=item * B<Model>
  22	22
  23	23	Access and modify content (data). L<Class::DBI>, L<Plucene>, L<Net::LDAP>...
  24	24
  25		=item * View
  	25	=item * B<View>
  26	26
  27	27	Present content to the user. L<Template Toolkit|Template>, L<Mason|HTML::Mason>...
  28	28
  29		=item * Controller
  	29	=item * B<Controller>
  30	30
  31	31	Control the whole request phase, check parameters, dispatch actions, flow control. Catalyst!
  32	32
  ......	@@ -40,17 +40,17 @@
  40	40
  41	41	=over 4
  42	42
  43		=item * Multiple Models, Views and Controllers
  	43	=item * B<Multiple Models, Views and Controllers>
  44	44
  45	45	To build a Catalyst application, you handle each type of concern inside special modules called L</Components>. Often this code will be very simple, just calling out to Perl modules like those listed above under L</MVC>. Catalyst is very flexible about these Components. Use as many Models, Views and Controllers as you like, using as many different Perl modules as you like, all in the same application. Want to manipulate multiple databases, plus retrieve some data via LDAP? No problem. Want to present data from the same Model using L<Template Toolkit|Template> and L<PDF::Template>? Easy.
  46	46
  47		=item * Re-Useable Components
  	47	=item * B<Re-Useable Components>
  48	48
  49	49	Not only does Catalyst promote the re-use of already-existing Perl modules, it also allows you to re-use your Catalyst components in multiple Catalyst applications.
  50	50
  51		=item * Unrestrained URL-to-Action Dispatching
  	51	=item * B<Unrestrained URL-to-Action Dispatching>
  52	52
  53		Catalyst allows you to dispatch any URLs to any application L<Actions>, even via regular expressions! Unlike some other frameworks, it doesn't require you to put class and method names in your URLs.
  	53	Catalyst allows you to dispatch any URLs to any application L<Actions>, even via regular expressions! Unlike some other frameworks, it doesn't require mod_rewrite or class and method names in URLs.
  54	54
  55	55	With Catalyst you register your actions and address them directly. For example:
  56	56
  ......	@@ -61,7 +61,7 @@
  61	61
  62	62	Now http://localhost:3000/hello prints "Hello World!".
  63	63
  64		=item * Support for CGI, mod_perl, Apache::Request
  	64	=item * B<Support for CGI, mod_perl, Apache::Request>
  65	65
  66	66	Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>.
  67	67
  ......	@@ -71,23 +71,23 @@
  71	71
  72	72	The best part is that Catalyst implements all this flexibility in a very simple way.
  73	73
  74		=item * Building Block Interface
  	74	=item * B<Building Block Interface>
  75	75
  76	76	Components interoperate very smoothly. For example, Catalyst automatically makes a L<Context> object available in every component. Via the context, you can access the request object, share data between components, and control the flow of your application. Building a Catalyst application feels a lot like snapping together toy building blocks, and everything just works.
  77	77
  78		=item * Component Auto-Discovery
  	78	=item * B<Component Auto-Discovery>
  79	79
  80	80	No need to C<use> all of your components. Catalyst automatically finds and loads them.
  81	81
  82		=item * Pre-Built Components for Popular Modules
  	82	=item * B<Pre-Built Components for Popular Modules>
  83	83
  84	84	See L<Catalyst::Model::CDBI> for L<Class::DBI>, or L<Catalyst::View::TT> for L<Template Toolkit|Template>. You can even get an instant web database front end with L<Catalyst::Model::CDBI::CRUD>.
  85	85
  86		=item * Builtin Test Framework
  	86	=item * B<Builtin Test Framework>
  87	87
  88	88	Catalyst comes with a builtin, lightweight http server and test framework, making it easy to test applications from the command line.
  89	89
  90		=item * Helper Scripts
  	90	=item * B<Helper Scripts>
  91	91
  92	92	Catalyst provides helper scripts to quickly generate running starter code for components and unit tests.
  93	93
  ......	@@ -153,23 +153,23 @@
  153	153
  154	154	=over 4
  155	155
  156		=item * name
  	156	=item * B<name>
  157	157
  158	158	Name of your application.
  159	159
  160		=item * root
  	160	=item * B<root>
  161	161
  162	162	Path to additional files like templates, images or other static data.
  163	163
  164	164	=back
  165	165
  166		However, you can define as many parameters as you want for plugins or whatever you need. You can access them anywhere in your application via $context->config->{$param_name}.
  	166	However, you can define as many parameters as you want for plugins or whatever you need. You can access them anywhere in your application via C<$context-E<gt>config-E<gt>{$param_name}>.
  167	167
  168	168	=head3 Context
  169	169
  170	170	Catalyst automatically blesses a Context object into your application class and makes it available everywhere in your application. Use the Context to directly interact with Catalyst and glue your L<Components> together.
  171	171
  172		As illustrated earlier in our URL-to-Action dispatching example, the Context is always the second method parameter, behind the Component object reference itself. Previously we called it $context for clarity, but most Catalyst developers just call it $c:
  	172	As illustrated earlier in our URL-to-Action dispatching example, the Context is always the second method parameter, behind the Component object reference or class name itself. Previously we called it C<$context> for clarity, but most Catalyst developers just call it C<$c>:
  173	173
  174	174	MyApp->action( 'hello' => sub {
  175	175	my ( $self, $c ) = @_;
  ......	@@ -185,7 +185,7 @@
  185	185	$c->request
  186	186	$c->req # alias
  187	187
  188		The request contains all kind of request specific informations like query parameters, cookies, uploads, headers and more.
  	188	The request contains all kinds of request-specific information, like query parameters, cookies, uploads, headers and more.
  189	189
  190	190	$c->req->params->{foo};
  191	191	$c->req->cookies->{sessionid};
  ......	@@ -197,7 +197,7 @@
  197	197	$c->response
  198	198	$c->res # alias
  199	199
  200		The response is like the request but contains just response specific informations.
  	200	The response is like the request, but contains just response-specific information.
  201	201
  202	202	$c->res->output('Hello World');
  203	203	$c->res->status(404);
  ......	@@ -217,7 +217,7 @@
  217	217	$c->log->debug('Something happened');
  218	218	$c->log->info('Something you should know');
  219	219
  220		=item * Stash
  	220	=item * B<Stash>
  221	221
  222	222	$c->stash
  223	223
  ......	@@ -225,7 +225,7 @@
  225	225
  226	226	=back
  227	227
  228		The last of these, the stash, is a universal hash for sharing data among application components. For an example, we return to our 'hello' action example:
  	228	The last of these, the stash, is a universal hash for sharing data among application components. For an example, we return to our 'hello' action:
  229	229
  230	230	MyApp->action(
  231	231
  ......	@@ -250,21 +250,21 @@
  250	250
  251	251	=over 4
  252	252
  253		=item * Literal
  	253	=item * B<Literal>
  254	254
  255	255	MyApp->action( 'foo/bar' => sub { } );
  256	256
  257	257	Matches only http://localhost:3000/foo/bar.
  258	258
  259		=item * Regex
  	259	=item * B<Regex>
  260	260
  261	261	MyApp->action( '/^foo(\d+)/bar(\d+)$/' => sub { } );
  262	262
  263	263	Matches any URL that matches the pattern in the action key, e.g. http://localhost:3000/foo23/bar42. The pattern must be enclosed with forward slashes, i.e. '/$pattern/'.
  264	264
  265		If you use capturing parantheses to extract values within the matching URL (23, 42 in the above example), those values are available in the $c->req->snippets array. Be sure to use ^ and $ if your action has arguments.
  	265	If you use capturing parantheses to extract values within the matching URL (23, 42 in the above example), those values are available in the $c->req->snippets array. If you want to pass arguments at the end of your URL, you must use regex action keys. See L</URL Argument Handling> below.
  266	266
  267		=item * Namespace-Prefixed
  	267	=item * B<Namespace-Prefixed>
  268	268
  269	269	package MyApp::Controller::My::Controller;
  270	270	MyApp->action( '?foo' => sub { } );
  ......	@@ -273,7 +273,7 @@
  273	273
  274	274	Prefixing the action key with '?' indicates that the matching URL must be prefixed with a modified form of the component's class (package) name. This modified class name excludes the parts that have a pre-defined meaning in Catalyst ("MyApp::Controller" in the above example), replaces "::" with "_" and converts the name to lower case. See L</Components> for a full explanation of the pre-defined meaning of Catalyst component class names.
  275	275
  276		=item * Private
  	276	=item * B<Private>
  277	277
  278	278	MyApp->action( '!foo' => sub { } );
  279	279
  ......	@@ -291,24 +291,45 @@
  291	291
  292	292	=over 4
  293	293
  294		=item * !default
  	294	=item * B<!default>
  295	295
  296	296	Called when no other action matches.
  297	297
  298		=item * !begin
  	298	=item * B<!begin>
  299	299
  300	300	Called at the beginning of a request, before any matching actions are called.
  301	301
  302		=item * !end
  	302	=item * B<!end>
  	303
  	304	=back
  303	305
  304	306	Called at the end of a request, after all matching actions are called.
  305	307
  306		=item * !?default, !?begin and !?end
  	308	=head4 B<Namespace-Prefixed Private Actions>
  307	309
  308		Like their equivalents above but used to overload them from Controllers.
  309		So each Controller can have its own !?default, !?begin and !?end.
  	310	MyApp->action( '!?foo' => sub { } );
  	311	MyApp->action( '!?default' => sub { } );
  310	312
  311		=back
  	313	The leading '!?' indicates that these are namespace-prefixed private actions. These override any application-wide private actions with the same names, and can be called only from within the namespace in which they are defined. Any private action can be namespace-prefixed, including the builtins. One use for this might be to give a Controller its own !?default, !?begin and !?end.
  	314
  	315	=head4 B<URL Argument Handling>
  	316
  	317	If you want to pass variable arguments at the end of a URL, you must use regex actions keys with '^' and '$' anchors, and the arguments must be separated with forward slashes (/) in the URL. For example, suppose you want to handle /foo/$bar/$baz, where $bar and $baz may vary:
  	318
  	319	MyApp->action( '/^foo$/' => sub { my ($self, $context, $bar, $baz) = @_; } );
  	320
  	321	But what if you also defined actions for /foo/boo and /foo/boo/hoo ?
  	322
  	323	MyApp->action( '/foo/boo' => sub { .. } );
  	324	MyApp->action( '/foo/boo/hoo' => sub { .. } );
  	325
  	326	Catalyst matches actions in most specific to least specific order:
  	327
  	328	/foo/boo/hoo
  	329	/foo/boo
  	330	/foo # might be /foo/bar/baz
  	331
  	332	So Catalyst would never mistakenly dispatch the first two URLs to the '/^foo$/' action.
  312	333
  313	334	=head3 Flow Control
  314	335
  ......	@@ -368,9 +389,9 @@
  368	389
  369	390	=head3 Components
  370	391
  371		Again, Catalyst has an uncommonly flexible component system. You can define as many L<Models>, L<Views> and Controllers as you like.
  	392	Again, Catalyst has an uncommonly flexible component system. You can define as many L<Models>, L<Views> and L<Controllers> as you like.
  372	393
  373		All components are must inherit from L<Catalyst::Base>, which provides a simple class structure and some common class methods like C<config> and C<new> (constructor).
  	394	All components must inherit from L<Catalyst::Base>, which provides a simple class structure and some common class methods like C<config> and C<new> (constructor).
  374	395
  375	396	package MyApp::Controller::MyController;
  376	397
  ......	@@ -385,17 +406,17 @@
  385	406
  386	407	=over 4
  387	408
  388		=item * MyApp/Model/
  	409	=item * B<MyApp/Model/>
  389	410
  390		=item * MyApp/M/
  	411	=item * B<MyApp/M/>
  391	412
  392		=item * MyApp/View/
  	413	=item * B<MyApp/View/>
  393	414
  394		=item * MyApp/V/
  	415	=item * B<MyApp/V/>
  395	416
  396		=item * MyApp/Controller/
  	417	=item * B<MyApp/Controller/>
  397	418
  398		=item * MyApp/C/
  	419	=item * B<MyApp/C/>
  399	420
  400	421	=back
  401	422
  ......	@@ -533,12 +554,20 @@
  533	554
  534	555	perl -I/home/joeuser/myapp/lib -MCatalyst::Test=MyApp -e1 3000
  535	556
  	557	or
  	558
  	559	perl bin/server
  	560
  536	561	...then visit http://localhost:3000/ in a browser to view the output.
  537	562
  538	563	You can also do it all from the command line:
  539	564
  540	565	perl -I/home/joeuser/myapp/lib -MCatalyst::Test=MyApp -e1 http://localhost/
  541	566
  	567	or
  	568
  	569	perl bin/test http://localhost/
  	570
  542	571	Have fun!
  543	572
  544	573	=head1 AUTHOR

• /trunk/Catalyst/Changes

  ......	@@ -5,6 +5,7 @@
  5	5	- improved docs
  6	6	- private prefixed actions override private non prefixed actions
  7	7	- added server_base
  	8	- updated Catalyst::Manual::Intro
  8	9
  9	10	4.10 Wed Mar 02 10:00:00 2005
  10	11	- improved documentation