Macros and Includes: Building Reusable Blocks

Three case walkthrough

Case one. A button macro you can drop anywhere

This is the poster child of reuse. Define a macro once, call it wherever you need a call to action. Want to switch class names or add rel attributes later Better to change one file than twenty.

<#-- file: macros/ui.ftl -->
<#macro button label url className="btn primary" rel="nofollow">
  <a href="${url?html}" class="${className?html}" rel="${rel?html}">${label?html}</a>
</#macro>

<#-- usage -->
<#import "/macros/ui.ftl" as ui />

<p>
  <@ui.button label="Get the guide" url="https://example.com/guide" />
</p>

Now the next time marketing wants rounded corners or a different class, you touch one macro.

Case two. Includes for headers and footers with simple switches

Put shared chrome in partials and include them. Add a tiny switch for campaigns or locales. This keeps templates readable while still flexible.

<#-- file: pages/landing.ftl -->
<#if campaign == "fall">
  <#include "/partials/header_fall.ftl" />
<#else>
  <#include "/partials/header.ftl" />
</#if>

<main>
  <h2>Limited offer</h2>
  <p>Save your seat for the webinar.</p>
</main>

<#include "/partials/footer.ftl" />

Includes are boring on purpose. That is the point. One header everywhere. Your QA and your future self will thank you.

Case three. A marketing macro to add tracking without tears

Stop hand typing utm params. Put the logic in a macro and keep your reports clean. This also prevents weird escaping bugs when a title sneaks into a query string.

<#-- file: macros/marketing.ftl -->
<#macro trackedLink url text campaign medium source>
  <#assign u = url + "?utm_campaign=" + campaign?url + "&utm_medium=" + medium?url + "&utm_source=" + source?url />
  <a href="${u}">${text?html}</a>
</#macro>

<#-- usage -->
<#import "/macros/marketing.ftl" as m />

<p>
  <@m.trackedLink
    url="https://example.com/signup"
    text="Sign up"
    campaign="fall"
    medium="email"
    source="newsletter"
/>
</p>

Now the team can change naming for sources in one place and re publish. Clean and safe.

Objections and replies

• I can just copy and paste. You can, but then you will fix five files at two in the morning. Macros and includes cut that cost to one edit.
• Macros are hard to debug. FreeMarker errors point to line numbers inside macros. Keep macros small, and name them clearly. Logging template exceptions in your servlet helps too.
• Includes will slow down the page. FreeMarker caches parsed templates by default. Set template update delay to a sane value in dev and in prod you get fast loads.
• Designers will hate template tags. Agree on a small set of macros with friendly names. Fewer tags in the file than repeated markup blocks makes files easier to read.
• We already have JSP taglibs. Great. Use both. Taglibs for heavy server side work, FreeMarker macros for tidy view snippets.

Action steps you can ship this week

• Create a folder for shared templates, for example /macros and /partials.
• Add a tiny ui.ftl with a button macro and start replacing duplicate buttons.
• Move your header and footer to /partials and include them from pages.
• Add one marketing macro for tracking links, and stop hand writing query params.
• Pick names and conventions. Keep macro names short and human. Add defaults for optional params.
• Turn on template caching and set template update delay in your FreeMarker config in dev and prod.
• Review templates with the team. Mark places that deserve a macro. Aim for fewer tags and cleaner files.

That is it. Reusable blocks with macros and includes make your templates calm. You spend less time fixing the same thing everywhere and more time shipping. If you are juggling Spring MVC or Struts and trying the new IE9 beta in the same day, you want this kind of boring power in your stack.