joerg 2004/01/09 10:45:46
Modified: src/documentation/xdocs/userdocs/actions sendmail-action.xml
Log:
additions and corrections (also grammar) by Jon Evans
(jon.evans(at)misgl.com), Bug 26016
Revision Changes Path
1.4 +212 -196
cocoon-2.1/src/documentation/xdocs/userdocs/actions/sendmail-action.xml
Index: sendmail-action.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/actions/sendmail-action.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- sendmail-action.xml 12 Oct 2003 13:04:51 -0000 1.3
+++ sendmail-action.xml 9 Jan 2004 18:45:46 -0000 1.4
@@ -6,31 +6,32 @@
<title>Sendmail Action</title>
<authors>
<person name="Frank Ridderbusch" email="[EMAIL PROTECTED]"/>
+ <person name="Jon Evans" email="[EMAIL PROTECTED]"/>
</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>
+ <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 Cocoons main sitemap or in a subsitemap, which is
- used for your application. Include the below
- <code>map:action</code> fragment inside the
- <code>map:components</code> -> <code>map:actions</code>
- tags.</p>
-
+ <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>
@@ -38,228 +39,243 @@
<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>
+ 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>
-...
+ <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>
+ 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>
-
+ <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="[EMAIL PROTECTED]"/>
- <map:parameter name="to" value="[EMAIL PROTECTED]"/>
+ <map:parameter name="to" value="[EMAIL PROTECTED]"/>
<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="[EMAIL PROTECTED]"/>
<map:parameter name="attachments"
- value="uploaded_file1 context://welcome.xml"/>
+ 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>
+ <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>
-
+ <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 know 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.</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>
+ <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
- <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>
+ [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>
-
+ <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 send.</td>
- </tr>
+ <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 Cocoons
- <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>
+ <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>
-<!--
-Local Variables:
-mode: xml
-sgml-indent-data: t
-End:
--->
