[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Tue Feb 13 11:28:18 EST 2007
User: gavin
Date: 07/02/13 11:28:18
Modified: doc/reference/en/modules jbpm.xml mail.xml security.xml
Log:
note to self: teach Pete how to use CDATA ;-)
Revision Changes Path
1.27 +10 -6 jboss-seam/doc/reference/en/modules/jbpm.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: jbpm.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/jbpm.xml,v
retrieving revision 1.26
retrieving revision 1.27
diff -u -b -r1.26 -r1.27
--- jbpm.xml 17 Jan 2007 03:14:29 -0000 1.26
+++ jbpm.xml 13 Feb 2007 16:28:18 -0000 1.27
@@ -365,9 +365,11 @@
Seam configuration in <literal>components.xml</literal>.
</para>
- <programlisting><![CDATA[<component class="org.jboss.seam.core.Jbpm">
- <property name="pageflowDefinitions">pageflow.jpdl.xml</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<core:jbpm>
+ <core:pageflow-definitions>
+ <value>pageflow.jpdl.xml</value>
+ </core:pageflow-definitions>
+</core:jbpm>]]></programlisting>
<para>
The first line installs jBPM, the second points to a jPDL-based
@@ -627,9 +629,11 @@
business process definitions:
</para>
- <programlisting><![CDATA[<component class="org.jboss.seam.core.Jbpm">
- <property name="processDefinitions">todo.jpdl.xml</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<core:jbpm>
+ <core:process-definitions>
+ <value>todo.jpdl.xml</value>
+ </core:process-definitions>
+</core:jbpm>]]></programlisting>
</section>
1.15 +125 -84 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.14
retrieving revision 1.15
diff -u -b -r1.14 -r1.15
--- mail.xml 11 Feb 2007 22:41:21 -0000 1.14
+++ mail.xml 13 Feb 2007 16:28:18 -0000 1.15
@@ -11,24 +11,26 @@
<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">
-
- <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>You can try out Seam by visiting
- <a href="http://labs.jboss.com/jbossseam">http://labs.jboss.com/jbossseam</a>.</p>
- <p>Regards,</p>
- <p>Peter</p>
- </m:body>
-</m:message></programlisting>
+ <para>You don't need to learn a whole new templating language to use Seam Mail—an email is just facelet!</para>
+
+ <programlisting><![CDATA[<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:subject>Try out Seam!</m:subject>
+
+ <m:body>
+ <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>
+ <p>Regards,</p>
+ <p>Peter</p>
+ </m:body>
+
+</m:message>]]></programlisting>
<para>The <literal><m:message></literal> tag wraps the whole message, and tells Seam to start rendering an email. Inside the
<literal><m:message></literal> tag we use an <literal><m:from></literal> tag to set who the message is from, a <literal><m:to></literal> tag to
@@ -41,17 +43,18 @@
<literal>m:message</literal> the <literal>mailSession</literal> is called to send the email, so all you have to do is
ask Seam to render the view:</para>
- <programlisting>@In(create=true)
+ <programlisting><![CDATA[@In(create=true)
private Renderer renderer;
public void send() {
try {
- renderer.render("/simple.xhtml");
- facesMessages.add("Email sent successfully");
- } catch (Exception e) {
- facesMessages.add("Email sending failed: " + e.getMessage());
+ renderer.render("/simple.xhtml");
+ facesMessages.add("Email sent successfully");
}
-}</programlisting>
+ catch (Exception e) {
+ facesMessages.add("Email sending failed: " + e.getMessage());
+ }
+}]]></programlisting>
<para>If, for example, you entered an invalid email address, then an exception would be thrown, which is caught
and then displayed to the user.</para>
@@ -62,20 +65,20 @@
<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>
+ <programlisting><![CDATA[<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>
+ <programlisting><![CDATA[<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="#{numbers}" /></programlisting>
+ <programlisting><![CDATA[<m:attachment value="#{numbers}"/>]]></programlisting>
- <para> a <literal>byte[]</literal> or a <literal>java.io.InputStream</literal>:</para>
+ <para>Or a <literal>byte[]</literal> or a <literal>java.io.InputStream</literal>:</para>
- <programlisting><m:attachment value="#{person.photo}" contentType="image/png" /></programlisting>
+ <programlisting><![CDATA[<m:attachment value="#{person.photo}" contentType="image/png"/>]]></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>
@@ -83,86 +86,105 @@
<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 fileName="tiny.pdf">
- <p:document>
+ <programlisting><![CDATA[<m:attachment fileName="tiny.pdf">
+ <p:document>
A very tiny PDF
- </p:document>
-</m:attachment></programlisting>
+ </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="#{people}" var="person">
- <m:attachment value="#{person.photo}" contentType="image/jpeg" fileName="#{person.firstname}_#{person.lastname}.jpg"/>
-</ui:repeat></programlisting>
+ <programlisting><![CDATA[<ui:repeat value="#{people}" var="person">
+ <m:attachment value="#{person.photo}" contentType="image/jpeg" fileName="#{person.firstname}_#{person.lastname}.jpg"/>
+</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,
-please go to http://labs.jboss.com/jbossseam to explore Seam.</f:facet>
-</m:body></programlisting>
+
+ <programlisting><![CDATA[<m:body>
+ <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>
<section>
<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}" />
-</ui:repeat></programlisting>
+
+ <programlisting><![CDATA[<ui:repeat value="#{allUsers} var="user">
+ <m:to name="#{user.firstname} #{user.lastname}" address="#{user.emailAddress}" />
+</ui:repeat>]]></programlisting>
+
</section>
<section>
<title>Multiple messages</title>
- <para>Sometimes however you need to send a slightly different message to each recipient (e.g. a password
+
+ <para>Sometimes, however, you need to send a slightly different message to each recipient (e.g. a password
reset). The best way to do this is to place the whole message inside a <literal><ui:repeat></literal>:</para>
- <programlisting><ui:repeat value="#{people}" var="p">
- <m:message>
- <m:from name="#{person.firstname} #{person.lastname}">#{person.address}</m:from>
- <m:to name="#{p.firstname}">#{p.address}</m:to>
+
+ <programlisting><![CDATA[<ui:repeat value="#{people}" var="p">
+ <m:message>
+ <m:from name="#{person.firstname} #{person.lastname}">#{person.address}</m:from>
+ <m:to name="#{p.firstname}">#{p.address}</m:to>
...
- </m:message>
-</ui:repeat>
- </programlisting>
+ </m:message>
+</ui:repeat>]]></programlisting>
+
</section>
<section>
<title>Templating</title>
- <para>The mail templating example shows that facelets templating 'just works' with the Seam mail tags.</para>
+
+ <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:subject>#{subject}</m:subject>
- <m:body>
- <html>
- <body>
- <ui:insert name="body"> This is the default body, specified by the template.</ui:insert>
- </body>
- </html>
- </m:body>
-</m:message></programlisting>
+
+ <programlisting><![CDATA[<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:subject>#{subject}</m:subject>
+ <m:body>
+ <html>
+ <body>
+ <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">
- <p>This email demonstrates that you can easily use <i>facelets templating features</i> in your code!</p>
-</ui:define></programlisting>
+
+ <programlisting><![CDATA[<ui:param name="subject" value="Templating with Seam Mail"/>
+<ui:define name="body">
+ <p>This example demonstrates that you can easily use <i>facelets templating</i> in email!</p>
+</ui:define>]]></programlisting>
+
</section>
<section>
<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><![CDATA[<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><![CDATA[<m:header name="X-Sent-From" value="JBoss Seam"/>]]></programlisting>
+
</section>
</section>
@@ -203,13 +225,16 @@
<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
(the API and impl used in JBoss AS are 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 <literal>mailSession</literal> component uses JavaMail to talk to a 'real' SMTP server.</para>
<section>
@@ -221,26 +246,37 @@
<section>
<title>JNDI lookup in JBoss AS</title>
+
<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:mail-session session-jndi-name="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:mail-session session-jndi-name="java:/Mail"/>
+
</components>]]></programlisting>
+
<para>Here we tell Seam to get the mail session bound to <literal>java:/Mail</literal> from JNDI.</para>
+
</section>
<section>
<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:mail-session 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:mail-session host="smtp.example.com"/>
+
</components>]]></programlisting>
+
</section>
</section>
</section>
@@ -253,7 +289,8 @@
<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>
+ <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>
@@ -265,7 +302,8 @@
<itemizedlist>
<listitem>
<para>
- <literal>importance</literal> — low, normal or high. By default normal, this sets the importance of the mail message.
+ <literal>importance</literal> — low, normal or high. By default normal, this sets the
+ importance of the mail message.
</para>
</listitem>
<listitem>
@@ -275,8 +313,8 @@
</listitem>
<listitem>
<para>
- <literal>requestReadReceipt</literal> — by default false, if set, a read receipt will be request will be added, with the
- read receipt being sent to the <literal>From:</literal> address.
+ <literal>requestReadReceipt</literal> — by default false, if set, a read receipt will be
+ request will be added, with the read receipt being sent to the <literal>From:</literal> address.
</para>
</listitem>
<listitem>
@@ -327,7 +365,8 @@
<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>.
+ 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>
@@ -347,7 +386,8 @@
<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>.
+ 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>
@@ -367,7 +407,8 @@
<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>.
+ 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>
1.35 +2 -2 jboss-seam/doc/reference/en/modules/security.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: security.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/security.xml,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -b -r1.34 -r1.35
--- security.xml 13 Feb 2007 14:58:22 -0000 1.34
+++ security.xml 13 Feb 2007 16:28:18 -0000 1.35
@@ -469,7 +469,7 @@
If the expression specified doesn't evaluate to <literal>true</literal>, either
</para>
- <numberedlist>
+ <itemizedlist>
<listitem>
<para>
if the user is not logged in, a <literal>NotLoggedInException</literal>
@@ -482,7 +482,7 @@
exception is thrown.
</para>
</listitem>
- </numberedlist>
+ </itemizedlist>
<para>
It is also possible to call the <literal>hasRole()</literal> and <literal>hasPermission()</literal>
More information about the jboss-cvs-commits
mailing list