NAME

Catalyst::Plugin::Errors - Standard error responses with content negotiation

SYNOPSIS

Use in your application class

    package Example;

    use Catalyst;

    __PACKAGE__->setup_plugins([qw/Errors/]);
    __PACKAGE__->setup();
    __PACKAGE__->meta->make_immutable();

And then you can use it in a controller (or anyplace where you have $c context).

    package Example::Controller::Root;

    use Moose;
    use MooseX::MethodAttributes;

    extends 'Catalyst::Controller';

    sub root :Chained(/) PathPart('') CaptureArgs(0) {} 

      sub not_found :Chained(root) PathPart('') Args {
        my ($self, $c, @args) = @_;
        $c->detach_error(404);
      }

    __PACKAGE__->config(namespace=>'');
    __PACKAGE__->meta->make_immutable;

DESCRIPTION

This is a plugin which installs (if needed) View classes to handle HTTP errors (4xx and 5xx codes) in a regular and content negotiated way. See <CatalystX::Errors> for a high level overview. Documentation here is more API level and the examples are sparse.

METHODS

This plugin adds the following methods to your $c context.

dispatch_error ($code, ?%args)

Dispatches to an error view based on content negotiation and the provided code. Any additional %args will be passed to the view handler, down to the template so if you have a custom view template you can use this to provide custom template parameters.

When dispatching to a $view we use the following rules in order:

First if the View has a method http_${code} (where $code is the HTTP status code you are using for the error) we call that method with args $c, %args and expect that method to setup a valid error response.

Second, when call the method http_default with args $c, $code, %args if that exists.

If neither method exists we call $c-forward($view)> and %args are added to the stash, along with a stash field 'template' which is set to the error $code. This should work with most standard Catalyst views that look at the stash field 'template' to find a template name.

detach_error

Calls "dispatch_error" with the provided arguments and then does a $c-detach> which effectively ends processing for the action.

CONFIGURATION & CUSTOMIZATION

This plugin can be customized with the following configuration options or via overriding or adapting the following methods

finalize_error_args

This method provides the actual arguments given to the error view (args which are for example used in the template for messaging to the end user). You can override this to provide your own version. See the source for how this should work

Configuration keys

This plugin defines the following configuration by default, which you can override.

    package Example;

    use Catalyst;

    __PACKAGE__->setup_plugins([qw/Errors/]);
    __PACKAGE__->config(
      # This is the configuration which is default.  You don't have to actually type
      # this out.  I'm just putting it here to show you what its doing under the hood.
      'Plugin::Errors' => +{
        'text/html'   => 'Errors::HTML',
        'text/plain'  => 'Errors::Text',
        'application/json' => 'Errors::JSON',
      },
    );

    __PACKAGE__->setup();
    __PACKAGE__->meta->make_immutable();

By default we map the media types text/html, text/plain and application/json to cooresponding views. This views are injected automatically if you don't provide subclasses or your own view locally. The following views are injected as needed:

Catalyst::View::Error::HTML, Catalyst::View::Error::Text, and Catalyst::View::Error::JSON.

You can check the docs for each of the default views for customization options but you can always make a local subclass inside you application's view directory and tweak as desired (or you can just use your own view or one of the common ones on CPAN).

You can also add additional media types mappings.

SEE ALSO

CatalystX::Errors.

AUTHOR

CatalystX::Errors.

COPYRIGHT & LICENSE

CatalystX::Errors.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 205:

Unterminated L<...> sequence