Skip to content

View config schema: centralize in PHP #81169

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

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

View config schema: centralize in PHP #81169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
43088fe
Generate view config reference docs from the REST controller schema
oandregal Aug 4, 2026
146f4b0
Extract the view config schema into a standalone PHP file
oandregal Aug 4, 2026
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
196 changes: 168 additions & 28 deletions docs/reference-guides/view-config-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ DataViews-powered admin screens (such as the Site Editor's Pages, Templates, Tem

The configuration is built per entity — identified by its kind (e.g. `postType`) and name (e.g. `page`) — and can be customized through the dynamic `get_entity_view_config_{$kind}_{$name}` filter, where the dynamic portions are lowercased: the `postType`/`page` entity maps to the `get_entity_view_config_posttype_page` filter. The editor retrieves the result through the `/wp/v2/view-config?kind={kind}&name={name}` REST API endpoint.

The property tables in this document are generated from the REST controller's schema, the single source of truth, by running `npm run docs:view-config-ref`.

Related docs:

- [Server-side view configuration filter](/docs/how-to-guides/curating-the-editor-experience/filters-and-hooks.md#server-side-view-configuration-filter): how to customize the configuration via the `get_entity_view_config_{$kind}_{$name}` filter and its methods (`merge`, `remove`, `replace`, `set`).
Expand All @@ -23,13 +25,19 @@ This section lists the properties of the view configuration. It has four top-lev

## default_view

> The view object is the same structure the [DataViews component](/packages/dataviews/README.md#view-object) consumes; see its documentation for the complete list of view properties and filter operators. There are two properties from the DataViews API that cannot be configured via the server filter: `search` and `page`. These are URL-managed that are set by the editor when the user searches or paginates.
> The view object is the same structure the [DataViews component](/packages/dataviews/README.md#view-object) consumes; see its documentation for the complete list of view properties and filter operators. There are two properties from the DataViews API that cannot be configured via the server filter: `search` and `page`. These are URL-managed: they are set by the editor when the user searches or paginates.

The default DataViews configuration for the screen: layout type, visible fields, sorting, filtering, and pagination. It is the view users see before they customize anything.

<!-- START TOKEN Autogenerated - DO NOT EDIT (default_view) -->

| Property | Description | Type |
| -------- | ----------- | ---- |
| type | The layout type, one of `table`, `grid`, `list`, or `activity`. | `string` |
| type | The layout type (e.g. `table`, `grid`, `list`, or `activity`). | `string` |
| layout | Configuration specific to the selected layout type. Accepts the layout options of all view types. | `{ styles, density, enableMoving, badgeFields, previewSize }` |
| filters | Filters applied to the dataset. A filter with `isLocked` set cannot be removed by the user. | `[ { field, operator, value, isLocked } ]` |
| sort | The sorting configuration: the field id and the direction (`asc` or `desc`). | `{ field, direction }` |
| perPage | Number of records per page. Also used as the batch size when infinite scroll is enabled. | `integer` |
| fields | Ids of the fields that are visible, in display order. | `[ string ]` |
| titleField | Id of the field used as the record title. | `string` |
| mediaField | Id of the field used as the record media (e.g. featured image or preview). | `string` |
Expand All @@ -38,20 +46,14 @@ The default DataViews configuration for the screen: layout type, visible fields,
| showMedia | Whether the media is shown. Defaults to `true`. | `boolean` |
| showDescription | Whether the description is shown. Defaults to `true`. | `boolean` |
| showLevels | Whether to display hierarchical levels for the records (e.g. child pages indented under their parent). Defaults to `false`. | `boolean` |
| sort | The default sort: the field id and the direction (`asc` or `desc`). | `{ field, direction }` |
| filters | Filters applied to the dataset. A filter with `isLocked` set cannot be removed by the user. | `[ { field, operator, value, isLocked } ]` |
| perPage | Number of records per page. | `integer` |
| layout | Configuration specific to the selected layout type. See [`default_layouts`](#default_layouts). | `object` |
| groupBy | The grouping configuration: the field id, the direction the groups are sorted by (`asc` or `desc`), and whether the group header shows the field label. | `{ field, direction, showLabel }` |
| infiniteScrollEnabled | Whether records load via infinite scroll instead of pagination. | `boolean` |

<!-- END TOKEN Autogenerated - DO NOT EDIT (default_view) -->

## default_layouts

The layout types the user can switch between. Each key is a layout type (`table`, `grid`, `list`, `activity`); a type that is not present is not offered in the UI. Each value is a partial view configuration applied when the user switches to that layout type — an empty array means the type is available with no overrides.

| Property | Description | Type |
| -------- | ----------- | ---- |
| table | View overrides applied when the table layout is selected. | `object` |
| grid | View overrides applied when the grid layout is selected. | `object` |
| list | View overrides applied when the list layout is selected. | `object` |
The layout types the user can switch between. Each key is a layout type; a type that is not present is not offered in the UI. Each value is a partial view configuration applied when the user switches to that layout type — an empty array means the type is available with no overrides.

Common overrides are `layout` (layout-specific configuration, such as per-field column `styles` for tables or `badgeFields` for grids) and view properties like `showMedia`:

Expand All @@ -74,15 +76,90 @@ $default_layouts = array(
);
```

<!-- START TOKEN Autogenerated - DO NOT EDIT (default_layouts) -->

| Property | Description | Type |
| -------- | ----------- | ---- |
| table | View overrides applied when the table layout is selected. | `object` |
| list | View overrides applied when the list layout is selected. | `object` |
| grid | View overrides applied when the grid layout is selected. | `object` |
| activity | View overrides applied when the activity layout is selected. | `object` |
| pickerGrid | View overrides applied when the picker grid layout is selected. | `object` |
| pickerTable | View overrides applied when the picker table layout is selected. | `object` |

Each layout type accepts all the [view properties](#default_view) as overrides (except `type`), plus a `layout` object with options specific to that layout type:

### table

Layout options specific to table-type views.

| Property | Description | Type |
| -------- | ----------- | ---- |
| styles | Styles for the table columns, keyed by field id. | `{ [ fieldId ]: { width, maxWidth, minWidth, align } }` |
| density | The density of the layout. | `compact \| balanced \| comfortable` |
| enableMoving | Whether the table columns display moving controls. | `boolean` |

### list

Layout options specific to list-type views.

| Property | Description | Type |
| -------- | ----------- | ---- |
| density | The density of the layout. | `compact \| balanced \| comfortable` |

### grid

Layout options specific to grid-type views.

| Property | Description | Type |
| -------- | ----------- | ---- |
| badgeFields | Ids of the fields rendered without label and styled as badges. | `[ string ]` |
| previewSize | The size of the grid item preview. | `number` |
| density | The density of the layout. | `compact \| balanced \| comfortable` |

### activity

Layout options specific to list-type views.

| Property | Description | Type |
| -------- | ----------- | ---- |
| density | The density of the layout. | `compact \| balanced \| comfortable` |

### pickerGrid

Layout options specific to grid-type views.

| Property | Description | Type |
| -------- | ----------- | ---- |
| badgeFields | Ids of the fields rendered without label and styled as badges. | `[ string ]` |
| previewSize | The size of the grid item preview. | `number` |
| density | The density of the layout. | `compact \| balanced \| comfortable` |

### pickerTable

Layout options specific to table-type views.

| Property | Description | Type |
| -------- | ----------- | ---- |
| styles | Styles for the table columns, keyed by field id. | `{ [ fieldId ]: { width, maxWidth, minWidth, align } }` |
| density | The density of the layout. | `compact \| balanced \| comfortable` |
| enableMoving | Whether the table columns display moving controls. | `boolean` |

<!-- END TOKEN Autogenerated - DO NOT EDIT (default_layouts) -->

## view_list

The preconfigured views displayed in the screen's sidebar (e.g. "All pages", "Published", "Drafts"). Each entry is:

<!-- START TOKEN Autogenerated - DO NOT EDIT (view_list) -->

| Property | Description | Type |
| -------- | ----------- | ---- |
| title | Title of the view, displayed in the sidebar. | `string` |
| slug | Unique identifier for the view. Used as the member identity when merging patches. | `string` |
| view | Partial view configuration applied on top of `default_view` when the view is selected — typically locked `filters`, but any view property works. Optional. | `object` |
| view | Partial view configuration applied on top of the default view when the view is selected. | `object` |

<!-- END TOKEN Autogenerated - DO NOT EDIT (view_list) -->

```php
$view_list = array(
Expand Down Expand Up @@ -113,20 +190,6 @@ $view_list = array(

The DataForm configuration for the Quick Edit form: which fields are displayed, in which order, and how each one is laid out.

| Property | Description | Type |
| -------- | ----------- | ---- |
| layout | The default layout for the form fields, e.g. `{ 'type' => 'panel' }`. | `{ type }` |
| fields | The fields of the form, in display order. Each entry is a field id, or an object for further configuration (see below). | `[ string \| object ]` |

A field declared as an object accepts:

| Property | Description | Type |
| -------- | ----------- | ---- |
| id | Id of the field. Used as the member identity when merging patches. | `string` |
| label | Label displayed for the field, overriding the field's own. | `string` |
| layout | How the field is rendered: `type` is one of `regular`, `panel`, `card`, or `row`, and `labelPosition` is one of `side`, `top`, or `none`. | `{ type, labelPosition }` |
| children | Fields combined under this entry, following the same shape as `fields`. | `[ string \| object ]` |

Only registered fields are rendered: a form entry whose field is not registered for the entity is dropped by the editor.

```php
Expand All @@ -150,3 +213,80 @@ $form = array(
),
);
```

<!-- START TOKEN Autogenerated - DO NOT EDIT (form) -->

| Property | Description | Type |
| -------- | ----------- | ---- |
| layout | The default layout for the form fields. | `{ type: regular \| panel \| card \| row \| details, … }` |
| fields | The fields of the form, in display order. Each entry is a field id, or an object for further configuration. | `[ string \| { id, label, description, layout, children } ]` |

@mcsf mcsf Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Vertical pipe char inside code tag is being escaped:

-| `[ string \| { id, label, description
+| `[ string | { id, label, description


### Form fields

A field declared as an object accepts:

| Property | Description | Type |
| -------- | ----------- | ---- |
| id | Id of the field. Used as the member identity when merging patches. | `string` |
| label | Label displayed for the field, overriding the field's own. | `string` |
| description | A description of the form field's purpose, used to provide additional context. | `string` |
| layout | The layout used to render this field, overriding the form layout. | `{ type: regular \| panel \| card \| row \| details, … }` |
| children | Fields combined under this entry, following the same shape as `fields`. | `[ string \| object ]` |

### Form layout variants

A form layout — the form `layout` or a field `layout` — is one of the following variants, discriminated by its `type` property:

#### regular

The `regular` layout renders the fields inline.

| Property | Description | Type |
| -------- | ----------- | ---- |
| type | The layout type. | `regular` |
| labelPosition | Position of the field label. Defaults to `top`. | `top \| side \| none` |

#### panel

The `panel` layout renders each field as a button that opens a dropdown or modal editor.

| Property | Description | Type |
| -------- | ----------- | ---- |
| type | The layout type. | `panel` |
| labelPosition | Position of the field label. Defaults to `side`. | `top \| side \| none` |
| openAs | Whether the panel editor opens as a dropdown or a modal. The object form also configures the labels of the modal buttons. Defaults to `dropdown`. | `dropdown \| modal \| { type, applyLabel, cancelLabel }` |
| summary | Id or ids of the fields displayed in the panel header. | `string \| [ string ]` |
| editVisibility | When the edit controls are visible. Defaults to `on-hover`. | `always \| on-hover` |

#### card

The `card` layout renders the fields inside a card, optionally collapsible behind a header.

| Property | Description | Type |
| -------- | ----------- | ---- |
| type | The layout type. | `card` |
| withHeader | Whether the card renders a header. Defaults to `true`. | `boolean` |
| isOpened | Whether the card is expanded. Defaults to `true`. | `boolean` |
| isCollapsible | Whether the card can be collapsed. Defaults to `true`. | `boolean` |
| summary | Id or ids of the fields displayed in the card header. Object entries control the visibility of each summary field (`always` or `when-collapsed`). | `string \| [ string \| { id, visibility } ]` |

#### row

The `row` layout renders the fields horizontally in a single row.

| Property | Description | Type |
| -------- | ----------- | ---- |
| type | The layout type. | `row` |
| alignment | Alignment of the fields within the row. Defaults to `center`. | `start \| center \| end` |
| styles | Styles for the fields in the row, keyed by field id. The `flex` property of each entry controls how the field sizes within the row. | `{ [ fieldId ]: { flex } }` |

#### details

The `details` layout renders the fields inside a collapsible details element.

| Property | Description | Type |
| -------- | ----------- | ---- |
| type | The layout type. | `details` |
| summary | Text shown in the details disclosure summary. | `string` |

<!-- END TOKEN Autogenerated - DO NOT EDIT (form) -->
Loading
Loading