<document>
  <header>
    <product>resin</product>
    <resin-2.0>$resin/java_tut/tag-mail.xtp</resin-2.0>
    <title>Mail Tag</title>
    <description>
      <p>Body tags can grab JSP results and send them to an entirely different
        location.  It's easy to create a custom tag that sends part of a JSP to
        a survey account.  The required attribute <var/to/> will specify the
        mail address for the mail and <var/subject/> specifies the subject.  The
        enclosed JSP contains the body of the mail.</p>

      <p>The contents of the tag can be any JSP code.  You can still use arbitrary
        scriptlets writing to <var/out/>.</p>
    </description>
  </header>

  <body>
    <summary/>
<section title="Using the mail tag">

<p>This example use of the mail tag writes a simple message with the
results of a form.  The user and the vote are mailed to john.doe.</p>

<example title="mail.jsp">
&lt;%@ taglib prefix="ct" uri="/WEB-INF/tags.tld" %>
&lt;h1>Testing Mail&lt;/h1>

&lt;ct:mail to="john.doe@localhost" subject="survey response">
&lt;item>
  &lt;user>&lt;%= request.getParameter("user") %>&lt;/user>
  &lt;vote>&lt;%= request.getParameter("vote") %>&lt;/vote>
&lt;/item>
&lt;/ct:mail>
</example>
<results>
Subject: survey
   Date: Mon, 11 Sep 2000 18:06:52 -0700
   From: Resin Account &lt;resin@localhost>
     To: john.doe@localhost

&lt;item>
  &lt;user>Fred Smith&lt;/user>
  &lt;vote>Gryffindor&lt;/vote>
&lt;/item>
</results>

</section>

<section title="Implementation of the Mail Tag">

<p>The MailTag has two required attributes, <var/subject/> and <var/to/>.
As usual, they are set using the <var/bean/> design patterns
<var/setSubject()/> and <var/setTo()/>.</p>

<p>Mailing uses Resin's VFS.  The <var/mailto:/> scheme sends mail
to any user account.</p>

<example title="test/MailTag.java">
package test;

import java.io.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

import com.caucho.vfs.*;

public class MailTag extends BodyTagSupport {
  private String to;
  private String subject;

  public void setTo(String to)
  {
    this.to = to;
  }

  public void setSubject(String subject)
  {
    this.subject = subject;
  }
  
  public int doAfterBody()
    throws JspException
  {
    String body = getBodyContent().getString();

    Path mailto = Vfs.lookup("mailto:" + to);
    try {
      WriteStream os = mailto.openWrite();
      os.setAttribute("subject", subject);

      os.print(body);

      os.close();
    } catch (IOException e) {
      throw new JspException(e.toString());
    }

    return SKIP_BODY;
  }
}
</example>

</section>

<section title="Attribute Configuration">

<p>Each expected attribute needs an entry in the .tld.  In this case,
both <var/to/> and <var/subject/> are required.</p>

<example title="WEB-INF/tag.tld">
&lt;taglib>
  &lt;tag>
    &lt;name>mail&lt;/name>
    &lt;tagclass>test.MailTag&lt;/tagclass>
    &lt;attribute>
      &lt;name>to&lt;/name>
      &lt;required>true&lt;/required>
    &lt;/attribute>
    &lt;attribute>
      &lt;name>subject&lt;/name>
      &lt;required>true&lt;/required>
    &lt;/attribute>
  &lt;/tag>
&lt;/taglib>
</example>

</section>

<section title="Summary">
<ul>
<li><var/BodyTags/> can capture arbitrary JSP output.
<li>After the contents complete, JSP calls <var/doAfterBody/>.
<li><var/getBodyContent()/> contains the JSP body.
<li>VFS <var/mailto:/> sends mail.
</ul>
</section>
  </body>
</document>
