From 6d24efe00945c694d1bacd40588054b8a4fdba6c Mon Sep 17 00:00:00 2001 From: Mike Jolley Date: Thu, 9 Nov 2023 11:47:49 +0000 Subject: [PATCH] onPaymentProcessing->onPaymentSetup (https://github.com/woocommerce/woocommerce-blocks/pull/11578) * onPaymentProcessing->onPaymentSetup * Missed a billingAddress --- .../checkout/checkout-api.md | 9 ++--- .../checkout/checkout-flow-and-events.md | 35 +++++++++++-------- .../testing/cart-checkout/data-stores.md | 4 +-- .../available-filters/cart-line-items.md | 2 +- .../available-filters/order-summary-items.md | 2 +- .../available-filters/totals-footer-item.md | 2 +- .../how-checkout-processes-an-order.md | 5 ++- .../filtering-payment-methods.md | 2 +- .../payment-method-integration.md | 6 ++-- 9 files changed, 36 insertions(+), 31 deletions(-) diff --git a/plugins/woocommerce-blocks/docs/internal-developers/block-client-apis/checkout/checkout-api.md b/plugins/woocommerce-blocks/docs/internal-developers/block-client-apis/checkout/checkout-api.md index 58b9e93b14b..8b7e143369b 100644 --- a/plugins/woocommerce-blocks/docs/internal-developers/block-client-apis/checkout/checkout-api.md +++ b/plugins/woocommerce-blocks/docs/internal-developers/block-client-apis/checkout/checkout-api.md @@ -95,7 +95,8 @@ The shipping method data context exposes the api interfaces for the following th The payment method events context exposes any event handlers related to payments (typedef `PaymentEventsContext`) via the `usePaymentEventsContext` hook. -- `onPaymentProcessing`: This is an event subscriber that can be used to subscribe observers to be called when the status for the context is `PROCESSING`. +- `onPaymentSetup`: This is an event subscriber that can be used to subscribe observers to be called when the payment is being setup. +- ~~`onPaymentProcessing`~~: This event was deprecated in favour of `onPaymentSetup`. ### Checkout Events Context @@ -151,9 +152,9 @@ Payment method components are passed, by default, everything from the [`usePayme ```js const Content = ( props ) => { const { eventRegistration, emitResponse } = props; - const { onPaymentProcessing } = eventRegistration; + const { onPaymentSetup } = eventRegistration; useEffect( () => { - const unsubscribe = onPaymentProcessing( async () => { + const unsubscribe = onPaymentSetup( async () => { // Here we can do any processing we need, and then emit a response. // For example, we might validate a custom field, or perform an AJAX request, and then emit a response indicating it is valid or not. const myGatewayCustomData = '12345'; @@ -182,7 +183,7 @@ const Content = ( props ) => { }, [ emitResponse.responseTypes.ERROR, emitResponse.responseTypes.SUCCESS, - onPaymentProcessing, + onPaymentSetup, ] ); return decodeEntities( settings.description || '' ); }; diff --git a/plugins/woocommerce-blocks/docs/internal-developers/block-client-apis/checkout/checkout-flow-and-events.md b/plugins/woocommerce-blocks/docs/internal-developers/block-client-apis/checkout/checkout-flow-and-events.md index 6a1a104b99f..606712730f2 100644 --- a/plugins/woocommerce-blocks/docs/internal-developers/block-client-apis/checkout/checkout-flow-and-events.md +++ b/plugins/woocommerce-blocks/docs/internal-developers/block-client-apis/checkout/checkout-flow-and-events.md @@ -4,13 +4,14 @@ - [General Concepts](#general-concepts) - [Tracking flow through status](#tracking-flow-through-status) - - [Checkout Data Store Status](#checkout-data-store-status) - - [Special States:](#special-states) + - [Checkout Data Store Status](#checkout-data-store-status) + - [Special States](#special-states) - [`ShippingProvider` Exposed Statuses](#shippingprovider-exposed-statuses) - [Payment Method Data Store Status](#payment-method-data-store-status) - [Emitting Events](#emitting-events) - [`onCheckoutValidation`](#oncheckoutvalidation) - - [`onPaymentProcessing`](#onpaymentprocessing) + - [~~`onPaymentProcessing`~~](#onpaymentprocessing) + - [`onPaymentSetup`](#onpaymentsetup) - [Success](#success) - [Fail](#fail) - [Error](#error) @@ -252,9 +253,13 @@ const PaymentMethodComponent = ( { eventRegistration } ) => { }; ``` -### `onPaymentProcessing` +### ~~`onPaymentProcessing`~~ -This event emitter is 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 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. @@ -271,10 +276,10 @@ 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. -- `billingData`: 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](../../../../assets/js/types/type-defs/billing.js). -- `shippingData`: 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-gutenberg-products-block/blob/34e17c3622637dbe8b02fac47b5c9b9ebf9e3596/assets/js/type-defs/cart.js#L20-L32). +- `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](../../../../assets/js/settings/shared/default-address-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](../../../../assets/js/settings/shared/default-address-fields.ts). -If `billingData` or `shippingData` properties aren't in the response object, then the state for the data is left alone. +If `billingAddress` or `shippingAddress` properties aren't in the response object, then the state for the data is left alone. #### Fail @@ -289,7 +294,7 @@ When a fail response is returned by an observer, the payment method context stat - `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). -- `billingData`: (same as for success responses). +- `billingAddress`: (same as for success responses). #### Error @@ -319,11 +324,11 @@ import { usePaymentEventsContext } from '@woocommerce/base-contexts'; import { useEffect } from '@wordpress/element'; const Component = () => { - const { onPaymentProcessing } = usePaymentEventsContext(); + const { onPaymentSetup } = usePaymentEventsContext(); useEffect( () => { - const unsubscribe = onPaymentProcessing( () => true ); + const unsubscribe = onPaymentSetup( () => true ); return unsubscribe; - }, [ onPaymentProcessing ] ); + }, [ onPaymentSetup ] ); return null; }; ``` @@ -334,11 +339,11 @@ _For registered payment method components:_ const { useEffect } = window.wp.element; const PaymentMethodComponent = ( { eventRegistration } ) => { - const { onPaymentMethodProcessing } = eventRegistration; + const { onPaymentSetup } = eventRegistration; useEffect( () => { - const unsubscribe = onPaymentMethodProcessing( () => true ); + const unsubscribe = onPaymentSetup( () => true ); return unsubscribe; - }, [ onPaymentMethodProcessing ] ); + }, [ onPaymentSetup ] ); }; ``` diff --git a/plugins/woocommerce-blocks/docs/internal-developers/testing/cart-checkout/data-stores.md b/plugins/woocommerce-blocks/docs/internal-developers/testing/cart-checkout/data-stores.md index f100b7f5e50..4cb99b15995 100644 --- a/plugins/woocommerce-blocks/docs/internal-developers/testing/cart-checkout/data-stores.md +++ b/plugins/woocommerce-blocks/docs/internal-developers/testing/cart-checkout/data-stores.md @@ -86,7 +86,7 @@ usePaymentProcessing( emitResponse, sourceId, setSourceId, - onPaymentProcessing, + onPaymentSetup, eventRegistration ); ``` @@ -102,7 +102,7 @@ export const usePaymentProcessing = ( emitResponse, sourceId, setSourceId, - onPaymentProcessing, + onPaymentSetup, eventRegistration ) => { ... diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/cart-line-items.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/cart-line-items.md index 43b8d19be03..4d5b7bcccf8 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/cart-line-items.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/cart-line-items.md @@ -572,7 +572,7 @@ The Cart object of the filters above has the following keys: - _phone_ `string` - The phone of the address. - _postcode_ `string` - The postcode of the address. - _state_ `string` - The state of the address. -- _billingData_ `object` - The billing data object with the same keys as the `billingAddress` object. +- ~~_billingData_~~ `object` - The billing data object with the same keys as the `billingAddress` object. - _cartCoupons_ `array` - The cart coupons array. - _cartErrors_ `array` - The cart errors array. - _cartFees_ `array` - The cart fees array. diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/order-summary-items.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/order-summary-items.md index 36bbbda4aed..3fd4260fd36 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/order-summary-items.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/order-summary-items.md @@ -388,7 +388,7 @@ The Cart object of the filters above has the following keys: - _phone_ `string` - The phone of the address. - _postcode_ `string` - The postcode of the address. - _state_ `string` - The state of the address. -- _billingData_ `object` - The billing data object with the same keys as the `billingAddress` object. +- ~~_billingData_~~ `object` - The billing data object with the same keys as the `billingAddress` object. - _cartCoupons_ `array` - The cart coupons array. - _cartErrors_ `array` - The cart errors array. - _cartFees_ `array` - The cart fees array. diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/totals-footer-item.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/totals-footer-item.md index cd328d09a4d..21764730dee 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/totals-footer-item.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/available-filters/totals-footer-item.md @@ -73,7 +73,7 @@ The Cart object of the filters above has the following keys: - _phone_ `string` - The phone of the address. - _postcode_ `string` - The postcode of the address. - _state_ `string` - The state of the address. -- _billingData_ `object` - The billing data object with the same keys as the `billingAddress` object. +- ~~_billingData_~~ `object` - The billing data object with the same keys as the `billingAddress` object. - _cartCoupons_ `array` - The cart coupons array. - _cartErrors_ `array` - The cart errors array. - _cartFees_ `array` - The cart fees array. diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/how-checkout-processes-an-order.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/how-checkout-processes-an-order.md index 7aba8f5d4ac..1fb6d09d7ee 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/how-checkout-processes-an-order.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-block/how-checkout-processes-an-order.md @@ -16,10 +16,10 @@ Data stores are used to keep track of data that is likely to change during a use ### Contexts -Contexts are used to make data available to the Checkout block. Each of these provide data and functions related to a specific area of concern, via the use of a hook. For example, if we wanted to use the `onPaymentProcessing` handler from the `PaymentEventsContext` context, we can do it like this: +Contexts are used to make data available to the Checkout block. Each of these provide data and functions related to a specific area of concern, via the use of a hook. For example, if we wanted to use the `onPaymentSetup` handler from the `PaymentEventsContext` context, we can do it like this: ```js -const { onPaymentProcessing } = usePaymentEventsContext(); +const { onPaymentSetup } = usePaymentEventsContext(); ``` The other job of contexts is to run side effects for our Checkout block. What typically happens is that the `CheckoutEvents` and `PaymentEvents` will listen for changes in the checkout and payment data stores, and dispatch actions on those stores based on some logic. @@ -145,4 +145,3 @@ The `checkPaymentMethodsCanPay()` [function](https://github.com/woocommerce/wooc 🐞 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-block/how-checkout-processes-an-order.md) - diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-payment-methods/filtering-payment-methods.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-payment-methods/filtering-payment-methods.md index aa3d6bff0b3..d6bb1972a37 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-payment-methods/filtering-payment-methods.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-payment-methods/filtering-payment-methods.md @@ -90,7 +90,7 @@ interface CanMakePaymentArgument { cart: Cart; cartTotals: CartTotals; cartNeedsShipping: boolean; - billingData: CartResponseBillingAddress; + billingAddress: CartResponseBillingAddress; shippingAddress: CartResponseShippingAddress; selectedShippingMethods: Record< string, unknown >; paymentRequirements: Array< string >; diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-payment-methods/payment-method-integration.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-payment-methods/payment-method-integration.md index 93d8c84f1de..d9bc0ec2901 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-payment-methods/payment-method-integration.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/checkout-payment-methods/payment-method-integration.md @@ -99,7 +99,7 @@ canMakePayment( { cartTotals: CartTotals, cartNeedsShipping: boolean, shippingAddress: CartShippingAddress, - billingData: BillingData, + billingAddress: CartBillingAddress, selectedShippingMethods: Record, paymentRequirements: string[], } ) @@ -164,12 +164,12 @@ A big part of the payment method integration is the interface that is exposed fo | Property | Type | Description | Values | | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `activePaymentMethod` | String | The slug of the current active payment method in the checkout. | - | -| `billing` | Object | Contains everything related to billing. | `billingData`, `cartTotal`, `currency`, `cartTotalItems`, `displayPricesIncludingTax`, `appliedCoupons`, `customerId` | +| `billing` | Object | Contains everything related to billing. | `billingAddress`, `cartTotal`, `currency`, `cartTotalItems`, `displayPricesIncludingTax`, `appliedCoupons`, `customerId` | | `cartData` | Object | Data exposed from the cart including items, fees, and any registered extension data. Note that this data should be treated as immutable (should not be modified/mutated) or it will result in errors in your application. | `cartItems`, `cartFees`, `extensions` | | `checkoutStatus` | Object | The current checkout status exposed as various boolean state. | `isCalculating`, `isComplete`, `isIdle`, `isProcessing` | | `components` | Object | It exposes React components that can be implemented by your payment method for various common interface elements used by payment methods. | | | `emitResponse` | Object | Contains some constants that can be helpful when using the event emitter. Read the _[Emitting Events](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/e267cd96a4329a4eeef816b2ef627e113ebb72a5/docs/extensibility/checkout-flow-and-events.md#emitting-events)_ section for more details. | | -| `eventRegistration` | object | Contains all the checkout event emitter registration functions. These are functions the payment method can register observers on to interact with various points in the checkout flow (see [this doc](./checkout-flow-and-events.md) for more info). | `onCheckoutValidation`, `onCheckoutSuccess`, `onCheckoutFail`, `onPaymentProcessing`, `onShippingRateSuccess`, `onShippingRateFail`, `onShippingRateSelectSuccess`, `onShippingRateSelectFail` | +| `eventRegistration` | object | Contains all the checkout event emitter registration functions. These are functions the payment method can register observers on to interact with various points in the checkout flow (see [this doc](./checkout-flow-and-events.md) for more info). | `onCheckoutValidation`, `onCheckoutSuccess`, `onCheckoutFail`, `onPaymentSetup`, `onShippingRateSuccess`, `onShippingRateFail`, `onShippingRateSelectSuccess`, `onShippingRateSelectFail` | | `onClick` | Function | **Provided to express payment methods** that should be triggered when the payment method button is clicked (which will signal to checkout the payment method has taken over payment processing) | - | | `onClose` | Function | **Provided to express payment methods** that should be triggered when the express payment method modal closes and control is returned to checkout. | - | | `onSubmit` | Function | Submits the checkout and begins processing | - |