lib/Catalyst/Action/REST/ForBrowsers.pm

   1 package Catalyst::Action::REST::ForBrowsers;
   2
   3 use Moose;
   4 use namespace::autoclean;
   5
   6 # VERSION
   7
   8 extends 'Catalyst::Action::REST';
   9 use Catalyst::Request::REST::ForBrowsers;
  10
  11 sub BUILDARGS {
  12     my $class  = shift;
  13     my $config = shift;
  14     Catalyst::Request::REST::ForBrowsers->_insert_self_into( $config->{class} );
  15     return $class->SUPER::BUILDARGS( $config, @_ );
  16 }
  17
  18 override dispatch => sub {
  19     my $self = shift;
  20     my $c    = shift;
  21
  22     my $req = $c->request();
  23
  24     return super()
  25         unless $req->can('looks_like_browser')
  26             && $req->looks_like_browser()
  27             && uc $c->request()->method() eq 'GET';
  28
  29     my $controller  = $c->component( $self->class );
  30     my $rest_method = $self->name() . '_GET_html';
  31
  32     if (   $controller->action_for($rest_method)
  33         || $controller->can($rest_method) ) {
  34
  35         return $self->_dispatch_rest_method( $c, $rest_method );
  36     }
  37
  38     return super();
  39 };
  40
  41 __PACKAGE__->meta->make_immutable;
  42
  43 1;
  44
  45 =head1 NAME
  46
  47 Catalyst::Action::REST::ForBrowsers - Automated REST Method Dispatching that Accommodates Browsers
  48
  49 =head1 SYNOPSIS
  50
  51     sub foo :Local :ActionClass('REST::ForBrowsers') {
  52       ... do setup for HTTP method specific handlers ...
  53     }
  54
  55     sub foo_GET : Private {
  56       ... do something for GET requests ...
  57     }
  58
  59     sub foo_GET_html : Private {
  60       ... do something for GET requests from browsers ...
  61     }
  62
  63     sub foo_PUT : Private {
  64       ... do something for PUT requests ...
  65     }
  66
  67 =head1 DESCRIPTION
  68
  69 This class subclasses L<Catalyst::Action::REST> to add an additional
  70 dispatching hook. If the request is a GET request I<and> the request looks
  71 like it comes from a browser, it tries to dispatch to a C<GET_html> method
  72 before trying to the C<GET> method instead. All other HTTP methods are
  73 dispatched in the same way.
  74
  75 For example, in the synopsis above, calling GET on "/foo" from a browser will
  76 end up calling the C<foo_GET_html> method. If the request is I<not> from a
  77 browser, it will call C<foo_GET>.
  78
  79 See L<Catalyst::Action::REST> for more details on dispatching details.
  80
  81 =head1 METHODS
  82
  83 =over 4
  84
  85 =item dispatch
  86
  87 This method overrides the default dispatch mechanism to the re-dispatching
  88 mechanism described above.
  89
  90 =back
  91
  92 =head1 SEE ALSO
  93
  94 You likely want to look at L<Catalyst::Controller::REST>, which implements a
  95 sensible set of defaults for a controller doing REST.
  96
  97 This class automatically adds the
  98 L<Catalyst::TraitFor::Request::REST::ForBrowsers> role to your request class.
  99
 100 =head1 CONTRIBUTORS
 101
 102 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 103
 104 =head1 COPYRIGHT
 105
 106 Copyright the above named AUTHOR and CONTRIBUTORS
 107
 108 =head1 LICENSE
 109
 110 You may distribute this code under the same terms as Perl itself.
 111
 112 =cut