Email 0.05, added doc section on using with TT

diff --git a/Changes b/Changes
index 873e755..03964e5 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,7 +1,12 @@
 Revision history for Perl extension Catalyst::Plugin::Email.
 
+0.05  Thu Nov 17 22:00:00 2005
+        - Added docs on sending email using a TT template.
+          (Andy Grundman)
+
 0.04  Fri Apr 15 16:09:00 2005
         - added pod tests.
+
 0.03  Wed Feb 02 18:00:00 2005
         - bugfix
 

diff --git a/Email.pm b/Email.pm
index 7dc8d33..54f2c50 100644 (file)
--- a/Email.pm
+++ b/Email.pm
@@ -5,7 +5,7 @@ use Email::Send;
 use Email::MIME;
 use Email::MIME::Creator;
 
-our $VERSION = '0.04';
+our $VERSION = '0.05';
 
 =head1 NAME
 
@@ -30,9 +30,62 @@ Catalyst::Plugin::Email - Send emails with Catalyst
 
 Send emails with Catalyst and L<Email::Send> and L<Email::MIME::Creator>.
 
-=head2 METHODS
+=head1 USING WITH A VIEW
 
-=head3 email
+A common practice is to handle emails using the same template language used
+for HTML pages.  This can be accomplished by pairing this plugin with
+L<Catalyst::Plugin::SubRequest>.
+
+Here is a short example of rendering an email from a Template Toolkit source
+file.  The call to $c->subreq makes an internal call to the render_email
+method just like an external call from a browser.  The request will pass
+through the end method to be processed by your View class.
+
+    sub send_email : Local {
+        my ( $self, $c ) = @_;  
+
+        $c->email(
+            header => [
+                To      => 'me@localhost',
+                Subject => 'A TT Email',
+            ],
+            body => $c->subreq( '/render_email' ),
+        );
+        # redirect or display a message
+    }
+    
+    sub render_email : Local {
+        my ( $self, $c ) = @_;
+        
+        $c->stash(
+            names    => [ qw/andyg sri mst/ ],
+            template => 'email.tt',
+        );
+    }
+    
+And the template:
+
+    [%- FOREACH name IN names -%]
+    Hi, [% name %]!
+    [%- END -%]
+    
+    --
+    Regards,
+    Us
+
+Output:
+
+    Hi, andyg!
+    Hi, sri!
+    Hi, mst!
+    
+    --
+    Regards,
+    Us
+
+=head1 METHODS
+
+=head2 email
 
 =cut
 
@@ -52,7 +105,8 @@ sub email {
 
 =head1 SEE ALSO
 
-L<Catalyst>.
+L<Catalyst>, L<Catalyst::Plugin::SubRequest>, L<Email::Send>,
+L<Email::MIME::Creator>
 
 =head1 AUTHOR
 

diff --git a/META.yml b/META.yml
index 53d9b18..5dfe1fe 100644 (file)
--- a/META.yml
+++ b/META.yml
@@ -1,7 +1,7 @@
 # http://module-build.sourceforge.net/META-spec.html
 #XXXXXXX This is a prototype!!!  It will change in the future!!! XXXXX#
 name:         Catalyst-Plugin-Email
-version:      0.04
+version:      0.05
 version_from: Email.pm
 installdirs:  site
 requires:

diff --git a/README b/README
index 93c1004..f5f4404 100644 (file)
--- a/README
+++ b/README
@@ -4,7 +4,7 @@ NAME
 SYNOPSIS
         use Catalyst 'Email';
 
-        __PACKAGE__->config->{email} = qw/SMTP smtp.oook.de/;
+        __PACKAGE__->config->{email} = [qw/SMTP smtp.oook.de/];
 
         $c->email(
             header => [
@@ -18,10 +18,64 @@ SYNOPSIS
 DESCRIPTION
     Send emails with Catalyst and Email::Send and Email::MIME::Creator.
 
-  METHODS
-   email
+USING WITH A VIEW
+    A common practice is to handle emails using the same template language
+    used for HTML pages. This can be accomplished by pairing this plugin
+    with Catalyst::Plugin::SubRequest.
+
+    Here is a short example of rendering an email from a Template Toolkit
+    source file. The call to $c->subreq makes an internal call to the
+    render_email method just like an external call from a browser. The
+    request will pass through the end method to be processed by your View
+    class.
+
+        sub send_email : Local {
+            my ( $self, $c ) = @_;  
+
+            $c->email(
+                header => [
+                    To      => 'me@localhost',
+                    Subject => 'A TT Email',
+                ],
+                body => $c->subreq( '/render_email' ),
+            );
+            # redirect or display a message
+        }
+    
+        sub render_email : Local {
+            my ( $self, $c ) = @_;
+        
+            $c->stash(
+                names    => [ qw/andyg sri mst/ ],
+                template => 'email.tt',
+            );
+        }
+    
+    And the template:
+
+        [%- FOREACH name IN names -%]
+        Hi, [% name %]!
+        [%- END -%]
+    
+        --
+        Regards,
+        Us
+
+    Output:
+
+        Hi, andyg!
+        Hi, sri!
+        Hi, mst!
+    
+        --
+        Regards,
+        Us
+
+METHODS
+  email
 SEE ALSO
-    Catalyst.
+    Catalyst, Catalyst::Plugin::SubRequest, Email::Send,
+    Email::MIME::Creator
 
 AUTHOR
     Sebastian Riedel, "sri@cpan.org"