Explore the Training guides product catalog implementation

This overview walks through the product catalog implementation used in the Training guides repository. It covers content modeling decisions, reusable field schemas for building product and variant content types, and the key features of the commerce implementation — including stock tracking, catalog discounts, product listing and detail widgets, and automatic page wrapper management.

Before you start

This guide requires the following:

• Familiarity with C#, .NET Core, Dependency injection, and the MVC pattern.
• Understanding of Page Builder, Reusable field schemas, and Taxonomies in Xperience by Kentico.
• A running instance of Xperience by Kentico, preferably 30.11.1 or higher.
  Some features covered in the training guides may not work in older versions.

Terminology

Before we start, let’s establish a few terms for different product types that we will use throughout this overview.

Product variants - distinct versions of a given product based on attributes such as size and color, that merit a distinct entity.

Parent products - products which have variants. Parent products are often abstract, providing info that is shared among their variants and representing the relationship between variants, but they cannot be directly purchased or stocked.

Basic products - products which do not have variants. Basic products are top-level products like parent products, but they are not abstract. They directly represent something that can be purchased.

Content querying and content modeling

With any content management platform, you must decide how to structure data. If you are a developer, you may feel tempted to leave content modeling totally in the hands of solution architects or project managers, but it is important to understand how modeling decisions affect both your development tasks and the ease of delivering a functional project.

When you design infrastructure-specific content types that exist within a digital experience platform like Xperience by Kentico, it is important to consider the strengths and friction points of that platform: will the design allow editors to easily work with the content? Does the platform have a straightforward way to query and display a given model, or will it create extra development work?

With the Training guides commerce implementation, our content modeling approach had the following goals:

• Store products in the Content hub, using page wrappers to display them in web channels
• Use separate content items to represent product variants
• Ensure developers can easily query products of multiple content types based on a variety of parameters
• Minimize unused, inapplicable fields during the editing process to prevent confusion

Let’s outline scenarios that prioritize editor usability and data querying efficiency, then examine the solution the Training guides model uses to balance them.

Choose a balanced modeling strategy

public bool ProductHasVariants(IProductSchema product)
{
    if (product is IProductParentSchema parentProduct)
    {
        return parentProduct.ProductParentSchemaVariants.Any();
    }

    return false;
}

private async Task<ProductViewModel> GetCatFoodViewModel(CatFood catFoodProduct, CatFoodVariant? catFoodVariant)
{
    // Shared logic that does most of the work based on shared schemas
    var model = await GetGenericProductViewModel(catFoodProduct, catFoodVariant);

    // Small addition to include a type-specific field that is not from a schema
    model.ProductOtherDetails = new HtmlString
            (("Ingredients:<br/>" + string.Join("<br/>", catFoodVariant?.CatFoodVariantFormulation
                .Select(formulation => formulation.PetFoodFormulationIngredients) ?? []))
            ?? string.Empty);

    return model;
}

Training guides commerce schemas

You likely noticed that the Training guides product model relies heavily on reusable field schemas. The schemas act as building blocks to create our individual product content types, and allow us to compose most of each content type with minimal type-specific fields. Let’s take a closer look at how they work.

Application

Let’s contextualize these schemas with an example. Imagine you are creating content types to represent T-shirt products and their variants. (We’ll use a ✓ icon to indicate that a given schema is broadly recommended, and a ? icon to indicate that a schema could apply depending on the given scenario.)

• T-shirt (parent product)
  • ✓ Product schema for basic name, image, etc.
  • ✓ Product parent schema so we can create variants for different sizes and colors
  • ? Product price schema to store price if all sizes and colors cost the same, and should not be possible to separately discount
  • ? Product shipping schema to set shipping info if the weight difference between shirt sizes is not large enough to affect shipping costs
  • ✓ Material schema so customers can filter the product listing by material
• T-shirt variant
  • ✓ Product schema for basic name, image, etc. (each color variant, at least, will need its own name and image)
  • ✓ Product variant schema to make the different sizes and colors selectable as variants of a parent product
  • ✓ Product SKU schema to track the available stock of a specific variant
  • ? Product price schema to store price if sizes and colors have different prices, or should be possible to separately discount
  • ? Product shipping schema to set shipping info if the different variants will have different shipping costs
  • ✓ Color/pattern schema to represent the color of a specific variant and allow filtering in product listings
  • ✓ Size schema to represent the size of a specific variant and allow filtering in product listings

Let’s examine how these might apply at a more general level, with the terminology from earlier:

• Parent products should implement the Product schema and the Product parent schema, but not the Product variant schema.
• Variants should implement the Product schema and the Product variant schema, but not the Product parent schema.
• Basic products should implement the Product schema but neither the Product parent schema nor the Product variant schema.

Browse the catalog

Now that we’ve gone over the content model for products, let’s start with a video tour of the implementation, followed by additional information on the key components in the text below.

Stock module

The finished branch of the Training guides repository includes a basic stock tracking example similar to the documentation’s example, with some minor name changes and code style adjustments.

The Training guides module makes the following key changes:

• A class override, which configures the stock class for Continuous Integration
• A field to hold the SKUCode value directly in the available stock class, to reduce extra querying in a hypothetical integration with warehouse inventory software
• Additional handlers for draft updates and deletion, to avoid orphaned stock when content items are deleted, and keep SKU codes up to date
• Evaluation based on the Product SKU Schema (IProductSkuSchema) to determine whether to create a stock entry

See the code files behind the custom stock module in the repo:

• Product stock admin files
• Product stock event handler

Catalog discount

The implementation includes a taxonomy-based catalog discount, as described in Catalog discount documentation, operating based on the ProductPriceSchemaDiscountCategory field of the Product price schema.

This allows editors to tag products for specific sale and discount events, such as Anniversary sale or Holiday special. Then, they can reference the same taxonomy tags from a catalog discount with its own start and end dates, meaning the discount will automatically stop affecting the product without the need to remove tags.

See the code files for catalog discounts in the repository:

• Code files for catalog discount

Product widgets

The Training guides product catalog contains widgets that handle product display, both for listing and detail scenarios. We created both widgets using the KentiCopilot widget creation tools and refined them further with AI assistance using the documentation MCP server for context.

Listing widget with filtering

The Product listing widget displays an array of ProductPage wrappers that live under the page where it exists, or under a specified page, depending on editor configuration. It allows editors to specify how member-only pages are handled, and to configure CTA text for products and sign-in.

It includes taxonomy-based filtering that uses AND or OR logic between categories, depending on editor configuration. The filtering operates on taxonomies applied to product types via the Material schema and Color/Pattern schema, and in cases of parent/variant products, filters on the attributes of both.

See the listing widget’s code in the Training guides repo:

• Listing widget code files
• Listing widget JavaScript

Detail widget

The Product widget displays the details of a product, allowing editors to choose between the page the widget exists on and a selectable ProductPage. It handles both basic products and parent products with variants. Editors can also configure whether variants are displayed, whether to include variant detail text, and an optional call-to-action link.

If the product has multiple images, customers can click through the gallery. If the product has variants and the widget is set to display them, they can click between variant thumbnails.

Find the code behind the Product widget in the repository:

• Product widget code files

Product service

The ProductService underlies much of the key functionality in both widgets, handling data retrieval, filtering, secured content, and view model assembly.

Explore the product service’s code in the repo:

• Product service

Automatic page wrapper module

The product catalog implementation includes an event handler that automatically manages page wrappers for content hub products, saving editors from tedious busywork. It creates, publishes, unpublishes, and deletes ProductPage pages, manages their parent StoreSection pages, and automatically assigns page templates containing the aforementioned listing and detail widgets via API.

The handler reacts to both basic products and parent products, but not variants.

Look over the page wrapper handler code in the Training guides repository:

• Product page wrapper handler

What’s next?

Clone and run the finished branch of the Training guides repository to see these features in action.

For more commerce-related topics from the architecture standpoint, take a look at:

• Model Page Builder components for commerce
• Upgrade - Commerce features overview

If you haven’t already, check out our other commerce-related guides for developers:

• Create product page wrappers for Content hub products
• Implement faceted filtering for product catalog

If you have any questions or scenarios you’d like us to cover in the future, please let us know with the Send us feedback button at the bottom of this page.