Outline Your E-mail Content material Utilizing Pure Templates In ColdFusion

Usually, when rendering content material in a ColdFusion utility, I discover it finest to outline your view templates as “pure templates”. Which means, the rendering logic inside the view template file is totally pushed by inputs which are both handed into that template (as a module attribute) or made out there to that template (as an embody context). This retains the view template devoid of information fetching and manipulation logic. An electronic mail template is, primarily, a view template that is rendered to the CFMail tag as an alternative of being rendered to the browser. As such, the identical “pure template” rules must be utilized.

I wish to outline my electronic mail templates to be consumed utilizing the CFInclude tag. Which means, they seem to be a ColdFusion web page that consumes the dad or mum web page’s context (not an remoted context). In a really perfect world, I might wish to outline my electronic mail templates utilizing ColdFusion customized tags / modules. However, I do not love all of the ceremony of passing round attributes and capturing thistag.generatedContent. That is only a private selection – it is not a “finest apply”.

The construction of my electronic mail templates all comply with the identical sample: quite a few CFParam tags that assist outline the inputs adopted by a CFOutput tag that renders the e-mail to the present output buffer (usually utilizing my ColdFusion customized tag electronic mail DSL). The supply of the output buffer is outlined by the calling context; it may be the web page output buffer, it may be a CFSaveContent output buffer, it may be a CFMail output buffer—the e-mail template would not care, it simply generates output.

To see this in motion, let’s create a quite simple “Welcome” electronic mail for a brand new person. For the sake of organizational simplicity, I like all of my electronic mail inputs to be captured underneath a single construction: partial:

<!---
	We're utilizing the CFParam tags to assist doc which inputs are required on this electronic mail
	template. This would possibly not be an exhaustive definition (elective arrays, for instance, are a
	laborious datatype to parameterize); however, this system will catch most use-cases.
--->
<cfparam title="partial.person.title" sort="string" />
<cfparam title="partial.person.electronic mail" sort="string" />
<cfparam title="partial.profileUrl" sort="string" />

<!--- Assume that the e-mail can be rendered to a content material buffer. --->
<cfoutput>

	<h1>
		Welcome #encodeForHtml( partial.person.title )#!
	</h1>

	<p>
		Thanks for signing as much as expertise our wonderful service!
		We have created an account for you utilizing the login:
		&lt;<sturdy>#encodeForHtml( partial.person.electronic mail )#</sturdy>&gt;.
	</p>

	<p>
		<a href="#partial.profileUrl#">View your profile</a> &rarr;
	</p>

</cfoutput>

As you possibly can see, this electronic mail template makes no assumptions about how it’s getting used. Apart from that it assumes the existence of a partial construction and it renders output to the “web page”.

And, now that we’ve got this “pure template” for our electronic mail rendering, we will render it in quite a lot of contexts. For instance, when creating this explicit workflow, we will render this electronic mail template on to the web page for debugging:

<cfscript>

	// NOTE: In Lucee CFML, we will use `localmode` to make sure that any UNSCOPED variables
	// created through the rendering of the embody template (corresponding to these within the CFLoop
	// tag) are routinely scoped to the LOCAL scope of this operate.
	(operate() localmode = "fashionable" {

		// Configure the hard-coded inputs for the e-mail template.
		var partial = {
			person: {
				id: 1,
				title: "Julia Stiles",
				electronic mail: "julia.stiles@instance.com"
			},
			profileUrl: "https://www.instance.com/account/1/profile"
		};

		// Since that is only a TEST of the e-mail, we will render the e-mail content material
		// on to the display screen with out capturing it in an middleman buffer.
		embody "./templates/emails/welcome.cfm";

	})();

</cfscript>

Since that is for growth functions, I can simply hard-code the partial variable after which CFInclude the e-mail template. And, once we run this ColdFusion web page, we get the next output:

As you possibly can see, the e-mail template, pushed by the one partial construction, rendered completely to the browser output.

In a manufacturing workflow, we will render the identical template. Solely, as an alternative of rendering on to the web page, we’ll render to a CFSaveContent buffer after which use that buffer to execute a CFMail tag. Within the following code, the sendWelcomEmail() technique is supposed to be consultant of a manufacturing workflow:

<cfscript>

	sendWelcomEmail( 1 );

	// ------------------------------------------------------------------------------- //
	// ------------------------------------------------------------------------------- //

	// NOTE: In Lucee CFML, we will use `localmode` to make sure that any UNSCOPED variables
	// created through the rendering of the embody template (corresponding to these within the CFLoop
	// tag) are routinely scoped to the LOCAL scope of this operate.
	public void operate sendWelcomEmail( required numeric userID )
		localmode = "fashionable"
		{

		// Simulate collect precise dwell knowledge.
		var person = getUser( userID );

		// Generate the inputs for the e-mail template utilizing dwell person knowledge.
		var partial = {
			person: {
				id: person.id,
				title: person.title,
				electronic mail: person.electronic mail
			},
			profileUrl: "https://www.instance.com/account/#person.id#/profile"
		};

		// Though we might render the CFInclude on to the CFMail physique, I like
		// to create an middleman buffer for the e-mail template. This makes it simpler
		// to debug points if one thing goes improper.
		savecontent variable = "native.emailBody" {
			embody "./templates/emails/welcome.cfm";
		}

		mail
			to = person.electronic mail
			from = "no-reply@instance.com"
			topic = "Welcome to our service"
			sort = "html"
			server = "127.0.0.1:1025"
			async = false
			{

			// Render interpolated electronic mail content material to CFMail tag.
			echo( emailBody );

		}

	}


	// Mock technique to get person knowledge.
	public struct operate getUser() {

		return({
			id: 2,
			title: "Patrick Verona",
			electronic mail: "patrick.verona@instance.com"
		});

	}

</cfscript>

This time, as an alternative of hard-coding the partial construction, I am doing a little (mock) knowledge fetching for the given person after which establishing the partial from the person knowledge. Then, once I invoke my CFInclude tag to execute the e-mail template, I am seize the e-mail output into the variable, emailBody; which I am then utilizing in my CFMail tag.

And, once we run this ColdFusion web page and verify the Mailhog electronic mail shopper, we get the next output:

As you possibly can see, the e-mail template, which was captured by a CFSaveContent buffer after which shipped by way of CFMail has efficiently landed in my Mailhog inbox.

By coding the e-mail template such that it’s utterly pushed by inputs and generates output to the contextual output buffer, we have created a whole lot of flexibility. This makes it easy to each develop emails with hard-coded knowledge and to ship emails in a manufacturing ColdFusion setting utilizing database-driven inputs.

Need to use code from this publish?
Take a look at the license.