Helpers

Inkcite’s Helpers dramatically simplify coding emails by:

Eliminate duplicate code that leads to rendering problems and #EmailMistakes
Make your code easier to read and maintain
Allow you to change once, change everywhere (no more search and replace)
Standardize elements within emails and across campaigns

Inkcite offers a variety of built-in Helpers for working with tables, images, links, fonts and lots more. In addition, it is quick and easy to create your own custom Helpers for components you use frequently in your email campaigns.

Helpers look like HTML tags except that they’re wrapped in curly brackets ({ and }) rather than greater-than and less-than symbols. Here’s an example of a bulletproof button.

{button id="order-now" href="http://mystore.com"}ORDER NOW{/button}

Refer to the documentation under Helpers for details on all of Inkcite’s built-in functionality to make email development easier.

Inkcite also makes it extremely easy for you to define your own custom variables and reusable code blocks.

Variables

The simplest Helper is a value you declare and give a readable name. For example, you might define a frequently-used column width or your primary call- to-action color. If you need to change the value, you can update it in one spot and it updates everywhere it is referenced.

Custom variable helpers are defined in the appropriately-named helpers.tsv file in the root of your Inkcite project. For example:

green	#009900
blue	#3366cc

Note! There are tabs between the color names and their corresponding hex values.

Once defined, you can use {green} and {blue} repeatedly in your email’s code like this:

<h2 color="{blue}">Now in stock!</h2>
<div style="color: {green}">from $134.99</div>

When you view your email using Inkcite’s server, send a preview or build the final assets, Inkcite will automatically insert the values that correspond to those tags. If your client changes their mind and wants a different color combination in your email, simply update your helpers.tsv file and all usages automatically update.

Code Blocks

Helpers aren’t limited to individual values. They can also be used to simplify your email by replacing repeated chunks of code. For example, it’s common to repeat your call-to-action multiple times in an email. Here’s an example where with a styled “Buy Now!” link appears multiple times in the email:

<a href="http://ourstie.org/buy-now/" style="bgcolor: #3366cc; color: #ffffff; display: block; padding: 5px; border-radius: 4px;">BUY NOW</a>

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed in urna
sodales tortor sollicitudin ullamcorper...

<a href="http://oursite.org/buy-now/" style="bgcolor: #3355cc; color: #ffffff; display: block; border-radius: 4px; padding: 6px;">BUY NOW!</a>

Oops! When you repeat code, you run the risk of making inadvertent mistakes. In this (admittedly contrived) example, the links have subtly different background colors and padding. One button’s label includes an exclamation point, the other contains a typo in the URL. The order of the style is different making it difficult to globally search-and-replace.

Reducing or removing duplicate code leads to less errors and makes your emails easier to maintain. Let’s define a {call-to-action} Helper like this:

call-to-action	<a href="http://oursite.org/buy-now/" style="bgcolor: #3366cc; color: #ffffff; display: block; border-radius: 4px; padding: 6px;">BUY NOW!</a>

Note! There is a tab between call-to-action and its corresponding HTML code.

Oops! This code still repeats itself. That #3366cc background color looks familiar. Helpers can reference other Helpers so we can include {blue} here:

call-to-action  <a href="http://oursite.org/buy-now/" style="bgcolor: {blue}; color: #ffffff; display: block; border-radius: 4px; padding: 6px;">BUY NOW!</a>

By replacing the duplicate HTML in email.html with the {call-to-action} helper, our email’s becomes a lot cleaner, simpler.

{call-to-action}

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed in urna
sodales tortor sollicitudin ullamcorper...

{call-to-action}

Custom Tags

The most powerful type of Helper is one that represents a custom tag. Custom tags allow you to detangle your content from your code and give you the power to define your own readable, reusable custom HTML-like tags.

<h2>30% Off Today's Bestsellers</h2>

Using header tags in your email can be problematic and often requires using CSS resets and overly complex styles that compete with email client defaults. Instead, let’s declare our own custom heading using a styled <div> with a second <div> used for consistent spacing afterwards.

<div style="font-size: 15px; font-weight: bold; color: {green}; border-bottom: 1px solid {green}; text-align: center;">
   ...
</div>
<div style="height: 8px; line-height: 8px; font-size: 8px;">&nbsp;</div>

This HTML should be saved to your project as helper/h2.html. Any HTML file saved in the `helper/’ directory is treated as a custom tag Helper. The name of the file, sans extension, corresponds to the custom tag you can now use in your email source.

In this case, you can now use {h2} and {/h2} tags to style your headings:

{h2}30% Off Today's Bestsellers{/h2}

Pay particular attention to the ... in the custom H2 code. That tells Inkcite where to put the content you specify between the open and close tags. In the previous example, when Inkcite renders the Helper, it would replace the ... with “30% Off Today’s Bestsellers”

Named Attributes

Removing duplicate code simplifies your email and makes it easier to maintain. Inevitably, however, you’re going to encounter a situation where an existing Helper meets almost all of your needs, but maybe requires a different color, more padding or some other attribute. That’s where named attributes come in.

Inkcite Helpers can be declared to accept attributes just like a regular HTML tag - e.g. the href attribute of an <a> tag. In this example, we’ll extract the vertical spacer we previously declared in our {h2} Helper and make it a standalone tag we can use throughout our email.

Here’s the code saved in helpers/vertical-space.html

<div style="height: 8px; line-height: 8px; font-size: 8px;">&nbsp;</div>

There are lots of uses for consistent cross-client vertical spacing - but you don’t necessarily want it hard-coded to 8px. It would be really useful if you could, instead, specify a height attribute whenever you use the {vertical-space} Helper. Here’s an example of how that might look:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed in urna
sodales tortor sollicitudin ullamcorper...

{vertical-space height=15}

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed in urna
sodales tortor sollicitudin ullamcorper...

Named attributes can be added to a Helper’s declaration by adding the variable name with $ around it. Here’s how we would make height an attribute for the {vertical-space} helper:

<div style="height: $height$px; line-height: $height$px; font-size: $height$px;">&nbsp;</div>

We’ve replaced the hard-coded 8 with $height$ and made this Helper significantly more flexible. As you can see, a named variable can be used anywhere inside of a helper’s declaration and can appear multiple times. When Inkcite renders this Helper in your email, it replaces every instance of $height$ with the value passed-in.

Frontmatter

Named attributes make Helpers extremely flexible. In the spirit of keeping your email code DRY, however, sometimes you don’t want to specify a value repeatedly. You can define default values for named variables using frontmatter.

Frontmatter is tab-delimited (just like helpers.tsv) name and value pairs at the top of your Helper file and enclosed in ---. The values defined within frontmatter are local to the Helper when it is rendered.

Here’s an example:

---
height	15
---
<div style="height: $height$px; line-height: $height$px; font-size: $height$px;">&nbsp;</div>

The frontmatter for this Helper indicates there is a height attribute that defaults to 15 but can be overriden by passing it in as an attribute when you use the vertical spacer.

Circling back to our {h2} Helper declaration, let’s add some frontmatter of its own and use the new {vertical-spacer} Helper to eliminate duplicate code.

---
color	{green}
---
<div style="font-size: 15px; font-weight: bold; color: $color$; border-bottom: 1px solid $color; text-align: center;">
   ...
</div>
{vertical-space height=8}

This updated Helper defaults to the globally-defined green color but now can be customized in specific cases by passing in the color attribute like this:

{h2 color=#ff0000}Needed a Red Header Here{/h2}

Putting it all Together

Here’s a complete example that puts all of this we’ve talked about into action. One of the newsletters we designed included a Featured Story section. Each story in this section included an image, a link to the story and a brief blurb about the article to entire the reader to click. It uses a combination of custom and built-in Helpers.

---
bgcolor	#004f7c
width	200
---
{a id="$id$" href="$href$"}
  {img src=$id$.jpg height=215 width=$width$ alt="$title$" bgcolor=$bgcolor$ mobile="fill"}
{/a}{table bgcolor=$bgcolor$ padding={padding} width=$width$ mobile="fill"}
  {td font=default}
    {a id="$id$" color={#text}}
      {h2}$title${/h2}
      ...
    {/a}
    {vertical-space height=10}
  {/td}
{/table}

This dramatically simplified the content inside of source.html. Each featured story required very little markup. Drop an image (in this case holiday.jpg) named to match the provided id value into the images folder, include the blurb between the tags.

{featured-story id="holiday" href="http://website.com" title="Holiday Concert"}
   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed in urna
   sodales tortor sollicitudin ullamcorper.
{/featured-story}

Documentation

Helpers

Helpers

Variables

Code Blocks

Custom Tags

Named Attributes

Frontmatter

Putting it all Together