Add documentation for ExperimentalDiscountsMeta, cart/extensions endpoint, and extensionCartUpdate
#4377
Conversation
opr
added
status: needs review
focus: documentation
|
Size Change: +154 kB (+15%) Total Size: 1.15 MB
ℹ️ View Unchanged
|
There was a problem hiding this comment.
Thank you for writing this PR Thomas! it's super valuable to have those docs this early.
However, I strongly suggest we align our documentation to a single template. This is something that Darren, Allen, and I discussed and iterated on to make our docs more approachable/structured to WordPress developers who are new to the JS world and those type of extensibility points on general.
| @@ -0,0 +1,90 @@ | |||
| # Updating the cart with the Store API | |||
There was a problem hiding this comment.
To keep consistency with the rest of our codebase, can we frame this doc as:
- Problem: What problem are we seeing here, this should be fairly easy to do since we only create new points After an existing problem.
- Solution: Describes the solution, can reference other documents.
- Basic Usage: The most minimal solution that can do the job.
- Things to consider: Any gotchas or things that people might need to know.
- API Definition: Full API docs in a table, see other documents.
- Putting it all together: A full example touching on all options that can be copy-pasted.
There was a problem hiding this comment.
Thanks Nadir, I've updated the document now to follow this format. I feel like there's going to be way too much to cover in the Putting it all together section, and a lot of irrelevant information not relating to this part of the API. I did not want to go into too much detail about the things not directly related to this, so I've omitted some parts that are covered in other documents, and also not gone into detail about the implementation of my example methods.
I also feel like there's quite a bit of overlap and duplication of the Basic usage and Putting it all together section, but this is probably OK.
| If you're an extension developer, and your extension does some server-side processing as a result of some client-side | ||
| input, then you may want to use the `cart/extensions` endpoint to signal to | ||
| the Store API that some processing needs to take place. |
There was a problem hiding this comment.
I'm struggling to understand this part. As a plugin developer, I fail to understand where my code would fall into this, and what would be Cart/Checkout blocks responsibility.
There was a problem hiding this comment.
I think the new format may help to illustrate the problem a bit better. What do you think?
| You are the author of an extension that automatically applies valid coupons to a user's cart when they press a | ||
| button. | ||
|
|
||
| Your extension adds a button to the sidebar in the Cart and Checkout blocks using the [`DiscountsMeta`](./available-slot-fills.md) Slot. | ||
|
|
||
| When this button is clicked, you want the server to do some work to figure out which coupons the customer is eligible | ||
| for, and then apply them to the cart. | ||
|
|
||
| When this is done, you expect to see the updated cart data in the client. |
There was a problem hiding this comment.
This fits very well in the intro of this document and severs as a good introduction to what problem are you solving here. After an initial read, developers can just skip that section straight into basic usage or API definition.
There was a problem hiding this comment.
Fixed by the new format, I think.
| ## Registering a callback to run when the `cart/extensions` endpoint is hit | ||
| 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).) you may add the callback | ||
| by invoking the `register_update_callback` method on the `ExtendRestApi` class from WooCommerce Blocks. | ||
|
|
||
| ```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' => 'my-extensions-unique-namespace', | ||
| 'callback' => /* Add your callable here */ | ||
| ] | ||
| ) | ||
| } ); | ||
| ``` |
There was a problem hiding this comment.
This would fit very well in the basic usage section as a sub item.
There was a problem hiding this comment.
Fixed by the new format.
| The method takes a single argument, an associative array. | ||
|
|
||
| The associative array must have the following entries: | ||
| - `namespace` (string) - The unique namespace of your extension. | ||
| - `callback` (Callable) - The function/method (or Callable) that will be executed when the `cart/extensions` endpoint is | ||
| hit with a `namespace` that matches your extension's. 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. | ||
| More information on how data gets passed from the client to the callback will be detailed over the next sections. |
There was a problem hiding this comment.
This could probably live in the API definition part.
There was a problem hiding this comment.
Fixed by the new format.
| ## Making the request to the `cart/extensions` endpoint | ||
| When you wish to make a request to the endpoint, you should do it by calling the `extensionCartUpdate` function, available | ||
| from `@woocommerce/blocks-checkout`. |
There was a problem hiding this comment.
This, with the JS example below, can be moved into the basic usage section with the argument breakdown into API definition.
There was a problem hiding this comment.
Fixed by the new format.
| ## Why can't I just POST to `cart/extensions` directly? | ||
| This endpoint returns an object representing the customer's cart, WooCommerce Blocks will then update the client-side | ||
| stores with the new cart data. The methods to do this are not available to third party extensions, which is why you must | ||
| use the `extensionCartUpdate` method. |
There was a problem hiding this comment.
This can be part of the "Problem" section.
It also doesn't do a good job of explaining why you can't update Cart block yourself, which is to protect the block from getting broken by a malfunctioning plugin.
There was a problem hiding this comment.
Fixed by the new format, and also more detail about why they can't update it has been added to the Problem section, and also mentioned again in the Things to consider section.
github-actions
bot
added
status: ready to merge
and removed
status: needs review
labels
Co-authored-by: Seghir Nadir <nadir.seghir@gmail.com>
This PR adds documentation for the
ExperimentalDiscountsMetaSlot/Fill, theextensionCartUpdateJS function, and thecart/extensionsendpoint, and theregister_update_callbackmethod on theExtendRestApiclass.How to test the changes in this Pull Request:
Changelog