Configurators

Build product configurators — controls, materials, formula-driven calculations, production parts, and presets.

Overview

A configurator is a self-contained pricing engine for one product: a set of customer-facing controls (width, color, direction, …), a materials list drawn from your project's catalog, and calculations that turn control values into material quantities and a price. Configurators are used inside orders, can be shared with customers via a public link or embedded as a widget on your own site, and can optionally be published to the cross-project showcase for other Configo users to copy.

Open Configurators in the project sidebar to see the list. Click Add to create one, or the edit icon on an existing row to open it. The editor is split into seven tabs: Settings, Materials, Controls, Calculations, Parts, Presets, and Preview.

While editing, your changes are kept in the browser's session storage as a draft and are only sent to the server when you click Save in the top-right corner. Reloading the page keeps the draft; closing the tab does not.

Settings

General

• Name (required) — internal name shown in the configurators list. Not shown to customers.
• Product name template — the title generated for each configuration, e.g. Plisse 16mm $width x $height $color. Reference any control by its variable ID ($width, $color, …); the value is substituted live as the customer fills in the form. Plain text around variables is preserved as-is — keep at least one non-alphanumeric character (space, ×, -) between two variables, otherwise they get parsed as a single identifier ($widthx is read as one variable named widthx, not $width followed by x).
• Product unit — the unit of measure for one finished, configured product (piece, set, etc.). This is separate from the units of the individual materials consumed to build it.

Pricing

This section controls how the final price is assembled. Understanding exactly what each field does — and what it does not do — avoids double-counting costs.

• Work cost and Amortization — flat amounts added once per configured unit, on top of the material totals. Both are static numbers, not formulas: they don't scale with width, height, quantity, or any control value, and they can't be made conditional.
• Price multiplier — multiplies every material price (purchase, sale, and dealer) by this factor. Use 1 to leave prices unchanged; use it to apply a currency conversion rate when your material catalog is priced in a different currency than what you sell in.
• Decimal places — how many digits after the decimal point calculated prices are rounded to.

The three price columns (purchase / sale / dealer) are computed from the material breakdown as follows:

Two consequences worth knowing before you configure a real product:

• Purchase price never includes work cost or amortization. It represents your raw material cost basis only. If you need labor or overhead reflected in your purchase/cost figure, work cost/amortization won't do it — you'd have to add a material line for it instead (see below).
• Work cost and amortization are added identically to both the sale and dealer price — there is no way to set a different labor charge for retail vs. dealer customers using these fields, and the price multiplier does not scale them (it only scales material prices).

Modeling labor and overhead: two approaches, pick deliberately

There are two different ways to add a labor/assembly/installation charge to a configurator, and they behave differently — mixing them up leads to accidentally double-charging or under-charging:

1. Work cost / Amortization field (Settings → Pricing) — simplest option. Use it when the labor charge is a fixed amount per configured unit, identical for sale and dealer pricing, and doesn't need to scale with size or depend on any control (e.g. a flat "assembly fee").

2. A material with a Calculation formula — use this when the labor cost should:

   • scale with a control (e.g. $width + $height for cutting time), or
   • be conditional (e.g. only charged when a certain option is selected), or
   • need distinct purchase/sale/dealer prices, or
   • appear as its own line in the customer-facing material breakdown table.

   To model labor this way, add a material (e.g. "Installation") with a unit like pcs or hour, then create a calculation for it with a formula that returns the labor quantity (often just a constant 1, or a condition-driven value). Because it's a material, it also gets scaled by price multiplier and (if set) waste %, which is usually not what you want for labor — set waste % to 0 on labor materials.

Whichever approach you choose, don't use both for the same cost — that charges it twice.

Visibility

• Shareable — allows this configurator to be copied into other projects via the cross-project showcase directory (see Showcase and publishing below).
• Public access — allows anyone with the link to open this configurator without being a project member. Required for the public widget embed.
• Show breakdown — whether the material breakdown table (quantities and line prices) is shown to the customer, or only the final total. Turn this off if you don't want customers reverse-engineering your material costs from the itemized list.

Materials

The Materials tab lists every material this configurator can use. Click Add to attach one:

• Search an existing material from your project's material catalog by name and pick it from the results, or
• Type a new name directly — a new material is created in your project's catalog as soon as you save it here.

Either way, you're editing a real project material record (name, group, vendor code, unit, purchase/sale/dealer price, waste %, and YAML properties) — changes made here are reflected in the project's Materials page too, and vice versa.

Only materials attached here are available to reference from the Controls, Calculations, and Parts tabs of this configurator. A material that isn't referenced by any Calculation or Part is flagged with a small "Not used by any calculation or part" note under its name — a quick way to spot orphaned materials before they're forgotten.

Controls

Controls are the input fields the customer fills in. Each control has:

• Label — the field's display text.

• Variable ID — how the control is referenced in formulas and templates, e.g. $width. Must start with $ and cannot be changed after the control is created.

• Width — how many of the 12 grid columns the field occupies in the form layout.

• Type — one of:

  Type	Description
  Text	Free-text input.
  Textarea	Multi-line free-text input.
  Number	Numeric input, with optional min/max/step.
  Select	A dropdown. Options come from one of several sources (below).
  Select with image	Like Select, but options are rendered as clickable thumbnails, sourced from a material group (each material's image and name become an option).
  Select with dependency	A dropdown whose available options are filtered by matching material properties against the current value of one or more other controls — useful for cascading selects (e.g. pick a series, then only see colors available in that series).
  Materials	Lets the customer pick one or more materials directly (with quantities) from a material group or a set of groups, instead of the quantity being formula-derived.

• Default value — pre-filled value shown when the configurator loads or resets.

Option sources (Select type)

• JSON / YAML — a fixed, manually entered list of option strings.
• Material group — one option per distinct material name in the chosen group.
• Group property — one option per distinct value of a chosen property across all materials in a group (read from each material's YAML properties).
• Material property — one option per value found in a specific property of one specific material (useful when that material's property is itself an array of choices, e.g. a list of available colors).

Use the Preview panel at the bottom of the Add/Edit Control form to see exactly how the control will render before saving.

Calculations

Calculations are what turn control values into material quantities. Each calculation targets one material (or, by leaving the target as a group name instead of picking a specific material, dynamically resolves to whichever material in that group matches the customer's current selection) and holds one or more formulas. The material/group picker is searchable — type to filter instead of scrolling through the whole catalog.

• Formulas are evaluated as OR — the first formula whose conditions pass and whose code evaluates to a quantity greater than 0 is used; the rest are skipped. Add multiple formulas (up to 5) to express "different formula for different scenario" for the same material, e.g. one length formula when a threshold option is selected, another when it isn't.
• Conditions are evaluated as AND within a formula (up to 5). Each condition compares a control's current value against a fixed value using an operator: is, is not, greater than, less than, include, not include.
• Formula code is a JavaScript-like expression evaluated in a sandboxed worker. It can reference any control by its variable ID ($width, $height, …) and use the built-in math helpers exposed by the ƒ button: abs, round, ceil, floor, trunc, max, min, sin/cos/tan/asin/acos/atan/atan2, pow, sqrt, exp, log, log10, random, and the constants PI, E, LN2, LN10, SQRT2, SQRT1_2. The result is treated as the required quantity of that material, in its own unit of measure.

A formula with no conditions always applies — this is how you express "always needed, regardless of the customer's choices" (e.g. a fixed hardware kit). A new formula starts with no conditions by default; click AND to add one only if you actually need to gate the formula on a control value.

If a condition is left with no variable selected, it's automatically dropped when you save rather than silently making the formula unmatchable — so a half-filled condition can't accidentally zero out a material.

The formula code box validates as you type: a syntax or reference error is shown in red directly under the box (e.g. "Unexpected token ')'"), so you don't have to switch to Preview to discover a typo.

If a material has a waste % set on it (Materials tab), the calculated quantity is automatically increased by that percentage before pricing.

Parts

Parts feed the production sheet — the cut list a workshop actually cuts from, distinct from the customer-facing material breakdown (which only totals how much material is consumed, not how it's cut up). Each Part is one distinct cut piece: a material, a size (one formula per dimension — 1D, 2D, or 3D), and a Quantity saying how many identical copies of that exact piece are needed. Conditions work the same OR-formulas / AND-conditions model as Calculations, with the same live syntax validation under the formula box.

A Part is one cut length, not one profile. If a frame profile runs around the full perimeter of the product, it isn't cut as a single piece — it's four: two pieces the length of the width, two the length of the height. Model that as two Parts, not one:

• Part 1: material = frame profile, size = $width, Quantity = 2
• Part 2: material = frame profile, size = $height, Quantity = 2

A single Part with Quantity 1 and a size of $width only describes one bar the length of the width — it silently drops the two height-length pieces from the cut list entirely. Whenever a material is consumed as multiple differently-sized (or differently-counted) pieces per unit produced, give each distinct piece its own Part.

• Quantity and Item unit — how many identical copies of this specific piece are cut, and in what unit.
• Size type — 1D, 2D, or 3D, controlling how many size formulas you fill in (e.g. width only, or width × height).
• Material unit and Size unit — the unit the resulting dimension is expressed in.

The material picker is searchable, same as in Calculations. To check the computed sizes and quantities before saving, switch to the Preview tab — the production list for every Part is shown there, live, right under the material breakdown.

Presets

Presets are named, reusable snapshots of control values (e.g. "Standard 800×2100 White") that a customer can pick from a dropdown to instantly fill in the whole form instead of configuring it manually.

To create one: click Add preset, fill in the configurator form on the right with the values you want to save, click Save as preset (this captures the current values), give it a name in the field at the top, then confirm with Save. Editing an existing preset re-applies its saved values into the form so you can adjust and re-save.

Preview

A live, fully working instance of the configurator exactly as a customer would see it, using whatever is currently in the draft (including unsaved changes). Use it after every change to Controls, Materials, or Calculations to confirm quantities, conditional branches, and the total price behave as expected — this is the fastest way to catch a mismatched formula or a forgotten condition before saving.

If the configurator has any Parts, a production list table is shown below the material breakdown, listing the computed material, size, and quantity for every Part that currently matches — recalculated live as you change control values in the same panel, so Parts and Calculations can be sanity-checked side by side against the exact same inputs.

Showcase and publishing

• Showcase (Configurators → Showcase in the sidebar) is a directory of configurators from across all Configo projects that have been marked Shareable. From there you can preview any listed configurator and Copy it into your own project as a starting point, materials and all.
• Public widget — when a configurator's Public access setting is on, it becomes reachable at a public, no-login URL and can be embedded as an iframe widget on an external website. The widget posts calculated and addToCart events to the parent page via postMessage, so an external storefront can react to configuration changes and handle checkout. Availability of the widget embed depends on your plan.

Tips

• Prefer Work cost over a labor material whenever the charge is truly flat — it's one field instead of a material + calculation, and there's less to keep in sync.
• Set waste % to 0 on any material that isn't an actual physical, wasteable good (labor, fixed fees modeled as materials, etc.).
• A red error under a formula box only catches syntax/reference errors — it can't tell you that a formula's logic is wrong (e.g. an off-by-one in a condition). Use Preview to confirm the actual computed numbers, not just that the formula runs without error.
• Watch the "Not used by any calculation or part" note on the Materials tab — it catches materials you attached but forgot to wire up.