move checkout docs with front matter to main folder (#49186)

* move checkout docs with front matter to main folder

* add manifest

* add core changelog

* Remove emojis, unsupported links and table of contents

* pr comments

* update folder name and remove toc

* title fix

---------

Co-authored-by: Jacklyn Biggin <hi@jacklyn.dev>
This commit is contained in:
piinthecloud 2024-07-10 16:53:52 +02:00 committed by GitHub
parent 39b8b23fc8
commit ec82b3f08f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
29 changed files with 1051 additions and 454 deletions

View File

@ -1,6 +1,6 @@
---
post_title: How to add a custom field to simple and variable products
menu_title: Add custom fields to products
menu_title: Add Custom Fields to Products
tags: how-to
---

View File

@ -0,0 +1,5 @@
---
category_title: Cart and Checkout Blocks
category_slug: cart-and-checkout-blocks
post_title: Cart and Checkout blocks - Extensibility
---

View File

@ -1,55 +1,9 @@
---
post_title: Cart and Checkout - Additional Checkout Fields
post_title: Cart and Checkout - Additional checkout fields
menu_title: Additional Checkout Fields
tags: reference
---
# Additional Checkout Fields <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [Available field locations](#available-field-locations)
- [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)
- [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)
- [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)
- [Backward compatibility](#backward-compatibility)
- [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.
This document will outline the steps an extension should take to register some additional checkout fields.

View File

@ -0,0 +1,8 @@
---
category_title: Available Filters
category_slug: cart-and-checkout-available-filters
post_title: Cart and Checkout - Available Filters
---

View File

@ -1,15 +1,12 @@
---
post_title: Cart and Checkout - Inner Block Types
post_title: Cart and Checkout - Inner block types
menu_title: Inner Block Types
tags: reference, checkout-available-filters
tags: reference
---
# Additional Cart and Checkout inner block types
The following Additional Cart and Checkout inner block types filter is available:
- [`additionalCartCheckoutInnerBlockTypes`](#additionalcartcheckoutinnerblocktypes)
- `additionalCartCheckoutInnerBlockTypes`
## `additionalCartCheckoutInnerBlockTypes`
@ -69,7 +66,7 @@ document.addEventListener( 'DOMContentLoaded', function () {
To call this filter within the editor, wrap the filter registration in a `DOMContentLoaded` event listener and ensure the code runs in the admin panel.
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> 💡 Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->

View File

@ -0,0 +1,116 @@
---
post_title: Cart and Checkout - Available filters
menu_title: Available Filters
tags: reference
---
This document lists the filters that are currently available to extensions and offers usage information for each one of them. Information on registering filters can be found on the [Checkout - Filter Registry](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/packages/checkout/filter-registry/README.md) page.
## Cart Line Items filters
The following [Cart Line Items filters](./cart-line-items.md) are available:
- [`cartItemClass`](./cart-line-items.md#cartitemclass)
- [`cartItemPrice`](./cart-line-items.md#cartitemprice)
- [`itemName`](./cart-line-items.md#itemname)
- [`saleBadgePriceFormat`](./cart-line-items.md#salebadgepriceformat)
- [`showRemoveItemLink`](./cart-line-items.md#showremoveitemlink)
- [`subtotalPriceFormat`](./cart-line-items.md#subtotalpriceformat)
The following screenshot shows which parts the individual filters affect:
![Cart Line Items](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-26-at-13.12.33.png)
## Order Summary Items filters
The following [Order Summary Items filters](./order-summary-items.md) are available:
- [`cartItemClass`](./order-summary-items.md#cartitemclass)
- [`cartItemPrice`](./order-summary-items.md#cartitemprice)
- [`itemName`](./order-summary-items.md#itemname)
- [`subtotalPriceFormat`](./order-summary-items.md#subtotalpriceformat)
The following screenshot shows which parts the individual filters affect:
![Order Summary Items](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-26-at-16.29.45.png)
## Totals Footer Item filter
The following [Totals Footer Item filter](./totals-footer-item.md) is available:
- [`totalLabel`](./totals-footer-item.md#totallabel)
- [`totalValue`](./totals-footer-item.md#totalvalue)
## Checkout and place order button filters
The following [Checkout and place order button filters](./checkout-and-place-order-button.md) are available:
- [`proceedToCheckoutButtonLabel`](./checkout-and-place-order-button.md#proceedtocheckoutbuttonlabel)
- [`proceedToCheckoutButtonLink`](./checkout-and-place-order-button.md#proceedtocheckoutbuttonlink)
- [`placeOrderButtonLabel`](./checkout-and-place-order-button.md#placeorderbuttonlabel)
## Coupon filters
The following [Coupon filters](./coupons.md) are available:
- [`coupons`](./coupons.md#coupons-1)
- [`showApplyCouponNotice`](./coupons.md#showapplycouponnotice)
- [`showRemoveCouponNotice`](./coupons.md#showremovecouponnotice)
## Additional Cart and Checkout inner block types filter
The following [Additional Cart and Checkout inner block types filter](./additional-cart-checkout-inner-block-types.md) is available:
- [`additionalCartCheckoutInnerBlockTypes`](./additional-cart-checkout-inner-block-types.md#additionalcartcheckoutinnerblocktypes)
## Combined filters
Filters can also be combined. The following example shows how to combine some of the available filters.
```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;
const isOrderSummaryContext = ( args ) => args?.context === 'summary';
const modifyCartItemClass = ( defaultValue, extensions, args ) => {
if ( isOrderSummaryContext( args ) ) {
return 'my-custom-class';
}
return defaultValue;
};
const modifyCartItemPrice = ( defaultValue, extensions, args ) => {
if ( isOrderSummaryContext( args ) ) {
return '<price/> for all items';
}
return defaultValue;
};
const modifyItemName = ( defaultValue, extensions, args ) => {
if ( isOrderSummaryContext( args ) ) {
return `🪴 ${ defaultValue } 🪴`;
}
return defaultValue;
};
const modifySubtotalPriceFormat = ( defaultValue, extensions, args ) => {
if ( isOrderSummaryContext( args ) ) {
return '<price/> per item';
}
return defaultValue;
};
registerCheckoutFilters( 'example-extension', {
cartItemClass: modifyCartItemClass,
cartItemPrice: modifyCartItemPrice,
itemName: modifyItemName,
subtotalPriceFormat: modifySubtotalPriceFormat,
} );
```
## Troubleshooting
If you are logged in to the store as an administrator, you should be shown an error like this if your filter is not
working correctly. The error will also be shown in your console.
![Troubleshooting](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-30-at-10.52.53.png)

View File

@ -1,26 +1,24 @@
---
post_title: Cart and Checkout - Cart Line Items
post_title: Cart and Checkout - Cart line items
menu_title: Cart Line Items
tags: reference, checkout-available-filters
tags: reference
---
<!-- markdownlint-disable MD024 -->
# Cart Line Items
The following Cart Line Items filters are available:
- [`cartItemClass`](#cartitemclass)
- [`cartItemPrice`](#cartitemprice)
- [`itemName`](#itemname)
- [`saleBadgePriceFormat`](#salebadgepriceformat)
- [`showRemoveItemLink`](#showremoveitemlink)
- [`subtotalPriceFormat`](#subtotalpriceformat)
- `cartItemClass`
- `cartItemPrice`
- `itemName`
- `saleBadgePriceFormat`
- `showRemoveItemLink`
- `subtotalPriceFormat`
The following objects are shared between the filters:
- [Cart object](#cart-object)
- [Cart Item object](#cart-item-object)
- Cart object
- [Cart Item object
The following screenshot shows which parts the individual filters affect:
@ -95,7 +93,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -174,7 +172,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -251,7 +249,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -337,7 +335,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -415,7 +413,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -505,7 +503,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->

View File

@ -1,21 +1,20 @@
---
post_title: Cart and Checkout - Checkout and Place Order Button
post_title: Cart and Checkout - Checkout and place order button
menu_title: Checkout and Place Order Button
tags: reference, checkout-available-filters
tags: reference
---
<!-- markdownlint-disable MD024 -->
# Checkout and place order button
The following Checkout and place order button filters are available:
- [`proceedToCheckoutButtonLabel`](#proceedtocheckoutbuttonlabel)
- [`proceedToCheckoutButtonLink`](#proceedtocheckoutbuttonlink)
- [`placeOrderButtonLabel`](#placeorderbuttonlabel)
- `proceedToCheckoutButtonLabel`
- `proceedToCheckoutButtonLink`
- `placeOrderButtonLabel`
The following objects are shared between the filters:
- [Cart object](#cart-object)
- [Cart Item object](#cart-item-object)
- Cart object
- Cart Item object
## `proceedToCheckoutButtonLabel`
@ -88,7 +87,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -107,7 +106,7 @@ The `proceedToCheckoutButtonLink` filter allows change the link of the "Proceed
- _defaultValue_ `string` (default: `/checkout`) - The link of the "Proceed to checkout" button.
- _extensions_ `object` (default: `{}`) - The extensions object.
- _args_ `object` - The arguments object with the following keys:
- _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](../available-filters.md#cart-object).
- _cart_ `object` - The cart object from `wc/store/cart`, see [Cart object](./available-filters.md#cart-object).
### Returns <!-- omit in toc -->
@ -167,7 +166,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -204,7 +203,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->

View File

@ -1,18 +1,16 @@
---
post_title: Cart and Checkout Filters - Coupons
menu_title: Coupons
tags: reference, checkout-available-filters
tags: reference
---
<!-- markdownlint-disable MD024 -->
# Coupons
The following Coupon filters are available:
- [`coupons`](#coupons-1)
- [`showApplyCouponNotice`](#showapplycouponnotice)
- [`showRemoveCouponNotice`](#showremovecouponnotice)
- `coupons`
- `showApplyCouponNotice`
- `showRemoveCouponNotice`
## `coupons`
@ -66,7 +64,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -124,7 +122,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -182,7 +180,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->

View File

@ -1,22 +1,21 @@
---
post_title: Cart and Checkout Filters - Order Summary Items
post_title: Cart and Checkout Filters - Order summary items
menu_title: Order Summary Items
tags: reference, checkout-available-filters
tags: reference
---
<!-- markdownlint-disable MD024 -->
# Order Summary Items
The following Order Summary Items filters are available:
- [`cartItemClass`](#cartitemclass)
- [`cartItemPrice`](#cartitemprice)
- [`itemName`](#itemname)
- [`subtotalPriceFormat`](#subtotalpriceformat)
- `cartItemClass`
- `cartItemPrice`
- `itemName`
- `subtotalPriceFormat`
The following objects are shared between the filters:
- [Cart object](#cart-object)
- [Cart Item object](#cart-item-object)
- Cart object
- Cart Item object
The following screenshot shows which parts the individual filters affect:
@ -91,7 +90,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -169,7 +168,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -246,7 +245,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -334,7 +333,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->

View File

@ -1,17 +1,15 @@
---
post_title: Cart and Checkout - Totals Footer Item
post_title: Cart and Checkout - Totals footer item
menu_title: Totals Footer Item
tags: reference, checkout-available-filters
tags: reference
---
<!-- markdownlint-disable MD024 -->
# Totals Footer Item
The following Totals Footer Item filter are available:
- [`totalLabel`](#totallabel)
- [`totalValue`](#totalvalue)
- `totalLabel`
- `totalValue`
## `totalLabel`
@ -48,7 +46,7 @@ registerCheckoutFilters( 'example-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->
@ -93,7 +91,7 @@ registerCheckoutFilters( 'my-extension', {
} );
```
> 💡 Filters can be also combined. See [Combined filters](../available-filters.md#combined-filters) for an example.
> Filters can be also combined. See [Combined filters](./available-filters.md#combined-filters) for an example.
### Screenshots <!-- omit in toc -->

View File

@ -1,27 +1,15 @@
---
post_title: Cart and Checkout - Available Slots
post_title: Cart and Checkout - Available slots
menu_title: Available Slots
tags: reference
---
<!-- markdownlint-disable MD024 -->
# Available Slots <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [ExperimentalOrderMeta](#experimentalordermeta)
- [Passed parameters](#passed-parameters)
- [ExperimentalOrderShippingPackages](#experimentalordershippingpackages)
- [Passed parameters](#passed-parameters-1)
- [ExperimentalOrderLocalPickupPackages](#experimentalorderlocalpickuppackages)
- [Passed parameters](#passed-parameters-2)
- [ExperimentalDiscountsMeta](#experimentaldiscountsmeta)
- [Passed parameters](#passed-parameters-3)
This document presents the list of available Slots that you can use for adding your custom content (Fill).
If you want to add a new SlotFill component, check the [Checkout - Slot Fill document](../../../../packages/checkout/slot/README.md). To read more about Slot and Fill, check the [Slot and Fill document](./slot-fills.md).
If you want to add a new SlotFill component, check the [Checkout - Slot Fill document](https://github.com/woocommerce/woocommerce/blob/1675c63bba94c59703f57c7ef06e7deff8fd6bba/plugins/woocommerce-blocks/packages/checkout/slot/README.md). To read more about Slot and Fill, check the [Slot and Fill document](./slot-fills.md).
**Note About Naming:** Slots that are prefixed with `Experimental` are experimental and subject to change or remove. Once they graduate from the experimental stage, the naming would change and the `Experimental` prefix would be dropped. Check the [Feature Gating document](../../../internal-developers/blocks/feature-flags-and-experimental-interfaces.md) from more information.
**Note About Naming:** Slots that are prefixed with `Experimental` are experimental and subject to change or remove. Once they graduate from the experimental stage, the naming would change and the `Experimental` prefix would be dropped. Check the [Feature Gating document](https://github.com/woocommerce/woocommerce/blob/1675c63bba94c59703f57c7ef06e7deff8fd6bba/plugins/woocommerce-blocks/docs/internal-developers/blocks/feature-flags-and-experimental-interfaces.md) from more information.
## ExperimentalOrderMeta

View File

@ -0,0 +1,8 @@
---
category_title: Payment Methods
category_slug: checkout-payment-methods
post_title: Checkout payment methods
---

View File

@ -0,0 +1,469 @@
---
post_title: Cart and Checkout - Checkout flow and events
menu_title: Checkout Flow and Events
tags: reference
---
This document gives an overview of the flow for the checkout in the WooCommerce checkout block, and some general architectural overviews.
The architecture of the Checkout Block is derived from the following principles:
- A single source of truth for data within the checkout flow.
- Provide a consistent interface for extension integrations (eg Payment methods). This interface protects the integrity of the checkout process and isolates extension logic from checkout logic. The checkout block handles _all_ communication with the server for processing the order. Extensions are able to react to and communicate with the checkout block via the provided interface.
- Checkout flow state is tracked by checkout status.
- Extensions are able to interact with the checkout flow via subscribing to emitted events.
Here's a high level overview of the flow:
![checkout flow diagram](https://user-images.githubusercontent.com/1628454/113739726-f8c9df00-96f7-11eb-80f1-78e25ccc88cb.png)
## General Concepts
### Tracking flow through status
At any point in the checkout lifecycle, components should be able to accurately detect the state of the checkout flow. This includes things like:
- Is something loading? What is loading?
- Is there an error? What is the error?
- is the checkout calculating totals?
Using simple booleans can be fine in some cases, but in others it can lead to complicated conditionals and bug prone code (especially for logic behaviour that reacts to various flow state).
To surface the flow state, the block uses statuses that are tracked in the various contexts. _As much as possible_ these statuses are set internally in reaction to various actions so there's no implementation needed in children components (components just have to _consume_ the status not set status).
The following statuses exist in the Checkout.
#### Checkout Data Store Status
There are various statuses that are exposed on the Checkout data store via selectors. All the selectors are detailed below and in the [Checkout API docs](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/internal-developers/block-client-apis/checkout/checkout-api.md).
You can use them in your component like so
```jsx
const { useSelect } = window.wp.data;
const { CHECKOUT_STORE_KEY } = window.wc.wcBlocksData;
const MyComponent = ( props ) => {
const isComplete = useSelect( ( select ) =>
select( CHECKOUT_STORE_KEY ).isComplete()
);
// do something with isComplete
};
```
The following boolean flags available related to status are:
**isIdle**: When the checkout status is `IDLE` this flag is true. Checkout will be this status after any change to checkout state after the block is loaded. It will also be this status when retrying a purchase is possible after processing happens with an error.
**isBeforeProcessing**: When the checkout status is `BEFORE_PROCESSING` this flag is true. Checkout will be this status when the user submits checkout for processing.
**isProcessing**: When the checkout status is `PROCESSING` this flag is true. Checkout will be this status when all the observers on the event emitted with the `BEFORE_PROCESSING` status are completed without error. It is during this status that the block will be sending a request to the server on the checkout endpoint for processing the order. **Note:** there are some checkout payment status changes that happen during this state as well (outlined in the `PaymentProvider` exposed statuses section).
**isAfterProcessing**: When the checkout status is `AFTER_PROCESSING` this flag is true. Checkout will have this status after the block receives the response from the server side processing request.
**isComplete**: When the checkout status is `COMPLETE` this flag is true. Checkout will have this status after all observers on the events emitted during the `AFTER_PROCESSING` status are completed successfully. When checkout is at this status, the shopper's browser will be redirected to the value of `redirectUrl` at that point (usually the `order-received` route).
#### Special States
The following are booleans exposed via the checkout provider that are independent from each other and checkout statuses but can be used in combination to react to various state in the checkout.
**isCalculating:** This is true when the total is being re-calculated for the order. There are numerous things that might trigger a recalculation of the total: coupons being added or removed, shipping rates updated, shipping rate selected etc. This flag consolidates all activity that might be occurring (including requests to the server that potentially affect calculation of totals). So instead of having to check each of those individual states you can reliably just check if this boolean is true (calculating) or false (not calculating).
**hasError:** This is true when anything in the checkout has created an error condition state. This might be validation errors, request errors, coupon application errors, payment processing errors etc.
### `ShippingProvider` Exposed Statuses
The shipping context provider exposes everything related to shipping in the checkout. Included in this are a set of error statuses that inform what error state the shipping context is in and the error state is affected by requests to the server on address changes, rate retrieval and selection.
Currently the error status may be one of `NONE`, `INVALID_ADDRESS` or `UNKNOWN` (note, this may change in the future).
The status is exposed on the `currentErrorStatus` object provided by the `useShippingDataContext` hook. This object has the following properties on it:
- `isPristine` and `isValid`: Both of these booleans are connected to the same error status. When the status is `NONE` the values for these booleans will be `true`. It basically means there is no shipping error.
- `hasInvalidAddress`: When the address provided for shipping is invalid, this will be true.
- `hasError`: This is `true` when the error status for shipping is either `UNKNOWN` or `hasInvalidAddress`.
### Payment Method Data Store Status
The status of the payment lives in the payment data store. You can query the status with the following selectors:
```jsx
const { select } = window.wp.data;
const { PAYMENT_STORE_KEY } = window.wc.wcBlocksData;
const MyComponent = ( props ) => {
const isPaymentIdle = select( PAYMENT_STORE_KEY ).isPaymentIdle();
const isExpressPaymentStarted =
select( PAYMENT_STORE_KEY ).isExpressPaymentStarted();
const isPaymentProcessing =
select( PAYMENT_STORE_KEY ).isPaymentProcessing();
const isPaymentReady = select( PAYMENT_STORE_KEY ).isPaymentReady();
const hasPaymentError = select( PAYMENT_STORE_KEY ).hasPaymentError();
// do something with the boolean values
};
```
The status here will help inform the current state of _client side_ processing for the payment and are updated via the store actions at different points throughout the checkout processing cycle. _Client side_ means the state of processing any payments by registered and active payment methods when the checkout form is submitted via those payment methods registered client side components. It's still possible that payment methods might have additional server side processing when the order is being processed but that is not reflected by these statuses (more in the [payment method integration doc](./payment-method-integration.md)).
The possible _internal_ statuses that may be set are:
- `IDLE`: This is the status when checkout is initialized and there are payment methods that are not doing anything. This status is also set whenever the checkout status is changed to `IDLE`.
- `EXPRESS_STARTED`: **Express Payment Methods Only** - This status is used when an express payment method has been triggered by the user clicking it's button. This flow happens before processing, usually in a modal window.
- `PROCESSING`: This status is set when the checkout status is `PROCESSING`, checkout `hasError` is false, checkout is not calculating, and the current payment status is not `FINISHED`. When this status is set, it will trigger the payment processing event emitter.
- `READY`: This status is set after all the observers hooked into the payment processing event have completed successfully. The `CheckoutProcessor` component uses this along with the checkout `PROCESSING` status to signal things are ready to send the order to the server with data for processing and to take payment
- `ERROR`: This status is set after an observer hooked into the payment processing event returns an error response. This in turn will end up causing the checkout `hasError` flag to be set to true.
### Emitting Events
Another tricky thing for extensibility, is providing opinionated, yet flexible interfaces for extensions to act and react to specific events in the flow. For stability, it's important that the core checkout flow _controls_ all communication to and from the server specific to checkout/order processing and leave extension specific requirements for the extension to handle. This allows for extensions to predictably interact with the checkout data and flow as needed without impacting other extensions hooking into it.
One of the most reliable ways to implement this type of extensibility is via the usage of an events system. Thus the various context providers:
- expose subscriber APIs for extensions to subscribe _observers_ to the events they want to react to.
- emit events at specific points of the checkout flow that in turn will feed data to the registered observers and, in some cases, react accordingly to the responses from observers.
One _**very important rule**_ when it comes to observers registered to any event emitter in this system is that they _cannot_ update context state. Updating state local to a specific component is okay but not any context or global state. The reason for this is that the observer callbacks are run sequentially at a specific point and thus subsequent observers registered to the same event will not react to any change in global/context state in earlier executed observers.
```jsx
const unsubscribe = emitter( myCallback );
```
You could substitute in whatever emitter you are registering for the `emitter` function. So for example if you are registering for the `onCheckoutValidation` event emitter, you'd have something like:
```jsx
const unsubscribe = onCheckoutValidation( myCallback );
```
You can also indicate what priority you want your observer to execute at. Lower priority is run before higher priority, so you can affect when your observer will run in the stack of observers registered to an emitter. You indicate priority via an number on the second argument:
```jsx
const unsubscribe = onCheckoutValidation( myCallback, 10 );
```
In the examples, `myCallback`, is your subscriber function. The subscriber function could receive data from the event emitter (described in the emitter details below) and may be expected to return a response in a specific shape (also described in the specific emitter details). The subscriber function can be a `Promise` and when the event emitter cycles through the registered observers it will await for any registered Promise to resolve.
Finally, the return value of the call to the emitter function is an unsubscribe function that can be used to unregister your observer. This is especially useful in a React component context where you need to make sure you unsubscribe the observer on component unmount. An example is usage in a `useEffect` hook:
```jsx
const MyComponent = ( { onCheckoutValidation } ) => {
useEffect( () => {
const unsubscribe = onCheckoutValidation( () => true );
return unsubscribe;
}, [ onCheckoutValidation ] );
return null;
};
```
**`Event Emitter Utilities`**
There are a bunch of utility methods that can be used related to events. These are available in `assets/js/base/context/event-emit/utils.ts` and can be imported as follows:
```jsx
import {
isSuccessResponse,
isErrorResponse,
isFailResponse,
noticeContexts,
responseTypes,
shouldRetry,
} from '@woocommerce/base-context';
};
```
The helper functions are described below:
- `isSuccessResponse`, `isErrorResponse` and `isFailResponse`: These are helper functions that receive a value and report via boolean whether the object is a type of response expected. For event emitters that receive responses from registered observers, a `type` property on the returned object from the observer indicates what type of response it is and event emitters will react according to that type. So for instance if an observer returned `{ type: 'success' }` the emitter could feed that to `isSuccessResponse` and it would return `true`. You can see an example of this being implemented for the payment processing emitted event [here](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/34e17c3622637dbe8b02fac47b5c9b9ebf9e3596/assets/js/base/context/cart-checkout/payment-methods/payment-method-data-context.js#L281-L307).
- `noticeContexts`: This is an object containing properties referencing areas where notices can be targeted in the checkout. The object has the following properties:
- `PAYMENTS`: This is a reference to the notice area in the payment methods step.
- `EXPRESS_PAYMENTS`: This is a reference to the notice area in the express payment methods step.
- `responseTypes`: This is an object containing properties referencing the various response types that can be returned by observers for some event emitters. It makes it easier for autocompleting the types and avoiding typos due to human error. The types are `SUCCESS`, `FAIL`, `ERROR`. The values for these types also correspond to the [payment status types](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/34e17c3622637dbe8b02fac47b5c9b9ebf9e3596/src/Payments/PaymentResult.php#L21) from the [checkout endpoint response from the server](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/34e17c3622637dbe8b02fac47b5c9b9ebf9e3596/src/RestApi/StoreApi/Schemas/CheckoutSchema.php#L103-L113).
- `shouldRetry`: This is a function containing the logic whether the checkout flow should allow the user to retry the payment after a previous payment failed. It receives the `response` object and by default checks whether the `retry` property is true/undefined or false. Refer to the [`onCheckoutSuccess`](#oncheckoutsuccess) documentation for more details.
Note: `noticeContexts` and `responseTypes` are exposed to payment methods via the `emitResponse` prop given to their component:
```jsx
const MyPaymentMethodComponent = ( { emitResponse } ) => {
const { noticeContexts, responseTypes } = emitResponse;
// other logic for payment method...
};
```
The following event emitters are available to extensions to register observers to:
### `onCheckoutValidation`
Observers registered to this event emitter will receive nothing as an argument. Also, all observers will be executed before the checkout handles the responses from the emitters. Observers registered to this emitter can return `true` if they have nothing to communicate back to checkout, `false` if they want checkout to go back to `IDLE` status state, or an object with any of the following properties:
- `errorMessage`: This will be added as an error notice on the checkout context.
- `validationErrors`: This will be set as inline validation errors on checkout fields. If your observer wants to trigger validation errors it can use the following shape for the errors:
- This is an object where keys are the property names the validation error is for (that correspond to a checkout field, eg `country` or `coupon`) and values are the error message describing the validation problem.
This event is emitted when the checkout status is `BEFORE_PROCESSING` (which happens at validation time, after the checkout form submission is triggered by the user - or Express Payment methods).
If all observers return `true` for this event, then the checkout status will be changed to `PROCESSING`.
This event emitter subscriber can be obtained via the checkout context using the `useCheckoutContext` hook or to payment method extensions as a prop on their registered component:
_For internal development:_
```jsx
import { useCheckoutContext } from '@woocommerce/base-contexts';
import { useEffect } from '@wordpress/element';
const Component = () => {
const { onCheckoutValidation } = useCheckoutContext();
useEffect( () => {
const unsubscribe = onCheckoutValidation( () => true );
return unsubscribe;
}, [ onCheckoutValidation ] );
return null;
};
```
_For registered payment method components:_
```jsx
const { useEffect } = window.wp.element;
const PaymentMethodComponent = ( { eventRegistration } ) => {
const { onCheckoutValidation } = eventRegistration;
useEffect( () => {
const unsubscribe = onCheckoutValidation( () => true );
return unsubscribe;
}, [ onCheckoutValidation ] );
};
```
### ~~`onPaymentProcessing`~~
This is now deprecated and replaced by the `onPaymentSetup` event emitter.
### `onPaymentSetup`
This event emitter was fired when the payment method context status is `PROCESSING` and that status is set when the checkout status is `PROCESSING`, checkout `hasError` is false, checkout is not calculating, and the current payment status is not `FINISHED`.
This event emitter will execute through each registered observer (passing in nothing as an argument) _until_ an observer returns a non-truthy value at which point it will _abort_ further execution of registered observers.
When a payment method returns a non-truthy value, if it returns a valid response type the event emitter will update various internal statuses according to the response. Here's the possible response types that will get handled by the emitter:
#### Success
A successful response should be given when the user's entered data is correct and the payment checks are successful. A response is considered successful if, at a minimum, it is an object with this shape:
```js
const successResponse = { type: 'success' };
```
When a success response is returned, the payment method context status will be changed to `SUCCESS`. In addition, including any of the additional properties will result in extra actions:
- `paymentMethodData`: The contents of this object will be included as the value for `payment_data` when checkout sends a request to the checkout endpoint for processing the order. This is useful if a payment method does additional server side processing.
- `billingAddress`: This allows payment methods to update any billing data information in the checkout (typically used by Express payment methods) so it's included in the checkout processing request to the server. This data should be in the [shape outlined here](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/assets/js/settings/shared/default-fields.ts).
- `shippingAddress`: This allows payment methods to update any shipping data information for the order (typically used by Express payment methods) so it's included in the checkout processing request to the server. This data should be in the [shape outlined here](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/assets/js/settings/shared/default-fields.ts).
If `billingAddress` or `shippingAddress` properties aren't in the response object, then the state for the data is left alone.
#### Fail
A fail response should be given when there is an error with the payment processing. A response is considered a fail response when it is an object with this shape:
```js
const failResponse = { type: 'failure' };
```
When a fail response is returned by an observer, the payment method context status will be changed to `FAIL`. In addition, including any of the following properties will result in extra actions:
- `message`: The string provided here will be set as an error notice in the checkout.
- `messageContext`: If provided, this will target the given area for the error notice (this is where `noticeContexts` mentioned earlier come in to play). Otherwise the notice will be added to the `noticeContexts.PAYMENTS` area.
- `paymentMethodData`: (same as for success responses).
- `billingAddress`: (same as for success responses).
#### Error
An error response should be given when there is an error with the user input on the checkout form. A response is considered an error response when it is an object with this shape:
```js
const errorResponse = { type: 'error' };
```
When an error response is returned by an observer, the payment method context status will be changed to `ERROR`. In addition, including any of the following properties will result in extra actions:
- `message`: The string provided here will be set as an error notice.
- `messageContext`: If provided, this will target the given area for the error notice (this is where `noticeContexts` mentioned earlier come in to play). Otherwise, the notice will be added to the `noticeContexts.PAYMENTS` area.
- `validationErrors`: This will be set as inline validation errors on checkout fields. If your observer wants to trigger validation errors it can use the following shape for the errors:
- This is an object where keys are the property names the validation error is for (that correspond to a checkout field, eg `country` or `coupon`) and values are the error message describing the validation problem.
If the response object doesn't match any of the above conditions, then the fallback is to set the payment status as `SUCCESS`.
When the payment status is set to `SUCCESS` and the checkout status is `PROCESSING`, the `CheckoutProcessor` component will trigger the request to the server for processing the order.
This event emitter subscriber can be obtained via the checkout context using the `usePaymentEventsContext` hook or to payment method extensions as a prop on their registered component:
_For internal development:_
```jsx
import { usePaymentEventsContext } from '@woocommerce/base-contexts';
import { useEffect } from '@wordpress/element';
const Component = () => {
const { onPaymentSetup } = usePaymentEventsContext();
useEffect( () => {
const unsubscribe = onPaymentSetup( () => true );
return unsubscribe;
}, [ onPaymentSetup ] );
return null;
};
```
_For registered payment method components:_
```jsx
const { useEffect } = window.wp.element;
const PaymentMethodComponent = ( { eventRegistration } ) => {
const { onPaymentSetup } = eventRegistration;
useEffect( () => {
const unsubscribe = onPaymentSetup( () => true );
return unsubscribe;
}, [ onPaymentSetup ] );
};
```
### `onCheckoutSuccess`
This event emitter is fired when the checkout status is `AFTER_PROCESSING` and the checkout `hasError` state is false. The `AFTER_PROCESSING` status is set by the `CheckoutProcessor` component after receiving a response from the server for the checkout processing request.
Observers registered to this event emitter will receive the following object as an argument:
```js
const onCheckoutProcessingData = {
redirectUrl,
orderId,
customerId,
orderNotes,
paymentResult,
};
```
The properties are:
- `redirectUrl`: This is a string that is the url the checkout will redirect to as returned by the processing on the server.
- `orderId`: Is the id of the current order being processed.
- `customerId`: Is the id for the customer making the purchase (that is attached to the order).
- `orderNotes`: This will be any custom note the customer left on the order.
- `paymentResult`: This is the value of [`payment_result` from the /checkout StoreApi response](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/34e17c3622637dbe8b02fac47b5c9b9ebf9e3596/src/RestApi/StoreApi/Schemas/CheckoutSchema.php#L103-L138). The data exposed on this object is (via the object properties):
- `paymentStatus`: Whatever the status is for the payment after it was processed server side. Will be one of `success`, `failure`, `pending`, `error`.
- `paymentDetails`: This will be an arbitrary object that contains any data the payment method processing server side sends back to the client in the checkout processing response. Payment methods are able to hook in on the processing server side and set this data for returning.
This event emitter will invoke each registered observer until a response from any of the registered observers does not equal `true`. At that point any remaining non-invoked observers will be skipped and the response from the observer triggering the abort will be processed.
This emitter will handle a `success` response type (`{ type: success }`) by setting the checkout status to `COMPLETE`. Along with that, if the response includes `redirectUrl` then the checkout will redirect to the given address.
This emitter will also handle a `failure` response type or an `error` response type and if no valid type is detected it will treat it as an `error` response type.
In all cases, if there are the following properties in the response, additional actions will happen:
- `message`: This string will be added as an error notice.
- `messageContext`: If present, the notice will be configured to show in the designated notice area (otherwise it will just be a general notice for the checkout block).
- `retry`: If this is `true` or not defined, then the checkout status will be set to `IDLE`. This basically means that the error is recoverable (for example try a different payment method) and so checkout will be reset to `IDLE` for another attempt by the shopper. If this is `false`, then the checkout status is set to `COMPLETE` and the checkout will redirect to whatever is currently set as the `redirectUrl`.
- `redirectUrl`: If this is present, then the checkout will redirect to this url when the status is `COMPLETE`.
If all observers return `true`, then the checkout status will just be set to `COMPLETE`.
This event emitter subscriber can be obtained via the checkout context using the `useCheckoutContext` hook or to payment method extensions as a prop on their registered component:
_For internal development:_
```jsx
import { useCheckoutContext } from '@woocommerce/base-contexts';
import { useEffect } from '@wordpress/element';
const Component = () => {
const { onCheckoutSuccess } = useCheckoutContext();
useEffect( () => {
const unsubscribe = onCheckoutSuccess( () => true );
return unsubscribe;
}, [ onCheckoutSuccess ] );
return null;
};
```
_For registered payment method components:_
```jsx
const { useEffect } = window.wp.element;
const PaymentMethodComponent = ( { eventRegistration } ) => {
const { onCheckoutSuccess } = eventRegistration;
useEffect( () => {
const unsubscribe = onCheckoutSuccess( () => true );
return unsubscribe;
}, [ onCheckoutSuccess ] );
};
```
### `onCheckoutFail`
This event emitter is fired when the checkout status is `AFTER_PROCESSING` and the checkout `hasError` state is `true`. The `AFTER_PROCESSING` status is set by the `CheckoutProcessor` component after receiving a response from the server for the checkout processing request.
Observers registered to this emitter will receive the same data package as those registered to `onCheckoutSuccess`.
The response from the first observer returning a value that does not `===` true will be handled similarly as the `onCheckoutSuccess` except it only handles when the type is `error` or `failure`.
If all observers return `true`, then the checkout status will just be set to `IDLE` and a default error notice will be shown in the checkout context.
This event emitter subscriber can be obtained via the checkout context using the `useCheckoutContext` hook or to payment method extensions as a prop on their registered component:
_For internal development:_
```jsx
import { useCheckoutContext } from '@woocommerce/base-contexts';
import { useEffect } from '@wordpress/element';
const Component = () => {
const { onCheckoutFail } = useCheckoutContext();
useEffect( () => {
const unsubscribe = onCheckoutFail( () => true );
return unsubscribe;
}, [ onCheckoutFail ] );
return null;
};
```
_For registered payment method components:_
```jsx
const { useEffect } = window.wp.element;
const PaymentMethodComponent = ( { eventRegistration } ) => {
const { onCheckoutFail } = eventRegistration;
useEffect( () => {
const unsubscribe = onCheckoutFail( () => true );
return unsubscribe;
}, [ onCheckoutFail ] );
};
```
### `onShippingRateSuccess`
This event emitter is fired when shipping rates are not loading and the shipping data context error state is `NONE` and there are shipping rates available.
This event emitter doesn't care about any registered observer response and will simply execute all registered observers passing them the current shipping rates retrieved from the server.
### `onShippingRateFail`
This event emitter is fired when shipping rates are not loading and the shipping data context error state is `UNKNOWN` or `INVALID_ADDRESS`.
This event emitter doesn't care about any registered observer response and will simply execute all registered observers passing them the current error status in the context.
### `onShippingRateSelectSuccess`
This event emitter is fired when a shipping rate selection is not being persisted to the server and there are selected rates available and the current error status in the context is `NONE`.
This event emitter doesn't care about any registered observer response and will simply execute all registered observers passing them the current selected rates.
### `onShippingRateSelectFail`
This event emitter is fired when a shipping rate selection is not being persisted to the server and the shipping data context error state is `UNKNOWN` or `INVALID_ADDRESS`.
This event emitter doesn't care about any registered observer response and will simply execute all registered observers passing them the current error status in the context.

View File

@ -1,30 +1,11 @@
---
post_title: Cart and Checkout - Filtering payment methods in the Checkout block
menu_title: Filtering Payment Methods
tags: how-to, checkout-payment-methods
tags: how-to
---
<!-- markdownlint-disable MD024 -->
# Filtering Payment Methods in the Checkout block <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [The problem](#the-problem)
- [The solution](#the-solution)
- [Importing](#importing)
- [Aliased import](#aliased-import)
- [`wc global`](#wc-global)
- [Signature](#signature)
- [Extension namespace collision](#extension-namespace-collision)
- [Usage example](#usage-example)
- [Callbacks registered for payment methods](#callbacks-registered-for-payment-methods)
- [Filtering payment methods using requirements](#filtering-payment-methods-using-requirements)
- [The problem](#the-problem-1)
- [The solution](#the-solution-1)
- [Basic usage](#basic-usage)
- [Putting it all together](#putting-it-all-together)
## The problem
You're an extension developer, and your extension is conditionally hiding payment gateways on the checkout step. You need to be able to hide payment gateways on the Checkout block using a front-end extensibility point.
@ -105,7 +86,8 @@ interface CanMakePaymentArgument {
}
```
If you need data that is not available in the parameter received by the callback you can consider [exposing your data in the Store API](../rest-api/extend-rest-api-add-data.md).
If you need data that is not available in the parameter received by the callback you can consider [exposing your data in the Store API](https://github.com/woocommerce/woocommerce/blob/1675c63bba94c59703f57c7ef06e7deff8fd6bba/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-add-data.md).
## Filtering payment methods using requirements
@ -121,7 +103,7 @@ To allow the shopper to check out without entering payment details, but still re
Using the `supports` configuration of payment methods it is possible to prevent other payment methods (such as credit card, PayPal etc.) from being used to check out, and only allow the one your extension has added to appear in the Checkout block.
For more information on how to register a payment method with WooCommerce Blocks, please refer to the [Payment method integration](../checkout-payment-methods/payment-method-integration.md) documentation.
For more information on how to register a payment method with WooCommerce Blocks, please refer to the [Payment method integration](./payment-method-integration.md) documentation.
### Basic usage

View File

@ -1,37 +1,9 @@
---
post_title: Cart and Checkout - Payment method integration for the Checkout block
menu_title: Payment Method Integration
tags: reference, checkout-payment-methods
tags: reference
---
# Payment Method Integration for the Checkout Block <!-- omit in toc -->
The checkout block has an API interface for payment methods to integrate that consists of both a server side and client side implementation.
## Table of Contents <!-- omit in toc -->
- [Client Side integration](#client-side-integration)
- [Express payment methods - `registerExpressPaymentMethod( options )`](#express-payment-methods---registerexpresspaymentmethod-options-)
- [Aliased import](#registerexpresspaymentmethod-aliased-import)
- [`wc global`](#registerexpresspaymentmethod-on-the-wc-global)
- [The registration options](#the-registerexpresspaymentmethod-registration-options)
- [`name` (required)](#name-required)
- [`content` (required)](#content-required)
- [`edit` (required)](#edit-required)
- [`canMakePayment` (required)](#canmakepayment-required)
- [`paymentMethodId`](#paymentmethodid)
- [`supports:features`](#supportsfeatures)
- [Payment Methods - `registerPaymentMethod( options )`](#payment-methods---registerpaymentmethod-options-)
- [Aliased import](#registerpaymentmethod-aliased-import)
- [`wc global`](#registerpaymentmethod-on-the-wc-global)
- [The registration options](#the-registerpaymentmethod-registration-options)
- [Props Fed to Payment Method Nodes](#props-fed-to-payment-method-nodes)
- [Server Side Integration](#server-side-integration)
- [Processing Payment](#processing-payment)
- [Registering Assets](#registering-assets)
- [Hooking into the Checkout processing by the Store API](#hooking-into-the-checkout-processing-by-the-store-api)
- [Putting it all together](#putting-it-all-together)
## Client Side integration
The client side integration consists of an API for registering both _express_ payment methods (those that consist of a one-button payment process initiated by the shopper such as Stripe, ApplePay, or GooglePay), and payment methods such as _cheque_, PayPal Standard, or Stripe Credit Card.
@ -89,7 +61,7 @@ This should be a unique string (wise to try to pick something unique for your ga
#### `content` (required)
This should be a React node that will output in the express payment method area when the block is rendered in the frontend. It will be cloned in the rendering process. When cloned, this React node will receive props passed in from the checkout payment method interface that will allow your component to interact with checkout data (more on [these props later](./payment-method-integration.md#props-fed-to-payment-method-nodes)).
This should be a React node that will output in the express payment method area when the block is rendered in the frontend. It will be cloned in the rendering process. When cloned, this React node will receive props passed in from the checkout payment method interface that will allow your component to interact with checkout data (more on [these props later](#props-fed-to-payment-method-nodes)).
#### `edit` (required)
@ -165,7 +137,7 @@ The options you feed the configuration instance are the same as those for expres
### Props Fed to Payment Method Nodes
A big part of the payment method integration is the interface that is exposed for payment methods to use via props when the node provided is cloned and rendered on block mount. While all the props are listed below, you can find more details about what the props reference, their types etc via the [typedefs described in this file](../../../../assets/js/types/type-defs/payment-method-interface.ts).
A big part of the payment method integration is the interface that is exposed for payment methods to use via props when the node provided is cloned and rendered on block mount. While all the props are listed below, you can find more details about what the props reference, their types etc via the [typedefs described in this file](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/assets/js/types/type-defs/payment-method-interface.ts).
| Property | Type | Description | Values |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

View File

@ -1,20 +1,9 @@
---
post_title: Cart and Checkout - Dom Events
menu_title: Dom Events
post_title: Cart and Checkout - DOM events
menu_title: DOM Events
tags: reference
---
# DOM Events <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [WooCommerce core events in WooCommerce Blocks](#woocommerce-core-events-in-woocommerce-blocks)
- [WooCommerce Blocks events](#woocommerce-blocks-events)
- [`wc-blocks_adding_to_cart`](#wc-blocks_adding_to_cart)
- [`wc-blocks_added_to_cart`](#wc-blocks_added_to_cart)
- [`detail` parameters:](#detail-parameters)
- [`wc-blocks_removed_from_cart`](#wc-blocks_removed_from_cart)
Some blocks need to react to certain events in order to display the most up to date data or behave in a certain way. That's the case of the Cart block, for example, that must listen to 'add to cart' events in order to update the cart contents; or the Mini-Cart block, that gets opened every time a product is added to the cart.
## WooCommerce core events in WooCommerce Blocks

View File

@ -0,0 +1,8 @@
---
category_title: Hooks
category_slug: cart-and-checkout-hooks
post_title: Cart and Checkout - Hooks
---

View File

@ -0,0 +1,50 @@
---
post_title: Cart and Checkout - Legacy hooks
menu_title: Legacy Hooks
tags: reference
---
Below are the hooks that exist in WooCommerce core and that were brough over to WooCommerce Blocks.
Please note that the actions and filters here run on the server side. The client-side blocks won't necessarily change based on a callback added to a server side hook. [Please see our documentation relating to APIs for manipulating the blocks on the client-side](../README.md).
## Legacy Filters
- [loop_shop_per_page](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#loop_shop_per_page)
- [wc_session_expiration](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#wc_session_expiration)
- [woocommerce_add_cart_item](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_add_cart_item)
- [woocommerce_add_cart_item_data](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_add_cart_item_data)
- [woocommerce_add_to_cart_quantity](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_add_to_cart_quantity)
- [woocommerce_add_to_cart_sold_individually_quantity](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_add_to_cart_sold_individually_quantity)
- [woocommerce_add_to_cart_validation](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_add_to_cart_validation)
- [woocommerce_adjust_non_base_location_prices](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_adjust_non_base_location_prices)
- [woocommerce_apply_base_tax_for_local_pickup](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_apply_base_tax_for_local_pickup)
- [woocommerce_apply_individual_use_coupon](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_apply_individual_use_coupon)
- [woocommerce_apply_with_individual_use_coupon](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_apply_with_individual_use_coupon)
- [woocommerce_cart_contents_changed](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_cart_contents_changed)
- [woocommerce_cart_item_permalink](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_cart_item_permalink)
- [woocommerce_get_item_data](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_get_item_data)
- [woocommerce_loop_add_to_cart_args](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_loop_add_to_cart_args)
- [woocommerce_loop_add_to_cart_link](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_loop_add_to_cart_link)
- [woocommerce_new_customer_data](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_new_customer_data)
- [woocommerce_pay_order_product_has_enough_stock](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_pay_order_product_has_enough_stock)
- [woocommerce_pay_order_product_in_stock](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_pay_order_product_in_stock)
- [woocommerce_registration_errors](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_registration_errors)
- [woocommerce_shipping_package_name](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_shipping_package_name)
- [woocommerce_show_page_title](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_show_page_title)
- [woocommerce_single_product_image_thumbnail_html](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/filters.md#woocommerce_single_product_image_thumbnail_html)
## Legacy Actions
- [woocommerce_add_to_cart](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_add_to_cart)
- [woocommerce_after_main_content](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_after_main_content)
- [woocommerce_after_shop_loop](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_after_shop_loop)
- [woocommerce_applied_coupon](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_applied_coupon)
- [woocommerce_archive_description](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_archive_description)
- [woocommerce_before_main_content](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_before_main_content)
- [woocommerce_before_shop_loop](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_before_shop_loop)
- [woocommerce_check_cart_items](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_check_cart_items)
- [woocommerce_created_customer](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_created_customer)
- [woocommerce_no_products_found](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_no_products_found)
- [woocommerce_register_post](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_register_post)
- [woocommerce_shop_loop](https://github.com/woocommerce/woocommerce-blocks/blob/trunk/docs/third-party-developers/extensibility/hooks/actions.md#woocommerce_shop_loop)

View File

@ -1,11 +1,9 @@
---
post_title: Cart and Checkout - How the Checkout block processes an order
menu_title: Processing an order
post_title: Cart and Checkout - How the checkout block processes an order
menu_title: Processing an Order
tags: reference
---
# How The Checkout Block Processes an Order
This document will shed some light on the inner workings of the Checkout flow. More specifically, what happens after a user hits the “Place Order” button.
## Structure

View File

@ -1,24 +1,9 @@
---
post_title: Cart and Checkout - Handling scripts, styles, and data
menu_title: Script, styles, and data handling
menu_title: Script, Styles, and Data Handling
tags: how-to
---
# `IntegrationRegistry` and `IntegrationInterface` <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [The problem](#the-problem)
- [The solution](#the-solution)
- [`IntegrationInterface` methods](#integrationinterface-methods)
- [`get_name()`](#get_name)
- [`initialize()`](#initialize)
- [`get_script_handles()`](#get_script_handles)
- [`get_editor_script_handles()`](#get_editor_script_handles)
- [`get_script_data()`](#get_script_data)
- [Usage example](#usage-example)
- [Getting data added in `get_script_data`](#getting-data-added-in-get_script_data)
## The problem
You are an extension developer, and to allow users to interact with your extension on the client-side, you have written some CSS and JavaScript that you would like to be included on the page. Your JavaScript also relies on some server-side data, and you'd like this to be available to your scripts.

View File

@ -1,22 +1,12 @@
---
post_title: Cart and Checkout - Slot and Fill
post_title: Cart and Checkout - Slot and fill
menu_title: Slot and Fill
tags: reference
---
# Slot and Fill <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [The problem](#the-problem)
- [Solution](#solution)
- [Basic Usage](#basic-usage)
- [registerPlugin](#registerplugin)
- [Requirements](#requirements)
## The problem
You added custom data to the [Store API](../rest-api/extend-rest-api-add-data.md). You changed several strings using [Checkout filters](./available-filters.md). Now you want to render your own components in specific places in the Cart and Checkout.
You added custom data to the [Store API](https://github.com/woocommerce/woocommerce/blob/1675c63bba94c59703f57c7ef06e7deff8fd6bba/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-add-data.md). You changed several strings using [Checkout filters](./available-filters.md). Now you want to render your own components in specific places in the Cart and Checkout.
## Solution

View File

@ -37,16 +37,225 @@
},
{
"post_title": "How to add a custom field to simple and variable products",
"menu_title": "Add custom fields to products",
"menu_title": "Add Custom Fields to Products",
"tags": "how-to",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/building-a-woo-store/adding-a-custom-field-to-variable-products.md",
"hash": "72eba9999d9f1a152a10d27df349e666d1c3735fd3f1328a50c69c846dd18bed",
"hash": "59ef97ed2053dedfa5e7c658d5c7fa470d8110afc9b84584cb32b58389bf5687",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/building-a-woo-store/adding-a-custom-field-to-variable-products.md",
"id": "64b686dcd5fdd4842be2fc570108231d5a8bfc1b"
}
],
"categories": []
},
{
"content": "",
"category_slug": "cart-and-checkout-blocks",
"category_title": "Cart and Checkout Blocks",
"posts": [
{
"post_title": "Cart and Checkout - Slot and fill",
"menu_title": "Slot and Fill",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/slot-fills.md",
"hash": "59ffc2bc3121b6bd9f5d0d6e390600e85bbffb0e23ad31118f8628eb264b0bd7",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/slot-fills.md",
"id": "e388101586765dd9aca752d66d667d74951a1504"
},
{
"post_title": "Cart and Checkout - Handling scripts, styles, and data",
"menu_title": "Script, Styles, and Data Handling",
"tags": "how-to",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/integration-interface.md",
"hash": "0f69443cf4d6fc672fb1ff02158f81c513e05675c9df0f8f4bc82a7efacbb20c",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/integration-interface.md",
"id": "4e702e6f5d22756c4d3518ee3190320df691878f"
},
{
"post_title": "Cart and Checkout - How the checkout block processes an order",
"menu_title": "Processing an Order",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/how-checkout-processes-an-order.md",
"hash": "17b546f85344c84ee773be7d77ddd0f7f4bfe49f05c3f483dd2d01b21ac92dfc",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/how-checkout-processes-an-order.md",
"id": "092e66dac8f44d08799ba1d2411d757fd53c9e00"
},
{
"post_title": "Cart and Checkout - DOM events",
"menu_title": "DOM Events",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/dom-events.md",
"hash": "5ad212b2ee74a7f85dfe05dfa10a3797d839c4e791cc78998fadf30f8a61adf9",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/dom-events.md",
"id": "d04c25818072f47ec21c36e7907e0f81c9c20cc3"
},
{
"post_title": "Cart and Checkout - Available slots",
"menu_title": "Available Slots",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/available-slot-fills.md",
"hash": "0d715a474c3e6e5d11aec427c8baf2098416d09ea8d79a1ce32f0a88e6888ae9",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/available-slot-fills.md",
"id": "c7ac16eee5540b06b6db928f5d03282ff177e84e",
"links": {
"./slot-fills.md": "e388101586765dd9aca752d66d667d74951a1504"
}
},
{
"post_title": "Cart and Checkout - Additional checkout fields",
"menu_title": "Additional Checkout Fields",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/additional-checkout-fields.md",
"hash": "9ebaa1a488a72db1f698504bf0c6b556fb4d12a70f648e247dc323fa91969f13",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/additional-checkout-fields.md",
"id": "cb5dd8d59043a4e53929121b45da7b33b1661ab8"
}
],
"categories": [
{
"content": "\n\n\n",
"category_slug": "cart-and-checkout-available-filters",
"category_title": "Available Filters",
"posts": [
{
"post_title": "Cart and Checkout - Totals footer item",
"menu_title": "Totals Footer Item",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/available-filters/totals-footer-item.md",
"hash": "628eec63db5f53987c508509e4929b4635725313701d6c5f9600d1e82746acb3",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/available-filters/totals-footer-item.md",
"id": "90a9b8df374082f1713866a58b810303adb4d3da"
},
{
"post_title": "Cart and Checkout Filters - Order summary items",
"menu_title": "Order Summary Items",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/available-filters/order-summary-items.md",
"hash": "bb49ef3f1867dcb1992c629d0f8cbef1dfc5f138e2f0b479bca0f6b961150f94",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/available-filters/order-summary-items.md",
"id": "78eb3b135f82a3624a49979e3e93334295abd060"
},
{
"post_title": "Cart and Checkout Filters - Coupons",
"menu_title": "Coupons",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/available-filters/coupons.md",
"hash": "825c97646d49559e4f0425590f1d968f2c861c47484b90fc633eefe5f50e432e",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/available-filters/coupons.md",
"id": "5a022617f3d0267c9b771374f28970e779a6e99d"
},
{
"post_title": "Cart and Checkout - Checkout and place order button",
"menu_title": "Checkout and Place Order Button",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/available-filters/checkout-and-place-order-button.md",
"hash": "b3d0568c6e4d17fcc6bb2446e6c606d8fc5b790af92920e5d6dd71f2b31c2e8f",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/available-filters/checkout-and-place-order-button.md",
"id": "c97ca710c2e8107bf90915e038a34c8a1016c63a"
},
{
"post_title": "Cart and Checkout - Cart line items",
"menu_title": "Cart Line Items",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/available-filters/cart-line-items.md",
"hash": "7bcde17e82296595ff97fcc57f38bab0e0f37bbcc741e40f1a12cbd10775174c",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/available-filters/cart-line-items.md",
"id": "97881b973dc1d08a54c54e0a04ecb75ee48dcee2"
},
{
"post_title": "Cart and Checkout - Available filters",
"menu_title": "Available Filters",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/available-filters/available-filters.md",
"hash": "7c58edf7ec3223171bff44a41c2fc2a65db8372f9718ca6f2ea1c9ab511f9dbb",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/available-filters/available-filters.md",
"id": "d88f29ca4697eace597ea00ea41b6f25b4a4dee1",
"links": {
"./cart-line-items.md": "97881b973dc1d08a54c54e0a04ecb75ee48dcee2",
"./order-summary-items.md": "78eb3b135f82a3624a49979e3e93334295abd060",
"./totals-footer-item.md": "90a9b8df374082f1713866a58b810303adb4d3da",
"./checkout-and-place-order-button.md": "c97ca710c2e8107bf90915e038a34c8a1016c63a",
"./coupons.md": "5a022617f3d0267c9b771374f28970e779a6e99d",
"./additional-cart-checkout-inner-block-types.md": "3167c9602b1bd3b206226a0d4415944a5f647495"
}
},
{
"post_title": "Cart and Checkout - Inner block types",
"menu_title": "Inner Block Types",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/available-filters/additional-cart-checkout-inner-block-types.md",
"hash": "3ea3113a1686f0749ceac3ede28c865630563ccca6d18431d7efb0f6f463cc09",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/available-filters/additional-cart-checkout-inner-block-types.md",
"id": "3167c9602b1bd3b206226a0d4415944a5f647495"
}
],
"categories": []
},
{
"content": "\n\n\n",
"category_slug": "checkout-payment-methods",
"category_title": "Payment Methods",
"posts": [
{
"post_title": "Cart and Checkout - Payment method integration for the Checkout block",
"menu_title": "Payment Method Integration",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/checkout-payment-methods/payment-method-integration.md",
"hash": "f60acaaea4a6ac4adf637bc7069c966e01db089f9dfaa937def91165a71a4255",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/checkout-payment-methods/payment-method-integration.md",
"id": "c9a763b6976ecf03aeb961577c17c31f1ac7c420",
"links": {
"./checkout-flow-and-events.md": "499384cbb48ed96a2e12653cd68bd82d123a20a1"
}
},
{
"post_title": "Cart and Checkout - Filtering payment methods in the Checkout block",
"menu_title": "Filtering Payment Methods",
"tags": "how-to",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/checkout-payment-methods/filtering-payment-methods.md",
"hash": "eec74b9116b1c0b76fdd9e50810e5f08467aec90ee62486409ca204be21dc3e4",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/checkout-payment-methods/filtering-payment-methods.md",
"id": "5c9ff65767116f51e9ec4de26794e6e4e743ffa3",
"links": {
"./payment-method-integration.md": "c9a763b6976ecf03aeb961577c17c31f1ac7c420"
}
},
{
"post_title": "Cart and Checkout - Checkout flow and events",
"menu_title": "Checkout Flow and Events",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/checkout-payment-methods/checkout-flow-and-events.md",
"hash": "dcc4af69b2614b0722431f81a312558bf3c5fa349021849d241bf896e02813a7",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/checkout-payment-methods/checkout-flow-and-events.md",
"id": "499384cbb48ed96a2e12653cd68bd82d123a20a1",
"links": {
"./payment-method-integration.md": "c9a763b6976ecf03aeb961577c17c31f1ac7c420"
}
}
],
"categories": []
},
{
"content": "\n\n\n",
"category_slug": "cart-and-checkout-hooks",
"category_title": "Hooks",
"posts": [
{
"post_title": "Cart and Checkout - Legacy hooks",
"menu_title": "Legacy Hooks",
"tags": "reference",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/cart-and-checkout-blocks/hooks/migrated-hooks.md",
"hash": "dc87374afba4a93d796d0fd89f99bec5a4c0bac6a5e1f81c89dc37242cd6dd0b",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/cart-and-checkout-blocks/hooks/migrated-hooks.md",
"id": "5264fa45d393327b2c9cffb038c4d3670879d911",
"links": {
"../README.md": "c259c391610e4f89c7218966dd742c5c579c0a8f"
}
}
],
"categories": []
}
]
},
{
"content": "\nAccess a collection of useful code snippets to customize and enhance your WooCommerce store's functionality.\n",
"category_slug": "code-snippets",
@ -299,6 +508,34 @@
],
"categories": []
},
{
"content": "",
"category_slug": "extensibility-in-blocks",
"category_title": "Extensibility in blocks",
"posts": [
{
"post_title": "An introduction to extensiblity in WooCommerce Blocks",
"menu_title": "Introduction",
"edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/extensibility-in-blocks/extending-blocks.md",
"hash": "c81b808abcdcfb708266a7db33d73bc85b014c5042c54801d6be719ca745e45d",
"url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/extensibility-in-blocks/extending-blocks.md",
"id": "4fadb6f83309e1033060d94b3340ae0be27ad718",
"links": {
"../cart-and-checkout-blocks/hooks/migrated-hooks.md": "5264fa45d393327b2c9cffb038c4d3670879d911",
"../cart-and-checkout-blocks/checkout-payment-methods/checkout-flow-and-events.md": "499384cbb48ed96a2e12653cd68bd82d123a20a1",
"../cart-and-checkout-blocks/checkout-payment-methods/payment-method-integration.md": "c9a763b6976ecf03aeb961577c17c31f1ac7c420",
"../cart-and-checkout-blocks/checkout-payment-methods/filtering-payment-methods.md": "5c9ff65767116f51e9ec4de26794e6e4e743ffa3",
"../cart-and-checkout-blocks/how-checkout-processes-an-order.md": "092e66dac8f44d08799ba1d2411d757fd53c9e00",
"../cart-and-checkout-blocks/integration-interface.md": "4e702e6f5d22756c4d3518ee3190320df691878f",
"../cart-and-checkout-blocks/slot-fills.md": "e388101586765dd9aca752d66d667d74951a1504",
"../cart-and-checkout-blocks/available-slot-fills.md": "c7ac16eee5540b06b6db928f5d03282ff177e84e",
"../cart-and-checkout-blocks/dom-events.md": "d04c25818072f47ec21c36e7907e0f81c9c20cc3",
"../cart-and-checkout-blocks/additional-checkout-fields.md": "cb5dd8d59043a4e53929121b45da7b33b1661ab8"
}
}
],
"categories": []
},
{
"content": "\nExplore how to develop WooCommerce extensions with practical tutorials and resources ideal for initial setup and understanding the core functionalities of the platform.\n",
"category_slug": "extension-development",
@ -1367,5 +1604,5 @@
"categories": []
}
],
"hash": "cf89b5c07e5b7a9007eb4afe021b02ddce4611c81a863b0a431ae57491a3b37f"
"hash": "287d122348fe6d8990938c8a08c37eaae24832f403cb020e555d8ea8980b0fde"
}

View File

@ -0,0 +1,5 @@
---
category_title: Extensibility in blocks
category_slug: extensibility-in-blocks
post_title: Extensibility in blocks
---

View File

@ -0,0 +1,62 @@
---
post_title: An introduction to extensiblity in WooCommerce Blocks
menu_title: Introduction
---
These documents are all dealing with extensibility in the various WooCommerce Blocks.
## Imports and dependency extration
The documentation in this section will use window globals in code examples, for example:
```js
const { registerCheckoutFilters } = window.wc.blocksCheckout;
```
However, if you're using `@woocommerce/dependency-extraction-webpack-plugin` for enhanced dependency management you can instead use ES module syntax:
```js
import { registerCheckoutFilters } from '@woocommerce/blocks-checkout';
```
See <https://www.npmjs.com/package/@woocommerce/dependency-extraction-webpack-plugin> for more information.
## Hooks (actions and filters)
| Document | Description |
| ----------------------------- | ------------------------------------------------------- |
| [Actions](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/hooks/actions.md) | Documentation covering action hooks on the server side. |
| [Filters](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/hooks/filters.md) | Documentation covering filter hooks on the server side. |
| [Migrated Hooks](../cart-and-checkout-blocks/hooks/migrated-hooks.md) | Documentation covering the migrated WooCommerce core hooks. |
## REST API
| Document | Description |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Exposing your data in the Store API.](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-add-data.md) | Explains how you can add additional data to Store API endpoints. |
| [Available endpoints to extend with ExtendSchema](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/rest-api/available-endpoints-to-extend.md) | A list of all available endpoints to extend. |
| [Available Formatters](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-formatters.md) | Available `Formatters` to format data for use in the Store API. |
| [Updating the cart with the Store API](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/rest-api/extend-rest-api-update-cart.md) | Update the server-side cart following an action from the front-end. |
## Checkout Payment Methods
| Document | Description |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [Checkout Flow and Events](../cart-and-checkout-blocks/checkout-payment-methods/checkout-flow-and-events.md) | All about the checkout flow in the checkout block and the various emitted events that can be subscribed to. |
| [Payment Method Integration](../cart-and-checkout-blocks/checkout-payment-methods/payment-method-integration.md) | Information about implementing payment methods. |
| [Filtering Payment Methods](../cart-and-checkout-blocks/checkout-payment-methods/filtering-payment-methods.md) | Information about filtering the payment methods available in the Checkout Block. |
## Checkout Block
In addition to the reference material below, [please see the `block-checkout` package documentation](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/packages/checkout/README.md) which is used to extend checkout with Filters, Slot Fills, and Inner Blocks.
| Document | Description |
|--------------------------------------------------------------------------------------------------| ----------------------------------------------------------------------------------------------------------------- |
| [How the Checkout Block processes an order](../cart-and-checkout-blocks/how-checkout-processes-an-order.md) | The detailed inner workings of the Checkout Flow. |
| [IntegrationInterface](../cart-and-checkout-blocks/integration-interface.md) | The `IntegrationInterface` class and how to use it to register scripts, styles, and data with WooCommerce Blocks. |
| [Available Filters](../cart-and-checkout-blocks/available-filters.md) | All about the filters that you may use to change values of certain elements of WooCommerce Blocks. |
| [Slots and Fills](../cart-and-checkout-blocks/slot-fills.md) | Explains Slot Fills and how to use them to render your own components in Cart and Checkout. |
| [Available Slot Fills](../cart-and-checkout-blocks/available-slot-fills.md) | Available Slots that you can use and their positions in Cart and Checkout. |
| [DOM Events](../cart-and-checkout-blocks/dom-events.md) | A list of DOM Events used by some blocks to communicate between them and with other parts of WooCommerce. |
| [Filter Registry](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce-blocks/packages/checkout/filter-registry/README.md) | The filter registry allows callbacks to be registered to manipulate certain values. |
| [Additional Checkout Fields](../cart-and-checkout-blocks/additional-checkout-fields.md) | The filter registry allows callbacks to be registered to manipulate certain values. |

View File

@ -1,77 +0,0 @@
# Extensibility in WooCommerce Blocks <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [Imports and dependency extration](#imports-and-dependency-extration)
- [Hooks (actions and filters)](#hooks-actions-and-filters)
- [REST API](#rest-api)
- [Checkout Payment Methods](#checkout-payment-methods)
- [Checkout Block](#checkout-block)
These documents are all dealing with extensibility in the various WooCommerce Blocks.
## Imports and dependency extration
The documentation in this section will use window globals in code examples, for example:
```js
const { registerCheckoutFilters } = window.wc.blocksCheckout;
```
However, if you're using `@woocommerce/dependency-extraction-webpack-plugin` for enhanced dependency management you can instead use ES module syntax:
```js
import { registerCheckoutFilters } from '@woocommerce/blocks-checkout';
```
See <https://www.npmjs.com/package/@woocommerce/dependency-extraction-webpack-plugin> for more information.
## Hooks (actions and filters)
| Document | Description |
| ----------------------------- | ------------------------------------------------------- |
| [Actions](./hooks/actions.md) | Documentation covering action hooks on the server side. |
| [Filters](./hooks/filters.md) | Documentation covering filter hooks on the server side. |
| [Migrated Hooks](./hooks/migrated-hooks.md) | Documentation covering the migrated WooCommerce core hooks. |
## REST API
| Document | Description |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Exposing your data in the Store API.](./rest-api/extend-rest-api-add-data.md) | Explains how you can add additional data to Store API endpoints. |
| [Available endpoints to extend with ExtendSchema](./rest-api/available-endpoints-to-extend.md) | A list of all available endpoints to extend. |
| [Available Formatters](./rest-api/extend-rest-api-formatters.md) | Available `Formatters` to format data for use in the Store API. |
| [Updating the cart with the Store API](./rest-api/extend-rest-api-update-cart.md) | Update the server-side cart following an action from the front-end. |
## Checkout Payment Methods
| Document | Description |
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [Checkout Flow and Events](./checkout-payment-methods/checkout-flow-and-events.md) | All about the checkout flow in the checkout block and the various emitted events that can be subscribed to. |
| [Payment Method Integration](./checkout-payment-methods/payment-method-integration.md) | Information about implementing payment methods. |
| [Filtering Payment Methods](./checkout-payment-methods/filtering-payment-methods.md) | Information about filtering the payment methods available in the Checkout Block. |
## Checkout Block
In addition to the reference material below, [please see the `block-checkout` package documentation](../../../packages/checkout/README.md) which is used to extend checkout with Filters, Slot Fills, and Inner Blocks.
| Document | Description |
|--------------------------------------------------------------------------------------------------| ----------------------------------------------------------------------------------------------------------------- |
| [How the Checkout Block processes an order](./checkout-block/how-checkout-processes-an-order.md) | The detailed inner workings of the Checkout Flow. |
| [IntegrationInterface](./checkout-block/integration-interface.md) | The `IntegrationInterface` class and how to use it to register scripts, styles, and data with WooCommerce Blocks. |
| [Available Filters](./checkout-block/available-filters.md) | All about the filters that you may use to change values of certain elements of WooCommerce Blocks. |
| [Slots and Fills](./checkout-block/slot-fills.md) | Explains Slot Fills and how to use them to render your own components in Cart and Checkout. |
| [Available Slot Fills](./checkout-block/available-slot-fills.md) | Available Slots that you can use and their positions in Cart and Checkout. |
| [DOM Events](./checkout-block/dom-events.md) | A list of DOM Events used by some blocks to communicate between them and with other parts of WooCommerce. |
| [Filter Registry](../../../packages/checkout/filter-registry/README.md) | The filter registry allows callbacks to be registered to manipulate certain values. |
| [Additional Checkout Fields](./checkout-block/additional-checkout-fields.md) | The filter registry allows callbacks to be registered to manipulate certain values. |
<!-- FEEDBACK -->
---
[We're hiring!](https://woocommerce.com/careers/) Come work with us!
🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/third-party-developers/extensibility/README.md)
<!-- /FEEDBACK -->

View File

@ -1,129 +0,0 @@
---
post_title: Cart and Checkout - Available Filters
menu_title: Available Filters
tags: reference
---
# Available filters <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [Cart Line Items filters](#cart-line-items-filters)
- [Order Summary Items filters](#order-summary-items-filters)
- [Totals Footer Item filter](#totals-footer-item-filter)
- [Checkout and place order button filters](#checkout-and-place-order-button-filters)
- [Coupon filters](#coupon-filters)
- [Additional Cart and Checkout inner block types filter](#additional-cart-and-checkout-inner-block-types-filter)
- [Combined filters](#combined-filters)
- [Troubleshooting](#troubleshooting)
This document lists the filters that are currently available to extensions and offers usage information for each one of them. Information on registering filters can be found on the [Checkout - Filter Registry](../../../../packages/checkout/filter-registry/README.md) page.
## Cart Line Items filters
The following [Cart Line Items filters](./available-filters/cart-line-items.md) are available:
- [`cartItemClass`](./available-filters/cart-line-items.md#cartitemclass)
- [`cartItemPrice`](./available-filters/cart-line-items.md#cartitemprice)
- [`itemName`](./available-filters/cart-line-items.md#itemname)
- [`saleBadgePriceFormat`](./available-filters/cart-line-items.md#salebadgepriceformat)
- [`showRemoveItemLink`](./available-filters/cart-line-items.md#showremoveitemlink)
- [`subtotalPriceFormat`](./available-filters/cart-line-items.md#subtotalpriceformat)
The following screenshot shows which parts the individual filters affect:
![Cart Line Items](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-26-at-13.12.33.png)
## Order Summary Items filters
The following [Order Summary Items filters](./available-filters/order-summary-items.md) are available:
- [`cartItemClass`](./available-filters/order-summary-items.md#cartitemclass)
- [`cartItemPrice`](./available-filters/order-summary-items.md#cartitemprice)
- [`itemName`](./available-filters/order-summary-items.md#itemname)
- [`subtotalPriceFormat`](./available-filters/order-summary-items.md#subtotalpriceformat)
The following screenshot shows which parts the individual filters affect:
![Order Summary Items](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-26-at-16.29.45.png)
## Totals Footer Item filter
The following [Totals Footer Item filter](./available-filters/totals-footer-item.md) is available:
- [`totalLabel`](./available-filters/totals-footer-item.md#totallabel)
- [`totalValue`](./available-filters/totals-footer-item.md#totalvalue)
## Checkout and place order button filters
The following [Checkout and place order button filters](./available-filters/checkout-and-place-order-button.md) are available:
- [`proceedToCheckoutButtonLabel`](./available-filters/checkout-and-place-order-button.md#proceedtocheckoutbuttonlabel)
- [`proceedToCheckoutButtonLink`](./available-filters/checkout-and-place-order-button.md#proceedtocheckoutbuttonlink)
- [`placeOrderButtonLabel`](./available-filters/checkout-and-place-order-button.md#placeorderbuttonlabel)
## Coupon filters
The following [Coupon filters](./available-filters/coupons.md) are available:
- [`coupons`](./available-filters/coupons.md#coupons-1)
- [`showApplyCouponNotice`](./available-filters/coupons.md#showapplycouponnotice)
- [`showRemoveCouponNotice`](./available-filters/coupons.md#showremovecouponnotice)
## Additional Cart and Checkout inner block types filter
The following [Additional Cart and Checkout inner block types filter](./available-filters/additional-cart-checkout-inner-block-types.md) is available:
- [`additionalCartCheckoutInnerBlockTypes`](./available-filters/additional-cart-checkout-inner-block-types.md#additionalcartcheckoutinnerblocktypes)
## Combined filters
Filters can also be combined. The following example shows how to combine some of the available filters.
```tsx
const { registerCheckoutFilters } = window.wc.blocksCheckout;
const isOrderSummaryContext = ( args ) => args?.context === 'summary';
const modifyCartItemClass = ( defaultValue, extensions, args ) => {
if ( isOrderSummaryContext( args ) ) {
return 'my-custom-class';
}
return defaultValue;
};
const modifyCartItemPrice = ( defaultValue, extensions, args ) => {
if ( isOrderSummaryContext( args ) ) {
return '<price/> for all items';
}
return defaultValue;
};
const modifyItemName = ( defaultValue, extensions, args ) => {
if ( isOrderSummaryContext( args ) ) {
return `🪴 ${ defaultValue } 🪴`;
}
return defaultValue;
};
const modifySubtotalPriceFormat = ( defaultValue, extensions, args ) => {
if ( isOrderSummaryContext( args ) ) {
return '<price/> per item';
}
return defaultValue;
};
registerCheckoutFilters( 'example-extension', {
cartItemClass: modifyCartItemClass,
cartItemPrice: modifyCartItemPrice,
itemName: modifyItemName,
subtotalPriceFormat: modifySubtotalPriceFormat,
} );
```
## Troubleshooting
If you are logged in to the store as an administrator, you should be shown an error like this if your filter is not
working correctly. The error will also be shown in your console.
![Troubleshooting](https://woocommerce.com/wp-content/uploads/2023/10/Screenshot-2023-10-30-at-10.52.53.png)

View File

@ -1,16 +0,0 @@
# Checkout Flow and Events
To see the Checkout Flow and Events please consult the following document:
[Checkout Flow and Events](../../../../docs/internal-developers/block-client-apis/checkout/checkout-flow-and-events.md)
<!-- FEEDBACK -->
---
[We're hiring!](https://woocommerce.com/careers/) Come work with us!
🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/third-party-developers/extensibility/checkout-payment-methods/checkout-flow-and-events.md)
<!-- /FEEDBACK -->

View File

@ -0,0 +1,4 @@
Significance: minor
Type: dev
move part of checkout docs to main docs folder