Skip to content

Commit

Permalink
Interfaces, Panels
Browse files Browse the repository at this point in the history
  • Loading branch information
@phazonoverload
phazonoverload committed Sep 16, 2024
1 parent 30db008 commit 93c1537
Show file tree
Hide file tree
Showing 2 changed files with 214 additions and 3 deletions.
111 changes: 110 additions & 1 deletion content/10.extensions/4.app-extensions/2.interfaces.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,114 @@
---
description:
description: Interfaces are form inputs used primarily inside of the Editor.
---

# Editor Interfaces

Interfaces are form inputs used primarily inside of the :product-link{product="editor"}.

Interfaces are the primary way users interact with data inside of Directus. Custom interfaces can be used for use cases with unique interaction needs, complex data entry, and any time you need to add elements to the editor.

<!-- TODO: Image -->

:partial{content="extensions-app"}

## Interface Entrypoint

The `index.js` or `index.ts` file exports an object that is read by Directus. It contains properties that control how an interface is displayed within menus, it’s what types it supports, what configurable options will be available to users, and the actual Vue component that will be loaded.

### Entrypoint Example

```jsx
import InterfaceComponent from './interface.vue';

export default {
id: 'custom',
name: 'Custom',
icon: 'box',
description: 'This is my custom interface!',
component: InterfaceComponent,
types: ['string'],
options: [
{
field: 'text',
name: 'Text',
type: 'string',
meta: {
interface: 'input',
width: 'full',
}
},
],
};
```

### Properties

| Property | Type | Description |
| --------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | A unique identifier for this extension. |
| `name` | string | The displayed name for this panel in the Data Studio. |
| `icon` | string | An icon name from the [Google Material Icons set](https://fonts.google.com/icons). Supports filled and outlined variants. |
| `description` | string | A description of this interface shown in the Data Studio. Maximum 80 characters. |
| `component` | component | A reference to the Vue component rendered in the editor. |
| `types` | array | All [types](https://www.notion.so/ffc90a5128a4412eb9042cc170a16d37?pvs=21) supported by the interface. |
| `localTypes` | array | All local types supported by this interface. Accepts `standard`, `file`, `files`, `m2o`, `o2m`, `m2m`, `m2a`, `presentation`, `translations`, and `group`. Defaults to `standard`. |
| `group` | string | The group this interface is shown at when creating a field. Accepts `standard`, `selection`, `relational`, `presentation`, `group`, or `other`. Defaults to `other`. |
| `relational` | boolean | Indicates if this a relational interface. |
| `recommendedDisplays` | array | A list of display names which are recommended to be used with this interface. |
| `options` | array | component | When an array, options contains user-configurable fields that are set when creating or editing the interface.
| `preview` | string | Inline SVG to display in interface selection drawer. |

:partial{content="extensions-uid"}

:partial{content="extensions-theme"}

## Interface Component

The interface component is a Vue component that will be rendered in the Data Studio within the Editor. Data from the entrypoint is passed in as props.

### Component Example

This example assumes there is an item in the entrypoint’s `options` array with a `field` value of `url`.

```jsx
<template>
<input :value="value" @input="handleChange($event.target.value)" />
<span>{{ text }}</span>
</template>

<script setup>
defineProps(['text', 'value']);
const emit = defineEmits(['input']);

function handleChange(value) {
emit('input', value);
}
</script>
```

The current value of the field is provided to the component via the `value` prop. If the value was changed inside your component, it should be emitted to the Directus Editor by using the `input` emit.

### Props

The interface component will be passed all user configuration options from the entrypoint file. It will also receive the following props:

| Prop | Type | Description |
| ------------ | ------ | ------------------------------------------------------------------------------ |
| `value` | string | The current value of the field. |
| `width` | string | The layout width of the field. One of `half`, `half-right`, `full`, or `fill`. |
| `type` | string | The type of the field. |
| `collection` | string | The current collection name. |
| `field` | uuid | The key of the field. |
| `primaryKey` | string | The current item's primary key. |

### Emits

The interface component can emit the following events that will be recognized by Directus.

| Event | Description |
| --------------- | -------------------------------------- |
| `input` | Update the value of the field. |
| `setFieldValue` | Used to set the value of other fields. |

:partial{content="extensions-app-internals"}
106 changes: 104 additions & 2 deletions content/10.extensions/4.app-extensions/4.panels.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,107 @@
---
description:
description: Panels are customizable components within Directus Insights dashboards.
---

# Dashboard Panels
# Dashboard Panels

Panels are customizable components within :product-link{product="insights"} dashboards.

Panels are the building blocks of analytics dashboards, enabling rapid, no-code creation of data visualizations with data from a Directus project. Panels can also contain interactive elements, making them suitable for building custom internal applications within dashboards.

<!-- TODO: Image -->

:partial{content="extensions-app"}

## Panel Entrypoint

The `index.js` or `index.ts` file exports an object that is read by Directus. It contains properties that control how a panel is displayed within menus, it’s minimum width and height on the dashboard grid, what configurable options will be available to users, and the actual Vue component that will be loaded.

### Entrypoint Example

```js
import PanelComponent from './panel.vue';

export default {
id: 'custom',
name: 'Custom',
icon: 'box',
description: 'This is my custom panel!',
component: PanelComponent,
minWidth: 12,
minHeight: 8,
options: [
{
field: 'text',
name: 'Text',
type: 'string',
meta: {
interface: 'input',
width: 'full',
},
},
],
};
```

### Properties

| Property | Type | Description |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | A unique identifier for this extension. |
| `name` | string | The displayed name for this panel in the Data Studio. |
| `icon` | string | An icon name from the [Google Material Icons set](https://fonts.google.com/icons). Supports filled and outlined variants. |
| `description` | string | A description of this panel shown in the Data Studio. Maximum 80 characters. |
| `component` | component | A reference to the Vue component rendered in the dashboard. |
| `minWidth` | number | Smallest number of grid units in the dashboard. |
| `minHeight` | number | Smallest number of grid units in the dashboard. |
| `options` | array | component | When an array, options contains user-configurable fields that are set when creating or editing the panel.
| `preview` | string | Inline SVG to display in panel selection drawer. |

:partial{content="extensions-uid"}

:partial{content="extensions-theme"}

## Panel Component

The panel component is a Vue component that will be rendered in the Data Studio within a dashboard. Data from the entrypoint is passed in as props.

### Component Example

This example assumes there is an item in the entrypoint’s `options` array with a `field` value of `text`.

```vue
<template>
<div class="text" :class="{ 'has-header': showHeader }">
{{ text }}
</div>
</template>
<script setup>
defineProps(['showHeader', 'text']);
</script>
<style scoped>
.text {
padding: 12px;
}
.text.has-header {
padding: 0 12px;
}
</style>
```

### Props

The panel component will be passed all user configuration options from the entrypoint file. It will also receive the following props:

| Prop | Type | Description |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `id` | uuid | The UUID for this panel. This is for a specific instance of the panel and will not be the defined `id` in the entrypoint file. |
| `dashboard` | uuid | The UUID for the dashboard containing the panel. |
| `showHeader` | boolean | Whether the panel header visibility is enabled in the options. |
| `width` | number | The current number of grid units wide the panel is. |
| `height` | number | The current number of grid units high the panel is. |
| `now` | date | The date object at the time of loading the dashboard. |

:partial{content="extensions-app-internals"}

0 comments on commit 93c1537

Please sign in to comment.