Download the PHP package orangecat/module-product-lists without Composer

Orangecat_ProductLists

Saved product lists (order templates) for logged-in B2B customers — create, manage, and reorder from named lists.

Module: Orangecat_ProductLists Version: 1.0.0 License: OSL-3.0 Author: Oliverio Gombert [email protected]

Table of Contents

1. Overview
2. Theme Compatibility
3. Requirements
4. Installation
5. What Gets Installed
6. Configuration
7. Store Admin Guide
8. Buyer Guide
9. Developer Guide
10. REST API
11. Frontend Routes Reference
12. DevOps & Integrator Notes

Overview

Orangecat_ProductLists lets logged-in customers maintain multiple named product lists — essentially saved order templates. Each list holds products with their configured options (color, size, etc.) and quantities, which can be added to cart in one click.

The module handles:

• Creating, renaming, and deleting multiple product lists per customer
• Adding products (simple and configurable) to a list from the PLP, PDP, related products, and upsell blocks
• Updating item quantities within a list
• Adding all or selected items from a list to the shopping cart
• Exporting a list to CSV (SKU, price, qty, name, options, URL)
• Paginated "My Lists" dashboard and per-list detail page in the customer account
• AJAX-based list selector modal when multiple lists exist
• Optional AJAX mode for silent add-to-list without page reload

Position in the Orangecat B2B Dependency Chain

Orangecat_ProductLists is independent of Orangecat_Company. It works for any logged-in customer, whether they belong to a company or not.

The buy_request Field

Each product_list_item row stores a buy_request JSON blob — the same data structure Magento uses for cart line items. This preserves the full configurable option selection (e.g. {"super_attribute":{"93":52,"142":167},"qty":2}). ProductListItem::getBuyRequestObject() deserializes this blob into a DataObject ready to pass to Cart::addProduct(), overriding the stored qty with the item's dedicated qty column.

Theme Compatibility

Hyvä templates follow the view/frontend/templates/ convention (not view/hyva/).

Requirements

Installation

Via Git Submodule (recommended for this project)

Enable the Module

Run inside the PHP container (reward shell):

What Gets Installed

Database Tables

product_list

Index on customer_id. Deleting a customer cascades to all their lists.

product_list_item

Indexes on list_id and product_id. Deleting a list cascades to all its items.

EAV Attributes

None.

Data Patches

None. No default records, roles, or CMS pages are created.

Configuration

Path: Stores > Configuration > Orangecat > Product List

General Settings

Both settings are configurable at Default, Website, and Store view scope.

Store Admin Guide

There is no Admin UI for managing individual product lists or customer list items. Lists are owned and managed entirely by customers via the frontend.

Admin access is limited to:

• Enabling/disabling the feature: Stores > Configuration > Orangecat > Product List
• Viewing data directly: via database (product_list, product_list_item tables)

To grant a role access to the configuration section, assign the ACL resource Orangecat_ProductLists::config (visible under Stores > Settings > Configuration).

Buyer Guide

Accessing My Lists

After logging in, navigate to Account Dashboard > My Lists or go directly to:

The "My Lists" link appears in the customer account sidebar when Enable Product List is set to Yes.

Creating a List

From the My Lists page, click Add List. Enter a name and optional description in the modal dialog, then save.

Adding Products to a List

From a product listing page (PLP) or product detail page (PDP):

Click the Add to List button. If multiple lists exist, a modal appears to select the target list or create a new one inline. For configurable products, the required options (size, color, etc.) must be selected first — an error is shown if they are not.

If only one list exists and AJAX mode is enabled, the product is added silently.

Duplicate handling: Adding the same product with the same option selection to a list increments the existing item's quantity rather than creating a duplicate row.

Viewing a List

Click any list name from My Lists to open its detail page:

The detail page shows product thumbnails, names, configured options, unit prices, and a quantity field per item. A search box filters items by product name within the list.

Updating Quantities

Edit the quantity field for any item on the list detail page and click Update to save all changes at once.

Removing Items

Click Remove next to any item to delete it from the list immediately.

Adding to Cart

From the list detail page:

• Add All to Cart — adds every item to the cart, preserving configured options and quantities. Products remain in the list.
• Add Selected to Cart — check the items to add, optionally override qty, then click Add Selected to Cart.

After a successful add, the browser redirects to the cart.

Exporting a List

From the list detail page, click Export to download a CSV file with columns: SKU, Price, Qty, Name, Options, URL.

Deleting a List

From My Lists, click Delete next to a list. A confirmation dialog is shown. Deleting a list permanently removes it and all its items.

Developer Guide

Module Structure

Key Interfaces

ConfigInterface

ProductListsProviderInterface

ProductListInterface

ProductListItemInterface

Observers

This module registers no observers. There is no etc/events.xml.

Plugins

JS Components

Frontend

Both components use RequireJS AMD format and work on Luma and Breeze. Hyvä uses Alpine.js templates instead.

Admin JS

None.

Email Templates

This module sends no transactional emails. There are no email template files.

ACL Resources

Adding Custom Logic

• Extend the provider: Implement or decorate ProductListsProviderInterface via di.xml preference to change how lists are loaded (e.g., filter by company, add sharing across company users).
• Extend item behavior: Override ProductListItemInterface preference to add custom buy-request transformations before items are added to cart.
• Add new add-to-list placements: Inject a block extending Orangecat\ProductLists\Block\Catalog\Product\ProductList\Item\AddTo\ProductList into any layout handle with Helper\Data::getListParams($product) to generate the required data-post attribute.

REST API

This module exposes no REST API endpoints. There is no etc/webapi.xml.

Frontend Routes Reference

Route ID: product_lists (front name: product_lists)

All ownership checks are enforced by filtering collections on both customer_id and the requested entity ID — no separate authorization layer is needed.

DevOps & Integrator Notes

Deployment Checklist

Integration Token Scope

This module has no REST API. No integration token permissions are required to consume it. Direct database access to product_list / product_list_item requires no ACL resource.

For Admin panel config access, grant Orangecat_ProductLists::config.

Disabling Without Uninstalling

Disabling hides the "My Lists" nav link (ifconfig guard on the layout block) and stops all frontend routes from resolving, but leaves the database tables and data intact.

Data Integrity Notes

• Deleting a customer triggers a cascade delete of all their product_list rows, which in turn cascades to all product_list_item rows for those lists.
• Deleting a product does not cascade to product_list_item (no FK enforced on product_id). Orphaned items pointing to deleted products are skipped gracefully at render and cart-add time.
• The buy_request JSON blob may become stale if a configurable product's attribute options change after an item was saved. The cart-add action will reject an invalid option combination with a LocalizedException.
• No unique constraint exists on (list_id, product_id) — the application layer deduplicates by matching super_attribute values and incrementing qty instead of inserting.