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

Collections Store (wc/store/collections)

Table of Contents

• Overview
• Usage
• Actions
  • receiveCollection( namespace, resourceName, queryString, ids = [], items = [], replace = false )
  • receiveCollectionError
  • receiveLastModified
• Selectors
  • getFromState
  • getCollection
  • getCollectionHeader
  • getCollectionHeaders
  • getCollectionError
  • getCollectionLastModified

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:

const { COLLECTIONS_STORE_KEY } = window.wc.wcBlocksData;

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

• 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

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

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

const { dispatch } = useDispatch( COLLECTIONS_STORE_KEY );
dispatch( receiveLastModified( timestamp ) );

Selectors

getFromState

This selector will return the state from the collections store.

Returns

• object: The state from the collections store 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.
  • 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).
  • type string: type of the collections ie items.

or

• array | null | undefined: Returns a fallback value (specified as a parameter) when the collection lacks matching headers for the provided arguments.

Example

const store = select( COLLECTIONS_STORE_KEY );
const state = store.getFromState( state, namespace, resourceName, queryString, ids, type, fallback );

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

• object: Returns the getFromState object (see getFromState).

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

• 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).

getCollectionHeaders

This selector will return the headers for a collection.

Returns

• object: Returns the getFromState object (see getFromState).

Example

const store = select( COLLECTIONS_STORE_KEY );
const headers = store.getCollectionHeaders( state, namespace, resourceName, queryString );

getCollectionError

This selector will return any error that occurred while fetching a collection.

Returns

• object: Returns the getFromState object (see getFromState).

Example

const store = select( COLLECTIONS_STORE_KEY );
const error = store.getCollectionError( state, namespace, resourceName, queryString );

getCollectionLastModified

This selector will return the last modified date for a collection.

Returns

• number: The last modified date for the collection, or 0 if there was no last modified date.

Example

const store = select( COLLECTIONS_STORE_KEY );
const lastModified = store.getCollectionLastModified( state, namespace, resourceName, queryString );

---

We're hiring! Come work with us!

🐞 Found a mistake, or have a suggestion? Leave feedback about this document here.