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

134 lines
6.4 KiB
Markdown
Raw Normal View History

Improve the data stores documentation (https://github.com/woocommerce/woocommerce-blocks/pull/11336) * Update data store docs * Link related docs to /docs/third-party-developers/extensibility/data-store * Improve data store overview * Remove obsolete entry * Update TOC of docs/third-party-developers/extensibility/data-store/store-notices.md * Update TOCs * Update link titles * Replace primary key with import statement * Optimise Validation Store description * Keep store IDs in title * Correct wrong key * Optimise data store docs overview * Explain the difference between cart and checkout store * Add example to Validation Store * Add example to Validation Store * Add overview text to collections.md * Add example to store-notices.md * Update TOC of store-notices.md * Update overview description of store-notices.md * Add code snippets for displaying the validationError message * Update data store docs * Link related docs to /docs/third-party-developers/extensibility/data-store * Improve data store overview * Remove obsolete entry * Update TOC of docs/third-party-developers/extensibility/data-store/store-notices.md * Update TOCs * Update link titles * Replace primary key with import statement * Optimise Validation Store description * Keep store IDs in title * Correct wrong key * Optimise data store docs overview * Explain the difference between cart and checkout store * Add example to Validation Store * Add example to Validation Store * Add overview text to collections.md * Add example to store-notices.md * Update TOC of store-notices.md * Update overview description of store-notices.md * Add code snippets for displaying the validationError message * Mention full link in assets/js/data/cart/README.md * Changed Store-Notices to Store Notices
2023-10-26 02:37:13 +00:00
# Collections Store (`wc/store/collections`) <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [Overview](#overview)
- [Usage](#usage)
- [Actions](#actions)
- [receiveCollection( namespace, resourceName, queryString, ids = \[\], items = \[\], replace = false )](#receivecollection-namespace-resourcename-querystring-ids---items---replace--false-)
- [receiveCollectionError](#receivecollectionerror)
- [receiveLastModified](#receivelastmodified)
Improve the data stores documentation (https://github.com/woocommerce/woocommerce-blocks/pull/11336) * Update data store docs * Link related docs to /docs/third-party-developers/extensibility/data-store * Improve data store overview * Remove obsolete entry * Update TOC of docs/third-party-developers/extensibility/data-store/store-notices.md * Update TOCs * Update link titles * Replace primary key with import statement * Optimise Validation Store description * Keep store IDs in title * Correct wrong key * Optimise data store docs overview * Explain the difference between cart and checkout store * Add example to Validation Store * Add example to Validation Store * Add overview text to collections.md * Add example to store-notices.md * Update TOC of store-notices.md * Update overview description of store-notices.md * Add code snippets for displaying the validationError message * Update data store docs * Link related docs to /docs/third-party-developers/extensibility/data-store * Improve data store overview * Remove obsolete entry * Update TOC of docs/third-party-developers/extensibility/data-store/store-notices.md * Update TOCs * Update link titles * Replace primary key with import statement * Optimise Validation Store description * Keep store IDs in title * Correct wrong key * Optimise data store docs overview * Explain the difference between cart and checkout store * Add example to Validation Store * Add example to Validation Store * Add overview text to collections.md * Add example to store-notices.md * Update TOC of store-notices.md * Update overview description of store-notices.md * Add code snippets for displaying the validationError message * Mention full link in assets/js/data/cart/README.md * Changed Store-Notices to Store Notices
2023-10-26 02:37:13 +00:00
- [Selectors](#selectors)
- [getCollection](#getcollection)
- [getCollectionHeader](#getcollectionheader)
## Overview
The Collections Store allows to retrieve product-related collections within WooCommerce Blocks.
## Usage
To utilize this store you will import the COLLECTIONS_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 { COLLECTIONS_STORE_KEY } = window.wc.wcBlocksData;
Improve the data stores documentation (https://github.com/woocommerce/woocommerce-blocks/pull/11336) * Update data store docs * Link related docs to /docs/third-party-developers/extensibility/data-store * Improve data store overview * Remove obsolete entry * Update TOC of docs/third-party-developers/extensibility/data-store/store-notices.md * Update TOCs * Update link titles * Replace primary key with import statement * Optimise Validation Store description * Keep store IDs in title * Correct wrong key * Optimise data store docs overview * Explain the difference between cart and checkout store * Add example to Validation Store * Add example to Validation Store * Add overview text to collections.md * Add example to store-notices.md * Update TOC of store-notices.md * Update overview description of store-notices.md * Add code snippets for displaying the validationError message * Update data store docs * Link related docs to /docs/third-party-developers/extensibility/data-store * Improve data store overview * Remove obsolete entry * Update TOC of docs/third-party-developers/extensibility/data-store/store-notices.md * Update TOCs * Update link titles * Replace primary key with import statement * Optimise Validation Store description * Keep store IDs in title * Correct wrong key * Optimise data store docs overview * Explain the difference between cart and checkout store * Add example to Validation Store * Add example to Validation Store * Add overview text to collections.md * Add example to store-notices.md * Update TOC of store-notices.md * Update overview description of store-notices.md * Add code snippets for displaying the validationError message * Mention full link in assets/js/data/cart/README.md * Changed Store-Notices to Store Notices
2023-10-26 02:37:13 +00:00
```
## Actions
### receiveCollection( namespace, resourceName, queryString, ids = [], items = [], replace = false )
This will return an action object for the given arguments used in dispatching the collection results to the store.
> ⚠️ You should rarely have to dispatch this action directly as it is used by the resolver for the `getCollection` selector.
#### _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.
- _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_ <!-- 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 ) );
```
Improve the data stores documentation (https://github.com/woocommerce/woocommerce-blocks/pull/11336) * Update data store docs * Link related docs to /docs/third-party-developers/extensibility/data-store * Improve data store overview * Remove obsolete entry * Update TOC of docs/third-party-developers/extensibility/data-store/store-notices.md * Update TOCs * Update link titles * Replace primary key with import statement * Optimise Validation Store description * Keep store IDs in title * Correct wrong key * Optimise data store docs overview * Explain the difference between cart and checkout store * Add example to Validation Store * Add example to Validation Store * Add overview text to collections.md * Add example to store-notices.md * Update TOC of store-notices.md * Update overview description of store-notices.md * Add code snippets for displaying the validationError message * Update data store docs * Link related docs to /docs/third-party-developers/extensibility/data-store * Improve data store overview * Remove obsolete entry * Update TOC of docs/third-party-developers/extensibility/data-store/store-notices.md * Update TOCs * Update link titles * Replace primary key with import statement * Optimise Validation Store description * Keep store IDs in title * Correct wrong key * Optimise data store docs overview * Explain the difference between cart and checkout store * Add example to Validation Store * Add example to Validation Store * Add overview text to collections.md * Add example to store-notices.md * Update TOC of store-notices.md * Update overview description of store-notices.md * Add code snippets for displaying the validationError message * Mention full link in assets/js/data/cart/README.md * Changed Store-Notices to Store Notices
2023-10-26 02:37:13 +00:00
## Selectors
### getCollection
This selector will return the collection for the given arguments. It has a sibling resolver, so if the selector has never been resolved, the resolver will make a request to the server for the collection and dispatch results to the store.
#### _Returns_ <!-- 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`.
- _query_ `object`: The query arguments for the collection, eg. `{ order: 'ASC', sortBy: Price }`.
- _ids_ `array`: If the collection route has placeholders for ids you provide the values for those placeholders in this array (in order).
### getCollectionHeader
This selector will return a header from the collection response using the given arguments. It has a sibling resolver that will resolve `getCollection` using the arguments if that has never been resolved.
#### _Returns_ <!-- omit in toc -->
- `undefined`: If the collection has headers but not a matching header for the given `header` argument, then `undefined` will be returned.
or
- `null`: If the collection does not have any matching headers for the given arguments, then `null` is returned.
or
- `object`: If the collection has a matching header for the given arguments, then an object is returned with the following properties:
- _namespace_ `string`: The route namespace for the collection, eg. `/wc/blocks`.
- _resourceName_ `string`: The resource name for the collection, eg. `products/attributes`.
- _header_ `string`: The header key for the header.
- _query_ `Object`: The query arguments for the collection, eg. `{ order: 'ASC', sortBy: Price }`.
- _ids_ `Array`: If the collection route has placeholders for ids you provide the values for those placeholders in this array (in order).
<!-- FEEDBACK -->
---
[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/blocks/feature-flags-and-experimental-interfaces.md)
<!-- /FEEDBACK -->