ASF_20_SRC_AUTO/src/documentation/xdocs/userdocs/xsp/sendmail.xml - cocoon - Git at Google

 <?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 <perry@inflexions.com>
 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="frank.ridderbusch@gmx.de"/>
     </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>&lt;builtin-logicsheet&gt;</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>&lt;xsp:expr&gt;request.get("req-param")&lt;/xsp:expr&gt;</code>
 	you actually get an object of class
 	<code>org.apache.cocoon.servlet.multipart.Part</code>.
 	The <code>&lt;sendmail:send-mail&gt;</code> fragment is
 	replaced with an <code>&lt;error&gt;</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>&lt;sendmail:body&gt;</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 &lt;sendmail:param/&gt; 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>&lt;xsp:expr&gt;request.get("req-param")&lt;/xsp:expr&gt;</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:
 -->
	<?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 <perry@inflexions.com>
	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="frank.ridderbusch@gmx.de"/>
	</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:
	-->