Address Field Renderers in MAHX Checkout

The MAHX Checkout module introduces a powerful and flexible system to render and manage Shipping and Billing address fields. It decouples data, UI logic, and dynamic behavior, empowering developers to customize and extend address fields with minimal effort and maximum control.

---

💡 Core Concept

Each address field is encapsulated by the MageHx\MahxCheckout\Data\AddressFieldAttributes data object. These field objects are dynamically rendered using pluggable Field Renderers, and the entire system is designed to be:

• Configurable via di.xml
• Customizable via observers and plugins
• Extendable via events fired at strategic points

This makes the system incredibly extensible while keeping the base logic clean and modular.

---

🧱 Address Field Rendering Workflow

Here’s how the address field rendering system works under the hood:

1. Field Preparation

   • The method getAddressFieldList($formId) in MageHx\MahxCheckout\Service\AddressFieldManager fetches the field definitions for a form.
   • Fields are represented as AddressFieldAttributes data objects.

2. Field Rendering

   • For each field, the RendererPool::getRenderer() method determines the appropriate renderer.
   • The chosen renderer is then used to generate the final HTML using block templates.

3. ViewModels

   • ShippingAddress and BillingAddress ViewModels use getAddressFields() to fetch and render fields in their respective templates.

4. Templates

   • Final HTML is generated by blocks like MageHx\MahxCheckout\Block\Address\FieldRenderer.
   • Templates reside in: view/frontend/templates/ui/address/fields/*.phtml

---

⚙️ Renderer Configuration

Field renderers are defined in di.xml under RendererPool:

<type name="MageHx\MahxCheckout\Model\FieldRenderer\RendererPool">
    <arguments>
        <argument name="renderers" xsi:type="array">
            <item name="MageHx_MahxCheckout::text" xsi:type="array">
                <item name="class" xsi:type="object">MageHx\MahxCheckout\Model\FieldRenderer\Renderer\TextRenderer</item>
            </item>
            <!-- Add more renderers here -->
        </argument>
    </arguments>
</type>

Each renderer must implement the FieldRendererInterface with two methods:

• render(AddressFieldAttributes $field): string
• canRender(AddressFieldAttributes $field): bool

This design allows flexible matching and rendering of fields based on custom logic.

---

🧩 Address Field Attributes

The AddressFieldAttributes object holds all the metadata required to define and render a form field:

Attribute	Description
name	Field name identifier
label	Field label shown to users
type	Input type (e.g. text, select, etc.)
required	Is this field required? (bool)
form	The form ID it belongs to
value	Current/default value
rules	Validation rules
sortOrder	Position in the form
additionalData	Extra data for rendering and behavior (see below)

🔧 additionalData Options (Enum: AdditionalFieldAttribute)

Key	Purpose
options	Options for select fields (key-value pairs)
defaultOptionLabel	Default option label for select fields
inputElemAdditionalAttributes	Add extra HTML attributes (e.g. hx-*) to <input>
beforeInputHtml	Insert custom HTML before input element
afterInputHtml	Insert custom HTML after input element
wrapperElemExtraClass	Add extra CSS classes to the field wrapper div
wrapperElemAdditionalAttributes	Add extra attributes to the wrapper div

These options allow rich customization of each field’s structure and behavior without rewriting HTML templates.

---

🛠️ Extendability via Events

MAHX Checkout fires several helpful events during field generation and rendering. You can use observers to hook into these events.

🚚 Shipping Address Events

Context	Event Name
Field Preparation	mahxcheckout_address_form_fields_prepared mahxcheckout_shipping_address_form_fields_prepared
Renderer Selection	mahxcheckout_address_field_renderer_selected
Before/After Render	mahxcheckout_shipping_address_field_render_before mahxcheckout_shipping_address_field_render_after

💳 Billing Address Events

Context	Event Name
Field Preparation	mahxcheckout_address_form_fields_prepared mahxcheckout_billing_address_form_fields_prepared
Renderer Selection	mahxcheckout_address_field_renderer_selected
Before/After Render	mahxcheckout_billing_address_field_render_before mahxcheckout_billing_address_field_render_after

🧩 Renderer Configuration Events

These events allow injection or modification of renderers:

Event	Description
mahxcheckout_prepare_address_field_renderers_before	Modify or add renderers before renderer pool is built
mahxcheckout_prepare_address_field_renderers_after	Modify or add renderers after pool is built

---

📚 Example Observers

Here are a few real-world examples from the codebase:

Event	Example Observer
mahxcheckout_address_form_fields_prepared	AddCountryOptions
mahxcheckout_shipping_address_form_fields_prepared	PopulateShippingAddressFormValues
mahxcheckout_billing_address_form_fields_prepared	PopulateBillingAddressFormValues
mahxcheckout_address_field_renderer_selected	UpdateRegionFieldBasedOnCountry

---

✅ Best Practices

• Always prefer observers or plugins to modify fields and renderers.
• Avoid overriding core ViewModels or templates directly.
• Use additionalData to add dynamic behavior to input fields.
• Follow the provided examples to inject custom renderers cleanly.

---

🧪 Summary

MAHX Checkout’s address field rendering system is built with modularity and flexibility in mind. Whether you want to:

• Add a new input field,
• Change its behavior or appearance,
• Inject dynamic frontend attributes,
• Or even swap out the renderer logic entirely.

---