How Gatemi Checkout Fields Works

Three rules govern how the plugin changes your checkout.

The patch rule: your changes go on top of WooCommerce's fields

WooCommerce builds the checkout's fields as one big array and passes it through the woocommerce_checkout_fields filter. Other plugins add their fields to the same array.

The plugin does not replace that array with a list of its own. It takes what WooCommerce and every other plugin put there and patches it with the changes you made, field by field:

  • the label, if you typed one;
  • the order (priority);
  • whether it is required;
  • for a field you created, its type (and, in the full edition, choices, placeholder and classes when they are set).

Everything else about a core field stays WooCommerce's: its validation, its autocomplete hint, its CSS classes, and the country-specific rules that rename "State" to "County" or make a postcode optional. That is why switching a field back on returns exactly what WooCommerce defined, and why deactivating the plugin puts the checkout back as it was.

For the same reason a core field's type is never changed — WooCommerce attaches its address formats and validation to it.

Fields from other plugins

The editor reads the checkout's real field list, so a field another plugin adds (a VAT number, a delivery date) appears in the table too, and you can rename, reorder, require or hide it like any other.

A hidden field is removed, not styled away

Unticking Show removes the field from the array. A field merely hidden with display:none would still be posted, still be validated, still be saved and still turn up in the confirmation email. Here a hidden field does not exist on the checkout at all.

Hiding a field does not delete your edit of it: the row stays on the screen, with its label and order, ready to be switched back on.

Your own fields, from checkout to order

When a shopper places an order:

  1. Validation. Before the order is created, every one of your fields ticked Required is checked. An empty one stops the order with "Label is a required field." Full edition: the value is sanitised by its type first, so a Date that is not YYYY-MM-DD or a Number that is not numeric counts as empty.
  2. Saving. Each of your fields with a value is saved on the order as meta _<key>, for example _gmcf_delivery_instructions. An empty optional field leaves nothing behind.
  3. On the order screen. Under the billing address, both editions list each of your fields that has a value — on the HPOS orders screen and the classic one. Full edition: a checkbox reads Yes or No and a dropdown shows its option's label.
  4. In emails — Full edition. Fields with Emails ticked are added to the order emails through WooCommerce's woocommerce_email_order_meta_fields.

The values are part of the order. Changing or deleting a field later does not change what past orders say, and uninstalling never removes them.

Every type has its own sanitiser — Full edition

Each field type names the function that cleans what a shopper typed: a text area keeps its line breaks, an email address must be one, a checkbox becomes 1 or nothing. A type the plugin does not recognise — for example one an extension added and then stopped providing — is treated as plain text and sanitised as such, never passed through unchecked.

The free edition and the full edition's fields

Both editions use the option gmcf_fields and the gmcf_ key prefix. The free edition puts only text fields of your own on the checkout. A field the full edition created as a dropdown, date or any other type is left off the checkout entirely — not drawn as a text box that would accept anything — and its value on past orders still shows on the order screen.

The block checkout

The Checkout block does not use woocommerce_checkout_fields. It builds its address forms from WooCommerce's address-field settings and its own additional-fields API. So:

  • Both editions: renaming, reordering, requiring and hiding WooCommerce's own fields reaches the block through the country locale (woocommerce_get_country_locale and woocommerce_get_country_locale_default), which is what the block and the Store API's address check read. The edit is laid over every country the store sells or ships to, a country's own rule for a property is kept, and it applies only on the checkout, the cart and Store API requests — never to the My Account address forms. The block draws one address form for billing and shipping, so an edit is carried when the two rows agree on it. A field switched off is hidden and not required, and a value posted for it anyway is emptied on woocommerce_store_api_checkout_update_order_from_request, before the order is saved.
  • Free edition: your own fields appear on the classic checkout only.
  • Full edition: with Register your custom fields with the block checkout too on, each of your enabled fields is registered with woocommerce_register_additional_checkout_field() under the id gatemi/<key>. A billing or shipping field goes into the address forms, an additional field into the order information step. WooCommerce then draws it, checks it, saves it and shows it on the order itself, under its own meta keys — not as _gmcf_<key>.
Shopping Cart
Scroll to Top