X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FView%2FEmail%2FTemplate.pm;h=11a9d7bb12285641c67f763bf9c08b8d4ab4250f;hb=5d205d68e1cd576075c734a6d9ce2a286cc0d607;hp=96fd76c706e8df2098f8e3e767b3bc3ff0629e04;hpb=ea115f9bbc60c54fe194d288a877ca864a2840aa;p=catagits%2FCatalyst-View-Email.git diff --git a/lib/Catalyst/View/Email/Template.pm b/lib/Catalyst/View/Email/Template.pm index 96fd76c..11a9d7b 100644 --- a/lib/Catalyst/View/Email/Template.pm +++ b/lib/Catalyst/View/Email/Template.pm @@ -1,34 +1,32 @@ 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.09999_01'; - +our $VERSION = '0.28'; +$VERSION = eval $VERSION; =head1 NAME Catalyst::View::Email::Template - Send Templated Email from Catalyst =head1 SYNOPSIS -Sends Templated mail, based upon your default view. It captures 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 using Email::MIME::Creator and sends it out. +email using L and sends it out. =head1 CONFIGURATION -Use the helper to create your View: +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: @@ -36,49 +34,35 @@ In your app configuration (example in L): # template paths. # Default: none template_prefix: email - # Where to look in the stash for the email information. - # Default: email - stash_key: email # Define the defaults for the mail default: - # Defines the default content type (mime type). - # Mandatory - content_type: text/html - # Defines the default charset for every MIME part with the content - # type text. - # According to RFC2049 a MIME part without a charset should - # be treated as US-ASCII by the mail client. - # If the charset is not set it won't be set for all MIME parts - # without an overridden one. - # Default: none - charset: utf-8 # 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 - # Setup how to send the email - # All those options are passed directly to Email::Send, - # for all available options look at its docs. - sender: - mailer: SMTP - mailer_args: - Host: smtp.example.com # defaults to localhost - username: username - password: password =head1 SENDING EMAIL -Sending email is just setting up your defaults, the 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', - template => '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 to override the defaults: @@ -99,17 +83,40 @@ to override the defaults: ] -If it fails $c->error will have the error message. +=head1 HANDLING ERRORS + +See L. =cut # here the defaults of Catalyst::View::Email are extended by the additional # ones Template.pm needs. -__PACKAGE__->config( - template_prefix => '', +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 @@ -129,132 +136,159 @@ __PACKAGE__->config( #multipart/alternative sub _validate_view { - my ($self, $view) = @_; - - croak "Email::Template's configured view '$view' isn't an object!" - unless (blessed($view)); + my ( $self, $view ) = @_; + + croak "C::V::Email::Template's configured view '$view' isn't an object!" + unless ( blessed($view) ); - croak "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' isn't an Catalyst::View!" + unless ( $view->isa('Catalyst::View') ); - croak "Email::Template's configured view '$view' doesn't have a render method!" - unless ($view->can('render')); + croak +"C::V::Email::Template's configured view '$view' doesn't have a render method!" + unless ( $view->can('render') ); } -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}; +=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. - my $e_m_attrs = {}; +=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; + 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; } + # 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->debug( + "C::V::Email::Template uses default view $view for rendering.") + if $c->debug; } + # else fallback to Catalysts default view else { $view = $c->view; - $c->log->debug("C::V::Email::Template uses back to catalysts default view $view for rendering.") if $c->debug;; + $c->log->debug( +"C::V::Email::Template uses Catalysts default view $view for rendering." + ) if $c->debug; } # 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}; - - if (exists $attrs->{content_type} && defined $attrs->{content_type} && $attrs->{content_type} ne '') { - $e_m_attrs->{content_type} = $attrs->{content_type}; - } - elsif (defined $default_content_type && $default_content_type ne '') { - $e_m_attrs->{content_type} = $default_content_type; - } - - if (exists $attrs->{charset} && defined $attrs->{charset} && $attrs->{charset} ne '') { - $e_m_attrs->{charset} = $attrs->{charset}; - } - elsif (defined $default_charset && $default_charset ne '') { - $e_m_attrs->{charset} = $default_charset; - } + 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; + 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; } - + return Email::MIME->create( attributes => $e_m_attrs, - body => $output, + body => $output, ); } -sub process { - my ( $self, $c ) = @_; +=item process - # don't validate template_prefix +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. - # the default view is validated if used +=cut - # the content type should be validated by Email::MIME::Creator - - my $stash_key = $self->{stash_key}; +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}; - croak "No template specified for rendering" - unless $c->stash->{$stash_key}->{template} - or $c->stash->{$stash_key}->{templates}; - - # this array holds the Email::MIME objects # in case of the simple api only one - my @parts = (); + 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} + if ( $c->stash->{$stash_key}->{templates} && ref $c->stash->{$stash_key}->{templates} eq 'ARRAY' - && ref $c->stash->{$stash_key}->{templates}[0] eq 'HASH') { + && 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}, - }); - } + 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}, + } + ); + } } + # single part api - elsif($c->stash->{$stash_key}->{template}) { - push @parts, $self->_generate_part($c, { - template => $c->stash->{$stash_key}->{template}, - }); + 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 @@ -287,7 +321,7 @@ J. Shirley Simon Elliott -Alexander Hartmaier +Alexander Hartmaier =head1 LICENSE