Creating Handlebars Partials

What Are Partials?

Terminalfour makes partials available across your entire publishing environment, so a partial defined once can be used in layouts for completely different channels, page layouts, or content layouts.

To call a partial, you call it by referencing the partial name in an expression with an angle bracket at the start.

For example

{{> metaTags}}

Why Use Partials?

Without partials, keeping templates consistent across a large site quickly becomes a maintenance burden. If the same HTML structure (e.g. a card component, a meta tag block, a navigation fragment, a footer disclaimer) could appear in a dozen different Content Layouts or Page Layouts. Fixing a bug or updating that structure means editing every layout individually. It's easy to miss one, and inconsistencies creep in over time.

Partials solve this by giving you a single source of truth for any repeated markup:

• Reduce duplication
  • write a piece of template logic once and reuse it everywhere it is needed.
• Easier maintenance
  • update a partial in one place and every layout that uses it immediately benefits from the change at the next publish.
• Cleaner layouts
  • complex layouts become easier to read when large repeated blocks are extracted into named partials, leaving the parent layout focused on its own structure.
• Consistency
  • since all templates draw from the same partial, the output is guaranteed to be identical wherever that fragment appears.

Common candidates for partials include things like: a social media meta tag block, a reusable card or teaser component, schema.org structured data snippets, shared navigation markup, or a standard analytics script include.

Types of Partials

Terminalfour supports partials in a few forms, each suited to a different need:

• Standard partials: a named, reusable fragment stored as a Handlebars Partial content item and called with {{> partialName}}. Available across your whole publishing environment. This is the most common type and is covered first below.
• Partial blocks: a partial used as a wrapper around content, called with {{#> partialName}} ... {{/partialName}}. The wrapped content is rendered wherever the partial outputs {{> @partial-block}}.
• Inline partials: a partial defined directly inside a layout with {{#*inline "name"}} ... {{/inline}}, for reuse within that single layout without registering it globally.

The rest of this guide covers how to define and call standard partials, then how to use partial blocks and inline partials.

Defining Partials

Like Custom Helpers, partials are managed as content items stored inside a dedicated section in your Terminalfour site structure.

A note on the current setup requirements:

Managing Partials today requires navigating to a specific section in your site structure using a section ID retrieved via a SQL query. We recognize this is not an ideal experience: it requires database access and familiarity with Terminalfour's internals that shouldn't be necessary for what is ultimately a templating task.

This is a temporary requirement. A dedicated UI for creating and managing Partials is planned, which will make the process straightforward without any need for SQL or manual section navigation. When that UI ships, all existing partials you have created through the current workflow will automatically appear there. Nothing will need to be migrated or recreated.

In the meantime, the steps below walk you through the current process.

1. Find the Partial Section

First, you'll need to locate the section in your site structure where partials are stored. You can find this by running the following SQL query against your Terminalfour database:

SELECT * FROM config_option WHERE config_key='handlebars.partialsSectionId'

This will return the section ID for the section where Partials should be created and managed. Make a note of the relevant section ID.

If you cannot run SQL against your instance, contact Client Support who can provide you with the Section ID for managing Partials in your instance.

2. Edit the Section

Navigate to the section identified by the query above in Site Structure. To do this, open any section from the Site Structure and update the URL in your browser to reference the Section ID you found step 1.

E.g https://your-instance.terminalfour.net/terminalfour/page/section#edit/<YOUR_SECTION_ID>

3. Create a Content Item

Inside the partials section, create a new content item. Only one Content Type is enabled in this section but if you see an option to select a Content Type, ensure you select the one named "Handlebars Partials".

The content item has two elements:

• Name
  • This becomes the registered name of the partial, and is how you will reference it in your layouts. For example, a name of articleCard means you would call it as {{> articleCard}}. Ensure you use a camelCase naming convention to avoid issues.
• Code
  • The Handlebars and/or markup that makes up the partial's content.

The status of the Content Item defining your Partial is ignored. We recommend saving and approving the content to avoid issues.

Using a Partial in a Layout

Once a partial is defined, calling it in any layout is straightforward:

{{> articleCard}}The > character is Handlebars' syntax for invoking a partial. At publish time, Terminalfour will look up the partial by name and inline its output at that point in the template.

You can call the same partial multiple times within a single layout:

<div class="featured">
  {{> articleCard}}
</div>
<div class="listing">
  {{> articleCard}}
  {{> articleCard}}
  {{> articleCard}}
</div>

Passing Parameters into Partials

Partials are processed in the context in which they are used. That means if you include a helper like {{sectionName}} in your Partial code, it will output a different value depending on where the Partial is used.

By default, a partial inherits the full data context of the layout that calls it. So any variables available in the parent layout are also available inside the partial. This is useful for simple cases, but often you'll want to pass specific values explicitly to make your partial more flexible and self-contained. 

You can pass parameters to a partial using hash arguments directly in the partial call:

{{> articleCard title="Latest News" showImage=true imageUrl=(media id=(mediaId element="Image") layout="path/*") summary=(publish element="Summary") maxWords=80}}Inside the partial, these values are available as regular Handlebars variables:

{{! articleCard partial }}
<div class="card">
  {{#if showImage}}
    <img src="{{imageUrl}}" alt="{{title}}" />
  {{/if}}
  <h3>{{title}}</h3>
  <p>{{truncate summary maxWords}}</p>
</div>

Example:  Output Meta Tags in site header

You likely have several Page Layouts that all output the same or similar meta tags at the top of the page.

With partials, you can manage them in a single place. Changing the partial, changes the meta tag output everywhere.

A partial named standardMetaTags

<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
{{meta id="12" name="description"}}
{{meta id="14" name="keywords"}}

Usage in a layout:

{{> standardMetaTags}}

Partials can process any Handlebars code but T4 Tags will not be processed.

Partial Blocks

Sometimes you want a partial to act as a wrapper around content, rather than just being dropped in on its own. For example, a "card" component that provides a consistent styled container, but where the content inside changes each time you use it.

This is done with a partial block (sometimes referred to as a block-level partial). It's called using {{#> }} syntax (note the # before the >). Whatever markup you place between the opening and closing tags is passed into the partial and rendered wherever the partial outputs {{> @partial-block}}.

Calling a partial block

In your Content Layout or Page Layout you could call the following:

{{#> card title="My Block"}}
  <p>Some content here</p>
{{/callout}}The card partial code

The code to output this partial could look something like:

{{!-- @partial-block outputs the content placed between the partial call tags --}}
<div class="card">
  {{!-- hash parameters passed on the call are available as variables --}}
  {{#if title}}
    <h4>{{title}}</h4>
  {{/if}}
  {{> @partial-block}}
</div>

With the call above, this outputs:

<div class="card">
  <h4>My Block</h4>
  <p>Some content here</p>
</div>

Key points:

• Use {{#> partialName}} ... {{/partialName}} to call a partial as a block. The closing tag must match the partial name.
• Inside the partial, {{> @partial-block}} is where the wrapped content is inserted. If you omit it, the wrapped content is discarded.
• You can still pass hash parameters (like title above) on the same call. They work exactly as they do for a normal partial.

Inline Partials

An inline partial is a partial defined directly inside a layout using {{#*inline "name"}}, rather than being stored as a separate Handlebars Partial content item. This is useful when a reusable fragment is only needed within a single layout and doesn't warrant a globally registered partial.

Once defined, an inline partial is called with the same {{> name}} syntax as any other partial, and can be called as many times as you need within that layout.

{{#*inline "displayMessage"}}
  <p>Message to display: {{{message}}}</p>
{{/inline}}

{{>displayMessage message="This is an example of a message"}}
{{>displayMessage message=(publish element="HTML")}}

This outputs the displayMessage fragment twice. Once with a literal string, and once with the value of the HTML element resolved via publish.

Key points:

• Define with {{#*inline "name"}} ... {{/inline}} (note the * before inline).
• An inline partial is only available within the layout (and scope) where it is defined. It is not registered globally like a Handlebars Partial content item.
• Call it exactly like a normal partial: {{> name}}, including passing hash parameters.