Options and variants
This page is for developers and merchants who sell products with choices. Exponential has four option datatypes; a customer's choice is posted with the add-to-basket form, stored with the basket item and copied into the order. This page explains which datatype fits which kind of choice and when a "variant" should be its own product.
Contents
The four option datatypes
| Datatype | Use for | Example |
|---|---|---|
ezoption | One list of choices, each with an optional additional price | Gift wrapping: none, standard (+2.00), premium (+5.00) |
ezmultioption | Several independent lists on one product | Size and color |
ezmultioption2 | Groups of option lists that can be nested, with rules between choices, for configurable products | A computer with base model, memory and extras |
ezrangeoption | A numeric range with a start, stop and step value | A length from 1 to 10 meters in steps of 1 |
All four live in kernel/classes/datatypes/. Their editing is covered in
Choosing datatypes for your fields.
How a choice travels
- The product's full template posts the add-to-basket form with the chosen option values (Basket, checkout and orders).
- The
addtobasketoperation stores the item in the basket's product collection, and each chosen option as an item option with its name, value and price (tableezproductcollection_item_opt). - Item prices are calculated with the option prices included; the basket and confirmation show them.
- At checkout the product collection becomes the order's, so the choice stays visible in the order view and the order mail even if the product changes later.
The workflow trigger shop_addtobasket receives the option_list, so an event on that trigger can check a choice
before the item is added (Workflows on shop triggers).
Options or separate products
| Prefer options when | Prefer separate products when |
|---|---|
| The choice changes the price a little or not at all | Each variant has its own item number for stock or accounting |
| All variants share images and description | Variants have their own images or descriptions |
| You do not track stock per variant | You will connect a stock system later |
| Customers see one product page | Customers should find each variant by search |
Separate products can share a parent folder or relations so that the page still shows "other colors". A shipping or stock integration usually needs an identifier per sellable unit, which favors separate products.
Template work
The shipped themes' product templates post the add-to-basket form; the option fields must be rendered inside that
form so their values are posted. The standard design shows chosen options in the basket and order templates under
design/standard/templates/shop/. Check every template that lists items: basket, confirmation, order view, order
receipt and order mail.
Checklist
- To do: Each option list has a clear label for screen readers (Store accessibility).
- To do: Additional prices include or exclude VAT the same way as the product's price.
- To do: A test order with options shows each choice in the basket, the order view and the mail.
- To do: Changing an option's price on the product does not change existing orders.
Related pages
- Catalog modeling
- Catalog modeling in depth
- Product classes and catalog
- Wishlists and baskets
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.