Product Frontend Display

Purpose and Scope

This page documents the frontend customer-facing display system for products in the GP247/Shop e-commerce platform. It covers how customers browse products, view product details, filter and sort product listings, and navigate through categories and brands. The system handles language switching for SEO-friendly URLs, view template resolution, and product interaction tracking.

For product data models and backend business logic, see Product Model and Business Logic. For administrative category management, see Category Management. For shopping cart and order functionality, see Shopping Cart and Order System.

System Architecture Overview

The frontend display system is organized into three primary controllers that extend RootFrontController:

Controller	Primary Responsibility	Key Methods
ShopProductController	Product listings and details	allProductsProcessFront(), productDetailProcessFront(), processFilter()
ShopCategoryController	Category navigation and products	allCategoriesProcessFront(), categoryDetailProcessFront()
ShopBrandController	Brand navigation and products	allBrandsProcessFront(), brandDetailProcessFront()

All three controllers follow a consistent pattern: public methods handle route processing and language switching, while private methods contain the core business logic.

Sources: src/Controllers/ShopProductController.php1-267 src/Controllers/ShopCategoryController.php1-159 src/Controllers/ShopBrandController.php1-126

Request Flow and Language Switching

Language-Aware URL Processing

All frontend controllers support optional language prefixes in URLs when GP247_SEO_LANG is enabled. The pattern is:

1. With SEO Language Enabled: /en/products → allProductsProcessFront('en')
2. Without SEO Language: /products → allProductsProcessFront()

The public methods extract the language parameter and call gp247_lang_switch($lang) before delegating to private methods.

Sources: src/Controllers/ShopProductController.php21-28 src/Controllers/ShopProductController.php80-90 src/Controllers/ShopCategoryController.php23-30 src/Controllers/ShopBrandController.php21-28

Product Listing Display

All Products Page

The all products page displays paginated products with filtering capabilities.

The _allProducts() method constructs a fluent query chain on the ShopProduct model. It applies the following in sequence:

1. Limit: Set from gp247_config('product_list') configuration
2. Pagination: Enable pagination via setPaginate()
3. Sort: Optional sort criteria from filter processing
4. Price Range: Optional price range filtering
5. Brand Filter: Optional brand ID filtering
6. Category Filter: Optional category ID filtering

Sources: src/Controllers/ShopProductController.php34-72

Category Detail Page

Category detail pages show subcategories and products within a specific category.

The _categoryDetail() method implements a comprehensive category display:

1. Retrieves the category by alias using ShopCategory::getDetail()
2. Gets all child category IDs via getListSub()
3. Filters products belonging to the category and all its descendants
4. Applies additional filters (sort, price, brand) from request parameters
5. Retrieves subcategories for display
6. Builds hierarchical breadcrumb navigation
7. Returns view with category, subcategories, and filtered products

Sources: src/Controllers/ShopCategoryController.php86-157

Brand Detail Page

Brand detail pages display all products associated with a specific brand.

The brand detail implementation is simpler than categories since brands don't have hierarchies. It retrieves the brand, filters products by brand ID, applies optional sort/price filters, and renders the product list.

Sources: src/Controllers/ShopBrandController.php82-124

Product Detail Page

Detail Page Flow

Product Validation Logic

The system validates products before display using several criteria:

Validation Check	Configuration	Behavior
product->status	N/A	Product must be active
Stock management enabled	gp247_config('product_stock')	If enabled, additional checks apply
Display out of stock	gp247_config('product_display_out_of_stock')	If disabled, requires stock > 0
Stock level	product->stock	Must be > 0 if stock management enabled and display_out_of_stock disabled

The validation logic at src/Controllers/ShopProductController.php103:

if ($product && $product->status && 
 (!gp247_config('product_stock', $storeId) || 
 gp247_config('product_display_out_of_stock', $storeId) || 
 $product->stock > 0))

Sources: src/Controllers/ShopProductController.php99-167

Last Viewed Products Tracking

The system tracks recently viewed products in a browser cookie:

1. Cookie Name: productsLastView
2. Format: JSON object with product_id: timestamp pairs
3. Expiration: 1440 * config('gp247-config.shop.cart_expire.lastview') minutes
4. Sorting: Most recent products first (arsort by timestamp)

The tracking occurs on every product detail page view at src/Controllers/ShopProductController.php111-117

Sources: src/Controllers/ShopProductController.php111-118

Related Products

Related products are retrieved based on shared categories:

1. Extract all category IDs from product->categories
2. Query products in those categories using getProductToCategory()
3. Apply random sorting via setRandom()
4. Limit by gp247_config('product_relation') configuration

Sources: src/Controllers/ShopProductController.php120-141

Filter Processing System

Filter Types and Processing

The processFilter() method handles five filter types:

Sort Filter Mapping

The sort filter maps user-friendly strings to database field and order pairs:

Filter Value	Database Field	Sort Order
price_desc	price	desc
price_asc	price	asc
sort_desc	sort	desc
sort_asc	sort	asc
id_desc	id	desc
id_asc	id	asc

Sources: src/Controllers/ShopProductController.php185-203

Category Filter with Hierarchy

Category filtering includes descendant categories to ensure products in child categories are shown:

1. Convert comma-separated aliases to category IDs
2. Query parent field to find immediate children (arrayMid)
3. Query parent IN (arrayMid) to find grandchildren (arraySmall)
4. Merge all three arrays for complete hierarchy filtering

This ensures browsing a parent category shows products from all nested levels.

Sources: src/Controllers/ShopProductController.php221-234

Brand Filter Processing

Brand filtering converts aliases to IDs:

1. Split comma-separated brand aliases
2. Query ShopBrand using whereIn('alias', $arr_brand)
3. Extract IDs via pluck('id')->toArray()
4. Pass to getProductToBrand() query method

Sources: src/Controllers/ShopProductController.php211-219

View Resolution and Template Rendering

View Path Resolution

The system uses a two-part view resolution strategy:

1. Template Path: Base path from $this->GP247TemplatePath (inherited from RootFrontController)
2. Subpath: Specific screen or component path (e.g., screen.shop_product_list)
3. Resolution: gp247_shop_process_view() combines these paths
4. Validation: gp247_check_view() ensures the view exists

Sources: src/Controllers/ShopProductController.php55-58 src/Controllers/ShopCategoryController.php44-46 src/Controllers/ShopBrandController.php41-43

Common View Templates

View Subpath	Purpose	Used By
screen.shop_product_list	Product listing grid	All products, category detail, brand detail
screen.shop_product_detail	Product detail page	Product detail
screen.shop_item_list	Generic item listing	Category list, brand list
common.item_single	Single item card	Item list rendering
common.pagination	Pagination controls	All paginated lists
common.pagination_result	Pagination result count	All paginated lists

Sources: src/Views/front/screen/shop_item_list.blade.php1-67

View Data Structure

All view methods return consistent data structures:

Key	Type	Description
title	string	Page title for SEO
description	string	Meta description
keyword	string	Meta keywords
layout_page	string	Layout identifier for template system
breadcrumbs	array	Hierarchical navigation trail
products	Collection	Paginated product collection
filter_sort	string	Current sort filter value
og_image	string	Open Graph image URL

Sources: src/Controllers/ShopProductController.php58-71 src/Controllers/ShopCategoryController.php138-153 src/Controllers/ShopBrandController.php103-120

Item List Template Pattern

Reusable List Template

The shop_item_list.blade.php template provides a reusable pattern for displaying any paginated collection of items (categories, brands, etc.):

The template expects:

• Variable: $itemsList - Paginated collection
• Layout Page: Identifier for layout system (e.g., shop_item_list)
• Item Properties: Each item must have getThumb(), getUrl(), and title methods/properties

Sources: src/Views/front/screen/shop_item_list.blade.php1-67

Item Single Partial

Each item renders via the common.item_single partial by providing:

This enables consistent rendering across categories, brands, and other catalog items.

Sources: src/Views/front/screen/shop_item_list.blade.php29-38

Breadcrumb Navigation

Breadcrumb Structure

All frontend pages include breadcrumb navigation for user orientation:

Breadcrumbs are arrays of associative arrays with url and title keys:

Category Breadcrumb Hierarchy

Category detail pages build three-level breadcrumbs:

1. Root: Link to all categories
2. Parent: Link to parent category (if exists)
3. Current: Current category name (no link)

The system queries the parent category by ID to construct the middle level.

Sources: src/Controllers/ShopCategoryController.php120-132

Data Aggregation Method

The dataFilter() method provides a unified interface for retrieving filtered products with all processing logic:

1. Calls processFilter() with all filter types
2. Constructs ShopProduct query chain
3. Applies all filters (sort, price, brand, category, keyword)
4. Sets limit from configuration
5. Enables pagination
6. Returns data via getData()

This method can be used by AJAX endpoints or other components needing filtered product data without duplicating logic.

Sources: src/Controllers/ShopProductController.php244-265

Multi-Store Context

All frontend display operations respect the current store context:

• Store ID Resolution: config('app.storeId') provides the current store
• Product Visibility: Products are filtered by store via junction tables (see Multi-Store Architecture)
• Configuration: Display settings like product_list, product_relation are store-specific
• Stock Display: product_stock and product_display_out_of_stock configurations are per-store

The store context is applied automatically by the model query builders and configuration system, requiring no explicit filtering in controllers.

Sources: src/Controllers/ShopProductController.php101-103