Skip to content
Kea LabsKea Labs

Card Template

The Card Template is the customization surface that controls how a single product is rendered inside the search results grid and other search surfaces. It lives in the admin under the search customization area and is one of the product UI surfaces that the PrestaShop back office exposes under UI Settings.

This page explains how product-card templates work: presets, custom HTML, supported fields, allowed tags, and save/publish behavior. For the PrestaShop screen and menu path, see Card Template (PrestaShop).

What it controls

Section titled “What it controls”

A card template is a small render unit that draws one product: image, title, price, optional rating, and a small set of inline action zones (open, add to cart, find similar). The template can be one of three built-in presets, or a custom HTML fragment written against the runtime view model.

Card templates are scoped to a search surface (a “view” in the admin configuration model). The supported surfaces are:

  • Search Results Page — the product grid on the storefront search results route.
  • Search Box (Dropdown) — the inline result list rendered inside the autocomplete dropdown.

Both surfaces share the same template shape but are configured independently, so the same merchant can ship a different card on the results page from the card shown in the dropdown.

Two template modes

Section titled “Two template modes”

The Card Template editor offers two modes:

  • Preset mode — pick one of three built-in layouts. No HTML is written and no Mustache validation is needed. You should still save, check storefront preview, and publish only after the card looks correct.
  • Custom mode — write a Mustache-compatible HTML fragment against the runtime view model. The fragment must be non-empty to save a usable preview, and validation issues surface in the Preview Issues panel below the editor.

The Preset / Custom toggle is a per-surface setting: a merchant can keep the results page on a preset and write a custom card for the dropdown, or vice versa.

The three built-in presets

Section titled “The three built-in presets”
Preset Layout
Standard Vertical card with image, title, price, and rating.
Horizontal Compact horizontal card with a small image and inline details.
Simple Minimal card — title and price only, no image placeholder.

Presets are not styled at the card level. They define the layout skeleton (image placement, text alignment, action zones); colors, fonts, and spacing are still driven by the CSS variables and CSS classes the storefront runtime exposes. Switching a preset does not change theme tokens or class hooks, but it still changes what shoppers see. Check it in preview before publishing.

Custom mode: supported view-model fields

Section titled “Custom mode: supported view-model fields”

A custom template is a Mustache-compatible HTML fragment. The runtime emits the following field groups against the product view model:

product (identity)

Section titled “product (identity)”
Field Description
{{ product.id }} Product identifier
{{ product.url }} Product page URL
{{ product.title }} Product display name
{{ product.image_url }} Primary image URL
{{#product.has_image}} … {{/product.has_image}} Block shown when the product has an image
{{ product.vendor_code }} Vendor / SKU reference code
{{#product.has_vendor_code}} … {{/product.has_vendor_code}} Block shown when the vendor code is present

product (pricing)

Section titled “product (pricing)”
Field Description
{{ product.price_text }} Display price with currency symbol
{{ product.original_price_text }} Original price before discount (formatted)
{{ product.original_price }} Original price raw value
{{#product.has_discount}} … {{/product.has_discount}} Block shown when the product is discounted
{{ product.discount_percent }} Discount percentage (numeric)
{{ product.currency }} Currency code (e.g. USD)

product (availability)

Section titled “product (availability)”
Field Description
{{#product.available}} … {{/product.available}} Block shown when the product is in stock
{{ product.count }} Stock quantity (numeric)
{{ product.unit }} Stock unit label (e.g. pcs)

product.attributes (optional indexed data)

Section titled “product.attributes (optional indexed data)”

product.attributes contains the provider-backed data enabled under Settings → Data Settings → Additional product data. Missing providers produce no matching Mustache section.

Field Description
{{#product.attributes.attribute}} … {{/product.attributes.attribute}} Iterates the optional PrestaShop attribute summary. Each item exposes name and value.
{{#product.attributes.feature}} … {{/product.attributes.feature}} Iterates optional PrestaShop product features. Each item exposes name and value.

For example:

{{#product.attributes.feature}}
  <span class="kea-card__feature">{{ name }}: {{ value }}</span>
{{/product.attributes.feature}}

The search API can also return product.variants for grouped cards and product.variant for individual combination cards. Those objects are not part of the current bounded Mustache product-card view model. Do not reference them in a Card Template until the editor’s supported-field list includes them.

product (capability flags)

Section titled “product (capability flags)”
Field Description
{{#product.can_open}} … {{/product.can_open}} Block shown when the product link is available
{{#product.can_add_to_cart}} … {{/product.can_add_to_cart}} Block shown when add-to-cart is enabled
{{#product.can_find_similar}} … {{/product.can_find_similar}} Block shown when visual similarity search is enabled

labels

Section titled “labels”
Field Description
{{ labels.add_to_cart }} Localized “Add to cart” label
{{ labels.find_similar }} Localized “Find similar” label
{{ labels.vendor_code }} Localized “SKU” / vendor code label

ui

Section titled “ui”
Field Description
{{ ui.source }} Search surface identifier (e.g. resultsPage)
{{ ui.mode }} Preview or production mode flag
{{ ui.breakpoint }} Current responsive breakpoint
{{ ui.card_type }} Card type: standard | horizontal | simple
{{#ui.is_standard}} … {{/ui.is_standard}} Block when card_type is standard
{{#ui.is_horizontal}} … {{/ui.is_horizontal}} Block when card_type is horizontal
{{#ui.is_simple}} … {{/ui.is_simple}} Block when card_type is simple
{{ ui.position }} Zero-based position in the results grid
{{ ui.ratio }} Image aspect ratio for the current card type

Allowed HTML

Section titled “Allowed HTML”

The custom-template runtime accepts a fixed set of HTML tags. Anything outside that set is stripped at compile time. The allowed tags are:

  • Block: div, p, ul, ol, li
  • Inline: span, small, strong, em, s, del, ins, br
  • Links and forms: a, button
  • Media: img, picture, source

Use class, title, aria-*, data-kea-role, and data-kea-action to attach styling and behavior. The data-kea-action attribute drives the runtime action zones (open, add to cart, find similar); see the DOM markers reference for the full list.

Save and publish behavior

Section titled “Save and publish behavior”

A custom template goes through two stages:

  1. Save writes the current template settings to the preview configuration and rebuilds the preview bundle. The Preview Issues panel validates the fragment against the runtime and surfaces any errors (unclosed sections, missing required fields, disallowed tags).
  2. Publish promotes the valid preview bundle to production through the platform’s publish flow. Production should change only after the saved preview has been checked.

If validation fails — for example, the editor is in Custom mode and the fragment is empty — the preview is not usable. The editor surfaces a “Template is empty” warning inline, and the Preview Issues panel reports the validation failure so the fragment can be fixed and saved again. In that case the storefront continues to render the last successfully published template.

The Custom HTML editor is gated on a cardTemplateEditor capability on the gateway. When the capability is absent (older plugin build), the editor shows an “unavailable” notice and the mode toggle is capped to Preset. Preset changes can still be saved, previewed, and published in that state.

Section titled “Use the right surface for related changes”
  • The CSS variables that drive card colors, spacing, and radius are part of the theme tokens and the CSS variables reference. They are not edited on the Card Template page.
  • The results grid itself (columns, gap, alignment) is part of the search interface visual editor, not the Card Template.
  • The action zones (open, add to cart, find similar) are emitted by the runtime when the template uses the data-kea-action="…" attribute. They are not configured on the Card Template page.
Section titled “Related”