Dancer - lightweight yet powerful web application framework
#!/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.
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.
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.
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.
after
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.
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 };
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.
before
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.
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.
before_template
This filter works as the before and after filter.
Accesses cookies values, which returns a hashref of Dancer::Cookie objects:
get '/some_action' => sub { my $cookie = cookies->{name}; return $cookie->value; };
Accesses the configuration of the application:
get '/appname' => sub { return "This is " . config->{appname}; };
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.
content_type
Alias for the start keyword.
start
Logs a message of debug level:
debug "This is a debug message";
Returns the dirname of the path given:
my $dir = dirname($some_path);
Logs a message of error level:
error "This is an error message";
Constant that returns a false value (0).
Deserializes a Data::Dumper structure.
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.
JSON::from_json
Deserializes a YAML structure.
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.
XML::Simple::XMLin
Defines a route for HTTP GET requests to the given path:
get '/' => sub { return "Hello world"; }
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"; };
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!'; }
Allows you to set the default layout to use when rendering a view. Syntactic sugar around the layout setting:
layout
layout 'user';
Allows you to set the logger engine to use. Syntactic sugar around the logger setting:
logger
logger 'console';
Loads one or more perl scripts in the current application's namespace. Syntactic sugar around Perl's require:
require
load 'UserActions.pl', 'AdminActions.pl';
Loads a Dancer package. This method takes care to set the libdir to the curent ./lib directory:
./lib
# 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).
:syntax
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';
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';
This method should be called from a route handler. Alias for the Dancer::Request params accessor.
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:
return
pass
get '/some/route' => sub { if (...) { # we want to let the next matching route handler process this one return pass(); } };
Concatenates multiple path together, without worrying about the underlying operating system:
my $path = path(dirname($0), 'lib', 'File.pm');
Defines a route for HTTP POST requests to the given URL:
POST '/' => sub { return "Hello world"; }
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
Defines a route for HTTP DELETE requests to the given URL:
del '/resource' => sub { ... };
Defines a route for HTTP OPTIONS requests to the given URL:
options '/resource' => sub { ... };
Defines a route for HTTP PUT requests to the given URL:
put '/resource' => sub { ... };
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 { };
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'; };
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:
template
render_with_layout $content, {}, { layout => 'layoutname' };
Returns a Dancer::Request object representing the current request.
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.
return send_error(...)
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).
mime_type
Defines a setting:
set something => 'value';
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.
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; ... };
Returns the list of captures made from a route handler with a route pattern which includes wildcards:
get '/file/*.*' => sub { my ($file, $extension) = splat; ... };
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.
Changes the status code provided by an action. By default, an action will produce an HTTP 200 OK status code, meaning everything is OK:
HTTP 200 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.
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 }; };
Serializes a structure with Data::Dumper.
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.
JSON::to_json
Serializes a structure to YAML.
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.
XML::Simple::XMLout
Constant that returns a true value (1).
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.
Returns a fully-qualified URI for the given path:
get '/' => sub { redirect uri_for('/path'); # can be something like: http://localhost:3000/path };
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} !" };
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) { ... } };
Logs a warning message through the current logger engine.
This module has been written by Alexis Sukrieh <sukria@cpan.org> and others, see the AUTHORS file that comes with this distribution for details.
The source code for this module is hosted on GitHub http://github.com/sukria/Dancer
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
The following modules are mandatory (Dancer cannot run without them):
The following modules are optional:
This module is free software and is published under the same terms as Perl itself.
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.
To install Dancer, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dancer
CPAN shell
perl -MCPAN -e shell install Dancer
For more information on module installation, please visit the detailed CPAN module installation guide.