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

Add documentation for `ExperimentalDiscountsMeta`, `cart/extensions` endpoint, and `extensionCartUpdate` (https://github.com/woocommerce/woocommerce-blocks/pull/4377) 

* Add documentation for `cart/extensions`

* Add documentation for ExperimentalDiscountsMeta slot

* Add clearer information to `cart/extensions` documentation

* Change checkout screenshot

* Change checkout screenshot

* Update documentation into new template and amend based on suggestions

* Fix typo

* Fix punctuation and remove passive-aggressive voice!

* Update docs/extensibility/extend-rest-api-update-cart.md

Co-authored-by: Seghir Nadir <nadir.seghir@gmail.com>

Co-authored-by: Seghir Nadir <nadir.seghir@gmail.com>
This commit is contained in:
Thomas Roberts 2021-08-25 13:12:34 +01:00 committed by GitHub
parent 581769886a
commit e3b88d501e
2 changed files with 220 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
plugins/woocommerce-blocks/docs/extensibility/available-slot-fills.md
View File

@ -38,3 +38,16 @@ Checkout:
- `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`.
## ExperimentalDiscountsMeta
This slot renders below the `CouponCode` input.
Cart:
<img alt="Cart showing ExperimentalDiscountsMeta location" src="https://user-images.githubusercontent.com/5656702/122774218-ea27a880-d2a0-11eb-9450-11f119567f26.png" />
Checkout:
<img alt="Checkout showing ExperimentalDiscountsMeta location" src="https://user-images.githubusercontent.com/5656702/122779606-efd3bd00-d2a5-11eb-8c84-6525eca5d704.png" />
### 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.

207
plugins/woocommerce-blocks/docs/extensibility/extend-rest-api-update-cart.md Normal file
View File

@ -0,0 +1,207 @@
# Updating the cart with the Store API
## The problem
You're an extension developer, and your extension does some server-side processing as a result of some client-side
input, i.e. a shopper filling in an input field in the Cart sidebar, and then pressing a button.
This server-side processing causes the state of the cart to change, and you want to update the data displayed
in the client-side Cart or Checkout block.
You can't simply update the client-side cart state yourself. This is restricted to prevent malfunctioning extensions
inadvertently updating it with malformed or invalid data which will cause the whole block to break.
## The solution
`ExtendRestApi` offers the ability for extensions to register callback functions to be executed when
signalled to do so by the client-side Cart or Checkout.
WooCommerce Blocks also provides a front-end function called `extensionCartUpdate` which can be called by client-side
code, this will send data (specified by you when calling `extensionCartUpdate`) to the `cart/extensions` endpoint.
When this endpoint gets hit, any relevant (based on the namespace provided to `extensionCartUpdate`) callbacks get
executed, and the latest server-side cart data gets returned and the block is updated with this new data.
## Basic usage
In your extension's server-side integration code:
```PHP
use Automattic\WooCommerce\Blocks\Package;
use Automattic\WooCommerce\Blocks\Domain\Services\ExtendRestApi;
add_action('woocommerce_blocks_loaded', function() {
// ExtendRestApi is stored in the container as a shared instance between the API and consumers.
// You shouldn't initiate your own ExtendRestApi instance using `new ExtendRestApi` but should always use the shared instance from the Package dependency injection container.
$extend = Package::container()->get( ExtendRestApi::class );
$extend->register_update_callback(
[
'namespace' => 'extension-unique-namespace',
'callback' => /* Add your callable here */
]
);
} );
```
and on the client side:
```typescript
const { extensionCartUpdate } = wc.blocksCheckout;
extensionCartUpdate(
{
namespace: 'extension-unique-namespace',
data: {
key: 'value',
another_key: 100,
third_key: {
fourth_key: true,
}
}
}
)
```
## Things to consider
### Extensions cannot update the client-side cart state themselves
You may be wondering why it's not possible to just make a custom AJAX endpoint for your extension that will update the
cart. As mentioned, extensions are not permitted to update the client-side cart's state, because doing this incorrectly
would cause the entire block to break, preventing the user from continuing their checkout. Instead you _must_ do this
through the `extensionCartUpdate` function.
### Only one callback for a given namespace may be registered
With this in mind, if your extension has several client-side interactions that result in different code paths being
executed on the server-side, you may wish to pass additional data through in `extensionsCartUpdate`. For example
if you have two actions the user can take, one to _add_ a discount, and the other to _remove_ it, you may wish to pass
a key called `action` along with the other data to `extensionsCartUpdate`. Then in your callback, you can check this
value to distinguish which code path you should execute.
Example:
```PHP
<?php
use Automattic\WooCommerce\Blocks\Package;
use Automattic\WooCommerce\Blocks\Domain\Services\ExtendRestApi;
function add_discount() {
/* Do some processing here */
}
function remove_discount() {
/* Do some processing here */
}
add_action('woocommerce_blocks_loaded', function() {
// ExtendRestApi is stored in the container as a shared instance between the API and consumers.
// You shouldn't initiate your own ExtendRestApi instance using `new ExtendRestApi` but should always use the shared instance from the Package dependency injection container.
$extend = Package::container()->get( ExtendRestApi::class );
$extend->register_update_callback(
[
'namespace' => 'extension-unique-namespace',
'callback' => function( $data ) {
if ( $data['action'] === 'add' ) {
add_discount( );
}
if ( $data['action'] === 'remove' ) {
remove_discount();
}
}
]
);
} );
```
If you try to register again, under the same namespace, the previously registered callback will be overwritten.
## API Definition
### PHP
`ExtendRestApi::register_update_callback`: Used to register a callback to be executed when the `cart/extensions`
endpoint gets hit with a given namespace. It takes an array of arguments
| Attribute | Type | Required | Description |
|---|---|---|---|
| `namespace` | `string` | Yes | The namespace of your extension. This is used to determine which extension's callbacks should be executed. |
| `callback` | `Callable` | Yes | The function/method (or Callable) that will be executed when the `cart/extensions` endpoint is hit with a `namespace` that matches the one supplied. The callable should take a single argument. The data passed into the callback via this argument will be an array containing whatever data you choose to pass to it. The callable does not need to return anything, if it does, then its return value will not be used.
### JavaScript
`extensionCartUpdate`: Used to signal that you want your registered callback to be executed, and to pass data to the callback. It takes an object as its only argument.
| Attribute | Type | Required | Description |
|---|---|---|---|
| `namespace` | `string` | Yes | The namespace of your extension. This is used to determine which extension's callbacks should be executed. |
| `data` | `Object` | No | The data you want to pass to your callback. Anything in the `data` key will be passed as the first (and only) argument to your callback as an associative array.
## Putting it all together
You are the author of an extension that lets the shopper redeem points that they earn on your website for a discount on
their order. There is a text field where the shopper can enter how many points they want to redeem, and a submit button
that will apply the redemption.
Your extension adds these UI elements to the sidebar in the Cart and Checkout blocks using the [`DiscountsMeta`](./available-slot-fills.md) Slot.
More information on how to use Slots is available in our [Slots and Fills documentation](./slot-fills.md).
Once implemented, the sidebar has a control added to it like this:
<img src="https://user-images.githubusercontent.com/5656702/125109827-bf7c8300-e0db-11eb-9e51-59921b38a0c2.png" width=400 />
### The "Redeem" button
In your UI, you are tracking the value the shopper enters into the `Enter amount` box using a React `useState` variable.
The variable in this example shall be called `pointsInputValue`.
When the `Redeem` button gets clicked, you want to tell the server how many points to apply to the shopper's basket,
based on what they entered into the box, apply the relevant discount, update the server-side cart, and then show the
updated price in the client-side sidebar.
To do this, you will need to use `extensionCartUpdate` to tell the server you want to execute your callback, and have
the new cart state loaded into the UI. The `onClick` handler of the button may look like this:
```javascript
import { extensionCartUpdate } from '@woocommerce/blocks-checkout';
const buttonClickHandler = () => {
extensionCartUpdate(
{
namespace: 'super-coupons',
data: {
pointsInputValue
}
}
)
};
```
### Registering a callback to run when the `cart/extensions` endpoint is hit
So far, we haven't registered a callback with WooCommerce Blocks yet, so when `extensionCartUpdate` causes the
`cart/extensions` endpoint to get hit, nothing will happen.
Much like adding data to the Store API (described in more detail in
[Exposing your data in the Store API](./extend-rest-api-add-data.md).) we can add the callback
by invoking the `register_update_callback` method on the `ExtendRestApi` class from WooCommerce Blocks.
We have written a function called `redeem_points` which applies a discount to the WooCommerce cart. This function does
not return anything. Note, the actual implementation of this function is not the focus of this document, so has been
omitted. All that is important to note is that it modifies the WooCommerce cart.
```PHP
<?php
use Automattic\WooCommerce\Blocks\Package;
use Automattic\WooCommerce\Blocks\Domain\Services\ExtendRestApi;
function redeem_points( $points ) {
/* Do some processing here that applies a discount to the WC cart based on the value of $points */
}
add_action('woocommerce_blocks_loaded', function() {
// ExtendRestApi is stored in the container as a shared instance between the API and consumers.
// You shouldn't initiate your own ExtendRestApi instance using `new ExtendRestApi` but should always use the shared instance from the Package dependency injection container.
$extend = Package::container()->get( ExtendRestApi::class );
$extend->register_update_callback(
[
'namespace' => 'super-coupons',
'callback' => function( $data ) {
redeem_points( $data['points'] );
},
]
);
} );
```
Now that this is registered, when the button is pressed, the `cart/extensions` endpoint is hit, with a `namespace` of
`super-coupons` our `redeem_points` function will be executed. After this has finished processing, the client-side cart
will be updated by WooCommerce Blocks.