Forms for products 

A product extension can link its products with forms of the form framework (EXT:form). The customer fills in the form, e.g. the names and the age of the participants of an event, and the product is added to the cart with these values. EXT:cart_events uses this to book events with a form.

In your own product extension you are free to add your own normal fields for values of the product, e.g. the color of the product. The form framework is useful when the editor defines the fields per product, product type or product group: every form can have its own fields with different input types and validators, without changing the templates of the product extension.

EXT:cart does not use these forms itself; it provides the parts a product extension needs:

  • the form prototype cart with the finisher AddToCart,
  • the event \Extcode\Cart\Event\Form\AddToCartFinisherEvent to create the products from the form values,
  • the itemsProcFunc \Extcode\Cart\Hooks\FormDefinitions to select a form for a product in the backend.

Form prototype 

EXT:cart registers the prototype cart in EXT:cart/Configuration/Yaml/FormSetup.yaml. The YAML file is included with the TypoScript of EXT:cart for the frontend and the backend. The prototype inherits from the prototype standard and

  • adds the finisher AddToCart,
  • removes the finishers of the prototype standard (EmailToSender, EmailToReceiver, Redirect, DeleteUploads and Confirmation) from the selection in the form editor, because sending mails or redirecting to a page makes no sense when a product is added to the cart,
  • uses its own form template, which allows submitting the form by AJAX.

The finisher AddToCart cannot be selected in the form editor either. It is part of the template for new forms, so an editor cannot remove it by accident.

The prototype cart is the base for the prototypes of the product extensions and should not be used for forms directly. A product extension adds its own prototype which inherits from cart. This way the own prototype inherits the finisher and the restricted selection of finishers, and only the forms of this prototype can be selected for the products of the extension.

The form setup registers the prototype and makes it selectable in the backend module "Forms", with a template for new forms:

EXT:my_product/Configuration/Yaml/FormSetup.yaml
TYPO3:
  CMS:
    Form:
      formManager:
        selectablePrototypesConfiguration:
          1700000000:
            identifier: 'my-product'
            label: 'My product'
            newFormTemplates:
              100:
                templatePath: 'EXT:my_product/Resources/Private/Backend/Templates/FormEditor/Yaml/NewForms/Example.form.yaml'
                label: 'My product form (Example)'
      prototypes:
        my-product:
          __inheritances:
            10: 'TYPO3.CMS.Form.prototypes.cart'
Copied!

The form setup has to be added to the YAML configurations of the form framework for the frontend and the backend, like EXT:cart does in its TypoScript:

EXT:my_product/Configuration/TypoScript/setup.typoscript
plugin.tx_form.settings.yamlConfigurations {
    1700000000 = EXT:my_product/Configuration/Yaml/FormSetup.yaml
}

module.tx_form.settings.yamlConfigurations {
    1700000000 = EXT:my_product/Configuration/Yaml/FormSetup.yaml
}
Copied!

The template for new forms uses the same prototype and contains the finisher AddToCart. The editor adds the fields in the backend module "Forms":

EXT:my_product/Resources/Private/Backend/Templates/FormEditor/Yaml/NewForms/Example.form.yaml
renderingOptions:
  submitButtonLabel: Submit
  controllerAction: form
type: Form
identifier: my-product-example
label: 'My product - Example'
prototypeName: my-product
finishers:
  -
    identifier: AddToCart
renderables:
  -
    type: Page
    identifier: page-1
    label: ''
    renderables:
      -
        type: Text
        identifier: firstName
        label: FirstName
        validators:
          -
            identifier: NotEmpty
Copied!

Select a form for a product 

The field which stores the selected form has to be named form_definition. The itemsProcFunc lists the forms of the prototype configured in itemsProcFuncConfig. Without this configuration it lists the forms of the prototype cart, so the prototype of the product extension should always be configured. The field should only be added if EXT:form is loaded:

EXT:my_product/Configuration/TCA/Overrides/tx_myproduct_domain_model_product.php
use Extcode\Cart\Hooks\FormDefinitions;
use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

if (ExtensionManagementUtility::isLoaded('form')) {
    ExtensionManagementUtility::addTCAcolumns(
        'tx_myproduct_domain_model_product',
        [
            'form_definition' => [
                'label' => 'Form',
                'config' => [
                    'type' => 'select',
                    'renderType' => 'selectSingle',
                    'items' => [
                        ['label' => '', 'value' => ''],
                    ],
                    'itemsProcFunc' => FormDefinitions::class . '->getItems',
                    'itemsProcFuncConfig' => [
                        'prototypeName' => 'my-product',
                    ],
                    'size' => 1,
                    'minitems' => 0,
                    'maxitems' => 1,
                    'softref' => 'formPersistenceIdentifier',
                ],
            ],
        ]
    );
    ExtensionManagementUtility::addToAllTCAtypes(
        'tx_myproduct_domain_model_product',
        'form_definition'
    );
}
Copied!

The forms of the file storages are filtered by the prototype of their listing. The database storage lists every form with the prototype standard; these forms are loaded to check their prototype.

Create the products 

When the form is submitted, the finisher AddToCart dispatches the event \Extcode\Cart\Event\Form\AddToCartFinisherEvent with the form values and the cart. A listener of the product extension creates the products from the form values and passes them back to the event. The finisher adds the products to the cart and stores the cart in the session.

EXT:my_product/Classes/EventListener/AddProductFromForm.php
use Extcode\Cart\Event\Form\AddToCartFinisherEvent;

final class AddProductFromForm
{
    public function __invoke(AddToCartFinisherEvent $event): void
    {
        $formValues = $event->getFormValues();
        if (($formValues['productType'] ?? '') !== 'MyProduct') {
            return;
        }

        // Create the \Extcode\Cart\Domain\Model\Cart\Product from the form
        // values, other form values can be added as frontend variants.
        $cartProduct = ...;

        $event->setCartProducts([$cartProduct]);
        // or, if the product cannot be added:
        // $event->setErrors([...]);
    }
}
Copied!

The listener is registered for the event in the service configuration of the product extension. Several product extensions can listen to the event, so a listener should only handle the forms of its own products, e.g. by a hidden field productType in the form.

The finisher responds with JSON for the page types configured in plugin.tx_cart.settings.jsonResponseForPageTypes, otherwise it adds a flash message. The messages are taken from the language labels tx_cart.add_to_cart_finisher.<productType>.message.status.200.body and .title, with a fallback to tx_cart.add_to_cart_finisher.message.status.200.body and .title.