cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From h...@apache.org
Subject cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/actions sendmail-action.xml
Date Thu, 17 Apr 2003 20:13:44 GMT
haul        2003/04/17 13:13:44

  Added:       src/documentation/xdocs/userdocs/actions sendmail-action.xml
  Log:
  docs for sendmail action
  
  Revision  Changes    Path
  1.1                  cocoon-2.1/src/documentation/xdocs/userdocs/actions/sendmail-action.xml
  
  Index: sendmail-action.xml
  ===================================================================
  <?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"/>
      </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 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>
  
        <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="maillinglist@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 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>
  <!-- [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>
  -->
        </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 send.</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>
      </s1>
    </body>
  </document>
  
  <!--
  Local Variables:
  mode: xml
  sgml-indent-data: t
  End:
  -->
  
  
  

Mime
View raw message