diff --git a/lib/Dancer2/Manual.pod b/lib/Dancer2/Manual.pod
index 58e3d72cc..8f471b3be 100644
--- a/lib/Dancer2/Manual.pod
+++ b/lib/Dancer2/Manual.pod
@@ -452,1195 +452,1179 @@ can use lexical prefix like this:
 
     get '/page1' => sub {}; # will match /page1
 
-=head2 Delayed responses (Async/Streaming)
-
-L<Dancer2> can provide delayed (otherwise known as I<asynchronous>) responses
-using the C<delayed> keyword. These responses are streamed, although you can
-set the content all at once, if you prefer.
-
-    get '/status' => sub {
-        delayed {
-            response_header 'X-Foo' => 'Bar';
-
-            # flush headers (in case of streaming)
-            flush;
+=head2 Action Skipping
 
-            # send content to the user
-            content 'Hello, world!';
+An action can choose not to serve the current request and ask Dancer2 to
+process the request with the next matching route.
 
-            # you can write more content
-            # all streaming
-            content 'Hello, again!';
+This is done with the B<pass> keyword, like in the following example
 
-            # when done, close the connection
-            done;
+    get '/say/:word' => sub {
+        pass if route_parameters->get('word') =~ /^\d+$/;
+        "I say a word: " . route_parameters->get('word');
+    };
 
-            # do whatever you want else, asynchronously
-            # the user socket closed by now
-            ...
-        };
+    get '/say/:number' => sub {
+        "I say a number: " . route_parameters->get('number');
     };
 
-If you are streaming (calling C<content> several times), you must call
-C<flush> first. If you're sending only once, you don't need to call C<flush>.
 
-Here is an example of using delayed responses with L<AnyEvent>:
+=head1 HANDLERS
 
-    use Dancer2;
-    use AnyEvent;
+=head2 File Handler
 
-    my %timers;
-    my $count = 5;
-    get '/drums' => sub {
-        delayed {
-            print "Stretching...\n";
-            flush; # necessary, since we're streaming
+Whenever a content is produced out of the parsing of a static file, the
+L<Dancer2::Handler::File> component is used. This component provides two
+hooks, C<before_file_render> and C<after_file_render>.
 
-            $timers{'Snare'} = AE::timer 1, 1, delayed {
-                $timers{'HiHat'} ||= AE::timer 0, 0.5, delayed {
-                    content "Tss...\n";
-                };
+C<before_file_render> hooks are called just before starting to parse the
+file, the hook receives as its first argument the file path that is going to
+be processed.
 
-                content "Bap!\n";
+    hook before_file_render => sub {
+        my $path = shift;
+    };
 
-                if ( $count-- == 0 ) {
-                    %timers = ();
-                    content "Tugu tugu tugu dum!\n";
-                    done;
+C<after_file_render> hooks are called after the file has been parsed and the
+response content produced. It receives the response object
+(L<Dancer2::Core::Response>) produced.
 
-                    print "<enter sound of applause>\n\n";
-                    $timers{'Applause'} = AE::timer 3, 0, sub {
-                        # the DSL will not available here
-                        # because we didn't call the "delayed" keyword
-                        print "<applause dies out>\n";
-                    };
-                }
-            };
-        };
+    hook after_file_render => sub {
+       my $response = shift;
     };
 
-If an error happens during a write operation, a warning will be issued
-to the logger.
-
-You can handle the error yourself by providing an C<on_error> handler:
+=head2 Auto page
 
-    get '/' => sub {
-        delayed {
-            flush;
-            content "works";
+Whenever a page that matches an existing template needs to be served, the
+L<Dancer2::Handler::AutoPage> component is used.
 
-            # ... user disconnected here ...
 
-            content "fails";
+=head1 ERRORS
 
-            # ... error triggered ...
+=head2 Error Pages
 
-            done; # doesn't even get run
-        } on_error => sub {
-            # delayed{} not needed, DSL already available
-            my ($error) = @_;
-            # do something with $error
-        };
-    };
+When an HTTP error occurs (i.e. the action responds with a status code other
+than 200), this is how Dancer2 determines what page to display.
 
-Here is an example that asynchronously streams the contents of a CSV file:
+=over
 
-    use Dancer2;
-    use Text::CSV_XS  qw< csv >;
-    use Path::Tiny    qw< path >;
-    use JSON::MaybeXS qw< encode_json >;
-    # Create CSV parser
-    my $csv = Text::CSV_XS->new({
-        binary    => 1,
-        auto_diag => 1,
-    });
-    get '/' => sub {
-        # delayed response:
-        delayed {
-            # streaming content
-            flush;
-            # Read each row and stream it in JSON
-            my $fh = path('filename.csv')->openr_utf8;
-            while ( my $row = $csv->getline($fh) ) {
-                content encode_json $row;
-            }
-            # close user connection
-            done;
-        } on_error => sub {
-            my ($error) = @_;
-            warning 'Failed to stream to user: ' . request->remote_address;
-        };
-    };
+=item * Looks in the C<views/> directory for a corresponding template file
+matching the error code (e.g. C<500.tt> or C<404.tt>). If such a file exists,
+it's used to report the error.
 
-B<NOTE:> If you just want to send a file's contents asynchronously,
-use C<send_file($filename)> instead of C<delayed>, as it will
-automatically take advantage of any asynchronous capability.
+=item * Next, looks in the C<public/> directory for a corresponding HTML file
+matching the error code (e.g. C<500.html> or C<404.html>). If such a file
+exists, it's used to report the error. (Note, however, that if B<show_stacktrace>
+is set to true, in the case of a 500 error the static HTML page will not be
+shown, but will be replaced with a default error page containing more
+informative diagnostics. For more information see L<Dancer2::Config>.)
 
-=head2 Action Skipping
+(In older versions, B<show_errors> was used instead of B<show_stacktrace>.
+Both are supported, but B<show_errors> is deprecated.)
 
-An action can choose not to serve the current request and ask Dancer2 to
-process the request with the next matching route.
+=item * As default, render a generic error page on the fly.
 
-This is done with the B<pass> keyword, like in the following example
+=back
 
-    get '/say/:word' => sub {
-        pass if route_parameters->get('word') =~ /^\d+$/;
-        "I say a word: " . route_parameters->get('word');
-    };
+=head2 Execution Errors
 
-    get '/say/:number' => sub {
-        "I say a number: " . route_parameters->get('number');
-    };
+When an error occurs during the route execution, Dancer2 will render an
+error page with the HTTP status code 500.
 
-=head1 HOOKS
+It's possible either to display the content of the error message or to hide
+it with a generic error page. This is a choice left to the end-user and can
+be controlled with the B<show_stacktrace> setting (see above).
 
-Hooks are code references (or anonymous subroutines) that are triggered at
-specific moments during the resolution of a request.  They are set up using the
-L<hook|Dancer2::Manual::Keywords/hook> keyword.
+=head2 Error Hooks
 
-Many of them are provided by Dancer2's core, but plugins and engines can also
-define their own.
+When an error is caught by Dancer2's core, an exception object is built (of
+the class L<Dancer2::Core::Error>). This class provides a hook to let the
+user alter the error workflow if needed.
 
-=over 4
+C<init_error> hooks are called whenever an error object is built, the object
+is passed to the hook.
 
-=item * C<before> hooks
+    hook init_error => sub {
+        my $error = shift;
+        # do something with $error
+    };
 
-C<before> hooks are evaluated before each request within the context of the
-request and receives as argument the app (a L<Dancer2::Core::App> object).
+I<This hook was named B<before_error_init> in Dancer, both names currently
+are synonyms for backward-compatibility.>
 
-It's possible to define variables which will be accessible in the action
-blocks with the L<var keyword|Dancer2::Manual::Keywords/var>.
+C<before_error> hooks are called whenever an error is going to be thrown, it
+receives the error object as its sole argument.
 
-    hook before => sub {
-        var note => 'Hi there';
+    hook before_error => sub {
+        my $error = shift;
+        # do something with $error
     };
 
-    get '/foo/*' => sub {
-        my ($match) = splat; # 'oversee';
-        vars->{note};        # 'Hi there'
-    };
+I<This hook was named B<before_error_render> in Dancer, both names currently
+are synonyms for backward-compatibility.>
 
-For another example, this can be used along with session support to easily
-give non-logged-in users a login page:
+C<after_error> hooks are called whenever an error object has been thrown, it
+receives a L<Dancer2::Core::Response> object as its sole argument.
 
-    hook before => sub {
-        if (!session('user') && request->path !~ m{^/login}) {
-            # Pass the original path requested along to the handler:
-            forward '/login', { requested_path => request->path };
-        }
+    hook after_error => sub {
+        my $response = shift;
     };
 
-The request keyword returns the current L<Dancer2::Core::Request> object
-representing the incoming request.
+I<This hook was named B<after_error_render> in Dancer, both names currently
+are synonyms for backward-compatibility.>
 
-=item * C<after> hooks
+C<on_route_exception> is called when an exception has been caught, at the
+route level, just before rethrowing it higher. This hook receives a
+L<Dancer2::Core::App> and the error as arguments.
 
-C<after> hooks are evaluated after the response has been built by a route
-handler, and can alter the response itself, just before it's sent to the
-client.
+  hook on_route_exception => sub {
+    my ($app, $error) = @_;
+  };
 
-This hook runs after a request has been processed, but before the response
-is sent.
+=head1 SESSIONS
 
-It receives a L<Dancer2::Core::Response> object, which it can modify if it
-needs to make changes to the response which is about to be sent.
+=head2 Handling sessions
 
-The hook can use other keywords in order to do whatever it wants.
+It's common to want to use sessions to give your web applications state; for
+instance, allowing a user to log in, creating a session, and checking that
+session on subsequent requests.
 
-    hook after => sub {
-        response->content(
-            q{The "after" hook can alter the response's content here!}
-        );
-    };
+By default Dancer 2 has L<Simple|Dancer2::Session::Simple> sessions enabled.
+It implements a very simple in-memory session storage. This will be fast and
+useful for testing, but such sessions will not persist between restarts of
+your app.
 
-=back
+If you'd like to use a different session engine you must declare it in the
+configuration file.
 
-=head2 Templates
+For example to use YAML file base sessions you need to add the following
+to your F<config.yml>:
 
-=over 4
+    session: YAML
 
-=item * C<before_template_render>
+Or, to enable session support from within your code,
 
-C<before_template_render> hooks are called whenever a template is going to
-be processed, they are passed the tokens hash which they can alter.
+    set session => 'YAML';
 
-    hook before_template_render => sub {
-        my $tokens = shift;
-        $tokens->{foo} = 'bar';
-    };
+(However, controlling settings is best done from your config file.)
 
-The tokens hash will then be passed to the template with all the
-modifications performed by the hook. This is a good way to setup some
-global vars you like to have in all your templates, like the name of the
-user logged in or a section name.
+The L<Dancer2::Session::YAML> backend implements a file-based YAML session
+storage to help with debugging, but shouldn't be used on production systems.
 
-=item * C<after_template_render>
+There are other session backends, such as L<Dancer2::Session::Memcached>,
+which are recommended for production use.
 
-C<after_template_render> hooks are called after the view has been rendered.
-They receive as their first argument the reference to the content that has
-been produced. This can be used to post-process the content rendered by the
-template engine.
+You can then use the L<session|Dancer2::Manual/session> keyword to manipulate the
+session:
 
-    hook after_template_render => sub {
-        my $ref_content = shift;
-        my $content     = ${$ref_content};
+=head3 Storing data in the session
 
-        # do something with $content
-        ${$ref_content} = $content;
-    };
+Storing data in the session is as easy as:
 
-=item * C<before_layout_render>
+    session varname => 'value';
 
-C<before_layout_render> hooks are called whenever the layout is going to be
-applied to the current content. The arguments received by the hook are the
-current tokens hashref and a reference to the current content.
+=head3 Retrieving data from the session
 
-    hook before_layout_render => sub {
-        my ($tokens, $ref_content) = @_;
-        $tokens->{new_stuff} = 42;
-        $ref_content = \"new content";
-    };
+Retrieving data from the session is as easy as:
 
-=item * C<after_layout_render>
+    session('varname')
 
-C<after_layout_render> hooks are called once the complete content of the
-view has been produced, after the layout has been applied to the content.
-The argument received by the hook is a reference to the complete content
-string.
+Or, alternatively,
 
-    hook after_layout_render => sub {
-        my $ref_content = shift;
-        # do something with ${ $ref_content }, which reflects directly
-        #   in the caller
-    };
+    session->read("varname")
 
-=back
+=head3 Controlling where sessions are stored
 
-=head2 Error Handling
+For disc-based session backends like L<Dancer2::Session::YAML>,
+session files are written to the session dir specified by
+the C<session_dir> setting, which defaults to C<./sessions>
+if not specifically set.
 
-Refer to L<Error Hooks|Dancer2::Manual/Error-Hooks>
-for details about the following hooks:
+If you need to control where session files are created, you can do so
+quickly and easily within your config file, for example:
 
-=over 4
+    session: YAML
+    engines:
+      session:
+        YAML:
+          session_dir: /tmp/dancer-sessions
 
-=item * C<init_error>
+If the directory you specify does not exist, Dancer2 will attempt to create
+it for you.
 
-=item * C<before_error>
+=head3 Changing session ID
 
-=item * C<after_error>
+If you wish to change the session ID (for example on privilege level change):
 
-=item * C<on_route_exception>
+    my $new_session_id = app->change_session_id
 
-=back
+=head3 Destroying a session
 
-=head2 File Rendering
+When you're done with your session, you can destroy it:
 
-Refer to L<File Handler|Dancer2::Manual/File-Handler>
-for details on the following hooks:
+    app->destroy_session
 
-=over 4
+=head2 Sessions and logging in
 
-=item * C<before_file_render>
+A common requirement is to check the user is logged in, and, if not, require
+them to log in before continuing.
 
-=item * C<after_file_render>
+This can easily be handled using a before hook to check their session:
 
-=back
+    use Dancer2;
+    set session => "Simple";
 
-=head2 Logging
+    hook before => sub {
+        if (!session('user') && request->path !~ m{^/login}) {
+            forward '/login', { requested_path => request->path };
+        }
+    };
 
-Logging hooks do not allow you to alter log message content, but they do
-give you a place to perform extra actions. For example, if you want to send
-an email for error messages, but you don't want to use a heavier logger
-such as L<Log::Any> or L<Log::Log4perl>:
+    get '/' => sub { return "Home Page"; };
 
-    hook 'engine.logger.after' => sub {
-        my ( $logger, $level, $message ) = @_;
+    get '/secret' => sub { return "Top Secret Stuff here"; };
 
-        if( $level eq 'error' ) {
-            # Send an email with the message content
-        }
+    get '/login' => sub {
+        # Display a login page; the original URL they requested is available as
+        # query_parameters->get('requested_path'), so could be put in a hidden field in the form
+        template 'login', { path => query_parameters->get('requested_path') };
     };
 
-There are two hooks available for logging:
+    post '/login' => sub {
+        # Validate the username and password they supplied
+        if (body_parameters->get('user') eq 'bob' && body_parameters->get('pass') eq 'letmein') {
+            session user => body_parameters->get('user');
+            redirect body_parameters->get('path') || '/';
+        } else {
+            redirect '/login?failed=1';
+        }
+    };
 
-=over 4
+    dance();
 
-=item * engine.logger.before
+Here is what the corresponding C<login.tt> file should look like. You should
+place it in a directory called C<views/>:
 
-This hook is called before a log message is produced.
+    <html>
+      <head>
+        <title>Session and logging in</title>
+      </head>
+      <body>
+        <form action='/login' method='POST'>
+            User Name : <input type='text' name='user'/>
+            Password: <input type='password' name='pass' />
 
-=item * engine.logger.after
+            <!-- Put the original path requested into a hidden
+                       field so it's sent back in the POST and can be
+                       used to redirect to the right page after login -->
+            <input type='hidden' name='path' value='<% path %>'/>
 
-This hook is called after a log message is produced.
+            <input type='submit' value='Login' />
+        </form>
+      </body>
+    </html>
 
-=back
+Of course, you'll probably want to validate your users against a database
+table, or maybe via IMAP/LDAP/SSH/POP3/local system accounts via PAM etc.
+L<Authen::Simple> is probably a good starting point here!
 
-=head2 Serializers
+A simple working example of handling authentication against a database table
+yourself (using L<Dancer2::Plugin::Database> which provides the C<database>
+keyword, and L<Crypt::SaltedHash> to handle salted hashed passwords (well,
+you wouldn't store your users passwords in the clear, would you?)) follows:
 
-=over 4
+    post '/login' => sub {
+        my $user_value = body_parameters->get('user');
+        my $pass_value = body_parameters->get('pass');
 
-=item * C<before_serializer> is called before serializing the content, and receives
-the content to serialize as an argument.
+        my $user = database->quick_select('users',
+            { username => $user_value }
+        );
+        if (!$user) {
+            warning "Failed login for unrecognised user $user_value";
+            redirect '/login?failed=1';
+        } else {
+            if (Crypt::SaltedHash->validate($user->{password}, $pass_value))
+            {
+                debug "Password correct";
+                # Logged in successfully
+                session user => $user;
+                redirect body_parameters->get('path') || '/';
+            } else {
+                debug("Login failed - password incorrect for " . $user_value);
+                redirect '/login?failed=1';
+            }
+        }
+    };
 
-  hook before_serializer => sub {
-    my $content = shift;
-    ...
-  };
+=head3 Retrieve complete hash stored in session
 
-=item * C<after_serializer> is called after the payload has been serialized, and
-receives the serialized content as an argument.
+Get complete hash stored in session:
 
-  hook after_serializer => sub {
-    my $serialized_content = shift;
-    ...
-  };
+    my $hash = session;
 
-=back
+=head3 The Session keyword
 
+Dancer2 maintains two session layers.
 
-=head1 HANDLERS
+The first layer, L<Dancer2::Core::Session> provides a session object
+which represents the current session. You can read from it as many
+times as you want, and write to it as many times as you want.
 
-=head2 File Handler
+The second layer is the session engine (L<Dancer2::Session::Simple>
+is one example), which is used in order to implement the reading and
+writing from the actual storage. This is read only once, when a request
+comes in (using a cookie whose value is C<dancer.session> by default).
+At the end of a request, all the data you've written will be flushed
+to the engine itself, which will do the actual write to the storage
+(whether it's in a hash in memory, in Memcache, or in a database).
 
-Whenever a content is produced out of the parsing of a static file, the
-L<Dancer2::Handler::File> component is used. This component provides two
-hooks, C<before_file_render> and C<after_file_render>.
+=head1 TEMPLATES
 
-C<before_file_render> hooks are called just before starting to parse the
-file, the hook receives as its first argument the file path that is going to
-be processed.
+Returning plain content is all well and good for examples or trivial apps,
+but soon you'll want to use templates to maintain separation between your
+code and your content. Dancer2 makes this easy.
 
-    hook before_file_render => sub {
-        my $path = shift;
-    };
+Your route handlers can use the L<template|Dancer2::Manual/template> keyword
+to render templates.
 
-C<after_file_render> hooks are called after the file has been parsed and the
-response content produced. It receives the response object
-(L<Dancer2::Core::Response>) produced.
+=head2 Views
 
-    hook after_file_render => sub {
-       my $response = shift;
-    };
+In Dancer2, a file which holds a template is called a I<view>.  Views are
+located in the C<appdir/views> directory.
 
-=head2 Auto page
+You can change this location by changing the setting 'views'. For instance
+if your templates are located in the 'templates' directory, do the
+following:
 
-Whenever a page that matches an existing template needs to be served, the
-L<Dancer2::Handler::AutoPage> component is used.
+    set views => path( app->location , 'templates' );
 
+By default, the internal template engine L<Dancer2::Template::Simple> is
+used, but you may want to upgrade to L<Template
+Toolkit|http://www.template-toolkit.org/>. If you do so, you have to enable
+this engine in your settings as explained in
+L<Dancer2::Template::TemplateToolkit> and you'll also have to install the
+L<Template> module.
 
-=head1 ERRORS
+In order to render a view, just call the
+L<template|Dancer2::Manual/template> keyword at the end of the action by
+giving the view name and the HASHREF of tokens to interpolate in the view
+(note that for convenience, the request, session, params and vars are
+automatically accessible in the view, named C<request>, C<session>, C<params>,
+and C<vars>) - for example:
 
-=head2 Error Pages
+    hook before => sub { var time => scalar(localtime) };
 
-When an HTTP error occurs (i.e. the action responds with a status code other
-than 200), this is how Dancer2 determines what page to display.
+    get '/hello/:name' => sub {
+        my $name = route_parameters->get('name');
+        template 'hello.tt', { name => $name };
+    };
 
-=over
+The template C<hello.tt> could contain, for example:
 
-=item * Looks in the C<views/> directory for a corresponding template file
-matching the error code (e.g. C<500.tt> or C<404.tt>). If such a file exists,
-it's used to report the error.
+    <p>Hi there, [% name %]!</p>
+    <p>You're using [% request.user_agent %]</p>
+    [% IF session.username %]
+        <p>You're logged in as [% session.username %]</p>
+    [% END %]
+    It's currently [% vars.time %]
 
-=item * Next, looks in the C<public/> directory for a corresponding HTML file
-matching the error code (e.g. C<500.html> or C<404.html>). If such a file
-exists, it's used to report the error. (Note, however, that if B<show_stacktrace>
-is set to true, in the case of a 500 error the static HTML page will not be
-shown, but will be replaced with a default error page containing more
-informative diagnostics. For more information see L<Dancer2::Config>.)
+For a full list of the tokens automatically added to your template (like
+C<session>, C<request>, and C<vars>, refer to
+L<Dancer2::Core::Role::Template>).
 
-(In older versions, B<show_errors> was used instead of B<show_stacktrace>.
-Both are supported, but B<show_errors> is deprecated.)
+By default, views use a F<.tt> extension. This can be overridden by setting
+the C<extension> attribute in the template engine configuration:
 
-=item * As default, render a generic error page on the fly.
+    set engines => {
+        template => {
+            template_toolkit => {
+                extension => 'foo',
+            },
+        },
+    };
 
-=back
+=head2 Layouts
 
-=head2 Execution Errors
+A layout is a special view, located in the F<layouts> directory (inside the
+views directory) which must have a token named C<content>. That token marks
+the place where to render the action view. This lets you define a global
+layout for your actions, and have each individual view contain only
+specific content. This is a good thing and helps avoid lots of needless
+duplication of HTML. :)
 
-When an error occurs during the route execution, Dancer2 will render an
-error page with the HTTP status code 500.
+For example, the layout F<views/layouts/main.tt>:
 
-It's possible either to display the content of the error message or to hide
-it with a generic error page. This is a choice left to the end-user and can
-be controlled with the B<show_stacktrace> setting (see above).
+    <html>
+        <head>...</head>
+        <body>
+        <div id="header">
+        ...
+        </div>
 
-=head2 Error Hooks
+        <div id="content">
+        [% content %]
+        </div>
 
-When an error is caught by Dancer2's core, an exception object is built (of
-the class L<Dancer2::Core::Error>). This class provides a hook to let the
-user alter the error workflow if needed.
+        </body>
+    </html>
 
-C<init_error> hooks are called whenever an error object is built, the object
-is passed to the hook.
+You can tell your app which layout to use with C<layout: name> in the config
+file, or within your code:
 
-    hook init_error => sub {
-        my $error = shift;
-        # do something with $error
-    };
+    set layout => 'main';
 
-I<This hook was named B<before_error_init> in Dancer, both names currently
-are synonyms for backward-compatibility.>
+You can control which layout to use (or whether to use a layout at all) for
+a specific request without altering the layout setting by passing an options
+hashref as the third param to the template keyword:
 
-C<before_error> hooks are called whenever an error is going to be thrown, it
-receives the error object as its sole argument.
+    template 'index.tt', {}, { layout => undef };
 
-    hook before_error => sub {
-        my $error = shift;
-        # do something with $error
+If your application is not mounted under root (C</>), you can use a
+C<before_template_render> hook instead of hardcoding the path into your
+application for your CSS, images and JavaScript:
+
+    hook before_template_render => sub {
+        my $tokens = shift;
+        $tokens->{uri_base} = request->base->path;
     };
 
-I<This hook was named B<before_error_render> in Dancer, both names currently
-are synonyms for backward-compatibility.>
+Then in your layout, modify your CSS inclusion as follows:
 
-C<after_error> hooks are called whenever an error object has been thrown, it
-receives a L<Dancer2::Core::Response> object as its sole argument.
+    <link rel="stylesheet" href="[% uri_base %]/css/style.css" />
 
-    hook after_error => sub {
-        my $response = shift;
-    };
+From now on you can mount your application wherever you want, without any
+further modification of the CSS inclusion.
 
-I<This hook was named B<after_error_render> in Dancer, both names currently
-are synonyms for backward-compatibility.>
+=head2 Encoding
 
-C<on_route_exception> is called when an exception has been caught, at the
-route level, just before rethrowing it higher. This hook receives a
-L<Dancer2::Core::App> and the error as arguments.
+If you use L<Plack> and have a Unicode problem with your Dancer2
+application, don't forget to check if you have set your template engine to
+use Unicode, and set the default charset to UTF-8. So, if you are using
+template toolkit, your config file will look like this:
 
-  hook on_route_exception => sub {
-    my ($app, $error) = @_;
-  };
+    charset: UTF-8
+    engines:
+      template:
+        template_toolkit:
+          ENCODING: utf8
 
-=head1 SESSIONS
 
-=head2 Handling sessions
+=head2 Default Template Variables
 
-It's common to want to use sessions to give your web applications state; for
-instance, allowing a user to log in, creating a session, and checking that
-session on subsequent requests.
+Every template knows about the following variables, which are provided by
+L<Dancer2::Core::Role::Template>. Some are similar to the keywords you can
+use in the Perl part of your Dancer2 application.
 
-By default Dancer 2 has L<Simple|Dancer2::Session::Simple> sessions enabled.
-It implements a very simple in-memory session storage. This will be fast and
-useful for testing, but such sessions will not persist between restarts of
-your app.
+=over 4
 
-If you'd like to use a different session engine you must declare it in the
-configuration file.
+=item * B<perl_version>
 
-For example to use YAML file base sessions you need to add the following
-to your F<config.yml>:
+Current version of perl, effectively
+L<C<$^V>|http://perldoc.perl.org/perlvar.html#%24%5eV>.
 
-    session: YAML
+=item * B<dancer_version>
 
-Or, to enable session support from within your code,
+Current version of Dancer2, effectively C<< Dancer2->VERSION >>.
 
-    set session => 'YAML';
+=item * B<settings>
 
-(However, controlling settings is best done from your config file.)
+A hash of the application configuration. This is like
+the L<config|Dancer2::Manual/config> keyword.
 
-The L<Dancer2::Session::YAML> backend implements a file-based YAML session
-storage to help with debugging, but shouldn't be used on production systems.
+=item * B<request>
 
-There are other session backends, such as L<Dancer2::Session::Memcached>,
-which are recommended for production use.
+The current request object. This is like the L<request|Dancer2::Manual/request> keyword.
 
-You can then use the L<session|Dancer2::Manual/session> keyword to manipulate the
-session:
+=item * B<params>
 
-=head3 Storing data in the session
+A hash reference of all the parameters.
 
-Storing data in the session is as easy as:
+Currently the equivalent of C<< $request->params >>, and like the
+L<params|Dancer2::Manual/params> keyword.
 
-    session varname => 'value';
+=item * B<vars>
 
-=head3 Retrieving data from the session
+The list of request variables, which is what you would get if you
+called the L<vars|Dancer2::Manual/vars> keyword.
 
-Retrieving data from the session is as easy as:
+=item * B<session>
 
-    session('varname')
+The current session data, if a session exists. This is like
+the L<session|Dancer2::Manual/session> keyword.
 
-Or, alternatively,
+=back
 
-    session->read("varname")
+=head1 STATIC FILES
 
-=head3 Controlling where sessions are stored
+=head2 Static Directory
 
-For disc-based session backends like L<Dancer2::Session::YAML>,
-session files are written to the session dir specified by
-the C<session_dir> setting, which defaults to C<./sessions>
-if not specifically set.
+Static files are served from the F<./public> directory. You can specify a
+different location by setting the C<public_dir> option:
 
-If you need to control where session files are created, you can do so
-quickly and easily within your config file, for example:
+    set public_dir => path( app->location , 'static' );
 
-    session: YAML
-    engines:
-      session:
-        YAML:
-          session_dir: /tmp/dancer-sessions
+When you modify default public_dir you have to set C<static_handler> option.
 
-If the directory you specify does not exist, Dancer2 will attempt to create
-it for you.
+    set static_handler => true;
 
-=head3 Changing session ID
+Note that the public directory name is not included in the URL. A file
+F<./public/css/style.css> is made available as
+L<http://example.com/css/style.css>.
 
-If you wish to change the session ID (for example on privilege level change):
+=head2 Static File from a Route Handler
 
-    my $new_session_id = app->change_session_id
+It's possible for a route handler to send a static file, as follows:
 
-=head3 Destroying a session
+    get '/download/*' => sub {
+        my ($file) = splat;
 
-When you're done with your session, you can destroy it:
+        send_file $file;
+    };
 
-    app->destroy_session
+Or even if you want your index page to be a plain old F<index.html> file,
+just do:
 
-=head2 Sessions and logging in
+    get '/' => sub {
+        send_file '/index.html'
+    };
 
-A common requirement is to check the user is logged in, and, if not, require
-them to log in before continuing.
 
-This can easily be handled using a before hook to check their session:
+=head1 FILE UPLOADS
 
-    use Dancer2;
-    set session => "Simple";
+Files are uploaded in Dancer2 using the class L<Dancer2::Core::Request::Upload>.
+The objects are accessible within the route handlers using the C<upload>
+keyword:
 
-    hook before => sub {
-        if (!session('user') && request->path !~ m{^/login}) {
-            forward '/login', { requested_path => request->path };
-        }
+    post '/upload' => sub {
+        my $upload     = upload('file_input_name');    # upload object
+        $upload->copy_to('Uploads/');
     };
 
-    get '/' => sub { return "Home Page"; };
+=head1 CONFIGURATION
 
-    get '/secret' => sub { return "Top Secret Stuff here"; };
+=head2 Configuration and environments
 
-    get '/login' => sub {
-        # Display a login page; the original URL they requested is available as
-        # query_parameters->get('requested_path'), so could be put in a hidden field in the form
-        template 'login', { path => query_parameters->get('requested_path') };
-    };
+Configuring a Dancer2 application can be done in many ways. The easiest one
+(and maybe the dirtiest) is to put all your settings statements at the top
+of your script, before calling the C<dance()> method.
 
-    post '/login' => sub {
-        # Validate the username and password they supplied
-        if (body_parameters->get('user') eq 'bob' && body_parameters->get('pass') eq 'letmein') {
-            session user => body_parameters->get('user');
-            redirect body_parameters->get('path') || '/';
-        } else {
-            redirect '/login?failed=1';
-        }
-    };
+Other ways are possible: for example, you can define all your settings in the file
+C<appdir/config.yml>. For this, you must have installed the L<YAML> module, and
+of course, write the config file in YAML.
 
-    dance();
+That's better than the first option, but it's still not perfect as you can't
+switch easily from an environment to another without rewriting the config
+file.
 
-Here is what the corresponding C<login.tt> file should look like. You should
-place it in a directory called C<views/>:
+A better solution is to have one F<config.yml> file with default global
+settings, like the following:
 
-    <html>
-      <head>
-        <title>Session and logging in</title>
-      </head>
-      <body>
-        <form action='/login' method='POST'>
-            User Name : <input type='text' name='user'/>
-            Password: <input type='password' name='pass' />
+    # appdir/config.yml
+    logger: 'file'
+    layout: 'main'
 
-            <!-- Put the original path requested into a hidden
-                       field so it's sent back in the POST and can be
-                       used to redirect to the right page after login -->
-            <input type='hidden' name='path' value='<% path %>'/>
+And then write as many environment files as you like in
+C<appdir/environments>. That way, the appropriate environment config file
+will be loaded according to the running environment (if none is specified,
+it will be 'development').
 
-            <input type='submit' value='Login' />
-        </form>
-      </body>
-    </html>
+You can change the running environment when starting your app using the
+C<plackup> command's C<--env> or C<--E> switch:
 
-Of course, you'll probably want to validate your users against a database
-table, or maybe via IMAP/LDAP/SSH/POP3/local system accounts via PAM etc.
-L<Authen::Simple> is probably a good starting point here!
+    plackup -E production bin/app.psgi
 
-A simple working example of handling authentication against a database table
-yourself (using L<Dancer2::Plugin::Database> which provides the C<database>
-keyword, and L<Crypt::SaltedHash> to handle salted hashed passwords (well,
-you wouldn't store your users passwords in the clear, would you?)) follows:
+Altenatively, you can set the
+L<C<DANCER_ENVIRONMENT>|https://metacpan.org/pod/Dancer2::Config#DANCER_ENVIRONMENT>
+environment variable in the shell or in your web server's configuration file.
 
-    post '/login' => sub {
-        my $user_value = body_parameters->get('user');
-        my $pass_value = body_parameters->get('pass');
+Typically, you'll want to set the following values in a development config
+file:
 
-        my $user = database->quick_select('users',
-            { username => $user_value }
-        );
-        if (!$user) {
-            warning "Failed login for unrecognised user $user_value";
-            redirect '/login?failed=1';
-        } else {
-            if (Crypt::SaltedHash->validate($user->{password}, $pass_value))
-            {
-                debug "Password correct";
-                # Logged in successfully
-                session user => $user;
-                redirect body_parameters->get('path') || '/';
-            } else {
-                debug("Login failed - password incorrect for " . $user_value);
-                redirect '/login?failed=1';
-            }
-        }
+    # appdir/environments/development.yml
+    log: 'debug'
+    startup_info: 1
+    show_stacktrace:  1
+
+And in a production one:
+
+    # appdir/environments/production.yml
+    log: 'warning'
+    startup_info: 0
+    show_stacktrace:  0
+
+Please note that you are not limited to writing configuration files in YAML.
+Dancer2 supports any file format that is supported by L<Config::Any>, such
+as JSON, XML, INI files, and Apache-style config files. See the Dancer2
+L<configuration guide|https://metacpan.org/pod/Dancer2::Config#MANIPULATING-SETTINGS-VIA-CONFIGURATION-FILES>
+for more information.
+
+=head2 Accessing configuration information
+
+A Dancer2 application can use the C<config> keyword to easily access the
+settings within its config file, for instance:
+
+    get '/appname' => sub {
+        return "This is " . config->{appname};
     };
 
-=head3 Retrieve complete hash stored in session
+This makes keeping your application's settings all in one place simple and
+easy - you shouldn't need to worry about implementing all that yourself. :)
 
-Get complete hash stored in session:
+=head2 Settings
 
-    my $hash = session;
+It's possible to change almost every parameter of the application via the
+settings mechanism.
 
-=head3 The Session keyword
+A setting is a key/value pair assigned by the keyword B<set>:
 
-Dancer2 maintains two session layers.
+    set setting_name => 'setting_value';
 
-The first layer, L<Dancer2::Core::Session> provides a session object
-which represents the current session. You can read from it as many
-times as you want, and write to it as many times as you want.
+More usefully, settings can be defined in a configuration file.
+Environment-specific settings can also be defined in environment-specific
+files (for instance, you do not want to show error stacktraces in
+production, and might want extra logging in development).
 
-The second layer is the session engine (L<Dancer2::Session::Simple>
-is one example), which is used in order to implement the reading and
-writing from the actual storage. This is read only once, when a request
-comes in (using a cookie whose value is C<dancer.session> by default).
-At the end of a request, all the data you've written will be flushed
-to the engine itself, which will do the actual write to the storage
-(whether it's in a hash in memory, in Memcache, or in a database).
+=head1 LOGGING
 
-=head1 TEMPLATES
+=head2 Configuring logging
 
-Returning plain content is all well and good for examples or trivial apps,
-but soon you'll want to use templates to maintain separation between your
-code and your content. Dancer2 makes this easy.
+It's possible to log messages generated by the application and by Dancer2
+itself.
 
-Your route handlers can use the L<template|Dancer2::Manual/template> keyword
-to render templates.
+To start logging, select the logging engine you wish to use with the
+C<logger> setting; Dancer2 includes built-in log engines named C<file> and
+C<console>, which log to a logfile and to the console respectively.
 
-=head2 Views
+To enable logging to a file, add the following to your config file:
 
-In Dancer2, a file which holds a template is called a I<view>.  Views are
-located in the C<appdir/views> directory.
+    logger: 'file'
 
-You can change this location by changing the setting 'views'. For instance
-if your templates are located in the 'templates' directory, do the
-following:
+Then you can choose which kind of messages you want to actually log:
 
-    set views => path( app->location , 'templates' );
+    log: 'core'      # will log debug, info, warnings, errors,
+                     #   and messages from Dancer2 itself
+    log: 'debug'     # will log debug, info, warning and errors
+    log: 'info'      # will log info, warning and errors
+    log: 'warning'   # will log warning and errors
+    log: 'error'     # will log only errors
 
-By default, the internal template engine L<Dancer2::Template::Simple> is
-used, but you may want to upgrade to L<Template
-Toolkit|http://www.template-toolkit.org/>. If you do so, you have to enable
-this engine in your settings as explained in
-L<Dancer2::Template::TemplateToolkit> and you'll also have to install the
-L<Template> module.
+If you're using the C<file> logging engine, a directory C<appdir/logs> will
+be created and will host one logfile per environment. The log message
+contains the time it was written, the PID of the current process, the
+message and the caller information (file and line).
 
-In order to render a view, just call the
-L<template|Dancer2::Manual/template> keyword at the end of the action by
-giving the view name and the HASHREF of tokens to interpolate in the view
-(note that for convenience, the request, session, params and vars are
-automatically accessible in the view, named C<request>, C<session>, C<params>,
-and C<vars>) - for example:
+=head2 Logging your own messages
 
-    hook before => sub { var time => scalar(localtime) };
+Just call L<debug|https://metacpan.org/pod/Dancer2::Manual#debug>,
+L<info|https://metacpan.org/pod/Dancer2::Manual#info>,
+L<warning|https://metacpan.org/pod/Dancer2::Manual#warning> or
+L<error|https://metacpan.org/pod/Dancer2::Manual#error> with your message:
 
-    get '/hello/:name' => sub {
-        my $name = route_parameters->get('name');
-        template 'hello.tt', { name => $name };
-    };
+    debug "This is a debug message from my app.";
 
-The template C<hello.tt> could contain, for example:
 
-    <p>Hi there, [% name %]!</p>
-    <p>You're using [% request.user_agent %]</p>
-    [% IF session.username %]
-        <p>You're logged in as [% session.username %]</p>
-    [% END %]
-    It's currently [% vars.time %]
+=head1 Testing
 
-For a full list of the tokens automatically added to your template (like
-C<session>, C<request>, and C<vars>, refer to
-L<Dancer2::Core::Role::Template>).
+=head2 Using Plack::Test
 
-By default, views use a F<.tt> extension. This can be overridden by setting
-the C<extension> attribute in the template engine configuration:
+L<Plack::Test> receives a common web request (using standard L<HTTP::Request>
+objects), fakes a web server in order to create a proper PSGI request, and sends it
+to the web application. When the web application returns a PSGI response
+(which Dancer applications do), it will then convert it to a common web response
+(as a standard L<HTTP::Response> object).
 
-    set engines => {
-        template => {
-            template_toolkit => {
-                extension => 'foo',
-            },
-        },
-    };
+This allows you to then create requests in your test, create the code reference
+for your web application, call them, and receive a response object, which can
+then be tested.
 
-=head2 Layouts
+=head3 Basic Example
 
-A layout is a special view, located in the F<layouts> directory (inside the
-views directory) which must have a token named C<content>. That token marks
-the place where to render the action view. This lets you define a global
-layout for your actions, and have each individual view contain only
-specific content. This is a good thing and helps avoid lots of needless
-duplication of HTML. :)
+Assuming there is a web application:
 
-For example, the layout F<views/layouts/main.tt>:
+     # MyApp.pm
+     package MyApp;
+     use Dancer2;
+     get '/' => sub {'OK'};
+     1;
 
-    <html>
-        <head>...</head>
-        <body>
-        <div id="header">
-        ...
-        </div>
+The following test I<base.t> is created:
 
-        <div id="content">
-        [% content %]
-        </div>
+     # base.t
+     use strict;
+     use warnings;
+     use Test::More tests => 2;
+     use Plack::Test;
+     use HTTP::Request;
+     use MyApp;
 
-        </body>
-    </html>
+Creating a coderef for the application using the C<to_app> keyword:
 
-You can tell your app which layout to use with C<layout: name> in the config
-file, or within your code:
+     my $app = MyApp->to_app;
+
+Creating a test object from L<Plack::Test> for the application:
+
+     my $test = Plack::Test->create($app);
+
+Creating the first request object and sending it to the test object
+to receive a response:
+
+     my $request  = HTTP::Request->new( GET => '/' );
+     my $response = $test->request($request);
+
+It can now be tested:
+
+     ok( $response->is_success, '[GET /] Successful request' );
+     is( $response->content, 'OK', '[GET /] Correct content' );
+
+=head3 Putting it together
 
-    set layout => 'main';
+     # base.t
+     use strict;
+     use warnings;
+     use Test::More;
+     use Plack::Test;
+     use HTTP::Request::Common;
+     use MyApp;
 
-You can control which layout to use (or whether to use a layout at all) for
-a specific request without altering the layout setting by passing an options
-hashref as the third param to the template keyword:
+     my $test     = Plack::Test->create( MyApp->to_app );
+     my $response = $test->request( GET '/' );
 
-    template 'index.tt', {}, { layout => undef };
+     ok( $response->is_success, '[GET /] Successful request' );
+     is( $response->content, 'OK', '[GET /] Correct content' );
 
-If your application is not mounted under root (C</>), you can use a
-C<before_template_render> hook instead of hardcoding the path into your
-application for your CSS, images and JavaScript:
+     done_testing();
 
-    hook before_template_render => sub {
-        my $tokens = shift;
-        $tokens->{uri_base} = request->base->path;
-    };
+=head1 Complete Guide to Keywords
 
-Then in your layout, modify your CSS inclusion as follows:
+Dancer2 provides you with a DSL (Domain-Specific Language) which makes
+implementing your web application trivial.
 
-    <link rel="stylesheet" href="[% uri_base %]/css/style.css" />
+For example, take the following example:
 
-From now on you can mount your application wherever you want, without any
-further modification of the CSS inclusion.
+    use Dancer2;
 
-=head2 Encoding
+    get '/hello/:name' => sub {
+        my $name = route_parameters->get('name');
+    };
+    dance;
 
-If you use L<Plack> and have a Unicode problem with your Dancer2
-application, don't forget to check if you have set your template engine to
-use Unicode, and set the default charset to UTF-8. So, if you are using
-template toolkit, your config file will look like this:
+C<get> and C<route_parameters> are keywords provided by Dancer2.
 
-    charset: UTF-8
-    engines:
-      template:
-        template_toolkit:
-          ENCODING: utf8
+See L<Dancer2::Manual::Keywords/DSL Keywords manual> for a complete list of
+keywords provided by Dancer2.
 
+=head1 Plugins
 
-=head2 Default Template Variables
+TODO
 
-Every template knows about the following variables, which are provided by
-L<Dancer2::Core::Role::Template>. Some are similar to the keywords you can
-use in the Perl part of your Dancer2 application.
+=head1 Advanced Topics
 
-=over 4
+TODO
 
-=item * B<perl_version>
+=head2 Growing your apps with appname
 
-Current version of perl, effectively
-L<C<$^V>|http://perldoc.perl.org/perlvar.html#%24%5eV>.
+An app in Dancer2 uses the class name (defined by the C<package> function) to
+define the App name. Thus separating the App to multiple files, actually means
+creating multiple applications. This means that any engine defined in an application,
+because the application is a complete separate scope, will not be available to a
+different application:
 
-=item * B<dancer_version>
+     package MyApp::User {
+         use Dancer2;
+         set serializer => 'JSON';
+         get '/view' => sub {...};
+     }
 
-Current version of Dancer2, effectively C<< Dancer2->VERSION >>.
+     package MyApp::User::Edit {
+         use Dancer2;
+         get '/edit' => sub {...};
+     }
 
-=item * B<settings>
+These are two different Dancer2 Apps. They have different scopes, contexts,
+and thus different engines. While C<MyApp::User> has a serializer defined,
+C<MyApp::User::Edit> will not have that configuration.
 
-A hash of the application configuration. This is like
-the L<config|Dancer2::Manual/config> keyword.
+By using the import option C<appname>, we can ask Dancer2 to extend an
+App without creating a new one:
 
-=item * B<request>
+     package MyApp::User {
+         use Dancer2;
+         set serializer => 'JSON';
+         get '/view' => sub {...};
+     }
 
-The current request object. This is like the L<request|Dancer2::Manual/request> keyword.
+     package MyApp::User::Edit {
+         use Dancer2 appname => 'MyApp::User'; # extending MyApp::User
+         get '/edit' => sub {...};
+     }
 
-=item * B<params>
+The import option C<appname> allows you to seamlessly extend Dancer2 Apps
+without creating unnecessary additional applications or repeat any definitions.
+This allows you to spread your application routes across multiple files and allow
+ease of mind when developing it, and accommodate multiple developers working
+on the same codebase.
 
-A hash reference of all the parameters.
+     # app.pl
+     use MyApp::User;
+     use MyApp::User::Edit;
 
-Currently the equivalent of C<< $request->params >>, and like the
-L<params|Dancer2::Manual/params> keyword.
+     # single application composed of routes provided in multiple files
+     MyApp::User->to_app;
 
-=item * B<vars>
+This way only one class needs to be loaded while creating an app:
 
-The list of request variables, which is what you would get if you
-called the L<vars|Dancer2::Manual/vars> keyword.
+     # app.pl:
+     use MyApp::User;
+     MyApp::User->to_app;
 
-=item * B<session>
+=head2 Hooks
 
-The current session data, if a session exists. This is like
-the L<session|Dancer2::Manual/session> keyword.
+Hooks are code references (or anonymous subroutines) that are triggered at
+specific moments during the resolution of a request.  They are set up using the
+L<hook|Dancer2::Manual::Keywords/hook> keyword.
 
-=back
+Many of them are provided by Dancer2's core, but plugins and engines can also
+define their own.
 
-=head1 STATIC FILES
+=over 4
 
-=head2 Static Directory
+=head3 Serializers
 
-Static files are served from the F<./public> directory. You can specify a
-different location by setting the C<public_dir> option:
+When writing a webservice, data serialization/deserialization is a common
+issue to deal with. Dancer2 can automatically handle that for you, via a
+serializer.
 
-    set public_dir => path( app->location , 'static' );
+When setting up a serializer, a new behaviour is authorized for any route
+handler you define: any non-scalar response will be rendered as a serialized
+string, via the current serializer.
 
-When you modify default public_dir you have to set C<static_handler> option.
+Here is an example of a route handler that will return a hashref:
 
-    set static_handler => true;
+    use Dancer2;
+    set serializer => 'JSON';
 
-Note that the public directory name is not included in the URL. A file
-F<./public/css/style.css> is made available as
-L<http://example.com/css/style.css>.
+    get '/user/:id/' => sub {
+        { foo => 42,
+          number => 100234,
+          list => [qw(one two three)],
+        }
+    };
 
-=head2 Static File from a Route Handler
+Dancer2 will render the response via the current serializer.
 
-It's possible for a route handler to send a static file, as follows:
+Hence, with the JSON serializer set, the route handler above would result in
+a content like the following:
 
-    get '/download/*' => sub {
-        my ($file) = splat;
+    {"number":100234,"foo":42,"list":["one","two","three"]}
 
-        send_file $file;
-    };
+If you send a value which is validated serialized data, but is not in the
+form a key and value pair (such as a serialized string or a JSON array), the
+data will not be available in C<params> but will be available in
+C<< request->data >>.
 
-Or even if you want your index page to be a plain old F<index.html> file,
-just do:
+The following serializers are available, be aware they dynamically depend on
+Perl modules you may not have on your system.
 
-    get '/' => sub {
-        send_file '/index.html'
-    };
+=over 4
 
+=item * B<JSON>
 
-=head1 FILE UPLOADS
+Requires L<JSON>.
 
-Files are uploaded in Dancer2 using the class L<Dancer2::Core::Request::Upload>.
-The objects are accessible within the route handlers using the C<upload>
-keyword:
+=item * B<YAML>
 
-    post '/upload' => sub {
-        my $upload     = upload('file_input_name');    # upload object
-        $upload->copy_to('Uploads/');
-    };
+Requires L<YAML>,
 
-=head1 CONFIGURATION
+=item * B<XML>
 
-=head2 Configuration and environments
+Requires L<XML::Simple>.
 
-Configuring a Dancer2 application can be done in many ways. The easiest one
-(and maybe the dirtiest) is to put all your settings statements at the top
-of your script, before calling the C<dance()> method.
+=item * B<Mutable>
 
-Other ways are possible: for example, you can define all your settings in the file
-C<appdir/config.yml>. For this, you must have installed the L<YAML> module, and
-of course, write the config file in YAML.
+Will try to find the appropriate serializer using the B<Content-Type> and
+B<Accept-type> header of the request.
 
-That's better than the first option, but it's still not perfect as you can't
-switch easily from an environment to another without rewriting the config
-file.
+=back
 
-A better solution is to have one F<config.yml> file with default global
-settings, like the following:
+=item * C<before> hooks
 
-    # appdir/config.yml
-    logger: 'file'
-    layout: 'main'
+C<before> hooks are evaluated before each request within the context of the
+request and receives as argument the app (a L<Dancer2::Core::App> object).
 
-And then write as many environment files as you like in
-C<appdir/environments>. That way, the appropriate environment config file
-will be loaded according to the running environment (if none is specified,
-it will be 'development').
+It's possible to define variables which will be accessible in the action
+blocks with the L<var keyword|Dancer2::Manual::Keywords/var>.
 
-You can change the running environment when starting your app using the
-C<plackup> command's C<--env> or C<--E> switch:
+    hook before => sub {
+        var note => 'Hi there';
+    };
 
-    plackup -E production bin/app.psgi
+    get '/foo/*' => sub {
+        my ($match) = splat; # 'oversee';
+        vars->{note};        # 'Hi there'
+    };
 
-Altenatively, you can set the
-L<C<DANCER_ENVIRONMENT>|https://metacpan.org/pod/Dancer2::Config#DANCER_ENVIRONMENT>
-environment variable in the shell or in your web server's configuration file.
+For another example, this can be used along with session support to easily
+give non-logged-in users a login page:
 
-Typically, you'll want to set the following values in a development config
-file:
+    hook before => sub {
+        if (!session('user') && request->path !~ m{^/login}) {
+            # Pass the original path requested along to the handler:
+            forward '/login', { requested_path => request->path };
+        }
+    };
 
-    # appdir/environments/development.yml
-    log: 'debug'
-    startup_info: 1
-    show_stacktrace:  1
+The request keyword returns the current L<Dancer2::Core::Request> object
+representing the incoming request.
 
-And in a production one:
+=item * C<after> hooks
 
-    # appdir/environments/production.yml
-    log: 'warning'
-    startup_info: 0
-    show_stacktrace:  0
+C<after> hooks are evaluated after the response has been built by a route
+handler, and can alter the response itself, just before it's sent to the
+client.
 
-Please note that you are not limited to writing configuration files in YAML.
-Dancer2 supports any file format that is supported by L<Config::Any>, such
-as JSON, XML, INI files, and Apache-style config files. See the Dancer2
-L<configuration guide|https://metacpan.org/pod/Dancer2::Config#MANIPULATING-SETTINGS-VIA-CONFIGURATION-FILES>
-for more information.
+This hook runs after a request has been processed, but before the response
+is sent.
 
-=head2 Accessing configuration information
+It receives a L<Dancer2::Core::Response> object, which it can modify if it
+needs to make changes to the response which is about to be sent.
 
-A Dancer2 application can use the C<config> keyword to easily access the
-settings within its config file, for instance:
+The hook can use other keywords in order to do whatever it wants.
 
-    get '/appname' => sub {
-        return "This is " . config->{appname};
+    hook after => sub {
+        response->content(
+            q{The "after" hook can alter the response's content here!}
+        );
     };
 
-This makes keeping your application's settings all in one place simple and
-easy - you shouldn't need to worry about implementing all that yourself. :)
-
-=head2 Settings
+=back
 
-It's possible to change almost every parameter of the application via the
-settings mechanism.
+=head3 Templates
 
-A setting is a key/value pair assigned by the keyword B<set>:
+=over 4
 
-    set setting_name => 'setting_value';
+=item * C<before_template_render>
 
-More usefully, settings can be defined in a configuration file.
-Environment-specific settings can also be defined in environment-specific
-files (for instance, you do not want to show error stacktraces in
-production, and might want extra logging in development).
+C<before_template_render> hooks are called whenever a template is going to
+be processed, they are passed the tokens hash which they can alter.
 
-=head2 Serializers
+    hook before_template_render => sub {
+        my $tokens = shift;
+        $tokens->{foo} = 'bar';
+    };
 
-When writing a webservice, data serialization/deserialization is a common
-issue to deal with. Dancer2 can automatically handle that for you, via a
-serializer.
+The tokens hash will then be passed to the template with all the
+modifications performed by the hook. This is a good way to setup some
+global vars you like to have in all your templates, like the name of the
+user logged in or a section name.
 
-When setting up a serializer, a new behaviour is authorized for any route
-handler you define: any non-scalar response will be rendered as a serialized
-string, via the current serializer.
+=item * C<after_template_render>
 
-Here is an example of a route handler that will return a hashref:
+C<after_template_render> hooks are called after the view has been rendered.
+They receive as their first argument the reference to the content that has
+been produced. This can be used to post-process the content rendered by the
+template engine.
 
-    use Dancer2;
-    set serializer => 'JSON';
+    hook after_template_render => sub {
+        my $ref_content = shift;
+        my $content     = ${$ref_content};
 
-    get '/user/:id/' => sub {
-        { foo => 42,
-          number => 100234,
-          list => [qw(one two three)],
-        }
+        # do something with $content
+        ${$ref_content} = $content;
     };
 
-Dancer2 will render the response via the current serializer.
+=item * C<before_layout_render>
 
-Hence, with the JSON serializer set, the route handler above would result in
-a content like the following:
+C<before_layout_render> hooks are called whenever the layout is going to be
+applied to the current content. The arguments received by the hook are the
+current tokens hashref and a reference to the current content.
 
-    {"number":100234,"foo":42,"list":["one","two","three"]}
+    hook before_layout_render => sub {
+        my ($tokens, $ref_content) = @_;
+        $tokens->{new_stuff} = 42;
+        $ref_content = \"new content";
+    };
 
-If you send a value which is validated serialized data, but is not in the
-form a key and value pair (such as a serialized string or a JSON array), the
-data will not be available in C<params> but will be available in
-C<< request->data >>.
+=item * C<after_layout_render>
 
-The following serializers are available, be aware they dynamically depend on
-Perl modules you may not have on your system.
+C<after_layout_render> hooks are called once the complete content of the
+view has been produced, after the layout has been applied to the content.
+The argument received by the hook is a reference to the complete content
+string.
 
-=over 4
+    hook after_layout_render => sub {
+        my $ref_content = shift;
+        # do something with ${ $ref_content }, which reflects directly
+        #   in the caller
+    };
 
-=item * B<JSON>
+=back
 
-Requires L<JSON>.
+=head3 Error Handling
 
-=item * B<YAML>
+Refer to L<Error Hooks|Dancer2::Manual/Error-Hooks>
+for details about the following hooks:
 
-Requires L<YAML>,
+=over 4
 
-=item * B<XML>
+=item * C<init_error>
 
-Requires L<XML::Simple>.
+=item * C<before_error>
 
-=item * B<Mutable>
+=item * C<after_error>
 
-Will try to find the appropriate serializer using the B<Content-Type> and
-B<Accept-type> header of the request.
+=item * C<on_route_exception>
 
 =back
 
-=head2 Importing using Appname
+=head2 File Rendering
 
-An app in Dancer2 uses the class name (defined by the C<package> function) to
-define the App name. Thus separating the App to multiple files, actually means
-creating multiple applications. This means that any engine defined in an application,
-because the application is a complete separate scope, will not be available to a
-different application:
+Refer to L<File Handler|Dancer2::Manual/File-Handler>
+for details on the following hooks:
 
-     package MyApp::User {
-         use Dancer2;
-         set serializer => 'JSON';
-         get '/view' => sub {...};
-     }
+=over 4
 
-     package MyApp::User::Edit {
-         use Dancer2;
-         get '/edit' => sub {...};
-     }
+=item * C<before_file_render>
 
-These are two different Dancer2 Apps. They have different scopes, contexts,
-and thus different engines. While C<MyApp::User> has a serializer defined,
-C<MyApp::User::Edit> will not have that configuration.
+=item * C<after_file_render>
 
-By using the import option C<appname>, we can ask Dancer2 to extend an
-App without creating a new one:
+=back
 
-     package MyApp::User {
-         use Dancer2;
-         set serializer => 'JSON';
-         get '/view' => sub {...};
-     }
+=head2 Logging
 
-     package MyApp::User::Edit {
-         use Dancer2 appname => 'MyApp::User'; # extending MyApp::User
-         get '/edit' => sub {...};
-     }
+Logging hooks do not allow you to alter log message content, but they do
+give you a place to perform extra actions. For example, if you want to send
+an email for error messages, but you don't want to use a heavier logger
+such as L<Log::Any> or L<Log::Log4perl>:
 
-The import option C<appname> allows you to seamlessly extend Dancer2 Apps
-without creating unnecessary additional applications or repeat any definitions.
-This allows you to spread your application routes across multiple files and allow
-ease of mind when developing it, and accommodate multiple developers working
-on the same codebase.
+    hook 'engine.logger.after' => sub {
+        my ( $logger, $level, $message ) = @_;
 
-     # app.pl
-     use MyApp::User;
-     use MyApp::User::Edit;
+        if( $level eq 'error' ) {
+            # Send an email with the message content
+        }
+    };
 
-     # single application composed of routes provided in multiple files
-     MyApp::User->to_app;
+There are two hooks available for logging:
 
-This way only one class needs to be loaded while creating an app:
+=over 4
 
-     # app.pl:
-     use MyApp::User;
-     MyApp::User->to_app;
+=item * engine.logger.before
 
-=head1 LOGGING
+This hook is called before a log message is produced.
 
-=head2 Configuring logging
+=item * engine.logger.after
 
-It's possible to log messages generated by the application and by Dancer2
-itself.
+This hook is called after a log message is produced.
 
-To start logging, select the logging engine you wish to use with the
-C<logger> setting; Dancer2 includes built-in log engines named C<file> and
-C<console>, which log to a logfile and to the console respectively.
+=back
 
-To enable logging to a file, add the following to your config file:
+=head3 Serializers
 
-    logger: 'file'
+=over 4
 
-Then you can choose which kind of messages you want to actually log:
+=item * C<before_serializer> is called before serializing the content, and receives
+the content to serialize as an argument.
 
-    log: 'core'      # will log debug, info, warnings, errors,
-                     #   and messages from Dancer2 itself
-    log: 'debug'     # will log debug, info, warning and errors
-    log: 'info'      # will log info, warning and errors
-    log: 'warning'   # will log warning and errors
-    log: 'error'     # will log only errors
+  hook before_serializer => sub {
+    my $content = shift;
+    ...
+  };
 
-If you're using the C<file> logging engine, a directory C<appdir/logs> will
-be created and will host one logfile per environment. The log message
-contains the time it was written, the PID of the current process, the
-message and the caller information (file and line).
+=item * C<after_serializer> is called after the payload has been serialized, and
+receives the serialized content as an argument.
 
-=head2 Logging your own messages
+  hook after_serializer => sub {
+    my $serialized_content = shift;
+    ...
+  };
 
-Just call L<debug|https://metacpan.org/pod/Dancer2::Manual#debug>,
-L<info|https://metacpan.org/pod/Dancer2::Manual#info>,
-L<warning|https://metacpan.org/pod/Dancer2::Manual#warning> or
-L<error|https://metacpan.org/pod/Dancer2::Manual#error> with your message:
+=back
 
-    debug "This is a debug message from my app.";
+=head2 Exports
 
+By default, C<use Dancer2> exports all the DSL keywords and sets up the
+webapp under the name of the current package. The following tags control
+exports and webapp namespace.
 
-=head1 Testing
+=over 4
 
-=head2 Using Plack::Test
+=item * B<!keyword>
 
-L<Plack::Test> receives a common web request (using standard L<HTTP::Request>
-objects), fakes a web server in order to create a proper PSGI request, and sends it
-to the web application. When the web application returns a PSGI response
-(which Dancer applications do), it will then convert it to a common web response
-(as a standard L<HTTP::Response> object).
+If you want to prevent Dancer2 from exporting specific keywords (perhaps you
+plan to implement them yourself in a different way, or they clash with
+another module you're loading), you can simply exclude them:
 
-This allows you to then create requests in your test, create the code reference
-for your web application, call them, and receive a response object, which can
-then be tested.
+    use Test::More;
+    use Dancer2 qw(!pass);
 
-=head3 Basic Example
+The above would import all keywords as usual, with the exception of C<pass>.
 
-Assuming there is a web application:
+=item * B<appname>
+
+A larger application may split its source between several packages to aid
+maintainability. Dancer2 will create a separate application for each
+package, each having separate hooks, config and/or engines. You can force
+Dancer2 to collect the route and hooks into a single application with the
+C<appname> tag; e.g.
+
+    package MyApp;
+    use Dancer2;
+    get '/foo' => sub {...};
 
-     # MyApp.pm
-     package MyApp;
-     use Dancer2;
-     get '/' => sub {'OK'};
-     1;
+    package MyApp::Private;
+    use Dancer2 appname => MyApp;
+    get '/bar' => sub {...};
 
-The following test I<base.t> is created:
+The above would add the C<bar> route to the MyApp application. Dancer2 will
+I<not> create an application with the name C<MyApp::Private>.
 
-     # base.t
-     use strict;
-     use warnings;
-     use Test::More tests => 2;
-     use Plack::Test;
-     use HTTP::Request;
-     use MyApp;
+=item * B<:nopragmas>
 
-Creating a coderef for the application using the C<to_app> keyword:
+By default L<Dancer2> will import three pragmas: L<strict>, L<warnings>,
+and L<utf8>. If you require control over the imported pragmas, you can add
+B<:nopragmas> to the importing flags, in which case Dancer2 will not import
+any pragmas:
 
-     my $app = MyApp->to_app;
+    use strict;
+    use warnings;
+    no warnings 'experimental::smartmatch'; # for example...
+    use Dancer2 ':nopragmas'; # do not touch the existing pragmas
 
-Creating a test object from L<Plack::Test> for the application:
+This way importing C<Dancer2> does not change the existing pragmas setup
+you have.
 
-     my $test = Plack::Test->create($app);
+=back
 
-Creating the first request object and sending it to the test object
-to receive a response:
+When you C<use Dancer2>, you get an C<import> method added into the current
+package. This B<will> override previously declared import methods from other
+sources, such as L<Exporter>. Dancer2 applications support the following
+tags on import:
 
-     my $request  = HTTP::Request->new( GET => '/' );
-     my $response = $test->request($request);
+=over 4
 
-It can now be tested:
+=item * B<with>
 
-     ok( $response->is_success, '[GET /] Successful request' );
-     is( $response->content, 'OK', '[GET /] Correct content' );
+The C<with> tag allows an app to pass one or more config entries to another
+app, when it C<use>s it.
 
-=head3 Putting it together
+    package MyApp;
+    use Dancer2;
 
-     # base.t
-     use strict;
-     use warnings;
-     use Test::More;
-     use Plack::Test;
-     use HTTP::Request::Common;
-     use MyApp;
+    BEGIN { set session => 'YAML' };
+    use Blog with => { session => engine('session') };
 
-     my $test     = Plack::Test->create( MyApp->to_app );
-     my $response = $test->request( GET '/' );
+In this example, the session engine is passed to the C<Blog> app. That way,
+anything done in the session will be shared between both apps.
 
-     ok( $response->is_success, '[GET /] Successful request' );
-     is( $response->content, 'OK', '[GET /] Correct content' );
+Anything that is defined in the config entry can be passed that way. If we
+want to pass the whole config object, it can be done like so:
 
-     done_testing();
+    use SomeApp with => { %{config()} };
 
-=head1 MIDDLEWARES
+=back
 
-=head2 Plack middlewares
+=head2 Middleware
 
 If you want to use Plack middlewares, you need to enable them using
 L<Plack::Builder> as such:
@@ -1733,7 +1717,7 @@ before and after enabling this middleware. Among other things, you should
 notice that the response is gzip or deflate encoded, and contains a header
 C<Content-Encoding> set to C<gzip> or C<deflate>.
 
-=head3 Running multiple apps with Plack::Builder
+=head2 Running multiple apps with Plack::Builder
 
 You can use L<Plack::Builder> to mount multiple Dancer2 applications on a
 L<PSGI> webserver like L<Starman>.
@@ -1757,116 +1741,129 @@ Currently this still demands the same appdir for both (default circumstance)
 but in a future version this will be easier to change while staying very
 simple to mount.
 
-=head1 Complete Guide to Keywords
-
-Dancer2 provides you with a DSL (Domain-Specific Language) which makes
-implementing your web application trivial.
-
-For example, take the following example:
-
-    use Dancer2;
-
-    get '/hello/:name' => sub {
-        my $name = route_parameters->get('name');
-    };
-    dance;
-
-C<get> and C<route_parameters> are keywords provided by Dancer2.
-
-See L<Dancer2::Manual::Keywords/DSL Keywords manual> for a complete list of
-keywords provided by Dancer2.
-
-=head1 Plugins
-
-TODO
-
-=head1 Advanced Topics
-
-TODO
+=head2 Async/Streaming/Delayed Responses
 
-=head2 Exports
+L<Dancer2> can provide delayed (otherwise known as I<asynchronous>) responses
+using the C<delayed> keyword. These responses are streamed, although you can
+set the content all at once, if you prefer.
 
-By default, C<use Dancer2> exports all the DSL keywords and sets up the
-webapp under the name of the current package. The following tags control
-exports and webapp namespace.
+    get '/status' => sub {
+        delayed {
+            response_header 'X-Foo' => 'Bar';
 
-=over 4
+            # flush headers (in case of streaming)
+            flush;
 
-=item * B<!keyword>
+            # send content to the user
+            content 'Hello, world!';
 
-If you want to prevent Dancer2 from exporting specific keywords (perhaps you
-plan to implement them yourself in a different way, or they clash with
-another module you're loading), you can simply exclude them:
+            # you can write more content
+            # all streaming
+            content 'Hello, again!';
 
-    use Test::More;
-    use Dancer2 qw(!pass);
+            # when done, close the connection
+            done;
 
-The above would import all keywords as usual, with the exception of C<pass>.
+            # do whatever you want else, asynchronously
+            # the user socket closed by now
+            ...
+        };
+    };
 
-=item * B<appname>
+If you are streaming (calling C<content> several times), you must call
+C<flush> first. If you're sending only once, you don't need to call C<flush>.
 
-A larger application may split its source between several packages to aid
-maintainability. Dancer2 will create a separate application for each
-package, each having separate hooks, config and/or engines. You can force
-Dancer2 to collect the route and hooks into a single application with the
-C<appname> tag; e.g.
+Here is an example of using delayed responses with L<AnyEvent>:
 
-    package MyApp;
     use Dancer2;
-    get '/foo' => sub {...};
-
-    package MyApp::Private;
-    use Dancer2 appname => MyApp;
-    get '/bar' => sub {...};
-
-The above would add the C<bar> route to the MyApp application. Dancer2 will
-I<not> create an application with the name C<MyApp::Private>.
-
-=item * B<:nopragmas>
+    use AnyEvent;
 
-By default L<Dancer2> will import three pragmas: L<strict>, L<warnings>,
-and L<utf8>. If you require control over the imported pragmas, you can add
-B<:nopragmas> to the importing flags, in which case Dancer2 will not import
-any pragmas:
+    my %timers;
+    my $count = 5;
+    get '/drums' => sub {
+        delayed {
+            print "Stretching...\n";
+            flush; # necessary, since we're streaming
 
-    use strict;
-    use warnings;
-    no warnings 'experimental::smartmatch'; # for example...
-    use Dancer2 ':nopragmas'; # do not touch the existing pragmas
+            $timers{'Snare'} = AE::timer 1, 1, delayed {
+                $timers{'HiHat'} ||= AE::timer 0, 0.5, delayed {
+                    content "Tss...\n";
+                };
 
-This way importing C<Dancer2> does not change the existing pragmas setup
-you have.
+                content "Bap!\n";
 
-=back
+                if ( $count-- == 0 ) {
+                    %timers = ();
+                    content "Tugu tugu tugu dum!\n";
+                    done;
 
-When you C<use Dancer2>, you get an C<import> method added into the current
-package. This B<will> override previously declared import methods from other
-sources, such as L<Exporter>. Dancer2 applications support the following
-tags on import:
+                    print "<enter sound of applause>\n\n";
+                    $timers{'Applause'} = AE::timer 3, 0, sub {
+                        # the DSL will not available here
+                        # because we didn't call the "delayed" keyword
+                        print "<applause dies out>\n";
+                    };
+                }
+            };
+        };
+    };
 
-=over 4
+If an error happens during a write operation, a warning will be issued
+to the logger.
 
-=item * B<with>
+You can handle the error yourself by providing an C<on_error> handler:
 
-The C<with> tag allows an app to pass one or more config entries to another
-app, when it C<use>s it.
+    get '/' => sub {
+        delayed {
+            flush;
+            content "works";
 
-    package MyApp;
-    use Dancer2;
+            # ... user disconnected here ...
 
-    BEGIN { set session => 'YAML' };
-    use Blog with => { session => engine('session') };
+            content "fails";
 
-In this example, the session engine is passed to the C<Blog> app. That way,
-anything done in the session will be shared between both apps.
+            # ... error triggered ...
 
-Anything that is defined in the config entry can be passed that way. If we
-want to pass the whole config object, it can be done like so:
+            done; # doesn't even get run
+        } on_error => sub {
+            # delayed{} not needed, DSL already available
+            my ($error) = @_;
+            # do something with $error
+        };
+    };
 
-    use SomeApp with => { %{config()} };
+Here is an example that asynchronously streams the contents of a CSV file:
 
-=back
+    use Dancer2;
+    use Text::CSV_XS  qw< csv >;
+    use Path::Tiny    qw< path >;
+    use JSON::MaybeXS qw< encode_json >;
+    # Create CSV parser
+    my $csv = Text::CSV_XS->new({
+        binary    => 1,
+        auto_diag => 1,
+    });
+    get '/' => sub {
+        # delayed response:
+        delayed {
+            # streaming content
+            flush;
+            # Read each row and stream it in JSON
+            my $fh = path('filename.csv')->openr_utf8;
+            while ( my $row = $csv->getline($fh) ) {
+                content encode_json $row;
+            }
+            # close user connection
+            done;
+        } on_error => sub {
+            my ($error) = @_;
+            warning 'Failed to stream to user: ' . request->remote_address;
+        };
+    };
 
+B<NOTE:> If you just want to send a file's contents asynchronously,
+use C<send_file($filename)> instead of C<delayed>, as it will
+automatically take advantage of any asynchronous capability.
 
 =head1 Extending Dancer2