From 7bf91094eb8b24ed939ce5d48c686ee524be5ba4 Mon Sep 17 00:00:00 2001 From: Ryan Welcher Date: Mon, 5 Aug 2024 13:30:21 -0400 Subject: [PATCH 1/3] Add post type and taxonomy selectors. --- docs/reference-guides/data/data-core.md | 97 +++++++++++++++++++++++++ 1 file changed, 97 insertions(+) diff --git a/docs/reference-guides/data/data-core.md b/docs/reference-guides/data/data-core.md index a2bcf31b4d2e2..24252387f4e71 100644 --- a/docs/reference-guides/data/data-core.md +++ b/docs/reference-guides/data/data-core.md @@ -4,6 +4,103 @@ Namespace: `core`. ## Selectors +There are a number of user-friendly selectors that are wrappers of the more generic `getEntityRecord` and `getEntityRecords` that can be used to retrieve information for the various entities. + +### getPostType + +Returns the information for a given post type. + +_Usage_ + + import { useSelect } from '@wordpress/data'; + import { store as coreDataStore } from '@wordpress/core-data'; + + const postType = useSelect( + ( select ) => select( coreDataStore ).getPostType( 'post' ) + + // Equivalent to: select( coreDataStore ).getEntityRecord( 'root', 'postType', 'post' ) + ); + +_Parameters_ + +- postType `string` + +_Returns_ + +- `EntityRecord | undefined`: Record. + +### getPostTypes + +Returns the information for post types. + +_Usage_ + + import { useSelect } from '@wordpress/data'; + import { store as coreDataStore } from '@wordpress/core-data'; + + const postTypes = useSelect( ( select ) => { + return select( coreDataStore ).getPostTypes( { per_page: 4 } ); + + // Equivalent to: + // select( coreDataStore ).getEntityRecords( 'root', 'postType', { per_page: 4 } ); + } ); + +_Parameters_ + +- _query_ `GetRecordsHttpQuery`: Optional terms query. If requesting specific fields, fields must always include the ID. For valid query parameters see the [Reference](https://developer.wordpress.org/rest-api/reference/) in the REST API Handbook and select the entity kind. Then see the arguments available for "List [Entity kind]s". + +_Returns_ + +- `EntityRecord[] | null`: Records. + +### getTaxonomy + +Returns information for a given taxonomy. + +_Usage_ + + import { useSelect } from '@wordpress/data'; + import { store as coreDataStore } from '@wordpress/core-data'; + + const taxonomy = useSelect( ( select ) => { + return select( coreDataStore ).getTaxonomy( 'category' ); + + // Equivalent to: + // select( coreDataStore ).getEntityRecord( 'root', 'taxonomy', 'category' ); + } ); + +_Parameters_ + +- taxonomy `string` + +_Returns_ + +- `EntityRecord | undefined`: Record. + +### getTaxonomies + +Returns information for taxonomies. + +_Usage_ + + import { useSelect } from '@wordpress/data'; + import { store as coreDataStore } from '@wordpress/core-data'; + + const taxonomies = useSelect( ( select ) => { + return select( coreDataStore ).getTaxonomies( { type: 'post' } ); + + // Equivalent to: + // select( coreDataStore ).getEntityRecords( 'root', 'taxonomy', { type: 'post' } ); + } ); + +_Parameters_ + +- _query_ `GetRecordsHttpQuery`: Optional terms query. If requesting specific fields, fields must always include the ID. For valid query parameters see the [Reference](https://developer.wordpress.org/rest-api/reference/) in the REST API Handbook and select the entity kind. Then see the arguments available for "List [Entity kind]s". + +_Returns_ + +- `EntityRecord[] | null`: Records. + ### canUser From 928edc875a6e55f14f3a13f44a7a1b7fd2c2cd4e Mon Sep 17 00:00:00 2001 From: Ryan Welcher Date: Mon, 5 Aug 2024 13:35:17 -0400 Subject: [PATCH 2/3] Run docs build --- docs/reference-guides/data/data-core.md | 88 ++++++++++++------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/reference-guides/data/data-core.md b/docs/reference-guides/data/data-core.md index 24252387f4e71..1df27916cafae 100644 --- a/docs/reference-guides/data/data-core.md +++ b/docs/reference-guides/data/data-core.md @@ -103,7 +103,7 @@ _Returns_ -### canUser +#### canUser Returns whether the current user can perform the given action on the given REST resource. @@ -122,7 +122,7 @@ _Returns_ - `boolean | undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. -### canUserEditEntityRecord +#### canUserEditEntityRecord Returns whether the current user can edit the given entity. @@ -141,7 +141,7 @@ _Returns_ - `boolean | undefined`: Whether or not the user can edit, or `undefined` if the OPTIONS request is still being made. -### getAuthors +#### getAuthors > **Deprecated** since 11.3. Callers should use `select( 'core' ).getUsers({ who: 'authors' })` instead. @@ -156,7 +156,7 @@ _Returns_ - `ET.User[]`: Authors list. -### getAutosave +#### getAutosave Returns the autosave for the post and author. @@ -171,7 +171,7 @@ _Returns_ - `EntityRecord | undefined`: The autosave for the post and author. -### getAutosaves +#### getAutosaves Returns the latest autosaves for the post. @@ -187,7 +187,7 @@ _Returns_ - `Array< any > | undefined`: An array of autosaves for the post, or undefined if there is none. -### getBlockPatternCategories +#### getBlockPatternCategories Retrieve the list of registered block pattern categories. @@ -199,7 +199,7 @@ _Returns_ - `Array< any >`: Block pattern category list. -### getBlockPatterns +#### getBlockPatterns Retrieve the list of registered block patterns. @@ -211,7 +211,7 @@ _Returns_ - `Array< any >`: Block pattern list. -### getCurrentTheme +#### getCurrentTheme Return the current theme. @@ -223,7 +223,7 @@ _Returns_ - `any`: The current theme. -### getCurrentThemeGlobalStylesRevisions +#### getCurrentThemeGlobalStylesRevisions > **Deprecated** since WordPress 6.5.0. Callers should use `select( 'core' ).getRevisions( 'root', 'globalStyles', ${ recordKey } )` instead, where `recordKey` is the id of the global styles parent post. @@ -237,7 +237,7 @@ _Returns_ - `Array< object > | null`: The current global styles. -### getCurrentUser +#### getCurrentUser Returns the current user. @@ -249,7 +249,7 @@ _Returns_ - `ET.User< 'edit' >`: Current user object. -### getDefaultTemplateId +#### getDefaultTemplateId Returns the default template use to render a given query. @@ -262,7 +262,7 @@ _Returns_ - `string`: The default template id for the given query. -### getEditedEntityRecord +#### getEditedEntityRecord Returns the specified entity record, merged with its edits. @@ -277,7 +277,7 @@ _Returns_ - `ET.Updatable< EntityRecord > | false`: The entity record, merged with its edits. -### getEmbedPreview +#### getEmbedPreview Returns the embed preview for the given URL. @@ -290,7 +290,7 @@ _Returns_ - `any`: Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. -### getEntitiesByKind +#### getEntitiesByKind > **Deprecated** since WordPress 6.0. Use getEntitiesConfig instead @@ -305,7 +305,7 @@ _Returns_ - `Array< any >`: Array of entities with config matching kind. -### getEntitiesConfig +#### getEntitiesConfig Returns the loaded entities for the given kind. @@ -318,7 +318,7 @@ _Returns_ - `Array< any >`: Array of entities with config matching kind. -### getEntity +#### getEntity > **Deprecated** since WordPress 6.0. Use getEntityConfig instead @@ -334,7 +334,7 @@ _Returns_ - `any`: Entity config -### getEntityConfig +#### getEntityConfig Returns the entity config given its kind and name. @@ -348,7 +348,7 @@ _Returns_ - `any`: Entity config -### getEntityRecord +#### 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. @@ -364,7 +364,7 @@ _Returns_ - `EntityRecord | undefined`: Record. -### getEntityRecordEdits +#### getEntityRecordEdits Returns the specified entity record's edits. @@ -379,7 +379,7 @@ _Returns_ - `Optional< any >`: The entity record's edits. -### getEntityRecordNonTransientEdits +#### getEntityRecordNonTransientEdits Returns the specified entity record's non transient edits. @@ -396,7 +396,7 @@ _Returns_ - `Optional< any >`: The entity record's non transient edits. -### getEntityRecords +#### getEntityRecords Returns the Entity's records. @@ -411,7 +411,7 @@ _Returns_ - `EntityRecord[] | null`: Records. -### getEntityRecordsTotalItems +#### getEntityRecordsTotalItems Returns the Entity's total available records for a given query (ignoring pagination). @@ -426,7 +426,7 @@ _Returns_ - `number | null`: number | null. -### getEntityRecordsTotalPages +#### getEntityRecordsTotalPages Returns the number of available pages for the given query. @@ -441,7 +441,7 @@ _Returns_ - `number | null`: number | null. -### getLastEntityDeleteError +#### getLastEntityDeleteError Returns the specified entity record's last delete error. @@ -456,7 +456,7 @@ _Returns_ - `any`: The entity record's save error. -### getLastEntitySaveError +#### getLastEntitySaveError Returns the specified entity record's last save error. @@ -471,7 +471,7 @@ _Returns_ - `any`: The entity record's save error. -### getRawEntityRecord +#### getRawEntityRecord Returns the entity's record object by key, with its attributes mapped to their raw values. @@ -486,7 +486,7 @@ _Returns_ - `EntityRecord | undefined`: Object with the entity's raw attributes. -### getRedoEdit +#### getRedoEdit > **Deprecated** since 6.3 @@ -500,7 +500,7 @@ _Returns_ - `Optional< any >`: The edit. -### getReferenceByDistinctEdits +#### 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. @@ -519,7 +519,7 @@ _Returns_ - A value whose reference will change only when an edit occurs. -### getRevision +#### getRevision Returns a single, specific revision of a parent entity. @@ -536,7 +536,7 @@ _Returns_ - `RevisionRecord | Record< PropertyKey, never > | undefined`: Record. -### getRevisions +#### getRevisions Returns an entity's revisions. @@ -552,7 +552,7 @@ _Returns_ - `RevisionRecord[] | null`: Record. -### getThemeSupports +#### getThemeSupports Return theme supports data in the index. @@ -564,7 +564,7 @@ _Returns_ - `any`: Index data. -### getUndoEdit +#### getUndoEdit > **Deprecated** since 6.3 @@ -578,7 +578,7 @@ _Returns_ - `Optional< any >`: The edit. -### getUserPatternCategories +#### getUserPatternCategories Retrieve the registered user pattern categories. @@ -590,7 +590,7 @@ _Returns_ - `Array< UserPatternCategory >`: User patterns category array. -### getUserQueryResults +#### getUserQueryResults Returns all the users returned by a query ID. @@ -603,7 +603,7 @@ _Returns_ - `ET.User< 'edit' >[]`: Users list. -### hasEditsForEntityRecord +#### hasEditsForEntityRecord Returns true if the specified entity record has edits, and false otherwise. @@ -618,7 +618,7 @@ _Returns_ - `boolean`: Whether the entity record has edits or not. -### hasEntityRecords +#### hasEntityRecords Returns true if records have been received for the given set of parameters, or false otherwise. @@ -633,7 +633,7 @@ _Returns_ - `boolean`: Whether entity records have been received. -### hasFetchedAutosaves +#### hasFetchedAutosaves Returns true if the REST request for autosaves has completed. @@ -647,7 +647,7 @@ _Returns_ - `boolean`: True if the REST request was completed. False otherwise. -### hasRedo +#### hasRedo Returns true if there is a next edit from the current undo offset for the entity records edits history, and false otherwise. @@ -659,7 +659,7 @@ _Returns_ - `boolean`: Whether there is a next edit or not. -### hasUndo +#### hasUndo Returns true if there is a previous edit from the current undo offset for the entity records edits history, and false otherwise. @@ -671,7 +671,7 @@ _Returns_ - `boolean`: Whether there is a previous edit or not. -### isAutosavingEntityRecord +#### isAutosavingEntityRecord Returns true if the specified entity record is autosaving, and false otherwise. @@ -686,7 +686,7 @@ _Returns_ - `boolean`: Whether the entity record is autosaving or not. -### isDeletingEntityRecord +#### isDeletingEntityRecord Returns true if the specified entity record is deleting, and false otherwise. @@ -701,7 +701,7 @@ _Returns_ - `boolean`: Whether the entity record is deleting or not. -### isPreviewEmbedFallback +#### isPreviewEmbedFallback Determines if the returned preview is an oEmbed link fallback. @@ -716,7 +716,7 @@ _Returns_ - `boolean`: Is the preview for the URL an oEmbed link fallback. -### isRequestingEmbedPreview +#### isRequestingEmbedPreview Returns true if a request is in progress for embed preview data, or false otherwise. @@ -729,7 +729,7 @@ _Returns_ - `boolean`: Whether a request is in progress for an embed preview. -### isSavingEntityRecord +#### isSavingEntityRecord Returns true if the specified entity record is saving, and false otherwise. From 15d62deca5d1c2171b96ca711d874bceea325b43 Mon Sep 17 00:00:00 2001 From: Ryan Welcher Date: Mon, 5 Aug 2024 14:33:07 -0400 Subject: [PATCH 3/3] Change order to fix heading issue. --- docs/reference-guides/data/data-core.md | 92 +++++++++++++------------ 1 file changed, 47 insertions(+), 45 deletions(-) diff --git a/docs/reference-guides/data/data-core.md b/docs/reference-guides/data/data-core.md index 1df27916cafae..f4138c49dc8d6 100644 --- a/docs/reference-guides/data/data-core.md +++ b/docs/reference-guides/data/data-core.md @@ -2,7 +2,7 @@ Namespace: `core`. -## Selectors +### Dynamically generated selectors There are a number of user-friendly selectors that are wrappers of the more generic `getEntityRecord` and `getEntityRecords` that can be used to retrieve information for the various entities. @@ -101,9 +101,11 @@ _Returns_ - `EntityRecord[] | null`: Records. +## Other Selectors + -#### canUser +### canUser Returns whether the current user can perform the given action on the given REST resource. @@ -122,7 +124,7 @@ _Returns_ - `boolean | undefined`: Whether or not the user can perform the action, or `undefined` if the OPTIONS request is still being made. -#### canUserEditEntityRecord +### canUserEditEntityRecord Returns whether the current user can edit the given entity. @@ -141,7 +143,7 @@ _Returns_ - `boolean | undefined`: Whether or not the user can edit, or `undefined` if the OPTIONS request is still being made. -#### getAuthors +### getAuthors > **Deprecated** since 11.3. Callers should use `select( 'core' ).getUsers({ who: 'authors' })` instead. @@ -156,7 +158,7 @@ _Returns_ - `ET.User[]`: Authors list. -#### getAutosave +### getAutosave Returns the autosave for the post and author. @@ -171,7 +173,7 @@ _Returns_ - `EntityRecord | undefined`: The autosave for the post and author. -#### getAutosaves +### getAutosaves Returns the latest autosaves for the post. @@ -187,7 +189,7 @@ _Returns_ - `Array< any > | undefined`: An array of autosaves for the post, or undefined if there is none. -#### getBlockPatternCategories +### getBlockPatternCategories Retrieve the list of registered block pattern categories. @@ -199,7 +201,7 @@ _Returns_ - `Array< any >`: Block pattern category list. -#### getBlockPatterns +### getBlockPatterns Retrieve the list of registered block patterns. @@ -211,7 +213,7 @@ _Returns_ - `Array< any >`: Block pattern list. -#### getCurrentTheme +### getCurrentTheme Return the current theme. @@ -223,7 +225,7 @@ _Returns_ - `any`: The current theme. -#### getCurrentThemeGlobalStylesRevisions +### getCurrentThemeGlobalStylesRevisions > **Deprecated** since WordPress 6.5.0. Callers should use `select( 'core' ).getRevisions( 'root', 'globalStyles', ${ recordKey } )` instead, where `recordKey` is the id of the global styles parent post. @@ -237,7 +239,7 @@ _Returns_ - `Array< object > | null`: The current global styles. -#### getCurrentUser +### getCurrentUser Returns the current user. @@ -249,7 +251,7 @@ _Returns_ - `ET.User< 'edit' >`: Current user object. -#### getDefaultTemplateId +### getDefaultTemplateId Returns the default template use to render a given query. @@ -262,7 +264,7 @@ _Returns_ - `string`: The default template id for the given query. -#### getEditedEntityRecord +### getEditedEntityRecord Returns the specified entity record, merged with its edits. @@ -277,7 +279,7 @@ _Returns_ - `ET.Updatable< EntityRecord > | false`: The entity record, merged with its edits. -#### getEmbedPreview +### getEmbedPreview Returns the embed preview for the given URL. @@ -290,7 +292,7 @@ _Returns_ - `any`: Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API. -#### getEntitiesByKind +### getEntitiesByKind > **Deprecated** since WordPress 6.0. Use getEntitiesConfig instead @@ -305,7 +307,7 @@ _Returns_ - `Array< any >`: Array of entities with config matching kind. -#### getEntitiesConfig +### getEntitiesConfig Returns the loaded entities for the given kind. @@ -318,7 +320,7 @@ _Returns_ - `Array< any >`: Array of entities with config matching kind. -#### getEntity +### getEntity > **Deprecated** since WordPress 6.0. Use getEntityConfig instead @@ -334,7 +336,7 @@ _Returns_ - `any`: Entity config -#### getEntityConfig +### getEntityConfig Returns the entity config given its kind and name. @@ -348,7 +350,7 @@ _Returns_ - `any`: Entity config -#### getEntityRecord +### 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. @@ -364,7 +366,7 @@ _Returns_ - `EntityRecord | undefined`: Record. -#### getEntityRecordEdits +### getEntityRecordEdits Returns the specified entity record's edits. @@ -379,7 +381,7 @@ _Returns_ - `Optional< any >`: The entity record's edits. -#### getEntityRecordNonTransientEdits +### getEntityRecordNonTransientEdits Returns the specified entity record's non transient edits. @@ -396,7 +398,7 @@ _Returns_ - `Optional< any >`: The entity record's non transient edits. -#### getEntityRecords +### getEntityRecords Returns the Entity's records. @@ -411,7 +413,7 @@ _Returns_ - `EntityRecord[] | null`: Records. -#### getEntityRecordsTotalItems +### getEntityRecordsTotalItems Returns the Entity's total available records for a given query (ignoring pagination). @@ -426,7 +428,7 @@ _Returns_ - `number | null`: number | null. -#### getEntityRecordsTotalPages +### getEntityRecordsTotalPages Returns the number of available pages for the given query. @@ -441,7 +443,7 @@ _Returns_ - `number | null`: number | null. -#### getLastEntityDeleteError +### getLastEntityDeleteError Returns the specified entity record's last delete error. @@ -456,7 +458,7 @@ _Returns_ - `any`: The entity record's save error. -#### getLastEntitySaveError +### getLastEntitySaveError Returns the specified entity record's last save error. @@ -471,7 +473,7 @@ _Returns_ - `any`: The entity record's save error. -#### getRawEntityRecord +### getRawEntityRecord Returns the entity's record object by key, with its attributes mapped to their raw values. @@ -486,7 +488,7 @@ _Returns_ - `EntityRecord | undefined`: Object with the entity's raw attributes. -#### getRedoEdit +### getRedoEdit > **Deprecated** since 6.3 @@ -500,7 +502,7 @@ _Returns_ - `Optional< any >`: The edit. -#### getReferenceByDistinctEdits +### 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. @@ -519,7 +521,7 @@ _Returns_ - A value whose reference will change only when an edit occurs. -#### getRevision +### getRevision Returns a single, specific revision of a parent entity. @@ -536,7 +538,7 @@ _Returns_ - `RevisionRecord | Record< PropertyKey, never > | undefined`: Record. -#### getRevisions +### getRevisions Returns an entity's revisions. @@ -552,7 +554,7 @@ _Returns_ - `RevisionRecord[] | null`: Record. -#### getThemeSupports +### getThemeSupports Return theme supports data in the index. @@ -564,7 +566,7 @@ _Returns_ - `any`: Index data. -#### getUndoEdit +### getUndoEdit > **Deprecated** since 6.3 @@ -578,7 +580,7 @@ _Returns_ - `Optional< any >`: The edit. -#### getUserPatternCategories +### getUserPatternCategories Retrieve the registered user pattern categories. @@ -590,7 +592,7 @@ _Returns_ - `Array< UserPatternCategory >`: User patterns category array. -#### getUserQueryResults +### getUserQueryResults Returns all the users returned by a query ID. @@ -603,7 +605,7 @@ _Returns_ - `ET.User< 'edit' >[]`: Users list. -#### hasEditsForEntityRecord +### hasEditsForEntityRecord Returns true if the specified entity record has edits, and false otherwise. @@ -618,7 +620,7 @@ _Returns_ - `boolean`: Whether the entity record has edits or not. -#### hasEntityRecords +### hasEntityRecords Returns true if records have been received for the given set of parameters, or false otherwise. @@ -633,7 +635,7 @@ _Returns_ - `boolean`: Whether entity records have been received. -#### hasFetchedAutosaves +### hasFetchedAutosaves Returns true if the REST request for autosaves has completed. @@ -647,7 +649,7 @@ _Returns_ - `boolean`: True if the REST request was completed. False otherwise. -#### hasRedo +### hasRedo Returns true if there is a next edit from the current undo offset for the entity records edits history, and false otherwise. @@ -659,7 +661,7 @@ _Returns_ - `boolean`: Whether there is a next edit or not. -#### hasUndo +### hasUndo Returns true if there is a previous edit from the current undo offset for the entity records edits history, and false otherwise. @@ -671,7 +673,7 @@ _Returns_ - `boolean`: Whether there is a previous edit or not. -#### isAutosavingEntityRecord +### isAutosavingEntityRecord Returns true if the specified entity record is autosaving, and false otherwise. @@ -686,7 +688,7 @@ _Returns_ - `boolean`: Whether the entity record is autosaving or not. -#### isDeletingEntityRecord +### isDeletingEntityRecord Returns true if the specified entity record is deleting, and false otherwise. @@ -701,7 +703,7 @@ _Returns_ - `boolean`: Whether the entity record is deleting or not. -#### isPreviewEmbedFallback +### isPreviewEmbedFallback Determines if the returned preview is an oEmbed link fallback. @@ -716,7 +718,7 @@ _Returns_ - `boolean`: Is the preview for the URL an oEmbed link fallback. -#### isRequestingEmbedPreview +### isRequestingEmbedPreview Returns true if a request is in progress for embed preview data, or false otherwise. @@ -729,7 +731,7 @@ _Returns_ - `boolean`: Whether a request is in progress for an embed preview. -#### isSavingEntityRecord +### isSavingEntityRecord Returns true if the specified entity record is saving, and false otherwise.