lib/Catalyst/Action/Serialize.pm

   1 #
   2 # Catlyst::Action::Serialize.pm
   3 # Created by: Adam Jacob, Marchex, <adam@marchex.com>
   4 #
   5 # $Id$
   6
   7 package Catalyst::Action::Serialize;
   8
   9 use strict;
  10 use warnings;
  11
  12 use base 'Catalyst::Action';
  13 use Module::Pluggable::Object;
  14
  15 __PACKAGE__->mk_accessors(qw(plugins));
  16
  17 sub execute {
  18     my $self = shift;
  19     my ( $controller, $c ) = @_;
  20
  21     return 1 if $c->req->method eq 'HEAD';
  22     return 1 if length( $c->response->body );
  23     return 1 if scalar @{ $c->error };
  24     return 1 if $c->response->status =~ /^(?:204|3\d\d)$/;
  25
  26     # Load the Serialize Classes
  27     unless ( defined( $self->plugins ) ) {
  28         my $mpo = Module::Pluggable::Object->new(
  29             'require'     => 1,
  30             'search_path' => ['Catalyst::Action::Serialize'],
  31         );
  32         my @plugins = $mpo->plugins;
  33         $self->plugins( \@plugins );
  34     }
  35
  36     # Look up what serializer to use from content_type map
  37     #
  38     # If we don't find one, we use the default
  39     my $content_type = $c->request->content_type;
  40     my $sclass       = 'Catalyst::Action::Serialize::';
  41     my $sarg;
  42     my $map = $controller->serialize->{'map'};
  43     if ( exists( $map->{$content_type} ) ) {
  44         my $mc;
  45         if ( ref( $map->{$content_type} ) eq "ARRAY" ) {
  46             $mc   = $map->{$content_type}->[0];
  47             $sarg = $map->{$content_type}->[1];
  48         } else {
  49             $mc = $map->{$content_type};
  50         }
  51         $sclass .= $mc;
  52         if ( !grep( /^$sclass$/, @{ $self->plugins } ) ) {
  53             die "Cannot find plugin $sclass for $content_type!";
  54         }
  55     } else {
  56         if ( exists( $controller->serialize->{'default'} ) ) {
  57             $sclass .= $controller->serialize->{'default'};
  58         } else {
  59             die "I cannot find a default serializer!";
  60         }
  61     }
  62
  63     # Go ahead and serialize ourselves
  64     if ( defined($sarg) ) {
  65         $sclass->execute( $controller, $c, $sarg );
  66     } else {
  67         $sclass->execute( $controller, $c );
  68     }
  69
  70     if ( !$c->response->content_type ) {
  71         $c->response->content_type( $c->request->content_type );
  72     }
  73
  74     return 1;
  75 }
  76
  77 1;
  78
  79 =head1 NAME
  80
  81 Catalyst::Action::Serialize - Serialize Data in a Response
  82
  83 =head1 SYNOPSIS
  84
  85     package Foo::Controller::Bar;
  86
  87     __PACKAGE__->config(
  88         serialize => {
  89             'default'   => 'YAML',
  90             'stash_key' => 'rest',
  91             'map'       => {
  92                 'text/x-yaml'        => 'YAML',
  93                 'text/x-data-dumper' => [ 'Data::Serializer', 'Data::Dumper' ],
  94             },
  95         }
  96     );
  97
  98     sub end : ActionClass('Serialize') {}
  99
 100 =head1 DESCRIPTION
 101
 102 This action will serialize the body of an HTTP Response.  The serializer is
 103 selected by introspecting the requests content-type header.
 104
 105 It requires that your Catalyst controller have a "serialize" entry
 106 in it's configuration.
 107
 108 The specifics of serializing each content-type is implemented as
 109 a plugin to L<Catalyst::Action::Serialize>.
 110
 111 =head1 CONFIGURATION
 112
 113 =over 4
 114
 115 =item default
 116
 117 The default Serialization format.  See the next section for
 118 available options.  This is used if a requested content-type
 119 is not recognized.
 120
 121 =item stash_key
 122
 123 Where in the stash the data you want serialized lives.
 124
 125 =item map
 126
 127 Takes a hashref, mapping Content-Types to a given plugin.
 128
 129 =back
 130
 131 =head1 SEE ALSO
 132
 133 You likely want to look at L<Catalyst::Controller::REST>, which implements
 134 a sensible set of defaults for a controller doing REST.
 135
 136 L<Catalyst::Action::Deserialize>, L<Catalyst::Action::REST>
 137
 138 =head1 AUTHOR
 139
 140 Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and jrockway
 141
 142 Marchex, Inc. paid me while I developed this module.  (http://www.marchex.com)
 143
 144 =head1 LICENSE
 145
 146 You may distribute this code under the same terms as Perl itself.
 147
 148 =cut