The Dada Mail 3.0 Email Template Syntax

- The Dada Mail Email Template Syntax
- Audience
- The Basics

- Tags

- Built-in Tags

- Global Tags
- List-Specific Tags
- Subscriber-Specific Tags

- Using Tags in Email Messages

- Looping

- Advanced Templating Syntax

- HTML::Template::Expr Support

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

For extremely nerdy and technical stuff, do see... other nerdy and technical documentation.

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

     [tag]

A tag will start with a left bracket, will have a some text and then a right bracket. 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:

     [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

- [PROGRAM_NAME]

  The name of this program - usually it's set to, Dada Mail

- [PROGRAM_URL]

  The URL to Dada Mail, ie: http://example.com/cgi-bin/dada/mail.cgi

#### 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: `[list_settings.`. Notice the dot, . at the end.

The tag will then be proceeded with the attribute you want to use.

For example, if you want to have a tag to show the List's Name, you'd write:

     [list_settings.list_name]

To have a tag to show the list ower's email address, you'd write:

     [list_settings.list_owner_email]

Here's a non-exhaustive list of available list-specific tags:

- [list_settings.list]

  Your list's shortname

- [list_settings.list_name]

  Your list's name

- [list_settings.list_owner_email]

  The List Owner's email address

- [list_settings.info]

  The description of your list

- [list_settings.privacy_policy]

  Your list's Privacy Policy

- [list_settings.physical_address]

  Your list's physical address

#### 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: `[subscriber.` and are proceeded with the attribute we want to use.

For example, to use a subscriber's email address, you would use:

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

- [subscriber.email]

  user@example.com

- [subscriber.email_name]

  user

- [subscriber.email_domain]

  example.com

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, `[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:

     [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, [subscriber.email]

     You are subscribed to my list, [list_settings.list_name].

     Hazzah!

     -- [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, first_name, we can change the example above to:

     Hello, [subscriber.first_name]

     You are subscribed to my list, [list_settings.list_name].

     Hazzah!

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

## 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, `[loop]` tag, like so:

     [loop subscriber]
            [name]: [value]
     [/loop]

This will print out every attribute that's associated with the current email address.

Similarily, you can do this with the List Attributes:

     [loop list_settings]
            [name]: [value]
     [/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

You'll notice that the examples above use this sort of syntax for the template tags:

     [ima_tag]

instead of the HTML::Template way of doing things:

     <!-- tmpl_var ima_tag -->

Both will work with Dada Mail's email templating system and neither is really preferable. Dada Mail's syntax is simply filter to HTML::Template's syntax by HTML::Template itself.

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

To enable, log into your list control panel and under, Manage Copy -&gt; 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 [subscriber.first_name],

     [if expr="subscriber.favorite_fruit eq 'apples'"]
     I see you like apples!
     [else]
     You don't like apples?!
     [/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?!

You may find that it's easier to use the default HTML::Template::Expr style of tags, when dealing with the advanced syntax. The following should be equivilent to the above:

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