The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Dancer2::Manual - A gentle introduction to Dancer2

VERSION

version 2.000001

DESCRIPTION

Dancer2 is a free and open source micro web application framework written in Perl.

It's a complete rewrite of Dancer based on Moo.

INSTALL

Installation of Dancer2 is simple:

    perl -MCPAN -e 'install Dancer2'

Thanks to the magic of cpanminus, if you do not have CPAN.pm configured, or just want a quickfire way to get running, the following should work, at least on Unix-like systems:

    wget -O - http://cpanmin.us | sudo perl - Dancer2

(If you don't have root access, omit the 'sudo', and cpanminus will install Dancer2 and prereqs into ~/perl5.)

BOOTSTRAPING

In this current version, Dancer2 does not provide a helper script to bootstrap an application structre, but that will come soon as a separate distribution (probably Dancer2::Bootstrap).

Meanwhile, you can use Dancer's original helper script as very few changes are necessary to make the app work with Dancer2:

Create a web application using the dancer script (found in Dancer):

    dancer -a MyApp && cd MyApp

Replace Dancer by Dancer2 in the application's code:

    for f in $(find {lib,bin} -type f) ; do cat $f | sed -e 's/Dancer/Dancer2/g' > $f.2 && mv $f.2 $f; done

And voilà!

You can now run the web application:

    bin/app.pl

View the web application at:

    http://localhost:3000

Note that as Dancer2 supports the PSGI specification, you can also use the plackup tool (provided by Plack) for launching the application:

    plackup ./bin/app.pl -p 5000

USAGE

When Dancer2 is imported to a script, that script becomes a webapp, and at this point, all the script has to do is declare a list of routes. A route handler is composed by an HTTP method, a path pattern and a code block. strict and warnings pragmas are also imported with Dancer2.

The code block given to the route handler has to return a string which will be used as the content to render to the client.

Routes are defined for a given HTTP method. For each method supported, a keyword is exported by the module.

The following is an example of a route definition. The route is defined for the method 'get', so only GET requests will be honoured by that route:

    get '/hello/:name' => sub {
        # do something

        return "Hello ".param('name');
    };

HTTP METHODS

Here are some of the standard HTTP methods which you can use to define your route handlers.

GET The GET method retrieves information (when defining a route handler for the GET method, Dancer2 automatically defines a route handler for the HEAD method, in order to honour HEAD requests for each of your GET route handlers). To define a GET action, use the get keyword.
POST The POST method is used to create a resource on the server. To define a POST action, use the post keyword.
PUT The PUT method is used to update an existing resource. To define a PUT action, use the put keyword.
DELETE The DELETE method requests that the origin server delete the resource identified by the Request-URI. To define a DELETE action, use the del keyword.

To define a route for multiple methods you can also use the special keyword any. This example illustrates how to define a route for both GET and POST methods:

    any ['get', 'post'] => '/myaction' => sub {
        # code
    };

Or even, a route handler that would match any HTTP methods:

    any '/myaction' => sub {
        # code
    };

ROUTE HANDLERS

The route action is the code reference declared. It can access parameters through the `params' keyword, which returns a hashref. This hashref is a merge of the route pattern matches and the request params.

You can have more details about how params are built and how to access them in the Dancer2::Request documentation.

NAMED MATCHING

A route pattern can contain one or more tokens (a word prefixed with ':'). Each token found in a route pattern is used as a named-pattern match. Any match will be set in the params hashref.

    get '/hello/:name' => sub {
        "Hey ".param('name').", welcome here!";
    };

Tokens can be optional, for example:

    get '/hello/:name?' => sub {
        "Hello there " . param('name') || "whoever you are!";
    };

WILDCARDS MATCHING

A route can contain a wildcard (represented by a '*'). Each wildcard match will be returned in an arrayref, accessible via the `splat' keyword.

    get '/download/*.*' => sub {
        my ($file, $ext) = splat;
        # do something with $file.$ext here
    };

REGULAR EXPRESSION MATCHING

A route can be defined with a Perl regular expression.

In order to tell Dancer2 to consider the route as a real regexp, the route must be defined explicitly with qr{}, like the following:

    get qr{/hello/([\w]+)} => sub {
        my ($name) = splat;
        return "Hello $name";
    };

CONDITIONAL MATCHING

Routes may include some matching conditions (on the useragent and the hostname at the moment):

    get '/foo', {agent => 'Songbird (\d\.\d)[\d\/]*?'} => sub {
      'foo method for songbird'
    }

    get '/foo' => sub {
      'all browsers except songbird'
    }

PREFIX

A prefix can be defined for each route handler, like this:

    prefix '/home';

From here, any route handler is defined to /home/*

    get '/page1' => sub {}; # will match '/home/page1'

You can unset the prefix value

    prefix '/'; # or: prefix undef;
    get '/page1' => sub {}; will match /page1

Alternatively, to prevent you from ever forgetting to undef the prefix, you can use lexical prefix like this:

    prefix '/home' => sub {
      get '/page1' => sub {}; # will match '/home/page1'
    }; ## prefix reset to previous value on exit

    get '/page1' => sub {}; will match /page1

ACTION SKIPPING

An action can choose not to serve the current request and ask Dancer2 to process the request with the next matching route.

This is done with the pass keyword, like in the following example

    get '/say/:word' => sub {
        return pass if (params->{word} =~ /^\d+$/);
        "I say a word: ".params->{word};
    };

    get '/say/:number' => sub {
        "I say a number: ".params->{number};
    };

DEFAULT ERROR PAGES

When an error is rendered (the action responded with a status code different than 200), Dancer2 first looks in the public directory for an HTML file matching the error code (eg: 500.html or 404.html).

If such a file exists, it's used to render the error, otherwise, a default error page will be rendered on the fly.

EXECUTION ERRORS

When an error occurs during the route execution, Dancer2 will render an error page with the HTTP status code 500.

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 set with the show_errors setting.

Note that you can also choose to consider all warnings in your route handlers as errors when the setting warnings is set to 1.

HOOKS

Hooks are code references (or anonymous subroutines) that are triggered at specific moments during the resolution of a request.

Many of them are supported by the core but plugins and engines can also define their own.

For documentation about all supported hooks, please refer to Dancer2::Manual::Hooks.

CONFIGURATION AND ENVIRONMENTS

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 dance() method.

Other ways are possible. You could write all your setting calls in the file `appdir/config.yml'. You would, of course, have write the conffile in YAML.

While better than the first option, it's still not perfect. You can't easily switch from an environment to another (for example, from development to production) without rewriting the config.yml file. The best way is to have one config.yml file with default global settings, like the following:

    # appdir/config.yml
    logger: 'file'
    layout: 'main'

And then write as many environment files as you like in appdir/environments. That way, the appropriate environment config file will be loaded according to the running environment (if none is specified, 'development' is assumed).

Note that you can change the running environment using the --environment commandline switch.

Typically, you'll want to set the following values in a development config file:

    # appdir/environments/development.yml
    log: 'debug'
    startup_info: 1
    show_errors:  1

And in a production one:

    # appdir/environments/production.yml
    log: 'warning'
    startup_info: 0
    show_errors:  0

Please note that you are not limited to writing configuration files in YAML. Dancer2 supports any file format that is supported by " Config::Any ", such as JSON, XML, INI files, and Apache-style config files.

load

You can use the load method to include additional routes into your application:

    get '/go/:value', sub {
        # foo
    };

    load 'more_routes.pl';

    # then, in the file more_routes.pl:
    get '/yes', sub {
        'orly?';
    };

load is just a wrapper for require, but you can also specify a list of routes files:

    load 'login_routes.pl', 'session_routes.pl', 'misc_routes.pl';

Accessing configuration data

A Dancer2 application can access the information from its config file easily with the config keyword:

    get '/appname' => sub {
        return "This is " . config->{appname};
    };

Importing just the syntax

If you want to use more complex file hierarchies, you can import just the syntax of Dancer2.

    package App;

    use Dancer2;            # App may contain generic routes
    use App::User::Routes; # user-related routes

Then in App/User/Routes.pm:

    use Dancer2 ':syntax';

    get '/user/view/:id' => sub {
        ...
    };

LOGGING

It's possible to log messages sent by the application. In the current version, only one method is possible for logging messages but future releases may add additional logging methods, for instance logging to syslog.

In order to enable the logging system for your application, you first have to start the logger engine in your config file:

    logger: 'file'

Then you can choose which kind of messages you want to actually log:

    log: 'debug'     # will log debug, warning and errors
    log: 'warning'   # will log warning and errors
    log: 'error'     # will log only errors

A directory 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).

To log messages, use the debug, warning and error methods, for instance:

    debug "This is a debug message";

USING TEMPLATES

VIEWS

It's possible to render the action's content with a template; this is called a view. The `appdir/views' directory is the place where views are located.

You can change this location by changing the setting 'views', for instance if your templates are located in the 'templates' directory, do the following:

    set views => path(dirname(__FILE__), 'templates');

By default, the internal template engine is used (Dancer2::Template::Simple) but you may want to upgrade to Template::Toolkit. If you do so, you have to enable this engine in your settings as explained in Dancer2::Template::TemplateToolkit. If you do so, you'll also have to import the Template module in your application code. Note that Dancer2 configures the Template::Toolkit engine to use <% %> brackets instead of its default [% %] brackets, although you can change this in your config file.

All views must have a '.tt' extension. This may change in the future.

In order to render a view, just call the '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 the request, session and route params are automatically accessible in the view, named request, session and params):

    use Dancer2;
    use Template;

    get '/hello/:name' => sub {
        template 'hello' => { number => 42 };
    };

And the appdir/views/hello.tt view can contain the following code:

   <html>
    <head></head>
    <body>
        <h1>Hello <% params.name %></h1>
        <p>Your lucky number is <% number %></p>
        <p>You are using <% request.user_agent %></p>
        <% IF session.user %>
            <p>You're logged in as <% session.user %></p>
        <% END %>
    </body>
   </html>

LAYOUTS

A layout is a special view, located in the 'layouts' directory (inside the views directory) which must have a token named `content'. That token marks the place where to render the action view. This lets you define a global layout for your actions. Any tokens that you defined when you called the 'template' keyword are available in the layouts, as well as the standard session, request, and params tokens. This allows you to insert per-page content into the HTML boilerplate, such as page titles, current-page tags for navigation, etc.

Here is an example of a layout: views/layouts/main.tt:

    <html>
        <head><% page_title %></head>
        <body>
        <div id="header">
        ...
        </div>

        <div id="content">
        <% content %>
        </div>

        </body>
    </html>

This layout can be used like the following:

    use Dancer2;
    set layout => 'main';

    get '/' => sub {
        template 'index' => { page_title => "Your website Homepage" };
    };

Of course, if a layout is set, it can also be disabled for a specific action, like the following:

    use Dancer2;
    set layout => 'main';

    get '/nolayout' => sub {
        template 'some_ajax_view',
            { tokens_var => "42" },
            { layout => 0 };
    };

STATIC FILES

STATIC DIRECTORY

Static files are served from the ./public directory. You can specify a different location by setting the 'public' option:

    set public => path(dirname(__FILE__), 'static');

Note that the public directory name is not included in the URL. A file ./public/css/style.css is made available as example.com/css/style.css.

STATIC FILE FROM A ROUTE HANDLER

It's possible for a route handler to send a static file, as follows:

    get '/download/*' => sub {
        my $params = shift;
        my ($file) = @{ $params->{splat} };

        send_file $file;
    };

Or even if you want your index page to be a plain old index.html file, just do:

    get '/' => sub {
        send_file '/index.html'
    };

SETTINGS

It's possible to change quite every parameter of the application via the settings mechanism.

A setting is key/value pair assigned by the keyword set:

    set setting_name => 'setting_value';

More usefully, settings can be defined in a configuration file. Environment-specific settings can also be defined in environment-specific files (for instance, you don't want auto_reload in production, and might want extra logging in development). See the cookbook for examples.

SERIALIZERS

When writing a webservice, data serialization/deserialization is a common issue to deal with. Dancer2 can automatically handle that for you, via a serializer.

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.

Here is an example of a route handler that will return a HashRef

    use Dancer2;
    set serializer => 'JSON';

    get '/user/:id/' => sub {
        { foo => 42,
          number => 100234,
          list => [qw(one two three)],
        }
    };

As soon as the content is not a scalar - and a serializer is set, which is not the case by default - Dancer2 renders the response via the current serializer.

Hence, with the JSON serializer set, the route handler above would result in a content like the following:

    {"number":100234,"foo":42,"list":["one","two","three"]}

The following serializers are available, be aware they dynamically depend on Perl modules you may not have on your system.

JSON

requires JSON

YAML

requires YAML

XML

requires XML::Simple

Mutable

will try to find the appropriate serializer using the Content-Type and Accept-type header of the request.

EXAMPLE

This is a possible webapp created with Dancer2:

    #!/usr/bin/perl

    # make this script a webapp
    use Dancer2;

    # declare routes/actions
    get '/' => sub {
        "Hello World";
    };

    get '/hello/:name' => sub {
        "Hello ".param('name');
    };

    # run the webserver
    Dancer2->dance;

AUTHOR

Dancer Core Developers

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Alexis Sukrieh.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 57:

Non-ASCII character seen before =encoding in 'voilà!'. Assuming UTF-8

Around line 308:

L<> starts or ends with whitespace