home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-cocoon-addon-1.4.9-installer.exe / sendmail.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  10.6 KB  |  362 lines
  1. <?xml version="1.0" encoding="utf-8"?>
  2. <!--
  3.   Copyright 1999-2004 The Apache Software Foundation
  4.  
  5.   Licensed under the Apache License, Version 2.0 (the "License");
  6.   you may not use this file except in compliance with the License.
  7.   You may obtain a copy of the License at
  8.  
  9.       http://www.apache.org/licenses/LICENSE-2.0
  10.  
  11.   Unless required by applicable law or agreed to in writing, software
  12.   distributed under the License is distributed on an "AS IS" BASIS,
  13.   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.   See the License for the specific language governing permissions and
  15.   limitations under the License.
  16. -->
  17. <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
  18. <document>
  19.   <header>
  20.     <title>Sendmail Logicsheet</title>
  21.  
  22. <!--
  23. Credits:
  24.  
  25. The skeleton was taken from the Session logicsheet documentation by
  26. Christopher Painter-Wakefield. An article on
  27. http://www.cocooncenter.org/ by  Perry Molendijk <perry@inflexions.com>
  28. describing the setup of the Sendmail logicsheet has been a major
  29. inspiration.
  30.  
  31. This documentation describes the features as implemented
  32. by patch attachment
  33.  
  34. http://nagoya.apache.org/bugzilla/showattachment.cgi?attach_id=4879
  35.  
  36. to
  37.  
  38. http://nagoya.apache.org/bugzilla/show_bug.cgi?id=15005
  39. -->
  40.  
  41.     <authors>
  42.       <person name="Frank Ridderbusch" email="frank.ridderbusch@gmx.de"/>
  43.     </authors>
  44.   </header>
  45.  
  46.   <body>
  47.     <s1 title="Description">
  48.       <p>The Sendmail logicsheet (taglib) is a XSP logicsheet that
  49.     wraps XML tags around the operation of sending an email
  50.     message. Specifically, the Sendmail logicsheet provides an XML
  51.     interface to the primary methods of the Java Mail API for
  52.     sending an internet mail including the ability to attach any
  53.     binary data files to the message (see the
  54.     <link
  55.       href="http://java.sun.com/products/javamail/">Java
  56.       Mail API</link> ) for more
  57.     information.</p>
  58.  
  59.       <p>The Sendmail logicsheet is an alternative to the <link
  60.       href="../actions/sendmail-action.html">Sendmail
  61.       action</link>.</p>
  62.     </s1>
  63.  
  64.     <s1 title="Usage">
  65.       <p>As an XSP logicsheet, the Sendmail logicsheet can only be used
  66.     in an XSP page. It may be helpful to be familiar with <link
  67.       href="xsp.html">XSP</link> before working with this (or any)
  68.     logicsheet.</p>
  69.  
  70.       <p>Since the Sendmail logicsheet is not activated in the default
  71.     Cocoon setup, a couple of steps must be taken before an email
  72.     can be send.</p>
  73.  
  74.       <p>First of all Cocoon must have been compiled with the required
  75.     Java Mail API libraries. The libraries <code>mail.jar</code>
  76.     from the Java Mail distribution and the library
  77.     <code>activation.jar</code> from the Java Activation Framework
  78.     have to be copied to the location <code>lib/local</code> of
  79.     Cocoon's source distribution. Cocoon must then be recompiled.
  80.       </p>
  81.  
  82.       <p>Before the Sendmail logicsheet can be used, some setup in
  83.     <code>cocoon.xconf</code> is required. See, if the following
  84.     fragment is already existing.</p>
  85.  
  86.       <source>
  87. <![CDATA[
  88. <builtin-logicsheet>
  89.   <parameter name="prefix" value="sendmail"/>
  90.   <parameter name="uri" value="http://apache.org/cocoon/sendmail/1.0"/>
  91.   <parameter name="href"
  92.    value="resource://org/apache/cocoon/components/language/markup/xsp/java/sendmail.xsl"/>
  93. </builtin-logicsheet>
  94. ]]>
  95.       </source>
  96.  
  97.       <p>If it is not present, it is easiest to simply locate the
  98.     entry <code>xsp-response</code> for the Response logicsheet
  99.     and put the above fragment before the
  100.     <code><builtin-logicsheet></code> of the Response
  101.     logicsheet entry. This can either be done before recompilation
  102.     or later, when Cocoon is already deployed. If done later,
  103.     Cocoon must be reloaded.</p>
  104.  
  105.       <p>To use the Sendmail logicsheet, you must first declare the
  106.     <em>sendmail</em> namespace, mapping it to the uri
  107.     <em>http://apache.org/cocoon/sendmail/1.0</em>. These
  108.     steps will result in code like this:</p>
  109.  
  110.       <source>
  111. <![CDATA[
  112. <xsp:page language="java"
  113.   xmlns:xsp="http://apache.org/xsp"
  114.   xmlns:sendmail="http://apache.org/cocoon/sendmail/1.0">
  115.  
  116. ...
  117.  
  118. </xsp:page>
  119. ]]>
  120.       </source>
  121.  
  122.       <p>You may then use any of the elements in the <em>sendmail</em>
  123.     namespace described in the <link
  124.       href="sendmail.html#elements">Elements Reference</link>
  125.     section below.</p>
  126.     </s1>
  127.  
  128.     <s1 title="Example Code">
  129.       <p>The following code shows an example of using the Sendmail
  130.     logicsheet. A HTML form is used, to post information about
  131.     updated documentation to some imaginary mailing list. The XSP
  132.     page is invoked from a HTML form like this.</p>
  133.  
  134.       <source>
  135. <![CDATA[
  136. <form action="/cocoon/xsp/mail/send-a-mail" method="post"
  137.       enctype="multipart/form-data">
  138.  
  139. <input type="text" name="subject" size="56" />
  140. ...
  141. <input type="text" name="url1" size="56" />
  142. ...
  143. <input type="text" name="url1" size="56" />
  144. ...
  145. <input type="file" name="uploaded_file1" size="56" />
  146. ...
  147. <input type="file" name="uploaded_file2" size="56" />
  148. ...
  149. <textarea name="changes" rows="5" cols="72">
  150. </textarea>
  151. ...
  152. </form>
  153. ]]>
  154.       </source>
  155.  
  156.       <p>Since the form allows to attach upto two arbitrary files, it
  157.     is important, that <code>enctype="multipart/form-data"</code>
  158.     is used. This is the XSP code, that is invoked:</p>
  159.  
  160.       <source>
  161. <![CDATA[
  162. <?xml version="1.0" encoding="ISO-8859-1"?>
  163. <xsp:page language="java"
  164.       xmlns:xsp="http://apache.org/xsp"
  165.       xmlns:xsp-request="http://apache.org/xsp/request/2.0"
  166.       xmlns:sendmail="http://apache.org/cocoon/sendmail/1.0">
  167.   <email>
  168.     <xsp:logic>
  169.       StringBuffer body = new StringBuffer();
  170.       body.append("  Documentation:\n----------------\n");
  171.       body.append("URL: ");
  172.       body.append(<xsp-request:get-parameter name="url1"/>);
  173.       body.append("\n");
  174.       body.append("URL: ");
  175.       body.append(<xsp-request:get-parameter name="url2"/>);
  176.       body.append("\n\n");
  177.       body.append("     Changes:\n----------------\n");
  178.       body.append(<xsp-request:get-parameter name="changes"/>);
  179.       body.append("\n\n");
  180.     </xsp:logic>
  181.     <sendmail:send-mail>
  182.       <sendmail:from>from address</sendmail:from>
  183.       <sendmail:to>some maillinglist address</sendmail:to>
  184.       <sendmail:subject><xsp-request:get-parameter name="subject"/></sendmail:subject>
  185.       <!-- Modify the next line to point to your mail server -->
  186.       <sendmail:smtphost>localhost</sendmail:smtphost>
  187.       <sendmail:body><xsp:expr>body.toString()</xsp:expr></sendmail:body>
  188.       <sendmail:attachment>
  189.         <sendmail:param name="object"><xsp:expr>request.get("attachment")</xsp:expr></sendmail:param>
  190.       </sendmail:attachment>
  191.       <sendmail:attachment url="context://welcome.xml" mime-type="text/plain" name="foo.txt"/>
  192.       <sendmail:attachment url="cocoon:///"            mime-type="text/html"  name="welcome.html"/>
  193.  
  194.       <sendmail:on-success>
  195.          <p>
  196.            Email successfully sent.
  197.          </p>
  198.       </sendmail:on-success>
  199.       <sendmail:on-error>
  200.             <p style="color:red;">
  201.            An error occurred: <sendmail:error-message/>
  202.             </p>
  203.       </sendmail:on-error>
  204.     </sendmail:send-mail>
  205.  </email>
  206. </xsp:page>
  207. ]]>
  208.       </source>
  209.  
  210.       <p>Cocoons feature to automatically disassemble the incoming
  211.     request puts the uploaded files automatically into the upload
  212.     directory and the files are accessible through the
  213.     <code>uploaded_file[12]</code> request parameters (make sure,
  214.     that <code>autosave-uploads</code> is set to <code>true</code>
  215.     in the <code>WEB-INF/web.xml</code> file of the Cocoon
  216.     context). By using
  217.     <code><xsp:expr>request.get("req-param")</xsp:expr></code>
  218.     you actually get an object of class
  219.     <code>org.apache.cocoon.servlet.multipart.Part</code>.
  220.     The <code><sendmail:send-mail></code> fragment is
  221.     replaced with an <code><error></code> element, if an
  222.     error occurs during the sending of the message.</p>
  223.  
  224.       <p>Another noteworthy item is the formatting of the body text
  225.     through a Java <code>StringBuffer</code>. Any formatting, that
  226.     would be placed inside the <code><sendmail:body></code>
  227.     element would be lost due to the internal workings of the
  228.     Sendmail logicsheet.</p>
  229.  
  230.     </s1>
  231.  
  232.     <anchor id="elements" />
  233.  
  234.     <s1 title="Elements Reference">
  235.  
  236.       <table>
  237.         <caption>All of the Sendmail logicsheet elements, in alphabetic
  238.         order.</caption>
  239.  
  240.         <tr>
  241.           <th>Element Name</th>
  242.  
  243.           <th>Attributes/Child Elements</th>
  244.  
  245.           <th>Description</th>
  246.         </tr>
  247.  
  248.         <tr>
  249.  
  250.           <td>sendmail:attachment</td>
  251.  
  252.           <td>
  253.       </td>
  254.  
  255.           <td>Sets the attachment for this email. Attributes for setting name,
  256.               mime-type, or an URL (e.g. using cocoon:-protocol!). Parameters
  257. can be set dynamically using <sendmail:param/> syntax. If an object is
  258. to be attached, it must be set this way. Use the following
  259.         expression to obtain the correct object from the request:
  260.         <code><xsp:expr>request.get("req-param")</xsp:expr></code>.
  261.           </td>
  262.         </tr>
  263.  
  264.         <tr>
  265.           <td>sendmail:bcc</td>
  266.  
  267.           <td>
  268.           </td>
  269.  
  270.           <td>Sets the recipients of a blind carbon copy of the
  271.         email. This can be a list of comma separated email
  272.         addresses.</td>
  273.         </tr>
  274.  
  275.         <tr>
  276.           <td>sendmail:body</td>
  277.  
  278.           <td>
  279.           </td>
  280.  
  281.           <td>Sets the body text of the message.</td>
  282.         </tr>
  283.  
  284.  
  285.  
  286.         <tr>
  287.           <td>sendmail:cc</td>
  288.  
  289.           <td>
  290.           </td>
  291.  
  292.           <td>Sets the recipients of a carbon copy of this email. This
  293.         can be a list of comma separated email addresses.</td>
  294.         </tr>
  295.  
  296.         <tr>
  297.           <td>sendmail:charset</td>
  298.  
  299.           <td>
  300.           </td>
  301.  
  302.           <td>Sets the character set for encoding the message. This
  303.         tag has only an effect, if no attachments are send.</td>
  304.         </tr>
  305.  
  306.         <tr>
  307.           <td>sendmail:from</td>
  308.  
  309.           <td>
  310.           </td>
  311.  
  312.           <td>Sets the from address of the message.</td>
  313.         </tr>
  314.  
  315.         <tr>
  316.           <td>sendmail:smtphost</td>
  317.  
  318.           <td>
  319.           </td>
  320.  
  321.           <td>The IP-address or the name of the host, which should
  322.         deliver the email message. Better know as the mail
  323.         transfer agent or short MTA.</td>
  324.         </tr>
  325.  
  326.         <tr>
  327.           <td>sendmail:subject</td>
  328.  
  329.           <td>
  330.           </td>
  331.  
  332.           <td>Sets the subject line of the message.</td>
  333.         </tr>
  334.  
  335.         <tr>
  336.           <td>sendmail:to</td>
  337.  
  338.           <td></td>
  339.  
  340.           <td>Sets the destination/to address of the email message.
  341.         This can be a list of comma separated email
  342.         addresses.</td>
  343.         </tr>
  344.  
  345.       </table>
  346.     </s1>
  347.  
  348.     <s1 title="Hint">
  349.       <p>Please read this <link
  350.       href="../actions/sendmail-action.html#hint">hint</link>,
  351.     since it applies here as well.</p>
  352.     </s1>
  353.   </body>
  354. </document>
  355.  
  356. <!--
  357. Local Variables:
  358. mode: xml
  359. sgml-indent-data: t
  360. End:
  361. -->
  362.