Common Development Patterns

Recipes for tasks many templates share: showing a region conditionally, structuring repeatable field content, and fetching, narrowing, looping and paginating collections.

Each recipe here combines the mechanics in Templating Mechanics to do one job. A recipe shows one way, with the examples that belong to it; there is usually more than one valid way. Complete page templates, including a generic page and a pagination partial, live under Complete Examples.

Conditional Layout

Show or hide a region with if or unless, often from a query parameter, toggle, or login state.

Show or hide a section based on a query parameter, a toggle, or a condition. For example, include a sidebar only when a query parameter is present, or show different content when the user is logged in.

Use {% if %} or {% unless %} around the block. If the block is large, pull it into an include so the main template stays readable. Pass in only the data the partial needs.

The same idea applies to personalization checks (logged-in vs guest, client session counts) and to any optional chrome that should not render empty markup when the condition is false.

Example Include sidebar template unless a query param is falseInclude a sidebar template only when a query parameter is not false, using unless.

{%- unless request.query_params contains "show_sidebar=false" -%}
	{%- if request.query_params has_key "show_sidebar" -%}
		{%- include "_custom_sidebar" type:request.query_params.show_sidebar -%}
	{%- else -%}
		{%- include "_default_sidebar" type:request.query_params.show_sidebar -%}
	{%- endif -%}
{%- endunless -%}

Example Check if the user is logged in (not a guest)Use auth.logged_in to show different content for logged-in vs anonymous users.

{%- if auth.logged_in -%}
	<p>Do something</p>
{%- else -%}
	<p>Do something else</p>
{%- endif -%}

Example Count client sessions within a time window (e.g. one year)Count how many sessions the client has had within a time window (e.g. one year) for analytics or limits.

{%- if client.num_sessions > 6 and client.first_request_date < request.date | add_years: -1 -%}
	<p>You have viewed this site {{ client.num_sessions }} times since you first visited over a year ago.</p>
{%- endif -%}

add_years: -1 on the current request date gives "one year ago"; comparing first_request_date against that tells you whether the client's first visit was more than a year back. num_sessions is a running count the CMS keeps per client, so no manual counting is needed.

Structuring Repeatable Field Content

Use a fieldset for a repeatable group of values, and inspect an unfamiliar one during development.

Fieldsets let editors manage a consistent group of related values as one structured unit. A fieldset can hold one group or repeat the same group as many times as needed, so a template does not have to hard-code a fixed number of entries.

Whether a value should be a fieldset, a scalar field, or its own entity or datastore item is a planning decision; Content Types covers it.

When a fieldset's shape is unfamiliar, use the inspect filter during development. Keep the inspection depth bounded and replace inspection output with intentional child-field rendering before production. For how these values read at runtime, see Field Values.

Common Development Patterns