Product and Category Widgets
This page covers the widgets for product sliders, category tiles and carousels, the product details page, search with filters and promotion bundles. For each one it gives the steps to place it and the settings its form offers, in the words the form uses, so you can tell before you start which records and images you need to have ready. What a voucher (coupon) is, and what redeeming one records, is explained once in Voucher Management.
Your job, and the screen for it
| The job | Screen or tab | Read |
|---|---|---|
| Add one of these widgets to a page | Design Panel › Elements › Products & Categories | Configuration |
| Change a widget that is already on the page | Click it on the canvas, Design Panel › Selected Node | Its section under Configuration |
| Know which settings need an ID, JSON or rich text | Selected Node | Fields |
| Make a change reach the shop | SAVE NODE, then Publish | Configuring Widgets |
| Find out why a widget shows nothing | Troubleshooting |
Overview
The Products & Categories group in the Elements tab holds 17 widgets: categories, category-card-widget, category-filter-product-list, category-slider, category-slider-v2, category-tiles-listing, external-product-details, power-search-filter, product-category, product-details, product-filter, product-posts, product-rating, product-slider, product-slider-v2, product-sub-category, promo-bundle. Which products a widget shows is decided by a category group and a category (labels) from the catalogue, so get those right in the catalogue first — the widget only points at them. Placing, saving and publishing work the same for every widget and are explained once in Configuring Widgets in the Website Builder; this page adds what is particular to each widget.
Where it fits
| Before | These widgets | After |
|---|---|---|
| You can open the Website Builder and the page exists — User Permission Manager, Layout Instance | Placed on a page and configured | Shoppers see them on the storefront after Publish |
Screens and menus
Open a page from the Layout Manager tile. In the Design Panel, the Elements tab lists these widgets under Products & Categories, each with its one-line description; the search box matches the description too. Clicking a placed widget on the canvas opens its settings in Selected Node.
Configuration
Before you can use it
- Everything in Configuring Widgets › Before you can use it: CP Commerce Admin for your login, and the records the widgets point at.
- Check Platform before you drop a widget: it is added to that platform’s version of the page only.
categories
Category tiles grid (v2).
- In Elements, open Products & Categories (or search categories) and drag categories onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Title; Category group (pick from list); Label hdrs and layout urls (a list; each item has Category, Destination URL); Destination URL
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
category-card-widget
Category cards.
- In Elements, open Products & Categories (or search category-card-widget) and drag category-card-widget onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Category group (pick from list); Product list display page (pick a page)
- Style — Color; Background; Font; Col; Col sm; Border
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
category-filter-product-list
Product list with category filter.
- In Elements, open Products & Categories (or search category-filter-product-list) and drag category-filter-product-list onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Category (pick from list); Product list display page (pick a page); Product details page (pick a page); Category group (pick from list); Title; Color; Background color; Active background color; Active color; Scroll background color; Scroll color; Is infinite; Has margin top product name; Mobile cols; Web cols; Product limit; Show filter; Show title; Show all products; Hide add to cart; Hide favourite; Line count; Attributes (a list; each item has GUID, Icon); Load type (SCROLL / ON_BUTTON_CLICK); Multiple pricing scheme design; Checkout page (pick a page); Blur image when out of stock; Show max Qty per order; Show category image
- Fields to hide — Category name
- Icon button style — Background; Color
- Buy now styling config — Background; Color
- Add to cart styling config — Background; Color
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
Category group and Category choose the products. Web cols and Mobile cols are the width of each product out of 12 — 3 gives four products per row, 6 gives two. Show filter shows the filter bar above the products. Left empty, Product details page opens the page with the code product-details.
category-slider
Category carousel.
- In Elements, open Products & Categories (or search category-slider) and drag category-slider onto the page.
- In Selected Node, fill in the widget’s form: Title; Category Group and Select top 10 categories; Visible Items and Visible Mobile Items; Product List Display Layout; the arrow Color and Background Color, Hide Navigation Arrows; Padding, Card Background Color, Label Color and Title Color.
Under More settings at the bottom of the form:
- General — Title position; Destination URL; Hide category label
- Style — Box shadow
- Default view button — Hidden; Background; Color; Text; Font; Font size
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
category-slider-v2
Category carousel (v2).
- In Elements, open Products & Categories (or search category-slider-v2) and drag category-slider-v2 onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Title; Category group (pick from list); Visible items; Visible mobile items; Hide arrows; Product list display page (pick a page); Title position; Destination URL; Hide category label; Hide second track
- Style — Padding; Card; Label; Title text; Title color; Title font; Title font size
- Arrow — Background; Color
- Default view button — Hidden; Background; Color; Text; Font
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
category-tiles-listing
Category tiles grid.
- In Elements, open Products & Categories (or search category-tiles-listing) and drag category-tiles-listing onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Title; Category group (pick from list); Label hdrs and layout urls (a list; each item has Category, Destination URL); Destination URL; Title position; Hide arrows; Visible items; Visible mobile items; Display card; Disable right click
- Arrow — Background; Color
- View button — Position (top / bottom / left / right / center); Color; Background; Text; Font
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
external-product-details
Product details from an external source.
- In Elements, open Products & Categories (or search external-product-details) and drag external-product-details onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Whats app number
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
power-search-filter
Product search with filters.
- In Elements, open Products & Categories (or search power-search-filter) and drag power-search-filter onto the page.
- In Selected Node, fill in the widget’s form: Number of Lines for Product Name; whether to hide the add-to-cart and favourite buttons; Disable square image with Image Height; the sorting choices shoppers get (Available Sorting Function → Selected Sorting Function); Show Search Result Message; Display Attribute Icons; Show Prodct Price from Multiple Pricing Scheme; Checkout Route URL; the cart and Buy Now button colours.
Under More settings at the bottom of the form:
- General — Category (pick from list); Category group (pick from list); Title; Hide category name; Product click redirection type (COMPONENT / PAGE / CONTENT CATEGORY / EXTERNAL LINK / LAYOUT INSTANCE LINK / postGuid / postName / CATEGORY / LAYOUT INSTANCE); Disable right click; Title type (CUSTOM_TYPE / DEF_TYPE); Load type (SCROLL / ON_BUTTON_CLICK); Row item count; Has margin top product name; Blur image when out of stock; Show max Qty per order; Enable free text quantity; Enable child items Qty selection; Show variation imgs; Remarks; Hide display type option; Hide product code; Filter with product code; Show quick view
- Pricing config — Main price size; Main price size mobile; Badge color; Price centered; Color
- Icon button style — Background; Color
- On product click redirection — URL; Target window (New Tab / New Window / Same Frame); Disable product details route
- Scroller style — Scroller height; Color; Background color; Padding top; Padding bottom; Padding left; Padding right
- Scroller style › Button config — Background; Shadow; Font family; Font; Icon; Button Background; Button font; Link font
- Display button style — Color; Background
- Product card style — Box shadow; Border; Product font size; Product code color
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
product-category
Product category list.
- In Elements, open Products & Categories (or search product-category) and drag product-category onto the page.
- In Selected Node, fill in the widget’s form: Category Group and Product List Layout URL, the page a shopper is taken to after choosing a category.
Under More settings at the bottom of the form:
- General — Subcategory listing page (pick a page); Container margin top; Image height; Hide label; Hide title; Hide title on mobile; Title; Theme color; Theme background; Title and icon color; Sticky wrapper background; Sticky wrapper box shadow; Alphabet button border; Title font size; Remove has category styles; No badge design; Title center; Image object fit
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
product-details
Product details page.
- In Elements, open Products & Categories (or search product-details) and drag product-details onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Checkout page (pick a page); Enable shipping; Enable product views; Enable auth guarantee; Auth color; Disable image popup; Hide mobile add cart button; Hide mobile buy now button; Hide mobile redeem button; Hide mobile coupon buy now button; Hide membership buy now button; Hide membership add to cart button; Hide mobile membership buy now button; Hide mobile membership add to cart button; Hide web add cart button; Hide web buy now button; Hide web redeem button
- General, continued — Show vouchers; Socials (comma-separated); Hide membership calendar; Terms and conditions; Enable child items Qty selection; Enable last lablel variant Qty selection; Hide shipping method; Horizontal slider display; Enable free text quantity; Enable communication links; Show product code; Disable show item variation if not exist
- Style — Price color; Widget border radius; Margin top; Button fixed bottom; Wrapper background
- Style › Text Background style — Color; Background
- Style › Redeem to cart button — Color; Background; Border; Text
- Style › Add cart button — Color; Background; Border; Text
- Style › Buy now button — Color; Background; Border; Text
- Style › Buy now coupon button — Color; Background; Border; Text; Border radius; Width
- Style › Buy now membership item button — Color; Background; Border; Text; Border radius; Width
- Style › Shipping icon style — Color
- Style › Shipping method hover styles — Color; Background color
- Communication link json — Media (a list; each item has Name, Link); Terms and conditions
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
Shows the product named in the page’s address, so it only works when a shopper arrives by clicking a product. Give this page the code product-details and the product widgets find it without being told.
product-filter
Product filter.
- In Elements, open Products & Categories (or search product-filter) and drag product-filter onto the page.
- Selected Node shows This widget has no settings to configure. The widget reads nothing from its settings; give the node a recognisable Name if you like.
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
product-posts
Posts linked to a product.
- In Elements, open Products & Categories (or search product-posts) and drag product-posts onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Product description title; Selected product posts (comma-separated); Display title
- Style — Desktop margin
- Active title color — Color
- Non active title color — Color
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
product-rating
Product reviews and ratings.
- In Elements, open Products & Categories (or search product-rating) and drag product-rating onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Load type (SCROLL / ON_BUTTON_CLICK)
- Style — Desktop margin
- Review login button — Color; Font; Text; Background
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
product-slider
Product carousel (v1).
- In Elements, open Products & Categories (or search product-slider) and drag product-slider onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Category (pick from list); Product list display page (pick a page); Product details page (pick a page); Disable product details route; Category group (pick from list); Title; Visible items
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
Left empty, Product details page opens the page with the code product-details.
product-slider-v2
Product carousel.
- In Elements, open Products & Categories (or search product-slider-v2) and drag product-slider-v2 onto the page.
- In Selected Node, fill in the widget’s form: Title; Category Group (Label List Hdr) and Category (Label Hdr), which decide the products shown; Product List Display Layout and Product Details Layout, the pages a shopper is taken to; Number of Lines for Product Name; whether to hide the add-to-cart and favourite buttons; Display Attribute Icons; Show Prodct Price from Multiple Pricing Scheme; Checkout Route URL; the cart and Buy Now button colours; Number of Visible Items for web and for mobile; Hide Navigation Arrows.
Under More settings at the bottom of the form:
- General — Title position; Hide border; Has margin top product name; Blur image when out of stock; Show max Qty per order; Enable free text quantity; Enable child items Qty selection; Remarks; Show variation imgs; Disable product details route; Hide product code; Show quick view
- Arrow — Background; Color
- Pricing config › Pricing — Default pricing
- Pricing config › Styling — Main price size; Main price size mobile; Badge color; Price centered; Color
- Product card style — Box shadow; Border; Product font size; Product code color
- Icon button style — Background; Color
- Slider title style — Font size
- View button — Hidden; Position (top / bottom / left / right / center); Color; Background; Text; Font
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
Choose a Category inside the Category Group to narrow the slider to one category. Left empty, Product Details Layout opens the page with the code product-details.
product-sub-category
Sub-category list of a category.
- In Elements, open Products & Categories (or search product-sub-category) and drag product-sub-category onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Category group (pick from list); Product listing page (pick a page); Subcategory listing page (pick a page)
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
promo-bundle
Promotion bundle.
- In Elements, open Products & Categories (or search promo-bundle) and drag promo-bundle onto the page.
- In Selected Node, fill in the settings you need — leave the rest empty to keep the widget’s own behaviour:
- General — Item GUID; Checkout page (pick a page); Enable shipping; Enable product views; Enable auth guarantee; Auth color; Hide mobile add cart button; Hide mobile buy now button; Hide mobile redeem button; Hide mobile coupon buy now button; Hide membership buy now button; Hide membership add to cart button; Hide mobile membership buy now button; Hide mobile membership add to cart button; Show vouchers; Socials (comma-separated); Hide membership calendar
- Style — Price color; Widget border radius; Margin top; Button fixed bottom
- Style › Text Background style — Color; Background
- Style › Redeem to cart button — Color; Background; Border; Text
- Style › Add cart button — Color; Background; Border; Text
- Style › Buy now button — Color; Background; Border; Text
- Style › Buy now coupon button — Color; Background; Border; Text; Border radius; Width
- Style › Buy now membership item button — Color; Background; Border; Text; Border radius; Width
- Click SAVE NODE, then Preview and Publish (Steps 4 and 5).
Fields
The settings are listed with each widget above, in the form’s own words. Colours, lists and JSON behave as described in Configuring Widgets › Step 3.
Settings marked (pick a page) — their labels end in page — open a list of your pages when you click them and fill in the page’s address, /page/ and its code. You can also type any link instead, such as a full https:// address. Left empty, the widget uses its own default page where it has one.
The settings that pick a record, take JSON or hold rich text:
| Kind | Where | What to know |
|---|---|---|
| Typed IDs | category-filter-product-list › GUID; promo-bundle › Item GUID | No picker yet: paste the ID of the record. The form accepts any text, so copy it rather than typing it |
| Categories | categories › Category; category-filter-product-list › Category; category-tiles-listing › Category; power-search-filter › Category; product-slider › Category | Pick the product category by name; each is shown as Group › Category, and the search box finds it by either. A saved one that is not in the loaded list shows as Not in the list — saved ID …; publish, then reload, before you replace it — a reload loses unpublished changes |
| Category groups | categories › Category group; category-card-widget › Category group; category-filter-product-list › Category group; category-slider-v2 › Category group; category-tiles-listing › Category group; power-search-filter › Category group; product-slider › Category group; product-sub-category › Category group | Pick the product category group by name. A saved one that is not in the loaded list shows as Not in the list — saved ID …; publish, then reload, before you replace it — a reload loses unpublished changes |
Lifecycle and effects
SAVE NODE keeps a change in your browser tab only; Publish sends the page to the shop, and a reload before publishing loses the change. A setting left empty is not saved and the widget uses its own behaviour for it; opening a widget and saving without changes leaves its stored settings as they were. The full sequence is in Configuring Widgets › Lifecycle and effects.
Related applets
- CP Commerce Admin — decides who may publish, and holds the same pages under Layout Instance.
- Media Library — where the images these widgets show are uploaded.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The widget is empty on the shop | A record it shows is missing or inactive | Check the records its pickers point at |
| A change is gone after reload | The page was not published | Redo it and Publish before leaving |
| It shows on desktop but not on phones | It was added on a desktop platform only | Switch Platform and add it there too |
| SAVE NODE does nothing | Widget Config (JSON) holds invalid JSON | Fix or undo the JSON |
| A picker shows Not in the list — saved ID … | The record it saved was deleted, belongs to another website, or is not in the list as loaded | Publish what you have first (a reload loses unpublished changes), then reload; if it still shows, check the record before you pick a replacement |
| A picker shows The list is empty or could not be loaded | Nothing of that kind exists yet, or loading failed | Create the record first, or reload the page |
Related documentation
- Configuring Widgets in the Website Builder — placing, saving, previewing and publishing
- Website Builder — the other widget groups and the Website Builder pages