X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FView%2FEmail%2FTemplate.pm;h=4586c7738373f2a2c5f6f5f729046c5fb79aa060;hb=9ff9161d841a9471f1bef9ba767b12cf342458cc;hp=991f199b37cea862b17d4c84eae9e2b7c7c69dc9;hpb=4bf6fed15d2a2d3342ef3ed7c72f42600c2994a6;p=catagits%2FCatalyst-View-Email.git diff --git a/lib/Catalyst/View/Email/Template.pm b/lib/Catalyst/View/Email/Template.pm index 991f199..4586c77 100644 --- a/lib/Catalyst/View/Email/Template.pm +++ b/lib/Catalyst/View/Email/Template.pm @@ -1,86 +1,122 @@ package Catalyst::View::Email::Template; -use warnings; -use strict; - -use Class::C3; +use Moose; use Carp; +use Scalar::Util qw/ blessed /; +extends 'Catalyst::View::Email'; -use Email::MIME::Creator; - -use base qw|Catalyst::View::Email|; - -our $VERSION = '0.08'; - -__PACKAGE__->mk_accessors( qw(default_view template_prefix) ); - +our $VERSION = '0.21_01'; +$VERSION = eval $VERSION; =head1 NAME Catalyst::View::Email::Template - Send Templated Email from Catalyst =head1 SYNOPSIS -Sends Templated mail, based upon your Default View. Will capture the output +Sends templated mail, based upon your default view. It captures the output of the rendering path, slurps in based on mime-types and assembles a multi-part -email and sends it out. +email using L and sends it out. + +=head1 CONFIGURATION -=head2 CONFIGURATION +WARNING: since version 0.10 the configuration options slightly changed! + +Use the helper to create your view: + + $ script/myapp_create.pl view Email::Template Email::Template + +For basic configuration look at L. + +In your app configuration (example in L): View::Email::Template: - # Set it up so if you have multiple parts, they're alternatives. - # This is on the top-level message, not the individual parts. - content_type: multipart/alternative # Optional prefix to look somewhere under the existing configured # template paths. + # Default: none template_prefix: email - # Where to look in the stash for the email information - stash_key: email - # Setup how to send the email - sender: - method: SMTP - host: smtp.myhost.com - username: username - password: password + # Define the defaults for the mail + default: + # Defines the default view used to render the templates. + # If none is specified neither here nor in the stash + # Catalysts default view is used. + # Warning: if you don't tell Catalyst explicit which of your views should + # be its default one, C::V::Email::Template may choose the wrong one! + view: TT =head1 SENDING EMAIL -Sending email is just setting up your stash key, and forwarding to the view. - - $c->stash->{email} = { - to => 'jshirley@gmail.com', - from => 'no-reply@foobar.com', - subject => 'I am a Catalyst generated email', - # Specify which templates to include - templates => [ - qw{text_plain/test.tt}, - qw{text_html/test.tt} - ] - }; - $c->forward('View::Email::Template'); +Sending email works just like for L but by specifying +the template instead of the body and forwarding to your Email::Template view: + + sub controller : Private { + my ( $self, $c ) = @_; + + $c->stash->{email} = { + to => 'jshirley@gmail.com', + cc => 'abraxxa@cpan.org', + bcc => 'hidden@secret.com hidden2@foobar.com', + from => 'no-reply@foobar.com', + subject => 'I am a Catalyst generated email', + template => 'test.tt', + content_type => 'multipart/alternative' + }; + + $c->forward( $c->view('Email::Template') ); + } -Alternatively if you want more control over your templates you can use the following idiom :- +Alternatively if you want more control over your templates you can use the following idiom +to override the defaults: templates => [ - { view => 'HTML', - template => 'email/test.html.tt', - content_type => 'text/html' - }, - { view => 'Text', - template => 'email/test.plain.tt', - content_type => 'text/plain' - } - + { + template => 'email/test.html.tt', + content_type => 'text/html', + charset => 'utf-8', + view => 'TT', + }, + { + template => 'email/test.plain.mason', + content_type => 'text/plain', + charset => 'utf-8', + view => 'Mason', + } ] -If it fails $c->error will have the error message. +=head1 HANDLING ERRORS + +See L. =cut -__PACKAGE__->config( - template_prefix => '', +# here the defaults of Catalyst::View::Email are extended by the additional +# ones Template.pm needs. + +has 'stash_key' => ( + is => 'rw', + isa => 'Str', + default => sub { "email" }, + lazy => 1, ); +has 'template_prefix' => ( + is => 'rw', + isa => 'Str', + default => sub { '' }, + lazy => 1, +); + +has 'default' => ( + is => 'rw', + isa => 'HashRef', + default => sub { + { + view => 'TT', + content_type => 'text/html', + }; + }, + lazy => 1, +); # This view hitches into your default view and will call the render function # on the templates provided. This means that you have a layer of abstraction @@ -94,104 +130,165 @@ __PACKAGE__->config( # into an Email::MIME container. The mime-type will be stupidly guessed with # the subdir on the template. # -# TODO: Make this unretarded. -# -sub process { - my ( $self, $c ) = @_; - - my $stash_key = $self->stash_key || 'email'; - - croak "No template specified for rendering" - unless $c->stash->{$stash_key}->{template} or - $c->stash->{$stash_key}->{templates}; - # Where to look - my $template_prefix = $self->template_prefix; - my @templates = (); - - if ( $c->stash->{$stash_key}->{templates} && !ref $c->stash->{$stash_key}->{templates}[0]) { - push @templates, map { - join('/', $template_prefix, $_); - } @{$c->stash->{$stash_key}->{templates}}; - - } elsif($c->stash->{$stash_key}->{template}) { - push @templates, join('/', $template_prefix, - $c->stash->{$stash_key}->{template}); + +# Set it up so if you have multiple parts, they're alternatives. +# This is on the top-level message, not the individual parts. +#multipart/alternative + +sub _validate_view { + my ( $self, $view ) = @_; + + croak "C::V::Email::Template's configured view '$view' isn't an object!" + unless ( blessed($view) ); + + croak + "C::V::Email::Template's configured view '$view' isn't an Catalyst::View!" + unless ( $view->isa('Catalyst::View') ); + + croak +"C::V::Email::Template's configured view '$view' doesn't have a render method!" + unless ( $view->can('render') ); +} + +=head1 METHODS + +=over 4 + +=item generate_part + +Generates a MIME part to include in the email. Since the email is template based +every template piece is a separate part that is included in the email. + +=cut + +sub generate_part { + my ( $self, $c, $attrs ) = @_; + + my $template_prefix = $self->template_prefix; + my $default_view = $self->default->{view}; + my $default_content_type = $self->default->{content_type}; + my $default_charset = $self->default->{charset}; + + my $view; + + # use the view specified for the email part + if ( exists $attrs->{view} + && defined $attrs->{view} + && $attrs->{view} ne '' ) + { + $view = $c->view( $attrs->{view} ); + $c->log->debug( + "C::V::Email::Template uses specified view $view for rendering.") + if $c->debug; } - - my $default_view = $c->view( $self->default_view ); - unless ( $default_view->can('render') ) { - croak "Email::Template's configured view does not have a render method!"; + # if none specified use the configured default view + elsif ($default_view) { + $view = $c->view($default_view); + $c->log->debug( + "C::V::Email::Template uses default view $view for rendering.") + if $c->debug; } - #$c->log->_dump($default_view->config); - - my @parts = (); - foreach my $template ( @templates ) { - $template =~ s#^/+##; # Make sure that we don't have an absolute path. - # This seems really stupid to me... argh. will give me nightmares! - my $template_path = $template; - $template_path =~ s#^$template_prefix/##; - my ( $content_type, $extra ) = split('/', $template_path); - if ( $extra ) { - $content_type ||= 'text/plain'; - $content_type =~ s#_#/#; - } else { - $content_type = 'text/plain'; - } + # else fallback to Catalysts default view + else { + $view = $c->view; + $c->log->debug( +"C::V::Email::Template uses Catalysts default view $view for rendering." + ) if $c->debug; + } - my $output = $default_view->render( $c, $template, { - content_type => $content_type, - stash_key => $self->stash_key, + # validate the per template view + $self->_validate_view($view); + + # prefix with template_prefix if configured + my $template = + $template_prefix ne '' + ? join( '/', $template_prefix, $attrs->{template} ) + : $attrs->{template}; + + # setup the attributes (merge with defaults) + my $e_m_attrs = $self->SUPER::setup_attributes( $c, $attrs ); + + # render the email part + my $output = $view->render( + $c, + $template, + { + content_type => $e_m_attrs->{content_type}, + stash_key => $self->stash_key, %{$c->stash}, - }); + } + ); + if ( ref $output ) { + croak $output->can('as_string') ? $output->as_string : $output; + } - # Got a ref, not a scalar. An error! - if ( ref $output ) { - croak $output->can("as_string") ? $output->as_string : $output; + return Email::MIME->create( + attributes => $e_m_attrs, + body => $output, + ); +} + +=item process + +The process method is called when the view is dispatched to. This creates the +multipart message and then sends the message contents off to +L for processing, which in turn hands off to +L. + +=cut + +around 'process' => sub { + my ( $orig, $self, $c, @args ) = @_; + my $stash_key = $self->stash_key; + return $self->$orig( $c, @args ) + unless $c->stash->{$stash_key}->{template} + or $c->stash->{$stash_key}->{templates}; + + # in case of the simple api only one + my @parts = (); + + # now find out if the single or multipart api was used + # prefer the multipart one + + # multipart api + if ( $c->stash->{$stash_key}->{templates} + && ref $c->stash->{$stash_key}->{templates} eq 'ARRAY' + && ref $c->stash->{$stash_key}->{templates}[0] eq 'HASH' ) + { + + # loop through all parts of the mail + foreach my $part ( @{ $c->stash->{$stash_key}->{templates} } ) { + push @parts, + $self->generate_part( + $c, + { + view => $part->{view}, + template => $part->{template}, + content_type => $part->{content_type}, + charset => $part->{charset}, + } + ); } - push @parts, Email::MIME->create( - attributes => { - content_type => $content_type - }, - body => $output - ); } - #add user parts :- - if ( $c->stash->{$stash_key}->{'templates'} && ref $c->stash->{$stash_key}->{templates}[0] ) { - foreach my $part (@{$c->stash->{$stash_key}->{'templates'}}) { - my $view = $c->view($part->{'view'} || $self->config->{default_view}); - - my $content_type = $part->{'content_type'} || 'text/plain'; - unless ( $view->can('render') ) { - croak "Part does not have valid render view"; - } - - my $output = $view->render( $c, $part->{'template'}, { - 'content_type' => $content_type, - %{$c->stash} }); - - if ( ref $output ) { - croak $output->can("as_string") ? $output->as_string : $output; - } - - push @parts, Email::MIME->create( - attributes => { - content_type => $content_type - }, - body => $output - ); - } - } + # single part api + elsif ( $c->stash->{$stash_key}->{template} ) { + push @parts, + $self->generate_part( $c, + { template => $c->stash->{$stash_key}->{template}, } ); + } delete $c->stash->{$stash_key}->{body}; $c->stash->{$stash_key}->{parts} ||= []; - push @{$c->stash->{$stash_key}->{parts}}, @parts; + push @{ $c->stash->{$stash_key}->{parts} }, @parts; + + return $self->$orig($c); - # Let C::V::Email do the actual sending. We just assemble the tasty bits. - return $self->next::method($c); -} +}; + +=back =head1 TODO @@ -224,6 +321,8 @@ J. Shirley Simon Elliott +Alexander Hartmaier + =head1 LICENSE This library is free software, you can redistribute it and/or modify it under @@ -232,4 +331,3 @@ the same terms as Perl itself. =cut 1; -