/ 
Prancer-1.05
River stage one • 3 direct dependents • 3 total dependents
/ Prancer

NAME

Prancer

SYNOPSIS

When using as part of a web application:

===> foobar.yml

session:
    state:
        driver: Prancer::Session::State::Cookie
        options:
            session_key: PSESSION
    store:
        driver: Prancer::Session::Store::Storable
        options:
            dir: /tmp/prancer/sessions

static:
    path: /static
    dir: /srv/www/resources

===> myapp.psgi

#!/usr/bin/env perl

use strict;
use warnings;
use Plack::Runner;

# this just returns a PSGI application. $x can be wrapped with additional
# middleware before sending it along to Plack::Runner.
my $x = MyApp->new("/path/to/foobar.yml")->to_psgi_app();

# run the psgi app through Plack and send it everything from @ARGV. this
# way Plack::Runner will get options like what listening port to use and
# application server to use -- Starman, Twiggy, etc.
my $runner = Plack::Runner->new();
$runner->parse_options(@ARGV);
$runner->run($x);

===> MyApp.pm

package MyApp;

use strict;
use warnings;

use Prancer qw(config);

sub initialize {
    my $self = shift;

    # in here we can initialize things like plugins
    # but this method is not required to be implemented

    return;
}

sub handler {
    my ($self, $env, $request, $response, $session) = @_;

    sub (GET + /) {
        $response->header("Content-Type" => "text/plain");
        $response->body("Hello, world!");
        return $response->finalize(200);
    }, sub (GET + /foo) {
        $response->header("Content-Type" => "text/plain");
        $response->body(sub {
            my $writer = shift;
            $writer->write("Hello, world!");
            $writer->close();
            return;
        });
    }
}

1;

If you save the above snippet as myapp.psgi and run it like this:

plackup myapp.psgi

You will get "Hello, world!" in your browser. Or you can use Prancer as part of a standalone command line application:

#!/usr/bin/env perl

use strict;
use warnings;

use Prancer::Core qw(config);

# the advantage to using Prancer in a standalone application is the ability
# to use a standard configuration and to load plugins for things like
# loggers and database connectors and template engines.
my $x = Prancer::Core->new("/path/to/foobar.yml");
print "Hello, world!;

DESCRIPTION

Prancer is yet another PSGI framework that provides routing and session management as well as plugins for logging, database access, and template engines. It does this by wrapping Web::Simple to handle routing and by wrapping other libraries to bring easy access to things that need to be done in web applications.

There are two parts to using Prancer for a web application: a package to contain your application and a script to call your application. Both are necessary.

The package containing your application should contain a line like this:

use Prancer;

This modifies your application package such that it inherits from Prancer. It also means that your package must implement the handler method and optionally implement the initialize method. As Prancer inherits from Web::Simple it will also automatically enable the strict and warnings pragmas.

As mentioned, putting use Prancer; at the top of your package will require you to implement the handler method, like this:

sub handler {
    my ($self, $env, $request, $response, $session) = @_;

    # routing goes in here.
    # see Web::Simple for documentation on writing routing rules.
    sub (GET + /) {
        $response->header("Content-Type" => "text/plain");
        $response->body("Hello, world!");
        return $response->finalize(200);
    }
}

The $request variable is a Prancer::Request object. The $response variable is a Prancer::Response object. The $session variable is a Prancer::Session object. If there is no configuration for sessions in any of your configuration files then $session will be undef.

You may implement your own new method in your application but you MUST call $class->SUPER::new(@_); to get the configuration file loaded and any methods exported. As an alternative to implemeting new and remembering to call SUPER::new, Prancer will make a call to ->initialize at the end of its own implementation of new so things that you might put in new can instead be put into initialize, like this:

sub initialize {
    my $self = shift;

    # this is where you can initialize things when your package is created

    return;
}

By default, Prancer does not export anything into your package's namespace. However, that doesn't mean that there is not anything that it could export were one to ask:

use Prancer qw(config);

Importing config will make the keyword config available which gives access to any configuration options loaded by Prancer.

The second part of the Prancer equation is the script that creates and calls your package. This can be a pretty small and standard little script, like this:

my $myapp = MyApp->new("/path/to/foobar.yml")
my $psgi = $myapp->to_psgi_app();

$myapp is just an instance of your package. You can pass to new either one specific configuration file or a directory containing lots of configuration files. The functionality is documented in Prancer::Config.

$psgi is just a PSGI app that you can send to Plack::Runner or whatever you use to run PSGI apps. You can also wrap middleware around $app.

my $psgi = $myapp->to_psgi_app();
$psgi = Plack::Middleware::Runtime->wrap($psgi);

CONFIGURATION

Prancer needs a configuration file. Ok, it doesn't need a configuration file. By default, Prancer does not require any configuration. But it is less useful without one. You could always create your application like this:

my $app = MyApp->new->to_psgi_app();

How Prancer loads configuration files is documented in Prancer::Config. Anything you put into your configuration file is available to your application.

There are two special configuration keys reserved by Prancer. The key session will configure Prancer's session as documented in Prancer::Session. The key static will configure static file loading through Plack::Middleware::Static.

To configure static file loading you can add this to your configuration file:

static:
    path: /static
    dir: /path/to/my/resources

The dir option is required to indicate the root directory for your static resources. The path option indicates the web path to link to your static resources. If no path is not provided then static files can be accessed under /static by default.

CREDITS

This module could have been written except on the shoulders of the following giants:

COPYRIGHT

Copyright 2013, 2014 Paul Lockaby. All rights reserved.

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

SEE ALSO