X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README;h=e69de29bb2d1d6434b8b29ae775ad8c2e48c5391;hb=e07696b0e328a547419ad279eb074e790c5b748c;hp=02cc9aeb20a12779b2991f13157b5c4f873eb33a;hpb=5d205d68e1cd576075c734a6d9ce2a286cc0d607;p=catagits%2FCatalyst-View-Email.git diff --git a/README b/README index 02cc9ae..e69de29 100644 --- a/README +++ b/README @@ -1,196 +0,0 @@ -NAME - Catalyst::View::Email - Send Email from Catalyst - -SYNOPSIS - This module sends out emails from a stash key specified in the - configuration settings. - -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 - - In your app configuration: - - __PACKAGE__->config( - 'View::Email' => { - # Where to look in the stash for the email information. - # 'email' is the default, so you don't have to specify it. - stash_key => 'email', - # Define the defaults for the mail - default => { - # Defines the default content type (mime type). Mandatory - content_type => 'text/plain', - # 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' - }, - # Setup how to send the email - # all those options are passed directly to Email::Sender::Simple - sender => { - # if mailer doesn't start with Email::Sender::Simple::Transport::, - # then this is prepended. - mailer => 'SMTP', - # mailer_args is passed directly into Email::Sender::Simple - mailer_args => { - Host => 'smtp.example.com', # defaults to localhost - username => 'username', - password => 'password', - } - } - } - ); - -NOTE ON SMTP - If you use SMTP and don't specify host, it will default to localhost and - attempt delivery. This often means an email will sit in a queue and not - be delivered. - -SENDING EMAIL - Sending email is just filling the stash and forwarding to the view: - - sub controller : Private { - my ( $self, $c ) = @_; - - $c->stash->{email} = { - to => 'jshirley@gmail.com', - cc => 'abraxxa@cpan.org', - bcc => join ',', 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') ); - } - - Alternatively you can use a more raw interface and specify the headers - as an array reference like it is passed to 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 => 'jshirley@gmail.com', - Cc => 'abraxxa@cpan.org', - Bcc => join ',', 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 - parts => [ - Email::MIME->create( - attributes => { - content_type => 'text/plain', - disposition => 'attachment', - charset => 'US-ASCII', - }, - body => qq{Got a body, but didn't get ahead.}, - ) - ], - }; - -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: - - $c->forward( $c->view('Email') ); - - if ( scalar( @{ $c->error } ) ) { - $c->error(0); # Reset the error condition if you need to - $c->response->body('Oh noes!'); - } else { - $c->response->body('Email sent A-OK! (At least as far as we can tell)'); - } - -USING TEMPLATES FOR EMAIL - Now, it's no fun to just send out email using plain strings. Take a look - at Catalyst::View::Email::Template to see how you can use your favourite - template engine to render the mail body. - -METHODS - new Validates the base config and creates the Email::Sender::Simple - object for later use by process. - - 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 - Email::Sender::Simple to handle the actual email delivery. - - setup_attributes($c, $attr) - Merge attributes with the configured defaults. You can override this - method to return a structure to pass into generate_message which - subsequently passes the return value of this method to - Email::MIME->create under the "attributes" key. - - generate_message($c, $attr) - Generate a message part, which should be an Email::MIME object and - return it. - - Takes the attributes, merges with the defaults as necessary and - returns a message object. - -TROUBLESHOOTING - As with most things computer related, things break. Email even more so. - Typically any errors are going to come from using SMTP as your sending - method, which means that if you are having trouble the first place to - look is at Email::Sender::Transport::SMTP. This module is just a wrapper - for Email::Sender::Simple, so if you get an error on sending, it is - likely from there anyway. - - If you are using SMTP and have troubles sending, whether it is - authentication or a very bland "Can't send" message, make sure that you - have Net::SMTP and, if applicable, Net::SMTP::SSL installed. - - It is very simple to check that you can connect via Net::SMTP, and if - you do have sending errors the first thing to do is to write a simple - script that attempts to connect. If it works, it is probably something - in your configuration so double check there. If it doesn't, well, keep - modifying the script and/or your mail server configuration until it - does! - -SEE ALSO - Catalyst::View::Email::Template - Send fancy template emails with Cat - Catalyst::Manual - The Catalyst Manual - Catalyst::Manual::Cookbook - The Catalyst Cookbook -AUTHORS - J. Shirley - - Alexander Hartmaier - -CONTRIBUTORS - (Thanks!) - - Matt S Trout - - Daniel Westermann-Clark - - Simon Elliott - - Roman Filippov - - Lance Brown - - Devin Austin - - Chris Nehren - -COPYRIGHT - Copyright (c) 2007 - 2009 the Catalyst::View::Email "AUTHORS" and - "CONTRIBUTORS" as listed above. - -LICENSE - This library is free software, you can redistribute it and/or modify it - under the same terms as Perl itself. -