From ccba86a616851d314872993d38cc7458ddf48d2a Mon Sep 17 00:00:00 2001 From: Seghir Nadir Date: Mon, 13 May 2024 17:46:46 +0200 Subject: [PATCH] Update additional fields document's TOC and link to it from another document. (#47137) * update docs * Add changefile(s) from automation for the following project(s): woocommerce-blocks * fix linting * update manifest --------- Co-authored-by: github-actions --- .../customising-checkout-fields.md | 4 ++ docs/docs-manifest.json | 4 +- .../additional-checkout-fields.md | 70 +++++++++++-------- .../47137-fix-docs-fix-toc-additional-fields | 4 ++ 4 files changed, 49 insertions(+), 33 deletions(-) create mode 100644 plugins/woocommerce/changelog/47137-fix-docs-fix-toc-additional-fields diff --git a/docs/code-snippets/customising-checkout-fields.md b/docs/code-snippets/customising-checkout-fields.md index 379a5af0135..9b33a8b2af8 100644 --- a/docs/code-snippets/customising-checkout-fields.md +++ b/docs/code-snippets/customising-checkout-fields.md @@ -7,6 +7,10 @@ If you are unfamiliar with code and resolving potential conflicts, we have an ex Custom code should be copied into your child theme's **functions.php** file. +## Note + +Some parts of this document only applies to the shortcode Checkout, for adding fields to the Checkout block, [consult this document.](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/additional-checkout-fields.md) + ## How Are Checkout Fields Loaded to WooCommerce? The billing and shipping fields for checkout pull from the countries class `class-wc-countries.php` and the **`get_address_fields`** function. This allows WooCommerce to enable/disable fields based on the user's location. diff --git a/docs/docs-manifest.json b/docs/docs-manifest.json index b43e8e536c7..321af2cb17c 100644 --- a/docs/docs-manifest.json +++ b/docs/docs-manifest.json @@ -97,7 +97,7 @@ "post_title": "Customizing checkout fields using actions and filters", "tags": "code-snippet", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/code-snippets/customising-checkout-fields.md", - "hash": "95cdfe40544c35e1918a56654d3fe2c42490b3b91ac10713cc1c005baa003686", + "hash": "3b0ce072c92206279fc6d49f3aa4cb0e4fbc2da71a2a5f0ffada81c030c397df", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/code-snippets/customising-checkout-fields.md", "id": "83097d3b7414557fc80dcf9f8f1a708bbdcdd884" }, @@ -1266,5 +1266,5 @@ "categories": [] } ], - "hash": "24c95fd5e28dc3e1fd03ffa495e1487bafc1dc8c3ffa91334f05ac2ea3b12e78" + "hash": "556bb0eab0e99ed385dbc32b96008add0b64f01888d4aae6f7051345aae045cc" } \ No newline at end of file diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/additional-checkout-fields.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/additional-checkout-fields.md index 4d89bf2b996..2bdeff27360 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/additional-checkout-fields.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/additional-checkout-fields.md @@ -3,38 +3,46 @@ ## Table of Contents - [Available field locations](#available-field-locations) - - [Contact information](#contact-information) - - [Address](#address) - - [Order information](#order-information) + - [Contact information](#contact-information) + - [Address](#address) + - [Order information](#order-information) +- [Accessing values](#accessing-values) + - [Helper methods](#helper-methods) + - [Guest customers](#guest-customers) + - [Logged-in customers](#logged-in-customers) + - [Accessing all fields](#accessing-all-fields) + - [Accessing values directly](#accessing-values-directly) + - [Checkboxes values](#checkboxes-values) - [Supported field types](#supported-field-types) - [Using the API](#using-the-api) - - [Options](#options) - - [General options](#general-options) - - [Options for `text` fields](#options-for-text-fields) - - [Options for `select` fields](#options-for-select-fields) - - [Options for `checkbox` fields](#options-for-checkbox-fields) - - [Attributes](#attributes) + - [Options](#options) + - [General options](#general-options) + - [Options for `text` fields](#options-for-text-fields) + - [Options for `select` fields](#options-for-select-fields) + - [Example of `options` value](#example-of-options-value) + - [Options for `checkbox` fields](#options-for-checkbox-fields) + - [Attributes](#attributes) - [Usage examples](#usage-examples) - - [Rendering a text field](#rendering-a-text-field) - - [Rendering a checkbox field](#rendering-a-checkbox-field) - - [Rendering a select field](#rendering-a-select-field) - - [The select input before being focused](#the-select-input-before-being-focused) - - [The select input when focused](#the-select-input-when-focused) + - [Rendering a text field](#rendering-a-text-field) + - [Rendering a checkbox field](#rendering-a-checkbox-field) + - [Rendering a select field](#rendering-a-select-field) + - [The select input before being focused](#the-select-input-before-being-focused) + - [The select input when focused](#the-select-input-when-focused) - [Validation and sanitization](#validation-and-sanitization) - - [Sanitization](#sanitization) - - [Using the `woocommerce_sanitize_additional_field` filter](#using-the-woocommerce_sanitize_additional_field-filter) - - [Example of sanitization](#example-of-sanitization) - - [Validation](#validation) - - [Single field validation](#single-field-validation) - - [Using the `woocommerce_validate_additional_field` action](#using-the-woocommerce_validate_additional_field-action) - - [The `WP_Error` object](#the-wp_error-object) - - [Example of single-field validation](#example-of-single-field-validation) - - [Multiple field validation](#multiple-field-validation) - - [Using the `woocommerce_blocks_validate_location_{location}_fields` action](#using-the-woocommerce_blocks_validate_location_location_fields-action) - - [Example of location validation](#example-of-location-validation) + - [Sanitization](#sanitization) + - [Using the `woocommerce_sanitize_additional_field` filter](#using-the-woocommerce_sanitize_additional_field-filter) + - [Example of sanitization](#example-of-sanitization) + - [Validation](#validation) + - [Single field validation](#single-field-validation) + - [Using the `woocommerce_validate_additional_field` action](#using-the-woocommerce_validate_additional_field-action) + - [The `WP_Error` object](#the-wp_error-object) + - [Example of single-field validation](#example-of-single-field-validation) + - [Multiple field validation](#multiple-field-validation) + - [Using the `woocommerce_blocks_validate_location_{location}_fields` action](#using-the-woocommerce_blocks_validate_location_location_fields-action) + - [Example of location validation](#example-of-location-validation) - [Backward compatibility](#backward-compatibility) - - [React to to saving fields](#react-to-to-saving-fields) - - [React to reading fields](#react-to-reading-fields) + - [React to to saving fields](#react-to-to-saving-fields) + - [React to reading fields](#react-to-reading-fields) - [A full example](#a-full-example) A common use-case for developers and merchants is to add a new field to the Checkout form to collect additional data about a customer or their order. @@ -249,7 +257,7 @@ These options apply to all field types (except in a few circumstances which are | `sanitize_callback` | A function called to sanitize the customer provided value when posted. | No | See example below | By default the field's value is returned unchanged. | | `validate_callback` | A function called to validate the customer provided value when posted. This runs _after_ sanitization. | No | See example below | The default validation function will add an error to the response if the field is required and does not have a value. [See the default validation function.](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Blocks/Domain/Services/CheckoutFields.php#L270-L281) | -##### * Example of `sanitize_callback`. This function will remove spaces from the value +##### Example of `sanitize_callback`. This function will remove spaces from the value ```php 'sanitize_callback' => function( $field_value ) { @@ -257,7 +265,7 @@ These options apply to all field types (except in a few circumstances which are }, ``` -##### * Example of `validate_callback`. This function will check if the value is an email +##### Example of `validate_callback`. This function will check if the value is an email ```php 'validate_callback' => function( $field_value ) { @@ -283,10 +291,10 @@ Select fields can also be marked as required. If they are not (i.e. they are opt | Option name | Description | Required? | Example | Default value | |-----|-----|-----|----------------|--------------| -| `options` | An array of options to show in the select input. Each options must be an array containing a `label` and `value` property. Each entry must have a unique `value`. Any duplicate options will be removed. The `value` is what gets submitted to the server during checkout and the `label` is simply a user-friendly representation of this value. It is not transmitted to the server in any way. | Yes | *see below | No default - this must be provided. | +| `options` | An array of options to show in the select input. Each options must be an array containing a `label` and `value` property. Each entry must have a unique `value`. Any duplicate options will be removed. The `value` is what gets submitted to the server during checkout and the `label` is simply a user-friendly representation of this value. It is not transmitted to the server in any way. | Yes | see below | No default - this must be provided. | | `required` | If this is `true` then the shopper _must_ provide a value for this field during the checkout process. | No | `true` | `false` | -##### *Example of `options` value +##### Example of `options` value ```php [ diff --git a/plugins/woocommerce/changelog/47137-fix-docs-fix-toc-additional-fields b/plugins/woocommerce/changelog/47137-fix-docs-fix-toc-additional-fields new file mode 100644 index 00000000000..3c0b1b974a4 --- /dev/null +++ b/plugins/woocommerce/changelog/47137-fix-docs-fix-toc-additional-fields @@ -0,0 +1,4 @@ +Significance: patch +Type: tweak +Comment: Update docs TOC. +