lib/Catalyst/Action/REST/ForBrowsers.pm

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