X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FIntro.pod;h=36adc7ce83b287d198894184eac1715e56b610c2;hp=5aff62131154c45fe639333da9ca2eefcae3c240;hb=b411df01b40662f125aa854a7c25097bc53ad86a;hpb=cb93c9d7a46377666f9593736dcb87fad8f9d82e

diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod
index 5aff621..36adc7c 100644
--- a/lib/Catalyst/Manual/Intro.pod
+++ b/lib/Catalyst/Manual/Intro.pod
@@ -14,17 +14,17 @@ with Catalyst, see L<Catalyst::Manual::Tutorial>.
 =head2 What is Catalyst?
 
 Catalyst is an elegant web application framework, extremely flexible
-yet extremely simple. It's similar to Ruby on Rails, Spring (Java),
-and L<Maypole>, upon which it was originally based. Its most important
-design philosphy is to provide easy access to all the tools you need
-to develop web applications, with few restrictions on how you need to
-use these tools. However, this does mean that it is always possible to
-do things in a different way. Other web frameworks are B<initially>
-simpler to use, but achieve this by locking the programmer into a
-single set of tools. Catalyst's emphasis on flexibility means that you
-have to think more to use it. We view this as a feature.  For example,
-this leads to Catalyst being more suited to system integration tasks
-than other web frameworks.
+yet extremely simple. It's similar to Ruby on Rails, Spring (Java), and
+L<Maypole|Maypole>, upon which it was originally based. Its most
+important design philosphy is to provide easy access to all the tools
+you need to develop web applications, with few restrictions on how you
+need to use these tools. However, this does mean that it is always
+possible to do things in a different way. Other web frameworks are
+I<initially> simpler to use, but achieve this by locking the programmer
+into a single set of tools. Catalyst's emphasis on flexibility means
+that you have to think more to use it. We view this as a feature.  For
+example, this leads to Catalyst being more suited to system integration
+tasks than other web frameworks.
 
 =head3 MVC
 
@@ -104,6 +104,16 @@ example:
 
 Now http://localhost:3000/hello prints "Hello World!".
 
+Note that actions with the C< :Local > attribute are equivalent to
+using a C<:Path('/action_name') > attribute (note the leading slash).
+So our action could be equivalently:
+
+    sub hello : Path('/hello') {
+        my ( $self, $context ) = @_;
+        $context->response->body('Hello World!');
+    }
+
+
 =item * B<Support for CGI, mod_perl, Apache::Request, FastCGI>
 
 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Other
@@ -158,11 +168,14 @@ running, using the helper scripts described above.
 
 =head3 Install
 
-Installation of Catalyst can be a time-consuming and frustrating
-effort, due to its large number of dependencies. The easiest way
-to get up and running is to use Matt Trout's C<cat-install>
-script, from L<http://www.shadowcatsystems.co.uk/static/cat-install>,
-and then install L<Catalyst::Devel>.
+Installation of Catalyst can be a time-consuming effort, due to its
+large number of dependencies. Although most of the frustrations
+associated with this are now ironed out and a simple C<cpan
+Catalyst::Devel> or C<cpan Catalyst::Runtime> are now usually
+straightforward, if you still have problems, you can use use Matt
+Trout's C<cat-install> script, from
+L<http://www.shadowcatsystems.co.uk/static/cat-install>, and then
+install L<Catalyst::Devel>.
 
     # perl cat-install
     # perl -MCPAN -e 'install Catalyst::Devel'
@@ -174,6 +187,16 @@ and then install L<Catalyst::Devel>.
     $ cd MyApp
     $ script/myapp_create.pl controller Library::Login
 
+=head4 Frank Speiser's Amazon EC2 Catalyst SDK
+
+There are currently two flavors of publicly available Amazon Machine
+Images (AMI) that include all the elements you'd need to begin
+developing in a fully functional Catalyst environment within
+minutes. See
+L<Catalyst::Manual::Installation|Catalyst::Manual::Installation> for
+more details.
+
+
 =head3 Run
 
     $ script/myapp_server.pl
@@ -216,14 +239,15 @@ means that this decision is entirely up to you, the programmer;
 Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
 a general discussion of these issues.
 
-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).
+Model, View and Controller components must inherit from L<Catalyst::Model>,
+L<Catalyst::View> and L<Catalyst::Controller>, respectively. These, in turn, inherit
+from L<Catalyst::Component> which provides a simple class structure and some
+common class methods like C<config> and C<new> (constructor).
 
     package MyApp::Controller::Catalog;
 
     use strict;
-    use base 'Catalyst::Base';
+    use base 'Catalyst::Controller';
 
     __PACKAGE__->config( foo => 'bar' );
 
@@ -330,15 +354,15 @@ But first, we need a database.
 
     INSERT INTO foo (data) VALUES ('TEST!');
 
-    % sqlite /tmp/myapp.db < myapp.sql
+    % sqlite3 /tmp/myapp.db < myapp.sql
 
 Now we can create a DBIC::Schema model for this database.
 
     script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
 
-L<DBIx::Class::Schema::Loader> automatically loads table layouts and
-relationships, and converts them into a static schema definition C<MySchema>,
-which you can edit later.
+L<DBIx::Class::Schema::Loader> can automaticall load table layouts and
+relationships, and convert them into a static schema definition
+C<MySchema>, which you can edit later.
 
 Use the stash to pass data to your templates.
 
@@ -549,9 +573,8 @@ configure your application, load plugins, and extend Catalyst.
     package MyApp;
 
     use strict;
-    use Catalyst qw/-Debug/; # Add other plugins here, e.g.
-                             # for session support
-
+    use parent qw/Catalyst/;
+    use Catalyst qw/-Debug ConfigLoader Static::Simple/;
     MyApp->config(
         name => 'My Application',
 
@@ -695,9 +718,10 @@ this:
     # Sets the actions in this controller to be registered with no prefix
     # so they function identically to actions created in MyApp.pm
     __PACKAGE__->config->{namespace} = '';
-    sub default : Private {
+    sub default : Path  {
         my ( $self, $context ) = @_;
-        $context->response->body('Catalyst rocks!');
+        $context->response->status(404);
+        $context->response->body('404 not found');
     }
     1;
 
@@ -796,6 +820,11 @@ Catalyst ("MyApp::Controller" in the above example), replaces "::" with
 explanation of the pre-defined meaning of Catalyst component class
 names.
 
+Note that actions with the C< :Local > attribute are equivalent to the
+<:Path('action_name') > so sub foo : Local { } is equivalent to -
+
+    sub foo : Path('foo') { }
+
 =item * B<Chained>
 
 Catalyst also provides a method to build and dispatch chains of actions,
@@ -819,10 +848,16 @@ dispatch type, please see L<Catalyst::DispatchType::Chained>.
     sub foo : Private { }
 
 Matches no URL, and cannot be executed by requesting a URL that
-corresponds to the action key. Private actions can be executed only
-inside a Catalyst application, by calling the C<forward> method:
+corresponds to the action key. Catalyst's :Private attribute is
+exclusive and doesn't work with other attributes (so will not work
+combined with Path or Chained attributes). With the exception of the
+C< index >, C< auto > and C< default > actions, Private actions can
+only be executed from inside a Catalyst application, by calling the
+C<forward> or C<detach> methods:
 
     $c->forward('foo');
+    # or
+    $c->detach('foo');
 
 See L</Flow Control> for a full explanation of C<forward>. Note that, as
 discussed there, when forwarding from another component, you must use
@@ -860,26 +895,24 @@ call these built-in private actions in your application class:
 
 =over 4
 
-=item * B<default : Private>
+=item * B<default : Path>
 
 Called when no other action matches. Could be used, for example, for
 displaying a generic frontpage for the main app, or an error page for
-individual controllers.
+individual controllers. B<Note>: in older Catalyst applications you
+will see C<default : Private> which is roughly speaking equivalent.
 
-If C<default> isn't acting how you would expect, look at using a
-L</Literal> C<Path> action (with an empty path string). The difference
-is that C<Path> takes arguments relative from the namespace and
-C<default> I<always> takes arguments relative from the root, regardless
-of what controller it's in. Indeed, this is now the recommended way of
-handling default situations; the C<default> private controller should
-be considered deprecated.
 
-=item * B<index : Private>
+=item * B<index : Path : Args (0) >
 
-C<index> is much like C<default> except that it takes no arguments
-and it is weighted slightly higher in the matching process. It is
-useful as a static entry point to a controller, e.g. to have a static
-welcome page. Note that it's also weighted higher than Path.
+C<index> is much like C<default> except that it takes no arguments and
+it is weighted slightly higher in the matching process. It is useful
+as a static entry point to a controller, e.g. to have a static welcome
+page. Note that it's also weighted higher than Path.  Actually the sub
+name C<index> can be called anything you want.  The sub attributes are
+what determines the behaviour of the action.  B<Note>: in older
+Catalyst applications, you will see C<index : Private> used, which is
+roughly speaking equivalent.
 
 =item * B<begin : Private>
 
@@ -896,7 +929,7 @@ Called at the end of a request, after all matching actions are called.
 
     Package MyApp::Controller::Foo;
     sub begin : Private { }
-    sub default : Private { }
+    sub default : Path  { }
     sub auto : Private { }
 
 You can define built-in private actions within your controllers as
@@ -1158,8 +1191,8 @@ IRC:
 
 Mailing lists:
 
-    http://lists.rawmode.org/mailman/listinfo/catalyst
-    http://lists.rawmode.org/mailman/listinfo/catalyst-dev
+    http://lists.scsys.co.uk/mailman/listinfo/catalyst
+    http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev
 
 =head1 AUTHOR