# Configurator-Building Forms

> 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-c…

Source: CBX documentation, version 3.x (released). Canonical page: https://docs.configbox.at/docs/functional/configurator_building. Last updated 2026-08-02.

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

```mermaid
flowchart TD
    L["Product list"] --> P["Product"]
    P --> PG["Page"]
    PG --> Q["Question"]
    Q --> OA["Option Assignment"]
    OL["Option library"] -. "reusable answer" .-> OA
    R["Rule"] -. "show or hide" .-> Q
    R -. "show or hide" .-> OA
    C["Calculation"] -. "price and weight" .-> Q
    C -. "price and weight" .-> OA
    P --> DP["Detail Panes"]
```

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:

```mermaid
flowchart LR
    O["Option: one library record with default price, SKU, image, description"] --> A1["Assignment on Question A: default-selected, own rule, own ordering"]
    O --> A2["Assignment on Question B: price calculation, own visualization layer"]
    A1 --> QA["Question A"]
    A2 --> QB["Question B"]
```

---

## 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:

```mermaid
flowchart TD
    A["1. Create the Product"] --> B["2. Add Pages"] --> C["3. Add Questions"] --> D["4. Provide Answers"]
    D --> E["5. Price it"] --> F["6. Add logic"] --> G["7. Wire visualization"] --> H["8. Merchandise"]
```

---

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