Template Hooks

Hook Lifecycle Flow

1. Section Initialization Phase

onSectionInit is called when section is first created
- Sets up initial state and variables
- Configures section parameters
- Registers event listeners

2. Data Fetching Phase

getProductDetailsQuery is called to prepare GraphQL query
- Defines required product fields
- Sets up query variables
- Configures custom data requirements
- Sets up filtering parameters

3. Data Processing Phase

postProductFetch processes raw product data
- Filters products if needed
- Adds computed properties
- Transforms data structure
transformProductData transforms individual product data
- Normalizes data format
- Adds custom fields
- Prepares for rendering

4. Rendering Phase

afterSectionRendered is called once section is rendered on the page and ready to be used. Note: This is an optional hook, if you want to perform certain task, you can add your logic in this hook.
initSwiper (if carousel is enabled)
- Configures carousel settings
- Sets up navigation
- Initializes responsive behavior
- Sets up pagination

5. Interaction Phase

onVariantChange handles variant selection Note: This is an optional hook, if you want to perform certain task, you can add your logic in this hook.
onSwatchChange handles swatch interactions Note: This is an optional hook, if you want to perform certain task, you can add your logic in this hook.

6. Cart Operation Phase

beforeAddToCart validates cart operations
- Validates product selection
- Modifies cart payload
- Handles quantity validation
afterAddToCart handles post-cart updates Note: This is an optional hook, if you want to perform custom logic, you can setup your logic in this hook.

Available Hooks

1. onSectionInit

Purpose:
Primary initialization hook called when a section is first created. Parameters:

args contains:
- recommendation object which includes:
  - section containing section ID, layout type, title, and discount configuration
  - Array of products with product data
- engine object containing:
  - Engine name and version
  - Engine-specific configuration
- initEnginePayload containing engine initialization data
cb (Callback Function):
- Receives the processed recommendation object
- Used to handle initialization completion
- No return value expected
gloodUtils provides:

Function	Description
`formatMoney`	Formats price values according to store’s money format
`optimizeImage`	Optimizes image URLs with specified dimensions and crop settings
`getVariantFromOptions`	Finds a variant based on selected options
`findVariantById`	Retrieves a variant using its ID
`getSelectedVariant`	Gets currently selected variant for a product
`getDefaultVariant`	Returns the default/first available variant
`addToCart`	Handles adding items to cart with proper validation
`updateCart`	Updates existing cart items (quantity, properties)
`getProductUrl`	Generates product URL with tracking parameters
`getDiscountedPrice`	Calculates discounted price based on rules
`formatDiscount`	Formats discount text with proper currency/percentage
`getTranslation`	Retrieves translated text with fallback support
`trackEvent`	Sends tracking events to analytics
`refreshSection`	Re-renders section with updated data
`showNotification`	Displays toast/notification messages

Example:

onSectionInit: (args, cb, gloodUtils) => {
    const { recommendation, engine, initEnginePayload } = args;
    cb({
        recommendation,
        engine,
        initEnginePayload,
    });
}

Use Cases:

Section configuration
State initialization
Event listener setup
Feature initialization
Engine configuration

2. getProductDetailsQuery

Purpose:
Builds the GraphQL query for fetching product data. Parameters:

recommendation contains:
- section object with:
  - id (number): Unique section identifier
  - layout (String): Section layout type
  - discount_config (Object): Discount settings
  - widget_message (String): Custom message template
- products (Array): Currently loaded products
- template (Object): Template-specific settings
glood provides:
- shop object containing:
  - money_format (String): Store currency format
  - locale (String): Store language code
- product object with:
  - id (String): Current product context (format: “gid://shopify/Product/”)
  - handle (String): Product URL handle
- localization settings for:
  - Currency formatting
  - Language preferences
  - Regional settings

Returns:
GraphQL query string containing required product fields Example:

getProductDetailsQuery: (recommendation, glood) => {
    return `
        featuredImage {
            url
        }
        handle
        id
        title
        availableForSale
        priceRange {
            minVariantPrice {
                amount
                currencyCode
            }
        }
        compareAtPriceRange {
            minVariantPrice {
                amount
                currencyCode
            }
        }
        variants(first: 250) {
            nodes {
                id
                price {
                    amount
                    currencyCode
                }
                availableForSale
                // ... other variant fields
            }
        }
    `;
}

Use Cases:

Product data fetching
Field selection
Query customization
Data filtering
Performance optimization

3. postProductFetch

Description:
Processes raw product data after fetching. Allows for data transformation and enrichment before rendering. Parameters:

args (Object):
- products (Array): Raw product data array
- recommendation (Object): Section configuration
- template (Object): Template settings
utils (Object): Helper functions

Returns:
Array - Processed product data Example:

postProductFetch: (args, utils) => {
    const { products, recommendation, template } = args;
    return products.map(product => ({
        ...product,
        formattedPrice: utils.formatMoney(product.price),
        hasDiscount: product.compare_at_price > product.price,
        isAvailable: product.variants.nodes[0].availableForSale,
        imageUrl: utils.optimizeImage(product.featured_image, template.settings)
    }));
}

Use Cases:

Price formatting
Discount calculations
Image optimization
Availability checks
Data enrichment

4. transformProductData

Purpose:
Transforms raw GraphQL product data into template-friendly format. Parameters:

product (Raw GraphQL data) contains:
- Basic information:
  - id (String): GraphQL product ID (format: “gid://shopify/Product/”)
  - handle (String): Product URL handle
  - title (String): Product title
  - vendor (String): Product vendor
- Images:
  - featuredImage (Object): Main product image
  - images (Object): Additional product images
- Pricing:
  - priceRange (Object): Min/max prices
  - compareAtPriceRange (Object): Original prices
- Variants:
  - variants (Object): Product variants data
  - variantsCount (Object): Total variants count
- Options:
  - options (Array): Product options
  - selectedOptions (Array): Default selections
- Status:
  - availableForSale (Boolean): Stock status
  - tags (Array): Product tags
recommendation provides:
- section settings:
  - Display configuration
  - Pricing rules
  - Layout settings
  - Tracking configuration

Returns:
Product object containing:

Normalized product data
Formatted prices
Processed images
Structured variants
Computed fields

Example:

transformProductData: (product, recommendation, utils) => {
    return {
        ...product,
        trackingData: utils.generateTrackingData(product, recommendation),
        variants: product.variants.map(variant => ({
            ...variant,
            formattedPrice: utils.formatMoney(variant.price),
            isAvailable: variant.inventory_quantity > 0
        })),
        labels: utils.generateProductLabels(product, recommendation.settings)
    };
}

Use Cases:

Tracking setup
Variant processing
Label generation
Price formatting
Custom field addition

5. initSwiper

Purpose:
Initializes and configures the carousel/slider functionality for sections using Swiper.js. Parameters:

Swiper (Constructor Class):
- Swiper.js constructor
- Used to create carousel instances
- Handles slide functionality
- Manages touch events
- Controls navigation
templateSettings contains:
- template.settings with:
  - carousel (Object): Carousel-specific settings
  - breakpoints (Object): Responsive configuration:
    - small (Object): Mobile settings
    - medium (Object): Tablet settings
    - large (Object): Desktop settings
  - Each breakpoint contains:
    - screenSize (Number): Width breakpoint
    - cardsPerView (Number): Visible slides
    - gutter (Number): Space between slides
container (HTMLElement):
- Root section element
- Contains carousel structure:
  - Wrapper element
  - Slide elements
  - Navigation buttons
  - Pagination dots
params contains:
- recommendation:
  - section (Object): Section configuration
  - products (Array): Product data
  - Layout settings
- Template-specific parameters
defaultSettings contains:
- Default Swiper configuration:
  - Navigation options
  - Pagination settings
  - Autoplay configuration
  - Effect settings
  - Loop behavior
utils provides:
- merge: Deep object merging
- DOM manipulation helpers
- Event handling utilities
- Error handling functions

Returns:

Swiper instance if initialization succeeds
undefined if initialization fails

Example:

initSwiper: (Swiper, templateSettings, container, params, defaultSettings, utils) => {
  const carouselContainer = container.querySelector('._gai-crz-cnt');
  if (!carouselContainer) {
    console.error('GLOOD.AI:ERROR: Carousel container not found for section', params.recommendation.section.id);
    return;
  }
  
  const settings = templateSettings?.carousel?.swiperConfig || {};
  const swiperConfig = utils.merge(defaultSettings, settings);
  const breakpoints = Object.values(templateSettings.breakpoints).reduce(
    (acc, curr) => ({
      ...acc,
      [curr.screenSize]: {
        slidesPerView: curr.cardsPerView,
        spaceBetween: curr.gutter,
      },
    }),
    {}
  );
  
  return new Swiper(carouselContainer, utils.merge(swiperConfig, { breakpoints }));
}

6. onVariantChange

Purpose:
Handles product variant selection changes and updates the UI. Parameters:

args contains:
- variant information:
  - Basic details: ID, price, compare price
  - Image information with source and alt text
  - Availability status and quantity
  - Selected options (color, size, etc.)
- Complete product data
- DOM container element for the product card
utils provides:
- Price formatting functions
- Image update utilities
- Price display update functions
- Other UI manipulation helpers

7. onSwatchChange

Purpose:
Handles swatch selection events and updates product display accordingly. Parameters:

args contains:
- option object with:
  - name (String): Option name (e.g., “Color”, “Size”)
  - value (String): Selected option value
  - type (String): Swatch type (color/size/material)
  - swatchImage (String, optional): Custom swatch image URL
- product object containing:
  - variants (Array): All product variants
  - options (Array): Available option types
  - selectedVariant (Object): Currently selected variant
  - images (Array): Product images
- container (HTMLElement): Product card DOM element
utils provides:
- updateSwatchUI: Updates swatch selection state
- findMatchingVariant: Finds variant by options
- updateProductImage: Updates product image
- updatePriceDisplay: Updates price display
- Event tracking utilities

Returns:
void

8. onCartOperationComplete

Purpose:
Handles post-cart operation tasks and updates UI accordingly. Parameters:

args contains:
- operation (String): Type of operation (‘add’|‘update’|‘remove’)
- response object with:
  - cart (Object): Updated cart state
  - items (Array): Modified cart items
  - total (Number): New cart total
  - count (Number): Updated item count
- section containing:
  - Section configuration
  - Template settings
  - Tracking data
- container (HTMLElement): Section container
utils provides:
- updateCartUI: Updates cart display
- showNotification: Displays notifications
- updateInventory: Updates stock status
- Animation utilities
gloodUtils provides:
- trackCartEvent: Analytics tracking
- formatCartData: Data formatting
- updateShopifyCart: Cart sync utilities
- Store-specific helpers

Returns:
void

9. validateCartOperation

Purpose:
Validates and potentially modifies cart operations before execution. Parameters:

payload contains:
- Array of items being added/modified:
  - Product identifier
  - Variant identifier
  - Quantity
- Additional cart-specific data
recommendation provides:
- section configuration
- Product data
- Template settings
utils and gloodUtils:
- Validation helpers
- Cart operation utilities
- Format and transformation functions

Returns:

Modified payload if valid
Error message if validation fails
Optional redirect URL

10. onProductDataReceived

Purpose:
Processes raw product data before transformation and rendering. Parameters:

args contains:
- products array with raw product data:
  - id (number): Product identifier
  - title (String): Product title
  - handle (String): Product URL handle
  - featuredImage (Object): Main product image
  - variants (Array): Raw variant data
  - options (Array): Product options
  - tags (Array): Product tags
- section object with:
  - Layout configuration
  - Discount settings
  - Template rules
  - Display settings
- template containing:
  - Breakpoint settings
  - Card configuration
  - Image dimensions
  - Price display rules
utils provides:
- processImages: Image optimization utilities
- formatProductData: Data formatting helpers
- validateProducts: Data validation functions
- enrichProductData: Data enrichment utilities
- handleErrors: Error handling functions

Returns:
void

11. loadAjaxCart

Purpose:
Determines when to load the AJAX cart section by checking if the AJAX cart is active. Parameters:

bodyElem (HTMLElement):
- The document body element
- Provides access to AJAX cart state

Returns:
Boolean - True if AJAX cart is active and should be loaded Example:

loadAjaxCart: (bodyElem) => {
    const ajaxCart = bodyElem.querySelector('cart-drawer');
    return ajaxCart.classList.contains("active");
}

Use Cases:

Update recommendations dynamically when products are added to cart

12. unloadAjaxCart

Purpose:
Determines when to unload the AJAX cart section by checking if the AJAX cart is inactive. Parameters:

bodyElem (HTMLElement):
- The document body element
- Provides access to AJAX cart state

Returns:
Boolean - True if AJAX cart is inactive and should be unloaded Example:

unloadAjaxCart: (bodyElem) => {
    const ajaxCart = bodyElem.querySelector('cart-drawer');
    return !ajaxCart.classList.contains("active");
}

Use Cases:

Control AJAX cart unloading timing
Clean up cart resources
Manage AJAX cart states
Handle cart closure events

Hook Dependencies

Required Utils

formatMoney: Price formatting
getVariantById: Variant lookup
updateUrl: URL manipulation
merge: Object merging
imageOptimizer: Image optimization

Global Context

glood: Store configuration
translations: Text strings
template: Template settings
section: Section configuration
utils: Common utilities

Hook Flow Dependencies

transformProductData needs data from getProductDetailsQuery
afterSectionRendered needs data from transformProductData
Cart operations need data from onVariantChange
Swiper needs container from afterSectionRendered

Error Handling

Each hook should handle these critical errors:

Carousel Initialization Errors

// Critical: Section won't render if carousel container is missing
if (!carouselContainer) {
  console.error('GLOOD.AI:ERROR: Carousel container not found for section', params.recommendation.section.id);
  return;
}

Product Data Transformation Errors

// Critical: Invalid product data will break the section
if (!product.variants?.nodes) {
  console.error('GLOOD.AI:ERROR: Invalid variant data structure for product', product.id);
  return {
    ...product,
    variants: [],
    available: false
  };
}

GraphQL Query Response Errors

// Critical: Missing required fields will cause rendering issues
if (!product.priceRange?.minVariantPrice?.amount) {
  console.error('GLOOD.AI:ERROR: Missing price data for product', product.id);
  return null;
}

These errors require immediate attention as they:

Prevent sections from rendering correctly
Break core product functionality
Impact the shopping experience
Can cause JavaScript runtime errors

Support

If you need help with creating or customizing section templates, contact our support team at support@glood.ai

For Developers

​Template Hooks

​Hook Lifecycle Flow

​1. Section Initialization Phase

​2. Data Fetching Phase

​3. Data Processing Phase

​4. Rendering Phase

​5. Interaction Phase

​6. Cart Operation Phase

​Available Hooks

​1. onSectionInit

​2. getProductDetailsQuery

​3. postProductFetch

​4. transformProductData

​5. initSwiper

​6. onVariantChange

​7. onSwatchChange

​8. onCartOperationComplete

​9. validateCartOperation

​10. onProductDataReceived

​11. loadAjaxCart

​12. unloadAjaxCart

​Hook Dependencies

​Required Utils

​Global Context

​Hook Flow Dependencies

​Error Handling

​Support

Template Hooks

Hook Lifecycle Flow

1. Section Initialization Phase

2. Data Fetching Phase

3. Data Processing Phase

4. Rendering Phase

5. Interaction Phase

6. Cart Operation Phase

Available Hooks

1. onSectionInit

2. getProductDetailsQuery

3. postProductFetch

4. transformProductData

5. initSwiper

6. onVariantChange

7. onSwatchChange

8. onCartOperationComplete

9. validateCartOperation

10. onProductDataReceived

11. loadAjaxCart

12. unloadAjaxCart

Hook Dependencies

Required Utils

Global Context

Hook Flow Dependencies

Error Handling

Support