Getting Started with Email Template Filters

Introduction

Comparison

The Email Template Filter extension provides a way to create and control emails that are sent when new entries are created from the frontend, giving you as much control over the content as possible, making it easier to debug.

It is an improvement over the “Send Email” filter in many important ways:

The form can't be hijacked to send email to whoever the hijacker wants
You don't have to edit your XSLT to change the basics of the email, meaning a copy editor could tweak the templates to their liking, if you trust them
You can pull data from anywhere in the system and email it
You've got the ability to easily debug the contents of the email.

That's not to say that it's some pinnacle of perfection, there probably are problems, and probably are things that could be done better, your feedback is welcome.

Before we start, I should make it clear that I'm assuming you already have some knowledge of how to use Symphony, not limited to creating pages, events and datasources.

Client demands

So, what are we going to do with it? Well, I was kinda thinking, kinda, that we'd do something that is fairly common and create a contact form suitable for a large company; “Generic Placeholder Manufacturing” or GPM for short.

As with any client, GPM has requirements, today they want a large pineapple and a stack of chocolate coated, deep fried elephants, but thankfully tomorrow we think we know that they'll want a form that:

Allows their potential clients or existing members to contact them
Is sent to a different address depending on the visitors choice
Is sent to a different office depending on the visitors choice.

You're probably thinking that's quite a tall order, and not something you can easily create in Symphony, fortunately it is quite easy.

Basically what we'll be doing is creating a Symphony page, attaching a couple of datasources to it, then emailing its output across the internet.

So, what are you waiting for? Get to it!

Building it

Creating sections

The first thing we need to do is create a couple of new sections, one will store information regarding GPMs offices, the other will store data saved from the contact form.

Create the “Office Locations” section with these fields:

Location: The location of the office, any text input type field should do quite nicely.
General Enquiry Email: The email address to use for general enquiries.
Member Enquiry Email: The email address to use for general enquiries, a text input with email validation is best for both.
Contact Submissions: A Bi-Link field pointing at the section of the same name.

And the “Contact Submissions” section with these fields:

First Name: A text input will do the trick.
Last Name: Another text input.
Email: Just like the email addresses above.
Type: A select box with two choices: “General” or “Member”
Message: A textarea, with a formatter of some kind or you'll run the risk of user input breaking your email.
Office Location: A Bi-Link field pointing at the section of the same name.

Dummy copy time

Now would be a good time to enter some test data into your sections, for example here's my “Office Locations” section:

And here's my “Contact Submissions” section:

You can enter more if you like, but we only really need a couple of each.

Creating the datasource

Now we need a datasource to retrieve an entry from the “Contact Submissions” section, lets call it: “Content Submission by Id”. It's purpose — to fetch just one entry from the “Content Submissions” section.

A few things you should definitely note:

We're filtering by $etf-entry-id, it is a special parameter that is populated by the event we create in a few steps, don't forget to include it
The other parameter that we're filtering with, $entry-id, is created in the next step
In the included elements, only one (office-location: entries) of the two office-location items is selected. Because we used the Bi-Link field to link our two sections together, having this item selected means we have access to the linked entry without needing a second datasource.

Creating the email page

We need to create a new Symphony page, it will have one purpose — to provide the HTML that you want to send to the client:

As you can see, I've attached the datasource we created in the previous step to this page, and also defined that $entry-id parameter that is uses. The parameter assures that we pull the correct entry from the datasource.

When the page is ready take a look at {$root}/email-contact-details/{$entry-id}/?debug and examine the XML, here's an excerpt from mine:

<entry id="5">
    <office-location mode="entries" entries="1">
        <section id="4" handle="office-locations">Office Locations</section>
        <entry id="3">
            <location handle="brisbane">Brisbane</location>
            <general-enquiry-email>general@brisbane...</general-enquiry-email>
            <member-enquiry-email>member@brisbane...</member-enquiry-email>
        </entry>
    </office-location>
    <first-name handle="john">John</first-name>
    <last-name handle="doe">Doe</last-name>
    <email handle="john-examplecom">john@example.com</email>
    <type>
        <item handle="general">General</item>
    </type>
    <message word-count="2"><p>Hi everybody!</p></message>
</entry>

You should take some time to make the page output the HTML you want to be sent, how you do this really is up to you, treat it as a normal Symphony page, because that's what it is, the Email Template Filter extension doesn't care as long as it exists.

Creating the template

Now comes the groovy part, we need to create a new template. Take yourself to the “Emails – Templates” page and click the Create New button.

Fill in the top section of the page, again selecting the datasource we created, like so:

Next up, conditions. Each condition hangs on its expression, an XPath that tests against the XML output from the selected datasources. The first condition with an expression that doesn't evaluate to false, or with an expression that is left empty, will be used, any conditions afterwards will be ignored.

Each condition also has a range of fields for the subject, sender name, address to send from, and addresses to send to (comma delimited). Each of these fields can accept XPath expressions wrapped in curly braces, for example: {datasource/entry/@id}.

Now, time to actually our first condition, like so:

Above we're using the expression field to limit the condition to entries intended for the “General Enquiry” address. To target the “Member Enquiry” address, simply create a new condition, but change the expression to match member instead of general.

We've also selected the page we created above and in the URL parameters we've placed an expression to get the id of the entry. This will be read by the page and set as the value of the $entry-id parameter, which in turn is used by the datasource.

Create the event

Now, what we need is an event, because what the Email Template Filter extension does is make the template we created above into an event filter.

So create an event for the “Content Submissions” section, selecting the appropriate filter:

Obviously this event needs to be attached to a page somewhere that has a form, so go ahead, copy the example form provided by the event into a new page. After doing that, you should be ready to send your first enquiry email.

Conclusion

Hopefully it's now clear how the extension works and how to make the most of it. I'm sure you've got questions, since there are things that I've deliberately left out, due to a lack of time, but I hope I've written enough to make you sense of things.

That's all for now, if you have any comments, leave them on the forum.