org.apache.turbine.util.velocity
Class VelocityEmail

java.lang.Object
  |
  +--org.apache.turbine.util.velocity.VelocityEmail

public class VelocityEmail
extends java.lang.Object

This is a simple class for sending email from within Velocity. Essentially, the body of the email is processed with a Velocity Context object. The beauty of this is that you can send email from within your Velocity template or from your business logic in your Java code. The body of the email is just a Velocity template so you can use all the template functionality of Velocity within your emails!

Example Usage (This all needs to be on one line in your template):

Setup your context:

context.put ("VelocityEmail", new VelocityEmail() );

Then, in your template:

 $VelocityEmail.setTo("Jon Stevens", "jon@latchkey.com")
     .setFrom("Mom", "mom@mom.com").setSubject("Eat dinner")
     .setTemplate("email/momEmail.vm")
     .setContext($context)
 
The email/momEmail.wm template will then be parsed with the Context that was defined with setContext().

If you want to use this class from within your Java code all you have to do is something like this:

 VelocityEmail ve = new VelocityEmail();
 ve.setTo("Jon Stevens", "jon@latchkey.com");
 ve.setFrom("Mom", "mom@mom.com").setSubject("Eat dinner");
 ve.setContext(context);
 ve.setTemplate("email/momEmail.vm")
 ve.send();
 

(Note that when used within a Velocity template, the send method will be called for you when Velocity tries to convert the VelocityEmail to a string by calling toString()).

If you need your email to be word-wrapped, you can add the following call to those above:

 ve.setWordWrap (60);
 

This class is just a wrapper around the SimpleEmail class. Thus, it uses the JavaMail API and also depends on having the mail.server property set in the TurbineResources.properties file. If you want to use this class outside of Turbine for general processing that is also possible by making sure to set the path to the TurbineResources.properties. See the TurbineConfig class for more information.

Version:
$Id: VelocityEmail.java,v 1.2 2002/07/11 16:53:19 mpoeschl Exp $
Author:
Jon S. Stevens, Greg Coladonato

Constructor Summary
VelocityEmail()
          Constructor
VelocityEmail(org.apache.velocity.context.Context context)
          Constructor
 
Method Summary
 org.apache.velocity.context.Context getContext()
          Get the context object that will be merged with the template.
 void send()
          This method sends the email.
 VelocityEmail setContext(org.apache.velocity.context.Context context)
          Set the context object that will be merged with the template.
 VelocityEmail setFrom(java.lang.String from, java.lang.String email)
          From: name, email.
 VelocityEmail setSubject(java.lang.String subject)
          Subject.
 VelocityEmail setTemplate(java.lang.String template)
          Velocity template to execute.
 VelocityEmail setTo(java.lang.String to, java.lang.String email)
          To: name, email
 VelocityEmail setWordWrap(int wordWrap)
          Set the column at which long lines of text should be word- wrapped.
 java.lang.String toString()
          The method toString() calls send() for ease of use within a Velocity template (see example usage above).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

VelocityEmail

public VelocityEmail()
Constructor

VelocityEmail

public VelocityEmail(org.apache.velocity.context.Context context)
Constructor
Method Detail

setTo

public VelocityEmail setTo(java.lang.String to,
                           java.lang.String email)
To: name, email
Parameters:
to - A String with the TO name.
email - A String with the TO email.
Returns:
A VelocityEmail (self).

setFrom

public VelocityEmail setFrom(java.lang.String from,
                             java.lang.String email)
From: name, email.
Parameters:
from - A String with the FROM name.
email - A String with the FROM email.
Returns:
A VelocityEmail (self).

setSubject

public VelocityEmail setSubject(java.lang.String subject)
Subject.
Parameters:
subject - A String with the subject.
Returns:
A VelocityEmail (self).

setTemplate

public VelocityEmail setTemplate(java.lang.String template)
Velocity template to execute. Path is relative to the Velocity templates directory.
Parameters:
template - A String with the template.
Returns:
A VelocityEmail (self).

setWordWrap

public VelocityEmail setWordWrap(int wordWrap)
Set the column at which long lines of text should be word- wrapped. Setting to zero turns off word-wrap (default). NOTE: don't use tabs in your email template document, or your word-wrapping will be off for the lines with tabs in them.
Parameters:
wordWrap - The column at which to wrap long lines.
Returns:
A VelocityEmail (self).

setContext

public VelocityEmail setContext(org.apache.velocity.context.Context context)
Set the context object that will be merged with the template.
Parameters:
context - A Velocity context object.
Returns:
A VelocityEmail (self).

getContext

public org.apache.velocity.context.Context getContext()
Get the context object that will be merged with the template.
Returns:
A Context (self).

send

public void send()
          throws java.lang.Exception
This method sends the email.

toString

public java.lang.String toString()
The method toString() calls send() for ease of use within a Velocity template (see example usage above).
Overrides:
toString in class java.lang.Object
Returns:
An empty string.


Copyright © 2000-2002 Apache Software Foundation. All Rights Reserved.