💦 FULL SET: Block editor/reference guides/packages/packages core data

Core Data is a data module intended to simplify access to and manipulation of core WordPress entities. It registers its own store and provides a number of selectors which resolve data from the WordPress REST API automatically, along with dispatching action creators to manipulate data. Core data is shipped with TypeScript definitions for WordPress data types.

Used in combination with features of the data module such as subscribe or higher-order components, it enables a developer to easily add data into the logic and display of their plugin.

Installation

Install the module

npm install @wordpress/core-data --save

This package assumes that your code will run in an ES2015+ environment. If you’re using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Example

Below is an example of a component which simply renders a list of authors:

const { useSelect } = wp.data;

function MyAuthorsListBase() {
    const authors = useSelect( ( select ) => {
        return select( 'core' ).getUsers( { who: 'authors' } );
    }, [] );

    if ( ! authors ) {
        return null;
    }

    return (
        <ul>
            { authors.map( ( author ) => (
                <li key={ author.id }>{ author.name }</li>
            ) ) }
        </ul>
    );
}

What’s an entity?

An entity represents a data source. Each item within the entity is called an entity record. Available entities are defined in rootEntitiesConfig at ./src/entities.js.

As of right now, the default entities defined by this package map to the REST API handbook, though there is nothing in the design that prevents it from being used to interact with any other API.

What follows is a description of some of the properties of rootEntitiesConfig.

Connecting the entity with the data source

baseURL

Type: string.
Example: '/wp/v2/users'.

This property maps the entity to a given endpoint, taking its relative URL as value.

baseURLParams

Type: object.
Example: { context: 'edit' }.

Additional parameters to the request, added as a query string. Each property will be converted into a field/value pair. For example, given the baseURL: '/wp/v2/users' and the baseURLParams: { context: 'edit' } the URL would be /wp/v2/users?context=edit.

key

Type: string.
Example: 'slug'.

The entity engine aims to convert the API response into a number of entity records. Responses can come in different shapes, which are processed differently.

Responses that represent a single object map to a single entity record. For example:

{
    "title": "...",
    "description": "...",
    "...": "..."
}

Responses that represent a collection shaped as an array, map to as many entity records as elements of the array. For example:

[
    { "id": 1, "name": "...", "...": "..." },
    { "id": 2, "name": "...", "...": "..." },
    { "id": 3, "name": "...", "...": "..." }
]

There are also cases in which a response represents a collection shaped as an object, whose key is one of the property’s values. Each of the nested objects should be its own entity record. For this case not to be confused with single object/entities, the entity configuration must provide the property key that holds the value acting as the object key. In the following example, the slug property’s value is acting as the object key, hence the entity config must declare key: 'slug' for each nested object to be processed as an individual entity record:

{
    "publish": { "slug": "publish", "name": "Published", "...": "..." },
    "draft": { "slug": "draft", "name": "Draft", "...": "..." },
    "future": { "slug": "future", "name": "Future", "...": "..." }
}

Interacting with entity records

Entity records are unique. For entities that are collections, it’s assumed that each record has an id property which serves as an identifier to manage it. If the entity defines a key, that property would be used as its identifier instead of the assumed id.

name

Type: string.
Example: user.

The name of the entity. To be used in the utilities that interact with it (selectors, actions, hooks).

kind

Type: string.
Example: root.

Entities can be grouped by kind. To be used in the utilities that interact with them (selectors, actions, hooks).

The package provides general methods to interact with the entities (getEntityRecords, getEntityRecord, etc.) by leveraging the kind and name properties:

// Get the record collection for the user entity.
wp.data.select( 'core' ).getEntityRecords( 'root', 'user' );

// Get a single record for the user entity.
wp.data.select( 'core' ).getEntityRecord( 'root', 'user', recordId );

plural

Type: string.
Example: statuses.

In addition to the general utilities (getEntityRecords, getEntityRecord, etc.), the package dynamically creates nicer-looking methods to interact with the entity records of the root kind, both the collection and single records. Compare the general and nicer-looking methods as follows:

// Collection
wp.data.select( 'core' ).getEntityRecords( 'root', 'user' );
wp.data.select( 'core' ).getUsers();

// Single record
wp.data.select( 'core' ).getEntityRecord( 'root', 'user', recordId );
wp.data.select( 'core' ).getUser( recordId );

Sometimes, the pluralized form of an entity is not regular (it is not formed by adding a -s suffix). The plural property of the entity config allows to declare an alternative pluralized form for the dynamic methods created for the entity. For example, given the status entity that declares the statuses plural, there are the following methods created for it:

// Collection
wp.data.select( 'core' ).getStatuses();

// Single record
wp.data.select( 'core' ).getStatus( recordId );

Actions

The following set of dispatching action creators are available on the object returned by wp.data.dispatch( 'core' ):

addEntities

Returns an action object used in adding new entities.

Parameters

entities Array: Entities received.

Returns

Object: Action object.

deleteEntityRecord

Action triggered to delete an entity record.