Products

Overview

The main products collection block that displays a grid of products with optional filtering, sorting, and pagination. This is the core block for product listing pages, category pages, and search results. It serves as a container for child blocks like filters, search, sorting controls, and the product grid itself.

Requirements

• Parent block: None (top-level block)
• BigCommerce data: Product catalog synced from BigCommerce

Configuration

Attributes

• settingsId (string) - Settings configuration identifier
  • Default: ""
• align (string) - Block alignment
  • Default: "wide"
• dropzones (object) - Dropzone configuration for child blocks
  • Default: {}
• fullPayload (object) - Complete products data payload
  • Default: {}
  • Source: attribute
• isFetching (boolean) - Loading state indicator
  • Default: false
  • Source: attribute

Block Support

• HTML editing: Not supported
• Alignment: Supported (default: wide)

Context

The Products block uses context from parent blocks:

• commerce-connect/parentCategory - Category filter from parent block

The Products block provides context to child blocks:

• commerce-connect/productsDropzones - Available dropzone positions
• commerce-connect/productsFullPayload - Complete products data
• commerce-connect/productsIsFetching - Loading state

Usage

Placement

This block can be placed on any page or template where you want to display products. Common uses include:

• Product listing pages (e.g., /shop/)
• Category pages
• Search results pages
• Homepage featured products sections

Common Patterns

From the demo video script, the Products block is highly configurable:

[Products Block]
  Products Search Box
  Products Filters (category, attributes)
  Products Sort Control
  → Products Grid ← (product cards)
  Pagination

Global settings from Commerce Connect plugin (Products tab):

• Products per page (default page size)
• Products per row on desktop (e.g., 3 columns)
• Products per row on mobile (e.g., 1 column)
• Currency display format (symbol, code, narrow, spelled out)
• Default product ordering (newest, price, name, etc.)
• Product link behavior (same tab vs. new window)

These global defaults can be overridden at the block level for specific instances.

Technical Details

CSS Classes

• commerce-connect-block - Base block class
• products-blocks - Specific block identifier
• alignwide - Default alignment class
• ecom-root - Commerce Connect root element

Data Attributes

The block includes several data attributes for JavaScript functionality:

• data-commerce-connect-block - Block type (products or singleProduct)
• data-commerce-connect-id - Unique block instance ID
• data-commerce-connect-settings - Settings JSON
• data-commerce-connect-payload - Initial products data payload
• data-commerce-connect-filters - Available filters JSON

CSS Variables

The block supports CSS variable overrides for styling. Global overrides from plugin settings are merged with block-specific settings.

Data Source

The Products block retrieves product data from WordPress® (synced from BigCommerce) using the ProductsController:

For regular product listings:

• Queries WordPress® product post type
• Applies filters (category, search, attributes)
• Applies sorting (order by, direction)
• Applies pagination (page size, current page)
• Returns products with metadata (title, price, images, etc.)

For single product view:

• Detects ?product= query parameter
• Loads specific product by slug
• Returns single product data

For filtered/searched results:

• Processes URL parameters (category, search, variant attributes)
• Retrieves available filters based on current context
• Returns filtered products and available filter options

Product data is synced from BigCommerce and stored in WordPress®. The get_items() method queries WordPress® for fast performance, while maintaining BigCommerce as the source of truth.

Available Filters

The block calculates available filters based on:

• Current category (if any)
• Current search query (if any)
• Product variations and attributes

Filters are passed to child blocks (Products Filters block) via context.

Troubleshooting

Products not displaying

• Verify products are synced from BigCommerce (check Commerce Connect > Products)
• Ensure products are published in WordPress®
• Check that BigCommerce connection is active
• Review browser console for JavaScript errors

No products message shows incorrectly

The block displays “There are no published products in your store” only when:

• No products have publish status in WordPress®
• No search query is active
• No category filter is active
• No pagination is active
• Not viewing a single product

If this message appears incorrectly, check product publish status in WordPress® admin.

Search returns no results

The block displays “No results found for [search term]” when:

• Search query is present
• No products match the search
• Products response is empty

To troubleshoot:

• Verify product titles/descriptions contain the search term
• Check that product data is fully synced from BigCommerce
• Test search in WordPress® admin to confirm products are searchable

Filters not working

• Verify Products Filters block is added as a child block
• Check that available filters are being calculated correctly
• Review URL parameters for filter selections
• Ensure filter data is passed to child blocks via context

Pagination not working

• Check page size settings (global and block-level)
• Verify total product count is correct
• Review pagination controls implementation
• Ensure page parameter is being processed correctly

Category filtering not working

• Verify category data is synced from BigCommerce
• Check that products are assigned to categories in BigCommerce
• Review parentCategory context from parent blocks
• Ensure category selection is being applied to query

Performance issues with large catalogs

• Products are queried from WordPress® (not BigCommerce API) for performance
• Consider limiting products per page for large catalogs
• Use category filtering to reduce query scope
• Implement caching if needed for frequently accessed pages