Author: Frederik Holljen
Date: 2006-01-27 14:00:10 +0100 (Fri, 27 Jan 2006)
New Revision: 2053
Log:
- add tutorial
Added:
packages/Mail/trunk/docs/tutorial.txt
packages/Mail/trunk/tests/tutorial_examples.php
Modified:
packages/Mail/trunk/tests/suite.php
Added: packages/Mail/trunk/docs/tutorial.txt
===================================================================
--- packages/Mail/trunk/docs/tutorial.txt 2006-01-27 12:25:39 UTC (rev
2052)
+++ packages/Mail/trunk/docs/tutorial.txt 2006-01-27 13:00:10 UTC (rev
2053)
@@ -0,0 +1,184 @@
+eZ components - Mail
+~~~~~~~~~~~~~~~~~~~~~
+
+.. contents:: Table of Contents
+
+Introduction
+============
+
+The mail component provides functionality to send mail. The easiest way is to
+use the ezcMailComposer class. This class allows you to send HTML mail with
+images, attachments and an optional text part.
+If you require more advanced email messages you can build the complete message
+yourself using the ezcMailPart derived classes.
+
+Class overview
+==============
+
+This section gives you an overview of the main classes of in the Mail
+component.
+
+ezcMailComposer
+ The mail composer is a convenience class that allows you to send plain or
+ HTML messages with attachments without the need to construct the parts of
+ the message yourself. Most users want to use this class.
+
+ezcMail
+ If ezcMailComposer does not have the functionality you require you can use
+ the ezcMail class to build MIME structured mail from scratch. This requires
+ basic knowledge about how a mail is structured.
+
+ezcMailAddress
+ This small class represents a mail address with an optional name. It is used
+ by both ezcMailComposer and ezcMail to set recipient addresses.
+
+Usage
+=====
+
+Transport protocols
+-------------------
+
+The mail component provides two different transport
+classes. ezcMailTransportSmtp makes it possible to send mail over the SMTP
+protocol. If you prefer using a local mail agent you can use
+ezcMailTransportMta which wraps over the PHP mail function..
+
+Send a mail with the composer
+-----------------------------
+
+Sending a mail using the composer is very straightforward. This small example
+displays how to send a normal text message. ::
+
+ $mail = new ezcMailComposer();
+ $mail->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Adrian Ripburger' );
+ $mail->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'Maureen Corley' ) );
+ $mail->subject = "This is the subject of the example mail";
+ $mail->plainText = "This is the body of the example mail.";
+ $mail->build();
+ $transport = new ezcMailTransportMta();
+ $transport->send( $mail );
+
+
+An example with HTML text, images and attachments can be found in the
+ezcMailComposer class description.
+
+Building a mail from scratch
+-----------------------------
+
+The class structure of the mail component follows that of the mail MIME. This
+means that you can build advanced MIME messages part by part.
+
+The first example displays how to build a similar message to the one above. ::
+
+ $mail = new ezcMail();
+ $mail->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Boston Low' );
+ $mail->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'Maggie Robbins' ) );
+ $mail->subject = "This is the subject of the example mail";
+ $mail->body = new ezcMailText( "This is the body of the example mail." );
+ $transport = new ezcMailTransportMta();
+ $transport->send( $mail );
+
+As you can see there is not much difference with the composer version. In the
+next example we will add an attachment to our manually built mail: ::
+
+ $mail = new ezcMail();
+ $mail->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Bernard Bernoulli' );
+ $mail->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'Wendy' ) );
+ $mail->subject = "This is the subject of the example mail";
+ $textPart = new ezcMailText( "This is the body of the example mail." );
+ $fileAttachment = new ezcMailFile( "~/myfile.jpg" );
+ $mail->body = new ezcMailMultipartMixed( $textPart, $fileAttachment );
+ $transport = new ezcMailTransportMta();
+ $transport->send( $mail );
+
+The file 'myfile.jpg' must of course exist in order for this example to work.
+
+Extending the mail componentp
+----------------------------
+
+Even though the mail component supports a lot it does not support
+everything. There is no reason to dispair however, since it is very simple to
+extend. The following example shows how you can insert mail digests as
+attachments to your mail.
+
+The mail system already supports sending attachments through the
+ezcMailMultipartMixed type. Unfortunately directly inserting an ezcMail object
+as a part does not work. This is because mail digests are a special case: they
+require to extra headers that are separated by the normal headers in the
+e-mail.
+
+To make it work we will create the class RFC822Digest that adds these headers:
::
+
+ class RFC822Digest extends ezcMailPart
+ {
+ private $mail = null;
+ public function __construct( ezcMail $mail )
+ {
+ $this->mail = $mail;
+ $this->setHeader( 'Content-Type', 'message/rfc822' );
+ $this->setHeader( 'Content-Disposition', 'inline' );
+ }
+
+ public function generateBody()
+ {
+ return $this->mail->generate();
+ }
+ }
+
+Our new class extends the ezcMailPart class. This is required for all parts of
+a mail. ezcMailPart provides two important methods that we can override:
+generateHeaders() and generateBody(). These two methods are called in
+succession by the parent part and should return the headers and the body text
+of the part.
+We don't need to override generateHeaders() since we can simply set the headers
+we want directly on the object. We do need to override generateBody() however,
+since we want to include the full text of the mail digest.
+
+The new class can be used directly when building an email. The example assumes
+that a valid ezcMail object is available in the $digest variable. ::
+
+ $mail = new ezcMail();
+ $mail->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Largo LaGrande' );
+ $mail->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'Wally B. Feed' ) );
+ $mail->subject = "This is the subject of the mail with a mail digest.";
+ $textPart = new ezcMailText( "This is the body of the mail with a mail
digest." );
+
+ $mail->body = new ezcMailMultipartMixed( $textPart, new RFC822Digest(
$digest ) );
+ $transport = new ezcMailTransportMta();
+ $transport->send( $mail );
+
+Character encoding
+------------------
+
+Most of the world does not speak and write US ascii and require more advanced
+character encoding to display their mail correctly.
+
+The following example shows how to send a mail entirely encoded with
+iso-8859-1: ::
+
+ $mail = new ezcMail();
+ $mail->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Norwegian
characters: æøå', 'iso-8859-1' );
+ $mail->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'More norwegian
characters: æøå', 'iso-8859-1' ) );
+ $mail->subject = 'Oslo ligger sør i Norge og har vært landets hovedstad i
over 600 år.';
+ $mail->subjectCharset = 'iso-8859-1';
+ $mail->body = new ezcMailText( 'Oslo be grunnlagt rundt 1048 av Harald
Hardråde.', 'iso-8859-1' );
+ $transport = new ezcMailTransportMta();
+ $transport->send( $mail );
+
+You can of course choose and combine any available character set. Make sure
+that the input text is in the encoding specified or you may get unexpected
+results.
+
+References
+==========
+A list of mail related RFCs_.
+
+.. _RFCs: http://www.imc.org/rfcs.html
+
+
+..
+ Local Variables:
+ mode: rst
+ fill-column: 79
+ End:
+ vim: et syn=rst tw=79
Property changes on: packages/Mail/trunk/docs/tutorial.txt
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: packages/Mail/trunk/tests/suite.php
===================================================================
--- packages/Mail/trunk/tests/suite.php 2006-01-27 12:25:39 UTC (rev 2052)
+++ packages/Mail/trunk/tests/suite.php 2006-01-27 13:00:10 UTC (rev 2053)
@@ -19,6 +19,7 @@
require_once( "parts/file_part_test.php" );
require_once( "tools_test.php" );
require_once( "transports/transport_smtp_test.php" );
+require_once( "tutorial_examples.php" );
/**
* @package Mail
@@ -39,6 +40,7 @@
$this->addTest( ezcMailFileTest::suite() );
$this->addTest( ezcMailToolsTest::suite() );
$this->addTest( ezcMailTransportSmtpTest::suite() );
+ $this->addTest( ezcMailTutorialExamples::suite() );
}
public static function suite()
Added: packages/Mail/trunk/tests/tutorial_examples.php
===================================================================
--- packages/Mail/trunk/tests/tutorial_examples.php 2006-01-27 12:25:39 UTC
(rev 2052)
+++ packages/Mail/trunk/tests/tutorial_examples.php 2006-01-27 13:00:10 UTC
(rev 2053)
@@ -0,0 +1,116 @@
+<?php
+/**
+ * @copyright Copyright (C) 2005, 2006 eZ systems as. All rights reserved.
+ * @license http://ez.no/licenses/new_bsd New BSD License
+ * @version //autogentag//
+ * @filesource
+ * @package Mail
+ * @subpackage Tests
+ */
+class RFC822Digest extends ezcMailPart
+{
+ private $mail = null;
+ public function __construct( ezcMail $mail )
+ {
+ $this->mail = $mail;
+ $this->setHeader( 'Content-Type', 'message/rfc822' );
+ $this->setHeader( 'Content-Disposition', 'inline' );
+ }
+
+ public function generateBody()
+ {
+ return $this->mail->generate();
+ }
+}
+
+
+
+/**
+ * @package Mail
+ * @subpackage Tests
+ *
+ * If you change any of these, remember to update the tutorial as well.
+ */
+class ezcMailTutorialExamples extends ezcTestCase
+{
+
+ public function testComposer()
+ {
+ $mail = new ezcMailComposer();
+ $mail->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Adrian
Ripburger' );
+ $mail->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'Maureen
Corley' ) );
+ $mail->subject = "This is the subject of the example mail";
+ $mail->plainText = "This is the body of the example mail.";
+ $mail->build();
+ $transport = new ezcMailTransportMta();
+// $transport->send( $mail );
+ }
+
+ public function testMail1()
+ {
+ $mail = new ezcMail();
+ $mail->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Boston Low' );
+ $mail->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'Maggie
Robbins' ) );
+ $mail->subject = "This is the subject of the example mail";
+ $mail->body = new ezcMailText( "This is the body of the example mail."
);
+ $transport = new ezcMailTransportMta();
+// $transport->send( $mail );
+ }
+
+ public function testMail2()
+ {
+ $mail = new ezcMail();
+ $mail->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Bernard
Bernoulli' );
+ $mail->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'Wendy' ) );
+ $mail->subject = "This is the subject of the example mail";
+ $textPart = new ezcMailText( "This is the body of the example mail." );
+// $fileAttachment = new ezcMailFile( "~/myfile.jpg" );
+ $fileAttachment = new ezcMailFile( dirname( __FILE__) .
"/parts/data/fly.jpg" );
+
+ $mail->body = new ezcMailMultipartMixed( $textPart, $fileAttachment );
+ $transport = new ezcMailTransportMta();
+// $transport->send( $mail );
+ }
+
+ public function testMail3()
+ {
+ $digest = new ezcMail();
+ $digest->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Adrian
Ripburger' );
+ $digest->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'Maureen
Corley' ) );
+ $digest->subject = "This is the subject of the example mail";
+ $digestTextPart = new ezcMailText( "This is the body of the example
mail." );
+// $fileAttachment = new ezcMailFile( "~/myfile.jpg" );
+ $fileAttachment = new ezcMailFile( dirname( __FILE__) .
"/parts/data/fly.jpg" );
+
+ $digest->body = new ezcMailMultipartMixed( $digestTextPart,
$fileAttachment );
+
+ $mail = new ezcMail();
+ $mail->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Largo
LaGrande' );
+ $mail->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'Wally B. Feed'
) );
+ $mail->subject = "This is the subject of the mail with a mail digest.";
+ $textPart = new ezcMailText( "This is the body of the mail with a mail
digest." );
+
+ $mail->body = new ezcMailMultipartMixed( $textPart,
+ new RFC822Digest( $digest )
);
+ $transport = new ezcMailTransportMta();
+// $transport->send( $mail );
+ }
+
+ public function testMail4()
+ {
+ $mail = new ezcMail();
+ $mail->from = new ezcMailAddress( '[EMAIL PROTECTED]', 'Norwegian
characters: æøå', 'iso-8859-1' );
+ $mail->addTo( new ezcMailAddress( '[EMAIL PROTECTED]', 'More norwegian
characters: æøå', 'iso-8859-1' ) );
+ $mail->subject = 'Oslo ligger sør i Norge og har vært landets
hovedstad i over 600 år.';
+ $mail->subjectCharset = 'iso-8859-1';
+ $mail->body = new ezcMailText( 'Oslo be grunnlagt rundt 1048 av Harald
Hardråde.', 'iso-8859-1' );
+ $transport = new ezcMailTransportMta();
+// $transport->send( $mail );
+ }
+
+ public static function suite()
+ {
+ return new ezcTestSuite( "ezcMailTutorialExamples" );
+ }
+}
+?>
Property changes on: packages/Mail/trunk/tests/tutorial_examples.php
___________________________________________________________________
Name: svn:eol-style
+ native
--
svn-components mailing list
[email protected]
http://lists.ez.no/mailman/listinfo/svn-components
