diff --git a/plugins/woocommerce-blocks/assets/js/base/components/cart-checkout/shipping-rates-control/index.tsx b/plugins/woocommerce-blocks/assets/js/base/components/cart-checkout/shipping-rates-control/index.tsx index 79b5c4c2dcb..6cfd49ad640 100644 --- a/plugins/woocommerce-blocks/assets/js/base/components/cart-checkout/shipping-rates-control/index.tsx +++ b/plugins/woocommerce-blocks/assets/js/base/components/cart-checkout/shipping-rates-control/index.tsx @@ -81,6 +81,7 @@ interface ShippingRatesControlProps { shippingRatesLoading: boolean; noResultsMessage: ReactElement; renderOption: PackageRateRenderOption; + context: 'woocommerce/cart' | 'woocommerce/checkout'; } /** * Renders the shipping rates control element. @@ -92,6 +93,7 @@ interface ShippingRatesControlProps { * @param {boolean} [props.collapsible] If true, when multiple packages are rendered they can be toggled open and closed. * @param {ReactElement} props.noResultsMessage Rendered when there are no packages. * @param {Function} [props.renderOption] Function to render a shipping rate. + * @param {string} [props.context] String equal to the block name where the Slot is rendered */ const ShippingRatesControl = ( { shippingRates, @@ -100,6 +102,7 @@ const ShippingRatesControl = ( { collapsible = false, noResultsMessage, renderOption, + context, }: ShippingRatesControlProps ): JSX.Element => { useEffect( () => { if ( shippingRatesLoading ) { @@ -161,6 +164,7 @@ const ShippingRatesControl = ( { components: { ShippingRatesControlPackage, }, + context, }; const { isEditor } = useEditorContext(); diff --git a/plugins/woocommerce-blocks/assets/js/base/components/cart-checkout/totals/shipping/shipping-rate-selector.js b/plugins/woocommerce-blocks/assets/js/base/components/cart-checkout/totals/shipping/shipping-rate-selector.js index 05615e7a8b9..7b5d9e648ba 100644 --- a/plugins/woocommerce-blocks/assets/js/base/components/cart-checkout/totals/shipping/shipping-rate-selector.js +++ b/plugins/woocommerce-blocks/assets/js/base/components/cart-checkout/totals/shipping/shipping-rate-selector.js @@ -40,6 +40,7 @@ const ShippingRateSelector = ( { } shippingRates={ shippingRates } shippingRatesLoading={ shippingRatesLoading } + context="woocommerce/cart" /> ); diff --git a/plugins/woocommerce-blocks/assets/js/blocks/cart-checkout/cart/inner-blocks/cart-order-summary-block/block.tsx b/plugins/woocommerce-blocks/assets/js/blocks/cart-checkout/cart/inner-blocks/cart-order-summary-block/block.tsx index ee41ba37b39..fa7bdfc6f77 100644 --- a/plugins/woocommerce-blocks/assets/js/blocks/cart-checkout/cart/inner-blocks/cart-order-summary-block/block.tsx +++ b/plugins/woocommerce-blocks/assets/js/blocks/cart-checkout/cart/inner-blocks/cart-order-summary-block/block.tsx @@ -56,11 +56,13 @@ const Block = ( { const slotFillProps = { extensions, cart, + context: 'woocommerce/cart', }; const discountsSlotFillProps = { extensions, cart, + context: 'woocommerce/cart', }; return ( diff --git a/plugins/woocommerce-blocks/assets/js/blocks/checkout/inner-blocks/checkout-order-summary-block/block.tsx b/plugins/woocommerce-blocks/assets/js/blocks/checkout/inner-blocks/checkout-order-summary-block/block.tsx index 3833c39676d..5a3147e24cd 100644 --- a/plugins/woocommerce-blocks/assets/js/blocks/checkout/inner-blocks/checkout-order-summary-block/block.tsx +++ b/plugins/woocommerce-blocks/assets/js/blocks/checkout/inner-blocks/checkout-order-summary-block/block.tsx @@ -54,6 +54,7 @@ const Block = ( { const slotFillProps = { extensions, cart, + context: 'woocommerce/checkout', }; return ( diff --git a/plugins/woocommerce-blocks/assets/js/blocks/checkout/inner-blocks/checkout-shipping-methods-block/block.tsx b/plugins/woocommerce-blocks/assets/js/blocks/checkout/inner-blocks/checkout-shipping-methods-block/block.tsx index 604225d7dac..c3a13a11eaf 100644 --- a/plugins/woocommerce-blocks/assets/js/blocks/checkout/inner-blocks/checkout-shipping-methods-block/block.tsx +++ b/plugins/woocommerce-blocks/assets/js/blocks/checkout/inner-blocks/checkout-shipping-methods-block/block.tsx @@ -103,6 +103,7 @@ const Block = (): JSX.Element | null => { renderOption={ renderShippingRatesControlOption } shippingRates={ shippingRates } shippingRatesLoading={ shippingRatesLoading } + context="woocommerce/checkout" /> ) } diff --git a/plugins/woocommerce-blocks/docs/extensibility/available-slot-fills.md b/plugins/woocommerce-blocks/docs/extensibility/available-slot-fills.md index 4854960aa38..f446590a15a 100644 --- a/plugins/woocommerce-blocks/docs/extensibility/available-slot-fills.md +++ b/plugins/woocommerce-blocks/docs/extensibility/available-slot-fills.md @@ -2,52 +2,62 @@ This document presents the list of available Slots that you can use for adding your custom content (Fill): -- [ExperimentalOrderMeta](#experimentalordermeta) -- [ExperimentalOrderShippingPackages](#experimentalordershippingpackages) -- [ExperimentalDiscountsMeta](#experimentaldiscountsmeta) +- [ExperimentalOrderMeta](#experimentalordermeta) +- [ExperimentalOrderShippingPackages](#experimentalordershippingpackages) +- [ExperimentalDiscountsMeta](#experimentaldiscountsmeta) -*** +--- If you want to add a new SlotFill component, check the [Checkout - Slot Fill document](../../packages/checkout/slot/README.md). To read more about Slot and Fill, check the [Slot and Fill document](./slot-fills.md). **Note About Naming:** Slots that are prefixed with `Experimental` are experimental and subject to change or remove. Once they graduate from the experimental stage, the naming would change and the `Experimental` prefix would be dropped. Check the [Feature Gating document](../blocks/feature-flags-and-experimental-interfaces.md) from more information. - ## ExperimentalOrderMeta + This Slot renders below the Checkout summary section and above the "Proceed to Checkout" button in the Cart. -image +Cart: + +Example of ExperimentalOrderMeta in the Cart block + +Checkout: + +Example of ExperimentalOrderMeta in the Checkout block ### Passed parameters -- `cart`: `wc/store/cart` data but in `camelCase` instead of `snake_case`. [Object breakdown.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/c00da597efe4c16fcf5481c213d8052ec5df3766/assets/js/type-defs/cart.ts#L172-L188) -- `extensions`: external data registered by third-party developers using `ExtendRestAPI`. If you used `ExtendRestAPI` on `wc/store/cart` you would find your data under your namespace here. +- `cart`: `wc/store/cart` data but in `camelCase` instead of `snake_case`. [Object breakdown.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/c00da597efe4c16fcf5481c213d8052ec5df3766/assets/js/type-defs/cart.ts#L172-L188) +- `extensions`: external data registered by third-party developers using `ExtendRestAPI`. If you used `ExtendRestAPI` on `wc/store/cart` you would find your data under your namespace here. +- `context`, equal to the name of the Block in which the fill is rendered: `woocommerce/cart` or `woocommerce/checkout` ## ExperimentalOrderShippingPackages + This slot renders inside the shipping step of Checkout and inside the shipping options in Cart. Cart: -image +Example of ExperimentalOrderShippingPackages in the Cart block Checkout: -image +Example of ExperimentalOrderShippingPackages in the Checkout block ### Passed parameters -- `collapsible`: `Boolean` If a shipping package panel should be collapsible or not, this is false in Checkout and true in Cart. -- `collapse`: `Boolean` If a panel should be collapsed by default, this is true if there's more than 1 fill registered (Core Shipping options are registered as a fill and they're counted). -- `showItems`: `Boolean` If we should show the content of each package, this is true if there's more than 1 fill registered (Core Shipping options are registered as a fill and they're counted). -- `noResultsMessage`: A React element that you can render if there are no shipping options. -- `renderOption`: a render function that takes a rate object and returns a render option. -- `cart`: `wc/store/cart` data but in `camelCase` instead of `snake_case`. [Object breakdown.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/c00da597efe4c16fcf5481c213d8052ec5df3766/assets/js/type-defs/cart.ts#L172-L188) -- `extensions`: external data registered by third-party developers using `ExtendRestAPI`, if you used `ExtendRestAPI` on `wc/store/cart` you would find your data under your namespace here. -- `components`: an object containing components you can use to render your own shipping rates, it contains `ShippingRatesControlPackage`. +- `collapsible`: `Boolean` If a shipping package panel should be collapsible or not, this is false in Checkout and true in Cart. +- `collapse`: `Boolean` If a panel should be collapsed by default, this is true if there's more than 1 fill registered (Core Shipping options are registered as a fill and they're counted). +- `showItems`: `Boolean` If we should show the content of each package, this is true if there's more than 1 fill registered (Core Shipping options are registered as a fill and they're counted). +- `noResultsMessage`: A React element that you can render if there are no shipping options. +- `renderOption`: a render function that takes a rate object and returns a render option. +- `cart`: `wc/store/cart` data but in `camelCase` instead of `snake_case`. [Object breakdown.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/c00da597efe4c16fcf5481c213d8052ec5df3766/assets/js/type-defs/cart.ts#L172-L188) +- `extensions`: external data registered by third-party developers using `ExtendRestAPI`, if you used `ExtendRestAPI` on `wc/store/cart` you would find your data under your namespace here. +- `components`: an object containing components you can use to render your own shipping rates, it contains `ShippingRatesControlPackage`. +- `context`, equal to the name of the Block in which the fill is rendered: `woocommerce/cart` or `woocommerce/checkout` ## ExperimentalDiscountsMeta -This slot renders below the `CouponCode` input. + +This slot renders below the `CouponCode` input. Cart: Cart showing ExperimentalDiscountsMeta location @@ -56,14 +66,15 @@ Checkout: Checkout showing ExperimentalDiscountsMeta location ### Passed paramters -- `cart`: `wc/store/cart` data but in `camelCase` instead of `snake_case`. [Object breakdown.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/c00da597efe4c16fcf5481c213d8052ec5df3766/assets/js/type-defs/cart.ts#L172-L188) -- `extensions`: external data registered by third-party developers using `ExtendRestAPI`, if you used `ExtendRestAPI` on `wc/store/cart` you would find your data under your namespace here. - ---- +- `cart`: `wc/store/cart` data but in `camelCase` instead of `snake_case`. [Object breakdown.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/c00da597efe4c16fcf5481c213d8052ec5df3766/assets/js/type-defs/cart.ts#L172-L188) +- `extensions`: external data registered by third-party developers using `ExtendRestAPI`, if you used `ExtendRestAPI` on `wc/store/cart` you would find your data under your namespace here. +- `context`, equal to the name of the Block in which the fill is rendered: `woocommerce/cart` or `woocommerce/checkout` + +## [We're hiring!](https://woocommerce.com/careers/) Come work with us! 🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/extensibility/available-slot-fills.md) - + diff --git a/plugins/woocommerce-blocks/docs/extensibility/slot-fills.md b/plugins/woocommerce-blocks/docs/extensibility/slot-fills.md index 9746c230237..d6794cf58e5 100644 --- a/plugins/woocommerce-blocks/docs/extensibility/slot-fills.md +++ b/plugins/woocommerce-blocks/docs/extensibility/slot-fills.md @@ -1,6 +1,7 @@ # Slot and Fill ## The problem + You added custom data to the [Store API](./extend-rest-api-add-data.md). You changed several strings using [Checkout filters](./available-filters.md). Now you want to render your own components in specific places in the Cart and Checkout. ## Solution @@ -15,22 +16,26 @@ Slot and Fill use WordPress' API, and you can learn more about how they work in ## Basic Usage -`ExperimentalOrderMeta` is a fill that will render in a slot below the order summary section in the Cart and Checkout blocks. -The `ExperimentalOrderMeta` will automatically pass props to its top level child: `cart` which contains cart data, and `extensions` which contains data registered with `ExtendRestAPI` in `wc/store/cart` endpoint. +`ExperimentalOrderMeta` is a fill that will render in a slot below the Order summary section in the Cart and Checkout blocks. +The `ExperimentalOrderMeta` will automatically pass props to its top level child: + +- `cart` which contains cart data +- `extensions` which contains data registered with `ExtendRestAPI` in `wc/store/cart` endpoint +- `context`, equal to the name of the Block in which the fill is rendered: `woocommerce/cart` or `woocommerce/checkout` ```jsx const { registerPlugin } = wp.plugins; const { ExperimentalOrderMeta } = wc.blocksCheckout; const MyCustomComponent = ( { cart, extensions } ) => { - return
Hello WooCommerce
-} + return
Hello WooCommerce
; +}; const render = () => { return ( - - - + + + ); }; @@ -47,13 +52,13 @@ In the above example, we're using `registerPlugin`. This plugin will take our co You use `registerPlugin` to feed in your plugin namespace, your component `render`, and the scope of your `registerPlugin`. The value of scope should always be `woocommerce-checkout`. ## Requirements + For this to work, your script must be enqueued after Cart and Checkout. You can follow the [IntegrationInterface](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/50f9b3e8d012f425d318908cc13d9c601d97bd68/docs/extensibility/integration-interface.md) documentation for enqueueing your script. - ---- +## [We're hiring!](https://woocommerce.com/careers/) Come work with us! 🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/extensibility/slot-fills.md) - + diff --git a/plugins/woocommerce-blocks/packages/checkout/components/discounts-meta/index.js b/plugins/woocommerce-blocks/packages/checkout/components/discounts-meta/index.js index cf20570709f..267adf39db4 100644 --- a/plugins/woocommerce-blocks/packages/checkout/components/discounts-meta/index.js +++ b/plugins/woocommerce-blocks/packages/checkout/components/discounts-meta/index.js @@ -16,7 +16,7 @@ const { Slot: DiscountsMetaSlot, } = createSlotFill( slotName ); -const Slot = ( { className, extensions, cart } ) => { +const Slot = ( { className, extensions, cart, context } ) => { const { fills } = useSlot( slotName ); return ( hasValidFills( fills ) && ( @@ -26,7 +26,7 @@ const Slot = ( { className, extensions, cart } ) => { className, 'wc-block-components-discounts-meta' ) } - fillProps={ { extensions, cart } } + fillProps={ { extensions, cart, context } } /> ) diff --git a/plugins/woocommerce-blocks/packages/checkout/components/order-meta/index.js b/plugins/woocommerce-blocks/packages/checkout/components/order-meta/index.js index abf04a68a45..7c86bc632ee 100644 --- a/plugins/woocommerce-blocks/packages/checkout/components/order-meta/index.js +++ b/plugins/woocommerce-blocks/packages/checkout/components/order-meta/index.js @@ -15,7 +15,7 @@ const { Fill: ExperimentalOrderMeta, Slot: OrderMetaSlot } = createSlotFill( slotName ); -const Slot = ( { className, extensions, cart } ) => { +const Slot = ( { className, extensions, cart, context } ) => { const { fills } = useSlot( slotName ); return ( hasValidFills( fills ) && ( @@ -25,7 +25,7 @@ const Slot = ( { className, extensions, cart } ) => { className, 'wc-block-components-order-meta' ) } - fillProps={ { extensions, cart } } + fillProps={ { extensions, cart, context } } /> ) diff --git a/plugins/woocommerce-blocks/packages/checkout/components/order-shipping-packages/index.js b/plugins/woocommerce-blocks/packages/checkout/components/order-shipping-packages/index.js index 84a5c830926..d07a6e95884 100644 --- a/plugins/woocommerce-blocks/packages/checkout/components/order-shipping-packages/index.js +++ b/plugins/woocommerce-blocks/packages/checkout/components/order-shipping-packages/index.js @@ -22,6 +22,7 @@ const Slot = ( { extensions, cart, components, + context, } ) => { const { fills } = useSlot( slotName ); const hasMultiplePackages = fills.length > 1; @@ -40,6 +41,7 @@ const Slot = ( { extensions, cart, components, + context, } } /> );