From: Alexander Hartmaier Date: Thu, 22 Nov 2007 22:06:37 +0000 (+0000) Subject: POD updates X-Git-Tag: v0.14~13 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=4a44bcd32c38e882732c099871b6dd04ba29ac49;p=catagits%2FCatalyst-View-Email.git POD updates released as 0.10 --- diff --git a/Changes b/Changes index 5c3d38f..4edc849 100644 --- a/Changes +++ b/Changes @@ -1,7 +1,8 @@ Revision history for Perl extension Catalyst::View::Email. -0.10 +0.10 2007-11-22 23:00:00 - Refactored by Alexander Hartmaier with api changes + and POD improvements 0.06 - Fixing some slight issues with configuration not being handled diff --git a/lib/Catalyst/View/Email.pm b/lib/Catalyst/View/Email.pm index 73bc44f..68aefe2 100644 --- a/lib/Catalyst/View/Email.pm +++ b/lib/Catalyst/View/Email.pm @@ -11,7 +11,7 @@ use Email::MIME::Creator; use base qw/ Catalyst::View /; -our $VERSION = '0.09999_02'; +our $VERSION = '0.10'; __PACKAGE__->mk_accessors(qw/ mailer /); @@ -21,11 +21,13 @@ Catalyst::View::Email - Send Email from Catalyst =head1 SYNOPSIS -This module simply sends out email from a stash key specified in the +This module sends out emails from a stash key specified in the configuration settings. =head1 CONFIGURATION +WARNING: since version 0.10 the configuration options slightly changed! + Use the helper to create your View: $ script/myapp_create.pl view Email Email @@ -59,45 +61,54 @@ In your app configuration (example in L): username: username password: password -=head2 NOTE ON SMTP +=head1 NOTE ON SMTP If you use SMTP and don't specify Host, it will default to localhost and -attempt delivery. This often times means an email will sit in a queue -somewhere and not be delivered. +attempt delivery. This often means an email will sit in a queue and +not be delivered. =cut __PACKAGE__->config( stash_key => 'email', default => { - content_type => 'text/html', + content_type => 'text/plain', }, ); =head1 SENDING EMAIL -In your controller, simply forward to the view after populating the C +Sending email is just filling the stash and forwarding to the view: sub controller : Private { my ( $self, $c ) = @_; + $c->stash->{email} = { - to => q{catalyst@rocksyoursocks.com}, - cc => q{foo@bar.com}, - bcc => q{hidden@secret.com}, - from => q{no-reply@socksthatarerocked.com}, - subject => qq{Your Subject Here}, - body => qq{Body Body Body} + to => 'jshirley@gmail.com', + cc => 'abraxxa@cpan.org', + bcc => [ qw/hidden@secret.com hidden2@foobar.com/ ], + from => 'no-reply@foobar.com', + subject => 'I am a Catalyst generated email', + body => 'Body Body Body', }; - $c->forward( $c->view('Email' ) ); + + $c->forward( $c->view('Email') ); } -Alternatively, you can use a more raw interface, and specify the headers as -an array reference. +Alternatively you can use a more raw interface and specify the headers as +an array reference like it is passed to L. +Note that you may also mix both syntaxes if you like ours better but need to +specify additional header attributes. +The attributes are appended to the header array reference without overwriting +contained ones. $c->stash->{email} = { header => [ - To => 'foo@bar.com', - Subject => 'Note the capitalization differences' + To => 'jshirley@gmail.com', + Cc => 'abraxxa@cpan.org', + Bcc => [ qw/hidden@secret.com hidden2@foobar.com/ ], + From => 'no-reply@foobar.com', + Subject => 'Note the capitalization differences', ], body => qq{Ain't got no body, and nobody cares.}, # Or, send parts @@ -108,22 +119,23 @@ an array reference. disposition => 'attachment', charset => 'US-ASCII', }, - body => qq{Got a body, but didn't get ahead.} + body => qq{Got a body, but didn't get ahead.}, ) ], }; =head1 HANDLING ERRORS -If the email fails to send, the view will die (throw an exception). After -your forward to the view, it is a good idea to check for errors: +If the email fails to send, the view will die (throw an exception). +After your forward to the view, it is a good idea to check for errors: + + $c->forward( $c->view('Email') ); - $c->forward( $c->view('Email' ) ); if ( scalar( @{ $c->error } ) ) { $c->error(0); # Reset the error condition if you need to - $c->res->body('Oh noes!'); + $c->response->body('Oh noes!'); } else { - $c->res->body('Email sent A-OK! (At least as far as we can tell)'); + $c->response->body('Email sent A-OK! (At least as far as we can tell)'); } =head1 USING TEMPLATES FOR EMAIL @@ -132,14 +144,20 @@ Now, it's no fun to just send out email using plain strings. Take a look at L to see how you can use your favourite template engine to render the mail body. +=head1 METHODS + +=over 4 + +=item new + +Validates the base config and creates the L object for later use +by process. =cut sub new { my $self = shift->next::method(@_); - my ( $c, $arguments ) = @_; - my $stash_key = $self->{stash_key}; croak "$self stash_key isn't defined!" if ($stash_key eq ''); @@ -150,7 +168,8 @@ sub new { croak "$mailer is not supported, see Email::Send" unless $sender->mailer_available($mailer); $sender->mailer($mailer); - } else { + } + else { # Default case, run through the most likely options first. for ( qw/SMTP Sendmail Qmail/ ) { $sender->mailer($_) and last if $sender->mailer_available($_); @@ -173,7 +192,7 @@ sub new { return $self; } -=head2 process +=item process($c) The process method does the actual processing when the view is dispatched to. @@ -233,8 +252,6 @@ sub process { my $message = $self->generate_message( $c, \%mime ); - #my $message = Email::MIME->create(%mime); - if ( $message ) { my $return = $self->mailer->send($message); # return is a Return::Value object, so this will stringify as the error @@ -245,9 +262,9 @@ sub process { } } -=head2 setup_attributes +=item setup_attributes($c, $attr) -Merge attributes with the configured defaults. You can override this method to +Merge attributes with the configured defaults. You can override this method to return a structure to pass into L which subsequently passes the return value of this method to Email::MIME->create under the C key. @@ -281,7 +298,7 @@ sub setup_attributes { return $e_m_attrs; } -=head2 generate_message($c, $attr) +=item generate_message($c, $attr) Generate a message part, which should be an L object and return it. @@ -298,6 +315,8 @@ sub generate_message { return Email::MIME->create(%$attr); } +=back + =head1 SEE ALSO =head2 L - Send fancy template emails with Cat @@ -310,6 +329,8 @@ sub generate_message { J. Shirley +Alexander Hartmaier + =head1 CONTRIBUTORS (Thanks!) @@ -322,8 +343,6 @@ Simon Elliott Roman Filippov -Alexander Hartmaier - =head1 LICENSE This library is free software, you can redistribute it and/or modify it under diff --git a/lib/Catalyst/View/Email/Template.pm b/lib/Catalyst/View/Email/Template.pm index c7adcda..e783585 100644 --- a/lib/Catalyst/View/Email/Template.pm +++ b/lib/Catalyst/View/Email/Template.pm @@ -11,7 +11,7 @@ use Email::MIME::Creator; use base qw/ Catalyst::View::Email /; -our $VERSION = '0.09999_02'; +our $VERSION = '0.10'; =head1 NAME @@ -19,16 +19,20 @@ 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 +40,34 @@ 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( $c->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 => [ qw/hidden@secret.com hidden2@foobar.com/ ], + from => 'no-reply@foobar.com', + subject => 'I am a Catalyst generated email', + template => 'test.tt', + }; + + $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,7 +88,9 @@ to override the defaults: ] -If it fails $c->error will have the error message. +=head1 HANDLING ERRORS + +See L. =cut @@ -131,19 +122,23 @@ __PACKAGE__->config( sub _validate_view { my ($self, $view) = @_; - croak "Email::Template's configured view '$view' isn't an object!" + 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!" + 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!" + croak "C::V::Email::Template's configured view '$view' doesn't have a render method!" unless ($view->can('render')); } -=head2 generate_part +=head1 METHODS + +=over 4 -Generate a MIME part to include in the email. Since the email is template based +=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 @@ -199,12 +194,12 @@ sub generate_part { ); } -=head2 process +=item process -The process method is called when the view is dispatched to. This creates the +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 +L for processing, which in turn hands off to +L. =cut @@ -259,6 +254,8 @@ sub process { return $self->next::method($c); } +=back + =head1 TODO =head2 ATTACHMENTS @@ -290,7 +287,7 @@ J. Shirley Simon Elliott -Alexander Hartmaier +Alexander Hartmaier =head1 LICENSE