Skip to main content

Template Hooks & App Blocks

To build a thriving, modular e-commerce ecosystem, SitePack themes must be fully compatible with third-party applications (such as review aggregators, loyalty programs, search boosters, and custom banners).

SitePack accomplishes this integration using Template Hooks paired with App Blocks. By embedding lightweight, semantic hooks in standardized layout coordinates across your theme files, you reserve structural space for apps to inject dynamic HTML, stylesheets, and scripts seamlessly.

Architectural Concept: How App Injection Works​

┌──────────────────────────────────────────────┐
│             sitepack-app.json                │
│  (App declares target: product_price_after)  │
└──────────────────────────────────────────────┘
                       │
                       ▼ (Injected at compile-time)
┌──────────────────────────────────────────────┐
│          templates/product.twig              │
│  ...                                         │
│  <h3>{{ sitepack_price(product.priceCents) }}</h3>  │
│  {% app_block 'product_price_after' %}       │ <── App renders review stars here!
│  ...                                         │
└──────────────────────────────────────────────┘

When a merchant installs an app, the app can hook into any of our predefined standard coordinates. During page compilation, the SitePack engine checks which apps are installed and maps their content directly into the corresponding {% app_block %} tags in your template files.

This process is server-side and edge-cached, meaning zero performance drag or client-side layout shifts (CLS) commonly seen in client-side script tag injectors.

Technical Syntax: Implementing Hooks​

To define a layout injection coordinate inside your Twig templates, use the custom {% app_block 'hook_name' %} block tag:

{# Defining an injection block inside snippets/product-card.twig #}
<div class="product-card-info">
    <h3 class="card-title">{{ product.name }}</h3>
    
    {# Let reviews apps inject star ratings directly beneath the title #}
    {% app_block 'product_card_info_after' %}
    
    <span class="price">{{ sitepack_price(product.priceCents) }}</span>
</div>

Exhaustive Coordinates Directory​

To pass our platform quality review and list your theme on the public SitePack Theme Marketplace, you must implement the following standard hook points in their corresponding template files:

1. Global Core Hooks (layouts/base.twig)​

These hooks manage global scripts, font loader links, analytics pixels, cookie managers, and customer tracking integrations:

  • head_after: Place this immediately before the closing </head> tag.
  • body_start: Place this immediately after the opening <body> tag.
  • body_end: Place this immediately before the closing </body> tag (and after footer modules).

2. Header Snippet Hooks (snippets/header.twig)​

  • header_before: Renders immediately preceding the opening <header> markup element.
  • header_after: Renders immediately following the closing </header> markup element.
  • footer_before: Renders immediately preceding the opening <footer> element.
  • footer_after: Renders immediately following the closing </footer> element.

4. Homepage Hooks (templates/index.twig)​

  • index_before: Positioned at the very top of the homepage content (e.g., for announcement banners).
  • index_after: Positioned at the absolute bottom of the homepage (e.g., for Instagram feeds).

5. Product Details Template Hooks (templates/product.twig)​

These are highly active coordinates, heavily utilized by dynamic e-commerce widgets:

  • product_details_before: Renders at the start of the product's primary info card.
  • product_details_after: Renders at the absolute end of the product detail sheet.
  • product_image_before: Positioned before the primary image carousel.
  • product_image_after: Positioned immediately beneath the image carousel (ideal for gallery zoom extensions).
  • product_price_before: Positioned before the product price display block.
  • product_price_after: Positioned immediately following the price (perfect for product-level payment installment details).
  • product_description_before: Renders immediately before the rich-text product description.
  • product_description_after: Renders immediately after the product description block.
  • product_form_before: Positioned inside the buy-box form, directly before input elements (e.g., size dropdowns).
  • product_form_after: Positioned inside the buy-box, directly after the "Add to Cart" CTA (great for stock alert badges).

6. Catalog Listing Hooks (templates/category.twig)​

  • category_before: Renders at the very top of the collection list, before description grids.
  • category_after: Renders at the bottom of the collection view, after the pagination controls.

7. Product Card Snippet Hooks (snippets/product-card.twig)​

  • product_card_before: Renders immediately preceding the wrapping .product-card card element.
  • product_card_after: Renders immediately following the card's ending </div>.
  • product_card_image_before: Positioned right before the product thumbnail image container.
  • product_card_info_before: Positioned before the title/price info region of the card.
  • product_card_info_after: Positioned after the title/price information region.

8. Shopping Cart Hooks (templates/cart.twig)​

  • cart_before: Positioned above the shopping cart line item grid.
  • cart_after: Positioned below the main cart section.
  • cart_item_before: Renders inside the cart loop, directly before each item row.
  • cart_item_after: Renders inside the loop, directly after each item row.
  • cart_item_image_before: Positioned inside the line-item thumbnail container.
  • cart_item_image_after: Positioned after the item thumbnail.
  • cart_item_quantity_before: Positioned before the line item quantity numeric adjustments.
  • cart_item_quantity_after: Positioned after the quantity adjustments.
  • cart_buttons_after: Positioned adjacent to or immediately beneath the primary "Proceed to Checkout" buttons (ideal for safe-checkout badges).

9. Editorial Blog & Post Hooks (templates/blog.twig & templates/article.twig)​

Maintain app compatibility across your blog layouts:

  • blog_before: Appends to the top of the collection posts grid page.
  • blog_after: Appends to the bottom of the collection posts page.
  • blog_article_before: Precedes each single article summary card in the list loop.
  • blog_article_after: Follows each single article summary card in the list loop.
  • blog_article_image_before: Renders above the article thumbnail.
  • blog_article_image_after: Renders below the article thumbnail.
  • article_before: Renders at the very top of a single post template view.
  • article_after: Renders at the absolute bottom of a single post template view (great for comments apps).
  • article_image_before: Placed above the main post banner image.
  • article_image_after: Placed below the main post banner image.
  • article_content_before: Renders immediately before the post's HTML content.
  • article_content_after: Renders immediately after the post's HTML content.
  • article_tag_before: Precedes post tag lists.
  • article_tag_after: Follows post tag lists.

10. Customer Portal / Accounts Hooks (templates/account.twig)​

  • account_before: Positioned at the header of the customer dashboard.
  • account_after: Positioned at the footer of the customer portal.
  • account_dashboard_start: Renders inside the home tab container.
  • account_dashboard_end: Renders at the closing point of the home tab container.
  • account_order_before: Renders above the order history table.
  • account_order_after: Renders below the order history list.
  • account_address_before: Positioned before the customer address-card list.
  • account_address_after: Positioned after the customer address-card list.

11. Static Content Hooks (templates/page.twig)​

  • page_before: Placed above the standard title heading of static content pages.
  • page_after: Placed below the standard text container of static content pages.

12. Error Views Hooks (templates/404.twig)​

  • error_404_before: Renders above the standard 404 message block.
  • error_404_after: Renders below the standard 404 navigation recovery links.

Exploring Further:​

Now that you have configured modular app blocks, learn how to localize your templates into multiple languages in the Theme Translations Guide!