Product Options and Customization

This page documents the technical implementation of product customization in Maho, covering custom product options, configurable product selections, and downloadable product links. These systems allow for per-product flexibility beyond standard EAV attributes.

1. Custom Product Options

Custom options are per-product configurations (e.g., text engraving, file uploads) defined individually for each product rather than at the attribute set level.

Option Type Architecture

Options are categorized into groups, each handled by a specific type model. The Mage_Catalog_Model_Product_Option class acts as the entity, while specialized type classes handle validation and formatting.

Group Constant	Input Types	Type Model Reference
`OPTION_GROUP_TEXT`	`field`, `area`	`Mage_Catalog_Model_Product_Option_Type_Default`
`OPTION_GROUP_FILE`	`file`	`Mage_Catalog_Model_Product_Option_Type_File`
`OPTION_GROUP_SELECT`	`drop_down`, `radio`, `checkbox`, `multiple`	`Mage_Catalog_Model_Product_Option_Type_Select`
`OPTION_GROUP_DATE`	`date`, `date_time`, `time`	`Mage_Catalog_Model_Product_Option_Type_Date`

The mapping between types and groups is defined in Mage_Catalog_Model_Product_Option::getGroupByType().

Data Flow: Frontend to Cart

When a customer configures options on the product page, the Product.Options JavaScript class manages the state and price updates.

Title: Custom Option Interaction Flow

Sources: app/design/frontend/base/default/template/catalog/product/view/options.phtml28 app/design/frontend/base/default/template/catalog/product/view/options/type/text.phtml23 app/code/core/Mage/Catalog/Model/Product/Option/Type/File.php109-110

File Option Handling

File uploads require complex state management to handle new uploads, deletions, and existing files (e.g., during cart editing or reordering).

Key Logic:

State Management: Controlled via _action hidden fields: save_new, save_old (restore from config), or empty (delete) app/design/frontend/base/default/template/catalog/product/view/options/type/file.phtml19 The Mage_Catalog_Model_Product_Option_Type_File::_getCurrentConfigFileInfo() method checks for these actions to determine if an existing file should be restored or a new one processed app/code/core/Mage/Catalog/Model/Product/Option/Type/File.php81-97
Validation: _validateUploadedFile() checks for PHP upload errors (e.g., UPLOAD_ERR_INI_SIZE) and enforces requirements app/code/core/Mage/Catalog/Model/Product/Option/Type/File.php152-179
Security: getSanitizedFileExtension() filters allowed extensions against a forbidden list via the catalog helper app/code/core/Mage/Catalog/Block/Product/View/Options/Type/File.php34-42
Frontend Controller: A randomized JS variable (e.g., opFile123) manages the UI state for changing or deleting existing files app/design/frontend/base/default/template/catalog/product/view/options/type/file.phtml59-92
Server Limits: The block calculates the effective maximum file size by comparing upload_max_filesize and post_max_size PHP settings app/code/core/Mage/Catalog/Block/Product/View/Options/Type/File.php44-51

Sources: app/code/core/Mage/Catalog/Model/Product/Option/Type/File.php81-179 app/design/frontend/base/default/template/catalog/product/view/options/type/file.phtml12-92 app/code/core/Mage/Catalog/Block/Product/View/Options/Type/File.php20-51

2. Configurable Product Options

Configurable products allow customers to select variants based on attributes (e.g., Size, Color).

Implementation Blocks and Models

Block: Mage_Catalog_Block_Product_View_Type_Configurable generates the JSON configuration (getJsonConfig) used by the frontend to update prices and availability app/code/core/Mage/Catalog/Block/Product/View/Type/Configurable.php105-186
Type Instance: The product's type instance handles the retrieval of "used products" (simple variants) app/code/core/Mage/Catalog/Block/Product/View/Type/Configurable.php75
Attribute Logic: getAllowAttributes() fetches attributes that define the configuration (e.g., color, size) app/code/core/Mage/Catalog/Block/Product/View/Type/Configurable.php37-42

Frontend Configuration Logic

The getJsonConfig() method builds a complex object containing:

Attributes: IDs, codes, and labels app/code/core/Mage/Catalog/Block/Product/View/Type/Configurable.php141-146
Options: Label, price, and associated simple product IDs app/code/core/Mage/Catalog/Block/Product/View/Type/Configurable.php177-183
Stock Status: Whether the specific variant is in stock app/code/core/Mage/Catalog/Block/Product/View/Type/Configurable.php122

Title: Configurable Product Data Resolution

Sources: app/code/core/Mage/Catalog/Block/Product/View/Type/Configurable.php20-186 app/code/core/Mage/Catalog/Model/Product/Type/Abstract.php13-113

3. Composite Product Relationships

Composite products (Configurable, Bundle, Grouped) represent a collection of other products.

Abstract Type Behavior

The Mage_Catalog_Model_Product_Type_Abstract provides the foundation for all product types:

Relation Info: getRelationInfo() returns data objects describing links app/code/core/Mage/Catalog/Model/Product/Type/Abstract.php134-137
Children Discovery: getChildrenIds($parentId, $required) is implemented by specific types to find linked entities app/code/core/Mage/Catalog/Model/Product/Type/Abstract.php149-152
Editable Attributes: Filters EAV attributes based on the apply_to property of the attribute app/code/core/Mage/Catalog/Model/Product/Type/Abstract.php206-221

Validation Modes

Product types support different processing modes during cart addition:

Full Mode (PROCESS_MODE_FULL): All required options must be present app/code/core/Mage/Catalog/Model/Product/Type/Abstract.php77
Lite Mode (PROCESS_MODE_LITE): Only provided options are validated app/code/core/Mage/Catalog/Model/Product/Type/Abstract.php84

Sources: app/code/core/Mage/Catalog/Model/Product/Type/Abstract.php13-221 app/code/core/Mage/Catalog/Model/Product/Option/Type/File.php190-198

4. Technical Reference: Code to Entity Mapping

This diagram maps the internal Maho code symbols to the functional customization components.

Title: Code Entity Mapping

Sources: app/code/core/Mage/Catalog/Block/Product/View/Type/Configurable.php20-105 app/code/core/Mage/Catalog/Model/Product/Option/Type/File.php16-109 app/design/frontend/base/default/template/catalog/product/view/options/js.phtml15

5. Downloadable and Date Options

Date and Time Options

Handled via Mage_Catalog_Block_Product_View_Options_Type_Date.

Frontend: Uses Product.OptionsDate JS class app/design/frontend/base/default/template/catalog/product/view/options/js.phtml15
Validation: Includes custom JS validation rules for complete datetime fields (checking if day/month/year are all filled or all empty) app/design/frontend/base/default/template/catalog/product/view/options/type/date.phtml33-52

Text and Select Options

Text: Supports field and area types with character length validation app/design/frontend/base/default/template/catalog/product/view/options/type/text.phtml22-29
Select: Handles multiple choice types (radio, checkbox, dropdown) and manages price reload via opConfig.reloadPrice() app/design/frontend/base/default/template/catalog/product/view/options/type/select.phtml13-28

Sources: app/design/frontend/base/default/template/catalog/product/view/options/type/date.phtml12-53 app/design/frontend/base/default/template/catalog/product/view/options/js.phtml14-16 app/design/frontend/base/default/template/catalog/product/view/options/type/text.phtml12-31 app/design/frontend/base/default/template/catalog/product/view/options/type/select.phtml12-29

URL: https://deepwiki.com/MahoCommerce/maho/8.5-product-options-and-customization