Form modification hooks
Choosing a hook
Finding the right modification hook (and modifier sort order) may not be straightforward.
Not every type of form and field manipulation is possible in every hook, so the desired effect also determines the hook that should be used.
If more than one modifier alter the same field, both the modifier sortOrder
and the hook execution order influence the order in which the callbacks are executed.
For example, a form:build
hook with a high sort order will still be executed before a form:build:magewire
hook with a lower sort order.
form:init
Use this hook to add or remove form fields, or adjust the form itself, along with its fields and values.
This hook is triggered whenever a form is constructed.
Callback Parameters | Preceding | Subsequent | Since | Associated hooks |
---|---|---|---|---|
1. EntityFormInterface $form |
Yes | Yes | 1.1.0 | form:populate |
form:fill
This hook is triggered every time an array is used to fill a form.
This is also true when a parent (ancestor) field is populated with values for its child (relative) elements, causing this hook to trigger recursively.
Use this hook to change field values, whether it's a single field or for multiple fields of a form.
Callback Parameters | Preceding | Subsequent | Since |
---|---|---|---|
1. EntityFormInterface $form 2. array $valueMap |
Yes | Yes | 1.1.0 |
form:build
Use this hook to make visual changes to a form before it is rendered.
For example, you can add extra styles to fields. It is NOT intended for functional changes.
Do not use this hook to add or remove fields.
Callback Parameters | Preceding | Subsequent | Since |
---|---|---|---|
1. EntityFormInterface $form |
Yes | Yes | 1.1.0 |
form:build:magewire
Not all forms are Magewire forms (even though the address forms are).
This additional 'build' hook is intended to be used for making Magewire-specific adjustments.
For instance, you could add a special Magewire fields like wire:model
or wire:target
.
Internally, this hook is used to add all the necessary Magewire attributes.
You should utilize this hook if you want to make changes like removing a previously added attribute from the core.
Callback Parameters | Preceding | Subsequent | Since |
---|---|---|---|
1. EntityFormInterface $form |
Yes | Yes | 1.1.0 |
form:updated
In addition to the generic form:updated
hook, there also are form specific hooks form:shipping:updated
the form:billing:updated
.
Use this hooks to alter the value of fields based on the values others fields.
However, be aware that this hook is only triggered during subsequent requests.
Callback Parameters | Preceding | Subsequent | Since | Associated hooks |
---|---|---|---|---|
1. EntityFormInterface $form 2. MagewireAddressFormInterface $addressComponent |
No | Yes | 1.1.2 | 1. form:[ADDRESS_NAMESPACE]:updated |
Example:
$form->registerModificationListener(
'applyMyBillingModifications',
'form:billing:updated',
fn(EntityFormInterface $form, MagewireAddressFormInterface $addressComponent) => {
// Get the postcode field value.
$postcodeValue = $form->getField('postcode')->getValue();
// Talk with the API to retrieve a street value.
$streetValue = $apiCall->getStreetByZipcode($postcodeValue);
if ($streetValue) {
$form->getField('street')->setValue($streetValue);
}
return $form;
}
);
form:field:updated
Use this hook to alter the value of a field when it is being updated.
However, be aware that this hook is only triggered during subsequent requests.
Callback Parameters | Preceding | Subsequent | Since | Associated hooks |
---|---|---|---|---|
1. EntityFormInterface $form 2. EntityFieldInterface $field 3. MagewireAddressFormInterface $addressComponent |
No | Yes | 1.1.0 | 1. form:[FIELD_ID]:updated 2. form:[ADDRESS_NAMESPACE][FIELD_ID]:updated |
For example:
$form->registerModificationListener(
'applyMyShippingPostcodeModifications',
'form:shipping:postcode:updated',
fn(EntityFormInterface $form, EntityFieldInterface $field, MagewireAddressFormInterface $addressComponent) => {
$field->setValue( ucfirst($field->getValue()));
return $form;
}
);
form:action:edit
This hook is triggered when a visitor clicks the shipping or billing "Edit Address" button.
Callback Parameters | Preceding | Subsequent | Since | Associated hooks |
---|---|---|---|---|
1. EntityFormInterface $form 2. AddressInterface $address |
No | Yes | 1.1.0 | form:[FORM_NAMESPACE]:action:edit |
form:action:create
When a visitor clicks a shipping or billing "New Address" button.
Callback Parameters | Preceding | Subsequent | Since | Associated hooks |
---|---|---|---|---|
1. EntityFormInterface $form |
No | Yes | 1.1.0 | form:[FORM_NAMESPACE]:action:create |