[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Peter Muir
peter at bleepbleep.org.uk
Wed Jan 24 16:06:50 EST 2007
User: pmuir
Date: 07/01/24 16:06:50
Modified: doc/reference/en/modules components.xml
Added: doc/reference/en/modules mail.xml
Log:
Add documentation for mail stuff
Revision Changes Path
1.52 +67 -22 jboss-seam/doc/reference/en/modules/components.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: components.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/components.xml,v
retrieving revision 1.51
retrieving revision 1.52
diff -u -b -r1.51 -r1.52
--- components.xml 14 Dec 2006 19:39:12 -0000 1.51
+++ components.xml 24 Jan 2007 21:06:50 -0000 1.52
@@ -949,6 +949,51 @@
</variablelist>
</section>
+ <section id="components.mail">
+ <title>Mail-related components</title>
+ <para>
+ These components are for use with Seam's Email support
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.mail.mailSession</literal></term>
+ <listitem>
+ <para>
+ Manager component for a JavaMail <literal>Session</literal> .
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.host</literal> — the hostname of the SMTP server to use
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.port</literal> — the port of the SMTP server to use
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.username</literal> — the username to use to connect to the SMTP server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.password</literal> — the password to use to connect to the SMTP server
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.debug</literal> — enable JavaMail debugging (very verbose)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
<section>
<title>Infrastructural components</title>
<para>
1.1 date: 2007/01/24 21:06:50; author: pmuir; state: Exp;jboss-seam/doc/reference/en/modules/mail.xml
Index: mail.xml
===================================================================
<chapter id="mail">
<title>Email Generation and Sending</title>
<para>Seam now includes an optional component set for generating and sending emails.</para>
<section>
<title>Using Email Support</title>
<para>Email support is provided by <literal>jboss-seam-mail.jar</literal>. This JAR contains the mail JSF controls, which are used
to construct emails, and the <literal>mailSession</literal> component, which sends the generated email.
</para>
<para> The examples/mail project contains an example of the email support in action. It demonstrates proper
deployment packaging, and it contains a number of examples that demonstrate the key email generation features
currently supported. </para>
</section>
<section>
<title>Configuration</title>
<para>To include Email support in your application, include <literal>jboss-seam-mail.jar</literal> in your
WEB-INF/lib directory. If you are using JBoss AS there is no further configuration needed to use Seam's
email support otherwise you need to make sure you have the JavaMail API, an implementation of the JavaMail API present
(distributed with seam as <literal>lib/mail.jar</literal>), and a copy of the Java Activation Framework (distributed with seam as <literal>lib/activation.jar</literal>.</para>
<para>The Seam Email module requires the use of Facelets as the view technology. Future versions of the library
may also support the use of JSP. Additionally, it requires the use of the seam-ui package.</para>
<para>The mailSession component uses JavaMail to talk to a 'real' SMTP server. If you have one running on localhost, then no further
configuration is required. Otherwise, the mailSession component can be configured in <literal>components.xml</literal>. Here, we tell
Seam to use <literal>smtp.example.com</literal> as the smtp server, see <xref linkend="components.mail"/> for all the possible properties</para>
<programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:core="http://jboss.com/products/seam/core"
xmlns:mail="http://jboss.com/products/seam/mail">
<mail:mailSession host="smtp.example.com" />
</components>]]></programlisting>
</section>
<section>
<title>Creating a message</title>
<para>Emails are generated using tags in the
<literal>http://jboss.com/products/seam/mail</literal> namespace. Documents should always have the
<literal>message</literal> tag at the root of the message. The message tag prepares Seam to generate
an email. </para>
<para>The standard templating tags of facelets can be used as normal. Inside the body you can use any JSF tag which doesn't require access to external resources (stylesheets, javascript).</para>
<variablelist>
<varlistentry>
<term><m:message></term>
<listitem>
<para>
Root tag of a mail message
</para>
<!-- <itemizedlist>
<listitem>
<para>
<literal>importance</literal> — low, normal or high. By default normal, this sets the importance of the mail message.
value.
</para>
</listitem>
<listitem>
<para>
<literal>precedence</literal> — sets the precedence of the message (e.g. bulk).
</para>
</listitem>
<listitem>
<para>
<literal>requestReadReceipt</literal> — by default false, if set, a read receipt will be requested.
</para>
</listitem>
</itemizedlist>-->
</listitem>
</varlistentry>
<varlistentry>
<term><m:from></term>
<listitem>
<para>
Set's the From: address for the email. You can only have one of these per email.
</para>
<itemizedlist>
<listitem>
<para>
<literal>name</literal> — the name the email should come from.
</para>
</listitem>
<listitem>
<para>
<literal>address</literal> — the email address the email should come from.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><m:replyTo></term>
<listitem>
<para>
Set's the Reply-to: address for the email. You can only have one of these per email.
</para>
<itemizedlist>
<listitem>
<para>
<literal>address</literal> — the email address the email should come from.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><m:to></term>
<listitem>
<para>
Add a recipient to the email. Use multiple <m:to> tags for multiple recipients. This tag can be safely placed inside a repeat tag such as <ui:repeat>.
</para>
<itemizedlist>
<listitem>
<para>
<literal>name</literal> — the name of the recipient.
</para>
</listitem>
<listitem>
<para>
<literal>address</literal> — the email address of the recipient.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><m:cc></term>
<listitem>
<para>
Add a cc recipient to the email. Use multiple <m:cc> tags for multiple ccs. This tag can be safely placed inside a repeat tag such as <ui:repeat>.
</para>
<itemizedlist>
<listitem>
<para>
<literal>name</literal> — the name of the recipient.
</para>
</listitem>
<listitem>
<para>
<literal>address</literal> — the email address of the recipient.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><m:bcc></term>
<listitem>
<para>
Add a bcc recipient to the email. Use multiple <m:bcc> tags for multiple bccs. This tag can be safely placed inside a repeat tag such as <ui:repeat>.
</para>
<itemizedlist>
<listitem>
<para>
<literal>name</literal> — the name of the recipient.
</para>
</listitem>
<listitem>
<para>
<literal>address</literal> — the email address of the recipient.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term><m:subject></term>
<listitem>
<para>
Set's the subject for the email.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><m:body></term>
<listitem>
<para>
Set's the body for the email. Supports an <literal>alternative</literal> facet which, if an HTML email is generated can contain alternative text for a mail reader which doesn't support html.
</para>
<itemizedlist>
<listitem>
<para>
<literal>type</literal> — If set to <literal>plain</literal> then a plain text email will be generated otherwise an HTML email is generated.
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</section>
</chapter>
More information about the jboss-cvs-commits
mailing list