Skip to content

Commit

Permalink
[Data views]: Update actions API (#56026)
Browse files Browse the repository at this point in the history 
* [Data views]: Update actions API

* Update packages/edit-site/src/components/dataviews/README.md

Co-authored-by: André <[email protected]>

---------

Co-authored-by: André <[email protected]>
  • Loading branch information
@ntsekouras @oandregal
ntsekouras and oandregal authored Nov 10, 2023
1 parent f3f2607 commit 1e3bfc2
Show file tree
Hide file tree
Showing 4 changed files with 44 additions and 40 deletions.
12 changes: 6 additions & 6 deletions packages/edit-site/src/components/actions/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ export function useTrashPostAction() {
isEligible( { status } ) {
return status !== 'trash';
},
async perform( post ) {
async callback( post ) {
try {
await deleteEntityRecord(
'postType',
Expand Down Expand Up @@ -81,7 +81,7 @@ export function usePermanentlyDeletePostAction() {
isEligible( { status } ) {
return status === 'trash';
},
async perform( post ) {
async callback( post ) {
try {
await deleteEntityRecord(
'postType',
Expand Down Expand Up @@ -132,7 +132,7 @@ export function useRestorePostAction() {
isEligible( { status } ) {
return status === 'trash';
},
async perform( post ) {
async callback( post ) {
await editEntityRecord( 'postType', post.type, post.id, {
status: 'draft',
} );
Expand Down Expand Up @@ -183,7 +183,7 @@ export const viewPostAction = {
isEligible( post ) {
return post.status !== 'trash';
},
perform( post ) {
callback( post ) {
document.location.href = post.link;
},
};
Expand All @@ -197,7 +197,7 @@ export function useEditPostAction() {
isEligible( { status } ) {
return status !== 'trash';
},
perform( post ) {
callback( post ) {
history.push( {
postId: post.id,
postType: post.type,
Expand All @@ -222,7 +222,7 @@ export const postRevisionsAction = {
post?._links?.[ 'version-history' ]?.[ 0 ]?.count ?? 0;
return lastRevisionId && revisionsCount > 1;
},
perform( post ) {
callback( post ) {
const href = addQueryArgs( 'revision.php', {
revision: post?._links?.[ 'predecessor-version' ]?.[ 0 ]?.id,
} );
Expand Down
64 changes: 33 additions & 31 deletions packages/edit-site/src/components/dataviews/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ This file documents the DataViews UI component, which provides an API to render
```js
<DataViews
data={ pages }
isLoading= { isLoadingPages }
isLoading={ isLoadingPages }
view={ view }
onChangeView={ onChangeView }
fields={ fields }
Expand All @@ -16,7 +16,7 @@ This file documents the DataViews UI component, which provides an API to render

## Data

The dataset to work with, represented as a one-dimensional array.
The dataset to work with, represented as a one-dimensional array.

Example:

Expand Down Expand Up @@ -53,19 +53,19 @@ Example:
}
```

- `type`: view type, one of `list` or `grid`.
- `perPage`: number of records to show per page.
- `page`: the page that is visible.
- `sort.field`: field used for sorting the dataset.
- `sort.direction`: the direction to use for sorting, one of `asc` or `desc`.
- `search`: the text search applied to the dataset.
- `filters`: the filters applied to the dataset. Each item describes:
- `field`: which field this filter is bound to.
- `operator`: which type of filter it is. Only `in` available at the moment.
- `vaule`: the actual value selected by the user.
- `visibleFilters`: the `id` of the filters that are visible in the UI.
- `hiddenFields`: the `id` of the fields that are hidden in the UI.
- `layout`: ...
- `type`: view type, one of `list` or `grid`.
- `perPage`: number of records to show per page.
- `page`: the page that is visible.
- `sort.field`: field used for sorting the dataset.
- `sort.direction`: the direction to use for sorting, one of `asc` or `desc`.
- `search`: the text search applied to the dataset.
- `filters`: the filters applied to the dataset. Each item describes:
- `field`: which field this filter is bound to.
- `operator`: which type of filter it is. Only `in` available at the moment.
- `vaule`: the actual value selected by the user.
- `visibleFilters`: the `id` of the filters that are visible in the UI.
- `hiddenFields`: the `id` of the fields that are hidden in the UI.
- `layout`: ...

### View <=> data

Expand All @@ -74,7 +74,7 @@ The view is a representation of the visible state of the dataset. Note, however,
The following example shows how a view object is used to query the WordPress REST API via the entities abstraction. The same can be done with any other data provider.

```js
function MyCustomPageList() {
function MyCustomPageList() {
const [ view, setView ] = useState( {
type: 'list',
perPage: 5,
Expand Down Expand Up @@ -167,23 +167,25 @@ Example:
]
```

- `id`: identifier for the field. Unique.
- `header`: the field's name to be shown in the UI.
- `getValue`: function that returns the value of the field.
- `render`: function that renders the field.
- `elements`: the set of valid values for the field's value.
- `filters`: what filter operators are available for the user to use over this field. Only `in` available at the moment.
- `enableSorting`: whether the data can be sorted by the given field. True by default.
- `enableHiding`: whether the field can be hidden. True by default.
- `id`: identifier for the field. Unique.
- `header`: the field's name to be shown in the UI.
- `getValue`: function that returns the value of the field.
- `render`: function that renders the field.
- `elements`: the set of valid values for the field's value.
- `filters`: what filter operators are available for the user to use over this field. Only `in` available at the moment.
- `enableSorting`: whether the data can be sorted by the given field. True by default.
- `enableHiding`: whether the field can be hidden. True by default.

## Actions

Array of operations that can be performed upon each record. Each action is an object with the following properties:

- `id`: string, required. Unique identifier of the action. For example, `move-to-trash`.
- `label`: string, required. User facing description of the action. For example, `Move to Trash`.
- `isPrimary`: boolean, optional. Whether the action should be listed inline (primary) or in hidden in the more actions menu (secondary).
- `icon`: icon to show for primary actions. It's required for a primary action, otherwise the action would be considered secondary.
- `isEligible`: function, optional. Whether the action can be performed for a given record. If not present, the action is considered to be eligible for all items. It takes the given record as input.
- `isDestructive`: boolean, optional. Whether the action can delete data, in which case the UI would communicate it via red color.
- `perform`: function, required. Function that takes the record as input and performs the required action.
- `id`: string, required. Unique identifier of the action. For example, `move-to-trash`.
- `label`: string, required. User facing description of the action. For example, `Move to Trash`.
- `isPrimary`: boolean, optional. Whether the action should be listed inline (primary) or in hidden in the more actions menu (secondary).
- `icon`: icon to show for primary actions. It's required for a primary action, otherwise the action would be considered secondary.
- `isEligible`: function, optional. Whether the action can be performed for a given record. If not present, the action is considered to be eligible for all items. It takes the given record as input.
- `isDestructive`: boolean, optional. Whether the action can delete data, in which case the UI would communicate it via red color.
- `callback`: function, required. Callback function that takes the record as input and performs the required action.
- `RenderModal`: ReactElement, optional. If an action requires to render contents in a modal, can provide a component which takes as input the record and a `closeModal` function. If this prop is provided, the `callback` property would be ignored.
- `hideModalHeader`: boolean, optional. This property is used in combination with `RenderModal` and controls the visibility of the modal's header. If the action renders a modal and doesn't hide the header, the action's label is going to be used in the modal's header.
6 changes: 4 additions & 2 deletions packages/edit-site/src/components/dataviews/item-actions.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@ export default function ItemActions( { item, actions } ) {
key={ action.id }
action={ action }
item={ item }
onClick={ () => action.perform( item ) }
onClick={ () => action.callback( item ) }
/>
);
} ) }
Expand All @@ -129,7 +129,9 @@ export default function ItemActions( { item, actions } ) {
key={ action.id }
action={ action }
item={ item }
onClick={ () => action.perform( item ) }
onClick={ () =>
action.callback( item )
}
/>
);
} ) }
Expand Down
2 changes: 1 addition & 1 deletion packages/edit-site/src/components/page-templates/template-actions.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ export function useResetTemplateAction() {
isPrimary: true,
icon: backup,
isEligible: isTemplateRevertable,
async perform( template ) {
async callback( template ) {
try {
await revertTemplate( template, { allowUndo: false } );
await saveEditedEntityRecord(
Expand Down

0 comments on commit 1e3bfc2

Please sign in to comment.