Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add missing actions to data store documentation (https://github.com/woocommerce/woocommerce-blocks/pull/11986) 

* Add missing actions to the documentation

- Add the missing actions to the following:

- data-store/cart
- data-store/checkout
- data-store/collections
- data-store/validation

* Move actions above selectors in Cart doc

* Add more info to cart actions

* Fix syntax of Cart actions examples

* Fix syntax and examples

- Use store name constant instead of strings
- Fix description and examples of collections document

* Add more info about the keys of objects and arrays

* Update billing address info in cart data

* Update parameter names and descriptions in
checkout.md and collections.md

* Update docs/third-party-developers/extensibility/data-store/checkout.md

Co-authored-by: Niels Lange <info@nielslange.de>

---------

Co-authored-by: Niels Lange <info@nielslange.de>
This commit is contained in:
Tarun Vijwani 2023-12-06 12:58:25 +04:00 committed by GitHub
parent 69ef1b96e8
commit 1879839657
4 changed files with 647 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

562
plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/cart.md
View File

@ -10,6 +10,28 @@
- [Overview](#overview) - [Overview](#overview)
- [Usage](#usage) - [Usage](#usage)
- [Actions](#actions)
- [setCartData](#setcartdata)
- [setErrorData](#seterrordata)
- [receiveCartContents](#receivecartcontents)
- [receiveApplyingCoupon](#receiveapplyingcoupon)
- [receiveRemovingCoupon](#receiveremovingcoupon)
- [receiveCartItem](#receivecartitem)
- [itemIsPendingQuantity](#itemispendingquantity)
- [itemIsPendingDelete](#itemispendingdelete)
- [setIsCartDataStale](#setiscartdatastale)
- [updatingCustomerData](#updatingcustomerdata)
- [shippingRatesBeingSelected](#shippingratesbeingselected)
- [applyExtensionCartUpdate](#applyextensioncartupdate)
- [applyCoupon](#applycoupon)
- [removeCoupon](#removecoupon)
- [addItemToCart](#additemtocart)
- [removeItemFromCart](#removeitemfromcart)
- [changeCartItemQuantity](#changecartitemquantity)
- [selectShippingRate](#selectshippingrate)
- [setBillingAddress](#setbillingaddress)
- [setShippingAddress](#setshippingaddress)
- [updateCustomerData](#updatecustomerdata)
- [Selectors](#selectors) - [Selectors](#selectors)
- [getCartData](#getcartdata) - [getCartData](#getcartdata)
- [getCustomerData](#getcustomerdata) - [getCustomerData](#getcustomerdata)
@ -44,6 +66,489 @@ To utilize this store you will import the `CART_STORE_KEY` in any module referen
const { CART_STORE_KEY } = window.wc.wcBlocksData; const { CART_STORE_KEY } = window.wc.wcBlocksData;
``` ```
## Actions
### setCartData
This action is used to set the cart data in the store.
#### _Parameters_ <!-- omit in toc -->
- _cartData_ `object`: The current cart data with the following keys:
- _coupons_ `array`: The coupon items in the cart.
- _shippingRates_ `array`: The cart shipping rates (see `getShippingRates` selector).
- _shippingAddress_ `object`: The shipping address (see `getCustomerData` selector).
- _billingAddress_ `object`: The billing address (see `getCustomerData` selector).
- _items_ `array`: The cart items.
- _itemsCount_ `number`: The total number of items in the cart
- _itemsWeight_ `number`: The total weight of items in the cart.
- _crossSells_ `array`: The cross sells items.
- _needsPayment_ `boolean`: If the cart needs payment.
- _needsShipping_ `boolean`: If the cart needs shipping.
- _hasCalculatedShipping_ `boolean`: If the cart has calculated shipping.
- _fees_ `array`: The cart fees.
- _totals_ `object`: The cart totals (see `getCartTotals` selector).
- _errors_ `array`: The cart errors (see `getCartErrors` selector).
- _paymentRequirements_ `object`: The payment requirements for the cart.
- _extensions_ `object`: The extensions data.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( setCartData( newCartData ) );
```
### setErrorData
This action is used to set the error data in the store.
#### _Parameters_ <!-- omit in toc -->
- _errorData_ `object`: The error data that needs to be set in the store.
- _code_ `string`: The error code.
- _message_ `string`: The error message.
- _data_ `object`: Additional error data. This is an optional object with the following keys:
- _status_ `number`: The error status.
- _params_ `string`: The error params.
- _message_ `string`: The error message.
- _cart_ `object`: The cart data. This is an optional object with the following keys:
- _coupons_ `array`: The coupon items in the cart.
- _shippingRates_ `array`: The cart shipping rates (see `getShippingRates` selector).
- _shippingAddress_ `object`: The shipping address (see `getCustomerData` selector).
- _billingAddress_ `object`: The billing address (see `getCustomerData` selector).
- _items_ `array`: The cart items.
- _itemsCount_ `number`: The total number of items in the cart
- _itemsWeight_ `number`: The total weight of items in the cart.
- _crossSells_ `array`: The cross sells items.
- _needsPayment_ `boolean`: If the cart needs payment.
- _needsShipping_ `boolean`: If the cart needs shipping.
- _hasCalculatedShipping_ `boolean`: If the cart has calculated shipping.
- _fees_ `array`: The cart fees.
- _totals_ `object`: The cart totals (see `getCartTotals` selector).
- _errors_ `array`: The cart errors (see `getCartErrors` selector).
- _paymentRequirements_ `object`: The payment requirements for the cart.
- _extensions_ `object`: The extensions data.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( setErrorData( newErrorData ) );
```
### receiveCartContents
This action returns an action object used in updating the store with the provided cart. It omits the customer addresses so that only updates to cart items and totals are received.
#### _Parameters_ <!-- omit in toc -->
- _cartContents_ `object`: A cart contents API response.
- _coupons_ `array`: The coupon items in the cart.
- _shippingRates_ `array`: The cart shipping rates (see `getShippingRates` selector).
- _shippingAddress_ `object`: The shipping address (see `getCustomerData` selector).
- _billingAddress_ `object`: The billing address (see `getCustomerData` selector).
- _items_ `array`: The cart items.
- _itemsCount_ `number`: The total number of items in the cart
- _itemsWeight_ `number`: The total weight of items in the cart.
- _crossSells_ `array`: The cross sells items.
- _needsPayment_ `boolean`: If the cart needs payment.
- _needsShipping_ `boolean`: If the cart needs shipping.
- _hasCalculatedShipping_ `boolean`: If the cart has calculated shipping.
- _fees_ `array`: The cart fees.
- _totals_ `object`: The cart totals (see `getCartTotals` selector).
- _errors_ `array`: The cart errors (see `getCartErrors` selector).
- _paymentRequirements_ `object`: The payment requirements for the cart.
- _extensions_ `object`: The extensions data.
#### _Returns_ <!-- omit in toc -->
- `object`: The action object with the following keys:
- _type_ `string`: The action type.
- _cartContents_ `object`: The cart contents with the following keys:
- _coupons_ `array`: The coupon items in the cart.
- _shippingRates_ `array`: The cart shipping rates (see `getShippingRates` selector).
- _items_ `array`: The cart items.
- _itemsCount_ `number`: The total number of items in the cart
- _itemsWeight_ `number`: The total weight of items in the cart.
- _crossSells_ `array`: The cross sells items.
- _needsPayment_ `boolean`: If the cart needs payment.
- _needsShipping_ `boolean`: If the cart needs shipping.
- _hasCalculatedShipping_ `boolean`: If the cart has calculated shipping.
- _fees_ `array`: The cart fees.
- _totals_ `object`: The cart totals (see `getCartTotals` selector).
- _errors_ `array`: The cart errors (see `getCartErrors` selector).
- _paymentRequirements_ `object`: The payment requirements for the cart.
- _extensions_ `object`: The extensions data.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( receiveCartContents( newCartContents ) );
```
### receiveApplyingCoupon
This action returns an action object used to track when a coupon is applying.
#### _Parameters_ <!-- omit in toc -->
- _couponCode_ `string`: The code of the coupon being applied.
#### _Returns_ <!-- omit in toc -->
- `object`: The action object with following keys:
- _type_ `string`: The action type.
- _couponCode_ `string`: The code of the coupon being applied.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( receiveApplyingCoupon( couponCode ) );
```
### receiveRemovingCoupon
This action returns an action object used to track when a coupon is removing.
#### _Parameters_ <!-- omit in toc -->
- _couponCode_ `string`: The code of the coupon being removed.
#### _Returns_ <!-- omit in toc -->
- `object`: The action object with the following keys:
- _type_ `string`: The action type.
- _couponCode_ `string`: The code of the coupon being removed.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( receiveRemovingCoupon( couponCode ) );
```
### receiveCartItem
This action is used to update a specific item in the cart.
#### _Parameters_ <!-- omit in toc -->
- _cartResponseItem_ `object`: Cart response object with the following keys:
- _cartItem_ `object`: The cart item (see `getCartItem` selector).
#### _Returns_ <!-- omit in toc -->
- `object`: The action object with the following keys:
- _type_ `string`: The action type.
- _cartItem_ `object`: The cart item (see `getCartItem` selector).
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( receiveCartItem( CartResponseItem ) );
```
### itemIsPendingQuantity
This action returns an action object to indicate if the specified cart item quantity is being updated.
#### _Parameters_ <!-- omit in toc -->
- _cartItemKey_ `string`: The key of the cart item.
- _isPending_ `boolean` (default: `true`): Whether the cart item quantity is being updated.
#### _Returns_ <!-- omit in toc -->
- `object`: The action object with following keys:
- _type_ `string`: The action type.
- _cartItemKey_ `string`: The key of the cart item.
- _isPending_ `boolean`: Whether the cart item quantity is being updated.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( itemIsPendingQuantity( cartItemKey, isPending ) );
```
### itemIsPendingDelete
This action returns an action object to indicate if the specified cart item is being deleted.
#### _Parameters_ <!-- omit in toc -->
- _cartItemKey_ `string`: The key of the cart item.
- _isPending_ `boolean` (default: `true`): Whether the cart item is being deleted.
#### _Returns_ <!-- omit in toc -->
- `object`: The action object with the following keys:
- _type_ `string`: The action type.
- _cartItemKey_ `string`: The key of the cart item.
- _isPending_ `boolean`: Whether the cart item is being deleted.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( itemIsPendingDelete( cartItemKey, isPending ) );
```
### setIsCartDataStale
This action returns an action object to indicate if the cart data is stale.
#### _Parameters_ <!-- omit in toc -->
- _isCartDataStale_ `boolean` (default: `true`): Flag to mark cart data as stale; true if `lastCartUpdate` timestamp is newer than the one in wcSettings.
#### _Returns_ <!-- omit in toc -->
- `object`: The action object with the following keys:
- _type_ `string`: The action type.
- _isCartDataStale_ `boolean`: Flag to mark cart data as stale; true if `lastCartUpdate` timestamp is newer than the one in wcSettings.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( setIsCartDataStale( isCartDataStale ) );
```
### updatingCustomerData
This action returns an action object to indicate if the customer data is being updated.
#### _Parameters_ <!-- omit in toc -->
- _isResolving_ `boolean`: Whether the customer data is being updated.
#### _Returns_ <!-- omit in toc -->
- `object`: The action object with the following keys:
- _type_ `string`: The action type.
- _isResolving_ `boolean`: Whether the customer data is being updated.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( updatingCustomerData( isResolving ) );
```
### shippingRatesBeingSelected
This action returns an action object to indicate if the shipping rates are being selected.
#### _Parameters_ <!-- omit in toc -->
- _isResolving_ `boolean`: True if shipping rate is being selected.
#### _Returns_ <!-- omit in toc -->
- `object`: The action object with the following keys:
- _type_ `string`: The action type.
- _isResolving_ `boolean`: True if shipping rate is being selected.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( shippingRatesBeingSelected( isResolving ) );
```
### applyExtensionCartUpdate
This action is used to send POSTs request to the /cart/extensions endpoint with the data supplied by the extension.
#### _Parameters_ <!-- omit in toc -->
- _args_ `object`: The arguments for the request with the following keys:
- _extensionId_ `string`: The extension ID.
- _data_ `object`: The data to send to the endpoint with the following keys:
- _key_ `string`: The key of the extension.
- _value_ `string`: The value of the extension.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( applyExtensionCartUpdate( args ) );
```
### applyCoupon
This action is used to apply a coupon to the cart.
#### _Parameters_ <!-- omit in toc -->
- _couponCode_ `string`: The code of the coupon to apply.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( applyCoupon( couponCode ) );
```
### removeCoupon
This action is used to remove a coupon from the cart.
#### _Parameters_ <!-- omit in toc -->
- _couponCode_ `string`: The code of the coupon to remove.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( removeCoupon( couponCode ) );
```
### addItemToCart
This action is used to add an item to the cart.
#### _Parameters_ <!-- omit in toc -->
- _productId_ `number`: Product ID to add to cart.
- _quantity_ `number` (default: `1`): The quantity of the product to add.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( addItemToCart( productId, quantity ) );
```
### removeItemFromCart
This action is used to remove an item from the cart.
#### _Parameters_ <!-- omit in toc -->
- _cartItemKey_ `string`: Cart item being updated.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( removeItemFromCart( cartItemKey ) );
```
### changeCartItemQuantity
This action is used to change the quantity of an item in the cart.
#### _Parameters_ <!-- omit in toc -->
- _cartItemKey_ `string`: Cart item being updated.
- _quantity_ `number`: Quantity of the item.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( changeCartItemQuantity( cartItemKey, quantity ) );
```
### selectShippingRate
This action is used to select a shipping rate for the cart.
#### _Parameters_ <!-- omit in toc -->
- _rateId_ `string`: The ID of the shipping rate to select.
- _packageId_ `number | string` (default: `null`): The key of the packages that will select within the shipping rate.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( selectShippingRate( rateId, packageId ) );
```
### setBillingAddress
This action is used to set the billing address for the cart locally, as opposed to updateCustomerData which sends it to the server.
#### _Parameters_ <!-- omit in toc -->
- _billingAddress_ `object`: Billing address that needs to be set. The keys are as following:
- _first_name_ `string`: The first name.
- _last_name_ `string`: The last name.
- _company_ `string`: The company name.
- _address_1_ `string`: The address line 1.
- _address_2_ `string`: The address line 2.
- _city_ `string`: The city name.
- _state_ `string`: The state name.
- _postcode_ `string`: The postcode.
- _country_ `string`: The country name.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( setBillingAddress( billingAddress ) );
```
### setShippingAddress
This action is used to set the shipping address for the cart locally, as opposed to updateCustomerData which sends it to the server.
#### _Parameters_ <!-- omit in toc -->
- _shippingAddress_ `object`: Shipping address that needs to be set. The keys are as following:
- _first_name_ `string`: The first name.
- _last_name_ `string`: The last name.
- _company_ `string`: The company name.
- _address_1_ `string`: The address line 1.
- _address_2_ `string`: The address line 2.
- _city_ `string`: The city name.
- _state_ `string`: The state name.
- _postcode_ `string`: The postcode.
- _country_ `string`: The country name.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( setShippingAddress( shippingAddress ) );
```
### updateCustomerData
This action is used to updates the shipping and/or billing address for the customer and returns an updated cart.
#### _Parameters_ <!-- omit in toc -->
- _customerData_ `object`: Customer billing and shipping address. The keys are as following:
- _shippingAddress_ `object`: The shipping address with the following keys:
- _first_name_ `string`: The first name.
- _last_name_ `string`: The last name.
- _company_ `string`: The company name.
- _address_1_ `string`: The address line 1.
- _address_2_ `string`: The address line 2.
- _city_ `string`: The city name.
- _state_ `string`: The state name.
- _postcode_ `string`: The postcode.
- _country_ `string`: The country name.
- _billingAddress_ `object`: The billing address (same keys as shipping address).
- `editing: boolean` (default: `true`): If the address is being edited, we don't update the customer data in the store from the response.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( CART_STORE_KEY );
dispatch( updateCustomerData( customerData, editing ) );
```
## Selectors ## Selectors
### getCartData ### getCartData
@ -73,7 +578,7 @@ Returns the Cart data from the state.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const cartData = store.getCartData(); const cartData = store.getCartData();
``` ```
@ -99,7 +604,7 @@ Returns the shipping and billing address from the state.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const customerData = store.getCustomerData(); const customerData = store.getCustomerData();
``` ```
@ -109,12 +614,21 @@ Returns the shipping rates from the state.
#### _Returns_ <!-- omit in toc --> #### _Returns_ <!-- omit in toc -->
- `array`: The shipping rates. - `array`: The shipping rates. They keys are as following:
- _id_ `string`: The shipping rate ID.
- _label_ `string`: The shipping rate label.
- _cost_ `string`: The shipping rate cost.
- _package_id_ `number`: The shipping rate package ID.
- _meta_data_ `array`: The shipping rate meta data. The keys are as following:
- _id_ `number`: The shipping rate meta data ID.
- _key_ `string`: The shipping rate meta data key.
- _value_ `string`: The shipping rate meta data value.
- _taxes_ `array`: The shipping rate taxes.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const shippingRates = store.getShippingRates(); const shippingRates = store.getShippingRates();
``` ```
@ -129,7 +643,7 @@ Queries whether the cart needs shipping.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const needsShipping = store.getNeedsShipping(); const needsShipping = store.getNeedsShipping();
``` ```
@ -144,7 +658,7 @@ Queries whether the cart shipping has been calculated.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const hasCalculatedShipping = store.getHasCalculatedShipping(); const hasCalculatedShipping = store.getHasCalculatedShipping();
``` ```
@ -177,7 +691,7 @@ Returns the cart totals from state.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const cartTotals = store.getCartTotals(); const cartTotals = store.getCartTotals();
``` ```
@ -197,7 +711,7 @@ Returns the cart meta from state.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const cartMeta = store.getCartMeta(); const cartMeta = store.getCartMeta();
``` ```
@ -207,12 +721,16 @@ Returns the cart errors from state if cart receives customer facing errors from
#### _Returns_ <!-- omit in toc --> #### _Returns_ <!-- omit in toc -->
- `array`: The cart errors. - `array`: The cart errors with the following keys:
- _code_ `string`: The error code.
- _message_ `string`: The error message.
- _data_ `object`: API response data.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const cartErrors = store.getCartErrors(); const cartErrors = store.getCartErrors();
``` ```
@ -227,7 +745,7 @@ Queries whether a coupon is being applied.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const isApplyingCoupon = store.isApplyingCoupon(); const isApplyingCoupon = store.isApplyingCoupon();
``` ```
@ -242,7 +760,7 @@ Queries whether the cart data is stale.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const isCartDataStale = store.isCartDataStale(); const isCartDataStale = store.isCartDataStale();
``` ```
@ -257,7 +775,7 @@ Returns the coupon code being applied.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const couponBeingApplied = store.getCouponBeingApplied(); const couponBeingApplied = store.getCouponBeingApplied();
``` ```
@ -272,7 +790,7 @@ Queries whether a coupon is being removed.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const isRemovingCoupon = store.isRemovingCoupon(); const isRemovingCoupon = store.isRemovingCoupon();
``` ```
@ -287,7 +805,7 @@ Returns the coupon code being removed.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const couponBeingRemoved = store.getCouponBeingRemoved(); const couponBeingRemoved = store.getCouponBeingRemoved();
``` ```
@ -346,7 +864,7 @@ Returns a cart item from the state.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const cartItem = store.getCartItem( cartItemKey ); const cartItem = store.getCartItem( cartItemKey );
``` ```
@ -365,7 +883,7 @@ Queries whether a cart item is pending quantity.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const isItemPendingQuantity = store.isItemPendingQuantity( cartItemKey ); const isItemPendingQuantity = store.isItemPendingQuantity( cartItemKey );
``` ```
@ -384,7 +902,7 @@ Queries whether a cart item is pending delete.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const isItemPendingDelete = store.isItemPendingDelete( cartItemKey ); const isItemPendingDelete = store.isItemPendingDelete( cartItemKey );
``` ```
@ -399,7 +917,7 @@ Queries whether the customer data is being updated.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const isCustomerDataUpdating = store.isCustomerDataUpdating(); const isCustomerDataUpdating = store.isCustomerDataUpdating();
``` ```
@ -414,7 +932,7 @@ Queries whether a shipping rate is being selected.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const isShippingRateBeingSelected = store.isShippingRateBeingSelected(); const isShippingRateBeingSelected = store.isShippingRateBeingSelected();
``` ```
@ -429,7 +947,7 @@ Retrieves the item keys for items whose quantity is currently being updated.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const itemsPendingQuantityUpdate = store.getItemsPendingQuantityUpdate(); const itemsPendingQuantityUpdate = store.getItemsPendingQuantityUpdate();
``` ```
@ -444,7 +962,7 @@ Retrieves the item keys for items that are currently being deleted.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/cart' ); const store = select( CART_STORE_KEY );
const itemsPendingDelete = store.getItemsPendingDelete(); const itemsPendingDelete = store.getItemsPendingDelete();
``` ```

51
plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/checkout.md
View File

@ -27,6 +27,8 @@
- [isAfterProcessing](#isafterprocessing) - [isAfterProcessing](#isafterprocessing)
- [isComplete](#iscomplete) - [isComplete](#iscomplete)
- [isCalculating](#iscalculating) - [isCalculating](#iscalculating)
- [Actions](#actions)
- [setPrefersCollection](#setpreferscollection)
## Overview ## Overview
@ -53,7 +55,7 @@ Returns the WordPress user ID of the customer whose order is currently processed
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const customerId = store.getCustomerId(); const customerId = store.getCustomerId();
``` ```
@ -68,7 +70,7 @@ Returns the WooCommerce order ID of the order that is currently being processed
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const orderId = store.getOrderId(); const orderId = store.getOrderId();
``` ```
@ -83,7 +85,7 @@ Returns the order notes.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const orderNotes = store.getOrderNotes(); const orderNotes = store.getOrderNotes();
``` ```
@ -98,7 +100,7 @@ Returns the URL to redirect to after checkout is complete.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const redirectUrl = store.getRedirectUrl(); const redirectUrl = store.getRedirectUrl();
``` ```
@ -121,7 +123,7 @@ Returns the extra data registered by extensions.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const extensionData = store.getExtensionData(); const extensionData = store.getExtensionData();
``` ```
@ -136,7 +138,7 @@ Returns the current status of the checkout process.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const checkoutStatus = store.getCheckoutStatus(); const checkoutStatus = store.getCheckoutStatus();
``` ```
@ -151,7 +153,7 @@ Returns true if the shopper has opted to create an account with their order.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const shouldCreateAccount = store.getShouldCreateAccount(); const shouldCreateAccount = store.getShouldCreateAccount();
``` ```
@ -166,7 +168,7 @@ Returns true if the shopper has opted to use their shipping address as their bil
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const useShippingAsBilling = store.getUseShippingAsBilling(); const useShippingAsBilling = store.getUseShippingAsBilling();
``` ```
@ -181,7 +183,7 @@ Returns true if an error occurred, and false otherwise.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const hasError = store.hasError(); const hasError = store.hasError();
``` ```
@ -196,7 +198,7 @@ Returns true if a draft order had been created, and false otherwise.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const hasOrder = store.hasOrder(); const hasOrder = store.hasOrder();
``` ```
@ -211,7 +213,7 @@ When the checkout status is `IDLE` this flag is true. Checkout will be this stat
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const isIdle = store.isIdle(); const isIdle = store.isIdle();
``` ```
@ -226,7 +228,7 @@ When the checkout status is `BEFORE_PROCESSING` this flag is true. Checkout will
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const isBeforeProcessing = store.isBeforeProcessing(); const isBeforeProcessing = store.isBeforeProcessing();
``` ```
@ -241,7 +243,7 @@ When the checkout status is `PROCESSING` this flag is true. Checkout will be thi
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const isProcessing = store.isProcessing(); const isProcessing = store.isProcessing();
``` ```
@ -256,7 +258,7 @@ When the checkout status is `AFTER_PROCESSING` this flag is true. Checkout will
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const isAfterProcessing = store.isAfterProcessing(); const isAfterProcessing = store.isAfterProcessing();
``` ```
@ -271,7 +273,7 @@ When the checkout status is `COMPLETE` this flag is true. Checkout will have thi
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const isComplete = store.isComplete(); const isComplete = store.isComplete();
``` ```
@ -286,10 +288,27 @@ This is true when the total is being re-calculated for the order. There are nume
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/checkout' ); const store = select( CHECKOUT_STORE_KEY );
const isCalculating = store.isCalculating(); const isCalculating = store.isCalculating();
``` ```
## Actions
### setPrefersCollection
Sets the `prefersCollection` flag to true or false.
#### _Parameters_ <!-- omit in toc -->
- _prefersCollection_ `boolean`: True if the shopper prefers to collect their order.
#### _Example_ <!-- omit in toc -->
```js
const store = dispatch( CHECKOUT_STORE_KEY );
store.setPrefersCollection( true );
```
<!-- FEEDBACK --> <!-- FEEDBACK -->
--- ---

49
plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/collections.md
View File

@ -6,6 +6,8 @@
- [Usage](#usage) - [Usage](#usage)
- [Actions](#actions) - [Actions](#actions)
- [receiveCollection( namespace, resourceName, queryString, ids = \[\], items = \[\], replace = false )](#receivecollection-namespace-resourcename-querystring-ids---items---replace--false-) - [receiveCollection( namespace, resourceName, queryString, ids = \[\], items = \[\], replace = false )](#receivecollection-namespace-resourcename-querystring-ids---items---replace--false-)
- [receiveCollectionError](#receivecollectionerror)
- [receiveLastModified](#receivelastmodified)
- [Selectors](#selectors) - [Selectors](#selectors)
- [getCollection](#getcollection) - [getCollection](#getcollection)
- [getCollectionHeader](#getcollectionheader) - [getCollectionHeader](#getcollectionheader)
@ -39,6 +41,53 @@ This will return an action object for the given arguments used in dispatching th
- _response_ `Object`: An object containing a `items` property with the collection items from the response (array), and a `headers` property that is matches the `window.Headers` interface containing the headers from the response. - _response_ `Object`: An object containing a `items` property with the collection items from the response (array), and a `headers` property that is matches the `window.Headers` interface containing the headers from the response.
- _replace_ `boolean`: Whether or not to replace any existing items in the store for the given indexes (namespace, resourceName, queryString) if there are already values in the store. - _replace_ `boolean`: Whether or not to replace any existing items in the store for the given indexes (namespace, resourceName, queryString) if there are already values in the store.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( COLLECTIONS_STORE_KEY );
dispatch( receiveCollection( namespace, resourceName, queryString, ids, response ) );
```
### receiveCollectionError
This will return an action object for the given arguments used in dispatching an error to the store.
#### _Parameters_ <!-- omit in toc -->
- _namespace_ `string`: The route namespace for the collection, eg. `/wc/blocks`.
- _resourceName_ `string`: The resource name for the collection, eg. `products/attributes`.
- _queryString_ `string`: An additional query string to add to the request for the collection. Note, collections are cached by the query string, eg. `?order=ASC`.
- _ids_ `array`: If the collection route has placeholders for ids, you provide them via this argument in the order of how the placeholders appear in the route.
- _error_ `object`: The error object with the following keys:
- _code_ `string`: The error code.
- _message_ `string`: The error message.
- _data_ `object`: The error data with the following keys:
- _status_ `number`: The HTTP status code.
- _params_ `object`: The parameters for the error.
- _headers_ `object`: The headers for the error.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( COLLECTIONS_STORE_KEY );
dispatch( receiveCollectionError( namespace, resourceName, queryString, ids, error ) );
```
### receiveLastModified
This will return an action object for the given arguments used in dispatching the last modified date to the store.
#### _Parameters_ <!-- omit in toc -->
- _timestamp_ `number`: The timestamp of the last modified date.
#### _Example_ <!-- omit in toc -->
```js
const { dispatch } = useDispatch( COLLECTIONS_STORE_KEY );
dispatch( receiveLastModified( timestamp ) );
```
## Selectors ## Selectors
### getCollection ### getCollection

34
plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/validation.md
View File

@ -12,6 +12,7 @@
- [hideValidationError( errorId )](#hidevalidationerror-errorid-) - [hideValidationError( errorId )](#hidevalidationerror-errorid-)
- [showValidationError( errorId )](#showvalidationerror-errorid-) - [showValidationError( errorId )](#showvalidationerror-errorid-)
- [showAllValidationErrors](#showallvalidationerrors) - [showAllValidationErrors](#showallvalidationerrors)
- [clearAllValidationErrors](#clearallvalidationerrors)
- [Selectors](#selectors) - [Selectors](#selectors)
- [getValidationError( errorId )](#getvalidationerror-errorid-) - [getValidationError( errorId )](#getvalidationerror-errorid-)
- [getValidationErrorId( errorId )](#getvalidationerrorid-errorid-) - [getValidationErrorId( errorId )](#getvalidationerrorid-errorid-)
@ -42,7 +43,7 @@ When the checkout process begins, it will check if this data store has any entri
## Usage ## Usage
To utilize this store you will import the `CART_STORE_KEY` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the key via: To utilize this store you will import the `VALIDATION_STORE_KEY` in any module referencing it. Assuming `@woocommerce/block-data` is registered as an external pointing to `wc.wcBlocksData` you can import the key via:
```js ```js
const { VALIDATION_STORE_KEY } = window.wc.wcBlocksData; const { VALIDATION_STORE_KEY } = window.wc.wcBlocksData;
@ -168,7 +169,7 @@ Clears a validation error.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = dispatch( 'wc/store/validation' ); const store = dispatch( VALIDATION_STORE_KEY );
store.clearValidationError( 'billing-first-name' ); store.clearValidationError( 'billing-first-name' );
``` ```
@ -185,7 +186,7 @@ Clears multiple validation errors at once. If no error IDs are passed, all valid
1. This will clear only the validation errors passed in the array. 1. This will clear only the validation errors passed in the array.
```js ```js
const store = dispatch( 'wc/store/validation' ); const store = dispatch( VALIDATION_STORE_KEY );
store.clearValidationErrors( [ store.clearValidationErrors( [
'billing-first-name', 'billing-first-name',
'billing-last-name', 'billing-last-name',
@ -196,7 +197,7 @@ store.clearValidationErrors( [
2. This will clear all validation errors. 2. This will clear all validation errors.
```js ```js
const store = dispatch( 'wc/store/validation' ); const store = dispatch( VALIDATION_STORE_KEY );
store.clearValidationErrors(); store.clearValidationErrors();
``` ```
@ -212,7 +213,7 @@ Sets the validation errors. The entries in _errors_ will be _added_ to the list
```js ```js
const { dispatch } = wp.data; const { dispatch } = wp.data;
const { setValidationErrors } = dispatch( 'wc/store/validation' ); const { setValidationErrors } = dispatch( VALIDATION_STORE_KEY );
setValidationErrors( { setValidationErrors( {
'billing-first-name': { 'billing-first-name': {
@ -238,7 +239,7 @@ Hides a validation error by setting the `hidden` property to `true`. This will _
```js ```js
const { dispatch } = wp.data; const { dispatch } = wp.data;
const { hideValidationError } = dispatch( 'wc/store/validation' ); const { hideValidationError } = dispatch( VALIDATION_STORE_KEY );
hideValidationError( 'billing-first-name' ); hideValidationError( 'billing-first-name' );
``` ```
@ -255,7 +256,7 @@ Shows a validation error by setting the `hidden` property to `false`.
```js ```js
const { dispatch } = wp.data; const { dispatch } = wp.data;
const { showValidationError } = dispatch( 'wc/store/validation' ); const { showValidationError } = dispatch( VALIDATION_STORE_KEY );
showValidationError( 'billing-first-name' ); showValidationError( 'billing-first-name' );
``` ```
@ -268,11 +269,22 @@ Shows all validation errors by setting the `hidden` property to `false`.
```js ```js
const { dispatch } = wp.data; const { dispatch } = wp.data;
const { showAllValidationErrors } = dispatch( 'wc/store/validation' ); const { showAllValidationErrors } = dispatch( VALIDATION_STORE_KEY );
showAllValidationErrors(); showAllValidationErrors();
``` ```
### clearAllValidationErrors
Clears all validation errors by removing them from the store.
#### _Example_ <!-- omit in toc -->
```js
const { clearAllValidationErrors } = dispatch( VALIDATION_STORE_KEY );
clearAllValidationErrors();
```
## Selectors ## Selectors
### getValidationError( errorId ) ### getValidationError( errorId )
@ -290,7 +302,7 @@ Returns the validation error.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/validation' ); const store = select( VALIDATION_STORE_KEY );
const billingFirstNameError = store.getValidationError( 'billing-first-name' ); const billingFirstNameError = store.getValidationError( 'billing-first-name' );
``` ```
@ -309,7 +321,7 @@ Gets a validation error ID for use in HTML which can be used as a CSS selector,
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/validation' ); const store = select( VALIDATION_STORE_KEY );
const billingFirstNameErrorId = const billingFirstNameErrorId =
store.getValidationErrorId( 'billing-first-name' ); store.getValidationErrorId( 'billing-first-name' );
``` ```
@ -325,7 +337,7 @@ Returns true if validation errors occurred, and false otherwise.
#### _Example_ <!-- omit in toc --> #### _Example_ <!-- omit in toc -->
```js ```js
const store = select( 'wc/store/validation' ); const store = select( VALIDATION_STORE_KEY );
const hasValidationErrors = store.hasValidationErrors(); const hasValidationErrors = store.hasValidationErrors();
``` ```