Getting started with Email Template Filters

Why not use “Send Email?”

The Email Template Filter extension gives you 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.

Clients demand crazy things

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:

1. Allows their potential clients or existing members to contact them
2. Is sent to a different address depending on the visitors choice
3. 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 the damned

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:

1. 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
2. The other parameter that we’re filtering with, $entry-id, is created in the next step
3. 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.

And finally…

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.

Thoughts and feedback

newnomad 9 July 2009

Your extension uses the build in symphony/lib/toolkit/events/event.section.php for sending email? So this mean in order to sent MIME (for an attachment or html) the file in the toolkit needs to be modified, it cannot be done through an extension?

Rowan Lewis 13 July 2009

newnomad, you can’t really add file attachments to the emails unfortunately, however you could include a link in the email to download whatever it is you want to send.

Also, all emails are sent as HTML emails.

Matthew Pietz 8 August 2009

Rowan, this is awesome. Thanks for making this. One question, does it support an event with `Allow multiple` selected?

Andrew Minton 24 November 2009

Rowan, Is it possible to have a text only fallback to these html emails? or does the extension do this anyway.. i.e mail client side interprets it..

Is the sending of message body sorted for S2 at all?

Andrew Minton 24 November 2009

Also Rowan,

I am thick, and I know it, but is there an example html page so I can see how the data is being populated from the DS?

There was no example above and it’s the missing link for me.. taking the field data from the event and placing it in a HTML format/xsl template.