Methods and formatters

A method call inspects or reformats a token value. You write the token, then a dot, then the method name and parentheses: {token.method()}. The engine supports five methods: len, is_empty, format_date, inline_json, and letter. Methods do not change the stored value; they only affect what that expression produces.

Where method calls work

Method calls are expressions, so they are accepted anywhere the engine evaluates an expression:

• Value position: a placeholder that outputs a value, for example {brand.store_name.letter(30)}.
• Conditions: inside {if} and {elseif}, for example {if brand.tagline.is_empty()}.
• Method arguments: an argument can itself be a token or a method call, for example .letter(brand.store_name.len()).
• Numeric range bounds: the start and end of a for range accept expressions, so a count can drive the bound.

A single token calls one method. To base a method on a computed value, put the method on the argument instead of chaining two methods on the same token.

Method reference

len

Returns the length of the value's text. Numbers and booleans are measured as their text form. Because the count is a text length, characters outside the basic Latin range can count as more than one. A missing value measures as 0.

Use it to show a count or to guard against values that are too long.

<p>{brand.store_name.len()} characters</p>

{if brand.tagline.len() > 160}
  <p class="text-xs text-gray-500">Showing the first 160 characters.</p>
{/if}

is_empty

Returns true when the value is missing or its text is empty, and false otherwise. Use it on a text field or an optional value. A number or boolean is never empty because it always has a text form, so use it to test text rather than a counter.

Use it to show a placeholder for an optional field or to tailor a call to action.

{if currentUser.email.is_empty()}
  <a href="/login">Sign in</a>
{else}
  <span>{currentUser.email}</span>
{/if}

{if brand.tagline.is_empty()}
  <p class="text-gray-500">Add a tagline in brand settings.</p>
{/if}

format_date

Reformats a date value using a pattern. The argument is optional; without it the default pattern MMM D, YYYY is used, which prints a date such as Jan 5, 2026. If the value cannot be read as a date, the original value is returned unchanged, so the method is safe to apply to a token that may not be populated.

Accepted date inputs include a Unix timestamp in seconds or milliseconds (whole or fractional), an RFC 3339 value, an RFC 2822 value, and the common forms YYYY-MM-DD HH:MM:SS, YYYY-MM-DD HH:MM, YYYY-MM-DDTHH:MM:SS, and YYYY-MM-DD.

Pattern tokens:

Longer tokens win over shorter ones, so MMMM prints a full month name while MM prints a number. Any character that is not a token is copied through, but stray letters that happen to match a token are interpreted, so keep patterns to tokens, spaces, and separators such as -, /, and ,.

The examples use {template.updated_at}; substitute the date token that is available on your page.

<time>{template.updated_at.format_date()}</time>
<time>{template.updated_at.format_date("yyyy-MM-dd")}</time>
<time>{template.updated_at.format_date("MMMM d, yyyy")}</time>

If you are not sure which date token a page exposes, apply the method and check the rendered output; an unreadable value is printed as it was.

inline_json

Serializes a value as compact JSON. The result is escaped so it can be placed inside a double-quoted HTML attribute and read by page scripts. Text that is already JSON is parsed and re-serialized compactly; other text becomes a JSON string; an empty or missing value becomes null.

Use it to pass a token's value to JavaScript without a separate request.

<div id="page-schema" data-schema="{page.schema.inline_json()}"></div>

<script>
  const el = document.getElementById("page-schema");
  const schema = JSON.parse(el.dataset.schema || "null");
</script>

letter

Returns a number of characters from the value's text. The first argument is how many characters to take; it defaults to 1. The optional second argument chooses the side: first (the default) takes from the start and last or end takes from the end. If the count is zero or below, or the value is empty, the result is empty. If the count is larger than the text, the whole text is returned.

Use it for short previews, initials, or badges.

<span class="avatar-initials">{currentUser.first_name.letter(1)}{currentUser.last_name.letter(1)}</span>

<p>{brand.tagline.letter(80)}...</p>

<p class="text-xs">Ends with {currentUser.email.letter(3, "last")}</p>