mirror of
https://github.com/directus/directus.git
synced 2026-04-25 03:00:53 -04:00
848 lines
15 KiB
Markdown
848 lines
15 KiB
Markdown
---
|
||
description: REST and GraphQL API documentation on the Panels collection in Directus.
|
||
readTime: 5 min read
|
||
pageClass: page-reference
|
||
---
|
||
|
||
# Panels
|
||
|
||
> Panels are modular units of data visualization that exist within the Insights module. Each panel exists within a
|
||
> Dashboard and can be positioned and resized as needed.
|
||
|
||
[Learn more about Panels](/user-guide/insights/dashboards).
|
||
|
||
## The Panel Object
|
||
|
||
`id` **uuid**\
|
||
Primary key of the panel.
|
||
|
||
`dashboard` **many-to-one**\
|
||
Dashboard where this panel is visible. Many-to-one to [dashboards](/reference/system/dashboards).
|
||
|
||
`name` **string**\
|
||
Name of the panel.
|
||
|
||
`icon` **string**\
|
||
Material design icon for the panel.
|
||
|
||
`color` **string**\
|
||
Accent color of the panel.
|
||
|
||
`show_header` **boolean**\
|
||
Whether or not the header should be rendered for this panel.
|
||
|
||
`note` **string**\
|
||
Description for the panel.
|
||
|
||
`type` **string**\
|
||
The panel type used for this panel.
|
||
|
||
`position_x` **integer**\
|
||
The X position on the workspace grid.
|
||
|
||
`position_y` **integer**\
|
||
The Y position on the workspace grid.
|
||
|
||
`width` **integer**\
|
||
Width of the panel in number of workspace dots.
|
||
|
||
`height` **integer**\
|
||
Height of the panel in number of workspace dots.
|
||
|
||
`options` **JSON**\
|
||
Arbitrary options for the panel. Differs per panel type.
|
||
|
||
`date_created` **Date**\
|
||
When the panel was created
|
||
|
||
`user_created` **many-to-one**\
|
||
User that created the panel. Many-to-one to [users](/reference/system/users).
|
||
|
||
```json
|
||
{
|
||
"id": "22640672-eef0-4ee9-ab04-591f3afb2883",
|
||
"dashboard": "a79bd1b2-beb2-49fc-8a26-0b3eec0e2697",
|
||
"name": "30-day sales",
|
||
"icon": "paid",
|
||
"color": "#6B8068",
|
||
"show_header": true,
|
||
"note": "Overview of the sales numbers in the last 30 days",
|
||
"type": "time-series",
|
||
"position_x": 1,
|
||
"position_y": 1,
|
||
"width": 8,
|
||
"height": 6,
|
||
"options": {},
|
||
"date_created": "2023-01-05T19:05:51.884Z",
|
||
"user_created": "fd066644-c8e5-499d-947b-fe6c6e1a1473"
|
||
}
|
||
```
|
||
|
||
## List Panels
|
||
|
||
List all panels that exist in Directus.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`GET /panels`
|
||
|
||
`SEARCH /panels`
|
||
|
||
If using SEARCH you can provide a [query object](/reference/query) as the body of your request.
|
||
|
||
[Learn more about SEARCH ->](/reference/introduction#search-http-method)
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Query {
|
||
panels: [directus_panels]
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, readPanels } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(readPanels(query_object));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
### Response
|
||
|
||
An array of up to [limit](/reference/query#limit) [panel objects](#the-panel-object). If no items are available, data
|
||
will be an empty array.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`GET /panels`
|
||
|
||
`SEARCH /panels`
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
query {
|
||
panels {
|
||
id
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, readPanels } from '@directus/sdk';
|
||
|
||
const client = createDirectus('https://directus.example.com').with(rest());
|
||
|
||
const result = await client.request(
|
||
readPanels({
|
||
fields: ['*'],
|
||
})
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Retrieve a Panel
|
||
|
||
List an existing panel by primary key.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`GET /panels/:id`
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Query {
|
||
panels_by_id(id: ID!): directus_panels
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, readPanel } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(readPanel(panel_id, query_object));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
### Response
|
||
|
||
Returns the requested [panel object](#the-panel-object).
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`GET /panels/2fc325fb-299b-4d20-a9e7-a34349dee8b2`
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
query {
|
||
panels_by_id(id: "2fc325fb-299b-4d20-a9e7-a34349dee8b2") {
|
||
id
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, readPanel } from '@directus/sdk';
|
||
|
||
const client = createDirectus('https://directus.example.com').with(rest());
|
||
|
||
const result = await client.request(
|
||
readPanel('bf5d1373-3eea-431f-aaac-54591ba5ecf1', {
|
||
fields: ['*'],
|
||
})
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Create a Panel
|
||
|
||
Create a new panel.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`POST /panels`
|
||
|
||
Provide a [panel object](#the-panel-object) as the body of your request.
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
create_panels_item(data: create_directus_panels_input!): directus_panels
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, createPanel } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(createPanel(panel_object));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
#### Request Body
|
||
|
||
A partial [panel object](#the-panel-object).
|
||
|
||
### Response
|
||
|
||
Returns the [panel object](#the-panel-object) for the created panel.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`POST /panels`
|
||
|
||
```json
|
||
{
|
||
"name": "My Panel",
|
||
"icon": "architecture"
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
mutation {
|
||
create_panels_item(data: { name: "My Panel", icon: "panels" }) {
|
||
id
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, createPanel } from '@directus/sdk';
|
||
|
||
const client = createDirectus('https://directus.example.com').with(rest());
|
||
|
||
const result = await client.request(
|
||
createPanel({
|
||
name: 'sales chart',
|
||
type: 'bar-chart',
|
||
dashboard: '2418e38c-2f0b-460a-b46d-37b63106bcdc',
|
||
width: 12,
|
||
height: 10,
|
||
position_x: 10,
|
||
position_y: 10,
|
||
})
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Create Multiple Panels
|
||
|
||
Create multiple new panels.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`POST /panels`
|
||
|
||
Provide an array of [panel objects](#the-panel-object) as the body of your request.
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
create_panels_items(data: [create_directus_panels_input!]!): [directus_panels]
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, createPanels } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(createPanels(panel_object_array));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
#### Request Body
|
||
|
||
An array of partial [panel objects](#the-panel-object).
|
||
|
||
### Response
|
||
|
||
Returns the [panel object](#the-panel-object) for the created panel.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`POST /panels`
|
||
|
||
```json
|
||
[
|
||
{
|
||
"name": "My Panel",
|
||
"icon": "architecture"
|
||
},
|
||
{
|
||
"name": "Another Panel",
|
||
"icon": "person"
|
||
}
|
||
]
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
mutation {
|
||
create_panels_items(data: [{ name: "My Panel", icon: "architecture" }, { name: "Another Panel", icon: "person" }]) {
|
||
id
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, createPanels } from '@directus/sdk';
|
||
|
||
const client = createDirectus('https://directus.example.com').with(rest());
|
||
|
||
const result = await client.request(
|
||
createPanels([
|
||
{
|
||
name: 'sales chart',
|
||
type: 'bar-chart',
|
||
dashboard: '2418e38c-2f0b-460a-b46d-37b63106bcdc',
|
||
width: 12,
|
||
height: 10,
|
||
position_x: 20,
|
||
position_y: 10,
|
||
},
|
||
{
|
||
name: 'authorship percentage',
|
||
type: 'pie-chart',
|
||
dashboard: '2418e38c-2f0b-460a-b46d-37b63106bcdc',
|
||
width: 12,
|
||
height: 10,
|
||
position_x: 10,
|
||
position_y: 10,
|
||
},
|
||
])
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Update a Panel
|
||
|
||
Update an existing panel.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`PATCH /panels/:id`
|
||
|
||
Provide a partial [panel object](#the-panel-object) as the body of your request.
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
update_panels_item(id: ID!, data: update_directus_panels_input): directus_panels
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, updatePanel } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(updatePanel(panel_id, partial_panel_object));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
#### Request Body
|
||
|
||
A partial [panel object](#the-panel-object).
|
||
|
||
### Response
|
||
|
||
Returns the [panel object](#the-panel-object) for the updated panel.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`PATCH /panels/2fc325fb-299b-4d20-a9e7-a34349dee8b2`
|
||
|
||
```json
|
||
{
|
||
"name": "My Updated Panel"
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
mutation {
|
||
update_panels_item(id: "2fc325fb-299b-4d20-a9e7-a34349dee8b2", data: { name: "My Updated Panel" }) {
|
||
id
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, updatePanel } from '@directus/sdk';
|
||
|
||
const client = createDirectus('https://directus.example.com').with(rest());
|
||
|
||
const result = await client.request(
|
||
updatePanel('8d4acee9-f266-4664-801d-11d0273e9bfe', {
|
||
height: 20,
|
||
width: 20,
|
||
})
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Update Multiple Panels
|
||
|
||
Update multiple existing panels.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`PATCH /panels`
|
||
|
||
```json
|
||
{
|
||
"keys": panel_id_array,
|
||
"data": partial_panel_object
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
update_panels_items(ids: [ID!]!, data: update_directus_panels_input): [directus_panels]
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, updatePanels } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(updatePanels(panel_id_array, partial_panel_object));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
#### Query Parameters
|
||
|
||
Supports all [global query parameters](/reference/query).
|
||
|
||
#### Request Body
|
||
|
||
`keys` **Required**\
|
||
Array of primary keys of the panels you'd like to update.
|
||
|
||
`data` **Required**\
|
||
Any of [the panel](#the-panel-object)'s properties.
|
||
|
||
### Response
|
||
|
||
Returns the [panel objects](#the-panel-object) for the updated panels.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`PATCH /panels`
|
||
|
||
```json
|
||
{
|
||
"keys": ["3f2facab-7f05-4ee8-a7a3-d8b9c634a1fc", "7259bfa8-3786-45c6-8c08-cc688e7ba229"],
|
||
"data": {
|
||
"color": "#6644FF"
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
mutation {
|
||
update_panels_items(
|
||
ids: ["3f2facab-7f05-4ee8-a7a3-d8b9c634a1fc", "7259bfa8-3786-45c6-8c08-cc688e7ba229"]
|
||
data: { color: "#6644FF" }
|
||
) {
|
||
id
|
||
name
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, updatePanels } from '@directus/sdk';
|
||
|
||
const client = createDirectus('https://directus.example.com').with(rest());
|
||
|
||
const result = await client.request(
|
||
updatePanels(['8d4acee9-f266-4664-801d-11d0273e9bfe', '4a98c02e-62ac-4ceb-aabc-990ce603eb78'], {
|
||
position_x: 30,
|
||
})
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Delete a Panel
|
||
|
||
Delete an existing panel.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`DELETE /panels/:id`
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
delete_panels_item(id: ID!): delete_one
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, deletePanel } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(deletePanel(panel_id));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
### Response
|
||
|
||
Empty body.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`DELETE /panels/12204ee2-2c82-4d9a-b044-2f4842a11dba`
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
mutation {
|
||
delete_panels_item(id: "12204ee2-2c82-4d9a-b044-2f4842a11dba") {
|
||
id
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, deletePanel } from '@directus/sdk';
|
||
|
||
const client = createDirectus('https://directus.example.com').with(rest());
|
||
|
||
const result = await client.request(deletePanel('8d4acee9-f266-4664-801d-11d0273e9bfe'));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
## Delete Multiple Panels
|
||
|
||
Delete multiple existing panels.
|
||
|
||
### Request
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`DELETE /panels`
|
||
|
||
Provide an array of panel IDs as the body of your request.
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
type Mutation {
|
||
delete_panels_items(ids: [ID!]!): delete_many
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, deletePanels } from '@directus/sdk';
|
||
|
||
const client = createDirectus('directus_project_url').with(rest());
|
||
|
||
const result = await client.request(deletePanels(panel_id_array));
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|
||
|
||
### Request Body
|
||
|
||
An array of panels primary keys
|
||
|
||
### Response
|
||
|
||
Empty body.
|
||
|
||
### Example
|
||
|
||
<SnippetToggler :choices="['REST', 'GraphQL', 'SDK']" group="api">
|
||
<template #rest>
|
||
|
||
`DELETE /panels`
|
||
|
||
```json
|
||
["25821236-8c2a-4f89-8fdc-c7d01f35877d", "02b9486e-4273-4fd5-b94b-e18fd923d1ed", "7d62f1e9-a83f-407b-84f8-1c184f014501"]
|
||
```
|
||
|
||
</template>
|
||
<template #graphql>
|
||
|
||
`POST /graphql/system`
|
||
|
||
```graphql
|
||
mutation {
|
||
delete_panels_items(
|
||
ids: [
|
||
"25821236-8c2a-4f89-8fdc-c7d01f35877d"
|
||
"02b9486e-4273-4fd5-b94b-e18fd923d1ed"
|
||
"7d62f1e9-a83f-407b-84f8-1c184f014501"
|
||
]
|
||
) {
|
||
ids
|
||
}
|
||
}
|
||
```
|
||
|
||
</template>
|
||
<template #sdk>
|
||
|
||
```js
|
||
import { createDirectus, rest, deletePanels } from '@directus/sdk';
|
||
|
||
const client = createDirectus('https://directus.example.com').with(rest());
|
||
|
||
const result = await client.request(
|
||
deletePanels(['8d4acee9-f266-4664-801d-11d0273e9bfe', '4a98c02e-62ac-4ceb-aabc-990ce603eb78'])
|
||
);
|
||
```
|
||
|
||
</template>
|
||
</SnippetToggler>
|