Rule Authoring
- Version
- 3.x
- Updated
A functional description of how an admin builds rules — the conditional logic that decides
whether a question or answer is shown/active in the configurator. This is the authoring/usage view:
what you can express and how you build it. For how rules are stored and evaluated, see
technical/com_configbox_rule_engine.md.
A rule answers one yes/no question: "given the customer's current selections (and group), does this apply?" When it applies, the question/answer is shown (or, with negation, hidden). Rules are what make a configurator dynamic — options appear, disappear or grey out as the customer chooses.
The whole decision in one picture:
1. What a rule is attached to
A rule always belongs to one question or one answer — nothing else. There is no product-level, page-level or store-level rule, and no separate list of rules to manage: you open the question or the answer you want to make conditional, and write the rule there. If you are looking for "where do I manage the rules", the answer is that you do not — each rule lives on the thing it governs.
The two places, and what each controls:
| A rule on… | Controls |
|---|---|
| a Question | whether the whole question — its text and every one of its answers — is shown |
| an Answer | whether that one answer can be picked, within a question that is itself shown |
Both are edited in the same Rule Editor, and both read the customer's current selections. A rule on an answer only gets its say once the question it belongs to is showing: hide the question and its answers go with it, whatever their own rules say.
A question or answer with no rule always shows — that is the default, and the common case. Add a rule only to the ones that need to be conditional.
2. The Rule Editor (authoring UX)
Opened from the question's or answer's form (the "Rule" field → Change). It's a visual builder:
- Show-if vs Hide-if — a selector at the top chooses the rule's meaning:
- Show … if these conditions are met (normal), or
- Hide … if these conditions are met (negated).
- Drop area — the rule you're building. You drag conditions into it from the picker below.
- The condition picker: a list of the product's questions on the left (with a page filter and a title filter once the product has more than ten questions). Click a question and the conditions it offers appear on the right, grouped: Related to answers, Related to pricing, Related to custom fields, and a group of its own for a question type that adds fields. Below the questions, Other conditions lists the sources that are not a question: results of calculations, the customer group, and any custom condition type the site added.
- Combinators — drag AND / OR between conditions to combine them.
- Brackets — select conditions and "make parentheses" to group them (controls precedence, e.g.
A AND (B OR C)). - Operators — click a condition's operator to pick how it compares (see §4).
- Values — type the value each condition compares against (numbers are locale-aware).
- Save — writes the rule back onto the question/answer.
You can also copy/paste a rule between questions/answers, and delete it (reverting to "always show").
Verified live: the Show/Hide selector reads "Show the question if these conditions are met:" / "Hide the question if these conditions are met:"; combinators are AND / OR; and the toolbar buttons are Put in parentheses, Remove selected, Limit condition width, Save, Cancel. The picker is headed "Conditions" with the prompt "Pick a question to see its conditions"; the entries under "Other conditions" are "Results of calculations" and "Customer" (§3).
3. Condition types (the building blocks)
A question's own conditions (the most common)
Pick a question in the list and compare something about it to a value:
- Answer in … — the customer's chosen answer: one condition per answer (e.g. "Answer in 'Material' is 'Oak'") plus a not answered one. A question without answers offers Entry in … instead, the value typed or picked; a calendar offers Date in …, an upload File in ….
- Price of … / Recurring Price of … / Weight of … — that question's computed figures.
- The question's custom fields, and for a question with answers the selected answer's custom fields and global custom fields, under your configured labels.
- Whatever the question's type adds, under a heading of its own: a dimensions type offers its width, height and area, a quantities type the quantity of each answer. …then choose an operator and a value. An answer or a text can only be compared with is / is not; a number or a date takes all six operators (§4).
"Results of calculations"
Compare a calculation's result to a value (e.g. "Result of 'Total weight' is above 50"). This is how rules react to computed numbers, including anything you built in the calculation editors.
"Customer"
Compare a customer-group field to a value (e.g. show trade-only options when the group's flag is set). Lets rules depend on who the customer is rather than what they selected.
Custom condition types
A developer can add condition types for things that are not a question (a stock level, external
availability); they appear as further entries under Other conditions, each with its own list. A
custom question type needs no condition type of its own: the conditions it offers appear under
the question like any other question's. (How to add either: customization/com_configbox_custom_rule_conditions.md
and customization/com_configbox_custom_question_types.md.)
Choosing the right condition type is usually this simple:
4. Operators
Each condition compares its subject to your value using one of:
- is below (
<) - is or below (
≤) - is (
=) - is not (
≠) - is or above (
≥) - is above (
>)
Which operators a condition offers depends on what it compares: a number takes all six and compares
numerically (2.5 is above 2.10), a date takes all six and compares by day, while an answer or a
text takes only is / is not. An empty value means not answered: "Answer in 'Material' is
[not answered]" holds while nothing is chosen. (For choice questions, "Answer … is/is not " is the typical form.)
5. Combining conditions: AND / OR and brackets
- AND — all combined conditions must hold.
- OR — any one suffices.
- Brackets group conditions so you can express things like
(Material is Oak OR Material is Walnut) AND Finish is Lacquer.
That example, seen as the condition tree the brackets create:
Build arbitrarily complex logic by nesting brackets and mixing AND/OR.
6. Show-if vs Hide-if (negation)
The top selector flips the whole rule's meaning:
- Show-if — the question/answer appears only when the conditions are met (the default).
- Hide-if — the question/answer is hidden when the conditions are met (and shown otherwise).
Pick whichever reads more naturally for the case; they're logically complementary.
7. What happens when the outcome changes (companion behaviors)
A rule only decides applies / doesn't apply. What the configurator does when that changes is set by companion fields on the question/answer — part of authoring conditional behavior:
- Display while disabled (question & answer) — when the rule isn't met, hide the item or show it greyed-out (visible but not selectable). Use grey-out to keep the customer aware of options they could unlock.
- Behavior on activation (question) — what to do when the question becomes applicable, e.g. auto-select its default/first answer so it's never left empty.
- Behavior on inconsistency (question) — what to do when the current answer becomes invalid because of other changes, e.g. deselect it, or replace it with the default/any valid answer.
- Behavior on changes (question) — whether such automatic changes happen silently or prompt the customer to confirm.
How the pieces fit together when a rule's outcome flips:
These turn a static condition into smooth live behavior (options cascade, invalid choices self-correct, the customer is asked before surprising changes).
8. Worked examples
- Dependent question: On the question "Engraving text", Show-if Answer in "Add engraving" is "Yes". The text field only appears when engraving is chosen.
- Segment-gated options: On a premium answer, Show-if Customer group field "is_trade" is "1" — only trade customers see it.
- Either/or grouping: Show-if (Answer in "Use" is "Indoor" OR Answer in "Use" is "Covered") AND Answer in "Material" is "Steel".
- React to a calculation: On a "Reinforcement required" answer, Show-if Result of "Total span" is above "4".
- Hide on condition: On the "Color" question, Hide-if Answer in "Finish" is "Raw" (raw finish has no color choice).
9. What the customer experiences (runtime)
As the customer makes selections, CBX re-evaluates all rules live on every change: non-applying questions/answers hide or grey out, newly-applicable questions can auto-select defaults, and selections that became invalid are corrected (silently or with a confirmation prompt) per the companion behaviors. The effect is a configurator that continuously reshapes itself to valid, relevant choices.
The live loop, as the customer sees it:
10. Practical notes & limits
- A rule yields visibility only. Anything beyond show/hide/grey-out (auto-select, deselect, confirm) comes from the §7 behaviors, not the rule itself.
- Rules can reference calculations, so numeric thresholds (weight, total, dimensions) are expressible — pair the two editors.
- Performance: rules are evaluated on every selection change across the product; very large/deep rule sets add cost. Keep conditions focused.
- Copy/paste rules to reuse logic across similar questions/answers; product copy re-points rule references automatically.
11. Notes for the refactor (functional observations)
- Rules express visibility; behaviors express reaction. These are two coupled concerns the current UI splits across the rule editor and several question fields. A refactor could present them together as one "conditional behavior" model (condition → effect: show/hide/grey/require/auto-select), which is closer to how admins think.
- The condition vocabulary is small and clear (a question's fields, calculation-results, customer-group) and extensible: a question type declares what can be compared about it, and custom condition types cover sources that are not a question — worth preserving as an open set.
- Show-if/Hide-if is just negation of the same condition tree; a refactor might offer an explicit effect dropdown instead (Show / Hide / Disable / Require…).
- Rules + calculations are complementary engines (boolean logic vs numeric); keeping them as two composable systems (rules can read calc results) is a good separation to retain.
- Live cascade + inconsistency resolution is a genuine UX feature (not just a side effect) — the refactor should treat the auto-select/inconsistency/confirm behavior as a first-class part of the rules subsystem, with clear, testable semantics.