88 lines
3.9 KiB
Plaintext
88 lines
3.9 KiB
Plaintext
---
|
|
title: Custom Checkout Fields
|
|
description: How to extend WooNooW checkout with custom fields and address formatting
|
|
date: 2024-06-03
|
|
---
|
|
|
|
## Overview
|
|
|
|
WooNooW fully integrates with the standard `woocommerce_checkout_fields` filter. This means any plugin that modifies or adds fields to WooCommerce checkout will generally work seamlessly with the WooNooW SPA checkout and address book features.
|
|
|
|
However, WooNooW introduces several powerful SPA-specific enhancements that you can take advantage of when writing integrations or custom plugins (such as RajaOngkir).
|
|
|
|
---
|
|
|
|
## Supported Field Properties
|
|
|
|
When defining a custom field via `woocommerce_checkout_fields`, WooNooW respects the standard WooCommerce properties (like `type`, `label`, `required`, `default`, etc.), plus it adds a few specialized ones for modern React components.
|
|
|
|
### `form-row-wide` Class Support
|
|
|
|
The SPA natively converts WooCommerce field classes to Tailwind grid classes:
|
|
* Adding `'form-row-wide'` to the `class` array of a field will automatically apply `md:col-span-2`, forcing the field to take up **100% width** on the checkout and address editing forms.
|
|
* If `'form-row-wide'` is omitted, the field typically spans **50% width** on tablet and desktop screens (`md:col-span-1`).
|
|
|
|
### Hidden Fields
|
|
|
|
If you want to hide a standard field (e.g., `billing_last_name` or `shipping_country`), you can do so in two ways that WooNooW understands:
|
|
1. Change the field's type: `$fields['billing']['billing_last_name']['type'] = 'hidden';`
|
|
2. Add a hidden class: `$fields['billing']['billing_last_name']['class'][] = 'hidden';`
|
|
|
|
> **Tip**: If you hide `last_name`, you might want to make `first_name` take up the full row. You can easily do this by adding `'form-row-wide'` to the `first_name` class array!
|
|
|
|
### `searchable_select` Field Type (New in WooNooW)
|
|
|
|
WooNooW introduces a new `searchable_select` type which renders an accessible, auto-complete dropdown component with API search capabilities. This is perfect for deeply nested address data like subdistricts or provinces.
|
|
|
|
**Example:**
|
|
```php
|
|
$fields['billing']['billing_destination_id'] = [
|
|
'type' => 'searchable_select',
|
|
'label' => __('Destination', 'woonoow'),
|
|
'required' => true,
|
|
'search_endpoint' => '/rajaongkir/destinations',
|
|
'search_param' => 'search',
|
|
'min_chars' => 3,
|
|
'placeholder' => 'Type to search destination...',
|
|
];
|
|
```
|
|
|
|
* **`search_endpoint`**: The WooNooW API endpoint to call (e.g., `GET /wp-json/woonoow/v1/rajaongkir/destinations?search=query`).
|
|
* **`search_param`**: The query parameter name (default: `'search'`).
|
|
* **`min_chars`**: The minimum characters a user must type before firing the API request.
|
|
|
|
The endpoint must return an array of objects with `value` and `label`:
|
|
```json
|
|
[
|
|
{ "value": "123", "label": "Jakarta Selatan, DKI Jakarta" },
|
|
{ "value": "124", "label": "Jakarta Pusat, DKI Jakarta" }
|
|
]
|
|
```
|
|
|
|
---
|
|
|
|
## Custom Address Formatting
|
|
|
|
If you introduce custom fields (like a RajaOngkir destination ID), you will likely want to format how the address is displayed on the "My Account" address cards and the "Checkout" saved address selector.
|
|
|
|
WooNooW provides the `woonoow_format_address` filter for this exact purpose.
|
|
|
|
**Example:**
|
|
```php
|
|
add_filter('woonoow_format_address', function($formatted, $address) {
|
|
$parts = [];
|
|
$parts[] = $address['first_name'] . ' ' . $address['last_name'];
|
|
$parts[] = $address['address_1'];
|
|
|
|
// Append custom label saved by a searchable_select component
|
|
if (!empty($address['destination_id_label'])) {
|
|
$parts[] = $address['destination_id_label'];
|
|
}
|
|
|
|
// The SPA uses whitespace-pre-wrap, so newlines render correctly
|
|
return implode("\n", array_filter($parts));
|
|
}, 10, 2);
|
|
```
|
|
|
|
When `formatted_address` is provided, the SPA will automatically bypass its default layout and display your perfectly formatted, newline-separated string.
|