use base qw/ Catalyst::View /;
-our $VERSION = '0.09999_01';
+our $VERSION = '0.10';
__PACKAGE__->mk_accessors(qw/ mailer /);
=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
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<stash_key>
+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('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<Email::MIME::Creator>.
+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
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 FAILURES
+=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('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
Take a look at L<Catalyst::View::Email::Template> 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<Email::Send> 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 '');
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($_);
return $self;
}
+=item process($c)
+
+The process method does the actual processing when the view is dispatched to.
+
+This method sets up the email parts and hands off to L<Email::Send> to handle
+the actual email delivery.
+
+=cut
+
sub process {
my ( $self, $c ) = @_;
my $email = $c->stash->{$self->{stash_key}};
croak "Can't send email without a valid email structure"
unless $email;
-
+
if ( exists $self->{content_type} ) {
$email->{content_type} ||= $self->{content_type};
}
$mime{attributes}->{charset} = $self->{default}->{charset};
}
- my $message = $self->generate_part( \%mime );
-
- #my $message = Email::MIME->create(%mime);
+ my $message = $self->generate_message( $c, \%mime );
if ( $message ) {
my $return = $self->mailer->send($message);
+ # return is a Return::Value object, so this will stringify as the error
+ # in the case of a failure.
croak "$return" if !$return;
} else {
croak "Unable to create message";
}
}
+=item setup_attributes($c, $attr)
+
+Merge attributes with the configured defaults. You can override this method to
+return a structure to pass into L<generate_message> which subsequently
+passes the return value of this method to Email::MIME->create under the
+C<attributes> key.
+
+=cut
+
sub setup_attributes {
my ( $self, $c, $attrs ) = @_;
my $e_m_attrs = {};
if (exists $attrs->{content_type} && defined $attrs->{content_type} && $attrs->{content_type} ne '') {
+ $c->log->debug('C::V::Email uses specified content_type ' . $attrs->{content_type} . '.') if $c->debug;
$e_m_attrs->{content_type} = $attrs->{content_type};
}
elsif (defined $default_content_type && $default_content_type ne '') {
+ $c->log->debug("C::V::Email uses default content_type $default_content_type.") if $c->debug;
$e_m_attrs->{content_type} = $default_content_type;
}
return $e_m_attrs;
}
-sub generate_part {
- my ( $self, $attr ) = @_;
+=item generate_message($c, $attr)
+
+Generate a message part, which should be an L<Email::MIME> object and return it.
+
+Takes the attributes, merges with the defaults as necessary and returns a
+message object.
+
+=cut
+
+sub generate_message {
+ my ( $self, $c, $attr ) = @_;
# setup the attributes (merge with defaults)
- $attr->{attributes} = $self->setup_attributes($attr->{attributes});
+ $attr->{attributes} = $self->setup_attributes($c, $attr->{attributes});
return Email::MIME->create(%$attr);
}
+=back
+
=head1 SEE ALSO
=head2 L<Catalyst::View::Email::Template> - Send fancy template emails with Cat
J. Shirley <jshirley@gmail.com>
+Alexander Hartmaier <abraxxa@cpan.org>
+
=head1 CONTRIBUTORS
(Thanks!)
Roman Filippov
-Alexander Hartmaier <alex_hartmaier@hotmail.com>
-
=head1 LICENSE
This library is free software, you can redistribute it and/or modify it under
projects / catagits/Catalyst-View-Email.git / blobdiff