| <?xml version="1.0" encoding="utf-8"?> |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" |
| "../../dtd/document-v10.dtd"> |
| <document> |
| <header> |
| <title>Sendmail Action</title> |
| <authors> |
| <person name="Frank Ridderbusch" email="frank.ridderbusch@gmx.de"/> |
| <person name="Jon Evans" email="jon.evans@misgl.com"/> |
| </authors> |
| </header> |
| <body> |
| <s1 title="Description"> |
| <p> |
| The Sendmail action is an action which makes the capability of sending |
| an email message available to the sitemap. This includes attaching |
| binary files which come either from another Cocoon pipeline or from |
| HTML file uploads. The Sendmail action make the primary methods of the |
| <link href="http://java.sun.com/products/javamail/">Java Mail API</link> |
| available to the sitemap. |
| </p> |
| <p> |
| The Sendmail action is an alternative to the |
| <link href="../xsp/sendmail.html">Sendmail logicsheet</link>. |
| </p> |
| </s1> |
| <s1 title="Usage"> |
| <p> |
| Before the Sendmail action can be used, it must be activated - either in |
| Cocoon's main sitemap, or in a subsitemap which is used for your |
| application. Include the following <code>map:action</code> element |
| as child respectively grandchild of the <code>map:components</code> |
| -> <code>map:actions</code> elements. |
| </p> |
| <source> |
| <![CDATA[ |
| <map:components> |
| <map:actions> |
| <map:action name="sendmail" logger="sitemap.action.sendmail" |
| src="org.apache.cocoon.acting.Sendmail"/> |
| </map:actions> |
| </map:components> |
| ]]> |
| </source> |
| </s1> |
| <s1 title="Example Code"> |
| <p> |
| This example uses a simple HTML form which provides entry fields for |
| <code>subject</code>, <code>cc</code>, <code>uploaded_file1</code> and |
| the email <code>body</code>. |
| </p> |
| <source> |
| <![CDATA[ |
| <form action="/cocoon/mail/send-a-mail" |
| method="POST" |
| enctype="multipart/form-data"> |
| <input type="text" name="subject" size="56" /> |
| <input type="text" name="cc" size="56" /> |
| <input type="file" name="uploaded_file1" size="56" /> |
| <textarea name="body" rows="5" cols="72"> |
| </textarea> |
| </form> |
| ]]> |
| </source> |
| <p> |
| Please keep in mind that it is important to use |
| <code>enctype="multipart/form-data"</code> if you want to upload files |
| which should be attached to an email message. |
| </p> |
| <p>The posted HTTP request data is processed by this sitemap fragment.</p> |
| <source> |
| <![CDATA[ |
| <map:match pattern="mail/*"> |
| <map:act type="sendmail"> |
| <map:parameter name="smtphost" value="localhost"/> |
| <map:parameter name="from" value="cocoon@localhost"/> |
| <map:parameter name="to" value="mailinglist@somewhere.com"/> |
| <map:parameter name="subject" value="{request-param:subject}"/> |
| <map:parameter name="body" value="{request-param:body}"/> |
| <map:parameter name="cc" value="{request-param:cc}"/> |
| <map:parameter name="bcc" value="censor@somewhere.com"/> |
| <map:parameter name="attachments" |
| value="uploaded_file1 context://welcome.xml"/> |
| <map:generate src="mail/{status}.xml"/> |
| <map:serialize type="xml"/> |
| </map:act> |
| </map:match> |
| ]]> |
| </source> |
| <p> |
| The input modules are used to supply some of the input parameters for |
| the Sendmail action. In this example, apart from the |
| <code>uploaded_file1</code> request parameter, a second file is attached |
| to the email message, using the Cocoon protocol notation (the file |
| <code>welcome.xml</code> from the Cocoon context directory). The result |
| of sending the email message is passed back into the sitemap through the |
| <code>status</code> parameter and is used to provide the user with a |
| feedback. (The transformation is left as an exercise to the reader). |
| </p> |
| <p> |
| Please consider the security implications if you let a user specify an |
| email address in an input form. A malicious user might abuse this to |
| send SPAM emails. So, this example is probably only useful in an |
| intranet application, where users can mostly be considered well behaved. |
| </p> |
| </s1> |
| <anchor id="parameters"/> |
| <s1 title="Input/Output Parameter Reference"> |
| <p> |
| The following is the list of parameters which can be passed from the |
| sitemap into the Sendmail action. |
| </p> |
| <table> |
| <tr> |
| <th>Name:</th> |
| <th>Required?</th> |
| <th>Description:</th> |
| </tr> |
| <tr> |
| <td>smtphost</td> |
| <td>no</td> |
| <td> |
| The IP address or the name of the host, which should deliver the |
| email message. Better known as the mail transfer agent or short MTA. |
| </td> |
| </tr> |
| <tr> |
| <td>to</td> |
| <td>yes</td> |
| <td> |
| Sets the destination/to address of the email message. This can be a |
| list of comma separated email addresses. |
| </td> |
| </tr> |
| <tr> |
| <td>cc</td> |
| <td>no</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>bcc</td> |
| <td>no</td> |
| <td> |
| Sets the recipients of a black carbon copy of the email. This can be |
| a list of comma separated email addresses. |
| </td> |
| </tr> |
| <tr> |
| <td>from</td> |
| <td>yes</td> |
| <td>Sets the from address of the message.</td> |
| </tr> |
| <tr> |
| <td>subject</td> |
| <td>no</td> |
| <td>Sets the subject line of the message.</td> |
| </tr> |
| <tr> |
| <td>body</td> |
| <td>no</td> |
| <td> |
| Sets the body text of the message. This parameter is ignored if the |
| <code>src</code> parameter is specified. |
| </td> |
| </tr> |
| <tr> |
| <td>src</td> |
| <td>no</td> |
| <td> |
| A url specifying the source of the text body of the email. If |
| <code>src</code> is specified, the <code>body</code> parameter is |
| ignored. |
| </td> |
| </tr> |
| <tr> |
| <td>srcMimeType</td> |
| <td>no</td> |
| <td> |
| The optional mime type of the source of the text body of the email |
| if you specified <code>src</code>. |
| </td> |
| </tr> |
| <tr> |
| <td>charset</td> |
| <td>no</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>attachment</td> |
| <td>no</td> |
| <td> |
| Sets the attachment for this email. This is a blank separated list. |
| If an argument contains a ":", it is assumed that a Cocoon internal |
| protocol is specified (ex: <code>context://welcome.xml</code>). This |
| means that the attachment comes from a Cocoon pipeline (internally |
| an <code>org.apache.excalibur.source.Source</code> object). If the |
| argument does not contain a colon, the argument names a request |
| parameter which is a file upload through a HTML form (internally an |
| <code>org.apache.cocoon.components.request.multipart.FilePart</code> |
| object). |
| </td> |
| </tr> |
| <!-- [CH] I believe deleting attachments should be handled at a different place |
| [JH] Aren't uploads not already deleted by default? |
| <tr> |
| <td>keep-attachment</td> |
| <td>no</td> |
| <td> |
| This is a boolean parameter, which defaults to <code>false</code>. |
| This means, that any uploads are delete from Cocoons upload |
| directory. |
| </td> |
| </tr> |
| --> |
| </table> |
| <p> |
| The following is the list of parameters which are passed from Sendmail |
| action back into the sitemap. |
| </p> |
| <table> |
| <tr> |
| <th>Name:</th> |
| <th>Description:</th> |
| </tr> |
| <tr> |
| <td>status</td> |
| <td> |
| This parameter can take three values: <code>success</code>, |
| <code>user-error</code> and <code>server-error</code>. |
| <code>success</code> means that the email message has been |
| successfully delivered to the mail transfer host. |
| <code>user-error</code> means that there was a problem with at least |
| one of the specified email addresses (to, cc, bcc or from). |
| <code>server-error</code> means that there was some problem |
| delivering the message to the mail transfer host. In effect, this |
| parameter can be used to inform the user about the outcome of |
| sending the email message. |
| </td> |
| </tr> |
| <tr> |
| <td>message</td> |
| <td> |
| This parameter contain some explanatory text if the message couldn't |
| be delivered. It is unset if the email message had been successfully |
| sent. |
| </td> |
| </tr> |
| </table> |
| </s1> |
| <anchor id="hint"/> |
| <s1 title="Additional Hint"> |
| <p> |
| Cocoon provides the capability to automatically parse a file upload out |
| of an incoming HTTP request. Depending on the setting of the parameter |
| <code>autosave-uploads</code> (default is <code>false</code>) in |
| Cocoon's <code>web.xml</code> file, the file upload is either stored in |
| memory (<code>false</code>) for further processing or stuffed into |
| Cocoons upload directory (<code>true</code>). |
| </p> |
| <p> |
| In theory, it should be equal whether the file upload data comes from |
| memory of from file. In my particular setup (Linux, Tomcat 4.0.4, |
| Mozilla 1.3 and JDK 1.4.1_02) I was unable to get the file uploading |
| working with <code>autosave-upload=false</code>. Somehow the attached |
| binary data was distorted (a GIF file does not appear to be a GIF any |
| more). |
| </p> |
| <p> |
| With <code>autosave-upload=true</code> it worked flawlessly, even |
| attaching multiple files. |
| </p> |
| </s1> |
| </body> |
| </document> |
| |