[catagits/Catalyst-View-Email.git] / lib / Catalyst / View / Email / Template.pm

package Catalyst::View::Email::Template;

use warnings;
use strict;

use Class::C3;
use Carp;
use Scalar::Util qw/ blessed /;

use Email::MIME::Creator;

use base qw/ Catalyst::View::Email /;

our $VERSION = '0.09999_01';

=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
of the rendering path, slurps in based on mime-types and assembles a multi-part
email using Email::MIME::Creator and sends it out.

=head1 CONFIGURATION

Use the helper to create your View:
    
    $ script/myapp_create.pl view Email::Template Email::Template

In your app configuration (example in L<YAML>):

    View::Email::Template:
        # 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.
        # 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');

Alternatively if you want more control over your templates you can use the following idiom
to override the defaults:

    templates => [
        {
            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.

=cut

# here the defaults of Catalyst::View::Email are extended by the additional
# ones Template.pm needs.

__PACKAGE__->config(
    template_prefix => '',
);


# 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
# and you aren't required to modify your templates based on your desired engine
# (Template Toolkit or Mason, for example).  As long as the view adequately
# supports ->render, all things are good.  Mason, and others, are not good.

#
# The path here is to check configuration for the template root, and then
# proceed to call render on the subsequent templates and stuff each one
# into an Email::MIME container.  The mime-type will be stupidly guessed with
# the subdir on the 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 "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 "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};

    my $e_m_attrs = {};

    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 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;;
    }
    # 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;;
    }

    # 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;
    }

    # 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;
    }
	
    return Email::MIME->create(
        attributes => $e_m_attrs,
	body => $output,
    );
}

sub process {
    my ( $self, $c ) = @_;

    # don't validate template_prefix

    # the default view is validated if used

    # the content type should be validated by Email::MIME::Creator
    
    my $stash_key = $self->{stash_key};

    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 = (); 

    # 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},
            });
	}
    }
    # 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;

    # Let C::V::Email do the actual sending.  We just assemble the tasty bits.
    return $self->next::method($c);
}

=head1 TODO

=head2 ATTACHMENTS

There needs to be a method to support attachments.  What I am thinking is
something along these lines:

    attachments => [
        # Set the body to a file handle object, specify content_type and
        # the file name. (name is what it is sent at, not the file)
        { body => $fh, name => "foo.pdf", content_type => "application/pdf" },
        # Or, specify a filename that is added, and hey, encoding!
        { filename => "foo.gif", name => "foo.gif", content_type => "application/pdf", encoding => "quoted-printable" },
        # Or, just a path to a file, and do some guesswork for the content type
        "/path/to/somefile.pdf",
    ]

=head1 SEE ALSO

=head2 L<Catalyst::View::Email> - Send plain boring emails with Catalyst

=head2 L<Catalyst::Manual> - The Catalyst Manual

=head2 L<Catalyst::Manual::Cookbook> - The Catalyst Cookbook

=head1 AUTHORS

J. Shirley <jshirley@gmail.com>

Simon Elliott <cpan@browsing.co.uk>

Alexander Hartmaier <alex_hartmaier@hotmail.com>

=head1 LICENSE

This library is free software, you can redistribute it and/or modify it under
the same terms as Perl itself.

=cut

1;
Commit	Line	Data
529915ab	1	package Catalyst::View::Email::Template;
	2
	3	use warnings;
	4	use strict;
	5
	6	use Class::C3;
	7	use Carp;
ea115f9b	8	use Scalar::Util qw/ blessed /;
529915ab	9
	10	use Email::MIME::Creator;
	11
ea115f9b	12	use base qw/ Catalyst::View::Email /;
529915ab	13
ea115f9b	14	our $VERSION = '0.09999_01';
529915ab	15
	16	=head1 NAME
	17
	18	Catalyst::View::Email::Template - Send Templated Email from Catalyst
	19
	20	=head1 SYNOPSIS
	21
ea115f9b	22	Sends Templated mail, based upon your default view. It captures the output
529915ab	23	of the rendering path, slurps in based on mime-types and assembles a multi-part
ea115f9b	24	email using Email::MIME::Creator and sends it out.
529915ab	25
ea115f9b	26	=head1 CONFIGURATION
	27
	28	Use the helper to create your View:
	29
	30	$ script/myapp_create.pl view Email::Template Email::Template
	31
	32	In your app configuration (example in L<YAML>):
529915ab	33
529915ab	34	View::Email::Template:
529915ab	35	# Optional prefix to look somewhere under the existing configured
ea115f9b	36	# template paths.
ea115f9b	37	# Default: none
529915ab	38	template_prefix: email
06afcdbc	39	# Where to look in the stash for the email information.
ea115f9b	40	# Default: email
529915ab	41	stash_key: email
06afcdbc	42	# Define the defaults for the mail
06afcdbc	43	default:
ea115f9b	44	# Defines the default content type (mime type).
ea115f9b	45	# Mandatory
06afcdbc	46	content_type: text/html
06afcdbc	47	# Defines the default charset for every MIME part with the content
ea115f9b	48	# type text.
ea115f9b	49	# According to RFC2049 a MIME part without a charset should
06afcdbc	50	# be treated as US-ASCII by the mail client.
	51	# If the charset is not set it won't be set for all MIME parts
	52	# without an overridden one.
ea115f9b	53	# Default: none
06afcdbc	54	charset: utf-8
ea115f9b	55	# Defines the default view used to render the templates.
	56	# If none is specified neither here nor in the stash
	57	# Catalysts default view is used.
	58	# Warning: if you don't tell Catalyst explicit which of your views should
	59	# be its default one, C::V::Email::Template may choose the wrong one!
06afcdbc	60	view: TT
529915ab	61	# Setup how to send the email
ea115f9b	62	# All those options are passed directly to Email::Send,
ea115f9b	63	# for all available options look at its docs.
529915ab	64	sender:
06afcdbc	65	mailer: SMTP
	66	mailer_args:
	67	Host: smtp.example.com # defaults to localhost
	68	username: username
	69	password: password
529915ab	70
	71	=head1 SENDING EMAIL
	72
06afcdbc	73	Sending email is just setting up your defaults, the stash key and forwarding to the view.
529915ab	74
	75	$c->stash->{email} = {
	76	to => 'jshirley@gmail.com',
	77	from => 'no-reply@foobar.com',
	78	subject => 'I am a Catalyst generated email',
06afcdbc	79	template => 'test.tt',
529915ab	80	};
	81	$c->forward('View::Email::Template');
	82
06afcdbc	83	Alternatively if you want more control over your templates you can use the following idiom
06afcdbc	84	to override the defaults:
12c85b56	85
12c85b56	86	templates => [
06afcdbc	87	{
	88	template => 'email/test.html.tt',
	89	content_type => 'text/html',
ea115f9b	90	charset => 'utf-8',
06afcdbc	91	view => 'TT',
	92	},
	93	{
	94	template => 'email/test.plain.mason',
	95	content_type => 'text/plain',
ea115f9b	96	charset => 'utf-8',
06afcdbc	97	view => 'Mason',
06afcdbc	98	}
12c85b56	99	]
	100
	101
529915ab	102	If it fails $c->error will have the error message.
	103
	104	=cut
	105
06afcdbc	106	# here the defaults of Catalyst::View::Email are extended by the additional
	107	# ones Template.pm needs.
	108
529915ab	109	__PACKAGE__->config(
	110	template_prefix => '',
	111	);
	112
	113
	114	# This view hitches into your default view and will call the render function
	115	# on the templates provided. This means that you have a layer of abstraction
	116	# and you aren't required to modify your templates based on your desired engine
	117	# (Template Toolkit or Mason, for example). As long as the view adequately
	118	# supports ->render, all things are good. Mason, and others, are not good.
	119
	120	#
	121	# The path here is to check configuration for the template root, and then
	122	# proceed to call render on the subsequent templates and stuff each one
	123	# into an Email::MIME container. The mime-type will be stupidly guessed with
	124	# the subdir on the template.
	125	#
529915ab	126
06afcdbc	127	# Set it up so if you have multiple parts, they're alternatives.
	128	# This is on the top-level message, not the individual parts.
	129	#multipart/alternative
529915ab	130
06afcdbc	131	sub _validate_view {
	132	my ($self, $view) = @_;
	133
	134	croak "Email::Template's configured view '$view' isn't an object!"
	135	unless (blessed($view));
	136
	137	croak "Email::Template's configured view '$view' isn't an Catalyst::View!"
	138	unless ($view->isa('Catalyst::View'));
	139
	140	croak "Email::Template's configured view '$view' doesn't have a render method!"
	141	unless ($view->can('render'));
	142	}
529915ab	143
06afcdbc	144	sub _generate_part {
	145	my ($self, $c, $attrs) = @_;
	146
	147	my $template_prefix = $self->{template_prefix};
	148	my $default_view = $self->{default}->{view};
	149	my $default_content_type = $self->{default}->{content_type};
ea115f9b	150	my $default_charset = $self->{default}->{charset};
	151
	152	my $e_m_attrs = {};
	153
	154	my $view;
	155	# use the view specified for the email part
	156	if (exists $attrs->{view} && defined $attrs->{view} && $attrs->{view} ne '') {
	157	$view = $c->view($attrs->{view});
	158	$c->log->debug("C::V::Email::Template uses specified view $view for rendering.") if $c->debug;
	159	}
	160	# if none specified use the configured default view
	161	elsif ($default_view) {
	162	$view = $c->view($default_view);
	163	$c->log->debug("C::V::Email::Template uses default view $view for rendering.") if $c->debug;;
	164	}
	165	# else fallback to Catalysts default view
	166	else {
	167	$view = $c->view;
c649c40e	168	$c->log->debug("C::V::Email::Template uses Catalysts default view $view for rendering.") if $c->debug;;
ea115f9b	169	}
06afcdbc	170
06afcdbc	171	# validate the per template view
06afcdbc	172	$self->_validate_view($view);
06afcdbc	173
	174	# prefix with template_prefix if configured
	175	my $template = $template_prefix ne '' ? join('/', $template_prefix, $attrs->{template}) : $attrs->{template};
06afcdbc	176
ea115f9b	177	if (exists $attrs->{content_type} && defined $attrs->{content_type} && $attrs->{content_type} ne '') {
	178	$e_m_attrs->{content_type} = $attrs->{content_type};
	179	}
	180	elsif (defined $default_content_type && $default_content_type ne '') {
	181	$e_m_attrs->{content_type} = $default_content_type;
	182	}
	183
	184	if (exists $attrs->{charset} && defined $attrs->{charset} && $attrs->{charset} ne '') {
	185	$e_m_attrs->{charset} = $attrs->{charset};
	186	}
	187	elsif (defined $default_charset && $default_charset ne '') {
	188	$e_m_attrs->{charset} = $default_charset;
	189	}
	190
06afcdbc	191	# render the email part
06afcdbc	192	my $output = $view->render( $c, $template, {
ea115f9b	193	content_type => $e_m_attrs->{content_type},
ea115f9b	194	stash_key => $self->{stash_key},
06afcdbc	195	%{$c->stash},
	196	});
	197
	198	if (ref $output) {
	199	croak $output->can('as_string') ? $output->as_string : $output;
529915ab	200	}
06afcdbc	201
06afcdbc	202	return Email::MIME->create(
ea115f9b	203	attributes => $e_m_attrs,
06afcdbc	204	body => $output,
	205	);
	206	}
529915ab	207
06afcdbc	208	sub process {
06afcdbc	209	my ( $self, $c ) = @_;
529915ab	210
06afcdbc	211	# don't validate template_prefix
8b10ee55	212
ea115f9b	213	# the default view is validated if used
12c85b56	214
06afcdbc	215	# the content type should be validated by Email::MIME::Creator
ea115f9b	216
ea115f9b	217	my $stash_key = $self->{stash_key};
12c85b56	218
06afcdbc	219	croak "No template specified for rendering"
	220	unless $c->stash->{$stash_key}->{template}
	221	or $c->stash->{$stash_key}->{templates};
	222
	223	# this array holds the Email::MIME objects
	224	# in case of the simple api only one
	225	my @parts = ();
12c85b56	226
06afcdbc	227	# now find out if the single or multipart api was used
	228	# prefer the multipart one
	229
	230	# multipart api
	231	if ($c->stash->{$stash_key}->{templates}
	232	&& ref $c->stash->{$stash_key}->{templates} eq 'ARRAY'
	233	&& ref $c->stash->{$stash_key}->{templates}[0] eq 'HASH') {
	234	# loop through all parts of the mail
	235	foreach my $part (@{$c->stash->{$stash_key}->{templates}}) {
	236	push @parts, $self->_generate_part($c, {
	237	view => $part->{view},
	238	template => $part->{template},
	239	content_type => $part->{content_type},
ea115f9b	240	charset => $part->{charset},
06afcdbc	241	});
12c85b56	242	}
06afcdbc	243	}
	244	# single part api
	245	elsif($c->stash->{$stash_key}->{template}) {
	246	push @parts, $self->_generate_part($c, {
	247	template => $c->stash->{$stash_key}->{template},
	248	});
	249	}
	250
8b10ee55	251	delete $c->stash->{$stash_key}->{body};
	252	$c->stash->{$stash_key}->{parts} \|\|= [];
	253	push @{$c->stash->{$stash_key}->{parts}}, @parts;
529915ab	254
	255	# Let C::V::Email do the actual sending. We just assemble the tasty bits.
	256	return $self->next::method($c);
	257	}
	258
	259	=head1 TODO
	260
	261	=head2 ATTACHMENTS
	262
	263	There needs to be a method to support attachments. What I am thinking is
	264	something along these lines:
25650747	265
529915ab	266	attachments => [
	267	# Set the body to a file handle object, specify content_type and
	268	# the file name. (name is what it is sent at, not the file)
	269	{ body => $fh, name => "foo.pdf", content_type => "application/pdf" },
	270	# Or, specify a filename that is added, and hey, encoding!
	271	{ filename => "foo.gif", name => "foo.gif", content_type => "application/pdf", encoding => "quoted-printable" },
	272	# Or, just a path to a file, and do some guesswork for the content type
	273	"/path/to/somefile.pdf",
	274	]
	275
	276	=head1 SEE ALSO
	277
	278	=head2 L<Catalyst::View::Email> - Send plain boring emails with Catalyst
	279
	280	=head2 L<Catalyst::Manual> - The Catalyst Manual
	281
	282	=head2 L<Catalyst::Manual::Cookbook> - The Catalyst Cookbook
	283
	284	=head1 AUTHORS
	285
	286	J. Shirley <jshirley@gmail.com>
	287
12c85b56	288	Simon Elliott <cpan@browsing.co.uk>
12c85b56	289
06afcdbc	290	Alexander Hartmaier <alex_hartmaier@hotmail.com>
06afcdbc	291
529915ab	292	=head1 LICENSE
	293
	294	This library is free software, you can redistribute it and/or modify it under
	295	the same terms as Perl itself.
	296
	297	=cut
	298
	299	1;