Skip to main content
Version: 3.x

Configurator-Building Forms

Version
3.x
Updated
View markdown

A functional description of the forms an admin uses to build a configurable product — what each field is for and what it affects in the running shop. Usage-centric (a behavior spec for the refactor), not implementation. For how these forms are stored/rendered, see the technical docs.

This is the core authoring workflow. The build hierarchy is:

Product → Pages → Questions → Answers, where each answer belongs to exactly one question. Pricing/weight come from Calculations, conditional behavior from Rules, and merchandising from Detail Panes and Product lists.

The same hierarchy as a picture:

Forms covered here:

  1. Product Tree (navigation/overview)
  2. Product
  3. Page
  4. Question
  5. Answer (an answer on a question)
  6. Product Detail Pane
  7. Product list (+ product assignments)

Rules and Calculations are authored from within the Question/Answer forms; their full behavior is in the rule-engine and calculation-engine docs (technical) — here we describe only the fields that attach them.

Two ways to author​

These forms are reached from two entry points:

  • The back office (Components → CBX), where all the forms below live.
  • Front-end inline editing for managers — when a user with manager rights is logged in on the storefront, edit buttons appear on hover over most CBX elements (products, pages, questions, answers), opening the same forms in context. This lets an admin build/tweak a configurator while seeing it as the customer does. (A refactor should keep this "edit-in-place" authoring affordance — it's a notable usability feature.)

1. Product Tree (Products screen)​

A read-only, expandable tree of the whole catalog: Products → Pages → Questions → (optionally) Answers, optionally filtered to one product or one product list. It is the admin's primary navigation and overview of the configurator structure — clicking a node opens the relevant edit form. It doesn't store anything itself; it just visualizes and gives access to the hierarchy.

2. Product form​

The root entity of a configurable product. Organized into sections:

General​

  • Title (translatable) — the product name shown everywhere.
  • SEF Segment (label, translatable) — the URL slug for the product. Affects the product's public URL.
  • Product list(s) (multiselect) — which product lists/catalogs the product appears in. Affects where customers can find it.
  • Product Image — the main image used in product lists/detail.
  • Active (published) — whether the product is live. Affects public visibility (unpublished ⇒ not buyable; returns "gone").

Visualization​

  • Visualization type — how the configured product is previewed: none, composite image (2D layered images), or ShapeDiver (3D). Affects which visualization the configurator shows and which per-answer visualization fields are relevant.
  • Base image — the bottom layer for 2D composite visualization.
  • ShapeDiver Model — the 3D model binding (when ShapeDiver is chosen).

Base price (regular) and Base price (recurring)​

Two parallel pricing sections — one for one-off regular pricing, one for recurring (subscription) pricing:

  • Base Price — the starting price before option-driven changes.
  • Base Price Override (baseprice_overrides, per-currency/group) — explicit price values for specific currencies/customer groups. Affects what those audiences pay.
  • Was Price — a struck-through "before" price for promotions.
  • Tax Class — the tax rate set applied. Affects tax calculation.
  • Price Label (translatable) — a label shown next to the price (e.g. "from").
  • Custom Price Text (translatable) — free text shown instead of/with the price (e.g. "Call for quote").
  • (Recurring only) Recurring Interval (translatable) — e.g. "per month". Affects how the subscription cadence is shown.

Display in product detail page​

  • Product detail page type — what kind of detail page to use (built-in page, external URL, or none). Affects whether/where a detail page exists.
  • URL to product detail page (translatable) — the external URL when that type is chosen.
  • Theme for product detail page (layoutname) — the template/layout used.
  • Description on product detail page (translatable) — the long description (supports placeholders like price/buy/configure links).
  • Show product detail panes in product pages — whether the tabbed detail panes appear on the detail page.

Display in product lists​

  • Show buy button / Show product details button — which CTAs appear on the product-list tile.
  • Enable Reviews — whether reviews/ratings show for this product (can use defaults or an external source).
  • External Review ID — an identifier when reviews come from an external system.
  • Description in product lists (translatable) — the short text on the product-list tile.

Display in configurator​

  • Show product detail panes in configurator pages — whether detail panes appear during configuration.
  • Show page navigation using tabs / …with next/previous buttons — per-product overrides of the global configurator navigation (each can defer to the global default).
  • Block continuing if selections are missing — per-product override of required-selection gating (yes / no / use default).
  • Cart button on last page only — per-product override (yes / no / use default).

Product Detail Panes​

  • Product Detail Panes (child entries) — manage the product's info panes inline (see the Detail Pane form).
  • Product panes display method — how panes are presented (e.g. tabbed).

Custom Fields​

  • Product custom 1–6 — free-form product attributes (4 plain + 2 translatable). Their labels come from global Configuration; values here can be referenced in rules, calculations and templates.

Selection overview on configurator pages (per-product)​

A per-product copy of the global price/selection-overview toggles (regular + recurring: show overview/prices/pages/questions/question-prices/expand-mode/taxes/cart-button, plus delivery/payment/net options). Every option can defer to the global default ("Use default from settings"). Functionally: tune how detailed this specific product's live cost breakdown is. (See the configuration doc for what each toggle does.)

3. Page form​

A configurator step belonging to a product.

  • Title (translatable) — the step name (shown as the tab/heading).
  • Active (published) — whether the page is part of the configurator.
  • SEF Segment (label, translatable) — the page's URL slug.
  • Template (layoutname) — the layout used to render this page.
  • CSS Classes — extra classes for theming this page.
  • Product — the product this page belongs to (the parent link).
  • Description (translatable) — introductory text for the step.
  • Ordering — the page's position in the sequence. Affects step order in the configurator.

4. Question form​

The richest form — a single input/question on a page. What appears depends on the chosen question type.

General​

  • Title (translatable) — the question text shown to the customer.
  • Internal Name — an admin-only name for identification (shown in the back office when enabled globally).
  • Required — whether the customer must answer. Affects validation / navigation gating.
  • Question type — the input widget, one of: text box, multi-line text box, checkbox, radio buttons, dropdown, file upload, calendar, color picker, RAL color picker, clickable images, slider, choices + text field, plus any custom types. This is the master switch that determines which other sections below apply.

Type-specific settings (shown only for the relevant types)​

  • Calendar: first day of week, min/max validation type and min/max day offsets — constrain which dates are selectable.
  • Slider: number of steps — the granularity of the slider.
  • Choices: the predefined choice list (for "choices + text field").
  • Upload: allowed file extensions, allowed MIME types, and max size (MB) — constrain what customers may upload.

Text box settings (text/number-style types)​

For textbox/textarea/slider/choices/colorpicker:

  • Prefill with a default value + Default Value — pre-populate the field.
  • Restrict what the customer can enter + What can a customer enter (input_restriction, e.g. integer/decimal) — input validation.
  • Set a minimum value + Static Minimum Value or Calculated Minimum Value (a calculation) — lower bound (static or computed from other selections).
  • Set a maximum value + Static/Calculated Maximum Value — upper bound.
  • Show unit + Unit — a unit suffix shown next to the field (e.g. "cm").

Predefined Answers (choice-type questions)​

For checkbox/radio/dropdown/images: the Answers section (child entries) where you add and order the question's selectable answers — each entry is an Answer (§5), belonging to this question alone. This is where the question's answers live.

Rule​

  • Rule — the conditional-logic rule that decides whether this question shows (see rule-engine doc). Affects dynamic show/hide.
  • Display while disabled — when the rule isn't met, hide the question vs. show it greyed-out.
  • Behavior on activation — what happens when the question becomes applicable (e.g. auto-select a default).
  • Behavior on inconsistency — what happens when the current answer becomes invalid (e.g. deselect/replace).
  • Behavior on changes — how changes are handled (silent vs. confirm).

Visualization​

  • Controls a ShapeDiver parameter? + ShapeDiver parameter — bind this question to a 3D model parameter. Affects the 3D preview.

Calculations​

  • Price Calculation (calcmodel) — a calculation that contributes this question's price.
  • Price Multiplicator — a factor applied to the question's price result.
  • Display question in configurator (text_calcmodel) — display handling for text/number questions.
  • Recurring Price Calculation / Weight Calculation — recurring-price and weight contributions.

Description​

  • Description display method + Description (translatable) — help text and how it's shown (inline, tooltip, etc.).

Custom Fields​

  • Question custom 1–4 (+ 2 translatable) — free-form question attributes (labels from global Configuration); usable in rules/calculations/templates.

Misc​

  • Title display — how/whether the question title is shown.
  • CSS Classes — theming hooks.
  • Use Selection as Product Title — let this question's answer become the product's title (e.g. a name-engraving field).
  • Show in Overview — whether this question appears in the selection/price overview.
  • Image (el_image) — an image shown with the question.

5. Answer form (an answer on a question)​

An answer belongs to exactly one question and carries everything about itself: its text and price, whether it is preselected, its own conditional rule, any price-overriding calculation, its visualization layer and its ordering. Edited inline from the question's Answers section.

If you knew CBX 3: there is no global Option library and no Option Assignment step any more. The two were collapsed into this one record in CBX 4 — one editor, one identity. Reusing an answer's text on another question means creating an answer there; editing one answer changes only that answer. See the answer collapse if you are migrating a CBX 3 site.

Identity and pricing​

  • Title (translatable) — the answer text the customer reads.
  • SKU — stock-keeping unit, frozen onto the order line when this answer is chosen.
  • Price + Price Overrides (per currency/group) — the static price this answer adds.
  • Was Price — promotional struck-through price.
  • Price Recurring + Recurring Overrides + Was Price Recurring — the recurring-pricing equivalents.
  • Weight — the weight this answer adds (for shipping).
  • Internal Name — admin-only identifier, never shown to customers.

Selection​

  • Default — whether this answer is preselected.
  • Enable this answer? (published) — whether it is selectable at all.
  • Picker Image — the image used in image/picker questions.

Availability​

  • Available — whether the answer can currently be chosen.
  • Disable when not available — show but disable, versus hide, when unavailable.
  • Availability date — a date from which it becomes available.

Description​

  • Description display method + Description (translatable) — help text and how it is shown.
  • Answer Image — the answer's image.

Rule​

  • Rule — conditional logic deciding whether this answer shows (see the rule-authoring doc).
  • Display while disabled — hide versus grey-out when the rule is not met.

Calculations​

  • Price Calculation (+ Price Calculation Overrides) — a calculation overriding this answer's price.
  • Recurring Price Calculation (+ overrides) — recurring equivalent.
  • Weight Calculation — this answer's weight contribution.

Visualization​

  • Visualization Image — the layer image shown when this answer is selected (2D composite).
  • Visualization Stacking Order — the z-order of that layer, deciding which images sit on top.
  • ShapeDiver choice value — the value passed to the 3D model when this answer is chosen.

Custom answer fields​

  • Answer custom fields — free-form answer attributes (labels from global Configuration).

Ordering​

  • Ordering — the answer's position within the question, which is the order customers see.

6. Product Detail Pane form​

A tabbed/accordion info pane attached to a product (shown on detail and/or configurator pages per the product's settings).

  • Product — the owning product.
  • Heading — the pane's title/tab label.
  • Heading Icon — an icon for the tab.
  • CSS Classes — theming hooks.
  • Content — the pane's (rich) content.
  • Ordering — position among panes.

7. Product list form (product catalog)​

A collection of products the storefront can display.

  • Title — the product list's name.
  • Template (layoutname) — the layout used to render the list.
  • Active (published) — whether the list is live.
  • Description (translatable) — introductory text for the list.
  • Sort products by — Title (alphabetical) or Manual ordering. Affects product order on the storefront.
  • Products in this list (product_assignments) — which products belong, and (for manual sort) their order.

8. The build workflow (how it fits together)​

  1. Create the Product — title, pricing, tax class, visualization type, and how it shows in product lists/detail/configurator.
  2. Add Pages — the configurator steps, in order.
  3. Add Questions on each page — pick a question type and its type-specific settings; mark required ones.
  4. Provide Answers — for choice questions, attach Options (from the reusable library) via Option Assignments, setting defaults, ordering, and per-answer visuals.
  5. Price it — attach price/recurring/weight Calculations to questions and assignments (or rely on static Option prices); set base prices on the product.
  6. Add logic — attach Rules to questions/answers for conditional show/hide and configure activation/inconsistency behavior.
  7. Wire visualization — set base image + per-answer layer images & stacking (2D), or bind questions/answers to ShapeDiver parameters (3D).
  8. Merchandise — add Detail Panes, place the product into product lists, enable reviews.

The same workflow as a pipeline:

9. Notes for the refactor (functional observations)​

  • Option vs. Assignment is a genuine domain distinction (a reusable answer library vs. its per-question usage). A refactor should preserve this — it's what enables reuse with per-context pricing/rules/visuals — but the split is currently easy to confuse (two forms, overlapping fields).
  • Regular vs. recurring pricing is duplicated everywhere (product, option, assignment, question calculations all have parallel "…recurring" twins). Functionally it's "this product can be sold one-off and/or as a subscription." A refactor might model price kinds generically instead of hard-coding two.
  • Per-product overrides of global settings (navigation + selection-overview) use a tri-state "use default from settings." A cleaner model would be explicit inheritance/override of a presentation config.
  • Custom fields are fixed slots (product 6, question 4+2, assignment 4, option 6). They're the flexible-attributes mechanism; a refactor likely replaces them with typed custom attributes.
  • Visualization is two parallel systems (2D image-layer stacking vs. ShapeDiver 3D) selected per product; the per-answer fields differ accordingly. Worth modeling as pluggable visualization strategies.
  • The question type drives which fields are relevant (appliesWhen). Functionally each question type is a small sub-form; a refactor could make question types first-class plugins (they already are, technically — see the rule/calc extension pattern).
Last updated on