Email Template Syntax

The Dada Mail Email Template Syntax

Audience

This guide is meant to be read by everyone who would like to use the template features in Dada Mail's email messages.

The Basics

Tags

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.

Built-in Tags

There's basically three different groups of tags that you can be sure are always available to you.

Global Tags

These tags can be used in most every email message. This list isn't exhaustive, but should give you a good start

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 -->

Where, 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:

You can then use these different tags to create different date formats.

Little endian forms

Big endian forms

Middle endian forms

Flexible Date and Time formats

If the included simple date tags are not enough, Dada Mail has support for strftime formatting.

The formatting is documented at:

http://www.unix.com/man-page/FreeBSD/3/strftime/

If you're familiar with PHP's time formatting:

http://php.net/manual/en/function.strftime.php

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

List-Specific Tags

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:

Subscriber-Specific Tags

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, user@example.com as the subscriber email address. The subscriber-specific tags are:

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 -->

Using Tags in Email Messages

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 -->. 

        Hazzah!

        -- <!-- tmpl_var list_settings.list_owner_email -->

        This will print out something like: 

        Hello, user@example.com

        You are subscribed to my list, My Awesome List. 

        Hazzah!

        -- listowner@example.com

        And that's all there is to it. 

        If you have a subcriber field named, B<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!

        -- listowner@example.com

Original Sender Tags

If you use Bridge to send out your messages, you can use the, sender tags within the mass mailing layout or in the message itself to pull in information about them. Similar to the, subscriber tags, you can use the sender tags. You'll see this implemented in the discussion list-specific mass mailing layout that ships with Dada Mail:

        <!-- tmpl_unless list_settings.disable_discussion_sending -->
         <!-- tmpl_if list_settings.bridge_mention_original_sender -->
 
             From: <!-- tmpl_var sender.email -->
 
         <!-- /tmpl_if -->
        <!-- /tmpl_unless -->

In the above template code, we see if Bridge is enabled, and if this byline should be printed. If so, we print the sender's email address using the tag,

        <!-- tmpl_var sender.email -->

Looping

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 -->

Advanced Templating Syntax

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:

http://search.cpan.org/~samtregar/HTML-Template/Template.pm

HTML::Template::Expr Support

If simple if and loop statements don't have enough horesepower for you, Dada Mail does support the use of HTML::Template::Expr type expressions.

More information:

http://search.cpan.org/~samtregar/HTML-Template-Expr/Expr.pm

Here's an example of using these expressions:

        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?!

Dada Mail Project

Download

Installation

Support