Partials

Small, reusable chunks of code.

Partials are little sections of code that can be quickly added into one or more templates. They’re great when you want to add things to a couple of templates, but don’t want to repeat yourself. Move what you want everywhere into a partial, use the appropriate theme helper to pull it in where you want. When you need to change that content within, you only have to update it in one spot.

Each file in your theme’s partials folder is one partial. As of v1.7, these files can be HTML files, markdown files, or textile files. Each only contains the chunk of code you’ll want to use around your site. Partials will be parsed for Statamic the same way a template does.

Creating a Partial

As an example, let’s say that you want to include a tagline within some of your templates. Follow these steps to create your partial:

1. Check for a partials folder within your theme’s directory, if it’s not there, create it
2. In this partials folder, create tagline.html
3. Edit tagline.html to include the HTML that you’ll want to include within your templates

We called our partial tagline.html, but we could have named it anything. You can create any number of partials for use around your site.

Using Partials

To use a partial within your template, you’ll want to use Statamic’s theme helper for partials. This theme helper is a small template tag that tells Statamic where to place the contents of a particular partial.

In practice, it looks something like this:

<!-- sample template html -->
<aside class="sidebar">
    {{ theme:partial src="tagline" }}
</aside>

Statamic will use the above code to look for tagline.html within your current theme’s partials folder. If it finds it, it will replace the {{ theme:partial }} tag with the contents of that file.

If your partial contains other template tags, Statamic will also replace those with their appropriate values as well.

Variable Scope & Partials

By default (which applies to all partials before v1.7), partials did not realize variables in context around them. Within a standard partial, you can use Statamic template tags to access any of the variables set up to the page-level. Want to use this current page’s title? No problem, use {{ title }}.

Using Context

As of v1.7, partials can also inherit the variable scope into which they’re placed. To turn this on for a partial, set the use_context parameter to true. This means that you can use partials within tags like listings:

{{ entries:listing folder="blog" }}
    {{ theme:partial src="blog-listing" use_context="true" }}
{{ /entries:listing }}

By setting use_context to true, the partial is now aware of each loop in the {{ entries:listing }} tag that it’s wrapped in.

Passing Variables into Partials

If you need to pass specific data into your partial, you can add them as parameters onto the partial helper tag itself. For example, the {{ side }} tag will become available within the sidebar partial (with the value left) in this code:

{{ theme:partial src="sidebar" side="left" }}

Or, Do Both

You can both pass variables into a partial manually and have the partial use the context around it. Additionally, the use_context parameter becomes available to you within the partial, so the partial itself can detect if its being used within context or not (you’d check with {{ if use_context }}).

Partials Within Partials

Partials can also call other partials, optionally passing context through as it sees fit.

On Performance

It’s worth mentioning that partials will become a handy tool in not repeating yourself, but you should only turn on use_context if your partial needs it. There is a tiny performance hit that comes with using it. We should stress that the hit is tiny, but like all tiny things, using them a bunch of times can stack up.

The benefit contextually-based partials bring almost always outweighs the slight performance hit, but you should use your own judgment here.