Last indexed: 15 May 2026 (ea8ab8)

Product Display

Purpose and Scope

This document covers the product display system in Maho's frontend, including product list templates (grid and list views), individual product view pages, configurable product selections, and interactive components like toolbars and pagination. It focuses on the rendering logic, JavaScript interactivity for product options, and the data flow from the Mage_Catalog blocks to the frontend templates.

Maho modernizes the frontend experience by introducing asynchronous "Add to Cart" functionality via mahoFetch and a native off-canvas minicart integration.

Product Listing Display

Product listings are rendered through the Mage_Catalog_Block_Product_List block, which supports two display modes: grid and list. The display mode is controlled by the toolbar and can be toggled by users based on configuration.

Display Modes and Configuration

The default display behavior is governed by system configuration in the catalog/frontend path.

Config Field	Path	Purpose
List Mode	`catalog/frontend/list_mode`	Determines if grid, list, or both are available.
Grid Products Per Page	`catalog/frontend/grid_per_page`	Default pagination limit for grid view.
List Products Per Page	`catalog/frontend/list_per_page`	Default pagination limit for list view.
Enable Add to Cart	`catalog/frontend/enable_addtocart_in_product_listings`	Toggles the buy button in listings app/design/frontend/base/default/template/catalog/product/list.phtml71

Product List Template Structure

The product list template handles both grid and list modes within a single file using conditional logic. It integrates Maho's customFormSubmit utility for handling "Add to Cart", "Wishlist", and "Compare" actions via POST requests to prevent CSRF issues and simplify form handling.

Natural Language to Code Entity Space: Product Listing

Sources: app/design/frontend/base/default/template/catalog/product/list.phtml12-110

Key elements rendered for each product:

Product Image: Uses the catalog/image helper with 2x srcset for high-density displays app/design/frontend/base/default/template/catalog/product/list.phtml41-43
Action Buttons: "Add to Cart" functionality is gated by configuration app/design/frontend/base/default/template/catalog/product/list.phtml71
Comparison/Wishlist: Integrated via getAddToCompareUrlCustom and wishlist helper app/design/frontend/base/default/template/catalog/product/list.phtml89-108

Toolbar and Pagination

The toolbar (Mage_Catalog_Block_Product_List_Toolbar) manages the presentation state of the product collection, including sorting, view modes, and limiters.

Toolbar Component Logic

The toolbar provides an off-canvas trigger for layered navigation (filters) on mobile devices using data-offcanvas-target=".block-layered-nav" app/design/frontend/base/default/template/catalog/product/list/toolbar.phtml16

Sources: app/design/frontend/base/default/template/catalog/product/list/toolbar.phtml12-88

Pagination Implementation

The pager template (page/html/pager.phtml) handles the actual "Page X of Y" logic and jump links. It supports:

Previous/Next Jump: Logic for ... links when many pages exist app/design/frontend/base/default/template/page/html/pager.phtml70-84
Frame Pages: The range of page numbers visible around the current page app/design/frontend/base/default/template/page/html/pager.phtml74-80
Amount Display: Translates strings like %s-%s of %s for item counts app/design/frontend/base/default/template/page/html/pager.phtml25

Sources: app/design/frontend/base/default/template/page/html/pager.phtml1-112

Product Options and Configurable Selection

Individual product pages often require user input (custom options) or selection (configurable attributes). These are managed via a robust JavaScript architecture.

Configurable Product Logic

Configurable products use the Product.Config class to manage relationships between attributes like Color and Size. This class is initialized with product configuration data, including prices and tax settings public/js/varien/product.js13-21

State Management: Uses a Map to track selected attribute values public/js/varien/product.js17
Default Values: Can be set via config.defaultValues or URL parameters public/js/varien/product.js30-37
Dependency Flow: Selecting a parent attribute triggers fillSelect() for the next attribute in the hierarchy, filtering based on allowedProducts public/js/varien/product.js148-174 The configureElement() method handles the update of subsequent dropdowns and price reloading public/js/varien/product.js105-117
Dynamic Pricing: Updates the displayed price based on selected options using reloadPrice() public/js/varien/product.js117 The getOptionLabel() method formats the price display, considering tax configurations public/js/varien/product.js176-204
JSON Configuration: The Mage_Catalog_Block_Product_View_Type_Configurable::getJsonConfig() method generates the JSON object used to initialize Product.Config app/code/core/Mage/Catalog/Block/Product/View/Type/Configurable.php105-230 This includes attribute IDs, labels, prices, and associated product IDs.

Custom Options

Custom options (text, select, date, file) are handled by Product.Options public/js/varien/product_options.js13 This class iterates through all custom option elements on the page and updates prices based on user selections public/js/varien/product_options.js24-91

Price Calculation: The Product.OptionsPrice class aggregates base product price with option surcharges public/js/varien/product_options.js143-177 It uses addCustomPrices() to register option-specific price adjustments and reload() to update the displayed price public/js/varien/product_options.js191-193
File Uploads: Specialized handling for file options includes toggling between "save old" and "save new" actions via JavaScript functions toggleFileChange() and toggleFileDelete() app/design/frontend/base/default/template/catalog/product/view/options/type/file.phtml65-92
Date/Time: The Product.OptionsDate class provides logic to validate and adjust days in a month based on year selection, ensuring correct date options are presented public/js/varien/product_options.js94-133 The reloadMonth() method dynamically updates the day dropdown based on the selected month and year public/js/varien/product_options.js109-133
Validation: Custom validation rules are added for date/time options to ensure required fields are completed app/design/frontend/base/default/template/catalog/product/view/options/type/date.phtml33-51

Natural Language to Code Entity Space: Configurable Selection

Sources:

Widgets and Specialized Views

Maho includes several widgets for displaying products in specific contexts, such as "New Products" or "Recently Viewed".

New Products Widget: Uses Mage_Catalog_Block_Product_Widget_New and renders a grid of products marked as new app/design/frontend/base/default/template/catalog/product/widget/new/content/new_grid.phtml14-84
Image Processing: Widgets utilize the catalog/image helper for dynamic resizing, typically serving 210px images for grid widgets app/design/frontend/base/default/template/catalog/product/widget/new/content/new_grid.phtml28-30

Sources: app/design/frontend/base/default/template/catalog/product/widget/new/content/new_grid.phtml1-85

Image Processing Pipeline

Maho utilizes the catalog/image helper for dynamic resizing and caching of product images.

Feature	Implementation	Source
Resizing	`init($product, 'small_image')->resize(300)`	app/design/frontend/base/default/template/catalog/product/list.phtml41
Retina Support	`srcset` with 2x multiplier	app/design/frontend/base/default/template/catalog/product/list.phtml42
Composite Pricing	`Mage_Catalog_Helper_Product_Type_Composite`	Prepares prices for JS consumption app/code/core/Mage/Catalog/Helper/Product/Type/Composite.php13-33

Sources: app/design/frontend/base/default/template/catalog/product/list.phtml41-43 app/code/core/Mage/Catalog/Helper/Product/Type/Composite.php13-127

Refresh this wiki

URL: https://deepwiki.com/MahoCommerce/maho/6.3-product-display

⇱ Product Display | MahoCommerce/maho | DeepWiki