Skip to main content

Custom Twig Filters Reference API

SitePack registers custom filters inside the Twig environment to streamline data formatting, sanitize link behaviors, and handle dynamic layout styles (such as calculating background alphas).

Twig filters are applied directly to variables using the pipe character (|). They can be chained together or parameterized to yield precise layouts.

Filters Reference Directory​

asset_url​

Serves as an intuitive syntactic-sugar filter alias for the core rendering function theme_asset(). It parses a relative assets folder string into a fully qualified, versioned asset URL served from the globally distributed SitePack CDN.

  • Signature: string | asset_url
  • Example Usage: 
    {# Rendering a theme vector icon #}
    <img src="{{ 'img/icons/bag.svg' | asset_url }}" alt="Shopping Bag">

    {# Adding a background cover image in inline CSS #}
    <div class="hero-cover" style="background-image: url('{{ 'img/banners/summer.jpg' | asset_url }}');">

Validates and reformats arbitrary path strings to ensure they function as valid URL paths.

  • Architectural logic:
    • If the path begins with a slash (/), or contains a fully qualified protocol (http://, https://, mailto:, tel:), it remains unmodified.
    • If the path is a relative page string lacking a leading slash (e.g., 'contact-us'), it prepends a slash (/contact-us) so the link resolves correctly from any sub-route on your storefront.
  • Signature: string | ensure_link
  • Example Usage: 
    {# Ensures that merchant-entered navigation links resolve correctly #}
    <a href="{{ settings.custom_banner_link | ensure_link }}" class="banner-action-btn">
      Shop Collection
    </a>

hex_to_rgb​

Converts standard hexadecimal color notation codes (#ffffff) into a comma-separated Red, Green, Blue (RGB) triplet integer list (255, 255, 255).

  • Primary Use Case: This is extremely useful when applying custom transparency/alpha values to merchant-defined colors inside inline CSS blocks, since raw Hex codes do not natively support opacity overlays inside traditional CSS declarations without CSS variables.
  • Signature: string | hex_to_rgb
  • Example Usage: 
    {# Generates a semi-transparent black overlay mask from a HEX config #}
    <div class="modal-overlay" style="background-color: rgba({{ settings.overlay_hex_color | default('#000000') | hex_to_rgb }}, 0.85);">
      <div class="modal-content">
        <h2>Summer Promo</h2>
      </div>
    </div>

Combining Filters and Functions​

Twig allows you to chain multiple filters sequentially or combine them with dynamic customizer functions to build advanced stylesheet matrices:

{# Adjusting colors, calculating brightness, converting to rgb, and writing modern CSS configurations #}
<style>
  :root {
    --raw-accent: {{ settings.accent_color | default('#ff5500') }};
    
    {# Generate dynamic semi-transparent border #}
    --border-accent: rgba({{ settings.accent_color | default('#ff5500') | hex_to_rgb }}, 0.2);
    
    {# Calculate and output hover shade #}
    --accent-hover: {{ calculate_brightness(settings.accent_color | default('#ff5500'), -15) }};
  }
</style>

Exploring Further:​

Now that you have configured functions and filters, learn how to build extensibility zones for app integrations in the Template Hooks & App Blocks Guide!