[Catalyst-commits] r7156 - in Catalyst-View-Email/0.10: .
lib/Catalyst/View lib/Catalyst/View/Email
abraxxa at dev.catalyst.perl.org
abraxxa at dev.catalyst.perl.org
Thu Nov 22 22:06:37 GMT 2007
Author: abraxxa
Date: 2007-11-22 22:06:37 +0000 (Thu, 22 Nov 2007)
New Revision: 7156
Modified:
Catalyst-View-Email/0.10/Changes
Catalyst-View-Email/0.10/lib/Catalyst/View/Email.pm
Catalyst-View-Email/0.10/lib/Catalyst/View/Email/Template.pm
Log:
POD updates
released as 0.10
Modified: Catalyst-View-Email/0.10/Changes
===================================================================
--- Catalyst-View-Email/0.10/Changes 2007-11-22 19:48:08 UTC (rev 7155)
+++ Catalyst-View-Email/0.10/Changes 2007-11-22 22:06:37 UTC (rev 7156)
@@ -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
Modified: Catalyst-View-Email/0.10/lib/Catalyst/View/Email/Template.pm
===================================================================
--- Catalyst-View-Email/0.10/lib/Catalyst/View/Email/Template.pm 2007-11-22 19:48:08 UTC (rev 7155)
+++ Catalyst-View-Email/0.10/lib/Catalyst/View/Email/Template.pm 2007-11-22 22:06:37 UTC (rev 7156)
@@ -11,7 +11,7 @@
use base qw/ Catalyst::View::Email /;
-our $VERSION = '0.09999_02';
+our $VERSION = '0.10';
=head1 NAME
@@ -19,16 +19,20 @@
=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<Email::MIME::Creator> 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<Catalyst::View::Email/CONFIGURATION>.
+
In your app configuration (example in L<YAML>):
View::Email::Template:
@@ -36,50 +40,35 @@
# 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.
+Sending email works just like for L<Catalyst::View::Email> but by specifying
+the template instead of the body and forwarding to your Email::Template view:
- $c->stash->{email} = {
- to => 'jshirley at gmail.com',
- from => 'no-reply at foobar.com',
- subject => 'I am a Catalyst generated email',
- template => 'test.tt',
- };
- $c->forward( $c->view('Email::Template' ) );
+ sub controller : Private {
+ my ( $self, $c ) = @_;
+ $c->stash->{email} = {
+ to => 'jshirley at gmail.com',
+ cc => 'abraxxa at cpan.org',
+ bcc => [ qw/hidden at secret.com hidden2 at foobar.com/ ],
+ from => 'no-reply at 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,8 +88,10 @@
]
-If it fails $c->error will have the error message.
+=head1 HANDLING ERRORS
+See L<Catalyst::View::Email/HANDLING ERRORS>.
+
=cut
# here the defaults of Catalyst::View::Email are extended by the additional
@@ -131,19 +122,23 @@
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
-Generate a MIME part to include in the email. Since the email is template based
+=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
@@ -199,12 +194,12 @@
);
}
-=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<Catalyst::View::Email> for processing, which in turn hands off to
-L<Email::Send>
+L<Catalyst::View::Email> for processing, which in turn hands off to
+L<Email::Send>.
=cut
@@ -259,6 +254,8 @@
return $self->next::method($c);
}
+=back
+
=head1 TODO
=head2 ATTACHMENTS
@@ -290,7 +287,7 @@
Simon Elliott <cpan at browsing.co.uk>
-Alexander Hartmaier <alex_hartmaier at hotmail.com>
+Alexander Hartmaier <abraxxa at cpan.org>
=head1 LICENSE
Modified: Catalyst-View-Email/0.10/lib/Catalyst/View/Email.pm
===================================================================
--- Catalyst-View-Email/0.10/lib/Catalyst/View/Email.pm 2007-11-22 19:48:08 UTC (rev 7155)
+++ Catalyst-View-Email/0.10/lib/Catalyst/View/Email.pm 2007-11-22 22:06:37 UTC (rev 7156)
@@ -11,7 +11,7 @@
use base qw/ Catalyst::View /;
-our $VERSION = '0.09999_02';
+our $VERSION = '0.10';
__PACKAGE__->mk_accessors(qw/ mailer /);
@@ -21,11 +21,13 @@
=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 @@
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 at rocksyoursocks.com},
- cc => q{foo at bar.com},
- bcc => q{hidden at secret.com},
- from => q{no-reply at socksthatarerocked.com},
- subject => qq{Your Subject Here},
- body => qq{Body Body Body}
+ to => 'jshirley at gmail.com',
+ cc => 'abraxxa at cpan.org',
+ bcc => [ qw/hidden at secret.com hidden2 at foobar.com/ ],
+ from => 'no-reply at 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<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 at bar.com',
- Subject => 'Note the capitalization differences'
+ To => 'jshirley at gmail.com',
+ Cc => 'abraxxa at cpan.org',
+ Bcc => [ qw/hidden at secret.com hidden2 at foobar.com/ ],
+ From => 'no-reply at foobar.com',
+ Subject => 'Note the capitalization differences',
],
body => qq{Ain't got no body, and nobody cares.},
# Or, send parts
@@ -108,22 +119,23 @@
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 @@
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 '');
@@ -150,7 +168,8 @@
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 @@
return $self;
}
-=head2 process
+=item process($c)
The process method does the actual processing when the view is dispatched to.
@@ -233,8 +252,6 @@
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 @@
}
}
-=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<generate_message> which subsequently
passes the return value of this method to Email::MIME->create under the
C<attributes> key.
@@ -281,7 +298,7 @@
return $e_m_attrs;
}
-=head2 generate_message($c, $attr)
+=item generate_message($c, $attr)
Generate a message part, which should be an L<Email::MIME> object and return it.
@@ -298,6 +315,8 @@
return Email::MIME->create(%$attr);
}
+=back
+
=head1 SEE ALSO
=head2 L<Catalyst::View::Email::Template> - Send fancy template emails with Cat
@@ -310,6 +329,8 @@
J. Shirley <jshirley at gmail.com>
+Alexander Hartmaier <abraxxa at cpan.org>
+
=head1 CONTRIBUTORS
(Thanks!)
@@ -322,8 +343,6 @@
Roman Filippov
-Alexander Hartmaier <alex_hartmaier at hotmail.com>
-
=head1 LICENSE
This library is free software, you can redistribute it and/or modify it under
More information about the Catalyst-commits
mailing list