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 (Elements) → Answers, where answers come from a reusable Option library and are attached to a question via an Option Assignment. 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 (Element)
  5. Option (reusable global answer)
  6. Option Assignment (answer-on-a-question)
  7. Product Detail Pane
  8. 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 (Element) 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 attach and order the question's selectable answers — each entry is an Option Assignment (§6). This is where the question's options 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. Option form (reusable global answer)​

A global, reusable answer kept in an answer library; one option can be attached to many questions. Sections:

Component pricing​

  • Title (translatable) — the answer text.
  • SKU — stock-keeping unit for this answer.
  • 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).

Availability​

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

Description​

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

Custom Global Answer Fields​

  • Option custom 1–6 — free-form answer attributes (labels from global Configuration).

The Option holds the answer's default/global values. How that answer behaves on a specific question (default-selected, its own rule, a price-overriding calculation, visualization layer, ordering) is set on the Option Assignment (§6).

6. Option Assignment form (answer attached to a question)​

The link between a global Option and a Question, with per-attachment settings. (Managed inline from the Question's "Predefined Answers" section.)

  • Question (element_id) — the question this answer belongs to.
  • Reused Answer (option_id) — which global Option this assignment uses.
  • Default — whether this answer is preselected.
  • Internal Name — admin-only identifier for this assignment.
  • Enable this answer? (published) — whether the answer is selectable.
  • Picker Image — image used for the answer in image/picker questions.

Rule​

  • Rule — conditional logic deciding whether this answer shows (see rule-engine doc).
  • Display while disabled — hide vs. grey-out when the rule isn't met.

Calculations​

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

Visualization​

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

Custom Answer Fields​

  • Assignment custom 1–4 — free-form per-attachment attributes (labels from global Configuration).

Ordering​

  • Ordering — the answer's position within the question. Affects the option order shown to customers.

Option vs. Assignment, functionally: the Option is the answer's library record (its default price, SKU, image, description); the Assignment is "this answer, used on this question," carrying selection defaults, conditional rules, price-overriding calculations, visualization layers and ordering. The same Option reused on two questions can have entirely different rules, prices and visuals via its two assignments.

One library record, two independent usages:

7. 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.

8. 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.

9. 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:

10. 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