From ce04872b66b9068958354a31edd348a6e07ab53a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Maneiro?= <583546+oandregal@users.noreply.github.com> Date: Thu, 8 Feb 2024 09:42:24 +0100 Subject: [PATCH 1/5] Update search label --- packages/dataviews/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dataviews/README.md b/packages/dataviews/README.md index e476546c514ce..a002e22e14dbd 100644 --- a/packages/dataviews/README.md +++ b/packages/dataviews/README.md @@ -232,7 +232,7 @@ Array of operations that can be performed upon each record. Each action is an ob ## Other properties - `search`: whether the search input is enabled. `true` by default. -- `searchLabel`: what text to show in the search input. "Filter list" by default. +- `searchLabel`: what text to show in the search input. "Search" by default. - `getItemId`: function that receives an item and returns an unique identifier for it. By default, it uses the `id` of the item as unique identifier. If it's not, the consumer should provide their own. - `isLoading`: whether the data is loading. `false` by default. - `supportedLayouts`: array of layouts supported. By default, all are: `table`, `grid`, `list`. From ad7d37d56c7d2867d06ba962fa2512a7d14352e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Maneiro?= <583546+oandregal@users.noreply.github.com> Date: Thu, 8 Feb 2024 09:45:23 +0100 Subject: [PATCH 2/5] render optional --- packages/dataviews/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dataviews/README.md b/packages/dataviews/README.md index a002e22e14dbd..6e18d7dbae4b4 100644 --- a/packages/dataviews/README.md +++ b/packages/dataviews/README.md @@ -194,7 +194,7 @@ 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. +- `render`: function that renders the field. Optional, `getValue` will be used if `render` is not defined. - `elements`: the set of valid values for the field's value. - `type`: the type of the field. Used to generate the proper filters. Only `enumeration` available at the moment. See "Field types". - `enableSorting`: whether the data can be sorted by the given field. True by default. From efa7ed7f2ef5c094907510143fc8f28f977913be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Maneiro?= <583546+oandregal@users.noreply.github.com> Date: Thu, 8 Feb 2024 16:26:24 +0100 Subject: [PATCH 3/5] More updates --- packages/dataviews/README.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/packages/dataviews/README.md b/packages/dataviews/README.md index 6e18d7dbae4b4..9f9e5f4883a20 100644 --- a/packages/dataviews/README.md +++ b/packages/dataviews/README.md @@ -20,13 +20,7 @@ npm install @wordpress/dataviews --save onChangeView={ onChangeView } fields={ fields } actions={ [ trashPostAction ] } - search={ false } - searchLabel="Filter list" - getItemId={ ( item ) => item.id } - isLoading={ isLoadingData } supportedLayouts={ [ 'table' ] } - deferredRendering={ true } - onSelectionChange={ ( items ) => { /* ... */ } } /> ``` @@ -88,7 +82,7 @@ Example: - `hiddenFields`: the `id` of the fields that are hidden in the UI. - `layout`: config that is specific to a particular layout type. - `mediaField`: used by the `grid` and `list` layouts. The `id` of the field to be used for rendering each card's media. - - `primaryField`: used by the `grid` and `list` layouts. The `id` of the field to be highlighted in each card/list item. + - `primaryField`: used by the `table`, `grid` and `list` layouts. The `id` of the field to be highlighted in each card/list item. ### onChangeView: syncing view and data From 26038ebf3cbd6b60c64dc4b128300aec8a84e28b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Maneiro?= <583546+oandregal@users.noreply.github.com> Date: Thu, 8 Feb 2024 16:32:33 +0100 Subject: [PATCH 4/5] Only show the required properties in the example --- packages/dataviews/README.md | 146 ++++++++++++++++++----------------- 1 file changed, 75 insertions(+), 71 deletions(-) diff --git a/packages/dataviews/README.md b/packages/dataviews/README.md index 9f9e5f4883a20..1f6ef459ee2df 100644 --- a/packages/dataviews/README.md +++ b/packages/dataviews/README.md @@ -15,16 +15,17 @@ npm install @wordpress/dataviews --save ```js ``` -## Data +## Properties + +### Data The dataset to work with, represented as a one-dimensional array. @@ -39,12 +40,57 @@ Example: By default, dataviews would use each record's `id` as an unique identifier. If it's not, the consumer should provide a `getItemId` function that returns one. See "Other props" section. -## Pagination Info +### Fields -- `totalItems`: the total number of items in the datasets. -- `totalPages`: the total number of pages, taking into account the total items in the dataset and the number of items per page provided by the user. +The fields describe the visible items for each record in the dataset. + +Example: + +```js +[ + { + id: 'date', + header: __( 'Date' ), + getValue: ( { item } ) => item.date, + render: ( { item } ) => { + return ( + + ); + }, + enableHiding: false + }, + { + id: 'author', + header: __( 'Author' ), + getValue: ( { item } ) => item.author, + render: ( { item } ) => { + return ( + { item.author } + ); + }, + type: 'enumeration', + elements: [ + { value: 1, label: 'Admin' } + { value: 2, label: 'User' } + ] + enableSorting: false + } +] +``` + +- `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. Optional, `getValue` will be used if `render` is not defined. +- `elements`: the set of valid values for the field's value. +- `type`: the type of the field. Used to generate the proper filters. Only `enumeration` available at the moment. See "Field types". +- `enableSorting`: whether the data can be sorted by the given field. True by default. +- `enableHiding`: whether the field can be hidden. True by default. +- `filterBy`: configuration for the filters. + - `operators`: the list of operators supported by the field. + - `isPrimary`: whether it is a primary filter. A primary filter is always visible and is not listed in the "Add filter" component, except for the list layout where it behaves like a secondary filter. -## View +### View The view object configures how the dataset is visible to the user. @@ -141,63 +187,13 @@ function MyCustomPageTable() { data={ records } view={ view } onChangeView={ setView } - "..." + // ... /> ); } ``` -## Fields - -The fields describe the visible items for each record in the dataset. - -Example: - -```js -[ - { - id: 'date', - header: __( 'Date' ), - getValue: ( { item } ) => item.date, - render: ( { item } ) => { - return ( - - ); - }, - enableHiding: false - }, - { - id: 'author', - header: __( 'Author' ), - getValue: ( { item } ) => item.author, - render: ( { item } ) => { - return ( - { item.author } - ); - }, - type: 'enumeration', - elements: [ - { value: 1, label: 'Admin' } - { value: 2, label: 'User' } - ] - enableSorting: false - } -] -``` - -- `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. Optional, `getValue` will be used if `render` is not defined. -- `elements`: the set of valid values for the field's value. -- `type`: the type of the field. Used to generate the proper filters. Only `enumeration` available at the moment. See "Field types". -- `enableSorting`: whether the data can be sorted by the given field. True by default. -- `enableHiding`: whether the field can be hidden. True by default. -- `filterBy`: configuration for the filters. - - `operators`: the list of operators supported by the field. - - `isPrimary`: whether it is a primary filter. A primary filter is always visible and is not listed in the "Add filter" component, except for the list layout where it behaves like a secondary filter. - -## Actions +### Actions Array of operations that can be performed upon each record. Each action is an object with the following properties: @@ -211,19 +207,12 @@ Array of operations that can be performed upon each record. Each action is an ob - `RenderModal`: ReactElement, optional. If an action requires that some UI be rendered in a modal, it can provide a component which takes as props the record as `item` and a `closeModal` function. When this prop is provided, the `callback` property is 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. -## Types +### Pagination Info -- Layout types: - - `table`: the view uses a table layout. - - `grid`: the view uses a grid layout. - - `list`: the view uses a list layout. -- Field types: - - `enumeration`: the field value should be taken and can be filtered from a closed list of elements. -- Operator types: - - `in`: operator to be used in filters for fields of type `enumeration`. - - `notIn`: operator to be used in filters for fields of type `enumeration`. +- `totalItems`: the total number of items in the datasets. +- `totalPages`: the total number of pages, taking into account the total items in the dataset and the number of items per page provided by the user. -## Other properties +### Other properties - `search`: whether the search input is enabled. `true` by default. - `searchLabel`: what text to show in the search input. "Search" by default. @@ -234,6 +223,21 @@ Array of operations that can be performed upon each record. Each action is an ob - `onSelectionChange`: callback that signals the user selected one of more items, and takes them as parameter. So far, only the `list` view implements it. - `onDetailsChange`: callback that signals the user triggered the details for one of more items, and takes them as paremeter. So far, only the `list` view implements it. + +## Types + +- View/Layout types: + - `table`: the view uses a table layout. + - `grid`: the view uses a grid layout. + - `list`: the view uses a list layout. + +- Field types: + - `enumeration`: the field value should be taken and can be filtered from a closed list of elements. + +- Operator types: + - `in`: operator to be used in filters for fields of type `enumeration`. + - `notIn`: operator to be used in filters for fields of type `enumeration`. + ## Contributing to this package This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects. From e73e98d737811964bbb36b3f98230b739c71773a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Maneiro?= <583546+oandregal@users.noreply.github.com> Date: Thu, 8 Feb 2024 17:05:43 +0100 Subject: [PATCH 5/5] Restructure --- packages/dataviews/README.md | 157 +++++++++++++++++++++++------------ 1 file changed, 102 insertions(+), 55 deletions(-) diff --git a/packages/dataviews/README.md b/packages/dataviews/README.md index 1f6ef459ee2df..bbc2271db6573 100644 --- a/packages/dataviews/README.md +++ b/packages/dataviews/README.md @@ -12,52 +12,69 @@ npm install @wordpress/dataviews --save ## Usage -```js - +```jsx +const Example = () => { + + // Declare data, fields, etc. + + return ( + + ); +} ``` ## Properties -### Data +### `data`: `Object[]` The dataset to work with, represented as a one-dimensional array. Example: ```js -[ - { id: 1, title: "Title", ... }, - { ... } +const data = [ + { + id: 1, + title: "Title", + author: "Admin", + date: "2012-04-23T18:25:43.511Z" + }, + { /* ... */ } ] ``` -By default, dataviews would use each record's `id` as an unique identifier. If it's not, the consumer should provide a `getItemId` function that returns one. See "Other props" section. +By default, dataviews would use each record's `id` as an unique identifier. If it's not, the consumer should provide a `getItemId` function that returns one. -### Fields +### `fields`: `Object[]` The fields describe the visible items for each record in the dataset. Example: ```js -[ +const fields = [ + { + id: 'title', + header: 'Title', + getValue: ({ item }) => item.title, + enableHiding: false, + }, { id: 'date', - header: __( 'Date' ), + header: 'Date', getValue: ( { item } ) => item.date, render: ( { item } ) => { return ( ); - }, - enableHiding: false + } }, { id: 'author', @@ -78,6 +95,8 @@ Example: ] ``` +Each field is an object with the following properties: + - `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. @@ -90,47 +109,50 @@ Example: - `operators`: the list of operators supported by the field. - `isPrimary`: whether it is a primary filter. A primary filter is always visible and is not listed in the "Add filter" component, except for the list layout where it behaves like a secondary filter. -### View +### `view`: `object` The view object configures how the dataset is visible to the user. Example: ```js -{ +const view = { type: 'table', - perPage: 5, - page: 1, - sort: { - field: 'date', - direction: 'desc', - }, search: '', filters: [ { field: 'author', operator: 'in', value: 2 }, { field: 'status', operator: 'in', value: 'publish,draft' } ], + page: 1, + perPage: 5, + sort: { + field: 'date', + direction: 'desc', + }, hiddenFields: [ 'date', 'featured-image' ], layout: {}, } ``` -- `type`: view type, one of `table`, `grid`, `list`. See "View types". -- `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`. +Properties: + +- `type`: view type, one of `table`, `grid`, `list`. See "Layout types". - `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. One of `in`, `notIn`. See "Operator types". - `value`: the actual value selected by the user. +- `perPage`: number of records to show per page. +- `page`: the page that is visible. +- `sort`: + - `field`: the field used for sorting the dataset. + - `direction`: the direction to use for sorting, one of `asc` or `desc`. - `hiddenFields`: the `id` of the fields that are hidden in the UI. - `layout`: config that is specific to a particular layout type. - `mediaField`: used by the `grid` and `list` layouts. The `id` of the field to be used for rendering each card's media. - - `primaryField`: used by the `table`, `grid` and `list` layouts. The `id` of the field to be highlighted in each card/list item. + - `primaryField`: used by the `table`, `grid` and `list` layouts. The `id` of the field to be highlighted in each row/card/item. -### onChangeView: syncing view and data +### `onChangeView`: `function` The view is a representation of the visible state of the dataset: what type of layout is used to display it (table, grid, etc.), how the dataset is filtered, how it is sorted or paginated. @@ -193,9 +215,11 @@ function MyCustomPageTable() { } ``` -### Actions +### `actions`: `Object[]` -Array of operations that can be performed upon each record. Each action is an object with the following properties: +Collection 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`. @@ -207,36 +231,59 @@ Array of operations that can be performed upon each record. Each action is an ob - `RenderModal`: ReactElement, optional. If an action requires that some UI be rendered in a modal, it can provide a component which takes as props the record as `item` and a `closeModal` function. When this prop is provided, the `callback` property is 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. -### Pagination Info +### `paginationInfo`: `Object` - `totalItems`: the total number of items in the datasets. - `totalPages`: the total number of pages, taking into account the total items in the dataset and the number of items per page provided by the user. -### Other properties +### `search`: `boolean` + +Whether the search input is enabled. `true` by default. + +### `searchLabel`: `string` + +What text to show in the search input. "Search" by default. + +### `getItemId`: `function` + +Function that receives an item and returns an unique identifier for it. By default, it uses the `id` of the item as unique identifier. If it's not, the consumer should provide their own. -- `search`: whether the search input is enabled. `true` by default. -- `searchLabel`: what text to show in the search input. "Search" by default. -- `getItemId`: function that receives an item and returns an unique identifier for it. By default, it uses the `id` of the item as unique identifier. If it's not, the consumer should provide their own. -- `isLoading`: whether the data is loading. `false` by default. -- `supportedLayouts`: array of layouts supported. By default, all are: `table`, `grid`, `list`. -- `deferredRendering`: whether the items should be rendered asynchronously. Useful when there's a field that takes a lot of time (e.g.: previews). `false` by default. -- `onSelectionChange`: callback that signals the user selected one of more items, and takes them as parameter. So far, only the `list` view implements it. -- `onDetailsChange`: callback that signals the user triggered the details for one of more items, and takes them as paremeter. So far, only the `list` view implements it. +### `isLoading`: `boolean` +Whether the data is loading. `false` by default. + +### `supportedLayouts`: `String[]` + +Array of layouts supported. By default, all are: `table`, `grid`, `list`. + +### `deferredRendering`: `boolean` + +Whether the items should be rendered asynchronously. Useful when there's a field that takes a lot of time (e.g.: previews). `false` by default. + +### `onSelectionChange`: `function` + +Callback that signals the user selected one of more items, and takes them as parameter. So far, only the `list` view implements it. + +### `onDetailsChange`: `function` + +Callback that signals the user triggered the details for one of more items, and takes them as paremeter. So far, only the `list` view implements it. ## Types -- View/Layout types: - - `table`: the view uses a table layout. - - `grid`: the view uses a grid layout. - - `list`: the view uses a list layout. +### Layouts + +- `table`: the view uses a table layout. +- `grid`: the view uses a grid layout. +- `list`: the view uses a list layout. + +### Fields + +- `enumeration`: the field value should be taken and can be filtered from a closed list of elements. -- Field types: - - `enumeration`: the field value should be taken and can be filtered from a closed list of elements. +### Operators -- Operator types: - - `in`: operator to be used in filters for fields of type `enumeration`. - - `notIn`: operator to be used in filters for fields of type `enumeration`. +- `in`: operator to be used in filters for fields of type `enumeration`. +- `notIn`: operator to be used in filters for fields of type `enumeration`. ## Contributing to this package