Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Documentation] Add examples for core/data package #42639

Draft
wants to merge 14 commits into
base: trunk
Choose a base branch
from
Draft

[Documentation] Add examples for core/data package #42639

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
3fab15b
Adds examples for the following selectors:
ryanwelcher Jul 12, 2022
c89ac94
Merge branch 'trunk' into feature/add-examples-for-core-data
ryanwelcher Jul 12, 2022
91f0a28
Add example for getCurrentUser selector.
ryanwelcher Jul 12, 2022
f41aa05
Add example for getEntityRecord.
ryanwelcher Jul 13, 2022
c794120
Add example for getEntityRecords.
ryanwelcher Jul 13, 2022
4d70a55
Add example for getEmbedPreview.
ryanwelcher Jul 13, 2022
fac66cc
Merge branch 'trunk' into feature/add-examples-for-core-data
ryanwelcher Jul 13, 2022
57619a7
Merge branch 'trunk' into feature/add-examples-for-core-data
ryanwelcher Jul 19, 2022
5261a7e
Add example for isRequestingEmbedPreview.
ryanwelcher Jul 19, 2022
b4d3190
Merge branch 'trunk' into feature/add-examples-for-core-data
ryanwelcher Jul 22, 2022
1cfb5db
Merge branch 'trunk' into feature/add-examples-for-core-data
ryanwelcher Jul 25, 2022
f02334d
Merge branch 'trunk' into feature/add-examples-for-core-data
ryanwelcher Jul 25, 2023
b89320c
Merge branch 'trunk' into feature/add-examples-for-core-data
ryanwelcher Jul 18, 2024
c5b24f6
Add example for useEntityProp.
ryanwelcher Jul 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
285 changes: 285 additions & 0 deletions docs/reference-guides/data/data-core.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,26 @@ Calling this may trigger an OPTIONS request to the REST API via the

<https://developer.wordpress.org/rest-api/reference/>

_Usage_

```js
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';
import { __ } from '@wordpress/i18n';

const ExampleComponent = () => {
const canUpdatePost = useSelect( ( select ) =>
select( coreDataStore ).canUser( 'create', 'media' )
);

return canUpdatePost ? (
<div>{ __( 'This user can upload media' ) }</div>
) : (
<div>{ __( 'This user cannot upload media' ) }</div>
);
};
```

_Parameters_

- _state_ `State`: Data state.
Expand All @@ -36,6 +56,26 @@ Calling this may trigger an OPTIONS request to the REST API via the

<https://developer.wordpress.org/rest-api/reference/>

_Usage_

```js
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';
import { __ } from '@wordpress/i18n';

const ExampleComponent = () => {
const canEdit = useSelect( ( select ) =>
select( coreDataStore ).canUserEditEntityRecord( 'postType', 'post', 1 )
);

return canEdit ? (
<div>{ __( 'This user can edit post ID 1' ) }</div>
) : (
<div>{ __( 'This user cannot edit post ID 1' ) }</div>
);
};
```

_Parameters_

- _state_ `State`: Data state.
Expand Down Expand Up @@ -66,6 +106,28 @@ _Returns_

Returns the autosave for the post and author.

_Usage_

```js
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';
import { sprintf, __ } from '@wordpress/i18n';

const ExampleComponent = () => {
const postId = 1;
const userId = 1;
const autosave = useSelect( ( select ) =>
select( coreDataStore ).getAutosave( 'post', postId, userId )
);

return autosave ? (
<div>{ sprintf( 'Last autosave: %s', autosave.date ) }</div>
) : (
<div>{ __( 'There is no Autosave for this post and this user' ) }</div>
;
};
```

_Parameters_

- _state_ `State`: State tree.
Expand All @@ -84,6 +146,31 @@ Returns the latest autosaves for the post.
May return multiple autosaves since the backend stores one autosave per
author for each post.

_Usage_

```js
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';
import { sprintf, __ } from '@wordpress/i18n';

const ExampleComponent = () => {
const postId = 1;
const autosaves = useSelect( ( select ) =>
select( coreDataStore ).getAutosaves( 'post', postId )
);

return (
<ul>
{ autosaves?.map( ( autosave ) => (
<li key={ autosave.ID }>
{ sprintf( 'Date: %s', autosave.date ) }
</li>
) ) }
</ul>
);
};
```

_Parameters_

- _state_ `State`: State tree.
Expand All @@ -98,6 +185,28 @@ _Returns_

Retrieve the list of registered block pattern categories.

_Usage_

```js
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';
import { __ } from '@wordpress/i18n';

const ExampleComponent = () => {
const blockPatternCategories = useSelect( ( select ) =>
select( coreDataStore ).getBlockPatternCategories()
);

return (
<ul>
{ blockPatternCategories?.map( ( pattern ) => (
<li key={ pattern.name }>{ pattern.label }</li>
) ) }
</ul>
);
};
```

_Parameters_

- _state_ `State`: Data state.
Expand All @@ -110,6 +219,28 @@ _Returns_

Retrieve the list of registered block patterns.

_Usage_

```js
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';
import { __ } from '@wordpress/i18n';

const ExampleComponent = () => {
const blockPatterns = useSelect( ( select ) =>
select( coreDataStore ).getBlockPatterns()
);

return (
<ul>
{ blockPatterns?.map( ( pattern ) => (
<li key={ pattern.name }>{ pattern.title }</li>
) ) }
</ul>
);
};
```

_Parameters_

- _state_ `State`: Data state.
Expand All @@ -122,6 +253,31 @@ _Returns_

Return the current theme.

_Usage_

```js
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';
import { sprintf, __ } from '@wordpress/i18n';

const ExampleComponent = () => {
const currentTheme = useSelect( ( select ) =>
select( coreDataStore ).getCurrentTheme()
);

return currentTheme ? (
<div>
{ sprintf(
__( 'Current Theme: %s' ),
currentTheme?.name.rendered
) }
</div>
) : (
<div>{ __( 'Loading theme information…' ) }</div>
);
};
```

_Parameters_

- _state_ `State`: Data state.
Expand All @@ -134,6 +290,26 @@ _Returns_

Returns the current user.

_Usage_

```jsx
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';
import { sprintf, __ } from '@wordpress/i18n';

const ExampleComponent = () => {
const currentUser = useSelect( ( select ) =>
select( coreDataStore ).getCurrentUser()
);

return currentUser ? (
<div>{ sprintf( __( 'Hello, %s!' ), currentUser.name ) }</div>
) : (
<div>{ __( 'Loading User information…' ) }</div>
);
};
```

_Parameters_

- _state_ `State`: Data state.
Expand Down Expand Up @@ -161,6 +337,27 @@ _Returns_

Returns the embed preview for the given URL.

_Usage_

```js
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';

const ExampleComponent = () => {
const embedPreview = useSelect( ( select ) =>
select( coreDataStore ).getEmbedPreview(
'https://twitter.com/wordpress'
)
);

return embedPreview ? (
<div dangerouslySetInnerHTML={ { __html: embedPreview.html } } />
) : (
<div>{ __( 'Loading Tweets…' ) }</div>
);
};
```

_Parameters_

- _state_ `State`: Data state.
Expand Down Expand Up @@ -234,6 +431,41 @@ 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.

_Usage_

```jsx
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';
import { sprintf, __ } from '@wordpress/i18n';

const ExampleComponent = () => {
const { postData, termData } = useSelect( ( select ) => {
return {
postData: select( coreDataStore ).getEntityRecord(
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should consider marking getEntityRecord and getEntityRecords selectors as internal and promote related React hooks useEntityRecord and useEntityRecords instead. Those selectors still could be useful outside of React components, though. @adamziel, what do you think?

Maybe there is a way to reference those two concepts in some nice way.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These selectors are used across many @wordpress packages, unfortunately React hooks won't work in custom store actions.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

promote related React hooks useEntityRecord and useEntityRecords instead.

This is a great idea! They're more succinct and easier to think of than useSelect + getEntityRecord

postType',
'post',
1
),
termData: select( coreDataStore ).getEntityRecord(
'taxonomy',
'category',
1
),
};
} );

return postData && termData ? (
<div>
{ sprintf( __( 'Post Title:, %s' ), postData?.title.rendered ) }
<br />
{ sprintf( __( 'Term Name: %s' ), termData?.name ) }
</div>
) : (
<div>{ __( 'Loading…' ) }</div>
;
};
```

_Parameters_

- _state_ `State`: State tree
Expand Down Expand Up @@ -284,6 +516,31 @@ _Returns_

Returns the Entity's records.

_Usage_

```js
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';

const ExampleComponent = () => {
const posts = useSelect( ( select ) =>
select( coreDataStore ).getEntityRecords( 'postType', 'post', {
per_page: 5,
} )
);

return posts ? (
<ul>
{ posts.map( ( post ) => {
return <li key={ post?.id }>{ post?.title.rendered }</li>;
} ) }
</ul>
) : (
<div>{ __( 'Loading…' ) }</div>
);
};
```

_Parameters_

- _state_ `State`: State tree
Expand Down Expand Up @@ -537,6 +794,34 @@ _Returns_
Returns true if a request is in progress for embed preview data, or false
otherwise.

_Usage_

```js
import { store as coreDataStore } from '@wordpress/core-data';
import { useSelect } from '@wordpress/data';

const ExampleComponent = () => {
const { embedPreview, isRequestingEmbedPreview } = useSelect(
( select ) => {
return {
embedPreview: select( coreDataStore ).getEmbedPreview(
'https://twitter.com/wordpress'
),
isRequestingEmbedPreview: select(
coreDataStore
).isRequestingEmbedPreview( 'https://twitter.com/wordpress' ),
};
}
);

return ! isRequestingEmbedPreview && embedPreview ? (
<div dangerouslySetInnerHTML={ { __html: embedPreview.html } } />
) : (
<div>{ __( 'Loading Tweets…' ) }</div>
);
};
```

_Parameters_

- _state_ `State`: Data state.
Expand Down
Loading