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