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
cartwith the finisherAdd,To Cart - the event
\Extcode\to create the products from the form values,Cart\ Event\ Form\ Add To Cart Finisher Event - the itemsProcFunc
\Extcode\to select a form for a product in the backend.Cart\ Hooks\ Form Definitions
Note
The package typo3/ is not required by EXT:cart; the product
extension has to require it.
Form prototype
EXT:cart registers the prototype cart in
EXT:. 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
Add,To Cart - removes the finishers of the prototype
standard(Email,To Sender Email,To Receiver Redirect,DeleteandUploads 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 Add 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.
Important
The name of the prototype connects the parts of the product extension and has to be the same in three places:
- the identifier of the prototype and of the selectable prototype in the form setup,
- the
prototypeof the template for new forms,Name - the
prototypein theName itemsof the fieldProc Func Config form_.definition
EXT:cart_events uses the prototype cart-, see
EXT:,
EXT:
and
EXT:cart_events/Configuration/TCA/Overrides/tx_cartevents_domain_model_event.php.
The form setup registers the prototype and makes it selectable in the backend module "Forms", with a template for new forms:
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'
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:
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
}
The template for new forms uses the same prototype and contains the finisher
Add. The editor adds the fields in the backend module "Forms":
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
Select a form for a product
The field which stores the selected form has to be named form_.
The itemsProcFunc lists the forms of the prototype configured in
items. 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:
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'
);
}
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 Add dispatches the event
\Extcode\ 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.
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([...]);
}
}
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 product in the form.
The finisher responds with JSON for the page types configured in
plugin., otherwise it adds a
flash message. The messages are taken from the language labels
tx_ and
.title, with a fallback to
tx_ and .title.