diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/cart.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/cart.md index 96fde82fc13..e48f8e9108b 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/cart.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/cart.md @@ -10,6 +10,28 @@ - [Overview](#overview) - [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) - [getCartData](#getcartdata) - [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; ``` +## Actions + +### setCartData + +This action is used to set the cart data in the store. + +#### _Parameters_ + +- _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_ + +```js +const { dispatch } = useDispatch( CART_STORE_KEY ); +dispatch( setCartData( newCartData ) ); +``` + +### setErrorData + +This action is used to set the error data in the store. + +#### _Parameters_ + +- _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_ + +```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_ + +- _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_ + +- `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_ + +```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_ + +- _couponCode_ `string`: The code of the coupon being applied. + +#### _Returns_ + +- `object`: The action object with following keys: + - _type_ `string`: The action type. + - _couponCode_ `string`: The code of the coupon being applied. + +#### _Example_ + +```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_ + +- _couponCode_ `string`: The code of the coupon being removed. + +#### _Returns_ + +- `object`: The action object with the following keys: + - _type_ `string`: The action type. + - _couponCode_ `string`: The code of the coupon being removed. + +#### _Example_ + +```js +const { dispatch } = useDispatch( CART_STORE_KEY ); +dispatch( receiveRemovingCoupon( couponCode ) ); +``` + +### receiveCartItem + +This action is used to update a specific item in the cart. + +#### _Parameters_ + +- _cartResponseItem_ `object`: Cart response object with the following keys: + - _cartItem_ `object`: The cart item (see `getCartItem` selector). + +#### _Returns_ + +- `object`: The action object with the following keys: + - _type_ `string`: The action type. + - _cartItem_ `object`: The cart item (see `getCartItem` selector). + +#### _Example_ + +```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_ + +- _cartItemKey_ `string`: The key of the cart item. +- _isPending_ `boolean` (default: `true`): Whether the cart item quantity is being updated. + +#### _Returns_ + +- `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_ + +```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_ + +- _cartItemKey_ `string`: The key of the cart item. +- _isPending_ `boolean` (default: `true`): Whether the cart item is being deleted. + +#### _Returns_ + +- `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_ + +```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_ + +- _isCartDataStale_ `boolean` (default: `true`): Flag to mark cart data as stale; true if `lastCartUpdate` timestamp is newer than the one in wcSettings. + +#### _Returns_ + +- `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_ + +```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_ + +- _isResolving_ `boolean`: Whether the customer data is being updated. + +#### _Returns_ + +- `object`: The action object with the following keys: + - _type_ `string`: The action type. + - _isResolving_ `boolean`: Whether the customer data is being updated. + +#### _Example_ + +```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_ + +- _isResolving_ `boolean`: True if shipping rate is being selected. + +#### _Returns_ + +- `object`: The action object with the following keys: + - _type_ `string`: The action type. + - _isResolving_ `boolean`: True if shipping rate is being selected. + +#### _Example_ + +```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_ + +- _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_ + +```js +const { dispatch } = useDispatch( CART_STORE_KEY ); +dispatch( applyExtensionCartUpdate( args ) ); +``` + +### applyCoupon + +This action is used to apply a coupon to the cart. + +#### _Parameters_ + +- _couponCode_ `string`: The code of the coupon to apply. + +#### _Example_ + +```js +const { dispatch } = useDispatch( CART_STORE_KEY ); +dispatch( applyCoupon( couponCode ) ); +``` + +### removeCoupon + +This action is used to remove a coupon from the cart. + +#### _Parameters_ + +- _couponCode_ `string`: The code of the coupon to remove. + +#### _Example_ + +```js +const { dispatch } = useDispatch( CART_STORE_KEY ); +dispatch( removeCoupon( couponCode ) ); +``` + +### addItemToCart + +This action is used to add an item to the cart. + +#### _Parameters_ + +- _productId_ `number`: Product ID to add to cart. +- _quantity_ `number` (default: `1`): The quantity of the product to add. + +#### _Example_ + +```js +const { dispatch } = useDispatch( CART_STORE_KEY ); +dispatch( addItemToCart( productId, quantity ) ); +``` + +### removeItemFromCart + +This action is used to remove an item from the cart. + +#### _Parameters_ + +- _cartItemKey_ `string`: Cart item being updated. + +#### _Example_ + +```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_ + +- _cartItemKey_ `string`: Cart item being updated. +- _quantity_ `number`: Quantity of the item. + +#### _Example_ + +```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_ + +- _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_ + +```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_ + +- _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_ + +```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_ + +- _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_ + +```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_ + +- _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_ + +```js +const { dispatch } = useDispatch( CART_STORE_KEY ); +dispatch( updateCustomerData( customerData, editing ) ); +``` + ## Selectors ### getCartData @@ -73,7 +578,7 @@ Returns the Cart data from the state. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const cartData = store.getCartData(); ``` @@ -99,7 +604,7 @@ Returns the shipping and billing address from the state. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const customerData = store.getCustomerData(); ``` @@ -109,12 +614,21 @@ Returns the shipping rates from the state. #### _Returns_ -- `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_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const shippingRates = store.getShippingRates(); ``` @@ -129,7 +643,7 @@ Queries whether the cart needs shipping. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const needsShipping = store.getNeedsShipping(); ``` @@ -144,7 +658,7 @@ Queries whether the cart shipping has been calculated. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const hasCalculatedShipping = store.getHasCalculatedShipping(); ``` @@ -177,7 +691,7 @@ Returns the cart totals from state. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const cartTotals = store.getCartTotals(); ``` @@ -197,7 +711,7 @@ Returns the cart meta from state. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const cartMeta = store.getCartMeta(); ``` @@ -207,12 +721,16 @@ Returns the cart errors from state if cart receives customer facing errors from #### _Returns_ -- `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_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const cartErrors = store.getCartErrors(); ``` @@ -227,7 +745,7 @@ Queries whether a coupon is being applied. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const isApplyingCoupon = store.isApplyingCoupon(); ``` @@ -242,7 +760,7 @@ Queries whether the cart data is stale. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const isCartDataStale = store.isCartDataStale(); ``` @@ -257,7 +775,7 @@ Returns the coupon code being applied. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const couponBeingApplied = store.getCouponBeingApplied(); ``` @@ -272,7 +790,7 @@ Queries whether a coupon is being removed. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const isRemovingCoupon = store.isRemovingCoupon(); ``` @@ -287,7 +805,7 @@ Returns the coupon code being removed. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const couponBeingRemoved = store.getCouponBeingRemoved(); ``` @@ -346,7 +864,7 @@ Returns a cart item from the state. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const cartItem = store.getCartItem( cartItemKey ); ``` @@ -365,7 +883,7 @@ Queries whether a cart item is pending quantity. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const isItemPendingQuantity = store.isItemPendingQuantity( cartItemKey ); ``` @@ -384,7 +902,7 @@ Queries whether a cart item is pending delete. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const isItemPendingDelete = store.isItemPendingDelete( cartItemKey ); ``` @@ -399,7 +917,7 @@ Queries whether the customer data is being updated. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const isCustomerDataUpdating = store.isCustomerDataUpdating(); ``` @@ -414,7 +932,7 @@ Queries whether a shipping rate is being selected. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const isShippingRateBeingSelected = store.isShippingRateBeingSelected(); ``` @@ -429,7 +947,7 @@ Retrieves the item keys for items whose quantity is currently being updated. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const itemsPendingQuantityUpdate = store.getItemsPendingQuantityUpdate(); ``` @@ -444,7 +962,7 @@ Retrieves the item keys for items that are currently being deleted. #### _Example_ ```js -const store = select( 'wc/store/cart' ); +const store = select( CART_STORE_KEY ); const itemsPendingDelete = store.getItemsPendingDelete(); ``` diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/checkout.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/checkout.md index 044cb8e506f..314238c9178 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/checkout.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/checkout.md @@ -27,6 +27,8 @@ - [isAfterProcessing](#isafterprocessing) - [isComplete](#iscomplete) - [isCalculating](#iscalculating) +- [Actions](#actions) + - [setPrefersCollection](#setpreferscollection) ## Overview @@ -53,7 +55,7 @@ Returns the WordPress user ID of the customer whose order is currently processed #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const customerId = store.getCustomerId(); ``` @@ -68,7 +70,7 @@ Returns the WooCommerce order ID of the order that is currently being processed #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const orderId = store.getOrderId(); ``` @@ -83,7 +85,7 @@ Returns the order notes. #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const orderNotes = store.getOrderNotes(); ``` @@ -98,7 +100,7 @@ Returns the URL to redirect to after checkout is complete. #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const redirectUrl = store.getRedirectUrl(); ``` @@ -121,7 +123,7 @@ Returns the extra data registered by extensions. #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const extensionData = store.getExtensionData(); ``` @@ -136,7 +138,7 @@ Returns the current status of the checkout process. #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const checkoutStatus = store.getCheckoutStatus(); ``` @@ -151,7 +153,7 @@ Returns true if the shopper has opted to create an account with their order. #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const shouldCreateAccount = store.getShouldCreateAccount(); ``` @@ -166,7 +168,7 @@ Returns true if the shopper has opted to use their shipping address as their bil #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const useShippingAsBilling = store.getUseShippingAsBilling(); ``` @@ -181,7 +183,7 @@ Returns true if an error occurred, and false otherwise. #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const hasError = store.hasError(); ``` @@ -196,7 +198,7 @@ Returns true if a draft order had been created, and false otherwise. #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const hasOrder = store.hasOrder(); ``` @@ -211,7 +213,7 @@ When the checkout status is `IDLE` this flag is true. Checkout will be this stat #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const isIdle = store.isIdle(); ``` @@ -226,7 +228,7 @@ When the checkout status is `BEFORE_PROCESSING` this flag is true. Checkout will #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const isBeforeProcessing = store.isBeforeProcessing(); ``` @@ -241,7 +243,7 @@ When the checkout status is `PROCESSING` this flag is true. Checkout will be thi #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const isProcessing = store.isProcessing(); ``` @@ -256,7 +258,7 @@ When the checkout status is `AFTER_PROCESSING` this flag is true. Checkout will #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const isAfterProcessing = store.isAfterProcessing(); ``` @@ -271,7 +273,7 @@ When the checkout status is `COMPLETE` this flag is true. Checkout will have thi #### _Example_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); 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_ ```js -const store = select( 'wc/store/checkout' ); +const store = select( CHECKOUT_STORE_KEY ); const isCalculating = store.isCalculating(); ``` +## Actions + +### setPrefersCollection + +Sets the `prefersCollection` flag to true or false. + +#### _Parameters_ + +- _prefersCollection_ `boolean`: True if the shopper prefers to collect their order. + +#### _Example_ + +```js +const store = dispatch( CHECKOUT_STORE_KEY ); +store.setPrefersCollection( true ); +``` + --- diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/collections.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/collections.md index b75dcb50510..2917afedd0b 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/collections.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/collections.md @@ -6,6 +6,8 @@ - [Usage](#usage) - [Actions](#actions) - [receiveCollection( namespace, resourceName, queryString, ids = \[\], items = \[\], replace = false )](#receivecollection-namespace-resourcename-querystring-ids---items---replace--false-) + - [receiveCollectionError](#receivecollectionerror) + - [receiveLastModified](#receivelastmodified) - [Selectors](#selectors) - [getCollection](#getcollection) - [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. - _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_ + +```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_ + +- _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_ + +```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_ + +- _timestamp_ `number`: The timestamp of the last modified date. + +#### _Example_ + +```js +const { dispatch } = useDispatch( COLLECTIONS_STORE_KEY ); +dispatch( receiveLastModified( timestamp ) ); +``` + ## Selectors ### getCollection diff --git a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/validation.md b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/validation.md index d9bea418666..b9ab4f0bd81 100644 --- a/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/validation.md +++ b/plugins/woocommerce-blocks/docs/third-party-developers/extensibility/data-store/validation.md @@ -12,6 +12,7 @@ - [hideValidationError( errorId )](#hidevalidationerror-errorid-) - [showValidationError( errorId )](#showvalidationerror-errorid-) - [showAllValidationErrors](#showallvalidationerrors) + - [clearAllValidationErrors](#clearallvalidationerrors) - [Selectors](#selectors) - [getValidationError( errorId )](#getvalidationerror-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 -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 const { VALIDATION_STORE_KEY } = window.wc.wcBlocksData; @@ -168,7 +169,7 @@ Clears a validation error. #### _Example_ ```js -const store = dispatch( 'wc/store/validation' ); +const store = dispatch( VALIDATION_STORE_KEY ); 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. ```js -const store = dispatch( 'wc/store/validation' ); +const store = dispatch( VALIDATION_STORE_KEY ); store.clearValidationErrors( [ 'billing-first-name', 'billing-last-name', @@ -196,7 +197,7 @@ store.clearValidationErrors( [ 2. This will clear all validation errors. ```js -const store = dispatch( 'wc/store/validation' ); +const store = dispatch( VALIDATION_STORE_KEY ); store.clearValidationErrors(); ``` @@ -212,7 +213,7 @@ Sets the validation errors. The entries in _errors_ will be _added_ to the list ```js const { dispatch } = wp.data; -const { setValidationErrors } = dispatch( 'wc/store/validation' ); +const { setValidationErrors } = dispatch( VALIDATION_STORE_KEY ); setValidationErrors( { 'billing-first-name': { @@ -238,7 +239,7 @@ Hides a validation error by setting the `hidden` property to `true`. This will _ ```js const { dispatch } = wp.data; -const { hideValidationError } = dispatch( 'wc/store/validation' ); +const { hideValidationError } = dispatch( VALIDATION_STORE_KEY ); hideValidationError( 'billing-first-name' ); ``` @@ -255,7 +256,7 @@ Shows a validation error by setting the `hidden` property to `false`. ```js const { dispatch } = wp.data; -const { showValidationError } = dispatch( 'wc/store/validation' ); +const { showValidationError } = dispatch( VALIDATION_STORE_KEY ); showValidationError( 'billing-first-name' ); ``` @@ -268,11 +269,22 @@ Shows all validation errors by setting the `hidden` property to `false`. ```js const { dispatch } = wp.data; -const { showAllValidationErrors } = dispatch( 'wc/store/validation' ); +const { showAllValidationErrors } = dispatch( VALIDATION_STORE_KEY ); showAllValidationErrors(); ``` +### clearAllValidationErrors + +Clears all validation errors by removing them from the store. + +#### _Example_ + +```js +const { clearAllValidationErrors } = dispatch( VALIDATION_STORE_KEY ); +clearAllValidationErrors(); +``` + ## Selectors ### getValidationError( errorId ) @@ -290,7 +302,7 @@ Returns the validation error. #### _Example_ ```js -const store = select( 'wc/store/validation' ); +const store = select( VALIDATION_STORE_KEY ); 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_ ```js -const store = select( 'wc/store/validation' ); +const store = select( VALIDATION_STORE_KEY ); const billingFirstNameErrorId = store.getValidationErrorId( 'billing-first-name' ); ``` @@ -325,7 +337,7 @@ Returns true if validation errors occurred, and false otherwise. #### _Example_ ```js -const store = select( 'wc/store/validation' ); +const store = select( VALIDATION_STORE_KEY ); const hasValidationErrors = store.hasValidationErrors(); ```