Custom Tags

Maizzle includes some special tags designed to help you with templating logic.

Conditionals

You can use if/elseif/else conditionals in your email templates.

For example, the Starter uses it to output a preheader in its Layout:

src/templates/example.html

<if condition="page.preheader">
  <div class="hidden">{{ page.preheader }}</div>
</if>

Of course, you can create more complex conditions:

src/templates/example.html

<if condition="page.env === 'node'">
  <p>Using Maizzle programmatically</p>
</if>
<elseif condition="page.env === 'production'">
  <p>We are in production!</p>
</elseif>
<else>
  <p>We are probably developing locally.</p>
</else>

Custom conditionals tag

You may customize the conditional tag names:

config.js

module.exports = {
  build: {
    posthtml: {
      expressions: {
        conditionalTags: ['when', 'ifnotthen', 'otherwise']
      }
    }
  }
}

Example:

src/templates/example.html

<when condition="page.env === 'node'">
  <p>Using Maizzle programmatically</p>
</when>
<ifnotthen condition="page.env === 'production'">
  <p>We are in production!</p>
</ifnotthen>
<otherwise>
  <p>We are probably developing locally.</p>
</otherwise>

Outlook

Wrap content with MSO conditional comments so that it will only show up in Outlook 2007-2019 on Windows:

src/templates/example.html

<outlook>
  <div>Show this in all Outlook versions</div>
</outlook>

That will output:

<!--[if mso|ie]>
  <div>Show this in all Outlook versions</div>
<![endif]-->

Of course, there's also a tag for showing content everywhere except in Outlook:

src/templates/example.html

<not-outlook>
  <div>All Outlooks will ignore this</div>
</not-outlook>

Result:

<!--[if !mso]><!-->
  <div>All Outlooks will ignore this</div>
<!--<![endif]-->

The <outlook> tag supports various combinations of attributes that will help with showing or hiding content in specific Outlook versions:

only - show only in these Outlook versions
not - show in all versions except these
lt - all versions before this (not including it, i.e. lower than)
lte - all versions before this (including it, i.e. lower than or equal to)
gt - all versions after this (not including it, i.e. greater than)
gte - all versions after this (including it, i.e. greater than or equal to)

For example:

src/templates/example.html

<outlook only="2013">
  <div>Show only in Outlook 2013</div>
</outlook>

Result:

<!--[if mso 15]>
  <div>Show only in Outlook 2013</div>
<![endif]-->

The only and not attributes support multiple values, separated with a comma:

src/templates/example.html

<outlook only="2013,2016">
  <div>Show only in Outlook 2013 and 2016</div>
</outlook>

Result:

<!--[if (mso 15)|(mso 16)]>
  <div>Show only in Outlook 2013 and 2016</div>
<![endif]-->

You may also combine attributes:

src/templates/example.html

<outlook gt="2003" lte="2013">
  <div>Show in 2007, 2010, 2013</div>
</outlook>

Result:

<!--[if (gt mso 11)&(lte mso 15)]>
  <div>Show in 2007, 2010, 2013</div>
<![endif]-->

Custom Outlook tag

Of course, you may customize the <outlook> tag name:

config.js

module.exports = {
  build: {
    posthtml: {
      outlook: {
        tag: 'mso'
      }
    }
  }
}

You'd then use it like this:

src/templates/example.html

<mso only="2013">Show only in Outlook 2013</mso>
<not-mso>Hide from all Outlooks</not-mso>

Switch

Need to use a switch statement?

src/templates/example.html

<switch expression="page.user.subscription">
  <case n="'monthly'">
    <p>Your monthly subscription is about to renew.</p>
  </case>
  <case n="'yearly'">
    <p>Heads up! Yearly renewal coming soon, make sure you have enough money in your account.</p>
  </case>
  <default>
    <p>Your subscription will soon renew.</p>
  </default>
</switch>

Custom switch tag

You may define custom tags for the switch statement:

config.js

module.exports = {
  build: {
    posthtml: {
      expressions: {
        switchTags: ['handle', 'when', 'fallback']
      }
    }
  }
}

Example:

src/templates/example.html

<handle expression="page.env">
  <when n="'production'">
    production
  </when>
  <fallback>
    fallback content
  </fallback>
</handle>

Loops

You can iterate over arrays and objects with the <each> tag.

For arrays:

src/templates/example.html

<each loop="item, index in someArray">
  <p>{{ index }}: {{ item }}</p>
</each>

For objects:

src/templates/example.html

<each loop="value, key in anObject">
  <p>{{ key }}: {{ value }}</p>
</each>

Loop meta

Inside a loop you will have access to a {{ loop }} object that contains information about the loop currently being executed:

loop.index - the current iteration of the loop (0 indexed)
loop.remaining - number of iterations until the end (0 indexed)
loop.first - boolean indicating if it's the first iteration
loop.last - boolean indicating if it's the last iteration
loop.length - total number of items

Example:

src/templates/example.html

<each loop="item, index in [1,2,3]">
  <p>Number of iterations until the end: {{ loop.remaining }}</p>
</each>

Custom loop tag

You may customize the name of the loop tag:

config.js

module.exports = {
  build: {
    posthtml: {
      expressions: {
        loopTags: ['for']
      }
    }
  }
}

You can now use a <for> tag instead:

src/templates/example.html

<for loop="item, index in [1,2,3]">
  <p>{{ item }}</p>
</for>

Scope

Use <scope> tags to provide a data context to the content inside.

Imagine we had this data in our config.js:

config.js

module.exports = {
  roles: {
    author: { name: 'John' },
    editor: { name: 'Jane' },
  }
}

We could provide each object as a scope, so we can then access it from the context, instead of going up to the parent:

src/templates/example.html

<!-- Will output 'John', no need to write {{ page.roles.author.name }} -->
<scope with="page.roles.author">
  {{ name }}
</scope>

<!-- Will output 'Jane' -->
<scope with="page.roles.editor">
  {{ name }}
</scope>

Custom scope tag

You may customize the <scope> tag name:

config.js

module.exports = {
  build: {
    posthtml: {
      expressions: {
        scopeTags: ['context']
      }
    }
  }
}

Example:

src/templates/example.html

<!-- Will output 'Jane' -->
<context with="page.roles.editor">
  {{ name }}
</context>

Fetch

You can fetch and display remote content in your email templates:

src/templates/example.html

<fetch url="https://jsonplaceholder.typicode.com/users">
  <each loop="user in response">
    {{ user.name }}
  </each>
</fetch>

Inside the <fetch> tag, you have access to a {{ response }} variable.

Fetch options

You may use the fetch key to customize options:

config.js

module.exports = {
  build: {
    posthtml: {
      fetch: {
        tags: ['get'], // default ['fetch', 'remote']
        attribute: 'resource', // default 'url'
        got: {}, // pass options to the `got` package
        preserveTag: true, // default false
        expressions: {}, // configure expressions in fetch context
      }
    }
  }
}

Raw

Need to skip tag and expressions parsing in a whole block?

src/templates/example.html

<raw>
  This will not be parsed:
  <if condition="page.env">
    {{ page.env }}
  </if>
  Neither will this expression: {{ page.env }}
</raw>

Result:

build_production/example.html

This will not be parsed:
<if condition="page.env">
  {{ page.env }}
</if>
Neither will this expression: {{ page.env }}

Custom raw tag

The <raw> tag name may be customized:

config.js

module.exports = {
  build: {
    posthtml: {
      expressions: {
        ignoredTag: 'verbatim'
      }
    }
  }
}

Example:

src/templates/example.html

<verbatim>
  This will not be parsed: {{ page.env }}
</verbatim>