Custom Twig Functions Reference API

SitePack registers a powerful suite of custom Twig functions inside the ThemeService execution environment. These functions compile to native PHP calls, providing developers with high-performance hooks to render dynamic, edge-cached layouts, formats, prices, user interfaces (like live search modals, shopping cart icons, and cookie consent banners), and application blocks.

Using these built-in helpers ensures consistent e-commerce standards, security sandboxing, and compatibility with future platform updates.

Complete Functions Reference Directory

The following directory documents every custom Twig rendering function available within your theme templates:

`theme_asset(path)`

Generates the fully qualified, versioned URL of a static theme asset served from the global SitePack CDN.

Parameters:
- path (string): The relative path to the asset from inside your root /assets directory.

Example Usage:

<link rel="stylesheet" href="{{ theme_asset('css/theme.css') }}">
<script src="{{ theme_asset('js/main.js') }}" defer></script>

`theme_setting(config, key, default)`

Retrieves a user-configured setting from the Theme Customizer settings array.

Parameters:
- config (array): The global theme configurations array (typically passed as theme or config to templates).
- key (string): The unique setting lookup identifier (defined as id inside your root theme.json settings manifest).
- default (mixed, optional): The fallback value returned if the setting is null or undefined.

Example Usage:

<body style="background-color: {{ theme_setting(theme, 'primary_bg_color', '#ffffff') }}">

`sitepack_title()`

Generates the appropriate HTML meta title dynamically based on the current active storefront route (e.g., Category names, Product names, or Static page titles).

Example Usage:
```
<title>{{ sitepack_title() }}</title>
```

`sitepack_head()`

Compiles and renders essential HTML <head> tags, including SEO metadata, Open Graph microformats, favicon links, and merchant-injected CSS/styles. Place this inside your layout template before the closing </head> tag.

Example Usage:

<head>
    {{ sitepack_head() | raw }}
</head>

`sitepack_navigation()`

Generates and outputs the pre-styled, semantic standard navigation list for the storefront's main menu.

Example Usage:

<nav class="main-navigation-wrapper">
    {{ sitepack_navigation() | raw }}
</nav>

`sitepack_breadcrumbs()`

Renders the standard hierarchical breadcrumb link trail for the active storefront route (e.g., Home > Men's > Jackets).

Example Usage:

<div class="storefront-breadcrumbs">
    {{ sitepack_breadcrumbs() | raw }}
</div>

`sitepack_content()`

Renders the main content block of the active page route. This is where page body markup, category grid listings, or product details templates are injected.

Example Usage:

<main class="page-viewport-container">
    {{ sitepack_content() | raw }}
</main>

`sitepack_content_legal()`

Renders formal legal policies (e.g., terms and conditions, return policy, privacy declaration) inside policy-specific storefront routes.

Example Usage:

<article class="legal-document-wrapper">
    {{ sitepack_content_legal() | raw }}
</article>

`sitepack_footer()`

Compiles and renders standard footer navigation grids and payment network trust badges configured by the merchant in the admin panel.

Example Usage:

<footer class="site-main-footer">
    {{ sitepack_footer() | raw }}
</footer>

`sitepack_copyright()`

Example Usage:

<div class="footer-copyright-note">
    {{ sitepack_copyright() | raw }}
</div>

`sitepack_live_search()`

Renders the interactive SitePack live storefront search element (complete with immediate search matching, predictive listings, and a fullscreen modal wrapper).

Example Usage:
```
{{ sitepack_live_search() | raw }}
```

`sitepack_live_search_icon()`

Renders the default interactive SVG icon trigger for booting the live search modal.

Example Usage:

<button class="search-trigger-btn" aria-label="Open Search">
    {{ sitepack_live_search_icon() | raw }}
</button>

`sitepack_shopping_cart_icon(icon, showCount)`

Outputs an interactive shopping cart SVG icon container with real-time reactive cart counting badge.

Parameters:
- icon (string, optional): Name of the icon vector to render. Default: 'shopping-bag-solid'.
- showCount (boolean, optional): Toggle showing the live item-count quantity circle. Default: true.

Example Usage:

<a href="/cart" class="header-cart-icon">
    {{ sitepack_shopping_cart_icon('shopping-cart-solid', true) | raw }}
</a>

`sitepack_cart()`

Compiles and renders a highly interactive, responsive shopping cart table detailing added items, variant metadata, responsive quantity selector controls, item removal triggers, shipping calculation summaries, and the checkout funnel trigger buttons.

Example Usage:

<section class="shopping-cart-page-content">
    {{ sitepack_cart() | raw }}
</section>

`sitepack_cookies()`

Compiles and outputs the merchant's configured interactive Cookie Consent Banner modal. Handled cleanly over the CDN to meet European GDPR/ePrivacy standards. Place this near the footer of your base layout file.

Example Usage:
```
{{ sitepack_cookies() | raw }}
```

`sitepack_scripts()`

Renders essential system-level scripts and merchant tracker injection blocks (such as Google Analytics/Tag Manager, custom analytics pixels, checkout scripts). Place this function directly before the closing </body> tag of your base layout template.

Example Usage:
```
{{ sitepack_scripts() | raw }}
```

`app_block(name)`

Directly renders a designated third-party app block matching a specific placement code name.

Parameters:
- name (string): The layout hook target code (e.g., 'header_top', 'product_reviews').

Example Usage:

<div class="custom-promotional-strip">
    {{ app_block('header_top') | raw }}
</div>

`sitepack_price(priceCents, currency)`

Converts and formats a catalog integer represented in cents into a beautifully formatted, human-readable currency string.

Parameters:
- priceCents (integer): Price value represented in cents (e.g., 2450).
- currency (string, optional): Currency symbol or string. Default: '€' (Euro symbol).
Example Output: € 24,50

Example Usage:

<span class="price-tag">{{ sitepack_price(product.priceCents, '€') }}</span>

`calculate_text_color(backgroundColor)`

Dynamically analyzes the luminosity/brightness of an input CSS background color, returning either '#000000' (black) or '#ffffff' (white) to ensure proper contrast for text legibility and accessibility.

Parameters:
- backgroundColor (string): A hex color code (e.g., #ffffff, #000000, or #ff5500).

Example Usage:

{# Dynamically set text color relative to user-configured header color #}
<header style="background-color: {{ settings.header_color }}; color: {{ calculate_text_color(settings.header_color) }}">
    <h1>Welcome!</h1>
</header>

`calculate_brightness(hex, steps)`

Adjusts the brightness levels of an input HEX color up or down, making it lighter or darker. Perfect for generating dynamic button hover/active color states from a single user setting!

Parameters:
- hex (string): Hex color code to adjust (e.g., #ff5500).
- steps (integer): Value multiplier indicating the amount of brightness steps. Positive values lighten, negative values darken (range -255 to 255).

Example Usage:

{# Darken custom button background color by 20 points for hover state #}
<style>
  .btn-primary {
    background-color: {{ settings.button_color }};
  }
  .btn-primary:hover {
    background-color: {{ calculate_brightness(settings.button_color, -20) }};
  }
</style>

The Master Layout Integration Blueprint

To understand how to weave these critical custom Twig rendering functions together, study this production-ready blueprint of the master template layouts/base.twig:

<!DOCTYPE html>
<html lang="{{ site.language }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    
    {# Output SEO Title dynamically #}
    <title>{{ sitepack_title() }}</title>
    
    {# Inject essential head tags, metadata, and merchant tracking stylesheets #}
    {{ sitepack_head() | raw }}
    
    {# Load pre-minified custom theme stylesheets via theme_asset() helper #}
    <link rel="stylesheet" href="{{ theme_asset('css/theme.min.css') }}">
    
    {# Inject customizer colors directly into root styles #}
    <style>
      :root {
        --primary-color: {{ settings.primary_color | default('#ff5500') }};
        --text-color: {{ settings.text_color_body | default('#333333') }};
        --font-family: {{ settings.base_font_family | default('Arial, sans-serif') }};
      }
    </style>
    
    {# Let apps inject tags before the closing </head> #}
    {% app_block 'head_after' %}
</head>
<body style="font-family: var(--font-family); color: var(--text-color);">

    {# Let apps inject markup right at body start #}
    {% app_block 'body_start' %}
    
    {# Output site-wide cookie banner #}
    {{ sitepack_cookies() | raw }}
    
    {# Output promotional top app block #}
    {{ app_block('header_top') | raw }}

    {# Include the global modular header snippet #}
    {% include 'snippets/header.twig' %}

    {# Renders the breadcrumb navigation dynamically #}
    <div class="breadcrumb-nav-outer">
        <div class="container">
            {{ sitepack_breadcrumbs() | raw }}
        </div>
    </div>

    {# Inject the main viewport storefront page views #}
    <div class="storefront-viewport-main">
        {{ sitepack_content() | raw }}
    </div>

    {# Include the global modular footer snippet #}
    {% include 'snippets/footer.twig' %}

    {# Let apps inject markup right before body end #}
    {% app_block 'body_end' %}

    {# Output dynamic live search modal markup #}
    {{ sitepack_live_search() | raw }}

    {# Output core scripts & tracking pixels #}
    {{ sitepack_scripts() | raw }}
</body>
</html>

Exploring Further:

Now that you have mastered custom rendering functions, discover the custom data string filters available for theme templates inside the Custom Theme Filters Guide!

Complete Functions Reference Directory​

theme_asset(path)​

theme_setting(config, key, default)​

sitepack_title()​

sitepack_head()​

sitepack_navigation()​

sitepack_breadcrumbs()​

sitepack_content()​

sitepack_content_legal()​

sitepack_footer()​

sitepack_copyright()​

sitepack_live_search()​

sitepack_live_search_icon()​

sitepack_shopping_cart_icon(icon, showCount)​

sitepack_cart()​

sitepack_cookies()​

sitepack_scripts()​

app_block(name)​

sitepack_price(priceCents, currency)​

calculate_text_color(backgroundColor)​

calculate_brightness(hex, steps)​

The Master Layout Integration Blueprint​

Exploring Further:​

Complete Functions Reference Directory

`theme_asset(path)`

`theme_setting(config, key, default)`

`sitepack_title()`

`sitepack_head()`

`sitepack_navigation()`

`sitepack_breadcrumbs()`

`sitepack_content()`

`sitepack_content_legal()`

`sitepack_footer()`

`sitepack_copyright()`

`sitepack_live_search()`

`sitepack_live_search_icon()`

`sitepack_shopping_cart_icon(icon, showCount)`

`sitepack_cart()`

`sitepack_cookies()`

`sitepack_scripts()`

`app_block(name)`

`sitepack_price(priceCents, currency)`

`calculate_text_color(backgroundColor)`

`calculate_brightness(hex, steps)`

The Master Layout Integration Blueprint

Exploring Further: