Feature: Product Catalog
Relevant source files
The following files were used as context for generating this wiki page:- apps/catalog/views.py
- apps/catalog/models.py
- apps/catalog/urls.py
- apps/catalog/templates/catalog/catalog.html
- apps/catalog/templates/catalog/product_detail.html
- apps/main/models.py
- apps/catalog/static/catalog/js/catalog.js
- apps/catalog/templates/catalog/category.html
- apps/main/templates/main/product_detail.html
The Product Catalog is a core feature of the Becathlon application, providing the primary interface for users to browse, search, filter, and view sports equipment. It encompasses everything from the main product listing page, which supports advanced filtering and sorting, to individual product detail pages with image galleries and related product suggestions.
This module is designed to deliver a comprehensive e-commerce browsing experience. It handles the presentation of products and their categories, manages user interactions for filtering, and offers a "Quick View" modal for rapid product inspection without leaving the catalog page. The system is built upon a data model that separates products, categories, and product images for a flexible and scalable structure.
Data Models
The catalog's functionality is supported by several key Django models. The primary models for products and their types are defined in apps/main/models.py, while catalog-specific models like ProductImage are in apps/catalog/models.py.
This diagram illustrates the relationships between the main entities in the product catalog system.
ProductType
Represents a category for products (e.g., "Running", "Cycling").
| Field | Type | Description |
|---|---|---|
name | CharField(100) | The unique name of the category. |
description | TextField | An optional description for the category. |
Sources: apps/main/models.py:16-21
Product
The central model representing a sellable item.
| Field | Type | Description |
|---|---|---|
product_type | ForeignKey to ProductType | The category this product belongs to. |
name | CharField(255) | The name of the product. |
description | TextField | A detailed description of the product. |
price | DecimalField | The price of the product. |
stock | IntegerField | The available quantity of the product. |
image_url | URLField | A URL for the main product image. |
brand | CharField(100) | The brand of the product (optional). |
rating | FloatField | The product's rating (optional). |
created_by | ForeignKey to User | The user who created the product listing. |
created_at | DateTimeField | Timestamp of when the product was created. |
updated_at | DateTimeField | Timestamp of the last update. |
Sources: apps/main/models.py:24-43
ProductImage
Stores additional images for a product, enabling a gallery view.
| Field | Type | Description |
|---|---|---|
product | ForeignKey to Product | The product these images are associated with. |
image_url | URLField | The URL of the image. |
alt_text | CharField(255) | Alternative text for the image (optional). |
order | PositiveIntegerField | The display order for the image in a gallery. |
Sources: apps/catalog/models.py:5-15
URL Routing and Views
The catalog app defines several URL patterns to handle different aspects of product browsing. These are mapped to specific view functions that contain the business logic for fetching and displaying data.
Sources: apps/catalog/urls.py, apps/catalog/views.py
URL Endpoints
| Path | View Name | View Function | Description |
|---|---|---|---|
/ | home | catalog_home | Displays the main catalog page with all products and filters. |
category/<int:category_id>/ | category | category_view | Displays products belonging to a specific category. |
product/<int:pk>/ | product_detail | product_detail_view | Shows the detailed page for a single product. |
api/product/<int:pk>/quick-view/ | product_quick_view | product_quick_view | API endpoint to fetch data for the Quick View modal. |
Sources: apps/catalog/urls.py:4-8
Catalog Page Request Flow
The following diagram shows the process of a user requesting the main catalog page, applying filters, and receiving the filtered product list.
Filtering and Sorting Logic
The catalog views (catalog_home and category_view) implement robust filtering and sorting based on GET parameters from the URL.
Sources: apps/catalog/views.py:22-150
Filter Parameters
| Parameter | Type | Description |
|---|---|---|
categories | list of int | A list of ProductType IDs to filter by. |
min_price | float | The minimum price for products. |
max_price | float | The maximum price for products. |
in_stock_only | boolean | If true, only shows products with stock > 0. |
search | string | A search term to match against product names and descriptions. |
sort_by | string | The sorting order. Options: newest, price_low, price_high, name_asc, name_desc. |
Sources: apps/catalog/views.py:38-130, apps/catalog/templates/catalog/catalog.html:15-70
The backend uses Django's Q objects to build complex queries that combine these filters. For example, the search functionality checks both the product name and description.
# Snippet from apps/catalog/views.py
if search_query:
products = products.filter(
Q(name__icontains=search_query) | Q(description__icontains=search_query)
)
Sources: apps/catalog/views.py:98-101
Frontend and User Interface
The user interface for the catalog is composed of several templates and is enhanced with JavaScript for interactive features.
Catalog and Category Pages
Both the main catalog (catalog.html) and the category-specific pages (category.html) share a similar two-column layout:
- Sidebar: Contains a form with all filtering and sorting options. This includes a collapsible and searchable category list, price range inputs, a stock availability checkbox, and a search bar. Applying filters is done via a standard form submission, which reloads the page with new GET parameters.
- Main Content: Displays a grid of
product-cardelements. Each card shows the product image, name, price, stock status, and buttons for "View Details" and "Quick View". Pagination controls are present if the number of products exceeds the page limit.
Sources: apps/catalog/templates/catalog/catalog.html, apps/catalog/templates/catalog/category.html, apps/catalog/static/catalog/js/catalog.js:8-85
Product Detail Page
The product_detail.html template provides a comprehensive view of a single product. Key sections include:
- Image Gallery: A main image with clickable thumbnails below to switch between different product views.
- Product Information: Displays the product name, price, stock status, and a detailed description.
- Action Panel: Includes a quantity selector and an "Add to Cart" button.
- Related Products: A section at the bottom showcasing other products from the same category.
An ambient lighting effect, controlled by apps/main/static/main/js/product_detail.js, extracts the dominant color from the product image to create a subtle background glow, enhancing the visual presentation.
Sources: apps/catalog/templates/catalog/product_detail.html, apps/main/templates/main/product_detail.html, apps/main/static/main/js/product_detail.js:25-116
Quick View Modal
This feature allows users to quickly inspect a product without navigating away from the catalog grid.
- The user clicks the "Quick View" button on a product card.
- JavaScript captures the
data-product-idfrom the button. - An asynchronous
fetchrequest is sent to the/catalog/api/product/<id>/quick-view/endpoint. - The server responds with a JSON object containing the product's details.
- The JavaScript dynamically builds the HTML for the modal, populates it with the fetched data, and displays it to the user.
The sequence diagram below illustrates this flow.
Conclusion
The Product Catalog feature is a well-structured and essential component of the Becathlon project. It effectively combines Django's powerful ORM for filtering and data management with a dynamic frontend that enhances user experience through features like the AJAX-powered Quick View modal. The clear separation of concerns between models, views, templates, and static files makes the system maintainable and extensible. It serves as the primary gateway for customers to discover and engage with the products offered on the platform.