++ed by:
AWNCORP GARU PJF BIGPRESH BLOM

59 PAUSE user(s)
70 non-PAUSE user(s).

Sawyer X

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::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.

USAGE

As soon as Dancer is imported to a script, that script becomes a webapp. All the script has to do is to declare a list of routes. A route handler is composed by an HTTP method, a path pattern and a code block. strict and warnings pragma are also imported with Dancer.

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.

Here is an example of a route definition:

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

        return "Hello ".params->{name};
    };

The route is defined for the method 'get', so only GET requests will be honoured by that route.

HTTP METHODS

All existing HTTP methods are defined in the RFC 2616 http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html.

Here are the ones you can use to define your route handlers.

GET The GET method retrieves information (when defining a route handler for the GET method, Dancer 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.

You can also use the special keyword any to define a route for multiple methods at once. For instance, you may want to define a route for both GET and POST methods, this is done like the following:

    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 Dancer::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 ".params->{name}.", welcome here!";
    };

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. The syntax is assumed to be a classic Perl regexp except for the slashes that will be escaped before running the match.

For instance, don't do '\/hello\/(.+)' but rather: '/hello/(.+)'

In order to tell Dancer to consider the route as a real regexp, the route must be defined explicitly with the keyword 'r', like the following:

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

RUNNING THE WEBSERVER

Once the script is ready, you can run the webserver just by running the script. The following options are supported:

--port=XXXX set the port to listen to (default is 3000)
--daemon run the webserver in the background
--help display a detailed help message

ACTION SKIPPING

An action can choose not to serve the current request and ask Dancer 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 {
        pass if (params->{word} =~ /^\d+$/);
        "I say a word: ".params->{word};
    };

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

ACTION RESPONSES

The action's return value is always considered to be the content to render. So take care to your return value.

In order to change the default behaviour of the rendering of an action, you can use the following keywords.

redirect

The redirect action is a helper and shortcut to a common HTTP response code (302). You can either redirect to a complete different site or you can also do it 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;
    };

status

By default, an action will produce an 'HTTP 200 OK' status code, meaning everything is OK. It's possible to change that with the keyword status :

    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 the name of the status to render, it can be either an HTTP code or its alias, as defined in Dancer::HTTP.

file uploads

Dancer provides a common interface to handle file uploads. Any uploaded file is accessible as a Dancer::Request::Upload object. you can access all parsed uploads via the upload keyword, like the following:

    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 requesrt 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.

content_type

You can also change the content type rendered in the same maner, with the keyword content_type

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

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

cookies

You can create/update cookies with the set_cookie helper like the following:

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

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

You can access their value with the cookies helper, which returns a hashref of Cookie objects:

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

header(s)

It is possible to add custom headers to responses with the header (or headers) keyword:

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

or...

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

You can use both undistinctly, they do exactly what you expect them to do.

ERROR HANDLING

DEFAULT ERROR PAGES

When an error is renderered (the action responded with a status code different than 200), Dancer 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, Dancer 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.

FILTERS

Before filters

Before filters are evaluated before each request within the context of the request and can modify the request and response. It's possible to define variables which will be accessible in the action blocks with the keyword 'var'.

    before sub {
        var note => 'Hi there';
        request->path('/foo/oversee')
    };

    get '/foo/*' => sub {
        my ($match) = splat; # 'oversee';
        vars->{note}; # 'Hi there'
    };

For another example, this can be used along with session support to easily give non-logged-in users a login page:

    before sub {
        if (!session('user') && request->path_info !~ m{^/login}) {
            # Pass the original path requested along to the handler:
            var requested_path => request->path_info;
            request->path_info('/login');
        }
    };

The request keyword returns the current Dancer::Request object representing the incoming request. See the documentation of the Dancer::Request module for details.

CONFIGURATION AND ENVIRONMENTS

Configuring a Dancer application can be done in many ways. The easiest one (and maybe the 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 can write all your setting calls in the file `appdir/config.yml'. For this, you must have installed the YAML module, and of course, write the conffile in YAML.

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.yml file.

The better 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, it will be 'development').

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'
    access_log: 1
    show_errors: 1

And in a production one:

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

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 Dancer 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 files hierarchies, you can import just the syntax of Dancer.

    package App;

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

Then in App/User/Routes.pm:

    use Dancer ':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.yml

    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 (Dancer::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 Dancer::Template::TemplateToolkit. If you do so, you'll also have to import the Template module in your application code. Note that Dancer 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 Dancer;
    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 Dancer;
    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 Dancer;
    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.

MIME-TYPES CONFIGURATION

By default, Dancer will automatically detect the mime-types to use for the static files accessed.

It's possible to choose specific mime-type per file extensions. For instance, we can imagine you want to serve *.foo as a text/foo content, instead of text/plain (which would be the content type detected by Dancer if *.foo are text files).

        mime_type foo => 'text/foo';

This configures the 'text/foo' content type for any file matching '*.foo'.

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'
    };

ROUTE CACHING

Dancer automatically supports default caching for routes. What this means is that Dancer remembers for each path what route it took, so it doesn't have to match it again.

This makes things much faster, especially when dealing with many routes. There are default limitations on the size of the cache and the number of entries, so it doesn't get out of proportion.

Route caching can turned on using the route_cache option in the configuration:

    route_cache = 1

The default limitations are 10M in size or 600 entries in the cache, however you can override these by settings the following settings:

    # limiting the size of the route cache
    route_cache_size_limit: 50M

    # limiting the number of paths that will be cached
    route_cache_path_limit: 300

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 YAML 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.

See Dancer::Config for complete details about supported settings.

SERIALIZERS

When writing a webservice, data serialization/deserialization is a common issue to deal with. Dancer can automaticall 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 Dancer;
    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 - Dancer 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 Dancer:

    #!/usr/bin/perl

    # make this script a webapp
    use Dancer;

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

    get '/hello/:name' => sub {
        "Hello ".params->{name}"
    };

    # run the webserver
    Dancer->dance;

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

Dancer depends on the following modules:

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.