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.
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.
Install the module
npm install @wordpress/core-data --saveThis package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.
Below is an example of a component which simply renders a list of authors:
const { withSelect } = wp.data;
function MyAuthorsListBase( { authors } ) {
return (
<ul>
{ authors.map( ( author ) => (
<li key={ author.id }>{ author.name }</li>
) ) }
</ul>
);
}
const MyAuthorsList = withSelect( ( select ) => ( {
authors: select( 'core' ).getAuthors(),
} ) )( MyAuthorsListBase );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.
Parameters
- kind
string: Kind of the deleted entity. - name
string: Name of the deleted entity. - recordId
string: Record ID of the deleted entity. - query
?Object: Special query parameters for the DELETE API call. - options
[Object]: Delete options. - options.__unstableFetch
[Function]: Internal use only. Function to call instead ofapiFetch(). Must return a control descriptor.
# editEntityRecord
Returns an action object that triggers an edit to an entity record.
Parameters
- kind
string: Kind of the edited entity record. - name
string: Name of the edited entity record. - recordId
number: Record ID of the edited entity record. - edits
Object: The edits. - options
Object: Options for the edit. - options.undoIgnore
boolean: Whether to ignore the edit in undo history or not.
Returns
Object: Action object.
# receiveAutosaves
Returns an action object used in signalling that the autosaves for a post have been received.
Parameters
- postId
number: The id of the post that is parent to the autosave. - autosaves
Array|Object: An array of autosaves or singular autosave object.
Returns
Object: Action object.
# receiveCurrentTheme
Returns an action object used in signalling that the current theme has been received.
Parameters
- currentTheme
Object: The current theme.
Returns
Object: Action object.
# receiveCurrentUser
Returns an action used in signalling that the current user has been received.
Parameters
- currentUser
Object: Current user object.
Returns
Object: Action object.
# receiveEmbedPreview
Returns an action object used in signalling that the preview data for a given URl has been received.
Parameters
- url
string: URL to preview the embed for. - preview
*: Preview data.
Returns
Object: Action object.
# receiveEntityRecords
Returns an action object used in signalling that entity records have been received.
Parameters
- kind
string: Kind of the received entity. - name
string: Name of the received entity. - records
Array|Object: Records received. - query
?Object: Query Object. - invalidateCache
?boolean: Should invalidate query caches. - edits
?Object: Edits to reset.
Returns
Object: Action object.
# receiveThemeSupports
Returns an action object used in signalling that the index has been received.
Parameters
- themeSupports
Object: Theme support for the current theme.
Returns
Object: Action object.
# receiveUploadPermissions
Returns an action object used in signalling that Upload permissions have been received.
Parameters
- hasUploadPermissions
boolean: Does the user have permission to upload files?
Returns
Object: Action object.
# receiveUserPermission
Returns an action object used in signalling that the current user has permission to perform an action on a REST resource.
Parameters
- key
string: A key that represents the action and REST resource. - isAllowed
boolean: Whether or not the user can perform the action.
Returns
Object: Action object.
# receiveUserQuery
Returns an action object used in signalling that authors have been received.
Parameters
- queryID
string: Query ID. - users
Array|Object: Users received.
Returns
Object: Action object.
# redo
Action triggered to redo the last undoed edit to an entity record, if any.
# saveEditedEntityRecord
Action triggered to save an entity record's edits.
Parameters
- kind
string: Kind of the entity. - name
string: Name of the entity. - recordId
Object: ID of the record. - options
Object: Saving options.
# saveEntityRecord
Action triggered to save an entity record.
Parameters
- kind
string: Kind of the received entity. - name
string: Name of the received entity. - record
Object: Record to be saved. - options
Object: Saving options. - options.isAutosave
[boolean]: Whether this is an autosave. - options.__unstableFetch
[Function]: Internal use only. Function to call instead ofapiFetch(). Must return a control descriptor.
# undo
Action triggered to undo the last edit to an entity record, if any.
The following selectors are available on the object returned by wp.data.select( 'core' ):
# canUser
Returns whether the current user can perform the given action on the given REST resource.
Calling this may trigger an OPTIONS request to the REST API via the
canUser() resolver.
https://developer.wordpress.org/rest-api/reference/
Parameters
- state
Object: Data state. - action
string: Action to check. One of: 'create', 'read', 'update', 'delete'. - resource
string: REST resource to check, e.g. 'media' or 'posts'. - id
string=: Optional ID of the rest resource to check.
Returns
boolean|undefined: Whether or not the user can perform the action, orundefinedif the OPTIONS request is still being made.
# getAuthors
Returns all available authors.
Parameters
- state
Object: Data state. - query
Object|undefined: Optional object of query parameters to include with request.
Returns
Array: Authors list.
# getAutosave
Returns the autosave for the post and author.
Parameters
- state
Object: State tree. - postType
string: The type of the parent post. - postId
number: The id of the parent post. - authorId
number: The id of the author.
Returns
?Object: The autosave for the post and author.
# getAutosaves
Returns the latest autosaves for the post.
May return multiple autosaves since the backend stores one autosave per author for each post.
Parameters
- state
Object: State tree. - postType
string: The type of the parent post. - postId
number: The id of the parent post.
Returns
?Array: An array of autosaves for the post, or undefined if there is none.
# getCurrentTheme
Return the current theme.
Parameters
- state
Object: Data state.
Returns
Object: The current theme.
# getCurrentUser
Returns the current user.
Parameters
- state
Object: Data state.
Returns
Object: Current user object.
# getEditedEntityRecord
Returns the specified entity record, merged with its edits.
Parameters
- state
Object: State tree. - kind
string: Entity kind. - name
string: Entity name. - recordId
number: Record ID.
Returns
Object?: The entity record, merged with its edits.
# getEmbedPreview
Returns the embed preview for the given URL.
Parameters
- state
Object: Data state. - url
string: Embedded URL.
Returns
*: Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API.
# getEntitiesByKind
Returns whether the entities for the give kind are loaded.
Parameters
- state
Object: Data state. - kind
string: Entity kind.
Returns
boolean: Whether the entities are loaded
# getEntity
Returns the entity object given its kind and name.
Parameters
- state
Object: Data state. - kind
string: Entity kind. - name
string: Entity name.
Returns
Object: Entity
# getEntityRecord
Returns the Entity's record object by key. Returns null if the value is not
yet received, undefined if the value entity is known to not exist, or the
entity object if it exists and is received.
Parameters
- state
Object: State tree - kind
string: Entity kind. - name
string: Entity name. - key
number: Record's key - query
?Object: Optional query.
Returns
Object?: Record.
# getEntityRecordEdits
Returns the specified entity record's edits.
Parameters
- state
Object: State tree. - kind
string: Entity kind. - name
string: Entity name. - recordId
number: Record ID.
Returns
Object?: The entity record's edits.
# getEntityRecordNonTransientEdits
Returns the specified entity record's non transient edits.
Transient edits don't create an undo level, and are not considered for change detection. They are defined in the entity's config.
Parameters
- state
Object: State tree. - kind
string: Entity kind. - name
string: Entity name. - recordId
number: Record ID.
Returns
Object?: The entity record's non transient edits.
# getEntityRecords
Returns the Entity's records.
Parameters
- state
Object: State tree - kind
string: Entity kind. - name
string: Entity name. - query
?Object: Optional terms query.
Returns
?Array: Records.
# getLastEntityDeleteError
Returns the specified entity record's last delete error.
Parameters
- state
Object: State tree. - kind
string: Entity kind. - name
string: Entity name. - recordId
number: Record ID.
Returns
Object?: The entity record's save error.
# getLastEntitySaveError
Returns the specified entity record's last save error.
Parameters
- state
Object: State tree. - kind
string: Entity kind. - name
string: Entity name. - recordId
number: Record ID.
Returns
Object?: The entity record's save error.
# getRawEntityRecord
Returns the entity's record object by key, with its attributes mapped to their raw values.
Parameters
- state
Object: State tree. - kind
string: Entity kind. - name
string: Entity name. - key
number: Record's key.
Returns
Object?: Object with the entity's raw attributes.
# getRedoEdit
Returns the next edit from the current undo offset for the entity records edits history, if any.
Parameters
- state
Object: State tree.
Returns
Object?: The edit.
# getReferenceByDistinctEdits
Returns a new reference when edited values have changed. This is useful in inferring where an edit has been made between states by comparison of the return values using strict equality.
Usage
const hasEditOccurred = (
getReferenceByDistinctEdits( beforeState ) !==
getReferenceByDistinctEdits( afterState )
);
Parameters
- state
Object: Editor state.
Returns
*: A value whose reference will change only when an edit occurs.
# getThemeSupports
Return theme supports data in the index.
Parameters
- state
Object: Data state.
Returns
*: Index data.
# getUndoEdit
Returns the previous edit from the current undo offset for the entity records edits history, if any.
Parameters
- state
Object: State tree.
Returns
Object?: The edit.
# getUserQueryResults
Returns all the users returned by a query ID.
Parameters
- state
Object: Data state. - queryID
string: Query ID.
Returns
Array: Users list.
# hasEditsForEntityRecord
Returns true if the specified entity record has edits, and false otherwise.
Parameters
- state
Object: State tree. - kind
string: Entity kind. - name
string: Entity name. - recordId
number: Record ID.
Returns
boolean: Whether the entity record has edits or not.
# hasEntityRecords
Returns true if records have been received for the given set of parameters, or false otherwise.
Parameters
- state
Object: State tree - kind
string: Entity kind. - name
string: Entity name. - query
?Object: Optional terms query.
Returns
boolean: Whether entity records have been received.
# hasFetchedAutosaves
Returns true if the REST request for autosaves has completed.
Parameters
- state
Object: State tree. - postType
string: The type of the parent post. - postId
number: The id of the parent post.
Returns
boolean: True if the REST request was completed. False otherwise.
# hasRedo
Returns true if there is a next edit from the current undo offset for the entity records edits history, and false otherwise.
Parameters
- state
Object: State tree.
Returns
boolean: Whether there is a next edit or not.
# hasUndo
Returns true if there is a previous edit from the current undo offset for the entity records edits history, and false otherwise.
Parameters
- state
Object: State tree.
Returns
boolean: Whether there is a previous edit or not.
# hasUploadPermissions
Deprecated since 5.0. Callers should use the more generic
canUser()selector instead ofhasUploadPermissions(), e.g.canUser( 'create', 'media' ).
Returns whether the current user can upload media.
Calling this may trigger an OPTIONS request to the REST API via the
canUser() resolver.
https://developer.wordpress.org/rest-api/reference/
Parameters
- state
Object: Data state.
Returns
boolean: Whether or not the user can upload media. Defaults totrueif the OPTIONS request is being made.
# isAutosavingEntityRecord
Returns true if the specified entity record is autosaving, and false otherwise.
Parameters
- state
Object: State tree. - kind
string: Entity kind. - name
string: Entity name. - recordId
number: Record ID.
Returns
boolean: Whether the entity record is autosaving or not.
# isDeletingEntityRecord
Returns true if the specified entity record is deleting, and false otherwise.
Parameters
- state
Object: State tree. - kind
string: Entity kind. - name
string: Entity name. - recordId
number: Record ID.
Returns
boolean: Whether the entity record is deleting or not.
# isPreviewEmbedFallback
Determines if the returned preview is an oEmbed link fallback.
WordPress can be configured to return a simple link to a URL if it is not embeddable. We need to be able to determine if a URL is embeddable or not, based on what we get back from the oEmbed preview API.
Parameters
- state
Object: Data state. - url
string: Embedded URL.
Returns
boolean: Is the preview for the URL an oEmbed link fallback.
# isRequestingEmbedPreview
Returns true if a request is in progress for embed preview data, or false otherwise.
Parameters
- state
Object: Data state. - url
string: URL the preview would be for.
Returns
boolean: Whether a request is in progress for an embed preview.
# isSavingEntityRecord
Returns true if the specified entity record is saving, and false otherwise.
Parameters
- state
Object: State tree. - kind
string: Entity kind. - name
string: Entity name. - recordId
number: Record ID.
Returns
boolean: Whether the entity record is saving or not.
