Skip to content
This repository has been archived by the owner on Feb 23, 2024. It is now read-only.

Latest commit

 

History

History
211 lines (136 loc) · 8.84 KB

collections.md

File metadata and controls

211 lines (136 loc) · 8.84 KB

📣 Announcement: New documentation location

The documentation for WooCommerce Blocks has moved to the WooCommerce monorepo.

Please refer to the documentation in the new location as the files in this repository will no longer be updated and the repository will be archived.

Collections Store (wc/store/collections)

Table of Contents

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 storew ith 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.