Twig Global Objects & API Data Models

To dynamically render e-commerce storefronts, SitePack automatically injects fully-populated, rich data models into your Twig templates. This guide acts as the definitive API and field reference manual for the two core global variables: the site object (SiteInfoApiModel) and the product object (ProductApiModel).

These objects are highly optimized, lazy-loaded, and fully documented to support AI-assisted development (like GitHub Copilot or Custom LLMs) when coding your templates.

The `site` Object (`SiteInfoApiModel`)

The global site variable provides access to store configuration parameters, typography setups, SEO settings, custom design inputs, modular header/footer navigation items, and legal policies.

1. Store Identity Properties (`site.site`)

Access fundamental store branding, identity, and location coordinates via the site.site object:

Field Name	Return Type	Description / Usage	Code Example
`site.site.name`	`string`	The official business display name of the store.	`\{\{ site.site.name \}\}`
`site.site.domain`	`string`	The primary vanity custom domain of the store (e.g., `mystore.com`).	`\{\{ site.site.domain \}\}`
`site.site.host`	`string`	The active HTTP server hostname.	`\{\{ site.site.host \}\}`
`site.site.protocol`	`string`	Active security protocol, typically `https`.	`\{\{ site.site.protocol \}\}`
`site.site.logo`	`string`	The absolute URL pointing to the merchant's high-res brand logo.	`<img src="\{\{ site.site.logo \}\}">`
`site.site.icon`	`string`	Absolute URL to the store favicon.	`<link rel="icon" href="\{\{ site.site.icon \}\}">`
`site.site.description`	`string`	The store’s mission tagline or general description.	`\{\{ site.site.description \}\}`
`site.site.locale`	`string`	Full active locale code (e.g., `nl_NL`, `en_US`).	`\{\{ site.site.locale \}\}`
`site.language`	`string`	Two-character base language language code (e.g., `nl`, `en`).	`\{\% if site.language == 'en' \%\}`
`site.site.socialMedia`	`array`	Associative list of active brand social links (keys are network names like `facebook`, `instagram`).	`\{\% for network, link in site.site.socialMedia \%\}`

2. Store Search Optimization Metadata (`site.seo`)

Retrieve global search optimization configurations to render in the HTML <head> block:

Field Name	Return Type	Description / Usage	Code Example
`site.seo.canonical`	`string`	The canonical index URL for the current active page.	`<link rel="canonical" href="\{\{ site.seo.canonical \}\}">`
`site.seo.metaDescription`	`string`	The default, fallback SEO meta description string.	`<meta name="description" content="\{\{ site.seo.metaDescription \}\}">`
`site.seo.openGraphDescription`	`string`	Custom description designed for social web crawlers (Facebook, LinkedIn).	`<meta property="og:description" content="\{\{ site.seo.openGraphDescription \}\}">`
`site.seo.jsonLd`	`string`	Raw JSON-LD string representing schema.org structured data.	`\{\{ site.seo.jsonLd \| raw \}\}`
`site.seo.sitemapUrl`	`string`	The absolute URL pointing to the store's dynamic XML sitemap index.	`<a href="\{\{ site.seo.sitemapUrl \}\}">Sitemap</a>`
`site.seo.robotsUrl`	`string`	Absolute URL to the store’s robots.txt rule map.	`<a href="\{\{ site.seo.robotsUrl \}\}">Robots</a>`

Generate responsive headers, context sidebars, and footer sections using structured arrays:

site.navigation (array): A nested list of primary navigation menu items. Each item contains:
- title (string): Menu name.
- url (string): Relative or absolute link target.
- active (boolean): Flags if the shopper is currently visiting this page.
- children (array): Sub-menu items (follows the exact same schema for nested dropdowns).
site.footerElements (array): Structured array containing lists of URLs and link titles intended for footer grids.

{# Generating a multi-tier main navigation menu #}
<ul class="nav-menu">
  {% for item in site.navigation %}
    <li class="nav-item {% if item.active %}is-active{% endif %}">
      <a href="{{ item.url }}">{{ item.title }}</a>
      
      {% if item.children is not empty %}
        <ul class="nav-dropdown">
          {% for child in item.children %}
            <li class="dropdown-item {% if child.active %}is-active{% endif %}">
              <a href="{{ child.url }}">{{ child.title }}</a>
            </li>
          {% endfor %}
        </ul>
      {% endif %}
    </li>
  {% endfor %}
</ul>

4. Active Design Elements & Theme Customization (`site.themeSettings`)

Allows access to structural design inputs and layout parameters:

site.themeSettings (array): Contains configured settings grouped by page elements:
- site.themeSettings.header: Specific customization attributes for headers.
- site.themeSettings.footer: Footer-specific attributes (e.g., column layout sizes, payment icons).
- site.themeSettings.homepage: Layout configuration lists for the front page.
- site.themeSettings.design: General design parameters (e.g., font family, global spacing margins).
site.designSettings (array): The raw, un-grouped design variables array.
site.customTheme (array): Meta attributes describing the theme file itself (version, author, target keys).

5. Custom HTML Injectors

Merchants can append third-party scripts (e.g., Google Tag Manager, custom trackers, Live Chat widgets) via the SitePack Admin. Your theme layouts must render these blocks in their appropriate positions:

site.customHtml.css: Code blocks to render inside a <style> container in the header.
site.customHtml.htmlHead: Script tags, verification tags, or styling links injected before the closing </head>.
site.customHtml.htmlBody: Script blocks to inject immediately after the opening <body> tag.
site.customHtml.htmlCart: Special scripts loaded strictly on the checkout and cart templates.
site.customHtml.htmlCheckout: Specific scripts designed to trigger on successful conversion/checkout pages.

6. Dynamic Store Settings & Policies

site.popUp (object): Interactive promotional popup config containing:
- popUp.active (boolean): True if active.
- popUp.title (string), popUp.content (string): Markup elements.
- popUp.backgroundColor, popUp.titleColor, popUp.contentColor (hex strings).
site.legalPolicies (array): Complete listing of active legal documentation. Each policy object has:
- title (string): e.g., "Privacy Policy".
- slug (string): url-friendly slug.
- url (string): absolute link.
- content (string): raw rich-text HTML block.
site.getSetting('key') (method): Retrieve a specific global store setting value. For example, to pull the company email: {{ site.getSetting('contact_email') }}

The `product` Object (`ProductApiModel`)

The product object is dynamically injected and available inside catalog listings (templates/category.twig) and single details pages (templates/product.twig). It provides comprehensive attributes and methods regarding inventory, pricing models, SEO, media, brand mapping, and variant structures.

1. Core Identity & Basic Properties

Attribute / Getter	Return Type	Description / Usage	Code Example
`product.id`	`integer`	The primary, unique database ID of the product.	`\{\{ product.id \}\}`
`product.uuid`	`string`	The global universally unique identifier string.	`\{\{ product.uuid \}\}`
`product.name`	`string`	Full display name of the product.	`<h1>\{\{ product.name \}\}</h1>`
`product.nameWithoutBrand`	`string`	Product name with the manufacturer/brand name excluded.	`\{\{ product.nameWithoutBrand \}\}`
`product.slug`	`string`	URL-safe representation of the product.	`\{\{ product.slug \}\}`
`product.url`	`string`	The relative storefront path to the product page.	`<a href="\{\{ product.url \}\}">`
`product.canonical`	`string`	The official absolute canonical URL of the product.	`<link rel="canonical" href="\{\{ product.canonical \}\}">`
`product.brand`	`string`	Name of the brand / manufacturer.	`<span class="brand">\{\{ product.brand \}\}</span>`
`product.model`	`string`	Specific model designation or serial string.	`Model: \{\{ product.model \}\}`
`product.sku`	`string`	Stock Keeping Unit identifier.	`SKU: \{\{ product.sku \}\}`
`product.upc`	`string`	Universal Product Code (barcode value).	`UPC: \{\{ product.upc \}\}`
`product.upcParent`	`string`	Barcode value of parent product (for child variants).	`\{\{ product.upcParent \}\}`
`product.condition`	`string`	Condition rating (e.g., `new`, `refurbished`, `used`).	`Condition: \{\{ product.condition \}\}`
`product.importSource`	`string`	The channel provider through which the product was imported.	`Source: \{\{ product.importSource \}\}`

2. Gallery Media, Copy & Descriptions

Attribute / Getter	Return Type	Description / Usage	Code Example
`product.image`	`string`	URL to the primary/featured product image.	`<img src="\{\{ product.image \}\}">`
`product.images`	`array`	Flat array of URLs containing all catalog gallery images.	`\{\% for img in product.images \%\}`
`product.video`	`string`	(Optional) URL to an embedded product trailer or promo video.	`<iframe src="\{\{ product.video \}\}"></iframe>`
`product.description`	`string`	Full rich HTML content describing the item.	`<div class="desc">\{\{ product.description \| raw \}\}</div>`
`product.shortDescription`	`string`	A concise plain-text excerpt summarizing features.	`<p class="teaser">\{\{ product.shortDescription \}\}</p>`
`product.pdf`	`string`	(Optional) Absolute URL to catalog manual or datasheet PDF.	`<a href="\{\{ product.pdf \}\}">Download Manual</a>`

3. Financials & Pricing Models

SitePack handles prices in two separate formats to ensure programmatic precision and design flexibility. Always use cents integers for mathematical operations and formatted floats for plain displays.

Attribute / Getter	Return Type	Description / Usage	Code Example
`product.priceCents`	`integer`	Current active selling price represented in cents (e.g., `1995` for €19.95).	`\{\{ product.priceCents \}\}`
`product.pricePromo`	`float`	Dynamic promotion discount price.	`\{\{ product.pricePromo \}\}`
`product.pricePromoCents`	`integer`	Promotion/sale price represented in cents.	`\{\{ product.pricePromoCents \}\}`
`product.priceAdvised`	`float`	Manufacturer Suggested Retail Price (MSRP) for comparison.	`\{\{ product.priceAdvised \}\}`
`product.priceAdvisedCents`	`integer`	MSRP represented in cents.	`\{\{ product.priceAdvisedCents \}\}`
`product.disableProductSales`	`boolean`	True if product is catalog-only and sales are inactive.	`\{\% if not product.disableProductSales \%\}`

{# Rendering a professional price display with compare-at badge #}
<div class="product-pricing">
  {% if product.pricePromoCents > 0 and product.pricePromoCents < product.priceCents %}
    <span class="price-old">{{ sitepack_price(product.priceCents) }}</span>
    <span class="price-current sale-price">{{ sitepack_price(product.pricePromoCents) }}</span>
    <span class="discount-badge">SAVE!</span>
  {% else %}
    <span class="price-current">{{ sitepack_price(product.priceCents) }}</span>
  {% endif %}
  
  {% if product.priceAdvisedCents > product.priceCents %}
    <small class="msrp-tag">MSRP: {{ sitepack_price(product.priceAdvisedCents) }}</small>
  {% endif %}
</div>

4. Categorization & Specifications Attributes

product.categoryMain (ProductCategoryApiModel): The core parent category model.
product.categorySub (ProductCategoryApiModel): The secondary nested sub-category model.
product.categorySubSub (ProductCategoryApiModel): The third-tier sub-sub-category model.
- Properties on ProductCategoryApiModel:
  - name (string): Display title (e.g., "Men's Apparel").
  - slug (string): URL slug.
  - url (string): Relative collection URL.
product.facets (array): A collection of structural metadata/specification attributes. Ideal for creating technical spec tables:
- facet.name (string): Attribute type (e.g., "Color", "Material").
- facet.slug (string): Unique lookup key.
- facet.values (array of strings): Assigned values (e.g., ["Red", "Blue"]).

{# Rendering a structured technical details spec table #}
<table class="specs-table">
  <thead>
    <tr><th colspan="2">Technical Specifications</th></tr>
  </thead>
  <tbody>
    <tr>
      <td>Primary Brand</td>
      <td>{{ product.brand | default('N/A') }}</td>
    </tr>
    {% for facet in product.facets %}
      <tr>
        <td>{{ facet.name }}</td>
        <td>{{ facet.values | join(', ') }}</td>
      </tr>
    {% endfor %}
  </tbody>
</table>

5. SEO Metadata Object (`product.seo`)

Retrieve specific product-level SEO metadata blocks representing the single product details page overrides:

Field Name	Return Type	Description / Usage	Code Example
`product.seo.canonical`	`string`	Specific product canonical URL.	`<link rel="canonical" href="\{\{ product.seo.canonical \}\}">`
`product.seo.metaDescription`	`string`	Product search snippet meta description.	`<meta name="description" content="\{\{ product.seo.metaDescription \}\}">`
`product.seo.openGraphDescription`	`string`	Custom Open Graph social block.	`<meta property="og:description" content="\{\{ product.seo.openGraphDescription \}\}">`
`product.seo.jsonLd`	`string`	Rich snippet JSON-LD block (including Schema.org Product/Offer markings).	`\{\{ product.seo.jsonLd \| raw \}\}`
`product.seo.customTitleTag`	`string`	Overwritten meta header title (e.g., custom brand title).	`<title>\{\{ product.seo.customTitleTag \| default(product.name) \}\}</title>`
`product.seo.mainImage`	`string`	Target sharing image URL.	`<meta property="og:image" content="\{\{ product.seo.mainImage \}\}">`
`product.seo.noIndex`	`boolean`	True if crawler indexing is explicitly blocked.	`\{\% if product.seo.noIndex \%\}<meta name="robots" content="noindex">\{\% endif \%\}`
`product.seo.allowIndex`	`boolean`	Inverse of `noIndex`, true if search indexing is authorized.	`\{\{ product.seo.allowIndex \}\}`

6. Variants & Product Bundles

product.variants (ProductVariantsApiModel): Handles complex matrices of parent-child product relationship maps (e.g., shirt sizes and color options).
- variants.totalProducts (integer): Size of the variant combination tree.
- variants.rootLevelAttributes (array): Attributes defining the split (e.g., size, color).
- variants.productCombinations (array): Maps combinations to individual variant child product IDs.
product.bundles (array): An array of related/bundled ProductApiModel objects that the merchant recommends buying together.

7. Core Dates

product.created (DateTimeInterface): Date the product was initialized on the store. Can be parsed using Twig's date filter.
product.modified (DateTimeInterface): Timestamp of the last catalog update.

Exploring Further:

Now that you have mastered the Twig data models, discover all the dynamic layout rendering utilities and math helpers inside the Custom Theme Functions Guide!

The site Object (SiteInfoApiModel)​

1. Store Identity Properties (site.site)​

2. Store Search Optimization Metadata (site.seo)​

3. Navigation Menus & Links​

4. Active Design Elements & Theme Customization (site.themeSettings)​

5. Custom HTML Injectors​

6. Dynamic Store Settings & Policies​

The product Object (ProductApiModel)​

1. Core Identity & Basic Properties​

2. Gallery Media, Copy & Descriptions​

3. Financials & Pricing Models​

4. Categorization & Specifications Attributes​

5. SEO Metadata Object (product.seo)​

6. Variants & Product Bundles​

7. Core Dates​

Exploring Further:​