Limits and guarantees

Product Configurator adds one thing to OpenCart's own product options: conditional logic. Rules of the form when these answers hold, show, hide or require this option or this value. Everything else about an option (its price, its stock, how it prints on the order and the invoice) stays OpenCart's, on purpose.

This page states what that promises and where the promise stops. Read it before you buy.

At a glance

If you are asking	The short answer
Can a hidden option keep something secret from some customers?	No. Every option and value attached to the product is in the page source, whether a rule reveals it or not. More
Does a customer with JavaScript off get round the rules?	No. Every option shows, but the add to cart is still refused by OpenCart's own validation. More
Can a rule change a price, or add a percentage?	No. An option value adds the fixed amount OpenCart's Option tab holds, and nothing here changes it. More
Can one rule say or?	No. Conditions are joined with AND only; two rules with the same target are the or. More
Does a rule change reach lines already in a cart?	No. Nothing is re-checked in the cart or at checkout. More
Can I word the message a refused combination shows?	No. The refusal is OpenCart's own, in OpenCart's own words. More
Will the admin stop me saving rules that make a product unbuyable?	No. A product save is never refused on rule grounds. The Configurator tab warns about the dead ends it can see, as of when the form was opened. More
Can several products share one set of rules?	No. Rules belong to one product. Copying a product copies them, and Copy rules from puts another product's rules on this one as a copy, not a link. More
Does uninstalling delete my rules?	No. Uninstall removes the settings and event registrations and leaves the three rule tables alone. More
Does it work on OpenCart 4.1.0.0?	It installs, but OpenCart's own Copy fails there for every product with options. More

What a rule can say

• One grammar, and this is all of it.

  WHEN an option is a value [AND an option is a value …] THEN hide | show | require an option, or one value of an option

• Conditions are joined with AND only. There is no OR, no nesting and no brackets. Where you mean OR, write two rules: two rules with the same target are already a disjunction, so the grammar covers every condition you can state, though some of them take more than one row.

• A condition can only be written against a select, radio or checkbox option. Those are the options whose answers are values you chose in advance. A condition on text, a date or an uploaded file would be matching on whatever the customer typed, which is not configuration.
• require applies to a whole option, never to a single value. OpenCart carries a required flag per option and none per value, so there is nothing for the verb to flip on a value.
• Rules are not ordered, and hiding always wins. A target is hidden if any rule that fired hides it. Otherwise it shows, unless it is named by a show rule, in which case it is hidden until one of those rules fires. require applies only to an option that ends up visible, so a rule that hides an option and a rule that requires it do not fight: the customer is not asked. The other direction would let you build a product nobody can buy.
• A rule that names something no longer on the product does nothing. It is skipped, not an error, and it never blocks a save or an add to cart. The Configurator tab lists such a rule under No longer on this product: so you can see it and delete it.
• A product that attaches the same catalogue option twice gets the rule applied to both copies. A rule names the option in your catalogue, not one row of one product form, and OpenCart lets the same option be attached more than once.

What it does not do at all

Each of these is out on purpose, and none is scheduled.

• No live preview. Configuration is a form. There is no 2D composite, no 3D view and no artwork layer to upload.
• No reusable configurator template. Rules belong to one product. Ten products that configure the same way are ten sets of rules. There are two ways to make the tenth: OpenCart's own Copy, which makes a new product and carries the rules with it, and Copy rules from on the Configurator tab, which puts another product's rules on a product you already have. Either way the result is a second set: changing the rules on one product later changes nothing on the other.
• No percentage price modifiers. An option value adds the fixed amount OpenCart's own Option tab holds, and nothing here changes that. OpenCart sums option prices inside a library class no extension can reach, so a percentage could only be faked by shadowing the price, which goes silently wrong the moment a special is running.
• No rule that changes a price. Same reason.
• No multi-step wizard. Every option renders as one flat list, the way your theme already draws them.
• No stock of its own. Per-value quantity and subtract stock are OpenCart's, on its own Option tab, and they keep working as they did. There is no per-option stock switch here, because you can still edit any single value's subtract flag on OpenCart's screen, and a switch that a store owner can contradict elsewhere goes stale without saying so.
• No admin screen for a configuration, no change to the invoice and no change to the order emails. OpenCart already prints every chosen option on the order page, the invoice and both emails, and resolves an uploaded file to a working download link. Product Configurator adds nothing there, and stores no record of its own against an order.
• Nothing to place on a layout. OpenCart lists Product Configurator under Design → Layouts, because it lists every module there. Placing it on a layout draws nothing.

What the customer sees, and what the page still contains

• Hiding is availability, not secrecy. Every option and every value attached to the product is in the page source, whether or not a rule reveals it. The page renders them all and the browser then hides what does not apply. That is what lets an option appear the instant the customer picks the answer that reveals it. If you were thinking of hiding a trade customers only option this way, it hides nothing from anybody who looks at the page source.
• Conditional options need JavaScript in the customer's browser. Without it, every option shows and nothing hides, and the rules are still enforced when the customer adds to the cart, by OpenCart's own validation. The page is degraded rather than broken, which is the safe direction: a page filtered on the server would leave a customer with JavaScript off unable to reach an option a rule was supposed to reveal.
• An answer already given is kept, never cleared. An option a rule hides keeps what the customer typed into it, and gets it back if the rule stops firing. Nothing hidden is ever submitted.
• Swatches are drawn only on a product that has rules. They ride the same rewrite of the product page that does the hiding, so a product with no rules keeps OpenCart's own rendering of its option values. There is nothing here that draws swatches on their own.
• A swatch grid needs the images to be there. Values are drawn as swatches from the image you set on Catalog → Options; no image is stored here and there is no image field of its own. For radio and checkbox options, values with an image become swatches and values without keep OpenCart's own row. For a dropdown, the grid is offered only when every value has an image, because a grid half made of blank tiles is worse than the dropdown it replaced.
• A theme that has rewritten the product form keeps its own page. The instant hide is added by finding OpenCart's add-to-cart form; a form that is structurally different is left alone, and the store falls back to the JavaScript-off behaviour above. Losing the instant hide makes a worse page; losing the page would be an outage. The Change options link on the cart is placed the same way: a cart list that is structurally different keeps its own page, without the link.

What the server refuses, and in whose words

Rules are enforced where OpenCart resolves a product's options, so OpenCart's own validation does the refusing, with its own messages, on the storefront, on its API, and in the admin order editor, all three at once.

• A rule the customer's browser did not honour is still refused. A stale page, a hand-built form or a copied URL cannot buy a combination the rules forbid.
• The wording of a refusal is OpenCart's, and on one path it reads oddly. Where a forbidden answer was given on a required option, the message is OpenCart's own …required against a control the customer did fill in. It is reachable only from a stale or tampered form, and rewriting OpenCart's own response on a route other extensions may also have touched is not something this extension will do.
• On an optional option, a forbidden answer is dropped without an error and the line is added without it, which is what a current page would have submitted anyway. The cart lists what was chosen.
• There is no message of your own for a refused combination. You cannot attach an explanation to a rule.
• A required option whose every value is sold out is a dead end, and the tab warns about it but does not prevent it. OpenCart hides sold-out values, so a require rule can leave the customer facing a required control with nothing to pick. OpenCart behaves the same way today for its own required options that have sold out; rules only make it conditional. The Configurator tab lists such an option when the product form opens, but it reads the stock as it was at that moment. Stock that runs out after the form was opened, or on a product nobody opens, gets no warning. The warning changes nothing either: the requirement still applies, and the product still cannot be bought in that configuration until the stock comes back or the rule changes.

Cart lines and orders

• Editing a line reopens the product page. Change options on the cart page brings the product back with the answers filled in. OpenCart cannot change a cart line's options in place (its update path writes the quantity and nothing else), so an edit is a re-add, and three things follow that are behaviour rather than faults:
  • the edited line moves to the end of the cart;
  • if the new configuration matches a line already in the cart, the two merge and their quantities add up;
  • the old line is removed only once the re-add succeeds, so wandering off mid-edit leaves your customer's cart as it was.
• Answers that are no longer available are dropped, with one general notice. A value that has sold out or been deleted since the line was added, or that a rule now hides, is not filled in, and the page says some of the options you chose are no longer available. It does not name them one by one.
• Lines already in the cart are not re-checked. Change a rule, and lines added before it stay as they are, through checkout and onto the order. Nothing is re-validated at checkout either, which is also what OpenCart does with its own option validation. If a rule change has to reach carts already built, there is no mechanism here to make it.
• A configuration is stored nowhere except in OpenCart's own cart and order rows. That is what keeps the order screen, the invoice and the emails working with no help from this extension, and it is why there is no screen here that lists which orders used which rules.

Products, variants and copies

• The builder is on the product form, as a tab called Configurator, for a product that is not a variant.
• A variant has no builder, and inherits its master's rules, because rules name catalogue options and a variant's options are its master's.
• Copying a product copies its rules. The copy lands disabled, the way every OpenCart copy does, so you open it before a customer can see it.
• Copy rules from replaces this product's rules with another product's, on the Configurator tab. Nothing is stored until you press OpenCart's own Save, so leaving the form without saving changes nothing. It replaces, and never adds: a tab that already holds rules asks before it replaces them. Pick a variant and you get its master's rules, because a variant has none of its own, and the message names the master. A copied rule that names an option or value this product does not have is kept and listed under No longer on this product:, and does nothing until you attach what it names or delete the rule.
• Copy rules from is offered only to a user group that can store rules: access to this extension's route, and permission to modify products. A group missing either does not see the row at all.
• Deleting a product deletes its rules.
• Deleting a master leaves its variants without the rules they were inheriting. OpenCart promotes them to standalone products, and a promoted variant carries no ruleset of its own. Nothing is fabricated to cover it, and nothing warns you. If you delete a master whose variants were being sold, open each promoted product and use Copy rules from on its Configurator tab to take the rules from a product that still has them, or write them again.

What the admin will and will not stop you doing

• A product save is never refused on rule grounds. OpenCart's product form gives an extension no way to stop a save, and painting a red alert over a save that succeeded would be a lie about what happened. So the builder prevents what it can while you write a rule, and the server refuses nothing afterwards.
• The one thing the builder prevents is naming the same option on both sides of a rule: once an option is a condition subject, it leaves the target picker, and the other way round.
• A half-built ruleset saves, and the tab lists what it can see is wrong with it, without refusing anything. A show rule nothing ever fires, a rule that hides what another requires, a rule aimed at an option you detach later: all of them save, because a screen that discards half a ruleset is worse than one that does nothing yet. Above the rules, the tab warns about three things, each line numbered the way the rules are:
  • A required option with nothing to pick: an option a require rule targets, or one OpenCart marks Required that a show rule targets, where every value on this product is sold out.
  • A rule that can never fire: one of its conditions names an option or value no longer on this product, or two of its conditions name different values of one dropdown or radio option. A rule whose condition names a sold-out value is listed as unable to fire while it is sold out. Where such a rule is a show, the line also says whether its target can still be shown by another show rule, or is never shown at all.
  • A require that never applies: a hide rule on the same option whose conditions are all among the require rule's own. Whenever the require holds, so does the hide, and hiding wins.
• Anything else is not flagged. Two values of a checkbox option can both be ticked, so a rule asking for both is not a mistake. A hide with different conditions from the require it overlaps is a deliberate exception. A rule aimed at an option that has gone is already listed under No longer on this product:.
• The warnings describe the product as it was when the form opened, which is what the storefront was serving then, and the tab says so. Rules you write or change in the same visit are not checked until you save and open the form again. There is no setting to turn the warnings off, because they cost nothing on the storefront and cannot block anything.
• An option removed from the form in the same session leaves its rules behind, inert, and they show up under No longer on this product: the next time you open the tab.
• Every save replaces a product's rules with what the tab posted. That is how deleting a rule on the tab works. A product form the tab could not be placed on (one rewritten by an admin theme or another extension) posts no rules at all, and its save leaves the product's rules exactly as they were: you cannot edit rules from that form, and you cannot lose them through it either. A variant is the same, because its rules are its master's and its save never touches them.
• Only a user group with permission to modify products can write rules, and that is checked again when the rules are stored rather than assumed from the screen you were on.

Where your data lives, and what a removal leaves

• Three tables of its own, and none of OpenCart's altered. They are created when you enable the module, again on every update, and never twice.
• Turning the module off changes nothing anywhere (no tab, no swatches, no hiding, no enforcement) and leaves every rule you wrote where it is. Copying and deleting a product still carry its rules while the module is off, so switching it back on finds each copy configured and no deleted product's rules left behind.
• Uninstalling from the extension list keeps your rules. It removes the settings and every event registration, because a registration pointing at files that have gone is a fatal error on somebody else's screen. The three tables and everything in them stay, so reinstalling puts the extension back over the rules it left behind — less the rules of any product deleted while it was uninstalled, which installing clears, so they cannot attach themselves to a later product given the same id. An update is also an uninstall and an install, which is why an update is not a re-authoring job.
• Removing the rules is a deliberate act: delete them on the tab, or drop the three product_configurator_* tables yourself.

Language

Product Configurator says almost nothing to a shopper: the button that reopens the options on a cart line, and the note explaining that some of its answers are no longer available and were not filled back in. Everything else on the page is OpenCart's own, or your own option names. Which strings are read in which language is answered, and counted, on the shared language promise page rather than claimed here.

Four things about it, the first being the most important:

• A sentence nobody has translated yet reaches a shopper in English, never blank and never as its own name. Both of those two strings are served with English underneath them, string by string rather than language by language, so a store whose language we ship nothing in gets English words rather than the name of a setting on a cart line.
• The screens you work in are translated as far as somebody has read them and no further, and the rest is English. A string a named reviewer has signed off is served in your admin language; a string nobody has read is served in English rather than blank or as its own identifier; and a string whose English has since been reworded goes back to English until it is read again. Which string is in which state is on that page. This is where nearly all of this extension's words are: the rule builder, its conditions and its refusals are read by you and by nobody else.
• Neither of the two shopper strings is yours to reword, and that is a decision rather than an oversight. One is a control's label and the other reports what happened (that answers could not be filled back in), and a rewording that turned it into reassurance would make the page wrong about what the extension did. There is therefore no wording panel on the settings screen, and nothing to fill in.
• The option and value names your rules are written against are OpenCart's own, per language, and none of this reaches them. A rule refers to an option by its id rather than by what it is called, so renaming Frame colour in one language does not disturb a rule, and translating it does not need one. What a shopper sees on the configurator is what OpenCart's own product options say in the language they are browsing in.

OpenCart 4.1.0.0: a product cannot be copied

On that release OpenCart's Copy button re-uses the option identifiers of the product it is copying, and the database refuses them. The copy fails with a duplicate-entry error and no product is created. It is every product with options on the store, not only configured ones.

• Copying is how most people make the second configured product. On 4.1.0.0 each one has to be set up from scratch instead, which works and takes longer.
• Products that already exist are unaffected, and so are their rules, their swatches, their prices and everything a shopper sees or does.

It is OpenCart's, not ours: pressing Copy on OpenCart's own shipped demo product on a bare 4.1.0.0 store, with nothing installed, fails the same way, and the same press on a bare 4.1.0.1 store succeeds. No extension can repair it: the failing insert is OpenCart's own, on OpenCart's own table, in a routine no extension is given a say in. That is why 4.1.0.0 is not one of the releases Product Configurator claims. OpenCart fixed it in 4.1.0.1; upgrading to that or newer is the whole of the remedy, and the settings screen says so while you are on 4.1.0.0.

Releases

• OpenCart 4.0.2.0 is the floor, and a store below it is refused outright with a message rather than half-installed.
• A release newer than the newest one tested is not blocked. The module's own screen says the store is newer than anything a test pass has been through, and carries on.
• The releases a full install-to-uninstall pass has run against are the ones named in the extension's own extension.json, and nowhere else.
• A PHP below the floor on requirements is refused too, and that refusal is written to the store's error log rather than shown on a screen.

Anything not described here should be assumed absent. If you are relying on something this page does not mention, ask before you buy.