Template

The template object and methods for loading templates.

Template types are page, partial, form, and gallery. A page template renders a whole page and must produce a complete HTML document, usually through the site's shared header and footer partials. A partial is included by other templates. Form and gallery templates control how the CMS renders a Form or a Gallery. "Section" is not a template type: a sections folder is just a place to keep partials, and every template in it is a partial.

Properties

Properties of {{ template }} objects
Name	Type	Description
`object_type`	string	Will always be template
`is_valid`	boolean	True if this references a published template
`guid`	string	The unique identifier for this template
`value`	string	Contains the same value as guid
`name`	{{ text }}	The name of the template which, when combined together with the path, uniquely identifies the template on this site
`path`	string	The path, excluding filename, of this template used for organizational and reference purposes
`type`	{{ select }}	Field type (e.g., text, textarea, select, checkbox, etc.)
`markup`	{{ code }}	Template markup/source code
`field_id`	string	The identifier for this field
`label`	string	The label for this field
`output`	string	Outputs the rendered template in a new child scope - similar to calling {% include %} with the current template.

Example Include a template whose name is in a variableDemonstrates multple ways to dynamically include a template. Note that in all of these examples, the template fields will NOT be compiled in the page definition.

Dynamically Include a Template from a Variable

{%- var dynamicTemplate = "/partials/footer-main.liquid" -%}
{%- include dynamicTemplate -%}

Dynamically Include Template from a Select List

{%- if page.page_layout.is_valid -%}
	<div class="sidebar-{{ page.page_layout.value }}">
		{%- var includeTemplate = "/theme/sidebar/" | append:page.page_layout.value -%}
		{%- include includeTemplate -%}
	</div>
{%- endif -%}

Assuming that page_layout is a select field or similar, this code dynamically creates the name of the template to include based on the selected value.

Dynamically Include Multiple Templates from a TemplateList Field

{%- if page.sidebar_sections.count > 0 -%}
	{%- for section in page.sidebar_sections.selected -%}
		{%- include section -%}
	{%- endfor -%}
{%- endif -%}

Assuming that sidebar_sections is a templatelist field or similar, this code dynamically includes each of the selected templates.

Check if a dynamic template exists before including it

{%- template var dynamicTemplate = "/theme/sidebar/" | append: page.sidebar_section.value | append: ".liquid" -%}
{%- if dynamicTemplate.is_valid -%}
	{%- include dynamicTemplate -%}
{%- endif -%}

Assuming that sidebar_sections is a templatelist field or similar, this code dynamically includes each of the selected templates.

Example Fetch templates filtered by template_type{% templates %} returns a templates list; template_type and path options narrow which templates are returned.

{%- templates var partials = template_type:"Partial" limit:50 sort_by:"name" -%}
<ul>
{%- for tpl in partials -%}
	<li>{{ tpl.name }} — {{ tpl.path }}</li>
{%- endfor -%}
</ul>

{% templates %} is the list method for template assets. Type-specific options such as template_type and path combine with shared list options (limit, sort_by). Iterate the resulting templates object directly. This example teaches the templates query itself (unlike older snippets that only used templates while demonstrating join).

Contains multiple templates.

Properties

Properties of {{ templates }} objects
Name	Type	Description
`object_type`	string	Will always be templates
`is_valid`	boolean	True if this contains at least one published template
`output`	string	The default output that the templates will produce when it is output directly to the template - using the "output_in_list" property of each template in the items list
`prepended`	list	List containing any prepended templates.
`fetched`	list	List containing all of the templates that were fetched from the database (as opposed to prepended or appended).
`appended`	list	List containing any appended templates.
`appended_unique`	list	List containing any appended templates excluding any templates that are in either the list of prepended or fetched templates.
`items`	list	List containing all of the combined templates from the prepended, fetched, and appended lists. If unique is true, this list will not contain any duplicates. If max_size is set, this list will not contain more than the number of templates specified.
`size`	integer	The total number of templates in the items list, including prepended, fetched, and appended lists, and respecting the unique and max_size properties.
`max_size`	integer	If set, this is the maximum number of items that will be returned in the items list and the maximum number of items that will be included when this templates object is enumerated as a list. When not set, this value will be 0.
`unique`	boolean	When true, the items list will not contain any duplicates. Only the first instance of each template will be included.
`limit`	integer	The maximum number of items that were allowed to be in the list of fetched templates. May be 0 in some cases (such as when when there are no fetched templates.
`start`	integer	The 1-based index of the first item in the list of fetched templates.
`page`	integer	The 1-based index of the paginated results returned in the list of fetched templates, which is calculated from the start and limit parameters. Useful for paginated results.
`total_count`	integer	The 1-based index of the first item in the list of fetched templates
`total_pages`	integer	If any items were fetched from the database, total_pages will contain the number of paginated result pages in the database for the provided arguments. This may also be calculated using the total_count and limit properties.

Dynamically Include a Template from a Variable

{%- var dynamicTemplate = "/partials/footer-main.liquid" -%}
{%- include dynamicTemplate -%}

Dynamically Include Template from a Select List

{%- if page.page_layout.is_valid -%}
	<div class="sidebar-{{ page.page_layout.value }}">
		{%- var includeTemplate = "/theme/sidebar/" | append:page.page_layout.value -%}
		{%- include includeTemplate -%}
	</div>
{%- endif -%}

Assuming that page_layout is a select field or similar, this code dynamically creates the name of the template to include based on the selected value.

Dynamically Include Multiple Templates from a TemplateList Field

{%- if page.sidebar_sections.count > 0 -%}
	{%- for section in page.sidebar_sections.selected -%}
		{%- include section -%}
	{%- endfor -%}
{%- endif -%}

Assuming that sidebar_sections is a templatelist field or similar, this code dynamically includes each of the selected templates.

Check if a dynamic template exists before including it

{%- template var dynamicTemplate = "/theme/sidebar/" | append: page.sidebar_section.value | append: ".liquid" -%}
{%- if dynamicTemplate.is_valid -%}
	{%- include dynamicTemplate -%}
{%- endif -%}

Assuming that sidebar_sections is a templatelist field or similar, this code dynamically includes each of the selected templates.

Example Fetch templates filtered by template_type{% templates %} returns a templates list; template_type and path options narrow which templates are returned.

{%- templates var partials = template_type:"Partial" limit:50 sort_by:"name" -%}
<ul>
{%- for tpl in partials -%}
	<li>{{ tpl.name }} — {{ tpl.path }}</li>
{%- endfor -%}
</ul>

{% template %}

Identifies the template by its path and name. The path can be absolute (it begins with /, so it is taken from the root) or relative (it is resolved against the folder of the template being rendered, and .. moves up one folder; ./ is not supported). The name is matched as stored, with no extension added or removed. {% include %} gives the full rules, which are the same here.

{% template output_to_template? [[var, set, or assign]? variable_name]? output_to_template? = value %}

Parameters

output_to_template optionalflag

Include this flag to write the template's output into the page at this point. What that output is differs by type, and for most types it is a built-in default that may change at any time, so see the output property of the template object before relying on it. The flag may come before or after the variable name. When the call names no variable, the output is written whether or not the flag is present, which makes {% template = value %} the smallest valid use of this method. When the call names a variable, the flag saves the template to the variable and writes its output as well.

var, set, or assign optionalkeyword

Chooses the scope that holds the variable. var, the default, stores it in the current scope. set and assign can store it in outer scopes; Variable Scopes compares the three and when each fits.

variable_name optionalvariable

The variable that receives the template. It may also be written as a reference, &name, which reads the variable's name from another variable (see Methods Overview). Leave it out to write the template to the template instead.

value requiredexpression

Required; without a value the method call is not valid. Identifies which template to fetch. It can evaluate to the template itself, to its GUID, or to other text that identifies it, which for most types is its name; a type identified some other way, or only by GUID, says so in its summary. Names are matched without regard to case, but accented letters must match. A GUID identifies exactly one record, whereas when several records share a name, which of them is returned is not specified, so giving the records you fetch by name unique names avoids the question. A name reads better in a template and a GUID is exact; neither suits every site. When nothing matches, no error is raised: the variable holds an invalid template, whose is_valid is false, so check is_valid before using it. When the expression itself has no value, for example an undefined variable, the method does nothing and the variable keeps any earlier value. May use liquid filters.

Fetches a single {{ template }}.

Dynamically Include a Template from a Variable

{%- var dynamicTemplate = "/partials/footer-main.liquid" -%}
{%- include dynamicTemplate -%}

Dynamically Include Template from a Select List

{%- if page.page_layout.is_valid -%}
	<div class="sidebar-{{ page.page_layout.value }}">
		{%- var includeTemplate = "/theme/sidebar/" | append:page.page_layout.value -%}
		{%- include includeTemplate -%}
	</div>
{%- endif -%}

Assuming that page_layout is a select field or similar, this code dynamically creates the name of the template to include based on the selected value.

Dynamically Include Multiple Templates from a TemplateList Field

{%- if page.sidebar_sections.count > 0 -%}
	{%- for section in page.sidebar_sections.selected -%}
		{%- include section -%}
	{%- endfor -%}
{%- endif -%}

Assuming that sidebar_sections is a templatelist field or similar, this code dynamically includes each of the selected templates.

Check if a dynamic template exists before including it

{%- template var dynamicTemplate = "/theme/sidebar/" | append: page.sidebar_section.value | append: ".liquid" -%}
{%- if dynamicTemplate.is_valid -%}
	{%- include dynamicTemplate -%}
{%- endif -%}

Assuming that sidebar_sections is a templatelist field or similar, this code dynamically includes each of the selected templates.

{% templates %}

The prepend, append and exclude arguments identify a template by its path and name or by its GUID, as {% template %} does, with one difference: a list method reads every path from the root, with or without the leading /, and cannot take a relative path. The same text, such as partials/_card.liquid, is relative to the current folder in {% include %} and in {% template %} but means /partials/_card.liquid here. The path option is compared with each template's stored folder path as written (for example /partials), does not include child folders, and is not normalized.

{% templates output_to_template? [[var, set, or assign]? variable_name]? output_to_template? = arguments %}

Parameters

output_to_template optionalflag

Include this flag to write the templates list's output into the page here. That output is a built-in default for most types and may change at any time, so see the output property of the templates object before relying on it. The flag may come before or after the variable name. With no variable named, the output is written whether or not the flag is present; with one, the flag saves the list and writes its output too.

var, set, or assign optionalkeyword

Chooses the scope that holds the variable. var, the default, stores it in the current scope. set and assign can store it in outer scopes; Variable Scopes compares the three and when each fits.

variable_name optionalvariable

The variable that receives the templates list. It may also be written as a reference, &name, which reads the variable's name from another variable (see Methods Overview). Leave it out to write the list to the template instead.

arguments requiredcollection

Key:value pairs. May use the variable arguments syntax. Written after a required =. The name:value pairs choose which templates to fetch and how to narrow, order and page them. Nothing is fetched unless the call gives an argument other than prepend, append, unique, exclude_prepended, exclude_appended, max_size and cache_random; without one, the list holds only the prepended and appended templates.

Options

prepend optionallist

May be a single template, a list of templates, or the name or guid of one template, to be included at the beginning of the templates list.

append optionallist

May be a single template, a list of templates, or the name or guid of one template, to be included at the end of the templates list.

exclude optionallist

May be a single template, a list of templates, or the name or guid of one template that should NOT be included in the fetched results. Has no effect on prepended or appended templates.

exclude_prepended optionalboolean

True to specifically exclude all prepended templates from the fetched results. If "unique:true" is specified this is the default behavior, although you may also specify "exclude_prepended:false" to allow any prepended items to be fetched along with other results anyway.

exclude_appended optionalboolean

True to specifically exclude all appended templates from the fetched results. This is false by default - even if "unique:true" is specified - so that results are returned in the proper order.

unique optionalboolean

True to remove duplicates from each of the resulting lists (prepended, fetched, appended, and items), although there may be duplicates between the prepended, fetched, and appended lists. The "items" list will include objects in the order in which they appear - with prepended items first, then fetched items, then appended items.

max_size optionalinteger

The maximum number of items to be included in the "items" list. If there are any prepended or appended items, this will automatically lower the "limit" to only fetch as many templates as needed. Note that this may also impact both the "page" and "total_pages" values in the resulting templates. In order to use pagination with a list loaded using "max_size" use "start" instead of "page" and "limit".

template_type optionalvalue

Only include templates with the given template type (page, partial, form, or gallery)

path optionalvalue

May include multiple paths. Only include templates with one of the given paths (excluding child paths)

date_created_start optionalvalue

Only include templates with date_created greater than or equal to date_created_start. Remember that date_created will typically be the date that the template was first published.

date_created_end optionalvalue

Only include templates with date_created less than or equal to date_created_end. Remember that date_created will typically be the date that the template was first published.

start optionalinteger

Set the 1-based index of the first template to fetch.

page optionalinteger

Used to automatically calculate the first template to fetch based on both the "limit" and the 1-based "page" value. Defaults to 1, but is ignored if "start" is set.

limit optionalinteger

The maximum number of templates to fetch. Defaults to 10; a value that is not a number also gives 10. The largest limit is 1000, and a limit of 0 or less, or above 1000, returns up to 1000 templates. Note that if "max_size" is defined, then "limit" may be automatically lowered even if specified separately.

sort_by optionalstring

Specify which property to sort the results by. Has no effect on prepended or appended templates. An unrecognized value is ignored without an error and the default order is used. Some methods accept more values than the built-ins listed here; see each method. Options include:

date_created: the date each template was first published. Unpublishing and republishing one resets date_created to the current date.
random: results will be returned in a random order, which prevents the page from being fast-cached. Setting cache_random:true overrides this behavior and allows the page to be fast-cached anyway.
name
title
url
browser_title

sort_direction optionalstring

asc or desc. Defaults to desc; any value other than asc sorts descending.

cache_random optionalboolean

True to allow the results to be cached when sort_by is "random".

Fetches a list of {{ templates }}.

Example Fetch templates filtered by template_type{% templates %} returns a templates list; template_type and path options narrow which templates are returned.

{%- templates var partials = template_type:"Partial" limit:50 sort_by:"name" -%}
<ul>
{%- for tpl in partials -%}
	<li>{{ tpl.name }} — {{ tpl.path }}</li>
{%- endfor -%}
</ul>