added many more links to the guides and tutorial

mojolicious · Mar 12, 2012 · c541c55 · c541c55
1 parent 681b6ca
commit c541c55
Show file tree

Hide file tree

Showing 8 changed files with 115 additions and 95 deletions.
diff --git a/Changes b/Changes
@@ -1,6 +1,6 @@
 This file documents the revision history for Perl extension Mojolicious.
 
-2.60    2012-03-11 00:00:00
+2.60    2012-03-12 00:00:00
         - Made text_area helper a little smarter. (sshaw, sri)
         - Improved inactivity timeout logging for WebSockets.
         - Fixed escaping bug in select_field and text_area helpers.

diff --git a/lib/Mojolicious/Controller.pm b/lib/Mojolicious/Controller.pm
@@ -683,10 +683,10 @@ implements the following new ones.
 
 =head2 C<cookie>
 
-  $c         = $c->cookie(foo => 'bar');
-  $c         = $c->cookie(foo => 'bar', {path => '/'});
   my $value  = $c->cookie('foo');
   my @values = $c->cookie('foo');
+  $c         = $c->cookie(foo => 'bar');
+  $c         = $c->cookie(foo => 'bar', {path => '/'});
 
 Access request cookie values and create new response cookies.
 
@@ -952,10 +952,10 @@ that cookies are generally limited to 4096 bytes of data.
 
 =head2 C<signed_cookie>
 
-  $c         = $c->signed_cookie(foo => 'bar');
-  $c         = $c->signed_cookie(foo => 'bar', {path => '/'});
   my $value  = $c->signed_cookie('foo');
   my @values = $c->signed_cookie('foo');
+  $c         = $c->signed_cookie(foo => 'bar');
+  $c         = $c->signed_cookie(foo => 'bar', {path => '/'});
 
 Access signed request cookie values and create new signed response cookies.
 Cookies failing signature verification will be automatically discarded.

diff --git a/lib/Mojolicious/Guides/Cookbook.pod b/lib/Mojolicious/Guides/Cookbook.pod
@@ -398,7 +398,8 @@ shouldn't block for too long.
 
 The WebSocket protocol offers full bi-directional low-latency communication
 channels between clients and servers. Receiving messages is as easy as
-subscribing to the C<message> event of the transaction.
+subscribing to the event L<Mojo::Transaction::WebSocket/"message"> with the
+method L<Mojolicious::Controller/"on">.
 
   use Mojolicious::Lite;
   use Mojo::IOLoop;
@@ -453,8 +454,8 @@ subscribing to the C<message> event of the transaction.
     </body>
   </html>
 
-The C<finish> event will be emitted right after the WebSocket connection has
-been closed.
+The event L<Mojo::Transaction::WebSocket/"finish"> will be emitted right
+after the WebSocket connection has been closed.
 
 =head2 Testing WebSocket web services
 
@@ -532,8 +533,9 @@ HTTP protocol for transport.
     </body>
   </html>
 
-The C<message> event will be emitted for every new log message and the
-C<finish> event right after the transaction has been finished.
+The event L<Mojo::Log/"message"> will be emitted for every new log message
+and the event L<Mojo::Transaction/"finish"> right after the transaction has
+been finished.
 
 =head2 Streaming multipart uploads
 
@@ -717,9 +719,10 @@ You can just add username and password to the URL.
 
 =head2 Decorating followup requests
 
-L<Mojo::UserAgent> can automatically follow redirects, the C<start> event
-allows you direct access to each transaction right after they have been
-initialized and before a connection gets associated with them.
+L<Mojo::UserAgent> can automatically follow redirects, the event
+L<Mojo::UserAgent/"start"> allows you direct access to each transaction right
+after they have been initialized and before a connection gets associated with
+them.
 
   use Mojo::UserAgent;
 
@@ -758,8 +761,9 @@ L<Mojo::UserAgent> makes it actually easy.
   # Process transaction
   $ua->start($tx);
 
-The C<read> event will be emitted for every chunk of data that is received,
-even C<chunked> encoding will be handled transparently if necessary.
+The event L<Mojo::Content/"read"> will be emitted for every chunk of data
+that is received, even C<chunked> encoding will be handled transparently if
+necessary.
 
 =head2 Streaming request
 
@@ -788,8 +792,8 @@ Sending a streaming request is almost just as easy.
   # Process transaction
   $ua->start($tx);
 
-The drain callback passed to C<write> will be invoked whenever the entire
-previous chunk has actually been written.
+The drain callback passed to L<Mojo::Message/"write"> will be invoked
+whenever the entire previous chunk has actually been written.
 
 =head2 Large file downloads
 
@@ -906,8 +910,8 @@ transactions will be in random order.
   $ua->get('http://mojolicio.us/perldoc' => $delay->begin);
   my ($tx, $tx2) = $delay->wait;
 
-The C<finish> event of L<Mojo::IOLoop::Delay> can be used in code that needs
-to be able to work standalone as well as inside L<Mojolicious> applications.
+The event L<Mojo::IOLoop::Delay/"finish"> can be used for code that needs to
+be able to work standalone as well as inside L<Mojolicious> applications.
 
   use Mojo::UserAgent;
   use Mojo::IOLoop;

diff --git a/lib/Mojolicious/Guides/FAQ.pod b/lib/Mojolicious/Guides/FAQ.pod
@@ -81,7 +81,7 @@ C<MOJO_MAX_LINE_SIZE> environment variable to change this value.
 L<Mojolicious> uses a secret passphrase for security features such as signed
 cookies. It defaults to the name of your application, which is not very
 secure, so we added this log message as a reminder. You can change the
-passphrase with the C<secret> attribute of L<Mojolicious>.
+passphrase with the attribute L<Mojolicious/"secret">.
 
   app->secret('My very secret passphrase.');
 

diff --git a/lib/Mojolicious/Guides/Growing.pod b/lib/Mojolicious/Guides/Growing.pod
@@ -233,8 +233,9 @@ all logic related to matching usernames and passwords.
 
   1;
 
-A simple C<helper> function can be registered with the C<helper> method of
-L<Mojolicious> to make our C<model> available to all actions and templates.
+A simple helper function can be registered with the method
+L<Mojolicious/"helper"> to make our C<model> available to all actions and
+templates.
 
   #!/usr/bin/env perl
   use Mojolicious::Lite;
@@ -266,9 +267,9 @@ L<Mojolicious> to make our C<model> available to all actions and templates.
 
   app->start;
 
-The C<param> method of our L<Mojolicious::Controller> object is used to
-access query parameters, POST parameters, file uploads and route
-placeholders, all at once.
+The method L<Mojolicious::Controller/"param"> is used to access query
+parameters, POST parameters, file uploads and route placeholders, all at
+once.
 
 =head2 Testing
 
@@ -343,7 +344,8 @@ Quick C<GET> requests can be performed right from the command line.
 =head2 State keeping
 
 Sessions in L<Mojolicious> pretty much just work out of the box and there is
-no setup required, but we suggest using a more secure C<secret> passphrase.
+no setup required, but we suggest setting a more secure passphrase with
+L<Mojolicious/"secret">.
 
   app->secret('Mojolicious rocks');
 
@@ -365,7 +367,9 @@ past.
   $self->session(expires => 1);
 
 For data that should only be visible on the next request, like a confirmation
-message after a 302 redirect, you can use the C<flash>.
+message after a 302 redirect, you can use the flash, accessible through the
+method L<Mojolicious::Controller/"flash"> and helper
+L<Mojolicious::Plugin::DefaultHelpers/"flash">.
 
   $self->flash(message => 'Everything is fine.');
   $self->redirect_to('goodbye');
@@ -535,8 +539,8 @@ actual action code needs to be changed.
 
   1;
 
-The C<startup> method of L<Mojolicious> gets called right after instantiation
-and is the place where the whole application gets set up.
+The C<startup> method gets called right after instantiation and is the place
+where the whole application gets set up.
 
 =head2 Simplified application script
 

diff --git a/lib/Mojolicious/Guides/Rendering.pod b/lib/Mojolicious/Guides/Rendering.pod
@@ -143,18 +143,17 @@ Most commonly used features every L<Mojolicious> developer should know about.
 
 =head2 Automatic rendering
 
-The renderer can be manually started by calling the C<render> controller
-method, but that's usually not necessary, because it will get automatically
-called if nothing has been rendered after the routes dispatcher finished its
-work. This also means you can have routes pointing only to templates without
-actual actions.
+The renderer can be manually started by calling the method
+L<Mojolicious::Controller/"render">, but that's usually not necessary,
+because it will get automatically called if nothing has been rendered after
+the routes dispatcher finished its work. This also means you can have routes
+pointing only to templates without actual actions.
 
   $self->render;
 
-There is one big difference though, by calling C<render> manually you can
-make sure that templates use the current controller object and not the
-default controller specified in the C<controller_class> attribute of the
-application class.
+There is one big difference though, by calling it manually you can make sure
+that templates use the current controller object and not the default
+controller specified in the attribute L<Mojolicious/"controller_class">.
 
 =head2 Rendering templates
 
@@ -172,9 +171,6 @@ shortcut.
 
   $self->render('foo/bar');
 
-All values passed to the C<render> call are only temporarily assigned to the
-stash and get reset again once rendering is finished.
-
 =head2 Rendering inline templates
 
 Some renderers such as C<ep> allow templates to be passed inline.
@@ -244,8 +240,8 @@ These mappings can be easily extended or changed with L<Mojolicious/"types">.
 
 =head2 Stash data
 
-Data can be passed to templates through the C<stash> in any of the native
-Perl data types.
+Any of the native Perl data types can be passed to templates through the
+L<Mojolicious::Controller/"stash">.
 
   $self->stash(author     => 'Sebastian');
   $self->stash(frameworks => ['Catalyst', 'Mojolicious']);
@@ -268,8 +264,9 @@ Since everything is just Perl normal control structures just work.
 =head2 Content negotiation
 
 For resources with different representations and that require truly
-C<RESTful> content negotiation you can also use C<respond_to> instead of
-C<render>.
+C<RESTful> content negotiation you can also use
+L<Mojolicious::Controller/"respond_to"> instead of
+L<Mojolicious::Controller/"render">.
 
   # /hello (Accept: application/json) -> "json"
   # /hello (Accept: text/xml)         -> "xml"
@@ -295,7 +292,7 @@ parameter.
   );
 
 Callbacks can be used for representations that are too complex to fit into a
-single C<render> call.
+single render call.
 
   # /hello (Accept: application/json) -> "json"
   # /hello (Accept: text/html)        -> "html"
@@ -323,11 +320,11 @@ Helpers are little functions you can use in templates and controller code.
 
   my $serialized = $self->dumper([1, 2, 3]);
 
-The C<dumper> helper for example will use L<Data::Dumper> to serialize
-whatever data structure you pass it, this can be very useful for debugging.
-We differentiate between C<default helpers> which are more general purpose
-like C<dumper> and C<tag helpers>, which are template specific and mostly
-used to generate C<HTML> tags.
+The helper L<Mojolicious::Plugin::DefaultHelpers/"dumper"> for example will
+use L<Data::Dumper> to serialize whatever data structure you pass it, this
+can be very useful for debugging. We differentiate between C<default helpers>
+which are more general purpose like C<dumper> and C<tag helpers>, which are
+template specific and mostly used to generate C<HTML> tags.
 
   %= javascript '/script.js'
 
@@ -356,9 +353,11 @@ trivial.
     <body><%= content %></body>
   </html>
 
-You just select the right layout template with the C<layout> helper and place
-the result of the current template with the C<content> helper. You can also
-pass along normal stash values to the C<layout> helper.
+You just select the right layout template with the helper
+L<Mojolicious::Plugin::DefaultHelpers/"layout"> and place the result of the
+current template with the helper
+L<Mojolicious::Plugin::DefaultHelpers/"content">. You can also pass along
+normal stash values to the C<layout> helper.
 
   @@ foo/bar.html.ep
   % layout 'mylayout', title => 'Hi there';
@@ -372,11 +371,13 @@ pass along normal stash values to the C<layout> helper.
   </html>
 
 Instead of the C<layout> helper you could also just use the C<layout> stash
-value, or call C<render> with the C<layout> argument.
+value, or call L<Mojolicious::Controller/"render"> with the C<layout>
+argument.
 
   $self->render(template => 'mytemplate', layout => 'mylayout');
 
-To set a C<layout> stash value application wide you can use C<defaults>.
+To set a C<layout> stash value application wide you can use
+L<Mojolicious/"defaults">.
 
   # Application
   package MyApp;
@@ -393,8 +394,8 @@ To set a C<layout> stash value application wide you can use C<defaults>.
 
 =head2 Including partial templates
 
-Like most helpers the C<include> helper is just a shortcut to make your life
-a little easier.
+Like most helpers the helper L<Mojolicious::Plugin::DefaultHelpers/"include">
+is just a shortcut to make your life a little easier.
 
   @@ foo/bar.html.ep
   <!DOCTYPE html>
@@ -406,8 +407,8 @@ a little easier.
   @@ header.html.ep
   <head><title>Howdy</title></head>
 
-Instead of C<include> you could also just call C<render> with the C<partial>
-argument.
+Instead of C<include> you could also just call
+L<Mojolicious::Controller/"render"> with the C<partial> argument.
 
   @@ foo/bar.html.ep
   <!DOCTYPE html>
@@ -476,8 +477,8 @@ A naive translation to Perl code could look like this.
 
 =head2 Content blocks
 
-Blocks and the C<content_for> helper can also be used to pass whole sections
-of the template to the layout.
+Blocks and the helper L<Mojolicious::Plugin::DefaultHelpers/"content_for">
+can also be used to pass whole sections of the template to the layout.
 
   @@ foo/bar.html.ep
   % layout 'mylayout';
@@ -498,9 +499,10 @@ of the template to the layout.
 
 =head2 Template inheritance
 
-Inheritance takes the layout concept above one step further, it allows you to
-build a skeleton template with named C<content> blocks that child templates
-can override.
+Inheritance takes the layout concept above one step further, the helpers
+L<Mojolicious::Plugin::DefaultHelpers/"content"> and
+L<Mojolicious::Plugin::DefaultHelpers/"extends">allow you to build a skeleton
+template with named blocks that child templates can override.
 
   @@ first.html.ep
   <!DOCTYPE html>
@@ -527,9 +529,9 @@ This chain could go on and on to allow a very high level of template reuse.
 
 =head2 Memorizing template blocks
 
-Compiled templates are always cached in memory, but with the C<memorize>
-helper you can go one step further and prevent template blocks from getting
-executed more than once.
+Compiled templates are always cached in memory, but with the helper
+L<Mojolicious::Plugin::DefaultHelpers/"memorize"> you can go one step further
+and prevent template blocks from getting executed more than once.
 
   @@ cached.html.ep
   % use Time::Piece;
@@ -724,8 +726,8 @@ stylesheets.
   });
 
 The optional drain callback ensures that all previous chunks have been
-written before processing continues. An empty chunk or C<finish> call marks
-the end of the stream.
+written before processing continues. An empty chunk or call to
+L<Mojolicious::Controller/"finish"> marks the end of the stream.
 
   29
   <html><head><title>Example</title></head>