lib/Catalyst/View/Email/Template.pm

   1 package Catalyst::View::Email::Template;
   2
   3 use Moose;
   4 use Carp;
   5 use Scalar::Util qw/ blessed /;
   6 extends 'Catalyst::View::Email';
   7
   8 our $VERSION = '0.26_01';
   9 $VERSION = eval $VERSION;
  10 =head1 NAME
  11
  12 Catalyst::View::Email::Template - Send Templated Email from Catalyst
  13
  14 =head1 SYNOPSIS
  15
  16 Sends templated mail, based upon your default view. It captures the output
  17 of the rendering path, slurps in based on mime-types and assembles a multi-part
  18 email using L<Email::MIME::Creator> and sends it out.
  19
  20 =head1 CONFIGURATION
  21
  22 WARNING: since version 0.10 the configuration options slightly changed!
  23
  24 Use the helper to create your view:
  25
  26     $ script/myapp_create.pl view Email::Template Email::Template
  27
  28 For basic configuration look at L<Catalyst::View::Email/CONFIGURATION>.
  29
  30 In your app configuration (example in L<YAML>):
  31
  32     View::Email::Template:
  33         # Optional prefix to look somewhere under the existing configured
  34         # template  paths.
  35         # Default: none
  36         template_prefix: email
  37         # Define the defaults for the mail
  38         default:
  39             # Defines the default view used to render the templates.
  40             # If none is specified neither here nor in the stash
  41             # Catalysts default view is used.
  42             # Warning: if you don't tell Catalyst explicit which of your views should
  43             # be its default one, C::V::Email::Template may choose the wrong one!
  44             view: TT
  45
  46 =head1 SENDING EMAIL
  47
  48 Sending email works just like for L<Catalyst::View::Email> but by specifying
  49 the template instead of the body and forwarding to your Email::Template view:
  50
  51     sub controller : Private {
  52         my ( $self, $c ) = @_;
  53
  54         $c->stash->{email} = {
  55             to          => 'jshirley@gmail.com',
  56             cc          => 'abraxxa@cpan.org',
  57             bcc         => 'hidden@secret.com hidden2@foobar.com',
  58             from        => 'no-reply@foobar.com',
  59             subject     => 'I am a Catalyst generated email',
  60             template    => 'test.tt',
  61             content_type => 'multipart/alternative'
  62         };
  63
  64         $c->forward( $c->view('Email::Template') );
  65     }
  66
  67 Alternatively if you want more control over your templates you can use the following idiom
  68 to override the defaults:
  69
  70     templates => [
  71         {
  72             template        => 'email/test.html.tt',
  73             content_type    => 'text/html',
  74             charset         => 'utf-8',
  75             view            => 'TT',
  76         },
  77         {
  78             template        => 'email/test.plain.mason',
  79             content_type    => 'text/plain',
  80             charset         => 'utf-8',
  81             view            => 'Mason',
  82         }
  83     ]
  84
  85
  86 =head1 HANDLING ERRORS
  87
  88 See L<Catalyst::View::Email/HANDLING ERRORS>.
  89
  90 =cut
  91
  92 # here the defaults of Catalyst::View::Email are extended by the additional
  93 # ones Template.pm needs.
  94
  95 has 'stash_key' => (
  96     is      => 'rw',
  97     isa     => 'Str',
  98     default => sub { "email" },
  99     lazy    => 1,
 100 );
 101
 102 has 'template_prefix' => (
 103     is      => 'rw',
 104     isa     => 'Str',
 105     default => sub { '' },
 106     lazy    => 1,
 107 );
 108
 109 has 'default' => (
 110     is      => 'rw',
 111     isa     => 'HashRef',
 112     default => sub {
 113         {
 114             view         => 'TT',
 115             content_type => 'text/html',
 116         };
 117     },
 118     lazy => 1,
 119 );
 120
 121 # This view hitches into your default view and will call the render function
 122 # on the templates provided.  This means that you have a layer of abstraction
 123 # and you aren't required to modify your templates based on your desired engine
 124 # (Template Toolkit or Mason, for example).  As long as the view adequately
 125 # supports ->render, all things are good.  Mason, and others, are not good.
 126
 127 #
 128 # The path here is to check configuration for the template root, and then
 129 # proceed to call render on the subsequent templates and stuff each one
 130 # into an Email::MIME container.  The mime-type will be stupidly guessed with
 131 # the subdir on the template.
 132 #
 133
 134 # Set it up so if you have multiple parts, they're alternatives.
 135 # This is on the top-level message, not the individual parts.
 136 #multipart/alternative
 137
 138 sub _validate_view {
 139     my ( $self, $view ) = @_;
 140
 141     croak "C::V::Email::Template's configured view '$view' isn't an object!"
 142       unless ( blessed($view) );
 143
 144     croak
 145       "C::V::Email::Template's configured view '$view' isn't an Catalyst::View!"
 146       unless ( $view->isa('Catalyst::View') );
 147
 148     croak
 149 "C::V::Email::Template's configured view '$view' doesn't have a render method!"
 150       unless ( $view->can('render') );
 151 }
 152
 153 =head1 METHODS
 154
 155 =over 4
 156
 157 =item generate_part
 158
 159 Generates a MIME part to include in the email. Since the email is template based
 160 every template piece is a separate part that is included in the email.
 161
 162 =cut
 163
 164 sub generate_part {
 165     my ( $self, $c, $attrs ) = @_;
 166
 167     my $template_prefix      = $self->template_prefix;
 168     my $default_view         = $self->default->{view};
 169     my $default_content_type = $self->default->{content_type};
 170     my $default_charset      = $self->default->{charset};
 171
 172     my $view;
 173
 174     # use the view specified for the email part
 175     if (   exists $attrs->{view}
 176         && defined $attrs->{view}
 177         && $attrs->{view} ne '' )
 178     {
 179         $view = $c->view( $attrs->{view} );
 180         $c->log->debug(
 181             "C::V::Email::Template uses specified view $view for rendering.")
 182           if $c->debug;
 183     }
 184
 185     # if none specified use the configured default view
 186     elsif ($default_view) {
 187         $view = $c->view($default_view);
 188         $c->log->debug(
 189             "C::V::Email::Template uses default view $view for rendering.")
 190           if $c->debug;
 191     }
 192
 193     # else fallback to Catalysts default view
 194     else {
 195         $view = $c->view;
 196         $c->log->debug(
 197 "C::V::Email::Template uses Catalysts default view $view for rendering."
 198         ) if $c->debug;
 199     }
 200
 201     # validate the per template view
 202     $self->_validate_view($view);
 203
 204     # prefix with template_prefix if configured
 205     my $template =
 206       $template_prefix ne ''
 207       ? join( '/', $template_prefix, $attrs->{template} )
 208       : $attrs->{template};
 209
 210     # setup the attributes (merge with defaults)
 211     my $e_m_attrs = $self->SUPER::setup_attributes( $c, $attrs );
 212
 213     # render the email part
 214     my $output = $view->render(
 215         $c,
 216         $template,
 217         {
 218             content_type => $e_m_attrs->{content_type},
 219             stash_key    => $self->stash_key,
 220             %{$c->stash},
 221         }
 222     );
 223     if ( ref $output ) {
 224         croak $output->can('as_string') ? $output->as_string : $output;
 225     }
 226
 227     return Email::MIME->create(
 228         attributes => $e_m_attrs,
 229         body       => $output,
 230     );
 231 }
 232
 233 =item process
 234
 235 The process method is called when the view is dispatched to. This creates the
 236 multipart message and then sends the message contents off to
 237 L<Catalyst::View::Email> for processing, which in turn hands off to
 238 L<Email::Sender::Simple>.
 239
 240 =cut
 241
 242 around 'process' => sub {
 243     my ( $orig, $self, $c, @args ) = @_;
 244     my $stash_key = $self->stash_key;
 245     return $self->$orig( $c, @args )
 246       unless $c->stash->{$stash_key}->{template}
 247           or $c->stash->{$stash_key}->{templates};
 248
 249     # in case of the simple api only one
 250     my @parts = ();
 251
 252     # now find out if the single or multipart api was used
 253     # prefer the multipart one
 254
 255     # multipart api
 256     if (   $c->stash->{$stash_key}->{templates}
 257         && ref $c->stash->{$stash_key}->{templates} eq 'ARRAY'
 258         && ref $c->stash->{$stash_key}->{templates}[0] eq 'HASH' )
 259     {
 260
 261         # loop through all parts of the mail
 262         foreach my $part ( @{ $c->stash->{$stash_key}->{templates} } ) {
 263             push @parts,
 264               $self->generate_part(
 265                 $c,
 266                 {
 267                     view         => $part->{view},
 268                     template     => $part->{template},
 269                     content_type => $part->{content_type},
 270                     charset      => $part->{charset},
 271                 }
 272               );
 273         }
 274     }
 275
 276     # single part api
 277     elsif ( $c->stash->{$stash_key}->{template} ) {
 278         push @parts,
 279           $self->generate_part( $c,
 280             { template => $c->stash->{$stash_key}->{template}, } );
 281     }
 282
 283     delete $c->stash->{$stash_key}->{body};
 284     $c->stash->{$stash_key}->{parts} ||= [];
 285     push @{ $c->stash->{$stash_key}->{parts} }, @parts;
 286
 287     return $self->$orig($c);
 288
 289 };
 290
 291 =back
 292
 293 =head1 TODO
 294
 295 =head2 ATTACHMENTS
 296
 297 There needs to be a method to support attachments.  What I am thinking is
 298 something along these lines:
 299
 300     attachments => [
 301         # Set the body to a file handle object, specify content_type and
 302         # the file name. (name is what it is sent at, not the file)
 303         { body => $fh, name => "foo.pdf", content_type => "application/pdf" },
 304         # Or, specify a filename that is added, and hey, encoding!
 305         { filename => "foo.gif", name => "foo.gif", content_type => "application/pdf", encoding => "quoted-printable" },
 306         # Or, just a path to a file, and do some guesswork for the content type
 307         "/path/to/somefile.pdf",
 308     ]
 309
 310 =head1 SEE ALSO
 311
 312 =head2 L<Catalyst::View::Email> - Send plain boring emails with Catalyst
 313
 314 =head2 L<Catalyst::Manual> - The Catalyst Manual
 315
 316 =head2 L<Catalyst::Manual::Cookbook> - The Catalyst Cookbook
 317
 318 =head1 AUTHORS
 319
 320 J. Shirley <jshirley@gmail.com>
 321
 322 Simon Elliott <cpan@browsing.co.uk>
 323
 324 Alexander Hartmaier <abraxxa@cpan.org>
 325
 326 =head1 LICENSE
 327
 328 This library is free software, you can redistribute it and/or modify it under
 329 the same terms as Perl itself.
 330
 331 =cut
 332
 333 1;