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.

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.