Cart Products - extend EXT:cart with products 

Extension key

cart_products

Package name

extcode/cart-products

Version

main

Language

en

Author

Daniel Gohlke & Contributors

License

This document is published under the Open Publication License.

Rendered

Fri, 24 Apr 2026 18:59:32 +0000

Cart Products needs to be used together with EXT:cart.

• EXT:cart itself is only the base for a webshop.

• EXT:cart_products provides products which can be created in the TYPO3 backend.

  • Those products fit many use cases for "usual products" (no books, no events).
  • The products can be displayed on the website with a list view and a detail view.
  • As said does it extend EXT:cart so those products can be purchased with the cart of EXT:cart.

Slack 

There is an own channel at the TYPO3 Slack. Please use this channel to ask questions.

The URL is: https://typo3.slack.com/messages/ext-cart/

Support 

If you need further support, please contact me.

This support is not always free!

Install the extension 

Depending on your needs you have three options to install the extension.

composer require extcode/cart-products

git clone git@github.com:extcode/cart_products.git

Include TypoScript 

The extension ships some TypoScript code which needs to be included. There are two valid ways to do this:

plugin.tx_cartproducts.settings 

The most parameter are described in the documentation of EXT:cart, so here only the individual parameter are described.

Language 

Display the language of the product which is currently edited.

Type 

Products can have 4 different types:

SKU (Stock Keeping Unit) 

The product identifier, when using Variants the resulting identifier will be this base with trailed SKUs of the chosen variants.

Title 

Title of the product

URL segment 

The url segment which is used in the URL when RouteEnhancers are defined.

Teaser 

A shorter description of the product. By default this will be displayed on the detail page below the title. In individualized implementations it could be shown in the list view or in the search results when using a page search.

Description 

A longer description of the product. This is limited to text, for further options the below descriped 'Content' can be used.

Content 

Allows to add further descriptions with any available content record ('CType'). This makes it possible to add content like it's possible on usual pages in the backend. Longer descriptions with e.g. images and videos are possible with this feature.

Images 

Add images to the product which will be displayed in detail view and list view.

Files 

Add files to the product. The default implementation does not render the files. To display for example download links it would be an idea to overwrite /Resources/Private/Template/Product/Show.html.

Minimum numbers of product items per order 

Defines the minimal number that needs to be in the cart to buy this product.

It is possible to add less articles into the cart but a warning message will be displayed in the cart itself and it's not possible to finish the order.

Maximum numbers of product items per order 

Defines the maximal number that are allowed to be in the cart to buy this product.

It is possible to add more articles into the cart but a warning message will be displayed in the cart itself and it's not possible to finish the order.

Is Net Price 

Decides whether the price entered in the backend is net or gross.

Price 

The price of the product. When using BE variants this price will be part of the price calculation or might be ignored at all.

Tax class 

The tax class of the product. Tax classes are defined in EXT:cart.

Special Prices 

Allows to add prices for logged-in FE users. This can also be limited to FE user with a certain user group which allows to offer different prices depending on the user group.

If multiple special prices exist the best special price will be applied.

When using BE variants this field will be ignored as the special price needs to be defined for every single BE variant.

Quantity discount 

Allows to offer better prices when the amount of products in the cart exceeds a certain limit.

Concept of Measures 

When selling products in different quantities (e.g. 0.5 kg, 1 kg, 5 kg) it can be a legal demand to indicate the base price to make it possible for customers to compare the different quantities ('value-for-money ratio').

The three fields in this group are used together. The following example shows the usage. To stay with the example from above you might enter:

• Price = 10 € (defined in the tab Prices).
• Price Measure = 200
• Price Measure Unit = g
• Base Price Measure Unit = kg

Which will result in 50 €/kg.

Concept of Service Attributes 

Entering something in the service attribute fields does not have any effect by default. These fields provide a base to implement individual functionality. An example might be the best way to show the potential:

Stock Handling 

Stock handling allows to limit the available amount of products. Customers can not buy more products than the available amount.

Stock Handling in variants 

When a product uses BE variants it is possible to activate "Stock handling in variants". In this case it is needed to set the available amount for every BE variant that exists for the product.

Difference between Frontend Variants and Backend Variants 

Backend Variants can influence the price of a product while Frontend Variants foremost are used to get additional data from the customer.

The following example uses a T-shirt asBE variant product to illustrates the difference of both variants.

• Frontend Variant

  • The customer is able to enter a text which will be printed on the T-shirt. Therefore the product has an input field.
  • This does not influence the price of the product but just enables the customer to add additional information.

• Backend Variant

  • The shop owner sells the T-Shirt in different sizes S, M, L.
  • The available options are stored as BE variants in the product with different prices.
  • The customer can choose one of the options from a select list.
  • The choice of the customer changes the price of the T-Shirt.

Create Backend Variants 

It requires multiple steps to create Backend Variants. Which can be quite overwhelming at the beginning offers maximum flexibility and is logical once you get used to it.

1. Create a Backend Variant Attribute

   A Backend Variant Attribute determines the type of variant.

   An example is Size for a T-shirt.

   The record for a Backend Variant Attribute is created directly within a TYPO3 page.

   

   Note

   Backend Variants need to be placed on the same page as the product itself.

2. Create Backend Variant Attribute Options

   A Backend Variant Attribute Options is one certain instance of a Backend Variant Attribute which will be an option for the customer.

   An example is XXL as Size of a T-shirt.

   Such an attribute is created within a Backend Variant Attribute.

   

3. Set Backend Variant Attributes within Product

   The above defined Backend Variants Attribute is chosen within the product in the Tab "Variants".

   It is possible to define up to 3 different Backend Variants Attributes within a product, e.g. size, color and cut. The available combinations are defined in the next step.

   

4. Create final Backend Variants within Product

   Create a new Backend Variant.

   A single Backend Variant select for every above defined a Backend Variant Attribute an Backend Variant Attribute Option (as defined in step 2).

   

5. Set further values for the variant

   Set which price this variant shall have (as described below), additionally it is possible to set stock and price measures.

Price calculation for Backend Variants 

The price calculation for a Backend Variant can be set with multiple options:

Selection	Description
1: Product Price	Use price of product itself.
2: Variant Price	Use price of variant itself.
3: Product Price - Variant Price	Subtract variant price from product price.
4: Product Price - (Variant Price %)	Subtract variant as percentual amount of product price.
5: Product Price + Variant Price	Add variant price from product price.
6: Product Price + (Variant Price %)	Add variant as percentual amount of product price.

Create Frontend Variants 

A Frontend Variant is created directly within the product in the tab Variants.

Tag 

Add one or multiple tags to the product. By default the tag will simply be rendered in the detail view. Page with a page search (e.g. solr) could use tags as filter.

Main Category 

Within a category it is possible to define the list view PID and detail view PID for products which have this category. This is the category which determines which page the product uses as detail view if the teaser plugin is set and when the detail view PID was set within the category.

Furthermore it is possible to define one or more categories in the list view plugin of EXT:cart_products so that only products with this/these categories are shown.

Associated Categories 

This field can be used if a product shall be shown in multiple list view.

Plugin "Cart: Products" 

This plugin shows a list of products and / or the detail view of product.

Usage:

• You MUST add a Record Storage Page.
• You CAN add categories to only show products of one or multiple specific categories which are on the chosen record storage page.
• When using another detail page you MUST set a Product Detail Page.

Plugin "Cart: selected Products" (also known as Teaser plugin) 

This plugin shows specific products which are chosen by the editor in the Backend.

You do not need to set a detail page if every product has a category and you set a detail page for every category.

You can set detail view for a category by opening the edit view of a system category and then

Options → Cart: Page for the detail view of Products of this category.

Integration 

The following snippets show an example where the first image of a product is used:

<?php

declare(strict_types=1);

namespace Vendor\Cartintegration\EventListener\Cart\Create;

use Extcode\CartProducts\Event\RetrieveProductsFromRequestEvent;

class ExtendCartProduct
{
    public function __invoke(RetrieveProductsFromRequestEvent $event): void
    {
        $productProduct = $event->getProductProduct();
        $cartProduct = $event->getCartProduct();

        // Using null safe operator to avoid errors
        $imageUid = $productProduct?->getFirstImage()?->getOriginalResource()?->getOriginalFile()?->getUid() ?? null;

        if ($imageUid) {
            $cartProduct->setAdditional(
                'previewImage',
                $imageUid
            );
        }
    }
}

services:
  _defaults:
    autowire: true
    autoconfigure: true
    public: false

  Vendor\Cartintegration\:
    resource: '../Classes/*'
    exclude: '../Classes/Domain/Model/*'

  Vendor\Cartintegration\EventListener\Cart\ExtendCartProduct:
    tags:
      - name: event.listener

// This snippet is simplified and needs adaption for your styling!

<f:section name="withoutVariant">

    ...

    <f:if condition="{product.additionalArray.previewImage}">
        <f:image src="{product.additionalArray.previewImage}"/>
    </f:if>

...

<f:section name="withVariant">

    ...

    <f:for each="{product.beVariants}" as="variant">
        <f:if condition="{product.additionalArray.previewImage}">
            <f:image src="{product.additionalArray.previewImage}"/>
        </f:if>

...

Integration 

Create in your extension (e.g. your EXT:sitepackage) an overwrite of EXT:cart_products/Resources/Private/Partials/Products/CartForm.html.

Then you add the snippet as shown below:

...

<f:if condition="{product.beVariants}">
    <f:asset.script identifier="multi-selector" src="EXT:cart_products/Resources/Public/JavaScripts/cart.js" />

    ...

Integration 

Create in your extension (e.g. your EXT:sitepackage) an overwrite of EXT:cart_products/Resources/Private/Partials/Products/List/Grid.html or EXT:cart_products/Resources/Private/Partials/Products/List/Table.html.

Then you add the snippet as shown below:

...
<f:cObject typoscriptObjectPath="lib.cartProduct.showForm" data="{productUid: '{product.uid}'}"/>
...

Features 

Description 

After the release of the werkraummedia/watchlist extension for TYPO3 v13 the WatchlistItemHandler for extcode/cart-products can be added again. This allows products to be added to the watchlist.

Features 

Description 

If you have a long list of products, you would like to display them in a pagination with a defined number of products per page. This is already possible with the TypoScript configuration itemsPerPage. With a large number of products, the display of all page links may not work well, especially when it comes to the display on mobile devices. The TYPO3 core offers the SlidingWindowPagination since TYPO3 v12. This is compatible with the previously used SimplePagination if you pass the value 0 for the number of links.

Integration 

Set the new TypoScript configuration variable plugin.tx_cartproducts.maximumNumberOfLinks to a value greater than 0. If you use an own template file for Resources/Private/Partials/Utility/Paginator.html you have to adapt the changes to your file.

Breaking Changes 

Features 

Description 

EXT:cart v9 uses modularized JavaScript without jQuery (see [TASK] Switch from jQuery to vanilla JavaScript #438 <https://github.com/extcode/cart/pull/438>).

This allows to add the JavaScript only on pages where it's really needed which is good for performance. The JavaScript is for detail pages is now loaded with the TYPO3 Asset.script ViewHelper <https://docs.typo3.org/other/typo3/view-helper-reference/12.4/en-us/typo3/fluid/latest/Asset/Script.html>.

Affected Installations 

All installations which overwrite Resources/Private/Partials/Product/CartForm.html are affected. When using the CartForm.html which comes with this extension it will work without any changes.

Migration 

The JavaScript in EXT:cart is no longer added via TypoScript. All JavaScript files are now added via ViewHelper.

Two ViewHelpers needs to be added in Resources/Private/Partials/Product/CartForm.html:

• <f:asset.script identifier="add-to-cart" src="EXT:cart/Resources/Public/JavaScript/add_to_cart.js" />
• <f:asset.script identifier="change-be-variant" src="EXT:cart/Resources/Public/JavaScript/change_be_variant.js" /> (only when working with BE Variants).

Description 

With the version for TYPO3 v12 the references uses the key 'images' in column fieldname of table sys_file_reference. Before the key was 'image' (singular). Due to this the images are no longer shown, neither in the backend nor in the frontend.

Affected Installations 

All installations which are not set up with version 5 of EXT:cart_products (before TYPO3 v12).

Migration 

Run the UpdateWizard "Updates image references for EXT:cart_products".

Description 

The view for detail pages (/Resources/Private/Template/Show.html) got the Frontend user from the controller which was never used. Due to missing usage the user is no longer given.

Affected Installations 

All existing installations that uses the Frontend user in customized templates.

Description 

Switchable Controller Actions are removed in TYPO3 v12. The existing plugin "Cart: Products" was split into to plugins. A upgrade wizard cares about the updating. Important: Due to the changed pluginName you will need to adapt your RouteEnhancers in your SiteConfiguration.

Affected Installations 

All installations which are not set up with version 5 of EXT:cart_products (before TYPO3 v12).

Migration 

1. Run the UpdateWizard "Migrates plugins of existing cart_produts plugins using switchableControllerActions". 2. Adapt the value of plugin from Products to ShowProduct in your site configuration (config/sites/<your-site>/config.yaml):

BEFORE:

routeEnhancers:
  CartProducts:
    type: Extbase
    limitToPages:
      - 123
    extension: CartProducts
    plugin: Products
    routes:
    ...

AFTER:

routeEnhancers:
  CartProducts:
    type: Extbase
    limitToPages:
      - 123
    extension: CartProducts
    plugin: ShowProduct
    routes:
    ...

Description 

EXT:cart v9 has an extended \Extcode\Cart\Domain\Model\Cart\Cart\ProcessOrderCheckStockEvent. This allows product extensions as EXT:cart_product to set a flag if any product of an order is not available in sufficient amount (means: less articles in stock than what a customer wants to order).

The new Event Listener \Extcode\CartProducts\EventListener\Order\Stock\CheckStock checks whether the stock of any article is lower than what a customer wants to order. This situation can happen when customer B ordered the same product after customer A put the article into the cart. Customer A will get in this case a message that the article is no longer available in the desired amount and the order can not be finished until customer A adapts the amount.

This prevents a TYPO3 Exception "[..] Out of range value for column 'stock' [...]".

Impact 

Negative effects are not expected. This feature works out of the box when stock handling is activated. As long as flash messages are shown in the order form it's not necessary to adapt anything.

It is of course possible to override the displayed message which has the key tx_cart.error.stock_handling.order (in EXT:cart).

Description 

Render the available stock for a product if stock handling is activated. Together with an updated JS within EXT:cart this works even for BE variants.

Integration 

An example was implemented in the detail view for a product. See /Resources/Private/Partials/Product/Price.html

Breaking Changes 

Features 

Description 

In TYPO3 v11 <f:paginate> has been removed and is implemented via the controller.

Affected Installations 

All installations are affected by this change.

Migration 

If the templates for the lists of products in the frontend has been overwritten, then these templates must also be adapted. If pagination is not desired, a custom template must be used for the product list.

Description 

Because in TYPO3 v11 no pagination in the frontend is possible without an own ViewHelper or an extension, the list action in the ProductController was extended by the pagination. Via TypoScript it can be defined how many products should be displayed per page.

Integration 

An example was implemented in the list action template.

Breaking Changes 

Description 

The backend module didn't offer much more than a customized list view so far. The detail view did not contain a ready template and did not offer a representation like in the frontend. The list view can also be done via the List Module.

Impact 

Editors must resort to the list module.

Note 

If someone cannot do without this backend module, the code can be outsourced to a separate extension. As an alternative to this module, dashboard widgets are planned, which offer the editor the possibility to see all products whose stock is very low or which are no longer available.

Features 

Description 

In many cases the selection of backend variants in the frontend is not so user-friendly, especially if a product has more than one backend variant. In this case, every available combination is displayed as one entry in a selector. This version extends the selector with additional data attributes that are used to resolve this one selector into multiple selectors for each backend variant.

The redesign is done via JavaScript, so that only a selector is displayed when JavaScript is deactivated. The JavaScript then also ensures that only available options can be selected.

Integration 

Since this change in the view must first be adapted for the customer project, the necessary JavaScript is not included by default. This will probably be done in the upcoming major version.

::

page.includeJSFooter.tx_cartproducts = EXT:cart_products/Resources/Public/JavaScripts/cart.js

Attention 

The JavaScript is not yet finalized. There might be some changes in the coming minor versions. For this reason you should either include a copy via your own site package or check the behaviour in the page after each update.

Features 

Description 

In some cases you don't need a detail page for the products and want to allow adding products to the shopping cart in the list view. Diese Änderung erlaubt es, der showForm Action das Produkt als Parameter mitzugeben.

Integration 

To display the form in list view, you have to insert the following snippet in your own template.

<f:cObject typoscriptObjectPath="lib.cartProduct.showForm" data="{productUid: '{product.uid}'}"/>

Features 

Description 

Declare extension compatible with PHP 7.4. Set state of cart extension to stable.

Important 

Description 

For each product you can activate the stock management in the backend. Up to now, stock management was carried out independently for each language. The online shops implemented with the extension sell products with translated product titles and descriptions, but not translated products. Therefore there should be a collective stock for all translations of a product.

SELECT orig.uid AS orig_uid, orig.title AS orig_title, orig.handle_stock AS orig_handle_stock, trans.uid AS trans_uid, trans.title AS trans_title, trans.handle_stock AS trans_handle_stock
FROM `tx_cartproducts_domain_model_product_product` AS orig
JOIN `tx_cartproducts_domain_model_product_product` AS trans ON orig.uid = trans.l10n_parent
WHERE orig.handle_stock <> trans.handle_stock

UPDATE `tx_cartproducts_domain_model_product_product` AS trans
JOIN `tx_cartproducts_domain_model_product_product` AS orig ON orig.uid = trans.l10n_parent
SET trans.handle_stock = orig.handle_stock
WHERE orig.handle_stock <> trans.handle_stock

SELECT orig.uid AS orig_uid, orig.title AS orig_title, orig.handle_stock_in_variants AS orig_handle_stock_in_variants, trans.uid AS trans_uid, trans.title AS trans_title, trans.handle_stock_in_variants AS trans_handle_stock_in_variants
FROM `tx_cartproducts_domain_model_product_product` AS orig
JOIN `tx_cartproducts_domain_model_product_product` AS trans ON orig.uid = trans.l10n_parent
WHERE orig.handle_stock_in_variants <> trans.handle_stock_in_variants

UPDATE `tx_cartproducts_domain_model_product_product` AS trans
JOIN `tx_cartproducts_domain_model_product_product` AS orig ON orig.uid = trans.l10n_parent
SET trans.handle_stock_in_variants = orig.handle_stock_in_variants
WHERE orig.handle_stock_in_variants <> trans.handle_stock_in_variants

SELECT orig.uid AS orig_uid, orig.title AS orig_title, orig.stock AS orig_stock, trans.uid AS trans_uid, trans.title AS trans_title, trans.stock AS trans_stock
FROM `tx_cartproducts_domain_model_product_product` AS orig
JOIN `tx_cartproducts_domain_model_product_product` AS trans ON orig.uid = trans.l10n_parent
WHERE orig.stock <> trans.stock

UPDATE `tx_cartproducts_domain_model_product_product` AS trans
JOIN `tx_cartproducts_domain_model_product_product` AS orig ON orig.uid = trans.l10n_parent
SET trans.stock = orig.stock
WHERE orig.stock <> trans.stock

SELECT orig.product, orig_product.title, orig.uid AS orig_uid, orig.stock AS orig_stock, trans.uid AS trans_uid, trans.stock AS trans_stock
FROM `tx_cartproducts_domain_model_product_bevariant` AS orig
JOIN `tx_cartproducts_domain_model_product_bevariant` AS trans ON orig.uid = trans.l10n_parent
JOIN `tx_cartproducts_domain_model_product_product` AS orig_product ON orig.product = orig_product.uid
WHERE orig.stock IS NOT NULL AND orig.stock <> trans.stock;

UPDATE `tx_cartproducts_domain_model_product_bevariant` AS trans
JOIN `tx_cartproducts_domain_model_product_bevariant` AS orig ON orig.uid = trans.l10n_parent
SET trans.stock = orig.stock
WHERE orig.stock IS NOT NULL AND orig.stock <> trans.stock

Description 

For each product you can select a type such as simple or configurable. The product must of course have the same type in all languages.

Therefore, this change will remove the product type in the translations and take the type of the original language.

SELECT orig.uid AS orig_uid, orig.title AS orig_title, orig.product_type AS orig_product_type, trans.uid AS trans_uid, trans.title AS trans_title, trans.product_type AS trans_product_type
FROM `tx_cartproducts_domain_model_product_product` AS orig
JOIN `tx_cartproducts_domain_model_product_product` AS trans ON orig.uid = trans.l10n_parent
WHERE orig.product_type <> trans.product_type

UPDATE `tx_cartproducts_domain_model_product_product` AS trans
JOIN `tx_cartproducts_domain_model_product_product` AS orig ON orig.uid = trans.l10n_parent
SET trans.product_type = orig.product_type
WHERE orig.product_type <> trans.product_type