From 289e344a1b16d639b5606cc302c93335c6c2e527 Mon Sep 17 00:00:00 2001
From: Kevin Lewis <kvn@lws.io>
Date: Mon, 16 Sep 2024 19:12:51 +0200
Subject: [PATCH] Layouts

---
 .../4.app-extensions/2.interfaces.md          |   4 +-
 .../4.app-extensions/3.layouts.md             | 114 ++++++++++++++++++
 2 files changed, 116 insertions(+), 2 deletions(-)

diff --git a/content/10.extensions/4.app-extensions/2.interfaces.md b/content/10.extensions/4.app-extensions/2.interfaces.md
index 03e1b9f1..6573d581 100644
--- a/content/10.extensions/4.app-extensions/2.interfaces.md
+++ b/content/10.extensions/4.app-extensions/2.interfaces.md
@@ -18,7 +18,7 @@ The `index.js` or `index.ts` file exports an object that is read by Directus. It
 
 ### Entrypoint Example
 
-```jsx
+```vue
 import InterfaceComponent from './interface.vue';
 
 export default {
@@ -71,7 +71,7 @@ The interface component is a Vue component that will be rendered in the Data Stu
 
 This example assumes there is an item in the entrypoint’s `options` array with a `field` value of `url`.
 
-```jsx
+```vue
 <template>
 	<input :value="value" @input="handleChange($event.target.value)" />
 	<span>{{ text }}</span>
diff --git a/content/10.extensions/4.app-extensions/3.layouts.md b/content/10.extensions/4.app-extensions/3.layouts.md
index 1a6902f8..5c54935b 100644
--- a/content/10.extensions/4.app-extensions/3.layouts.md
+++ b/content/10.extensions/4.app-extensions/3.layouts.md
@@ -3,3 +3,117 @@ description:
 ---
 
 # Explore Layouts
+
+Layouts allow for listing of items in :product-link{product="explore"} pages.
+
+Layouts receive a collection, filters, searches, and any custom layout options that are defined in the layout entrypoint. They are then expected to fetch and render the items from a collection.
+
+<!-- TODO: Image -->
+
+:partial{content="extensions-app"}
+
+## Layout Entrypoint
+
+The `index.js` or `index.ts` file exports an object that is read by Directus. It contains properties that control how a layout is displayed within menus, which options are available, optional slots, and the actual Vue component that will be loaded.
+
+### Entrypoint Example
+
+```js
+import { ref } from 'vue';
+import LayoutComponent from './layout.vue';
+
+export default {
+	id: 'custom',
+	name: 'Custom',
+	icon: 'box',
+	component: LayoutComponent,
+	slots: {
+		options: () => null,
+		sidebar: () => null,
+		actions: () => null,
+	},
+	setup() {
+		const name = ref('Custom Layout');
+		return { name };
+	},
+};
+```
+
+### Properties
+
+| Property        | Type      | Description                                                                                                                                                                                                                           |
+| --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`            | string    | A unique identifier for this extension.                                                                                                                                                                                               |
+| `name`          | string    | The displayed name for this layout 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.                                                                                                             |
+| `component`     | component | A reference to the Vue component rendered in the Explore page.                                                                                                                                                                        |
+| `slots`         | object    | Additional components to be added by your layout.                                                                                                                                                                                     |
+| `slots.options` | component | A reference to an options component.                                                                                                                                                                                                  |
+| `slots.sidebar` | component | A reference to a sidebar component.                                                                                                                                                                                                   |
+| `slots.actions` | component | A reference to an actions component.                                                                                                                                                                                                  |
+| `setup`         | function  | A function to setup reactive state to be shared by the layout component and the other components. It receives a `props` object as the first parameter and a `context` object containing an `emit()` function as the second parameter. |
+
+The `actions` slot is used to render additional buttons at the top of the layout by the search bar. It is commonly used to add additional buttons or display metadata about the layout.
+
+:partial{content="extensions-uid"}
+
+## Layout Component
+
+The layout component is a Vue component that will be rendered in the Data Studio within Explore pages. 
+
+### Component Example
+
+```vue
+<template>
+	<div>
+		<p>Name: {{ name }}</p>
+		<p>Collection: {{ collection }}</p>
+	</div>
+</template>
+
+<script>
+export default {
+	inheritAttrs: false,
+	props: {
+		collection: {
+			type: String,
+			required: true,
+		},
+		name: {
+			type: String,
+			required: true,
+		},
+	},
+};
+</script>
+```
+
+### Props
+
+The layout component will be passed all user configuration options from the entrypoint file. It will also receive the following props: 
+
+| Prop            | Type     | Description                                                  |
+| --------------- | -------- | ------------------------------------------------------------ |
+| `collection`    | string   | The current collection's name.                               |
+| `selection`     | array    | Any currently selected items.                                |
+| `layoutOptions` | object   | The user's currently saved layout options.                   |
+| `layoutQuery`   | object   | The user's layout query parameters. (e.g., sort, limit, etc) |
+| `filter`        | object   | The combined active filter.                                  |
+| `filterUser`    | object   | The user's currently active filter.                          |
+| `filterSystem`  | object   | The system's currently active filter.                        |
+| `search`        | string   | The user's current search query.                             |
+| `selectMode`    | boolean  | Indicates if the layout should be in select mode.            |
+| `readonly`      | boolean  | Indicates if the layout should be in readonly mode.          |
+| `resetPreset`   | function | A function to reset the preset.                              |
+
+### Emits
+
+The layout component can emit the following events that will be recognized by Directus.
+
+| Event                  | Description                                           |
+|------------------------|-------------------------------------------------------|
+| `update:selection`     | Update the currently selected items.                  |
+| `update:layoutOptions` | Update the user's currently saved layout options.     |
+| `update:layoutQuery`   | Update the user's layout query parameters.            |
+
+:partial{content="extensions-app-internals"}
\ No newline at end of file