haul 2003/04/17 13:18:09
Modified: src/documentation/xdocs/userdocs/xsp book.xml
Added: src/documentation/xdocs/userdocs/xsp sendmail.xml
Log:
docs for sendmail logicsheet
thanks to Frank Ridderbusch <frank.ridderbusch AT fujitsu-siemens.com>
Revision Changes Path
1.2 +1 -0 cocoon-2.1/src/documentation/xdocs/userdocs/xsp/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/xsp/book.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- book.xml 9 Mar 2003 00:08:29 -0000 1.1
+++ book.xml 17 Apr 2003 20:18:09 -0000 1.2
@@ -23,6 +23,7 @@
<menu-item label="Session" href="session.html"/>
<menu-item label="ESQL" href="esql.html"/>
<menu-item label="Forms" href="logicsheet-forms.html"/>
+ <menu-item label="Sendmail" href="sendmail.html"/>
</menu>
</book>
1.1
cocoon-2.1/src/documentation/xdocs/userdocs/xsp/sendmail.xml
Index: sendmail.xml
===================================================================
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
<document>
<header>
<title>Sendmail Logicsheet</title>
<!--
Credits:
The skeleton was taken from the Session logicsheet documentation by
Christopher Painter-Wakefield. An article on
http://www.cocooncenter.org/ by Perry Molendijk <[EMAIL PROTECTED]>
describing the setup of the Sendmail logicsheet has been a major
inspiration.
This documentation describes the features as implemented
by patch attachment
http://nagoya.apache.org/bugzilla/showattachment.cgi?attach_id=4879
to
http://nagoya.apache.org/bugzilla/show_bug.cgi?id=15005
-->
<authors>
<person name="Frank Ridderbusch" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Description">
<p>The Sendmail logicsheet (taglib) is a XSP logicsheet that
wraps XML tags around the operation of sending an email
message. Specifically, the Sendmail logicsheet provides an XML
interface to the primary methods of the Java Mail API for
sending an internet mail including the ability to attach any
binary data files to the message (see the
<link
href="http://java.sun.com/products/javamail/";>Java
Mail API</link> ) for more
information.</p>
<p>The Sendmail logicsheet is an alternative to the <link
href="../actions/sendmail-action.html">Sendmail
action</link>.</p>
</s1>
<s1 title="Usage">
<p>As an XSP logicsheet, the Sendmail logicsheet can only be used
in an XSP page. It may be helpful to be familiar with <link
href="xsp.html">XSP</link> before working with this (or any)
logicsheet.</p>
<p>Since the Sendmail logicsheet is not activated in the default
Cocoon setup, a couple of steps must be taken before an email
can be send.</p>
<p>First of all Cocoon must have been compiled with the required
Java Mail API libraries. The libraries <code>mail.jar</code>
from the Java Mail distribution and the library
<code>activation.jar</code> from the Java Activation Framework
have to be copied to the location <code>lib/local</code> of
Cocoon's source distribution. Cocoon must then be recompiled.
</p>
<p>Before the Sendmail logicsheet can be used, some setup in
<code>cocoon.xconf</code> is required. See, if the following
fragment is already existing.</p>
<source>
<![CDATA[
<builtin-logicsheet>
<parameter name="prefix" value="sendmail"/>
<parameter name="uri" value="http://apache.org/cocoon/sendmail/1.0"/>
<parameter name="href"
value="resource://org/apache/cocoon/components/language/markup/xsp/java/sendmail.xsl"/>
</builtin-logicsheet>
]]>
</source>
<p>If it is not present, it is easiest to simply locate the
entry <code>xsp-response</code> for the Response logicsheet
and put the above fragment before the
<code><builtin-logicsheet></code> of the Response
logicsheet entry. This can either be done before recompilation
or later, when Cocoon is already deployed. If done later,
Cocoon must be reloaded.</p>
<p>To use the Sendmail logicsheet, you must first declare the
<em>sendmail</em> namespace, mapping it to the uri
<em>http://apache.org/cocoon/sendmail/1.0</em>. These
steps will result in code like this:</p>
<source>
<![CDATA[
<xsp:page language="java"
xmlns:xsp="http://apache.org/xsp";
xmlns:sendmail="http://apache.org/cocoon/sendmail/1.0";>
...
</xsp:page>
]]>
</source>
<p>You may then use any of the elements in the <em>sendmail</em>
namespace described in the <link
href="sendmail.html#elements">Elements Reference</link>
section below.</p>
</s1>
<s1 title="Example Code">
<p>The following code shows an example of using the Sendmail
logicsheet. A HTML form is used, to post information about
updated documentation to some imaginary mailing list. The XSP
page is invoked from a HTML form like this.</p>
<source>
<![CDATA[
<form action="/cocoon/xsp/mail/send-a-mail" method="post"
enctype="multipart/form-data">
<input type="text" name="subject" size="56" />
...
<input type="text" name="url1" size="56" />
...
<input type="text" name="url1" size="56" />
...
<input type="file" name="uploaded_file1" size="56" />
...
<input type="file" name="uploaded_file2" size="56" />
...
<textarea name="changes" rows="5" cols="72">
</textarea>
...
</form>
]]>
</source>
<p>Since the form allows to attach upto two arbitrary files, it
is important, that <code>enctype="multipart/form-data"</code>
is used. This is the XSP code, that is invoked:</p>
<source>
<![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>
<xsp:page language="java"
xmlns:xsp="http://apache.org/xsp";
xmlns:xsp-request="http://apache.org/xsp/request/2.0";
xmlns:sendmail="http://apache.org/cocoon/sendmail/1.0";>
<email>
<xsp:logic>
StringBuffer body = new StringBuffer();
body.append(" Documentation:\n----------------\n");
body.append("URL: ");
body.append(<xsp-request:get-parameter name="url1"/>);
body.append("\n");
body.append("URL: ");
body.append(<xsp-request:get-parameter name="url2"/>);
body.append("\n\n");
body.append(" Changes:\n----------------\n");
body.append(<xsp-request:get-parameter name="changes"/>);
body.append("\n\n");
</xsp:logic>
<sendmail:send-mail>
<sendmail:from>from address</sendmail:from>
<sendmail:to>some maillinglist address</sendmail:to>
<sendmail:subject><xsp-request:get-parameter
name="subject"/></sendmail:subject>
<!-- Modify the next line to point to your mail server -->
<sendmail:smtphost>localhost</sendmail:smtphost>
<sendmail:body><xsp:expr>body.toString()</xsp:expr></sendmail:body>
<sendmail:attachment>
<sendmail:param
name="object"><xsp:expr>request.get("attachment")</xsp:expr></sendmail:param>
</sendmail:attachment>
<sendmail:attachment url="context://welcome.xml" mime-type="text/plain"
name="foo.txt"/>
<sendmail:attachment url="cocoon:///" mime-type="text/html"
name="welcome.html"/>
<sendmail:on-success>
<p>
Email successfully sent.
</p>
</sendmail:on-success>
<sendmail:on-error>
<p style="color:red;">
An error occurred: <sendmail:error-message/>
</p>
</sendmail:on-error>
</sendmail:send-mail>
</email>
</xsp:page>
]]>
</source>
<p>Cocoons feature to automatically disassemble the incoming
request puts the uploaded files automatically into the upload
directory and the files are accessible through the
<code>uploaded_file[12]</code> request parameters (make sure,
that <code>autosave-uploads</code> is set to <code>true</code>
in the <code>WEB-INF/web.xml</code> file of the Cocoon
context). By using
<code><xsp:expr>request.get("req-param")</xsp:expr></code>
you actually get an object of class
<code>org.apache.cocoon.servlet.multipart.Part</code>.
The <code><sendmail:send-mail></code> fragment is
replaced with an <code><error></code> element, if an
error occurs during the sending of the message.</p>
<p>Another noteworthy item is the formatting of the body text
through a Java <code>StringBuffer</code>. Any formatting, that
would be placed inside the <code><sendmail:body></code>
element would be lost due to the internal workings of the
Sendmail logicsheet.</p>
</s1>
<anchor id="elements" />
<s1 title="Elements Reference">
<table>
<caption>All of the Sendmail logicsheet elements, in alphabetic
order.</caption>
<tr>
<th>Element Name</th>
<th>Attributes/Child Elements</th>
<th>Description</th>
</tr>
<tr>
<td>sendmail:attachment</td>
<td>
</td>
<td>Sets the attachment for this email. Attributes for setting name,
mime-type, or an URL (e.g. using cocoon:-protocol!). Parameters
can be set dynamically using <sendmail:param/> syntax. If an object is
to be attached, it must be set this way. Use the following
expression to obtain the correct object from the request:
<code><xsp:expr>request.get("req-param")</xsp:expr></code>.
</td>
</tr>
<tr>
<td>sendmail:bcc</td>
<td>
</td>
<td>Sets the recipients of a blind carbon copy of the
email. This can be a list of comma separated email
addresses.</td>
</tr>
<tr>
<td>sendmail:body</td>
<td>
</td>
<td>Sets the body text of the message.</td>
</tr>
<tr>
<td>sendmail:cc</td>
<td>
</td>
<td>Sets the recipients of a carbon copy of this email. This
can be a list of comma separated email addresses.</td>
</tr>
<tr>
<td>sendmail:charset</td>
<td>
</td>
<td>Sets the character set for encoding the message. This
tag has only an effect, if no attachments are send.</td>
</tr>
<tr>
<td>sendmail:from</td>
<td>
</td>
<td>Sets the from address of the message.</td>
</tr>
<tr>
<td>sendmail:smtphost</td>
<td>
</td>
<td>The IP-address or the name of the host, which should
deliver the email message. Better know as the mail
transfer agent or short MTA.</td>
</tr>
<tr>
<td>sendmail:subject</td>
<td>
</td>
<td>Sets the subject line of the message.</td>
</tr>
<tr>
<td>sendmail:to</td>
<td></td>
<td>Sets the destination/to address of the email message.
This can be a list of comma separated email
addresses.</td>
</tr>
</table>
</s1>
<s1 title="Hint">
<p>Please read this <link
href="../actions/sendmail-action.html#hint">hint</link>,
since it applies here as well.</p>
</s1>
</body>
</document>
<!--
Local Variables:
mode: xml
sgml-indent-data: t
End:
-->
