onPaymentProcessing->onPaymentSetup (https://github.com/woocommerce/woocommerce-blocks/pull/11578)
* onPaymentProcessing->onPaymentSetup * Missed a billingAddress
This commit is contained in:
Mike Jolley
GitHub
parent
df27cbac96
commit
6d24efe009
|
|
@ -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 || '' );
|
||||
};
|
||||
|
|
|
|||
|
|
@ -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 ] );
|
||||
};
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -86,7 +86,7 @@ usePaymentProcessing(
|
|||
emitResponse,
|
||||
sourceId,
|
||||
setSourceId,
|
||||
onPaymentProcessing,
|
||||
onPaymentSetup,
|
||||
eventRegistration
|
||||
);
|
||||
```
|
||||
|
|
@ -102,7 +102,7 @@ export const usePaymentProcessing = (
|
|||
emitResponse,
|
||||
sourceId,
|
||||
setSourceId,
|
||||
onPaymentProcessing,
|
||||
onPaymentSetup,
|
||||
eventRegistration
|
||||
) => {
|
||||
...
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
<!-- /FEEDBACK -->
|
||||
|
||||
|
|
|
|||
|
|
@ -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 >;
|
||||
|
|
|
|||
|
|
@ -99,7 +99,7 @@ canMakePayment( {
|
|||
cartTotals: CartTotals,
|
||||
cartNeedsShipping: boolean,
|
||||
shippingAddress: CartShippingAddress,
|
||||
billingData: BillingData,
|
||||
billingAddress: CartBillingAddress,
|
||||
selectedShippingMethods: Record<string,unknown>,
|
||||
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. | <ul><li>`ValidationInputError`: a container for holding validation errors which typically you'll include after any inputs</li><li>[`PaymentMethodLabel`](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/e089ae17043fa525e8397d605f0f470959f2ae95/assets/js/payment-method-extensions/payment-methods/paypal/index.js#L37-L40): use this component for the payment method label, including an optional icon</li><li>`PaymentMethodIcons`: a React component used for displaying payment method icons</li><li>`LoadingMask`: a wrapper component that handles displaying a loading state when the isLoading prop is true. Exposes the [LoadingMask component](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/c9074a4941919987dbad16a80f358b960336a09d/assets/js/base/components/loading-mask/index.js) </li></ul> |
|
||||
| `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. | <ul><li>`noticeContexts`: This is an object containing properties referencing areas where notices can be targeted in the checkout. The object has the following properties: <ul><li>`PAYMENTS`: This is a reference to the notice area in the payment methods step.</li><li>`EXPRESS_PAYMENTS`: This is a reference to the notice area in the express payment methods step.</li></ul></li><li>`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).</li></ul> |
|
||||
| `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 | - |
|
||||
|
|
|
|||
Loading…
Reference in New Issue