NAME¶
Poet::Mason -- Mason settings and enhancements for Poet
SYNOPSIS¶
# In a conf file...
mason:
plugins:
- Cache
- TidyObjectFiles
- +My::Mason::Plugin
static_source: 1
static_source_touch_file: ${root}/data/purge.dat
# Get the main Mason instance
my $mason = Poet::Mason->instance();
# Create a new Mason object
my $mason = Poet::Mason->new(...);
DESCRIPTION¶
This is a Poet-specific Mason subclass. It sets up sane default settings,
maintains a main Mason instance for handling web requests, and adds
Poet-specific methods to $m (the Mason request object).
CLASS METHODS¶
- get_options
- Returns a hash of Mason options by combining default settings and
configuration.
- instance
- Returns the main Mason instance used for web requests, which is created
with options from get_options.
- new
- Returns a new main Mason object, using options from get_options. Unless
you specifically need a new object, you probably want to call
instance.
DEFAULT SETTINGS¶
- •
- "comp_root" is set to $poet->comps_dir, by default the
"comps" subdirectory under the environment root.
- •
- "data_dir" is set to $poet->data_dir, by default the
"data" subdirectory under the environment root.
- •
- "plugins" is set to include Cache, HTMLFilters and
RouterSimple.
- •
- "cache_root_class" (a parameter of the "Cache" plugin)
is set to "MyApp::Cache" if it exists (replacing
"MyApp" with your app name), otherwise
"Poet::Cache".
CONFIGURATION¶
The Poet configuration entry 'mason', if any, will be treated as a hash of
options that supplements and/or overrides the defaults above. If the hash
contains 'extra_plugins', these will be added to the default plugins. e.g.
mason:
static_source: 1
static_source_touch_file: ${root}/data/purge.dat
extra_plugins:
- AnotherFavoritePlugin
QUICK VARS AND UTILITIES¶
Poet inserts the following line at the top of of every compiled Mason component:
use Poet qw($conf $poet :web);
which means that $conf, $poet, and web utilities are available from every
component.
NEW REQUEST METHODS¶
Under Poet these additional web-related methods are available in the Mason
request object, accessible in components via $m or elsewhere via
"Mason::Request->current_request".
- req ()
- A reference to the Plack::Request object. e.g.
my $user_agent = $m->req->headers->header('User-Agent');
- res ()
- A reference to the Plack::Response object. e.g.
$m->res->content_type('text/plain');
- abort (status)
- clear_and_abort (status)
- These methods are overridden to set the response status before aborting,
if status is provided. e.g. to send back a FORBIDDEN result:
$m->clear_and_abort(403);
This is equivalent to
$m->res->status(403);
$m->clear_and_abort();
If a status is not provided, the methods work just as before.
- redirect (url[, status])
- Sets headers and status for redirect, then clears the Mason buffer and
aborts the request. e.g.
$m->redirect("http://somesite.com", 302);
is equivalent to
$m->res->redirect("http://somesite.com", 302);
$m->clear_and_abort();
- not_found ()
- Sets the status to 404, then clears the Mason buffer and aborts the
request. e.g.
$m->not_found();
is equivalent to
$m->clear_and_abort(404);
- session
- A shortcut for "$m->req->session", the Plack session. This
is simply a persistent hash that you can read from and write to. It is
tied to the user's browser session via cookies and stored in a file cache
in the data directory (by default).
my $value = $m->session->{key};
$m->session->{key} = { some_complex => ['value'] };
- send_json ($data)
- Output the JSON-encoded $data, set the content type
to "application/json", and abort. e.g.
method handle {
my $data;
# compute data somehow
$m->send_json($data);
}
"send_json" is a shortcut for
$m->clear_buffer;
$m->print(JSON::XS::encode_json($data));
$m->res->content_type("application/json");
$m->abort();
SEE ALSO¶
Poet
AUTHOR¶
Jonathan Swartz <swartz@pobox.com>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2012 by Jonathan Swartz.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.