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.