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.