Clickframes

Clickframes allows you to specify the e-mails that should be sent when particular outcomes arise. At the moment, I’m writing password reset functionality for an app that I’m developing. When the user provides his e-mail address, the system will send a a unique URL by e-mail allowing him to reset his password – pretty routine stuff.

Clickframes-PHP makes it easy to integrate dynamic content into your e-mails, which keeps code customization to a minimum. I think it’s easiest to lead by example, so here’s a genuine appspec snippet:

<email id="passwordReset">
	<title>Password Reset Message</title>
	<description>
		Sent to user when he requests a password reset.
	</description>
	<emailSubject>CookItLater Password Reset Request</emailSubject>
	<emailText>
<![CDATA[
Hi!

You're only moments away from getting back into to your recipe collection.

To reset your password, click this URL, or paste into your browser:

http://cookitlater.com/passwordReset/#{user.passwordResetCode}

The unique code in the URL will expire in 24 hours to prevent unauthorized access.

We've sent this e-mail to #{user.email} - if this request was sent in error, please accept our apologies for the inconvenience.

Thanks!
CookItLater
]]>
	</emailText>
	<outputs>
		<output id="user" entity="user">
			<title>User</title>
			<description>
				User who requested password reset.
			</description>
		</output>
	</outputs>
</email>

When define an output within your e-mail, its properties become available to your e-mail text using Apache Velocity syntax, e.g. #{outputId.propertyId}

You can also define other substitution variables as you please, e.g. #{myAwesomeVariable}.

Clickframes-PHP generates a library class, [appspecName]Email.class.php, that manages all your e-mails. The class contains a send method for each e-mail; a method entitled sendPasswordReset() would be generated for the example above. The generated method accepts a “from” address, a “to” address, your substitution variables, and any outputs as parameters. Review the generated code for precise details.

The generated outcome code will automatically create your e-mail and send it. If you’re using Windows, I highly recommend smtp4dev to test e-mail locally.

If you’ve thought ahead a bit, you generally won’t need to customize the generated e-mail code. Please leave comments or contact the mailing list if you have questions or suggestions for improvement.