This guide is meant to be read by everyone who would like to use the template features in Dada Mail's email messages.
Templating in email messages works, because email messages have things called, tags, which are placeholders for other information.
A tag looks like this:
<!-- tmpl_var tag -->
A tag will start with,
<!-- tmpl_var , will have a some text and then,
-->. Before an email message is sent out, the email
message is first parsed and these placeholder tags are replaced with what they represent.
Not all tags will represent everything - for example, you can't just have a tag that says:
<!-- tmpl_var Current_President_Of_The_United_States -->
and expect Dada Mail to figure out what you want.
There's basically three different groups of tags that you can be sure are always available to you.
These tags can be used in most every email message. This list isn't exhaustive, but should give you a good start
The name of this program - usually it's set to, Dada Mail
The URL to Dada Mail, ie: http://example.com/cgi-bin/dada/mail.cgi
Dada Mail includes a few tags to dynamically put the current data in your email message. They'll take on the form:
<!-- tmpl_var date.x -->
x is a specific variable, which we'll explain below.
For example, if the current date is: Monday, October 15th, 2011 at 2:55 PM, the following tags would return:
Will print out the month. For "October", this would print out,
Will return the month, padded with a, "0" if the value is less than "0". For October, it would look the same as,
But, for something like January, it'll look like this:
Will print out the name of the month. For October, this would print out,
Will print out the name of the month, in an abbreviated form. For October, this would print out,
Will print the day of the month. For, "October 17th", this would print out:
Will print the day of the month, with the correct ordinal suffix. For, "October 17th", this would print out:
Will print the day of the month, padded for values less than, "10". For the 17th, this would print out,
But for October 1st, this would print out:
Will print out the day of the week. For, "Monday, October 15th", this would print out,
Will print out the day of the week, in an abbreviated form. For, "Monday", this would print out,
Will print out the current year. For example:
Will print out the abbreviated year (last two digits). For example 2011, will be printed out as:
Will print out the, "Unix Time" For example:
Will print out the current date and time in a format like this:
Mon Oct 17 14:55:39 2011
Will print out the time (hour:minute:second) in 24 hour time. So, if it's 4:33 PM, this will be printed out as:
You can then use these different tags to create different date formats.
<!-- tmpl_var date.day --> <!-- tmpl_var date.named_month --> <!-- tmpl_var date.year -->
<!-- tmpl_var date.day -->/<!-- tmpl_var date.month -->/<!-- tmpl_var date.year -->
<!-- tmpl_var date.year -->-<!-- tmpl_var date.padded_month -->-<!-- tmpl_var date.padded_day -->
<!-- tmpl_var date.year -->-<!-- tmpl_var date.abbr_named_month -->-<!-- tmpl_var date.day -->, <!-- tmpl_var date.day_of_the_week -->
<!-- tmpl_var date.day_of_the_week -->, <!-- tmpl_var date.named_month --> <!-- tmpl_var date.day -->, <!-- tmpl_var date.year -->
<!-- tmpl_var date.padded_month -->/<!-- tmpl_var date.padded_day -->/<!-- tmpl_var date.abbr_year -->
If the included simple date tags are not enough, Dada Mail has support for
The formatting is documented at:
If you're familiar with PHP's time formatting:
it's the same thing.
To use this in Dada Mail's templating syntax, use the
<!-- tmpl_strftime --> tag, like this:
<!-- tmpl_strftime %a, %d %b %Y -->
This will print out,
Mon, 17 Oct 2011
Your list has a whole slew of attributes that make up its behavior. Most of the these attributes can be used as tags in your email messages.
You'll know you're working with a list-specific attribute, as the tag will start out with:
<!-- tmpl_var list_settings.
Notice the dot,
. at the end.
The tag will then be proceeded with the attribute you want to use and end with,
For example, if you want to have a tag to show the List's Name, you'd write:
<!-- tmpl_var list_settings.list_name -->
To have a tag to show the list ower's email address, you'd write:
<!-- tmpl_var list_settings.list_owner_email -->
Here's a non-exhaustive list of available list-specific tags:
Your list's shortname
Your list's name
The List Owner's email address
The description of your list
Your list's physical address
Information about whom you are emailing to is also available to you.
This concept is somewhat tricky, so explanation is necessary.
We're going to use the term, subscriber in this case to describe the person we're emailing to, in the email message we're working on here.
For example, if we're sending a confirmation email message, our subscriber will be the address that we're current emailing to, even though they haven't yet subscribed.
Similar to the List-Specific Tags, Subscriber-Specific tags also have a way to let you know you're working with a subscriber-specific
attribute. Tags that deal with subscriber information start with:
<!-- tmpl_var subscriber. and are proceeded with the attribute we want to use.
For example, to use a subscriber's email address, you would use:
<!-- tmpl_var subscriber.email -->
A few subscriber-specific tags are usually always available to you. In these examples we'll use the email address,
firstname.lastname@example.org as the subscriber email address. The subscriber-specific tags are:
A very special case happens with email messages that are sent for email subscription confirmations, email unsubscriotion confirmations and List Invitations
In these email messages you also have the option to use the,
<!-- tmpl_var subscriber.pin --> tag. This tag holds the pin number used to subscribe and unsubscribe an email subscriber.
You can also access the subscriber's saved field values. For example, if you have a field named, first_name, you can use the following tag:
<!-- tmpl_var subscriber.first_name -->
Once you understand how these tags are made, it's simple to use them in your message. For example, we can great our subscriber as such:
Hello, <!-- tmpl_var subscriber.email --> You are subscribed to my list, <!-- tmpl_var list_settings.list_name -->.
-- <!-- tmpl_var list_settings.list_owner_email -->
This will print out something like:
Hello, email@example.com You are subscribed to my list, My Awesome List. Hazzah! -- firstname.lastname@example.org
And that's all there is to it.
If you have a subcriber field named, first_name, we can change the example above to:
Hello, <!-- tmpl_var subscriber.first_name --> You are subscribed to my list, <!-- tmpl_var list_settings.list_name -->. Hazzah! -- <!-- tmpl_var list_settings.list_owner_email --> This could print out something like: Hello, John, You are subscribed to my list, My Awesome List. Hazzah! -- email@example.com
Alongside tags that represent something, there's also tags that allow you to loop through all the information available.
Currently, you can loop through all the subscriber and list specific information, using the,
>!-- tmpl_loop --< tag, like so:
<!-- tmpl_loop subscriber --> <!-- tmpl_var name -->: <!-- tmpl_var value --> <!-- /tmpl_loop -->
This will print out every attribute that's associated with the current email address.
Similarily, you can do this with the List Attributes:
<!-- tmpl_loop list_settings --> <!-- tmpl_var name -->: <!-- tmpl_var value --> <!-- /tmpl_loop -->
Under the hood, Dada Mail's email templating system is powered by HTML::Template. Everything that can be done with it, can probably be done with Dada Mail.
Here's more information:
loop statements don't have enough horesepower for you, Dada Mail does support the use of
HTML::Template::Expr type expressions.
To enable, log into your list control panel and under, Manage Copy -> Email Templates, you should see an option, under, Advanced Options titled,
Use the advanced templating syntax for email messages.
You'll want to enable this option and HTML::Template::Expr syntax should be enabled.
With this option enabled, you can make statements, such as this:
Hello <!-- tmpl_var subscriber.first_name -->, <!-- tmpl_if expr="subscriber.favorite_fruit eq 'apples'" --> I see you like apples! <!-- tmpl_else --> You don't like apples?! <!-- /tmpl_if -->
This will print:
Hello John, I see you like apples!
If your subscriber has the field value, "first_name" set to, "John" and the, "favorite_fruit" set to, "Apples". If favorite fruit is set to something other than apples, this would be printed:
Hello John, You don't like apples?!
Prior to Dada Mail 4, template tags and templates themselves used the old-style format.
Old-style template tags look like this:
They were simply just a string, surrounded by square brackets.
We'd like to move away from that, so that syntax is now, deprecated. These types of tags still work, 100%. If you're upgrading, you shouldn't find any problems, yet, but please do not use the old-style tags in any feature templating you do.