1 package Catalyst::View::Email::Template;
5 use Scalar::Util qw/ blessed /;
6 extends 'Catalyst::View::Email';
12 Catalyst::View::Email::Template - Send Templated Email from Catalyst
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.
22 WARNING: since version 0.10 the configuration options slightly changed!
24 Use the helper to create your view:
26 $ script/myapp_create.pl view Email::Template Email::Template
28 For basic configuration look at L<Catalyst::View::Email/CONFIGURATION>.
30 In your app configuration (example in L<YAML>):
32 View::Email::Template:
33 # Optional prefix to look somewhere under the existing configured
36 template_prefix: email
37 # Define the defaults for the mail
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!
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:
51 sub controller : Private {
52 my ( $self, $c ) = @_;
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'
64 $c->forward( $c->view('Email::Template') );
67 Alternatively if you want more control over your templates you can use the following idiom
68 to override the defaults:
72 template => 'email/test.html.tt',
73 content_type => 'text/html',
78 template => 'email/test.plain.mason',
79 content_type => 'text/plain',
86 =head1 HANDLING ERRORS
88 See L<Catalyst::View::Email/HANDLING ERRORS>.
92 # here the defaults of Catalyst::View::Email are extended by the additional
93 # ones Template.pm needs.
98 default => sub { "email" },
102 has 'template_prefix' => (
105 default => sub { '' },
115 content_type => 'text/html',
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.
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.
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
139 my ( $self, $view ) = @_;
141 croak "C::V::Email::Template's configured view '$view' isn't an object!"
142 unless ( blessed($view) );
145 "C::V::Email::Template's configured view '$view' isn't an Catalyst::View!"
146 unless ( $view->isa('Catalyst::View') );
149 "C::V::Email::Template's configured view '$view' doesn't have a render method!"
150 unless ( $view->can('render') );
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.
165 my ( $self, $c, $attrs ) = @_;
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};
174 # use the view specified for the email part
175 if ( exists $attrs->{view}
176 && defined $attrs->{view}
177 && $attrs->{view} ne '' )
179 $view = $c->view( $attrs->{view} );
181 "C::V::Email::Template uses specified view $view for rendering.")
185 # if none specified use the configured default view
186 elsif ($default_view) {
187 $view = $c->view($default_view);
189 "C::V::Email::Template uses default view $view for rendering.")
193 # else fallback to Catalysts default view
197 "C::V::Email::Template uses Catalysts default view $view for rendering."
201 # validate the per template view
202 $self->_validate_view($view);
204 # prefix with template_prefix if configured
206 $template_prefix ne ''
207 ? join( '/', $template_prefix, $attrs->{template} )
208 : $attrs->{template};
210 # setup the attributes (merge with defaults)
211 my $e_m_attrs = $self->SUPER::setup_attributes( $c, $attrs );
213 # render the email part
214 my $output = $view->render(
218 content_type => $e_m_attrs->{content_type},
219 stash_key => $self->stash_key,
224 croak $output->can('as_string') ? $output->as_string : $output;
227 return Email::MIME->create(
228 attributes => $e_m_attrs,
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
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};
249 # in case of the simple api only one
252 # now find out if the single or multipart api was used
253 # prefer the multipart one
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' )
261 # loop through all parts of the mail
262 foreach my $part ( @{ $c->stash->{$stash_key}->{templates} } ) {
264 $self->generate_part(
267 view => $part->{view},
268 template => $part->{template},
269 content_type => $part->{content_type},
270 charset => $part->{charset},
277 elsif ( $c->stash->{$stash_key}->{template} ) {
279 $self->generate_part( $c,
280 { template => $c->stash->{$stash_key}->{template}, } );
283 delete $c->stash->{$stash_key}->{body};
284 $c->stash->{$stash_key}->{parts} ||= [];
285 push @{ $c->stash->{$stash_key}->{parts} }, @parts;
287 return $self->$orig($c);
297 There needs to be a method to support attachments. What I am thinking is
298 something along these lines:
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",
312 =head2 L<Catalyst::View::Email> - Send plain boring emails with Catalyst
314 =head2 L<Catalyst::Manual> - The Catalyst Manual
316 =head2 L<Catalyst::Manual::Cookbook> - The Catalyst Cookbook
320 J. Shirley <jshirley@gmail.com>
322 Simon Elliott <cpan@browsing.co.uk>
324 Alexander Hartmaier <abraxxa@cpan.org>
328 This library is free software, you can redistribute it and/or modify it under
329 the same terms as Perl itself.