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-action.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  10.8 KB  |  296 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 Action</title>
  21.     <authors>
  22.       <person name="Frank Ridderbusch" email="frank.ridderbusch@gmx.de"/>
  23.       <person name="Jon Evans" email="jon.evans@misgl.com"/>
  24.     </authors>
  25.   </header>
  26.   <body>
  27.     <s1 title="Description">
  28.       <p>
  29.         The Sendmail action is an action which makes the capability of sending
  30.         an email message available to the sitemap. This includes attaching
  31.         binary files which come either from another Cocoon pipeline or from
  32.         HTML file uploads. The Sendmail action make the primary methods of the
  33.         <link href="http://java.sun.com/products/javamail/">Java Mail API</link>
  34.         available to the sitemap.
  35.       </p>
  36.       <p>
  37.         The Sendmail action is an alternative to the
  38.         <link href="../xsp/sendmail.html">Sendmail logicsheet</link>.
  39.       </p>
  40.     </s1>
  41.     <s1 title="Usage">
  42.       <p>
  43.         Before the Sendmail action can be used, it must be activated - either in
  44.         Cocoon's main sitemap, or in a subsitemap which is used for your
  45.         application. Include the following <code>map:action</code> element
  46.         as child respectively grandchild of the <code>map:components</code>
  47.         -> <code>map:actions</code> elements.
  48.       </p>
  49.       <source>
  50. <![CDATA[
  51. <map:components>
  52.   <map:actions>
  53.      <map:action name="sendmail" logger="sitemap.action.sendmail"
  54.                   src="org.apache.cocoon.acting.Sendmail"/>
  55.   </map:actions>
  56. </map:components>
  57. ]]>
  58.       </source>
  59.     </s1>
  60.     <s1 title="Example Code">
  61.       <p>
  62.         This example uses a simple HTML form which provides entry fields for
  63.         <code>subject</code>, <code>cc</code>, <code>uploaded_file1</code> and
  64.         the email <code>body</code>.
  65.       </p>
  66.       <source>
  67. <![CDATA[
  68. <form action="/cocoon/mail/send-a-mail"
  69.       method="POST"
  70.      enctype="multipart/form-data">
  71.   <input type="text" name="subject" size="56" />
  72.   <input type="text" name="cc" size="56" />
  73.   <input type="file" name="uploaded_file1" size="56" />
  74.   <textarea name="body" rows="5" cols="72">
  75.   </textarea>
  76. </form>
  77. ]]>
  78.       </source>
  79.       <p>
  80.         Please keep in mind that it is important to use
  81.         <code>enctype="multipart/form-data"</code> if you want to upload files
  82.         which should be attached to an email message.
  83.       </p>
  84.       <p>The posted HTTP request data is processed by this sitemap fragment.</p>
  85.       <source>
  86. <![CDATA[
  87. <map:match pattern="mail/*">
  88.   <map:act type="sendmail">
  89.     <map:parameter name="smtphost" value="localhost"/>
  90.     <map:parameter name="from" value="cocoon@localhost"/>
  91.     <map:parameter name="to" value="mailinglist@somewhere.com"/>
  92.     <map:parameter name="subject" value="{request-param:subject}"/>
  93.     <map:parameter name="body" value="{request-param:body}"/>
  94.     <map:parameter name="cc" value="{request-param:cc}"/>
  95.     <map:parameter name="bcc" value="censor@somewhere.com"/>
  96.     <map:parameter name="attachments"
  97.                    value="uploaded_file1 context://welcome.xml"/>
  98.     <map:generate src="mail/{status}.xml"/>
  99.     <map:serialize type="xml"/>
  100.   </map:act>
  101. </map:match>
  102. ]]>
  103.       </source>
  104.       <p>
  105.         The input modules are used to supply some of the input parameters for
  106.         the Sendmail action. In this example, apart from the
  107.         <code>uploaded_file1</code> request parameter, a second file is attached
  108.         to the email message, using the Cocoon protocol notation (the file
  109.         <code>welcome.xml</code> from the Cocoon context directory). The result
  110.         of sending the email message is passed back into the sitemap through the
  111.         <code>status</code> parameter and is used to provide the user with a
  112.         feedback. (The transformation is left as an exercise to the reader).
  113.       </p>
  114.       <p>
  115.         Please consider the security implications if you let a user specify an
  116.         email address in an input form. A malicious user might abuse this to
  117.         send SPAM emails. So, this example is probably only useful in an
  118.         intranet application, where users can mostly be considered well behaved.
  119.       </p>
  120.     </s1>
  121.     <anchor id="parameters"/>
  122.     <s1 title="Input/Output Parameter Reference">
  123.       <p>
  124.         The following is the list of parameters which can be passed from the
  125.         sitemap into the Sendmail action.
  126.       </p>
  127.       <table>
  128.         <tr>
  129.           <th>Name:</th>
  130.           <th>Required?</th>
  131.           <th>Description:</th>
  132.         </tr>
  133.         <tr>
  134.           <td>smtphost</td>
  135.           <td>no</td>
  136.           <td>
  137.             The IP address or the name of the host, which should deliver the
  138.             email message. Better known as the mail transfer agent or short MTA.
  139.           </td>
  140.         </tr>
  141.         <tr>
  142.           <td>to</td>
  143.           <td>yes</td>
  144.           <td>
  145.             Sets the destination/to address of the email message. This can be a
  146.             list of comma separated email addresses.
  147.           </td>
  148.         </tr>
  149.         <tr>
  150.           <td>cc</td>
  151.           <td>no</td>
  152.           <td>
  153.             Sets the recipients of a carbon copy of this email. This can be a
  154.             list of comma separated email addresses.
  155.           </td>
  156.         </tr>
  157.         <tr>
  158.           <td>bcc</td>
  159.           <td>no</td>
  160.           <td>
  161.             Sets the recipients of a black carbon copy of the email. This can be
  162.             a list of comma separated email addresses.
  163.           </td>
  164.         </tr>
  165.         <tr>
  166.           <td>from</td>
  167.           <td>yes</td>
  168.           <td>Sets the from address of the message.</td>
  169.         </tr>
  170.         <tr>
  171.           <td>subject</td>
  172.           <td>no</td>
  173.           <td>Sets the subject line of the message.</td>
  174.         </tr>
  175.         <tr>
  176.           <td>body</td>
  177.           <td>no</td>
  178.           <td>
  179.             Sets the body text of the message. This parameter is ignored if the
  180.             <code>src</code> parameter is specified.
  181.           </td>
  182.         </tr>
  183.         <tr>
  184.           <td>src</td>
  185.           <td>no</td>
  186.           <td>
  187.             A url specifying the source of the text body of the email. If
  188.             <code>src</code> is specified, the <code>body</code> parameter is
  189.             ignored.
  190.           </td>
  191.         </tr>
  192.         <tr>
  193.           <td>srcMimeType</td>
  194.           <td>no</td>
  195.           <td>
  196.             The optional mime type of the source of the text body of the email
  197.             if you specified <code>src</code>.
  198.           </td>
  199.         </tr>
  200.         <tr>
  201.           <td>charset</td>
  202.           <td>no</td>
  203.           <td>
  204.             Sets the character set for encoding the message. This tag has only
  205.             an effect if no attachments are send.
  206.           </td>
  207.         </tr>
  208.         <tr>
  209.           <td>attachment</td>
  210.           <td>no</td>
  211.           <td>
  212.             Sets the attachment for this email. This is a blank separated list.
  213.             If an argument contains a ":", it is assumed that a Cocoon internal
  214.             protocol is specified (ex: <code>context://welcome.xml</code>). This
  215.             means that the attachment comes from a Cocoon pipeline (internally
  216.             an <code>org.apache.excalibur.source.Source</code> object). If the
  217.             argument does not contain a colon, the argument names a request
  218.             parameter which is a file upload through a HTML form (internally an
  219.             <code>org.apache.cocoon.components.request.multipart.FilePart</code>
  220.               object).
  221.           </td>
  222.         </tr>
  223. <!-- [CH] I believe deleting attachments should be handled at a different place
  224.      [JH] Aren't uploads not already deleted by default?
  225.         <tr>
  226.           <td>keep-attachment</td>
  227.           <td>no</td>
  228.           <td>
  229.             This is a boolean parameter, which defaults to <code>false</code>.
  230.             This means, that any uploads are delete from Cocoons upload
  231.             directory.
  232.           </td>
  233.         </tr>
  234. -->
  235.       </table>
  236.       <p>
  237.         The following is the list of parameters which are passed from Sendmail
  238.         action back into the sitemap.
  239.       </p>
  240.       <table>
  241.         <tr>
  242.           <th>Name:</th>
  243.           <th>Description:</th>
  244.         </tr>
  245.         <tr>
  246.           <td>status</td>
  247.           <td>
  248.             This parameter can take three values: <code>success</code>,
  249.             <code>user-error</code> and <code>server-error</code>.
  250.             <code>success</code> means that the email message has been
  251.             successfully delivered to the mail transfer host.
  252.             <code>user-error</code> means that there was a problem with at least
  253.             one of the specified email addresses (to, cc, bcc or from).
  254.             <code>server-error</code> means that there was some problem
  255.             delivering the message to the mail transfer host. In effect, this
  256.             parameter can be used to inform the user about the outcome of
  257.             sending the email message.
  258.           </td>
  259.         </tr>
  260.         <tr>
  261.           <td>message</td>
  262.           <td>
  263.             This parameter contain some explanatory text if the message couldn't
  264.             be delivered. It is unset if the email message had been successfully
  265.             sent.
  266.           </td>
  267.         </tr>
  268.       </table>
  269.     </s1>
  270.     <anchor id="hint"/>
  271.     <s1 title="Additional Hint">
  272.       <p>
  273.         Cocoon provides the capability to automatically parse a file upload out
  274.         of an incoming HTTP request. Depending on the setting of the parameter
  275.         <code>autosave-uploads</code> (default is <code>false</code>) in
  276.         Cocoon's <code>web.xml</code> file, the file upload is either stored in
  277.         memory (<code>false</code>) for further processing or stuffed into
  278.         Cocoons upload directory (<code>true</code>).
  279.       </p>
  280.       <p>
  281.         In theory, it should be equal whether the file upload data comes from
  282.         memory of from file. In my particular setup (Linux, Tomcat 4.0.4,
  283.         Mozilla 1.3 and JDK 1.4.1_02) I was unable to get the file uploading
  284.         working with <code>autosave-upload=false</code>. Somehow the attached
  285.         binary data was distorted (a GIF file does not appear to be a GIF any
  286.         more).
  287.       </p>
  288.       <p>
  289.         With <code>autosave-upload=true</code> it worked flawlessly, even
  290.         attaching multiple files.
  291.       </p>
  292.     </s1>
  293.   </body>
  294. </document>
  295.  
  296.