Safe Output and Handling Missing Data

Templates often depend on data that might be missing: an optional custom field, a query parameter that was not supplied, or a value passed into a partial under another name. The other half of safe output is encoding for the destination. A field printed in an HTML text node is not encoded the same way as that same value in a tag attribute, a CSS class, a URL, or JSON.

Most Marketpath fields (text, textarea, select, and similar) HTML-encode their default output. Printing {{ entity.title }} or {{ item.title }} in an HTML text node is usually correct. Do not pipe that default output through the escape filter — that double-encodes, and it can escape preview markup such as span tags. On the current page, output {{ entity.title }} for the heading; do not treat it as an optional plain string with the default filter, and do not wrap root entity in is_valid. Guard renamed copies such as item when a partial receives entity as an input.

The raw unencoded value is {{ field.value }}. Use .value when you need the string itself: HTML attributes, filter chains, or a partial that expects a plain string. In attributes, always use .value and escape, even on required fields, because default field output is HTML-oriented and may include preview markup that does not belong in an attribute:

<div aria-label="{{ item.title.value | escape }}"></div>

Choose a filter for the destination, not one generic “safe” filter. Use escape (or html_encode, which performs the same encoding) for HTML text and attributes. Use classname for class names, url_encode for query values, and json_encode for JSON. HTML escape does not make a URL or a JSON payload correct. Prefer escape over escape_once for ordinary unencoded text.

Two field types break the usual encoding rule. An html field is trusted markup; escaping it usually defeats the field’s purpose. A code field’s default output is the raw value — treat it as unsafe and use it with extreme caution.

For missing data, prefer {% if item.is_valid %} over a bare {% if item %} when item is a documented object. Bare truthiness is mainly for checking whether an unbound input variable exists. Wrap optional sections (an image, a link, a whole block) in {% if %} so you do not render empty tags or broken markup.

Use the default filter when a fallback is intentional. It returns the fallback when the input is null, an empty string, or invalid (is_valid is false). It does not treat the boolean false as missing. For an optional custom field in HTML:

{{ item['custom-field'].value | default: "Fallback" | escape }}

If you would rather keep the template readable, bind the field with {% var %}, test is_valid, and output the field (for a text node) or .value | escape (for an attribute). When a reusable partial expects a plain string, pass a string at the include boundary (for example title: item.title.value), not the field object.

When an input may be either a plain string or a field object, one chain resolves both: {{ input.value | default: input | default: "Fallback" | escape }}. An empty or missing field falls through to the next default because is_valid is false, and the result is a string suitable for an HTML text node or, unchanged, an attribute.

These habits keep encoding correct and keep missing data from producing errors or empty markup. See the linked examples, the default and escape filters, and the is_valid condition for more detail.

{%- if random_object is_valid -%}
	{%- include "display_random_object" object:random_object -%}
{%- endif -%}

{%- if field.is_valid -%}
	{{-field.value-}}
{%- endif -%}

{%- if varname is_valid -%}
	{{-varname-}}
{%- endif -%}

{%- unless varname is_valid -%}
	... do something if varname is NOT valid...
{%- endunless -%}

{%- var falsevar = false -%}
{%- if falsevar is_valid -%}
	false is_valid evaluates to TRUE!
{%- else -%}
	this will never be output
{%- endif -%}

{%- var greeting = "" -%}
{{- greeting | default: "hello" }} world
{%- set greeting = "goodbye" -%}
{{- greeting | default: "hello" }} world

hello world
goodbye world

{% var page = request.query_params['page'] | to_int | default: 1 %}

{{ item['headline'].value | default: "Untitled" | escape }}

{{ classname_prefix | strip | default: 'fallback-' | append: entity.name.value | classname }}

<div aria-label="{{ item.title.value | escape }}"></div>

<p title="{{"<p>A string with HTML & other characters</p>" | escape}}">...

<p title="&lt;p&gt;A string with HTML &amp; other characters&lt;/p&gt;">...

<p title="{{"&lt;p&gt;A string with some characters encoded & others not encoded&lt;/p>" | escape_once}}">...

<p title="&lt;p&gt;A string with some characters encoded &amp; others not encoded&lt;/p&gt;">...