Skip to content

Rendering an element with a custom template

To have the most control over how a field or element is rendered, it is possible to use a custom template.

Because it is implemented via Layout XML, this is one of the few common customizations not requiring a form modifier.

We have to distinguish between form elements and form fields. The technique is similar for both, but they use a different target layout block.

As a reminder: form elements can be anything within a form (informational text, icons, separators, controls, etc), while form fields are inputs.

Form element templates

To declare a custom template for a form element, add it as a child block to the entity-form.element-renderers block.
The block alias has to match the element id.
You can use any layout XML file that is loaded for the checkout step.

For example, for an element with the ID my_element:

<referenceBlock name="entity-form.element-renderers">
    <block name="form-field.my_element" as="my_element" template="Hyva_Example::form/my-element.phtml"/>
</referenceBlock>

Form field templates

To declare a custom template for a form field, add it as a child block to the entity-form.field-renderers block.
You can use any layout XML file that is loaded for the checkout step.

<referenceBlock name="entity-form.field-renderers">
    <block name="form-field.my_field" as="my_field" template="Hyva_Example::form/my-field.phtml"/>
</referenceBlock>

The field renderer tries to find a matching renderer block by iterating over several possible identifiers.
The one with a matching child block is used to render the field:

  • [form-name].[id].[input-type] (e.g. shipping.delivery.date)
  • [id].[input-type] (e.g. delivery.date)
  • [id] (e.g. delivery)
  • [form-name].[input-type] (e.g. shipping.date)
  • [type] (e.g. date)
  • text (literally text, the default renderer)

Setting a renderer in a form modifier

It is also possible to change a field renderer dynamically in a form modifier hook method.

To do so, set the input_alias property of the element.

For example:

class ExampleModifier implements EntityFormModifierInterface
{
    public function apply(EntityFormInterface $form): EntityFormInterface
    {
        $form->registerModificationListener(
            'replace-field-renderer',
            'form:init',
            function (EntityFormInterface $form) {
                if ($field = $form->getField('my_field')) {
                    $field->setData('input_alias', 'renderer_alias_name');
                }
            }
        );

        return $form;
    }
}

## Form field accessories

Form field accessories allow customization of specific form fields by using layout XML. Examples of form field accessories are:

- Labels
- Tooltips
- Rendering blocks before or after a form field.

- You can use layout XML to declare accessory blocks as children of the field renderer block. Use one of the several possible identifiers explained in the previous section.

Here's an example that customizes the `my_field` form field by adding a custom label and blocks before and after the form field:
```xml
    <referenceBlock name="entity-form.field-renderers">
        <block name="form-field.my_field">
            <block name="form-field.my_field.before" as="before" template="Hyva_Example::form/my-field/before.phtml" />
            <block name="form-field.my_field.after" as="after" template="Hyva_Example::form/my-field/after.phtml" />
            <block name="form-field.my_field.label" as="label" template="Hyva_Example::form/my-field/custom-label.phtml" />
        </block>
    </referenceBlock>