Fwd: [CakePHP : The Rapid Development Framework for PHP] #3913: EmailComponent Documentation Start
Samuel DeVore
Sam D
---------- Forwarded message ----------
From: CakePHP : The Rapid Development Framework for PHP <tic...@cakephp.org>
Date: Jan 14, 2008 9:33 PM
Subject: [CakePHP : The Rapid Development Framework for PHP] #3913:
EmailComponent Documentation Start
To:
Cc: tickets...@googlegroups.com
#3913: EmailComponent Documentation Start
-------------------------+--------------------------------------------------
Reporter: sdevore2 | Type: Documentation
Status: new | Priority: Very Low
Milestone: | Component: Documentation
Version: | Severity: Trivial
Keywords: | Php_version: n/a
Cake_version: |
-------------------------+--------------------------------------------------
= Email Component =
== Introduction ==
The emailComponent is a way for you to add simple email sending
functionalityto your CakePHP application. Using the same concepts of
layouts and view ctp files to send formated messages as text, html or
both. It supports sending via the built in mail functions of PHP, via
smtp server or a debug mode where it writes the message out to a session
flash message. It supports file attachments and does some basic header
injection checking/ filtering for you. There is a lot that it doesn't do
for you but it will get you started.
== EmailComponent Class ==
=== Methods ===
`send ( $content, $template, $layout )` this is the method that sends the
message based on the setting of the values of the class attributes that
you can set from your controller (seen below)
* - this is an array of text lines or a string that is passed to the
template for rendering (you can also use the ->set() like you do for
standard view files) [optional]
* $template - you can tell the component to use a specific template in
elements/email to use for sending the message (one in text/ and one in
/html/) [optional]
* $layout - override the default layout that you set up below [optional]
`reset()` this method resets the internal values to the defaults so that
you can send a new message and set new values as needed
=== Class Attributes or variables ===
These are the values that you can set before you call
EmailComponent::send()
* `$to` - address the message is going to (string)
* `$cc` - array of addresses to cc the message to
* `$bcc` - array of addresses to bcc (blind carbon copy) the message to
* `$replyTo` - reply to address (string)
* `$from` - from address (string)
* `$subject` - subject for the message (string)
* `$template` - the email element to use for the message (located in
`app/views/elements/email/html/` and `app/views/elements/email/html/`)
* `$sendAs` - how do you want message sent string values of `text`,
`html` or `both`
* `$attachments` - array of files to send (absolute and relative paths)
* `$delivery` - how to send the message (`mail`, `smtp` [would require
smtpOptions set below] and `debug`)
* `$smtpOptions` - associative array of options for smtp mailer (`port`,
`host`, `timeout`, `username`, `password`)
There are some other things that can be set but you should refer to the
api documentation for more information
== Sending a basic message ==
=== Setting up the Layouts ===
To use both text and html mailing message you need to create layout files
for them, just like in setting up your default layouts for the display of
your views in a browser, you need to set up default layouts for your email
messages. In the `app/views/layouts/` directory you need to set up (at a
minimum) the following structure
{{{
email/
html/
default.ctp
text/
default.ctp
}}}
These are the files that hold the layout templates for your default
messages. Some example content is below
`email/text/default.ctp`
{{{
<?php echo $content_for_layout; ?>
}}}
`email/html/default.ctp`
{{{
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body>
<?php echo $content_for_layout; ?>
</body>
</html>
}}}
=== Setup an email element for the message body ===
In the `app/views/elements/email/` directory you need to set up folders
for `text` and `html` unless you plan to just send one or the other. In
each of these folders you need to create templates for both types of
messages refering to the content that you send to the view either by using
`$this->set()` or using the `$contents` parameter of the `send()` method.
Some simple examples are shown below. For this example we will call the
templates `simple_message.ctp`
`text`
{{{
Dear <?php echo $User['first']. ' ' . $User['last'] ?>,
Thank you for your interest.
}}}
`html`
{{{
<p>Dear <?php echo $User['first']. ' ' . $User['last'] ?>,<br />
Thank you for your interest.</p>
}}}
=== Controller ===
In you controller you need to add the component to your `$components`
array or add a `$components` array to your controller like:
{{{
var $components = array('Email');
}}}
In this example we will set up a private method to handle sending the
email messages to a user identified by an $id. In our controller (let's
use the User controller in this example)
{{{
function _sendNewUserMail($id) {
$User = $this->User->read(null,$id);
$this->Email->to = $User['User'][0]['email'];
$this->Email->bcc = array('sec...@example.com'); // note
this could be just a string too
$this->Email->subject = 'Welcome to our really cool
thing';
$this->Email->replyTo = 'sup...@example.com';
$this->Email->from = 'Cool Web App <a...@example.com>';
$this->Email->template = 'simple_message'; // note no
'.ctp'
//Send as 'html', 'text' or 'both' (default is 'text')
$this->Email->sendAs = 'both'; // because we like to send
pretty mail
//Set view variables as normal
$this->set('User', $User);
//Do not pass any args to send()
$this->Email->send();
}
}}}
You have sent a message, you could call this from another method like
{{{
$this->_sendNewUserMail( $this->User->getInsertId() );
}}}
--
Ticket URL: <https://trac.cakephp.org/ticket/3913>
CakePHP : The Rapid Development Framework for PHP <https://trac.cakephp.org/>
Cake is a rapid development framework for PHP which uses commonly
known design patterns like ActiveRecord, Association Data Mapping,
Front Controller and MVC. Our primary goal is to provide a structured
framework that enables PHP users at all levels to rapidly develop
robust web applications, without any loss to flexibility.
--
(the old fart) the advice is free, the lack of crankiness will cost you
- its a fine line between a real question and an idiot
http://blog.samdevore.com/archives/2007/03/05/when-open-source-bugs-me/
John David Anderson
On Jan 15, 2008, at 9:14 AM, Samuel DeVore wrote:
>
> A start for the EmailComponent (it looks better in the ticket ;)
Sam, so you're finishing the rest of this right? Can I get back to you
next week on that?
(looks really great so far)
-- John
Samuel DeVore
>
>
> On Jan 15, 2008, at 9:14 AM, Samuel DeVore wrote:
>
> >
> > A start for the EmailComponent (it looks better in the ticket ;)
>
> Sam, so you're finishing the rest of this right? Can I get back to you
> next week on that?
I can, I just wanted to put the notes that I had done while adding
simple mail over the weekend. Wasn't really sure if Marcin wanted me
to just take the doc for Email or just share what my notes were.
Marcin do you want me to just finish this or since your experience is
greater then mine probably for this do you want to finish. It's just
written in trac wiki markdown and I can send you the source, or we
could open a google doc file and edit it together if you want....
Sam D
http://blog.samdevore.com/archives/2007/03/05/when-open-source-bugs-me/
Marci
John David Anderson
On Jan 16, 2008, at 11:31 AM, Samuel DeVore wrote:
> <snip>
> I can, I just wanted to put the notes that I had done while adding
> simple mail over the weekend. Wasn't really sure if Marcin wanted me
> to just take the doc for Email or just share what my notes were.
>
> Marcin do you want me to just finish this or since your experience is
> greater then mine probably for this do you want to finish. It's just
> written in trac wiki markdown and I can send you the source, or we
> could open a google doc file and edit it together if you want....
In the interim, I made the assumption he was relinquishing the task to
you, so I took advantage of that and gave him another assignment. :)
Sam, is it okay to ask you to finish it? If you can't that's totally
cool too, just let me know.
Samuel DeVore
a template or a guideline for sections though, it seems that we would
be so much more helpful if we were at least shooting first drafts out
in a consistent and more usable form.
Marcin Domanski
Sam, I've seen your first draft, It was great so i figured You wanted
to finish it.
I've taken the XMLHelper for now as a warm-up before datasources ;)
And yeah - some guidelines/template would be great maybe we can think
about it and try to write is in the projects wiki?
--
Marcin Domanski
http://kabturek.info
John David Anderson
On Jan 16, 2008, at 11:44 AM, Samuel DeVore wrote:
>
> no problem, I'll finish it in the next day or so. I do wish there was
> a template or a guideline for sections though, it seems that we would
> be so much more helpful if we were at least shooting first drafts out
> in a consistent and more usable form.
I'd use sibling sections in tempdocs as a guide. If you're writing a
components section, check out another components section, etc.
-- John
Samuel DeVore
http://cakeforge.org/plugins/wiki/index.php?EmailComponent&id=53&type=g
(linked from outline as well)
I'll work on adding some more content but any additions or edits are
more then welcome ;)
Sam D