Dec 20, 2010

Working with Variant Selectors

One of the exciting features we’ve introduced alongside the release of these templates is the Variant Selector. What this new feature does is actually pretty simple: it lets you switch between any number of different content structures (blocks of HTML) within your email. So, the explanation is straightforward, but if you’re a designer the practical implications of this feature are actually pretty huge.

First, let’s take a look at the new Basic Variable template:


The layout is deceptively simple, with a big upper content area and a lower area with a left-side image and right-side text. Hover over that lower area, however, and you’ll see that it’s repeatable and has a new control attached to it – that’s the Variant Selector.

This template has a left-image module and a right-image module that can be selected via the drop-down menu, then repeated and selected again. In this particular template, this allows you to create a "ping-pong" layout, where each image-and-text module mirrors the previous.

This is a neat use, and ultimately a pretty simple one, but like a lot of our features there’s quite a bit of power in that simplicity. An interesting use case for this? Maybe you’re an agency, or a freelance web designer building templates for others, and you find that your client wants to switch between two different templates each month, alternating the layout of the email they use to send your campaign content. By using the Variant Selector code, you can combine the two template layouts into one, then your client just selects which layout they’d like to send out. After that, they can continue on as if it’s a normal template. Easy for them, which is great, and a little less work for you to achieve your client’s goal.

So that’s the basic stuff covered. Let’s get our hands dirty with the code that lets this feature work. Those uncomfortable with HTML should look away… now.

First, here’s the unadulterated code for each of the modules in the Basic Variable template:

<!-- // Begin Module: Left Image with Content \\ -->
<table border="0" cellpadding="20" cellspacing="0" width="100%"
mc:repeatable="siwc_600" mc:variant="content with left image">
    <tr>
        <td align="center" valign="top">
            <img src="http://gallery.mailchimp.com/
      653153ae841fd11de66ad181a/images/placeholder_260.gif"
      style="max-width:250px;" mc:label="image"
      mc:edit="liwc600_image00" />
        </td>
        <td valign="top">
            <div mc:edit="liwc600_content00">
               <h4>Heading 4</h4>
               <strong>Variable content blocks:</strong>
         <a href="http://blog.mailchimp.com/kb/article/how-
         do-i-work-with-repeatable-content-blocks" target="_blank">
         Variable content sections</a> are noted with plus and
         minus signs so that you can add and subtract content blocks
         and also a drop-down selector that allows you to choose which
         type of content block to display.
            </div>
        </td>
    </tr>
</table>
<!-- // End Module: Left Image with Content \\ -->

<!-- // Begin Module: Right Image with Content \\ -->
<table border="0" cellpadding="20" cellspacing="0" width="100%"
mc:repeatable="siwc_600" mc:variant="content with right image">
    <tr>
        <td valign="top">
            <div mc:edit="riwc600_content00">
               <h4>Heading 4</h4>
               <strong>Variable content blocks:</strong>
         <a href="http://blog.mailchimp.com/kb/article/how-
         do-i-work-with-repeatable-content-blocks" target="_blank">
         Variable content sections</a> are noted with plus and
         minus signs so that you can add and subtract content blocks
         and also a drop-down selector that allows you to choose which
         type of content block to display.
            </div>
        </td>
        <td align="center" valign="top">
            <img src="http://gallery.mailchimp.com/
      653153ae841fd11de66ad181a/images/placeholder_260.gif"
      style="max-width:250px;" mc:label="image"
      mc:edit="riwc600_image00" />
        </td>
    </tr>
</table>
<!-- // End Module: Right Image with Content \\ -->

Each module is coded as its own HTML table, and they’re identical save for the order of the table cells that hold the image and text. In the first table’s opening HTML tag, you’ll see two attributes from our template language: mc:repeatable and mc:variant:

mc:repeatable="siwc_600" mc:variant="content with left image"

The mc:repeatable tag is familiar, save for one detail: it’s taking a name (in this case, siwc_600). That’s an important difference between a normal mc:repeatable tag, where no name is required. The app uses this name to track the repeated variant, so it’s very important that the name be included and that it be identical on the two items you want to alternate between.

The next tag is mc:variant, which is brand-new. You’ll see that it’s also taking a name; "content with left image" in the top module, "content with right image" on the bottom one. This tag sets the text that shows on the Variant Selector drop-down menu:

That’s all you need to get the Variant Selector working – the use of those two tags. There’s one more important detail: the tagged objects you wish to toggle between must be adjacent to each other in the template’s HTML. Here’s a simplified example:

<table>
  <tr>
    <td>
      <div mc:repeatable="catsdogsbirdsfish"
      mc:variant="meow meow meow!">
        <h1>Meow!</h1>
        Cats are the best!
      </div>
      <div mc:repeatable="catsdogsbirdsfish"
      mc:variant="woof woof woof!">
        <h1>Woof!</h1>
        Dogs are the best!
      </div>
      <div mc:repeatable="catsdogsbirdsfish"
      mc:variant="tweet tweet tweet!">
        <h1>Tweet!</h1>
        Birds are the best!
      </div>
      <div mc:repeatable="catsdogsbirdsfish"
      mc:variant="glub glub glub!">
        <h1>Glub?</h1>
        I don't know what sounds fish make,
        but they are the best!
      </div>
    </td>
  </tr>
</table>

Since the four divs are adjacent to each other and are correctly tagged up, they’ll be pulled as selectable variants within the app. Just keep in mind that the Variant Selectors you set up in "My Templates" will only be applicable within a campaign, since variants are content-specific tools.You can use the Variant Selectors on pretty much any number of chunks of code: we haven’t placed any limits on the number of variants you can set so, theoretically, you can do this to infinity+1*. That’s a pretty powerful proposition (alliteration bonus!).

*We’d rather you didn’t.