[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Peter Muir
peter at bleepbleep.org.uk
Sun Feb 4 13:14:57 EST 2007
User: pmuir
Date: 07/02/04 13:14:57
Modified: doc/reference/en/modules mail.xml
Log:
Tutorial for attachments
Revision Changes Path
1.8 +72 -30 jboss-seam/doc/reference/en/modules/mail.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: mail.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/mail.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- mail.xml 4 Feb 2007 01:21:20 -0000 1.7
+++ mail.xml 4 Feb 2007 18:14:57 -0000 1.8
@@ -12,18 +12,18 @@
<section>
<title>Creating a message</title>
<para>In Seam Mail, an email is just facelet:</para>
- <programlisting><m:message xmlns="http://www.w3.org/1999/xhtml"
- xmlns:m="http://jboss.com/products/seam/mail"
- xmlns:h="http://java.sun.com/jsf/html">
+ <programlisting><m:message xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:m="http://jboss.com/products/seam/mail"
+ xmlns:h="http://java.sun.com/jsf/html">
- <m:from name="Peter" address="peter at example.com" />
- <m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>
+ <m:from name="Peter" address="peter at example.com" />
+ <m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>
<m:subject>Try out Seam!</m:subject>
<m:body>
- <p><h:outputText value="Dear #{person.firstname}" />,</p>
+ <p><h:outputText value="Dear #{person.firstname}" />,</p>
<p>You can try out Seam by visiting
- <a href="http://labs.jboss.com/jbossseam">http://labs.jboss.com/jbossseam</a>.</p>
+ <a href="http://labs.jboss.com/jbossseam">http://labs.jboss.com/jbossseam</a>.</p>
<p>Regards,</p>
<p>Peter</p>
</m:body>
@@ -46,10 +46,10 @@
public void send() {
try {
- renderer.render("/simple.xhtml");
- facesMessages.add("Email sent successfully");
+ renderer.render("/simple.xhtml");
+ facesMessages.add("Email sent successfully");
} catch (Exception e) {
- facesMessages.add("Email sending failed: " + e.getMessage());
+ facesMessages.add("Email sending failed: " + e.getMessage());
}
}</programlisting>
@@ -57,11 +57,53 @@
and then displayed to the user.</para>
<section>
+ <title>Attachments</title>
+ <para>Seam makes it easy to attach files to an email. It supports most of the standard java types used when working with files.</para>
+
+ <para>If you wanted to email the <literal>jboss-seam-mail.jar</literal>:</para>
+
+ <programlisting><m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar" /></programlisting>
+
+ <para>Seam will load the file from the classpath, and attach it to the email. By default it would be attached as <literal>jboss-seam-mail.jar</literal>;
+ if you wanted it to have another name you would just add the <literal>fileName</literal> attribute:</para>
+
+ <programlisting><m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar" fileName="this-is-so-cool.jar" /></programlisting>
+
+ <para>You could also attach a <literal>java.io.File</literal>, a <literal>java.net.URL</literal>:</para>
+
+ <programlisting><m:attachment value="#{exampleSpreadsheet}" /></programlisting>
+
+ <para> a <literal>byte[]</literal> or a <literal>java.io.InputStream</literal>:</para>
+
+ <programlisting><m:attachment value="#{photo}" contentType="image/jpeg" /></programlisting>
+
+ <para>You'll notice that for a <literal>byte[]</literal> and a <literal>java.io.InputStream</literal> you need to specify the MIME type
+ of the attachment (as that information is not carried as part of the file).</para>
+
+ <para>And it gets even better, you can attach a Seam generated PDF, or any standard JSF view, just by wrapping a
+ <literal><m:attachment></literal> around the normal tags you would use:</para>
+
+ <programlisting><m:attachment>
+ <p:document>
+ A very tiny PDF
+ </p:document>
+</m:attachment></programlisting>
+
+ <para>If you had a set of files you wanted to attach (for example a set of pictures loaded from a database) you can just
+ use a <literal><ui:repeat></literal>:</para>
+
+ <programlisting><ui:repeat value="#{photos}" var="photo">
+ <m:attachment value="#{photo}" contentType="image/jpeg" />
+</ui:repeat></programlisting>
+
+ </section>
+
+ <section>
<title>HTML/Text alternative part</title>
<para>Whilst most mail readers nowadays support HTML, some don't, so you can add a plain text alternative
to your email body:</para>
<programlisting><m:body>
- <f:facet name="alternative">Sorry, your email reader can't show our fancy email,
+ <f:facet name="alternative">Sorry, your email reader can't show our fancy email,
please go to http://labs.jboss.com/jbossseam to explore Seam.</f:facet>
</m:body></programlisting>
</section>
@@ -70,8 +112,8 @@
<title>Multiple recipients</title>
<para>Often you'll want to send an email to a group of recipients (for example your users). All of the recipient
mail tags can be placed inside a <literal><ui:repeat></literal>:</para>
- <programlisting><ui:repeat value="#{allUsers} var="user">
- <m:to name="#{user.firstname} #{user.lastname}" address="#{user.emailAddress}" />
+ <programlisting><ui:repeat value="#{allUsers} var="user">
+ <m:to name="#{user.firstname} #{user.lastname}" address="#{user.emailAddress}" />
</ui:repeat></programlisting>
</section>
@@ -80,20 +122,20 @@
<para>The mail templating example shows that facelets templating 'just works' with the Seam mail tags.</para>
<para>Our <literal>template.xhtml</literal> contains:</para>
<programlisting><m:message>
- <m:from name="Seam" address="do-not-reply at jboss.com" />
- <m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>
+ <m:from name="Seam" address="do-not-reply at jboss.com" />
+ <m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>
<m:subject>#{subject}</m:subject>
<m:body>
<html>
<body>
- <ui:insert name="body"> This is the default body, specified by the template.</ui:insert>
+ <ui:insert name="body"> This is the default body, specified by the template.</ui:insert>
</body>
</html>
</m:body>
</m:message></programlisting>
<para>Our <literal>templating.xhtml</literal> contains:</para>
- <programlisting><ui:param name="subject" value="Templating with Seam Mail" />
-<ui:define name="body">
+ <programlisting><ui:param name="subject" value="Templating with Seam Mail" />
+<ui:define name="body">
<p>This email demonstrates that you can easily use <i>facelets templating features</i> in your code!</p>
</ui:define></programlisting>
</section>
@@ -102,11 +144,11 @@
<title>Other Headers</title>
<para>Sometimes you'll want to add other headers to your email. Seam provides support for some (see <xref linkend="mail.tags" />).
For example, we can set the importance of the email, and ask for a read receipt:</para>
- <programlisting><m:message xmlns:m="http://jboss.com/products/seam/mail"
- importance="low"
- requestReadReceipt="true"></programlisting>
+ <programlisting><m:message xmlns:m="http://jboss.com/products/seam/mail"
+ importance="low"
+ requestReadReceipt="true"></programlisting>
<para>Otherise you can add any header to the message using the <literal><m:header></literal> tag:</para>
- <programlisting><m:header name="X-Sent-From" value="JBoss Seam" /></programlisting>
+ <programlisting><m:header name="X-Sent-From" value="JBoss Seam" /></programlisting>
</section>
</section>
@@ -134,10 +176,10 @@
<para>The JBossAS <literal>deploy/mail-service.xml</literal> configures a JavaMail session binding into JNDI. The default service configuration will
need altering for your network. <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JavaMail">http://wiki.jboss.org/wiki/Wiki.jsp?page=JavaMail</ulink>
describes the service in more detail.</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 sessionJndiName="java:/Mail" />
+ <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 sessionJndiName="java:/Mail" />
</components>]]></programlisting>
<para>Here we tell Seam to get the mail session bound to <literal>java:/Mail</literal> from JNDI.</para>
</section>
@@ -146,10 +188,10 @@
<title>Seam configured Session</title>
<para>A mail session can be configured via <literal>components.xml</literal>. Here we tell Seam to use <literal>smtp.example.com</literal>
as the smtp server, </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" />
+ <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>
More information about the jboss-cvs-commits
mailing list