The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Dancer-1.2003
River stage three • 214 direct dependents • 218 total dependents
149 ++
/ Dancer

NAME

Dancer - lightweight yet powerful web application framework

SYNOPSIS

    #!/usr/bin/perl
    use Dancer;

    get '/hello/:name' => sub {
        return "Why, hello there " . params->{name};
    };

    dance;

The above is a basic but functional web app created with Dancer. If you want to see more examples and get up and running quickly, check out the Dancer::Introduction and the Dancer::Cookbook. For examples on deploying your Dancer applications, see Dancer::Deployment.

DESCRIPTION

Dancer is a web application framework designed to be as effortless as possible for the developer, taking care of the boring bits as easily as possible, yet staying out of your way and letting you get on with writing your code.

Dancer aims to provide the simplest way for writing web applications, and offers the flexibility to scale between a very simple lightweight web service consisting of a few lines of code in a single file, all the way up to a more complex fully-fledged web application with session support, templates for views and layouts, etc.

If you don't want to write CGI scripts by hand, and find Catalyst too big or cumbersome for your project, Dancer is what you need.

Dancer has few pre-requisites, so your Dancer webapps will be easy to deploy.

Dancer apps can be used with a an embedded web server (great for easy testing), and can run under PSGI/Plack for easy deployment in a variety of webserver environments.

DISCLAIMER

This documentation describes all the exported symbols of Dancer. If you want a quick start guide to discover the framework, you should look at Dancer::Introduction.

If you want to have specific examples of code for real-life problems, see the Dancer::Cookbook.

If you want to see configuration examples of different deployment solutions involving Dancer and Plack, see Dancer::Deployment.

METHODS

after

Add a hook at the after position:

    after sub {
        my $response = shift;
        # do something with request
    };

The anonymous function which is given to after will be executed after having executed a route.

You can define multiple after filters, using the after helper as many times as you wish; each filter will be executed, in the order you added them.

any

Defines a route for multiple HTTP methods at once:

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

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

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

before

Defines a before filter:

    before sub {
        # do something with request, vars or params
    };

The anonymous function which is given to before will be executed before looking for a route handler to handle the request.

You can define multiple before filters, using the before helper as many times as you wish; each filter will be executed in the order you added them.

before_template

Defines a before_template filter:

    before_template sub {
        my $tokens = shift;
        # do something with request, vars or params
    };

The anonymous function which is given to before_template will be executed before sending data and tokens to the template. Receives a hashref of the tokens that will be inserted into the template.

This filter works as the before and after filter.

cookies

Accesses cookies values, which returns a hashref of Dancer::Cookie objects:

    get '/some_action' => sub {
        my $cookie = cookies->{name};
        return $cookie->value;
    };

config

Accesses the configuration of the application:

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

content_type

Sets the content-type rendered, for the current route handler:

    get '/cat/:txtfile' => sub {
        content_type 'text/plain';

        # here we can dump the contents of params->{txtfile}
    };

Note that if you want to change the default content-type for every route, you have to change the setting content_type instead.

dance

Alias for the start keyword.

debug

Logs a message of debug level:

    debug "This is a debug message";

dirname

Returns the dirname of the path given:

    my $dir = dirname($some_path);

error

Logs a message of error level:

    error "This is an error message";

false

Constant that returns a false value (0).

from_dumper ($structure)

Deserializes a Data::Dumper structure.

from_json ($structure, %options)

Deserializes a JSON structure. Can receive optional arguments. Thoses arguments are valid JSON arguments to change the behavior of the default JSON::from_json function.

from_yaml ($structure)

Deserializes a YAML structure.

from_xml ($structure, %options)

Deserializes a XML structure. Can receive optional arguments. Thoses arguments are valid XML::Simple arguments to change the behavior of the default XML::Simple::XMLin function.

get

Defines a route for HTTP GET requests to the given path:

    get '/' => sub {
        return "Hello world";
    }

halt

Sets a response object with the content given.

When used as a return value from a filter, this breaks the execution flow and renders the response immediatly:

    before sub {
        if ($some_condition) {
            return halt("Unauthorized");
        }
    };

    get '/' => sub {
        "hello there";
    };

headers

Adds custom headers to responses:

    get '/send/headers', sub {
        headers 'X-Foo' => 'bar', X-Bar => 'foo';
    }

Adds a custom header to response:

    get '/send/header', sub {
        header 'X-My-Header' => 'shazam!';
    }

layout

Allows you to set the default layout to use when rendering a view. Syntactic sugar around the layout setting:

    layout 'user';

logger

Allows you to set the logger engine to use. Syntactic sugar around the logger setting:

    logger 'console';

load

Loads one or more perl scripts in the current application's namespace. Syntactic sugar around Perl's require:

    load 'UserActions.pl', 'AdminActions.pl';

load_app

Loads a Dancer package. This method takes care to set the libdir to the curent ./lib directory:

    # if we have lib/Webapp.pm, we can load it like:
    load_app 'Webapp';

Note that a package loaded using load_app must import Dancer with the :syntax option, in order not to change the application directory (which has been previously set for the caller script).

load_plugin

Loads a plugin in the current namespace. As with load_app, the method takes care to set the libdir to the current ./lib directory:

    package MyWebApp;
    use Dancer;

    load_plugin 'Dancer::Plugin::Database';

mime_type

Returns all the user-defined mime-types when called without parameters. Behaves as a setter/getter when given parameters

    # get the global hash of user-defined mime-types:
    my $mimes = mime_types;

    # set a mime-type
    mime_types foo => 'text/foo';

    # get a mime-type
    my $m = mime_types 'foo';

params

This method should be called from a route handler. Alias for the Dancer::Request params accessor.

pass

This method should be called from a route handler. Tells Dancer to pass the processing of the request to the next matching route.

You should always return after calling pass:

    get '/some/route' => sub {
        if (...) {
            # we want to let the next matching route handler process this one
            return pass();
        }
    };

path

Concatenates multiple path together, without worrying about the underlying operating system:

    my $path = path(dirname($0), 'lib', 'File.pm');

post

Defines a route for HTTP POST requests to the given URL:

    POST '/' => sub {
        return "Hello world";
    }

prefix

Defines a prefix 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 undef;
    get '/page1' => sub {}; will match /page1

del

Defines a route for HTTP DELETE requests to the given URL:

    del '/resource' => sub { ... };

options

Defines a route for HTTP OPTIONS requests to the given URL:

    options '/resource' => sub { ... };

put

Defines a route for HTTP PUT requests to the given URL:

    put '/resource' => sub { ... };

r

Defines a route pattern as a regular Perl regexp.

This method is DEPRECATED. Dancer now supports real Perl Regexp objects instead. You should not use r() but qr{} instead:

Don't do this:

    get r('/some/pattern(.*)') => sub { };

But rather this:

    get qr{/some/pattern(.*)} => sub { };

redirect

Generates a HTTP redirect (302). You can either redirect to a complete different site or within the application:

    get '/twitter', sub {
        redirect 'http://twitter.com/me';
    };

You can also force Dancer to return a specific 300-ish HTTP response code:

    get '/old/:resource', sub {
        redirect '/new/'.params->{resource}, 301;
    };

It is important to note that issuing a redirect by itself does not exit and redirect immediately, redirection is deferred until after the current route or filter has been processed. To exit and redirect immediately, use the return function, e.g.

    get '/restricted', sub {
        return redirect '/login' if accessDenied();
        return 'Welcome to the restricted section';
    };

render_with_layout

Allows a handler to provide plain HTML (or other content), but have it rendered within the layout still.

For example:

    get '/foo' => sub {
        # Do something which generates HTML directly (maybe using
        # HTML::Table::FromDatabase or something)
        my $content = ...;
        render_with_layout $content;
    };

It works very similarly to template in that you can pass tokens to be used in the layout, and/or options to control the way the layout is rendered. For instance, to use a custom layout:

    render_with_layout $content, {}, { layout => 'layoutname' };

request

Returns a Dancer::Request object representing the current request.

send_error

Returns a HTTP error. By default the HTTP code returned is 500:

    get '/photo/:id' => sub {
        if (...) {
            send_error("Not allowed", 403);
        } else {
           # return content
        }
    }

This will not cause your route handler to return immediately, so be careful that your route handler doesn't then override the error. You can avoid that by saying return send_error(...) instead.

send_file

Lets the current route handler send a file to the client.

    get '/download/:file' => sub {
        send_file(params->{file});
    }

The content-type will be set depending on the current mime-types definition (see mime_type if you want to define your own).

set

Defines a setting:

    set something => 'value';

setting

Returns the value of a given setting:

    setting('something'); # 'value'

Creates or updates cookie values:

    get '/some_action' => sub {
        set_cookie 'name' => 'value',
            'expires' => (time + 3600),
            'domain'  => '.foo.com';
    };

In the example above, only 'name' and 'value' are mandatory.

session

Provides access to all data stored in the current session engine (if any).

It can also be used as a setter to add new data to the current session engine:

    # getter example
    get '/user' => sub {
        if (session('user')) {
            return "Hello, ".session('user')->name;
        }
    };

    # setter example
    post '/user/login' => sub {
        ...
        if ($logged_in) {
            session user => $user;
        }
        ...
    };

You may also need to clear a session:

    # destroy session
    get '/logout' => sub {
        ...
        session->destroy;
        ...
    };

splat

Returns the list of captures made from a route handler with a route pattern which includes wildcards:

    get '/file/*.*' => sub {
        my ($file, $extension) = splat;
        ...
    };

start

Starts the application or the standalone server (depending on the deployment choices).

This keyword should be called at the very end of the script, once all routes are defined. At this point, Dancer takes over control.

status

Changes the status code provided by an action. By default, an action will produce an HTTP 200 OK status code, meaning everything is OK:

    get '/download/:file' => {
        if (! -f params->{file}) {
            status 'not_found';
            return "File does not exist, unable to download";
        }
        # serving the file...
    };

In that example, Dancer will notice that the status has changed, and will render the response accordingly.

The status keyword receives either a status code or its name in lower case, with underscores as a separator for blanks.

template

Tells the route handler to build a response with the current template engine:

    get '/' => sub {
        ...
        template 'some_view', { token => 'value'};
    };

The first parameter should be a template available in the views directory, the second one (optional) is a hashref of tokens to interpolate, and the third (again optional) is a hashref of options.

For example, to disable the layout for a specific request:

    get '/' => sub {
        template 'index.tt', {}, { layout => undef };
    };

to_dumper ($structure)

Serializes a structure with Data::Dumper.

to_json ($structure, %options)

Serializes a structure to JSON. Can receive optional arguments. Thoses arguments are valid JSON arguments to change the behavior of the default JSON::to_json function.

to_yaml ($structure)

Serializes a structure to YAML.

to_xml ($structure, %options)

Serializes a structure to XML. Can receive optional arguments. Thoses arguments are valid XML::Simple arguments to change the behavior of the default XML::Simple::XMLout function.

true

Constant that returns a true value (1).

upload

Provides access to file uploads. Any uploaded file is accessible as a Dancer::Request::Upload object. You can access all parsed uploads via:

    post '/some/route' => sub {
        my $file = upload('file_input_foo');
        # file is a Dancer::Request::Upload object
    };

If you named multiple input of type "file" with the same name, the upload keyword will return an array of Dancer::Request::Upload objects:

    post '/some/route' => sub {
        my ($file1, $file2) = upload('files_input');
        # $file1 and $file2 are Dancer::Request::Upload objects
    };

You can also access the raw hashref of parsed uploads via the current request object:

    post '/some/route' => sub {
        my $all_uploads = request->uploads;
        # $all_uploads->{'file_input_foo'} is a Dancer::Request::Upload object
        # $all_uploads->{'files_input'} is an array ref of Dancer::Request::Upload objects
    };

Note that you can also access the filename of the upload received via the params keyword:

    post '/some/route' => sub {
        # params->{'files_input'} is the filename of the file uploaded
    };

See Dancer::Request::Upload for details about the interface provided.

uri_for

Returns a fully-qualified URI for the given path:

    get '/' => sub {
        redirect uri_for('/path');
        # can be something like: http://localhost:3000/path
    };

captures

Returns a reference to a copy of %+, if there are named captures in the route Regexp.

Named captures are a feature of Perl 5.10, and are not supported in earlier versions:

    get qr{
        / (?<object> user   | ticket | comment )
        / (?<action> delete | find )
        / (?<id> \d+ )
        /?$
    }x
    , sub {
        my $value_for = captures;
        "i don't want to $$value_for{action} the $$value_for{object} $$value_for{id} !"
    };

var

Defines a variable shared between filters and route handlers.

    before sub {
        var foo => 42;
    };

Route handlers and other filters will be able to read that variable with the vars keyword.

vars

Returns the hashref of all shared variables set during the filter/route chain:

    get '/path' => sub {
        if (vars->{foo} eq 42) {
            ...
        }
    };

warning

Logs a warning message through the current logger engine.

AUTHOR

This module has been written by Alexis Sukrieh <sukria@cpan.org> and others, see the AUTHORS file that comes with this distribution for details.

SOURCE CODE

The source code for this module is hosted on GitHub http://github.com/sukria/Dancer

GETTING HELP / CONTRIBUTING

The Dancer development team can be found on #dancer on irc.perl.org: irc://irc.perl.org/dancer

There is also a Dancer users mailing list available - subscribe at:

http://lists.perldancer.org/cgi-bin/listinfo/dancer-users

DEPENDENCIES

The following modules are mandatory (Dancer cannot run without them):

HTTP::Server::Simple::PSGI
HTTP::Body
MIME::Types
URI

The following modules are optional:

Template : In order to use TT for rendering views
YAML : needed for configuration file support
File::MimeInfo::Simple

LICENSE

This module is free software and is published under the same terms as Perl itself.

SEE ALSO

Main Dancer web site: http://perldancer.org/.

The concept behind this module comes from the Sinatra ruby project, see http://www.sinatrarb.com/ for details.