mirror of
https://github.com/directus/directus.git
synced 2026-01-29 05:48:14 -05:00
139 lines
4.2 KiB
Markdown
139 lines
4.2 KiB
Markdown
---
|
|
description: A guide on how to build custom Display Extensions in Directus.
|
|
readTime: 4 min read
|
|
---
|
|
|
|
# Custom Displays <small></small>
|
|
|
|
> Displays are small inline components that allow you to create new ways of viewing field values throughout the App.
|
|
> [Learn more about Displays](/getting-started/glossary#displays).
|
|
|
|
## Extension Entrypoint
|
|
|
|
The entrypoint of your display is the `index` file inside the `src/` folder of your extension package. It exports a
|
|
configuration object with options to configure the behavior of your display. When loading your display, this object is
|
|
imported by the Directus host.
|
|
|
|
Example of an entrypoint:
|
|
|
|
```js
|
|
import DisplayComponent from './display.vue';
|
|
|
|
export default {
|
|
id: 'custom',
|
|
name: 'Custom',
|
|
icon: 'box',
|
|
description: 'This is my custom display!',
|
|
component: DisplayComponent,
|
|
options: null,
|
|
types: ['string'],
|
|
};
|
|
```
|
|
|
|
#### Available Options
|
|
|
|
- `id` — The unique key for this display. It is good practice to scope proprietary displays with an author prefix.
|
|
- `name` — The human-readable name for this display.
|
|
- `icon` — An icon name from the [material icon set](/getting-started/glossary#material-icons), or the extended list of
|
|
Directus custom icons.
|
|
- `description` — A short description (<80 characters) of this display shown in the App.
|
|
- `component` — A reference to your display component.
|
|
- `options` — The options of your display. Can be either an options object or a dedicated Vue component.
|
|
- `types` — An array of supported [types](/getting-started/glossary#types).
|
|
- `localTypes` — An array of local types. Accepts `standard`, `file`, `files`, `m2o`, `o2m`, `m2m`, `m2a`,
|
|
`presentation`, `translations` and `group`. Defaults to `standard`.
|
|
- `fields` — If this option is set, the display will fetch relational fields. Can either be an array of fields or a
|
|
function that returns an array of fields.
|
|
|
|
## Display Component
|
|
|
|
The display component is the part of your extension that will be rendered by the Directus App whenever your display
|
|
should be used to show the value of a field. This display component has to be Vue component. The most straightforward
|
|
way to write a Vue component is to use the Vue Single File Component syntax.
|
|
|
|
Example of a display component using the Vue SFC syntax:
|
|
|
|
```vue
|
|
<template>
|
|
<div>Value: {{ value }}</div>
|
|
</template>
|
|
|
|
<script>
|
|
export default {
|
|
props: {
|
|
value: {
|
|
type: String,
|
|
default: null,
|
|
},
|
|
},
|
|
};
|
|
</script>
|
|
```
|
|
|
|
The current value of the field is provided to the component via the `value` prop. If you use the `fields` option to
|
|
fetch relational fields, the `value` prop will be an object with the requested fields as keys and their respective
|
|
values.
|
|
|
|
#### Available Props
|
|
|
|
- `value` — The value of the field.
|
|
- `interface` - The interface of the field.
|
|
- `interfaceOptions` - The options for the field's interface.
|
|
- `type` — The type of the field.
|
|
- `collection` — The collection name of the field.
|
|
- `field` — The key of the field.
|
|
|
|
Other than this simple API to communicate with the Directus App, the display component is a blank canvas, allowing you
|
|
to create anything you need.
|
|
|
|
::: warning Vue Version
|
|
|
|
The Directus App uses Vue 3. There might be 3rd party libraries that aren't yet compatible with Vue 3.
|
|
|
|
:::
|
|
|
|
### Functional Component
|
|
|
|
Instead of defining the component inside a Vue SFC file, you can use a functional component. This allows you to make
|
|
simple displays that don't need a full component rendered:
|
|
|
|
```js
|
|
export default {
|
|
id: 'custom',
|
|
name: 'Custom',
|
|
icon: 'box',
|
|
description: 'This is my custom display!',
|
|
component: function ({ value }) {
|
|
return value.toLowerCase();
|
|
},
|
|
options: null,
|
|
types: ['string'],
|
|
};
|
|
```
|
|
|
|
## Accessing Internal Systems
|
|
|
|
To access internal systems like the API or the stores, you can use the `useApi()` and `useStores()` composables exported
|
|
by the `@directus/extensions-sdk` package. They can be used inside a `setup()` function like this:
|
|
|
|
```js
|
|
import { useApi, useStores } from '@directus/extensions-sdk';
|
|
|
|
export default {
|
|
setup() {
|
|
const api = useApi();
|
|
|
|
const { useCollectionsStore } = useStores();
|
|
const collectionsStore = useCollectionsStore();
|
|
|
|
// ...
|
|
},
|
|
};
|
|
```
|
|
|
|
::: tip Vue Options API
|
|
|
|
If you prefer to use the Vue Options API, you can inject the `api` and `stores` properties directly.
|
|
|
|
:::
|