NAME

VERSION

DESCRIPTION

INSTALL

    perl -MCPAN -e 'install Dancer'

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 - Dancer

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

SETUP

    dancer -a MyApp

Run the web application:

    cd MyApp
    bin/app.pl

You can read the output of "bin/app.pl --help" to change any settings such as the port number.

View the web application at:

    http://localhost:3000

USAGE

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

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

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

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

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

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

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

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

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

    prefix '/home';

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

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

    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

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

HOOKS

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

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

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

    hook 'after' => sub {
        my $response = shift;
        $response->{content} = 'after hook got here!';
    };

    hook 'before_template_render' => sub {
        my $tokens = shift;
        $tokens->{foo} = 'bar';
    };

CONFIGURATION AND ENVIRONMENTS

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 command line 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

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

    load 'more_routes.pl';

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

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

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

Importing just the syntax

    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

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, error and info messages
    log: 'info'      # will log info, warning and error messages
    log: 'warning'   # will log warning and error messages
    log: 'error'     # will log error messages

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, info, warning and error functions. For instance:

    debug "This is a debug message";

USING TEMPLATES

VIEWS

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>

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

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

        </body>
    </html>

    use Dancer;
    set layout => 'main';

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

    use Dancer;
    set layout => 'main';

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

STATIC FILES

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

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

        send_file $file;
    };

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

SETTINGS

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 might want extra logging in development). See the cookbook for examples.

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

SERIALIZERS

When setting up a serializer, a new behaviour is authorized for any route handler you define: any response that is a reference 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 a reference - 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

    #!/usr/bin/perl

    # make this script a webapp
    use Dancer;

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

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

    # run the webserver
    Dancer->dance;

AUTHOR

COPYRIGHT AND LICENSE

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