lib/Catalyst/View/Email/Template.pm

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