io.stallion.email

Class ContactableEmailer<T extends Contactable>

java.lang.Object

io.stallion.email.ContactableEmailer<T>

Type Parameters:

T -

Direct Known Subclasses:

AddressEmailer, ExceptionEmailRunnable.ExceptionEmailer, JsExtendableContactableEmailer, SimpleFormSubmissionEmailer, UserController.ResetEmailEmailer, UserController.VerifyEmailEmailer

public abstract class ContactableEmailer<T extends Contactable>
extends Object

This class a helper class for defining a way to send emails to a Contactable (usually a User or a Contact). You create a subclass, override getTemplate() and getSubject() to define the template and subject to use, override any additional handlers, and then you can send an email via: new MyEmailer(user, myContextVars).sendEmail() ContactableEmailer does a lot of extra work for you, such as adding in extra variables, excluding optedout users, preventing duplicates, making it easy to use templated subject lines, etc, etc.

Field Summary

Fields

Modifier and Type	Field and Description
protected String	dayStamp
protected String	hourStamp
protected String	minuteStamp
protected Sandbox	sandbox
protected String	template
protected URL	templateUrl
protected T	user
protected String	weekStamp

Constructor Summary

Constructors

Constructor and Description
ContactableEmailer(T user)
ContactableEmailer(T user, Map<String,Object> context)

Method Summary

Modifier and Type	Method and Description
boolean	checkDefaultOptOut() Apply default heuristics for opting out the user from email.
boolean	checkOptOut() Override this to check for additional conditions where the user might be opted out.
String	getCc() Override this to set a custom list of CC addresses
protected Map<String,Object>	getContext()
String	getEmailType() The type of the email, used for logging, defaults to using the Java class name, can be overrident
String	getFromAddress() Who is sending the email.
String	getReplyTo() Override this to set a custom-reply to address.
Sandbox	getSandbox() If not null, will render the email template with the sandbox, thus limiting access in the template context to site-wide data.
abstract String	getSubject() Your email subject.
abstract String	getTemplate() The path to the jinja template.
String	getUniqueKey() This is used to prevent accidentally sending duplicate emails, by default the uniqueKey is built from the subject, the contact id, the current week, and the email type.
protected boolean	hasSeenKey() Checks to see if the unique key for this email has been seen.
abstract boolean	isTransactional() Return true if this is an email that opt-out should not apply to.
protected void	markSeenKey() Mark the unique key as being seen.
protected void	onPrepareContext() Override this to prepare additional context variables.
void	onPreSend() Override this to do any additional actions just before the email is finally sent out.
protected void	prepareContext()
<Y extends ContactableEmailer> Y	put(String key, Object val) Add additional data to the template context
boolean	sendEmail()
<E extends ContactableEmailer> E	setSandbox(Sandbox box)
boolean	shouldLog()
protected void	updateContext(Map<String,? extends Object> context)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

user

protected T extends Contactable user

template

protected String template

templateUrl

protected URL templateUrl

weekStamp

protected String weekStamp

hourStamp

protected String hourStamp

dayStamp

protected String dayStamp

sandbox

protected Sandbox sandbox

minuteStamp

protected String minuteStamp

Constructor Detail

ContactableEmailer

public ContactableEmailer(T user)

ContactableEmailer

public ContactableEmailer(T user,
                          Map<String,Object> context)

Method Detail

sendEmail

public boolean sendEmail()

shouldLog

public boolean shouldLog()

checkDefaultOptOut

public boolean checkDefaultOptOut()

Apply default heuristics for opting out the user from email.

Returns:

isTransactional

public abstract boolean isTransactional()

Return true if this is an email that opt-out should not apply to. For example, return true for: password reset emails, security alerts, transaction reciepts. return false for all other emails that need an unsubscribe link, per CAN-SPAM laws.

Returns:

checkOptOut

public boolean checkOptOut()

Override this to check for additional conditions where the user might be opted out.

Returns:

getSandbox

public Sandbox getSandbox()

If not null, will render the email template with the sandbox, thus limiting access in the template context to site-wide data.

Returns:

setSandbox

public <E extends ContactableEmailer> E setSandbox(Sandbox box)

onPreSend

public void onPreSend()

Override this to do any additional actions just before the email is finally sent out. This may be useful for logging the message to a database.

prepareContext

protected void prepareContext()

onPrepareContext

protected void onPrepareContext()

Override this to prepare additional context variables.

updateContext

protected void updateContext(Map<String,? extends Object> context)

put

public <Y extends ContactableEmailer> Y put(String key,
                                            Object val)

Add additional data to the template context

Parameters:

key -

val -

getEmailType

public String getEmailType()

The type of the email, used for logging, defaults to using the Java class name, can be overrident

Returns:

hasSeenKey

protected boolean hasSeenKey()

Checks to see if the unique key for this email has been seen.

Returns:

markSeenKey

protected void markSeenKey()

Mark the unique key as being seen.

getTemplate

public abstract String getTemplate()

The path to the jinja template. If the template is in a resource file, should be "pluginName:/my-template.jinja" where my-template.jinja is in the templates folder in your resources directory in your java project. If it is a built-in stallion template, use "stallion:/my-template.jinja"

Returns:

getSubject

public abstract String getSubject()

Your email subject. This is interpreted as a SimpleTemplate -- so if you do "Hello, {{ contact.firstName }}" or "Hello, {{ myVar }}" then it will look-up the variable from the context and interpolate it.

Returns:

getFromAddress

public String getFromAddress()

Who is sending the email. Defaults to email.defaultFromAddress in Stallion settings, or the first admin email if that does not exist, or the email user and host, if that doesn't exist.

Returns:

getReplyTo

public String getReplyTo()

Override this to set a custom-reply to address.

Returns:

getCc

public String getCc()

Override this to set a custom list of CC addresses

Returns:

getUniqueKey

public String getUniqueKey()

This is used to prevent accidentally sending duplicate emails, by default the uniqueKey is built from the subject, the contact id, the current week, and the email type.

Returns:

getContext

protected Map<String,Object> getContext()