1 package Catalyst::View::Email::Template;
8 use Scalar::Util qw/ blessed /;
10 use Email::MIME::Creator;
12 use base qw/ Catalyst::View::Email /;
14 our $VERSION = '0.09999_01';
18 Catalyst::View::Email::Template - Send Templated Email from Catalyst
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.
28 Use the helper to create your View:
30 $ script/myapp_create.pl view Email::Template Email::Template
32 In your app configuration (example in L<YAML>):
34 View::Email::Template:
35 # Optional prefix to look somewhere under the existing configured
38 template_prefix: email
39 # Where to look in the stash for the email information.
42 # Define the defaults for the mail
44 # Defines the default content type (mime type).
46 content_type: text/html
47 # Defines the default charset for every MIME part with the content
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.
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!
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.
67 Host: smtp.example.com # defaults to localhost
73 Sending email is just setting up your defaults, the stash key and forwarding to the view.
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',
81 $c->forward('View::Email::Template');
83 Alternatively if you want more control over your templates you can use the following idiom
84 to override the defaults:
88 template => 'email/test.html.tt',
89 content_type => 'text/html',
94 template => 'email/test.plain.mason',
95 content_type => 'text/plain',
102 If it fails $c->error will have the error message.
106 # here the defaults of Catalyst::View::Email are extended by the additional
107 # ones Template.pm needs.
110 template_prefix => '',
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.
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.
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
132 my ($self, $view) = @_;
134 croak "Email::Template's configured view '$view' isn't an object!"
135 unless (blessed($view));
137 croak "Email::Template's configured view '$view' isn't an Catalyst::View!"
138 unless ($view->isa('Catalyst::View'));
140 croak "Email::Template's configured view '$view' doesn't have a render method!"
141 unless ($view->can('render'));
145 my ($self, $c, $attrs) = @_;
147 my $template_prefix = $self->{template_prefix};
148 my $default_view = $self->{default}->{view};
149 my $default_content_type = $self->{default}->{content_type};
150 my $default_charset = $self->{default}->{charset};
153 # use the view specified for the email part
154 if (exists $attrs->{view} && defined $attrs->{view} && $attrs->{view} ne '') {
155 $view = $c->view($attrs->{view});
156 $c->log->debug("C::V::Email::Template uses specified view $view for rendering.") if $c->debug;
158 # if none specified use the configured default view
159 elsif ($default_view) {
160 $view = $c->view($default_view);
161 $c->log->debug("C::V::Email::Template uses default view $view for rendering.") if $c->debug;;
163 # else fallback to Catalysts default view
166 $c->log->debug("C::V::Email::Template uses Catalysts default view $view for rendering.") if $c->debug;;
169 # validate the per template view
170 $self->_validate_view($view);
172 # prefix with template_prefix if configured
173 my $template = $template_prefix ne '' ? join('/', $template_prefix, $attrs->{template}) : $attrs->{template};
175 # setup the attributes (merge with defaults)
176 my $e_m_attrs = $self->setup_attributes($attrs);
178 # render the email part
179 my $output = $view->render( $c, $template, {
180 content_type => $e_m_attrs->{content_type},
181 stash_key => $self->{stash_key},
186 croak $output->can('as_string') ? $output->as_string : $output;
189 return Email::MIME->create(
190 attributes => $e_m_attrs,
196 my ( $self, $c ) = @_;
198 # don't validate template_prefix
200 # the default view is validated if used
202 # the content type should be validated by Email::MIME::Creator
204 my $stash_key = $self->{stash_key};
206 croak "No template specified for rendering"
207 unless $c->stash->{$stash_key}->{template}
208 or $c->stash->{$stash_key}->{templates};
210 # this array holds the Email::MIME objects
211 # in case of the simple api only one
214 # now find out if the single or multipart api was used
215 # prefer the multipart one
218 if ($c->stash->{$stash_key}->{templates}
219 && ref $c->stash->{$stash_key}->{templates} eq 'ARRAY'
220 && ref $c->stash->{$stash_key}->{templates}[0] eq 'HASH') {
221 # loop through all parts of the mail
222 foreach my $part (@{$c->stash->{$stash_key}->{templates}}) {
223 push @parts, $self->generate_part($c, {
224 view => $part->{view},
225 template => $part->{template},
226 content_type => $part->{content_type},
227 charset => $part->{charset},
232 elsif($c->stash->{$stash_key}->{template}) {
233 push @parts, $self->generate_part($c, {
234 template => $c->stash->{$stash_key}->{template},
238 delete $c->stash->{$stash_key}->{body};
239 $c->stash->{$stash_key}->{parts} ||= [];
240 push @{$c->stash->{$stash_key}->{parts}}, @parts;
242 # Let C::V::Email do the actual sending. We just assemble the tasty bits.
243 return $self->next::method($c);
250 There needs to be a method to support attachments. What I am thinking is
251 something along these lines:
254 # Set the body to a file handle object, specify content_type and
255 # the file name. (name is what it is sent at, not the file)
256 { body => $fh, name => "foo.pdf", content_type => "application/pdf" },
257 # Or, specify a filename that is added, and hey, encoding!
258 { filename => "foo.gif", name => "foo.gif", content_type => "application/pdf", encoding => "quoted-printable" },
259 # Or, just a path to a file, and do some guesswork for the content type
260 "/path/to/somefile.pdf",
265 =head2 L<Catalyst::View::Email> - Send plain boring emails with Catalyst
267 =head2 L<Catalyst::Manual> - The Catalyst Manual
269 =head2 L<Catalyst::Manual::Cookbook> - The Catalyst Cookbook
273 J. Shirley <jshirley@gmail.com>
275 Simon Elliott <cpan@browsing.co.uk>
277 Alexander Hartmaier <alex_hartmaier@hotmail.com>
281 This library is free software, you can redistribute it and/or modify it under
282 the same terms as Perl itself.