Skip to main content

Liquid Filters

Tapestry Stitch provides a comprehensive set of custom Liquid filters to transform and format data during template processing. These Stitch-specific filters sit on top of the standard Liquid toolset and add powerful data manipulation capabilities tailored for commerce data.

Standard Liquid filters

All of the native Liquid filters documented by LiquidJS are available out of the box. When you need the baseline functionality, refer to the LiquidJS filter reference and use those filters directly in your templates.

Stitch Custom Filters​

translate​

Translates field values based on locale settings. This filter supports product fields, variant fields, metafields, and nested data structures.

Usage:

{{ "product.title" | translate }}
{{ "product.metafields.namespace.key" | translate }}
{{ "variant.title" | translate }}

Features:

  • Automatic locale detection from context
  • Fallback locale support (e.g., "en-US" falls back to "en")
  • Support for array indices: {{ "variants[0].price" | translate }}
  • Works with loop variables: {% for item in collection %}{{ "item.title" | translate }}{% endfor %}

How it works:

  • Checks for translations in the current locale
  • Falls back to base locale if specific locale not found
  • Returns original value if no translation exists

parse_json​

Parses a JSON string into an object for template processing.

Usage:

{% assign data = json_string | parse_json %}
{{ data.property }}

Features:

  • Safe parsing with error handling
  • Returns null for invalid JSON
  • Preserves objects if already parsed
  • Handles special __JSON__ prefix markers

Example:

{% assign product_data = '{"name": "Widget", "price": 29.99}' | parse_json %}
Name: {{ product_data.name }}
Price: {{ product_data.price }}

json​

Converts any value to a valid JSON string representation. This filter overrides the built-in Liquid json filter to properly handle edge cases.

Usage:

{{ product | json }}
{{ null | json }}
{{ undefined_var | json }}

Features:

  • Properly handles null/undefined as "null"
  • Preserves empty strings as ""
  • Handles circular references gracefully
  • Ensures valid JSON output in all cases

Why custom? The built-in Liquid json filter outputs nothing for null/undefined values, which creates invalid JSON. Our custom filter ensures valid JSON output:

// Built-in (invalid):
"field": ,

// Custom (valid):
"field": null

integer​

Converts values to integers for proper JSON number output.

Usage:

{{ "42" | integer }}
{{ product.quantity | integer }}
{{ "3.14" | integer }}  // Returns 3

Features:

  • Returns null for invalid inputs
  • Floors decimal numbers to integers
  • Handles string numbers correctly
  • Preserves null values

Example:

{
  "quantity": {{ variant.inventory_quantity | integer }},
  "min_order": {{ settings.min_quantity | integer }}
}

float​

Converts values to floating-point numbers for decimal precision.

Usage:

{{ "29.99" | float }}
{{ product.price | float }}
{{ "invalid" | float }}  // Returns null

Features:

  • Returns null for invalid inputs
  • Preserves decimal precision
  • Handles string numbers correctly
  • Preserves null values

Example:

{
  "price": {{ variant.price | float }},
  "weight": {{ product.weight | float }},
  "tax_rate": {{ "0.08" | float }}
}

boolean​

Converts values to boolean true/false for proper JSON boolean output.

Usage:

{{ "true" | boolean }}
{{ product.available | boolean }}
{{ 1 | boolean }}  // Returns true
{{ 0 | boolean }}  // Returns false

Features:

  • String "true"/"false" conversion (case-insensitive)
  • Numbers: 0 = false, non-zero = true
  • Null/undefined = false
  • Empty string = false

Example:

{
  "available": {{ product.available | boolean }},
  "requires_shipping": {{ variant.requires_shipping | boolean }},
  "taxable": {{ "true" | boolean }}
}

string​

Alias for the json filter to ensure consistent string serialization.

Usage:

{{ product.title | string }}

Note: This filter is maintained for backward compatibility but internally uses the json filter for consistent behavior.

Common Use Cases​

Building JSON APIs​

{
  "id": {{ product.id | integer }},
  "title": {{ product.title | json }},
  "price": {{ product.price | float }},
  "available": {{ product.available | boolean }},
  "description": {{ product.description | json }}
}

Handling Translations​

{% assign locale = "fr-CA" %}
{
  "title": {{ "product.title" | translate }},
  "description": {{ "product.metafields.custom.description" | translate }}
}

Processing Dynamic Data​

{% assign config = settings.json_config | parse_json %}
{% for item in config.items %}
  {
    "name": {{ item.name | json }},
    "value": {{ item.value | float }},
    "enabled": {{ item.enabled | boolean }}
  }{% unless forloop.last %},{% endunless %}
{% endfor %}

Safe JSON Construction​

{
  "field1": {{ potentially_null_var | json }},
  "field2": {{ undefined_var | json }},
  "field3": {{ empty_string | json }}
}
// Output will always be valid JSON

Best Practices​

  1. Always use type filters for JSON output - Use integer, float, boolean, or json filters when building JSON to ensure proper formatting.

  2. Handle null values explicitly - Our filters properly handle null/undefined, but be aware of what output you expect.

  3. Use translate filter with locale context - The translate filter automatically uses the locale from context, ensure it's properly set.

  4. Parse JSON once and reuse - When working with JSON strings, parse once and assign to a variable:

    {% assign data = json_string | parse_json %}
    {{ data.field1 }}
    {{ data.field2 }}

  5. Chain filters when needed - Filters can be chained for complex transformations:

    {{ "product.price" | translate | float }}

Error Handling​

All filters are designed to handle errors gracefully:

  • Invalid input: Returns null or original value
  • Missing data: Returns null or empty string
  • Parsing errors: Returns original input
  • Type conversion failures: Returns null

This ensures your templates won't break due to unexpected data formats or missing values.

Performance Considerations​

  • Translation caching: The translate filter uses cached translation data for performance
  • JSON parsing: Parse JSON strings once and reuse the parsed object
  • Type conversion: These filters are lightweight and optimized for performance

Examples in Context​

Product Export Template​

{
  "products": [
    {% for product in products %}
    {
      "id": {{ product.id | integer }},
      "title": {{ "product.title" | translate | json }},
      "description": {{ "product.description" | translate | json }},
      "price": {{ product.price | float }},
      "available": {{ product.available | boolean }},
      "variants": [
        {% for variant in product.variants %}
        {
          "id": {{ variant.id | integer }},
          "title": {{ "variant.title" | translate | json }},
          "price": {{ variant.price | float }},
          "inventory": {{ variant.inventory_quantity | integer }}
        }{% unless forloop.last %},{% endunless %}
        {% endfor %}
      ]
    }{% unless forloop.last %},{% endunless %}
    {% endfor %}
  ]
}

Configuration Processing​

{% assign settings = shop.metafields.config.settings | parse_json %}
{
  "store_name": {{ shop.name | json }},
  "features": {
    "inventory_tracking": {{ settings.inventory_tracking | boolean }},
    "multi_currency": {{ settings.multi_currency | boolean }},
    "tax_rate": {{ settings.tax_rate | float }}
  }
}

These Liquid filters provide the foundation for powerful data transformation in Tapestry Stitch, enabling seamless integration between different systems and data formats.