Using a Macro to Build a Dynamic Button Component

February 22, 2018

Jinja macros are similar to functions in programming languages. They abstract a block of commonly used code and can be set up to accept modifications when called. In this guide we'll create a macro for a button that supports variables for text, color, and a URL. This way we can create a dynamic button component that can be customized to meet our needs each time it's called.

Starting Button HTML

Below is a button element in HTML. Copy and paste the code into the Dyspatch editor if you would like to follow along and create your own button macro.

<div>
  <!--[if mso]>
    <v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" href="http://" style="height:53px;v-text-anchor:middle;width:150px;" arcsize="48%" stroke="f" fillcolor="#49a9ce">
      <w:anchorlock/>
      <center>
  <![endif]-->
  <a href="http://"
style="background-color:#49a9ce;border-radius:25px;color:#ffffff;display:inline-block;font-family:sans-serif;font-size:13px;font-weight:bold;line-height:53px;text-align:center;text-decoration:none;width:150px;-webkit-text-size-adjust:none;">
    Login
  </a>
  <!--[if mso]>
      </center>
    </v:roundrect>
  <![endif]-->
</div>

This button HTML was created with buttons.cm, a useful tool for creating 'bulletproof email buttons' that will look and work the same across email clients.

The [if mso] blocks in the above example help the button render properly in Microsoft Office email clients. Testing Microsoft email clients with Dyspatch Previewing is recommended, as they often require additional or specialized code to render.

Rendered result:
A login button

Making an HTML Button into a Macro

Wrap the button HTML in macro tags {% macro %} and {% endmacro %}. Inside the opening tag we'll add a name and define the values the macro will accept by adding 'parameters'.

Macro Opening Tag: {% macro button(text, url, color='#49a9ce') %}

After macro is the macro's name, then the parameters inside the parentheses. In this example the macro is named button. The parameters are named text, url, and color. The macro and parameters can be named anything you'd like. We recommend using descriptive names to help you and your team recognize them in the future.

Parameters: Positional and Keyword Arguments

There are two types of parameters you can use when setting up your macro.

Keyword Arguments or 'kwargs'

Use keyword arguments when you want to set a default value. We are using color='#49a9ce' to make our button default to blue when no color value is passed in.

A keyword argument in our macro:

  • color='#49a9ce'

Positional Arguments

If you plan on always passing in a value to a parameter then a positional argument is all you need.

Positional arguments in our macro:

  • text
  • url
{% macro button(text, url, color='#49a9ce') %}
  <div>
    <!--[if mso]>
      <v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" href="http://" style="height:53px;v-text-anchor:middle;width:150px;" arcsize="48%" stroke="f" fillcolor="#49a9ce">
        <w:anchorlock/>
        <center>
    <![endif]-->
    <a href="http://"
  style="background-color:#49a9ce;border-radius:25px;color:#ffffff;display:inline-block;font-family:sans-serif;font-size:13px;font-weight:bold;line-height:53px;text-align:center;text-decoration:none;width:150px;-webkit-text-size-adjust:none;">
      Login
    </a>
    <!--[if mso]>
        </center>
      </v:roundrect>
    <![endif]-->
  </div>
{% endmacro %}

Add the Macro Variables

The button's text, URL, and color still need to be changed into variables to complete the macro. These variables are linked to the parameters we set in the opening tag. They share the same name and act as placeholders for the values we will pass into the macro when calling it.

{% macro button(text, url, color='#49a9ce') %}
  <div>
    <!--[if mso]>
      <v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" href="{{ url }}" style="height:53px;v-text-anchor:middle;width:150px;" arcsize="48%" stroke="f" fillcolor="{{ color }}">
        <w:anchorlock/>
        <center>
    <![endif]-->
    <a href="{{ url }}"
  style="background-color:{{ color }};border-radius:25px;color:#ffffff;display:inline-block;font-family:sans-serif;font-size:13px;font-weight:bold;line-height:53px;text-align:center;text-decoration:none;width:150px;-webkit-text-size-adjust:none;">
      {{ text }}
    </a>
    <!--[if mso]>
        </center>
      </v:roundrect>
    <![endif]-->
  </div>
{% endmacro %}
Note that we've added the variables {{ color }} and {{ url }} into the [if mso] blocks as well

Rendered result:

There isn't one yet! We need to call the macro to get the button to render now.

Call the Macro

At this point the button element is now a macro. Use the macro's name and then pass the desired button text, color, and URL inside the parentheses to call it.

{{ button('we made a macro!', 'https://www.example.site', color="#e91e63") }} 

Rendered result:
A rendered macro button

Create a Macro Library with a Snippet

You can store your macros in a snippet to use them across templates. This way you can centralize your macro code and build a macro component library to simplify your templates. Read more about creating snippets here: Introduction to Snippets

Let's place the button macro we created into a snippet named "macro-library". We now only need two lines of code to use our button in any template, one to call the snippet and another to call the button macro.

{% snippet 'macros-library' %}

{{ button('A macro in a snippet', 'https://www.example.site', color="#e91e63") }}

Further Reading

Didn't find what you're looking for?

Ask our support team, we're here to help!

Contact Support