cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jo...@apache.org
Subject cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/actions sendmail-action.xml
Date Fri, 09 Jan 2004 18:45:46 GMT
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="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>
  +      <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> -&gt; <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>
  +        -&gt; <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="cocoon@localhost"/>
  -    <map:parameter name="to" value="maillinglist@somewhere.com"/>
  +    <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"/>
  +                   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:
  --->
  
  
  

Mime
View raw message