Product Reviews and Ratings

Purpose and Scope

This document details the technical implementation of the product review and rating system in Maho. It covers the data architecture of the Mage_Review and Mage_Rating modules, the frontend rendering pipeline using the base/default theme, the submission workflow utilizing HTML5 <dialog> elements, and the administrative moderation system.

System Architecture

The review system is decoupled into two primary modules: Mage_Review (handling text content and metadata) and Mage_Rating (handling numerical scores and criteria).

Code Entity Mapping

The following diagram maps high-level system components to their specific code entities and templates.

Sources:

Data Model and Storage

Maho uses a relational structure to separate review metadata from localized content and numerical ratings.

Entity Relationship

Sources:

Frontend Implementation

Review Summary Rendering

The summary is typically rendered in product listings or at the top of the product page. It calculates a percentage-based width for the star rating UI.

Function	Source	Purpose
`getRatingSummary()`	`Mage_Review_Block_Helper`	Returns the aggregate percentage (e.g., 80 for 4 stars)
`getReviewsCount()`	`Mage_Review_Block_Helper`	Returns the total number of approved reviews

Template Logic: The UI uses a rating-box container where the inner rating div width is set dynamically based on the summary percentage app/design/frontend/base/default/template/review/helper/summary.phtml18 A shorter version is used for catalog grids and widgets app/design/frontend/base/default/template/review/helper/summary_short.phtml18-19 If no reviews exist, the system can optionally display a prompt to "Be the first to review this product" app/design/frontend/base/default/template/review/helper/summary.phtml25-27

Detailed Review List

The full list of reviews is handled by Mage_Review_Block_Product_View_List.

Collection Loading: Loads reviews associated with the current product and store using getReviewsCollection() app/design/frontend/base/default/template/review/product/view/list.phtml15
Vote Retrieval: Each review object contains a collection of RatingVotes accessed via $_review->getRatingVotes() app/design/frontend/base/default/template/review/product/view/list.phtml27
UI Layout:
- Author Meta: Displays the nickname and formatted creation date app/design/frontend/base/default/template/review/product/view/list.phtml30-36
- Single Rating: If only one criteria exists, it is shown in the header app/design/frontend/base/default/template/review/product/view/list.phtml37-45
- Multiple Ratings: If multiple criteria (Quality, Price, etc.) are used, they are rendered in a footer list using $_vote->getRatingCode() app/design/frontend/base/default/template/review/product/view/list.phtml51-64

Sources:

Submission Workflow

Maho uses a modern HTML5 <dialog> based submission form to improve UX and reduce page reloads.

Sequence Diagram: Review Submission

Key Submission Components

Modal Trigger: Uses document.getElementById('review-dialog').showModal() in both empty and populated states app/design/frontend/base/default/template/review/product/view/list.phtml21-23 app/design/frontend/base/default/template/review/product/view/list.phtml71-73
Validation: A custom VarienForm validator validate-rating ensures at least one radio button is selected for every rating row app/design/frontend/base/default/template/review/form.phtml63-74
Form Security: Includes a formkey hidden input via $this->getBlockHtml('formkey') to prevent CSRF app/design/frontend/base/default/template/review/form.phtml22
Controller Logic: The postAction in Mage_Review_ProductController handles the lifecycle of a review submission, including setting the product ID, customer ID, and default status to pending app/code/core/Mage/Review/controllers/ProductController.php130-174 The route for this action is defined using the #[Maho\Config\Route] attribute: #[Maho\Config\Route('/review/product/post', name: 'review.product.post', methods: ['POST'])] app/code/core/Mage/Review/controllers/ProductController.php131

Sources:

Moderation and Configuration

Review Statuses

Reviews are not visible on the frontend until approved by an administrator.

Status	CSV Label	Frontend Visibility
Pending	`Pending`	Hidden (Default)
Approved	`Approved`	Visible
Not Approved	`Not Approved`	Hidden

Sources:

System Configuration

Administrators can control guest participation via the system configuration.

Guest Access: The preDispatch method checks getIsGuestAllowToWrite() app/code/core/Mage/Review/controllers/ProductController.php23-29
Redirection: If guests are not allowed and a user is not logged in, they are redirected to the login page app/code/core/Mage/Review/controllers/ProductController.php30-36
Frontend Prompt: If guest reviews are disabled, the frontend renders a login/registration prompt instead of the submission form app/design/frontend/base/default/template/review/form.phtml75-79

Localization

Review-related strings are managed via Mage_Review.csv. Key translations include:

"Your review has been accepted for moderation." app/locale/en_US/Mage_Review.csv94
"Only registered users can write reviews." app/locale/en_US/Mage_Review.csv48

Technical Data Retrieval

Detailed Ratings Block

The Mage_Rating_Block_Entity_Detailed block handles the retrieval of specific rating criteria (e.g., Quality, Price) for a product.

Entity Filter: Filters ratings by entity type (typically 'product') app/code/core/Mage/Rating/Block/Entity/Detailed.php45
Store Filtering: Ensures ratings and names are retrieved for the current store scope app/code/core/Mage/Rating/Block/Entity/Detailed.php47-48
Summary Logic: It calculates totals using getTotalReviews($entityId, true) and populates a collection with store-specific names app/code/core/Mage/Rating/Block/Entity/Detailed.php36-55

Sources:

app/code/core/Mage/Rating/Block/Entity/Detailed.php16-58

URL: https://deepwiki.com/MahoCommerce/maho/6.5-product-reviews-and-ratings