introduce the concept of actions much earlier in the tutorial

mojolicious · Feb 26, 2013 · 8e22221 · 8e22221
1 parent 2b03611
commit 8e22221
Showing 1 changed file with 23 additions and 30 deletions.
diff --git a/lib/Mojolicious/Lite.pm b/lib/Mojolicious/Lite.pm
@@ -151,22 +151,26 @@ every change.
 =head2 Routes
 
 Routes are basically just fancy paths that can contain different kinds of
-placeholders. C<$self> is a L<Mojolicious::Controller> object containing both,
-the HTTP request and response.
+placeholders and usually lead to an action. The first argument passed to all
+actions (the invocant C<$self>) is a L<Mojolicious::Controller> object
+containing both, the HTTP request and response.
 
   use Mojolicious::Lite;
 
-  # /foo
+  # Route leading to an action
   get '/foo' => sub {
     my $self = shift;
     $self->render(text => 'Hello World!');
   };
 
   app->start;
 
+Responses are usually generated by actions with
+L<Mojolicious::Controller/"render">.
+
 =head2 GET/POST parameters
 
-All C<GET> and C<POST> parameters are accessible via
+All C<GET> and C<POST> parameters sent with the request are accessible via
 L<Mojolicious::Controller/"param">.
 
   use Mojolicious::Lite;
@@ -187,7 +191,7 @@ which can be inlined in the C<DATA> section.
 
   use Mojolicious::Lite;
 
-  # /bar
+  # Route leading to an action that renders a template
   get '/bar' => sub {
     my $self = shift;
     $self->stash(one => 23);
@@ -210,7 +214,7 @@ full access to all HTTP features and information.
 
   use Mojolicious::Lite;
 
-  # /agent
+  # Access response and request headers
   get '/agent' => sub {
     my $self = shift;
     $self->res->headers->header('X-Bender' => 'Bite my shiny metal ass!');
@@ -230,13 +234,13 @@ without non-word characters.
 
   use Mojolicious::Lite;
 
-  # /
+  # Render the template "index.html.ep"
   get '/' => sub {
     my $self = shift;
     $self->render;
   } => 'index';
 
-  # /hello
+  # Render the template "hello.html.ep"
   get '/hello';
 
   app->start;
@@ -258,11 +262,7 @@ L<Mojolicious::Plugin::DefaultHelpers/"content">.
 
   use Mojolicious::Lite;
 
-  # /with_layout
-  get '/with_layout' => sub {
-    my $self = shift;
-    $self->render('with_layout');
-  };
+  get '/with_layout';
 
   app->start;
   __DATA__
@@ -286,7 +286,6 @@ delimited by the C<begin> and C<end> keywords.
 
   use Mojolicious::Lite;
 
-  # /with_block
   get '/with_block' => 'block';
 
   app->start;
@@ -313,11 +312,7 @@ pass around blocks of captured content.
 
   use Mojolicious::Lite;
 
-  # /captured
-  get '/captured' => sub {
-    my $self = shift;
-    $self->render('captured');
-  };
+  get '/captured';
 
   app->start;
   __DATA__
@@ -350,15 +345,15 @@ L<Mojolicious::Plugin::TagHelpers>.
 
   use Mojolicious::Lite;
 
-  # "whois" helper
+  # A helper to identify visitors
   helper whois => sub {
     my $self  = shift;
     my $agent = $self->req->headers->user_agent || 'Anonymous';
     my $ip    = $self->tx->remote_address;
     return "$agent ($ip)";
   };
 
-  # /secret
+  # Use helper in action and template
   get '/secret' => sub {
     my $self = shift;
     my $user = $self->whois;
@@ -434,7 +429,7 @@ C<.>.
 
 =head2 HTTP methods
 
-Routes can be restricted to specific request methods.
+Routes can be restricted to specific request methods with different keywords.
 
   use Mojolicious::Lite;
 
@@ -542,7 +537,7 @@ are only evaluated if the callback returned a true value.
     return undef;
   };
 
-  # / (with authentication)
+  # Only reached when authenticated
   get '/' => 'index';
 
   app->start;
@@ -567,7 +562,7 @@ Prefixing multiple routes is another good use for C<under>.
   # /foo/baz
   get '/baz' => {text => 'foo baz'};
 
-  # /
+  # / (reset)
   under '/' => {message => 'whatever'};
 
   # /bar
@@ -621,7 +616,6 @@ Formats can be automatically detected by looking at file extensions.
     $self->render('detected');
   };
 
-
   app->start;
   __DATA__
 
@@ -705,13 +699,13 @@ constructs.
 
   use Mojolicious::Lite;
 
-  # /foo (Firefox)
+  # Firefox
   get '/foo' => (agent => qr/Firefox/) => sub {
     my $self = shift;
     $self->render(text => 'Congratulations, you are using a cool browser.');
   };
 
-  # /foo (Internet Explorer)
+  # Internet Explorer
   get '/foo' => (agent => qr/Internet Explorer/) => sub {
     my $self = shift;
     $self->render(text => 'Dude, you really need to upgrade to Firefox.');
@@ -733,6 +727,7 @@ L<Mojolicious::Plugin::DefaultHelpers/"session">.
 
   use Mojolicious::Lite;
 
+  # Access session data in action and template
   get '/counter' => sub {
     my $self = shift;
     $self->session->{counter}++;
@@ -845,11 +840,9 @@ directory.
 
   use Mojolicious::Lite;
 
-  # /external
+  # Render template "templates/foo/bar.html.ep"
   any '/external' => sub {
     my $self = shift;
-
-    # templates/foo/bar.html.ep
     $self->render('foo/bar');
   };