github/directus
1
1
Fork 0
mirror of https://github.com/directus/directus.git synced 2026-04-03 03:00:39 -04:00
Code Issues Packages Projects Releases Wiki Activity

Overhaul docs (#3951)

Browse Source 
* Add Quickstart Guide

* Update installation

* Remove unused files

* Update support/backing

* Tweaks in concepts

* Setup file structure for API reference 2.0

* Setup page layout for reference

* Add clean-urls plugin

* getting started updates

* Finish authentication rest

* getting started updates

* Render stylus in 2 spaces

* Various

* Various

* Finish activity docs

* Add collections reference

* Add extension reference

* concepts updates

* Fields/tweaks

* Add files doc

* Add revisions

* concepts docs

* More api reference

* Finish rest api reference (finally)

* initial concepts

* More things

* Add assets api ref

* Move sections from file to assets

* Add environment variables

* contributing docs

* Add field transforms page

* Left align table headers

* concept links

* Add API config

* Fix mobile nav

* Add migrating a project

* doc link fixes

Co-authored-by: Ben Haynes <ben@rngr.org>
This commit is contained in:
Rijk van Zanten
2021-02-05 18:51:54 -05:00
committed by GitHub
parent 4fe04539bb
commit 817ccf3620
148 changed files with 10078 additions and 3049 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
api/src/controllers/files.ts
View File

@@ -107,7 +107,6 @@ router.post(
if (req.is('multipart/form-data')) {
keys = res.locals.savedFiles;
} else {
// @TODO is this ever used in real life? Wouldn't you always upload a file on create?
keys = await service.create(req.body);
}

27
api/src/controllers/permissions.ts
View File

@@ -59,21 +59,26 @@ router.get(
router.get(
'/me',
asyncHandler(async (req, res, next) => {
if (!req.accountability?.user) {
throw new InvalidCredentialsException();
}
const service = new PermissionsService({ schema: req.schema });
const query = clone(req.sanitizedQuery || {});
query.filter = {
...(query.filter || {}),
role: {
_eq: req.accountability.role,
},
};
if (req.accountability?.role) {
query.filter = {
...(query.filter || {}),
role: {
_eq: req.accountability.role,
},
};
} else {
query.filter = {
...(query.filter || {}),
role: {
_null: true,
},
};
}
const items = await service.readByQuery(req.sanitizedQuery);
const items = await service.readByQuery(query);
res.locals.payload = { data: items || null };
return next();

2
api/src/services/graphql.ts
View File

@@ -64,7 +64,7 @@ export class GraphQLService {
args = {
sort: {
type: GraphQLString,
type: new GraphQLList(GraphQLString),
},
limit: {
type: GraphQLInt,

13
api/src/services/payload.ts
View File

@@ -72,19 +72,6 @@ export class PayloadService {
return value;
},
async 'file-links'({ action, value, payload }) {
if (action === 'read' && payload && payload.storage && payload.filename_disk) {
const publicKey = `STORAGE_${payload.storage.toUpperCase()}_PUBLIC_URL`;
return {
asset_url: new URL(`/assets/${payload.id}`, env.PUBLIC_URL),
public_url: new URL(payload.filename_disk, env[publicKey]),
};
}
// This is an non-existing column, so there isn't any data to save
return undefined;
},
async boolean({ action, value }) {
if (action === 'read') {
return value === true || value === 1 || value === '1';

2
docs/.editorconfig
View File

@@ -7,6 +7,6 @@ charset = utf-8
indent_style = tab
trim_trailing_whitespace = true
[{package.json,*.yml,*.yaml}]
[{package.json,*.yml,*.yaml,*.styl}]
indent_style = space
indent_size = 2

270
docs/.vuepress/components/APIReferenceLayout.vue
View File

@@ -1,270 +0,0 @@
<template>
<div
class="theme-container"
:class="pageClasses"
@touchstart="onTouchStart"
@touchend="onTouchEnd"
>
<Navbar
v-if="shouldShowNavbar"
@toggle-sidebar="toggleSidebar"
/>
<div
class="sidebar-mask"
@click="toggleSidebar(false)"
/>
<Sidebar
:items="sidebarItems"
@toggle-sidebar="toggleSidebar"
>
<template #top>
<slot name="sidebar-top" />
</template>
<template #bottom>
<slot name="sidebar-bottom" />
</template>
</Sidebar>
<main class="page">
<div class="theme-default-content content__default">
<h1>{{ $page.frontmatter.tag.name }}</h1>
<section>
<div class="two-up">
<div class="left">
<div v-html="micromark($page.frontmatter.tag.description)" />
</div>
<aside class="right">
<InfoBox title="endpoints">
<dl class="endpoints">
<div v-for="endpoint of endpoints" :key="endpoint.operationId">
<dt>{{ endpoint.method.toUpperCase() }}</dt>
<dd>{{ endpoint.url }}</dd>
</div>
</dl>
</InfoBox>
</aside>
</div>
</section>
<section v-if="schemaComponent && schemaComponent.properties">
<h2>The {{ $page.frontmatter.tag.name }} Object</h2>
<div class="two-up">
<div class="left">
<DefinitionList>
<div v-for="(propertyInfo, property) of schemaComponent.properties" :key="property">
<h4>{{ property }} <DefinitionType>{{ propertyInfo.type || (propertyInfo.oneOf && propertyInfo.oneOf[0] && propertyInfo.oneOf[0].type) || '???' }}</DefinitionType></h4>
<div v-if="propertyInfo.description" v-html="micromark(propertyInfo.description)" />
</div>
</DefinitionList>
</div>
<div class="right">
<InfoBox :title="`${$page.frontmatter.tag.name} Object`">
<pre class="language-json"><code>{{ schemaComponentObjectExample }}</code></pre>
</InfoBox>
</div>
</div>
</section>
<section v-for="endpoint of endpoints" :key="endpoint.operationId">
<h2>{{ endpoint.summary }}</h2>
<div class="two-up">
<div class="left">
<div v-html="micromark(endpoint.description)" />
<template v-if="endpoint.parameters && endpoint.parameters.length > 0">
<h3>Parameters</h3>
<DefinitionList>
<div v-for="parameter of endpoint.parameters" :key="parameter.name">
<h4>{{ parameter.name }} <DefinitionType>{{ parameter.schema.type }}</DefinitionType></h4>
<div v-if="parameter.description" v-html="micromark(parameter.description)" />
</div>
</DefinitionList>
</template>
<template v-if="endpoint.query && endpoint.query.length > 0">
<h3>Query</h3>
<DefinitionList>
<div v-for="query of endpoint.query" :key="query.name">
<h4>{{ query.name }} <DefinitionType>{{ query.schema.type }}</DefinitionType></h4>
<div v-if="query.description" v-html="micromark(query.description)" />
<a :href="`/reference/api/query/${query.name}`">Learn More</a>
</div>
</DefinitionList>
</template>
</div>
<div class="right">
<InfoBox title="endpoint">
<dl class="endpoints">
<div>
<dt>{{ endpoint.method.toUpperCase() }}</dt>
<dd>{{ endpoint.url }}</dd>
</div>
</dl>
</InfoBox>
</div>
</div>
</section>
</div>
</main>
</div>
</template>
<script>
import Layout from '@theme/layouts/Layout.vue';
import specs from '@directus/specs';
import micromark from 'micromark';
import get from 'lodash.get';
import InfoBox from './InfoBox.vue';
import DefinitionList from './DefinitionList.vue';
import DefinitionType from './DefinitionType.vue';
export default {
components: { Layout, InfoBox, DefinitionList, DefinitionType },
extends: Layout,
computed: {
endpoints() {
const tag = this.$page.frontmatter.tag.name;
const endpoints = [];
for (const [url, urlInfo] of Object.entries(specs.paths)) {
for (const [method, operation] of Object.entries(specs.paths[url])) {
if (operation.tags?.includes(tag) !== true) continue;
const endpoint = {
...operation,
url,
method,
query: operation.parameters,
parameters: urlInfo.parameters
};
endpoints.push(this.deref(endpoint));
}
}
return endpoints;
},
schemaComponent() {
const tag = this.$page.frontmatter.tag.name;
return this.deref(specs.components.schemas[tag]);
},
schemaComponentObjectExample() {
if (!this.schemaComponent) return null;
const example = {};
for (const [key, info] of Object.entries(this.schemaComponent.properties)) {
example[key] = info.example;
}
return JSON.stringify(example, null, 2);
}
},
methods: {
micromark,
deref(object) {
object = { ...object };
return deref(object, 0);
function deref(object, level) {
object = {...object};
if (isObject(object) === false) return object;
if (level > 3) return object;
if ('$ref' in object) {
const path = object.$ref.substring(2).replace(/\//g, '.');
return deref(get(specs, path), level + 1);
}
for (const [key, value] of Object.entries(object)) {
if (isArray(value)) {
object[key] = value.map(val => isObject(val) ? deref(val, level + 1) : val);
} else if (isObject(value)) {
if ('$ref' in value) {
const path = value.$ref.substring(2).replace(/\//g, '.');
object[key] = deref(get(specs, path), level + 1);
} else {
object[key] = deref(value, level + 1);
}
} else {
continue;
}
}
return object;
}
function isObject(value) {
return Object.prototype.toString.call(value) === '[object Object]';
}
function isArray(value) {
return Array.isArray(value);
}
}
},
};
</script>
<style scoped>
.page-content {
display: block;
padding-bottom: 2rem;
}
.theme-default-content {
max-width: 1200px;
}
.content__default section {
margin-bottom: 2rem;
padding-bottom: 2rem;
border-bottom: 1px solid #f0f4f9;
}
.content__default section h2 {
border-bottom: 0;
}
@media (min-width: 1174px) {
.content__default .two-up {
display: grid;
grid-gap: 3em;
grid-template-columns: minmax(0, 4fr) minmax(0, 3fr);
align-items: flex-start;
}
.content__default .right {
position: sticky;
top: 80px;
}
}
.endpoints {
font-size: 0.8em;
font-family: Consolas, Monaco, Andale Mono, Ubuntu Mono, monospace;
}
.endpoints div > * {
display: inline-block;
}
.endpoints div dt {
width: 8ch;
margin-right: 1ch;
text-align: right;
}
.endpoints div dd {
margin: 0;
}
</style>

37
docs/.vuepress/components/DefinitionList.vue
View File

@@ -1,37 +0,0 @@
<template>
<div class="definition-list">
<slot />
</div>
</template>
<style scoped>
.definition-list > *:last-child {
padding-bottom: 1rem;
border-bottom: 1px solid #eee;
}
.definition-list ::v-deep h4, .definition-list ::v-deep p {
margin: 0;
}
.definition-list ::v-deep p {
font-size: 14px;
}
.definition-list ::v-deep h4 {
margin-top: 1rem;
padding-top: 1rem;
font-size: 0.8rem;
font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New', monospace;
border-top: 1px solid #eee;
}
.definition-list ::v-deep code {
padding: 0;
background-color: transparent;
}
.definition-list ::v-deep a {
font-size: 0.8rem;
}
</style>

27
docs/.vuepress/components/DefinitionType.vue
View File

@@ -1,27 +0,0 @@
<template>
<span class="definition-type" :class="{ alert }"><slot /></span>
</template>
<script>
export default {
props: {
alert: {
type: Boolean,
default: false
}
}
}
</script>
<style scoped>
.definition-type {
color: #aaa;
font-size: 0.75rem;
font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
}
.definition-type.alert {
color: #ff9800;
text-transform: uppercase;
}
</style>

41
docs/.vuepress/components/InfoBox.vue
View File

@@ -1,41 +0,0 @@
<template>
<article class="info-box">
<div class="header">{{ title }}</div>
<div class="body">
<slot />
</div>
</article>
</template>
<script>
export default {
props: ['title']
}
</script>
<style scoped>
.info-box {
position: relative;
width: 100%;
overflow: hidden;
border: 2px solid #f0f4f9;
border-radius: 6px;
}
.header {
padding: 8px;
font-weight: 600;
font-size: 0.8em;
text-transform: uppercase;
background-color: #f0f4f9;
}
.body ::v-deep pre {
margin: 0;
padding: 20px;
overflow: auto;
color: white;
font-size: 0.8em;
border-radius: 0;
}
</style>

432
docs/.vuepress/config.js
View File

@@ -48,9 +48,11 @@ module.exports = {
editLinks: true,
docsDir: 'docs',
lastUpdated: true,
serviceWorker: true,
serviceWorker: false,
patterns: ['docs/**/*.md'],
sidebarDepth: 0,
activeHeaderLinks: false,
smoothScroll: false,
nav: [
{ text: 'Website', link: 'https://directus.io' },
{ text: 'Cloud', link: 'https://directus.cloud' },
@@ -68,7 +70,7 @@ module.exports = {
{
type: 'page',
path: '/getting-started/quickstart',
title: 'Quick Start',
title: 'Quickstart Guide',
},
{
type: 'page',
@@ -78,7 +80,7 @@ module.exports = {
{
type: 'page',
path: '/getting-started/support',
title: 'Support',
title: 'Help & Support',
},
{
type: 'page',
@@ -92,33 +94,73 @@ module.exports = {
children: [
{
type: 'page',
path: '/concepts/platform-overview',
title: 'Platform Overview',
path: '/concepts/activity',
title: 'Activity',
},
{
type: 'page',
path: '/concepts/app-overview',
title: 'App Overview',
path: '/concepts/application',
title: 'Application',
},
{
type: 'page',
path: '/concepts/data-model',
title: 'Data Model',
path: '/concepts/collections',
title: 'Collections',
},
{
type: 'page',
path: '/concepts/activity-and-versions',
title: 'Activity & Versions',
path: '/concepts/databases',
title: 'Databases',
},
{
type: 'page',
path: '/concepts/files-and-thumbnails',
title: 'Files & Thumbnails',
path: '/concepts/displays',
title: 'Displays',
},
{
type: 'page',
path: '/concepts/internationalization',
title: 'Internationalization',
path: '/concepts/extensions',
title: 'Extensions',
},
{
type: 'page',
path: '/concepts/fields',
title: 'Fields',
},
{
type: 'page',
path: '/concepts/files',
title: 'Files',
},
{
type: 'page',
path: '/concepts/interfaces',
title: 'Interfaces',
},
{
type: 'page',
path: '/concepts/items',
title: 'Items',
},
{
type: 'page',
path: '/concepts/layouts',
title: 'Layouts',
},
{
type: 'page',
path: '/concepts/modules',
title: 'Modules',
},
{
type: 'page',
path: '/concepts/permissions',
title: 'Permissions',
},
{
type: 'page',
path: '/concepts/projects',
title: 'Projects',
},
{
type: 'page',
@@ -127,18 +169,28 @@ module.exports = {
},
{
type: 'page',
path: '/concepts/users-roles-and-permissions',
title: 'Users, Roles, and Permissions',
path: '/concepts/revisions',
title: 'Revisions',
},
{
type: 'page',
path: '/concepts/app-extensions',
title: 'App Extensions',
path: '/concepts/roles',
title: 'Roles',
},
{
type: 'page',
path: '/concepts/api-extensions',
title: 'API Extensions',
path: '/concepts/translations',
title: 'Translations',
},
{
type: 'page',
path: '/concepts/types',
title: 'Types',
},
{
type: 'page',
path: '/concepts/users',
title: 'Users',
},
],
},
@@ -147,24 +199,44 @@ module.exports = {
children: [
{
type: 'page',
path: '/guides/installation/',
title: 'Installation',
path: '/guides/api-config',
title: 'API Config',
},
{
type: 'page',
path: '/guides/projects',
title: 'Projects',
path: '/guides/api-endpoints',
title: 'API Endpoints',
},
{
type: 'page',
path: '/guides/api-hooks',
title: 'API Hooks',
},
{
type: 'page',
path: '/guides/collections',
title: 'Collections',
},
{
type: 'page',
path: '/guides/displays',
title: 'Displays',
},
{
type: 'page',
path: '/guides/fields',
title: 'Fields',
},
{
type: 'page',
path: '/guides/files',
title: 'Files',
},
{
type: 'page',
path: '/guides/interfaces',
title: 'Interfaces',
},
{
type: 'page',
path: '/guides/items',
@@ -172,34 +244,49 @@ module.exports = {
},
{
type: 'page',
path: '/guides/files',
title: 'Files & Thumbnails',
path: '/guides/layouts',
title: 'Layouts',
},
{
type: 'page',
path: '/guides/roles-and-permissions',
title: 'Roles & Permissions',
path: '/guides/modules',
title: 'Modules',
},
{
type: 'page',
path: '/guides/permissions',
title: 'Permissions',
},
{
type: 'page',
path: '/guides/presets',
title: 'Presets',
},
{
type: 'page',
path: '/guides/projects',
title: 'Projects',
},
{
type: 'page',
path: '/guides/roles',
title: 'Roles',
},
{
type: 'page',
path: '/guides/styles',
title: 'Styles',
},
{
type: 'page',
path: '/guides/users',
title: 'Users',
},
{
type: 'page',
path: '/guides/presets',
title: 'Presets & Bookmarks',
},
{
type: 'page',
path: '/guides/webhooks',
title: 'Webhooks',
},
{
type: 'page',
path: '/guides/white-labeling',
title: 'White-Labeling',
},
],
},
{
@@ -220,21 +307,16 @@ module.exports = {
path: '/reference/error-codes',
title: 'Error Codes',
},
{
type: 'page',
path: '/reference/field-transforms',
title: 'Field Transforms',
},
{
type: 'page',
path: '/reference/filter-rules',
title: 'Filter Rules',
},
{
type: 'page',
path: '/reference/item-objects',
title: 'Item Objects',
},
{
type: 'page',
path: '/reference/internal-helpers',
title: 'Internal Helpers',
},
{
type: 'page',
path: '/reference/sdk-js',
@@ -252,59 +334,117 @@ module.exports = {
},
{
type: 'page',
path: '/reference/api/items',
title: 'Items',
path: '/reference/api/authentication',
title: 'Authentication',
},
{
type: 'page',
title: 'Global Query Parameters',
path: '/reference/api/query',
},
{
type: 'group',
title: 'Query Parameters',
title: 'REST API',
children: [
{
type: 'page',
path: '/reference/api/query/fields',
path: '/reference/api/rest/items',
title: 'Items',
},
{
type: 'divider',
},
{
type: 'page',
path: '/reference/api/rest/activity',
title: 'Activity',
},
{
type: 'page',
path: '/reference/api/rest/authentication',
title: 'Authentication',
},
{
type: 'page',
path: '/reference/api/rest/collections',
title: 'Collections',
},
{
type: 'page',
path: '/reference/api/rest/extensions',
title: 'Extensions',
},
{
type: 'page',
path: '/reference/api/rest/fields',
title: 'Fields',
},
{
type: 'page',
path: '/reference/api/query/filter',
title: 'Filter',
path: '/reference/api/rest/files',
title: 'Files',
},
{
type: 'page',
path: '/reference/api/query/limit',
title: 'Limit',
path: '/reference/api/rest/folders',
title: 'Folders',
},
{
type: 'page',
path: '/reference/api/query/meta',
title: 'Meta',
path: '/reference/api/rest/permissions',
title: 'Permissions',
},
{
type: 'page',
path: '/reference/api/query/offset',
title: 'Offset',
path: '/reference/api/rest/presets',
title: 'Presets',
},
{
type: 'page',
path: '/reference/api/query/search',
title: 'Search',
path: '/reference/api/rest/relations',
title: 'Relations',
},
{
type: 'page',
path: '/reference/api/query/single',
title: 'Single',
path: '/reference/api/rest/revisions',
title: 'Revisions',
},
{
type: 'page',
path: '/reference/api/query/sort',
title: 'Sort',
path: '/reference/api/rest/roles',
title: 'Roles',
},
{
type: 'page',
path: '/reference/api/rest/server',
title: 'Server',
},
{
type: 'page',
path: '/reference/api/rest/settings',
title: 'Settings',
},
{
type: 'page',
path: '/reference/api/rest/users',
title: 'Users',
},
{
type: 'page',
path: '/reference/api/rest/utilities',
title: 'Utilities',
},
{
type: 'page',
path: '/reference/api/rest/webhooks',
title: 'Webhooks',
},
],
},
{
type: 'page',
path: '/reference/api/activity',
title: 'Activity',
path: '/reference/api/graphql',
title: 'GraphQL',
},
{
type: 'page',
@@ -313,126 +453,8 @@ module.exports = {
},
{
type: 'page',
path: '/reference/api/authentication',
title: 'Authentication',
},
{
type: 'page',
path: '/reference/api/collections',
title: 'Collections',
},
{
type: 'page',
path: '/reference/api/extensions',
title: 'Extensions',
},
{
type: 'page',
path: '/reference/api/fields',
title: 'Fields',
},
{
type: 'page',
path: '/reference/api/files',
title: 'Files',
},
{
type: 'page',
path: '/reference/api/folders',
title: 'Folders',
},
{
type: 'page',
path: '/reference/api/permissions',
title: 'Permissions',
},
{
type: 'page',
path: '/reference/api/presets',
title: 'Presets',
},
{
type: 'page',
path: '/reference/api/relations',
title: 'Relations',
},
{
type: 'page',
path: '/reference/api/revisions',
title: 'Revisions',
},
{
type: 'page',
path: '/reference/api/roles',
title: 'Roles',
},
{
type: 'page',
path: '/reference/api/server',
title: 'Server',
},
{
type: 'page',
path: '/reference/api/settings',
title: 'Settings',
},
{
type: 'page',
path: '/reference/api/users',
title: 'Users',
},
{
type: 'page',
path: '/reference/api/utilities',
title: 'Utilities',
},
{
type: 'page',
path: '/reference/api/webhooks',
title: 'Webhooks',
},
],
},
{
title: 'Extensions',
children: [
{
type: 'page',
path: '/extensions/displays',
title: 'Displays',
},
{
type: 'page',
path: '/extensions/interfaces',
title: 'Interfaces',
},
{
type: 'page',
path: '/extensions/layouts',
title: 'Layouts',
},
{
type: 'page',
path: '/extensions/modules',
title: 'Modules',
},
{
type: 'page',
path: '/extensions/api-endpoints',
title: 'API Endpoints',
},
{
type: 'page',
path: '/extensions/api-hooks',
title: 'API Hooks',
},
{
type: 'divider',
},
{
type: 'page',
path: '/extensions/accessing-data',
title: 'Accessing Data',
path: '/reference/api/health',
title: 'Health Check',
},
],
},
@@ -446,32 +468,36 @@ module.exports = {
},
{
type: 'page',
path: '/contributing/development-workflow',
title: 'Development Workflow',
path: '/contributing/codebase-overview',
title: 'Codebase Overview',
},
{
type: 'page',
path: '/contributing/running-locally',
title: 'Running Locally',
},
{
type: 'page',
path: '/contributing/repo-overview',
title: 'Repo Overview',
},
{
type: 'page',
path: '/contributing/code-of-conduct',
title: 'Code of Conduct',
},
{
type: 'page',
path: '/contributing/translations',
title: 'App Translations',
title: 'Translating the App',
},
],
},
],
},
plugins: ['@vuepress/medium-zoom'],
markdown: {
toc: {
includeLevel: [2],
},
},
plugins: [
[
'vuepress-plugin-clean-urls',
{
normalSuffix: '/',
indexSuffix: '/',
notFoundPath: '/404.html',
},
],
],
};

113
docs/.vuepress/styles/index.styl
View File

@@ -1,26 +1,26 @@
html
scroll-padding-top 4rem
.tabs-component
.tabs-component
margin 4em 0
.tabs-component-tabs
.tabs-component-tabs
border solid 1px #ddd
border-radius 6px
.tabs-component-tab
&:hover
.tabs-component-tab
&:hover
color #666
&.is-active
&.is-active
color #000
border-bottom solid 1px #fff
z-index 2
&.is-disabled
*
&.is-disabled
*
color #cdcdcd
cursor not-allowed !important
.tabs-component-panels
.tabs-component-panels
padding 1em
@media (min-width: 700px)
.tabs-component-tabs
@media (min-width: 700px)
.tabs-component-tabs
border 0
align-items stretch
display flex
@@ -33,14 +33,14 @@ html
border-radius 6px 6px 0 0
margin-right 0.1em
transition transform 0.3s ease
.tabs-component-panels
.tabs-component-panels
border-top-left-radius 0
background-color #fff
border solid 1px #ddd
border-radius 0 6px 6px 6px
box-shadow 0 0 10px rgba(0, 0, 0, 0.05)
padding 1em
.tabs-component-tab
.tabs-component-tab
color #999
font-size 14px
font-weight 600
@@ -48,25 +48,86 @@ html
list-style none
&:not(:first-child)
border-left 0
.tabs-component-tab-a
.tabs-component-tab-a
align-items center
color inherit
display flex
padding 0.25em 1em
text-decoration none
.page-reference
.theme-default-content.content__default,
.page-edit,
.page-reference
.theme-default-content.content__default
.page-edit
.page-nav
max-width 1200px
hr
width calc(100% + 5rem)
left -2.5rem
position relative
margin 4rem 0
h1
hr
width calc(100% + 5rem)
left -2.5rem
position relative
margin 3rem 0
h2
border-bottom 0
margin-top 3rem
hr + h2
margin-top -1 * ($navbarHeight + 2rem)
h3
margin-top 3rem
font-size 1.2rem
h4
margin-top 2rem
margin-bottom 0
.definitions
font-size: 0.9rem
> p
border-bottom 2px solid $borderColor
padding .8rem 0
margin 0
> code:first-child
background transparent
padding 0
margin-right 0.2rem
font-weight 700
font-size 0.8rem
> strong
color#aaa
&:first-child
border-top 2px solid $borderColor
h2
border-bottom 0
h3
font-size 1.2rem
pre
tab-size: 2 !important;
.two-up
margin-top 3rem
.two-up .right
margin-top 50px
@media (min-width: 1000px)
.two-up
display grid
grid-template-columns minmax(0, 4fr) minmax(0, 3fr)
grid-gap 40px
align-items start
.two-up .left
.two-up .right
> *:first-child {
margin-top: 0 !important;
}
.two-up .right
margin-top 0
position sticky
top $navbarHeight
.navbar .home-link
width 4.3rem
overflow hidden
@media (min-width: 592px)
.navbar .home-link
width 12.2rem
@media (min-width: 700px)
.navbar .home-link
width auto
overflow auto

4
docs/.vuepress/styles/palette.styl
View File

@@ -1,6 +1,6 @@
$accentColor = #2CCDA6
$textColor = #172940
$borderColor = #F0F4F9
$codeBgColor = #182B44
$codeBgColor = #F0F4F9
$navbarHeight = 4.375rem
$navbar-vertical-padding = 0.7rem
$navbar-vertical-padding = 0.7rem

176
docs/.vuepress/theme/components/Home.vue
View File

@@ -1,176 +0,0 @@
<template>
<main
class="home"
:aria-labelledby="data.heroText !== null ? 'main-title' : null"
>
<header class="hero">
<img
v-if="data.heroImage"
:src="$withBase(data.heroImage)"
:alt="data.heroAlt || 'hero'"
>
<h1
v-if="data.heroText !== null"
id="main-title"
>
{{ data.heroText || $title || 'Hello' }}
</h1>
<p
v-if="data.tagline !== null"
class="description"
>
{{ data.tagline || $description || 'Welcome to your VuePress site' }}
</p>
<p
v-if="data.actionText && data.actionLink"
class="action"
>
<NavLink
class="action-button"
:item="actionLink"
/>
</p>
</header>
<div
v-if="data.features && data.features.length"
class="features"
>
<div
v-for="(feature, index) in data.features"
:key="index"
class="feature"
>
<h2>{{ feature.title }}</h2>
<p>{{ feature.details }}</p>
</div>
</div>
<Content class="theme-default-content custom" />
<div
v-if="data.footer"
class="footer"
>
{{ data.footer }}
</div>
</main>
</template>
<script>
import NavLink from '@theme/components/NavLink.vue'
export default {
name: 'Home',
components: { NavLink },
computed: {
data () {
return this.$page.frontmatter
},
actionLink () {
return {
link: this.data.actionLink,
text: this.data.actionText
}
}
}
}
</script>
<style lang="stylus">
/* stylelint-disable */
.home
padding $navbarHeight 2rem 0
max-width $homePageWidth
margin 0px auto
display block
.hero
text-align center
img
max-width: 100%
max-height 280px
display block
margin 3rem auto 1.5rem
h1
font-size 3rem
h1, .description, .action
margin 1.8rem auto
.description
max-width 35rem
font-size 1.6rem
line-height 1.3
color lighten($textColor, 40%)
.action-button
display inline-block
font-size 1.2rem
color #fff
background-color $accentColor
padding 0.8rem 1.6rem
border-radius 4px
transition background-color .1s ease
box-sizing border-box
border-bottom 1px solid darken($accentColor, 10%)
&:hover
background-color lighten($accentColor, 10%)
.features
border-top 1px solid $borderColor
padding 1.2rem 0
margin-top 2.5rem
display flex
flex-wrap wrap
align-items flex-start
align-content stretch
justify-content space-between
.feature
flex-grow 1
flex-basis 30%
max-width 30%
h2
font-size 1.4rem
font-weight 500
border-bottom none
padding-bottom 0
color lighten($textColor, 10%)
p
color lighten($textColor, 25%)
.footer
padding 2.5rem
border-top 1px solid $borderColor
text-align center
color lighten($textColor, 25%)
@media (max-width: $MQMobile)
.home
.features
flex-direction column
.feature
max-width 100%
padding 0 2.5rem
@media (max-width: $MQMobileNarrow)
.home
padding-left 1.5rem
padding-right 1.5rem
.hero
img
max-height 210px
margin 2rem auto 1.2rem
h1
font-size 2rem
h1, .description, .action
margin 1.2rem auto
.description
font-size 1.2rem
.action-button
font-size 1rem
padding 0.6rem 1.2rem
.feature
h2
font-size 1.25rem
</style>

4
docs/.vuepress/theme/components/PageEdit.vue
View File

@@ -125,7 +125,7 @@ export default {
.page-edit
@extend $wrapper
padding-top 1rem
padding-top 3rem
padding-bottom 1rem
overflow auto
@@ -144,7 +144,7 @@ export default {
color #A2B5CD
.time
font-weight 400
color #767676
color #a2b5cd
@media (max-width: $MQMobile)
.page-edit

29
docs/.vuepress/theme/components/SidebarButton.vue
View File

@@ -1,22 +1,13 @@
<template>
<div
class="sidebar-button"
@click="$emit('toggle-sidebar')"
>
<svg
class="icon"
xmlns="http://www.w3.org/2000/svg"
aria-hidden="true"
role="img"
viewBox="0 0 448 512"
>
<path
fill="currentColor"
d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"
class=""
/>
</svg>
</div>
<div class="sidebar-button" @click="$emit('toggle-sidebar')">
<svg class="icon" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512">
<path
fill="#fff"
d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"
class=""
/>
</svg>
</div>
</template>
<style lang="stylus">
@@ -28,7 +19,7 @@
height 1.25rem
position absolute
padding 0.6rem
top 0.6rem
top 0.9rem
left 1rem
.icon
display block

2
docs/.vuepress/theme/components/SidebarGroup.vue
View File

@@ -80,8 +80,6 @@ export default {
line-height 1.4
font-weight normal
padding-left 2rem
&:not(.clickable)
opacity 0.5
& > .sidebar-group-items
padding-left 1rem
& > li > .sidebar-link

224
docs/.vuepress/theme/layouts/Layout.vue
View File

@@ -1,151 +1,113 @@
<template>
<div
class="theme-container"
:class="pageClasses"
@touchstart="onTouchStart"
@touchend="onTouchEnd"
>
<Navbar
v-if="shouldShowNavbar"
@toggle-sidebar="toggleSidebar"
/>
<div class="theme-container" :class="pageClasses" @touchstart="onTouchStart" @touchend="onTouchEnd">
<Navbar v-if="shouldShowNavbar" @toggle-sidebar="toggleSidebar" />
<div
class="sidebar-mask"
@click="toggleSidebar(false)"
/>
<div class="sidebar-mask" @click="toggleSidebar(false)" />
<Sidebar
:items="sidebarItems"
@toggle-sidebar="toggleSidebar"
>
<template #top>
<slot name="sidebar-top" />
</template>
<template #bottom>
<slot name="sidebar-bottom" />
</template>
</Sidebar>
<Sidebar :items="sidebarItems" @toggle-sidebar="toggleSidebar">
<template #top>
<slot name="sidebar-top" />
</template>
<template #bottom>
<slot name="sidebar-bottom" />
</template>
</Sidebar>
<Home v-if="$page.frontmatter.home" />
<Page
v-else
:sidebar-items="sidebarItems"
>
<template #top>
<slot name="page-top" />
</template>
<template #bottom>
<slot name="page-bottom" />
</template>
</Page>
</div>
<Page :sidebar-items="sidebarItems">
<template #top>
<slot name="page-top" />
</template>
<template #bottom>
<slot name="page-bottom" />
</template>
</Page>
</div>
</template>
<script>
import Home from '@theme/components/Home.vue'
import Navbar from '@theme/components/Navbar.vue'
import Page from '@theme/components/Page.vue'
import Sidebar from '@theme/components/Sidebar.vue'
import { resolveSidebarItems } from '../util'
import Navbar from '@theme/components/Navbar.vue';
import Page from '@theme/components/Page.vue';
import Sidebar from '@theme/components/Sidebar.vue';
import { resolveSidebarItems } from '../util';
export default {
name: 'Layout',
name: 'Layout',
components: {
Home,
Page,
Sidebar,
Navbar
},
components: {
Page,
Sidebar,
Navbar,
},
data () {
return {
isSidebarOpen: false
}
},
data() {
return {
isSidebarOpen: false,
};
},
computed: {
shouldShowNavbar () {
const { themeConfig } = this.$site
const { frontmatter } = this.$page
if (
frontmatter.navbar === false
|| themeConfig.navbar === false) {
return false
}
return (
this.$title
|| themeConfig.logo
|| themeConfig.repo
|| themeConfig.nav
|| this.$themeLocaleConfig.nav
)
},
computed: {
shouldShowNavbar() {
const { themeConfig } = this.$site;
const { frontmatter } = this.$page;
if (frontmatter.navbar === false || themeConfig.navbar === false) {
return false;
}
return this.$title || themeConfig.logo || themeConfig.repo || themeConfig.nav || this.$themeLocaleConfig.nav;
},
shouldShowSidebar () {
const { frontmatter } = this.$page
return (
!frontmatter.home
&& frontmatter.sidebar !== false
&& this.sidebarItems.length
)
},
shouldShowSidebar() {
const { frontmatter } = this.$page;
return !frontmatter.home && frontmatter.sidebar !== false && this.sidebarItems.length;
},
sidebarItems () {
return resolveSidebarItems(
this.$page,
this.$page.regularPath,
this.$site,
this.$localePath
)
},
sidebarItems() {
return resolveSidebarItems(this.$page, this.$page.regularPath, this.$site, this.$localePath);
},
pageClasses () {
const userPageClass = this.$page.frontmatter.pageClass
return [
{
'no-navbar': !this.shouldShowNavbar,
'sidebar-open': this.isSidebarOpen,
'no-sidebar': !this.shouldShowSidebar
},
userPageClass
]
}
},
pageClasses() {
const userPageClass = this.$page.frontmatter.pageClass;
return [
{
'no-navbar': !this.shouldShowNavbar,
'sidebar-open': this.isSidebarOpen,
'no-sidebar': !this.shouldShowSidebar,
},
userPageClass,
];
},
},
mounted () {
this.$router.afterEach(() => {
this.isSidebarOpen = false
})
},
mounted() {
this.$router.afterEach(() => {
this.isSidebarOpen = false;
});
},
methods: {
toggleSidebar (to) {
this.isSidebarOpen = typeof to === 'boolean' ? to : !this.isSidebarOpen
this.$emit('toggle-sidebar', this.isSidebarOpen)
},
methods: {
toggleSidebar(to) {
this.isSidebarOpen = typeof to === 'boolean' ? to : !this.isSidebarOpen;
this.$emit('toggle-sidebar', this.isSidebarOpen);
},
// side swipe
onTouchStart (e) {
this.touchStart = {
x: e.changedTouches[0].clientX,
y: e.changedTouches[0].clientY
}
},
// side swipe
onTouchStart(e) {
this.touchStart = {
x: e.changedTouches[0].clientX,
y: e.changedTouches[0].clientY,
};
},
onTouchEnd (e) {
const dx = e.changedTouches[0].clientX - this.touchStart.x
const dy = e.changedTouches[0].clientY - this.touchStart.y
if (Math.abs(dx) > Math.abs(dy) && Math.abs(dx) > 40) {
if (dx > 0 && this.touchStart.x <= 80) {
this.toggleSidebar(true)
} else {
this.toggleSidebar(false)
}
}
}
}
}
onTouchEnd(e) {
const dx = e.changedTouches[0].clientX - this.touchStart.x;
const dy = e.changedTouches[0].clientY - this.touchStart.y;
if (Math.abs(dx) > Math.abs(dy) && Math.abs(dx) > 40) {
if (dx > 0 && this.touchStart.x <= 80) {
this.toggleSidebar(true);
} else {
this.toggleSidebar(false);
}
}
},
},
};
</script>

22
docs/.vuepress/theme/styles/code.styl
View File

@@ -20,10 +20,14 @@
border-radius 6px
overflow auto
code
color #fff
color #172940
padding 0
background-color transparent
border-radius 0
pre[class*="language-"]
border 2px solid $borderColor
max-width 100%
overflow-x auto
div[class*="language-"]
position relative
@@ -143,7 +147,7 @@ div[class~="language-php"]:before
code[class*="language-"],
pre[class*="language-"] {
color: #ccc;
color: #A2B5CD;
background: none;
font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace;
font-size: 1em;
@@ -173,7 +177,7 @@ pre[class*="language-"] {
:not(pre) > code[class*="language-"],
pre[class*="language-"] {
background: #2d2d2d;
background: #172940;
}
/* Inline code */
@@ -188,11 +192,11 @@ pre[class*="language-"] {
.token.prolog,
.token.doctype,
.token.cdata {
color: #999;
color: #A2B5CD;
}
.token.punctuation {
color: #ccc;
color: #A2B5CD;
}
.token.tag,
@@ -203,20 +207,20 @@ pre[class*="language-"] {
}
.token.function-name {
color: #68b0f4;
color: #fab00e;
}
.token.boolean,
.token.number,
.token.function {
color: #f1c2cb;
color: #e35169;
}
.token.property,
.token.class-name,
.token.constant,
.token.symbol {
color: #fbc54f;
color: #68b0f4;
}
.token.selector,
@@ -238,7 +242,7 @@ pre[class*="language-"] {
.token.operator,
.token.entity,
.token.url {
color: #67cdcc;
color: #68b0f4;
}
.token.important,

52
docs/.vuepress/theme/styles/index.styl
View File

@@ -68,10 +68,11 @@ body
p.demo
padding 1rem 1.5rem
border 1px solid #ddd
border-radius 4px
border-radius 6px
img
max-width 100%
border-radius 6px
{$contentClass}.custom
padding 0
@@ -109,6 +110,10 @@ blockquote
ul, ol
padding-left 1.2em
li > ul,
li > ol
padding-left 1.8em
strong
font-weight 600
@@ -118,7 +123,7 @@ h1, h2, h3, h4, h5, h6
{$contentClass}:not(.custom) > &
margin-top (0.5rem - $navbarHeight)
padding-top ($navbarHeight + 1rem)
padding-top ($navbarHeight + 2.5rem)
margin-bottom 0
&:first-child
@@ -132,10 +137,10 @@ h1, h2, h3, h4, h5, h6
opacity: 1
h1
position relative
font-weight 900
font-size 3.25rem
line-height 4.25rem
padding-top 3rem !important
h2
font-size 1.5rem
@@ -149,6 +154,14 @@ h3
font-size 1.25rem
line-height 1.875rem
h2 + h3
padding-top ($navbarHeight + 0.5rem) !important
h4
font-size 1.1rem
line-height 1.125rem
padding-top ($navbarHeight + 0.25rem) !important
a.header-anchor
font-size 0.85em
float left
@@ -160,6 +173,30 @@ a.header-anchor
&:hover
text-decoration none
small
position: absolute
margin-top: 7px
display inline-flex
align-items center
margin-left 8px
&::before
content 'Modular Extension'
display inline-block
background-color $accentColor
color white
border-radius 3px
font-size 15px
line-height 18px
padding 4px 8px
font-weight 600
h1 small
position absolute
top 5.25rem
left 0
margin-left 0
margin-top: 0
code, kbd, .line-number
font-family source-code-pro, Menlo, Monaco, Consolas, "Courier New", monospace
@@ -177,13 +214,14 @@ p, ul, ol
hr
border 0
border-top 1px solid $borderColor
border-top 2px solid $borderColor
margin 3rem 0
table
border-collapse collapse
margin 1rem 0
display: block
overflow-x: auto
width 100%
tr
border-top 1px solid #dfe2e5
@@ -191,6 +229,10 @@ tr
&:nth-child(2n)
background-color #f6f8fa
th
white-space nowrap
text-align left
th, td
border 1px solid #dfe2e5
padding .6em 1em

85
docs/assets/app-overview.svg Normal file
View File

@@ -0,0 +1,85 @@
<svg width="793" height="684" viewBox="0 0 793 684" fill="none" xmlns="http://www.w3.org/2000/svg">
<g filter="url(#filter0_dd)">
<rect x="232" y="38" width="457" height="512" fill="white"/>
<path d="M40 166H104V550H50C44.4772 550 40 545.523 40 540V166Z" fill="#18222F"/>
<rect x="104" y="38" width="128" height="512" fill="#F0F4F9"/>
<path d="M40 48C40 42.4772 44.4772 38 50 38H104V102H40V48Z" fill="#2ECFA8"/>
<rect x="40" y="102" width="64" height="64" fill="#F0F4F9"/>
<path d="M69 199.734C66.6562 199.734 62.0156 200.906 62.0156 203.25V204.984H75.9844V203.25C75.9844 200.906 71.3438 199.734 69 199.734ZM64.3594 203.016C65.2031 202.406 67.2188 201.75 69 201.75C70.7812 201.75 72.7969 202.406 73.6406 203.016H64.3594ZM69 198C70.9219 198 72.5156 196.453 72.5156 194.484C72.5156 192.562 70.9219 191.016 69 191.016C67.0781 191.016 65.4844 192.562 65.4844 194.484C65.4844 196.453 67.0781 198 69 198ZM69 192.984C69.8438 192.984 70.5 193.688 70.5 194.484C70.5 195.328 69.8438 195.984 69 195.984C68.1562 195.984 67.5 195.328 67.5 194.484C67.5 193.688 68.1562 192.984 69 192.984ZM76.0312 199.828C77.2031 200.672 78 201.75 78 203.25V204.984H81.9844V203.25C81.9844 201.234 78.5156 200.062 76.0312 199.828ZM75 198C76.9219 198 78.5156 196.453 78.5156 194.484C78.5156 192.562 76.9219 191.016 75 191.016C74.4375 191.016 73.9688 191.109 73.5 191.344C74.1094 192.234 74.4844 193.312 74.4844 194.484C74.4844 195.656 74.1094 196.781 73.5 197.672C73.9688 197.859 74.4375 198 75 198Z" fill="#8196B1"/>
<path d="M69.1875 256L71.1562 258.016H80.0156V268H63.9844V256H69.1875ZM69.9844 253.984H63.9844C62.9062 253.984 62.0156 254.922 62.0156 256V268C62.0156 269.078 62.9062 270.016 63.9844 270.016H80.0156C81.0938 270.016 81.9844 269.078 81.9844 268V258.016C81.9844 256.891 81.0938 256 80.0156 256H72L69.9844 253.984Z" fill="#8196B1"/>
<path d="M71.0156 320.984H72.9844V323H71.0156V320.984ZM71.0156 325.016H72.9844V331.016H71.0156V325.016ZM72 316.016C66.4688 316.016 62.0156 320.469 62.0156 326C62.0156 331.531 66.4688 335.984 72 335.984C77.5312 335.984 81.9844 331.531 81.9844 326C81.9844 320.469 77.5312 316.016 72 316.016ZM72 334.016C67.5938 334.016 63.9844 330.406 63.9844 326C63.9844 321.594 67.5938 317.984 72 317.984C76.4062 317.984 80.0156 321.594 80.0156 326C80.0156 330.406 76.4062 334.016 72 334.016Z" fill="#8196B1"/>
<path d="M79.4531 390.984C79.4531 390.656 79.5 390.328 79.5 390C79.5 389.672 79.4531 389.344 79.4531 389.016L81.5625 387.375C81.75 387.234 81.7969 386.953 81.6562 386.719L79.6406 383.25C79.5469 383.109 79.4062 383.016 79.2188 383.016C79.1719 383.016 79.0781 383.016 79.0312 383.062L76.5469 384.047C76.0312 383.672 75.4688 383.297 74.8594 383.062L74.4844 380.438C74.4375 380.203 74.25 380.016 74.0156 380.016H69.9844C69.75 380.016 69.5625 380.203 69.5156 380.438L69.1406 383.062C68.5312 383.297 67.9688 383.672 67.4531 384.047L64.9688 383.062C64.875 383.016 64.8281 383.016 64.7812 383.016C64.5938 383.016 64.4531 383.109 64.3594 383.25L62.3438 386.719C62.2031 386.953 62.25 387.234 62.4375 387.375L64.5469 389.016C64.5469 389.344 64.5 389.672 64.5 390C64.5 390.328 64.5469 390.656 64.5469 390.984L62.4375 392.625C62.25 392.766 62.2031 393.047 62.3438 393.281L64.3594 396.75C64.4531 396.891 64.5938 396.984 64.7812 396.984C64.8281 396.984 64.9219 396.984 64.9688 396.938L67.4531 395.953C67.9688 396.328 68.5312 396.703 69.1406 396.938L69.5156 399.562C69.5625 399.797 69.75 399.984 69.9844 399.984H74.0156C74.25 399.984 74.4375 399.797 74.4844 399.562L74.8594 396.938C75.4688 396.703 76.0312 396.328 76.5469 395.953L79.0312 396.938C79.125 396.984 79.1719 396.984 79.2188 396.984C79.4062 396.984 79.5469 396.891 79.6406 396.75L81.6562 393.281C81.7969 393.047 81.75 392.766 81.5625 392.625L79.4531 390.984ZM77.4375 389.25C77.4844 389.578 77.4844 389.812 77.4844 390C77.4844 390.188 77.4844 390.422 77.4375 390.75L77.2969 391.875L78.1875 392.578L79.2656 393.422L78.5625 394.594L77.2969 394.078L76.2656 393.703L75.375 394.359C74.9531 394.688 74.5312 394.922 74.1094 395.109L73.0781 395.531L72.8906 396.656L72.7031 398.016H71.2969L71.1094 396.656L70.9688 395.531L69.8906 395.109C69.4688 394.922 69.0469 394.688 68.6719 394.359L67.7344 393.703L66.7031 394.125L65.4375 394.641L64.7344 393.422L65.8125 392.578L66.7031 391.875L66.5625 390.75C66.5156 390.422 66.5156 390.188 66.5156 390C66.5156 389.812 66.5156 389.578 66.5625 389.25L66.7031 388.125L65.8125 387.422L64.7344 386.578L65.4375 385.406L66.7031 385.922L67.7344 386.297L68.625 385.641C69.0469 385.312 69.4688 385.078 69.8906 384.891L70.9219 384.469L71.1094 383.344L71.2969 381.984H72.7031L72.8906 383.344L73.0312 384.469L74.1094 384.891C74.5312 385.078 74.9531 385.312 75.3281 385.641L76.2188 386.297L77.2969 385.875L78.5625 385.359L79.2656 386.578L78.1875 387.422L77.2969 388.125L77.4375 389.25ZM72 386.016C69.7969 386.016 68.0156 387.797 68.0156 390C68.0156 392.203 69.7969 393.984 72 393.984C74.2031 393.984 75.9844 392.203 75.9844 390C75.9844 387.797 74.2031 386.016 72 386.016ZM72 392.016C70.9219 392.016 69.9844 391.078 69.9844 390C69.9844 388.922 70.9219 387.984 72 387.984C73.0781 387.984 74.0156 388.922 74.0156 390C74.0156 391.078 73.0781 392.016 72 392.016Z" fill="#8196B1"/>
<path d="M72 508.016C66.4688 508.016 62.0156 512.469 62.0156 518C62.0156 523.531 66.4688 527.984 72 527.984C77.5312 527.984 81.9844 523.531 81.9844 518C81.9844 512.469 77.5312 508.016 72 508.016ZM67.0781 524.281C67.5 523.391 70.125 522.5 72 522.5C73.875 522.5 76.5 523.391 76.9219 524.281C75.5625 525.359 73.875 526.016 72 526.016C70.125 526.016 68.4375 525.359 67.0781 524.281ZM78.375 522.828C76.9219 521.094 73.4531 520.484 72 520.484C70.5469 520.484 67.0781 521.094 65.625 522.828C64.6406 521.469 63.9844 519.828 63.9844 518C63.9844 513.594 67.5938 509.984 72 509.984C76.4062 509.984 80.0156 513.594 80.0156 518C80.0156 519.828 79.3594 521.469 78.375 522.828ZM72 512C70.0781 512 68.4844 513.547 68.4844 515.516C68.4844 517.438 70.0781 518.984 72 518.984C73.9219 518.984 75.5156 517.438 75.5156 515.516C75.5156 513.547 73.9219 512 72 512ZM72 517.016C71.1562 517.016 70.5 516.312 70.5 515.516C70.5 514.672 71.1562 514.016 72 514.016C72.8438 514.016 73.5 514.672 73.5 515.516C73.5 516.312 72.8438 517.016 72 517.016Z" fill="#8196B1"/>
<path d="M689 230H753V486H689V230Z" fill="#F0F4F9"/>
<path d="M689 38H743C748.523 38 753 42.4772 753 48V102H689V38Z" fill="#E4EAF1"/>
<path d="M689 102H753V166H689V102Z" fill="#E4EAF1"/>
<path d="M689 166H753V230H689V166Z" fill="#E4EAF1"/>
<path d="M689 486H753V540C753 545.523 748.523 550 743 550H689V486Z" fill="#E4EAF1"/>
<path d="M724.984 523.016V517.016C724.984 515.734 724.625 514.672 723.906 513.828C723.188 512.953 722.219 512.516 721 512.516C719.781 512.516 718.812 512.953 718.094 513.828C717.375 514.672 717.016 515.734 717.016 517.016V523.016H724.984ZM727 521.984L729.016 524V524.984H712.984V524L715 521.984V517.016C715 515.453 715.391 514.094 716.172 512.938C716.984 511.781 718.094 511.031 719.5 510.688V509.984C719.5 509.578 719.641 509.234 719.922 508.953C720.203 508.641 720.562 508.484 721 508.484C721.438 508.484 721.797 508.641 722.078 508.953C722.359 509.234 722.5 509.578 722.5 509.984V510.688C723.906 511.031 725 511.781 725.781 512.938C726.594 514.094 727 515.453 727 517.016V521.984ZM722.406 527.422C722 527.797 721.531 527.984 721 527.984C720.469 527.984 720 527.797 719.594 527.422C719.188 527.016 718.984 526.547 718.984 526.016H723.016C723.016 526.547 722.812 527.016 722.406 527.422Z" fill="#182B44"/>
<path d="M720.016 64.9844H721.984V67H720.016V64.9844ZM720.016 69.0156H721.984V75.0156H720.016V69.0156ZM721 60.0156C715.469 60.0156 711.016 64.4688 711.016 70C711.016 75.5312 715.469 79.9844 721 79.9844C726.531 79.9844 730.984 75.5312 730.984 70C730.984 64.4688 726.531 60.0156 721 60.0156ZM721 78.0156C716.594 78.0156 712.984 74.4062 712.984 70C712.984 65.5938 716.594 61.9844 721 61.9844C725.406 61.9844 729.016 65.5938 729.016 70C729.016 74.4062 725.406 78.0156 721 78.0156Z" fill="#182B44"/>
<path d="M721 140.562L713.641 134.797L712 136.062L721 143.047L730 136.062L728.359 134.797L721 140.562ZM721 137.984L728.359 132.266L730 131L721 124.016L712 131L713.641 132.266L721 137.984ZM721 126.547L726.719 131L721 135.453L715.281 131L721 126.547Z" fill="#182B44"/>
<path d="M715 198.984V197.016H727V198.984H715ZM712 192H730V194.016H712V192ZM718.984 204V201.984H723.016V204H718.984Z" fill="#182B44"/>
<path fill-rule="evenodd" clip-rule="evenodd" d="M84.4135 73.3189C84.2291 73.2728 84.0754 73.2267 83.9371 73.1652C83.7988 73.1038 83.6912 73.0269 83.599 72.9347C83.6912 72.1203 83.599 71.4134 83.6759 70.6143C83.9832 67.5102 85.9348 68.4937 87.6866 67.9866C88.7777 67.6793 89.8687 67.0492 90.1453 65.7584C88.9467 64.36 87.6098 63.1307 86.1499 62.0857C81.4016 58.705 75.1934 57.3527 69.5537 58.2901C70.4378 59.834 71.7554 61.0181 73.2837 61.7476C73.2837 61.7476 71.7554 61.7476 70.4454 60.7691C70.0613 60.9228 69.2925 61.2252 68.9237 61.4096C71.9202 64.2832 76.6071 64.6059 79.9725 62.0243C79.9571 62.055 79.6651 62.5006 79.3117 64.36C78.528 68.3247 76.269 68.0173 73.4723 67.0185C67.6636 64.9132 64.4673 66.8648 61.5629 62.8694C60.7177 63.3458 60.1953 64.2371 60.1953 65.2052C60.1953 66.204 60.7485 67.0492 61.5476 67.5102C61.9838 66.9315 62.1794 66.7669 62.9402 66.7669C61.7629 67.4344 61.6244 68.0173 61.1173 69.6309C60.5026 71.5825 60.7638 73.5802 57.8902 74.1026C56.3689 74.1795 56.3997 75.209 55.8464 76.7457C55.1549 78.7434 54.2329 79.5425 52.435 81.4326C53.1726 82.3239 53.941 82.4315 54.7247 82.1088C56.3382 81.4326 57.5829 79.3427 58.7508 77.9904C60.057 76.4845 63.1918 77.1299 65.5583 75.6547C67.1872 74.6558 67.9863 73.3035 66.9106 71.0139C67.6021 71.7822 68.017 72.7503 68.0785 73.7799C70.8138 73.4265 74.4711 76.7611 77.8057 77.3143C77.4677 76.884 77.1911 76.423 76.9913 75.9467C76.6071 75.0246 76.4842 74.1795 76.561 73.4418C76.8683 75.2705 78.7124 77.6216 81.6782 77.8368C82.4312 77.8982 83.261 77.806 84.1215 77.5448C85.1511 77.2375 86.1038 76.8379 87.241 77.0531C88.0862 77.2067 88.8699 77.637 89.3616 78.3593C90.0992 79.4349 91.7128 79.6654 92.435 78.3439C90.8061 74.0873 86.319 73.8107 84.4135 73.3189Z" fill="white"/>
<path fill-rule="evenodd" clip-rule="evenodd" d="M62.5626 139.763L71.5938 143.907C71.8646 144.031 72.1354 144.031 72.4062 143.907L81.4349 139.763C81.8112 139.591 81.9995 139.298 82 138.885V128.115C81.9996 128.057 81.994 127.999 81.983 127.941C81.983 127.924 81.983 127.907 81.983 127.89C81.9729 127.848 81.9599 127.807 81.9442 127.767L81.9297 127.726C81.9079 127.675 81.8821 127.627 81.8521 127.58L81.8302 127.549C81.8043 127.513 81.776 127.479 81.7454 127.447L81.6993 127.416C81.6658 127.384 81.6302 127.355 81.5926 127.329L81.5659 127.309C81.5241 127.282 81.4805 127.258 81.4349 127.237L72.4038 123.093C72.133 122.969 71.8622 122.969 71.5914 123.093L62.5626 127.237C62.5171 127.258 62.4734 127.282 62.4317 127.309L62.405 127.329C62.3674 127.355 62.3318 127.384 62.2983 127.416L62.2668 127.45C62.2361 127.482 62.2079 127.516 62.1819 127.551L62.1601 127.583C62.1301 127.629 62.1042 127.677 62.0825 127.728L62.0558 127.767C62.0401 127.807 62.0271 127.848 62.017 127.89C62.017 127.907 62.017 127.924 62.017 127.941C62.006 127.999 62.0004 128.057 62 128.115V138.885C62 139.297 62.1876 139.59 62.5626 139.763H62.5626ZM63.9377 129.628L71.0287 132.888V141.528L63.9377 138.265V129.628ZM72.9688 141.525V132.888L80.0599 129.628V138.268L72.9688 141.525ZM71.9988 125.03L78.7115 128.115L71.9988 131.201L65.286 128.115L71.9988 125.03Z" fill="#182B44"/>
<rect x="117" y="114" width="104" height="16" rx="4" fill="#E4EAF1"/>
<rect x="309" y="62" width="104" height="16" rx="4" fill="#F0F4F9"/>
<rect x="264" y="128" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="264" y="209" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="264" y="290" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="264" y="371" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="508" y="128" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="589" y="128" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="508" y="209" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="589" y="209" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="508" y="290" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="589" y="290" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="346" y="128" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="346" y="209" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="346" y="290" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="346" y="371" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="427" y="128" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="427" y="209" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="427" y="290" width="69" height="69" rx="4" fill="#F0F4F9"/>
<rect x="264" y="52" width="36" height="36" rx="18" fill="#F0F4F9"/>
<rect x="117" y="142" width="78" height="16" rx="4" fill="#E4EAF1"/>
<rect x="117" y="236" width="78" height="16" rx="4" fill="#E4EAF1"/>
<rect x="117" y="198" width="71" height="16" rx="4" fill="#E4EAF1"/>
<rect x="117" y="170" width="90" height="16" rx="4" fill="#E4EAF1"/>
<rect x="117" y="264" width="90" height="16" rx="4" fill="#E4EAF1"/>
<rect x="622" y="52" width="36" height="36" rx="18" fill="#2ECFA8"/>
<path d="M646.984 70.9844H640.984V76.9844H639.016V70.9844H633.016V69.0156H639.016V63.0156H640.984V69.0156H646.984V70.9844Z" fill="white"/>
<rect x="578" y="52" width="36" height="36" rx="18" fill="#C3F1E6"/>
<path d="M593.188 64L595.156 66.0156H604.016V76H587.984V64H593.188ZM593.984 61.9844H587.984C586.906 61.9844 586.016 62.9219 586.016 64V76C586.016 77.0781 586.906 78.0156 587.984 78.0156H604.016C605.094 78.0156 605.984 77.0781 605.984 76V66.0156C605.984 64.8906 605.094 64 604.016 64H596L593.984 61.9844Z" fill="#2ECFA8"/>
<rect x="535" y="53" width="34" height="34" rx="17" fill="white" stroke="#D3DAE4" stroke-width="2"/>
<path d="M546.328 70.7031C547.203 71.5781 548.266 72.0156 549.516 72.0156C550.766 72.0156 551.828 71.5781 552.703 70.7031C553.578 69.8281 554.016 68.7656 554.016 67.5156C554.016 66.2656 553.578 65.2031 552.703 64.3281C551.828 63.4531 550.766 63.0156 549.516 63.0156C548.266 63.0156 547.203 63.4531 546.328 64.3281C545.453 65.2031 545.016 66.2656 545.016 67.5156C545.016 68.7656 545.453 69.8281 546.328 70.7031ZM555.516 72.0156L560.484 76.9844L558.984 78.4844L554.016 73.5156V72.7188L553.734 72.4375C552.547 73.4688 551.141 73.9844 549.516 73.9844C547.703 73.9844 546.156 73.3594 544.875 72.1094C543.625 70.8594 543 69.3281 543 67.5156C543 65.7031 543.625 64.1719 544.875 62.9219C546.156 61.6406 547.703 61 549.516 61C551.328 61 552.859 61.6406 554.109 62.9219C555.359 64.1719 555.984 65.7031 555.984 67.5156C555.984 69.1406 555.469 70.5469 554.438 71.7344L554.719 72.0156H555.516Z" fill="#A2B5CD"/>
<rect x="104.435" y="38" width="128" height="64" fill="#E4EAF1"/>
<rect x="117" y="224" width="104" height="2" fill="#E4EAF1"/>
<rect opacity="0.25" x="48" y="484" width="48" height="2" fill="#8196B1"/>
<path d="M127 79.4688L115.375 64.9844C119.156 62.3281 123.031 61 127 61C130.969 61 134.844 62.3281 138.625 64.9844L127 79.4688Z" fill="#A2B5CD"/>
<rect x="147" y="62" width="74" height="16" rx="4" fill="#A2B5CD"/>
</g>
<circle cx="72" cy="612" r="32" fill="#2ECFA8"/>
<circle cx="168" cy="612" r="32" fill="#2ECFA8"/>
<circle cx="721" cy="612" r="32" fill="#2ECFA8"/>
<path d="M75.1374 602.545V620H71.4471V606.048H71.3448L67.3477 608.554V605.281L71.6687 602.545H75.1374Z" fill="white"/>
<path d="M161.856 620V617.341L168.069 611.588C168.598 611.077 169.041 610.616 169.399 610.207C169.762 609.798 170.038 609.398 170.225 609.006C170.413 608.608 170.507 608.179 170.507 607.719C170.507 607.207 170.39 606.767 170.157 606.398C169.924 606.023 169.606 605.736 169.203 605.537C168.799 605.332 168.342 605.23 167.831 605.23C167.297 605.23 166.831 605.338 166.433 605.554C166.035 605.77 165.728 606.08 165.512 606.483C165.297 606.886 165.189 607.366 165.189 607.923H161.686C161.686 606.781 161.944 605.79 162.461 604.949C162.978 604.108 163.703 603.457 164.635 602.997C165.566 602.537 166.64 602.307 167.856 602.307C169.106 602.307 170.194 602.528 171.12 602.972C172.052 603.409 172.777 604.017 173.294 604.795C173.811 605.574 174.069 606.466 174.069 607.472C174.069 608.131 173.939 608.781 173.677 609.423C173.422 610.065 172.964 610.778 172.305 611.562C171.646 612.341 170.717 613.276 169.518 614.366L166.97 616.864V616.983H174.299V620H161.856Z" fill="white"/>
<circle cx="461" cy="612" r="32" fill="#2ECFA8"/>
<path d="M460.956 620.239C459.684 620.239 458.55 620.02 457.556 619.582C456.567 619.139 455.786 618.531 455.212 617.759C454.644 616.98 454.351 616.082 454.334 615.065H458.05C458.073 615.491 458.212 615.866 458.468 616.19C458.729 616.509 459.076 616.756 459.507 616.932C459.939 617.108 460.425 617.196 460.965 617.196C461.527 617.196 462.025 617.097 462.456 616.898C462.888 616.699 463.226 616.423 463.471 616.071C463.715 615.719 463.837 615.312 463.837 614.852C463.837 614.386 463.706 613.974 463.445 613.616C463.189 613.253 462.82 612.969 462.337 612.764C461.86 612.56 461.292 612.457 460.632 612.457H459.005V609.747H460.632C461.189 609.747 461.681 609.651 462.107 609.457C462.539 609.264 462.874 608.997 463.113 608.656C463.351 608.31 463.471 607.906 463.471 607.446C463.471 607.009 463.365 606.625 463.155 606.295C462.951 605.96 462.661 605.699 462.286 605.511C461.917 605.324 461.485 605.23 460.99 605.23C460.49 605.23 460.033 605.321 459.618 605.503C459.203 605.679 458.871 605.932 458.621 606.261C458.371 606.591 458.238 606.977 458.221 607.42H454.684C454.701 606.415 454.988 605.528 455.544 604.761C456.101 603.994 456.851 603.395 457.794 602.963C458.743 602.526 459.814 602.307 461.007 602.307C462.212 602.307 463.266 602.526 464.169 602.963C465.073 603.401 465.775 603.991 466.275 604.736C466.78 605.474 467.03 606.304 467.025 607.224C467.03 608.202 466.726 609.017 466.113 609.67C465.505 610.324 464.712 610.739 463.735 610.915V611.051C465.019 611.216 465.996 611.662 466.667 612.389C467.343 613.111 467.678 614.014 467.672 615.099C467.678 616.094 467.391 616.977 466.811 617.75C466.238 618.523 465.445 619.131 464.434 619.574C463.422 620.017 462.263 620.239 460.956 620.239Z" fill="white"/>
<path d="M713.518 616.932V614.026L720.805 602.545H723.31V606.568H721.827L717.234 613.838V613.974H727.589V616.932H713.518ZM721.896 620V616.045L721.964 614.759V602.545H725.424V620H721.896Z" fill="white"/>
<defs>
<filter id="filter0_dd" x="0" y="0" width="793" height="592" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
<feFlood flood-opacity="0" result="BackgroundImageFix"/>
<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/>
<feOffset dy="2"/>
<feGaussianBlur stdDeviation="20"/>
<feColorMatrix type="matrix" values="0 0 0 0 0.0901961 0 0 0 0 0.160784 0 0 0 0 0.25098 0 0 0 0.05 0"/>
<feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow"/>
<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"/>
<feOffset dy="5"/>
<feGaussianBlur stdDeviation="5"/>
<feColorMatrix type="matrix" values="0 0 0 0 0.0901961 0 0 0 0 0.160784 0 0 0 0 0.25098 0 0 0 0.1 0"/>
<feBlend mode="normal" in2="effect1_dropShadow" result="effect2_dropShadow"/>
<feBlend mode="normal" in="SourceGraphic" in2="effect2_dropShadow" result="shape"/>
</filter>
</defs>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

BIN
docs/assets/getting-started/quickstart/add-field.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1019 KiB

BIN
docs/assets/getting-started/quickstart/create-item.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 851 KiB

BIN
docs/assets/getting-started/quickstart/empty-state.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 878 KiB

BIN
docs/assets/getting-started/quickstart/permissions.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 943 KiB

BIN
docs/assets/getting-started/quickstart/terminal-install.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 460 KiB

BIN
docs/assets/getting-started/quickstart/terminal-start.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 355 KiB

63
docs/concepts/activity-and-versions.md
View File

@@ -1,63 +0,0 @@
# Activity & Versions
> Directus stores detailed records of all changes made to data through the App and API. This gives a comprehensive
> accountability log of who did what, and when. This also powers the Directus versioning system, which allows storing
> alternate versions/revisions of items.
## Activity
This is a log of all events that have occurred within the project. Activity can be accessed in two ways, via the main
[Activity Module](/concepts/app-overview#activity-history), or within the sidebar of individual
[Item Detail](/concepts/app-overview#item-detail) pages. The following information is stored for each event's activity
item:
- Action
- User
- Datetime
- IP Address
- User Agent
- Collection
- Item
- Comment (when applicable)
::: tip Readonly
For proper accountability, activity records are readonly. Administrators should avoid changing, deleting, or truncating
this data.
:::
::: warning External Events
Directus can only track events that pass through the platform's middleware. Changes made directly to the database, or by
other external means, are not included in the activity log.
:::
## Versions
Every change made to items in Directus are also stored as a versioned snapshot. This additional data is also linked to
the specific Activity event which created it. Below are the two key pieces of information stored for each version:
- Data — A full snapshot of the item _after_ the event
- Delta — The specific field data changed by this event
<!-- @TODO ::: tip Customizing Version Data
Since versions store a full data snapshot and delta, the
`directus_revisions` collection can quickly grow quite large, increasing database size and
potentially decreasing performance. To remedy this, Directus allows
[configuring version scope](/concepts/app-overview) per collection to set the exact field data
saved.
::: -->
::: tip Creating Detached Versions
You can also create a new version for an item without saving the data to the parent item itself. This allows you to
"stage" changes to an item that may already be live/published.
:::
### Relevant Guides
- [Reverting an Item](/guides/items#reverting-an-item)
- [Changing an Item's Version](/guides/items)

31
docs/concepts/activity.md Normal file
View File

@@ -0,0 +1,31 @@
# Activity
> Directus stores detailed records of all data changes made via the App and API. This gives a comprehensive accountability log of who did what, and when. This also powers the Directus versioning system, which allows storing alternate versions/revisions of items.
The Activity Log tracks all events that have occurred within the project. Activity can be accessed in two ways, via the main
[Activity Module](/concepts/application/#activity-log), or within the sidebar of individual
[Item Detail](/concepts/application/#item-detail) pages. The following information is stored for each event's activity item:
## Activity Fields
- **User** — The Directus user that performed the action
- **Action** — The specific action taken, eg: Create, Update, Delete, Authenticate
- **TimeStamp** — The timestamp of when the action was performed
- **IP Address** — The IP address of the device from which the action was performed
- **User Agent** — The description of the browser that was used to perform the action
- **Collection** — The Collection affected by the action
- **Item** — The item (within the above Collection) affected by the action
- **Comment** — When applicable; the comment left by the user
::: tip Readonly
For proper accountability, activity records are readonly. Administrators should avoid changing, deleting, or truncating
this data.
:::
::: warning External Events
Directus can only track events that pass through the platform's middleware. Changes made directly to the database, or by other external means, are not included.
:::

105
docs/concepts/app-extensions.md
View File

@@ -1,105 +0,0 @@
# App Extensions
> Directus has been architected as completely modular and extensible. There are four keystone component types within the
> App. Out-of-the-box components are configurable, or altogether new components can be created as extensions.
## Modules
Modules are the highest and broadest level of organization within the App. All core functionality within the App (other
than authentication and activity) can be bucketed into one of the following five modules:
- Collections — The primary way to view and interact with database content
- User Directory — A dedicated section for the platform's system Users
- File Library — An aggregate of all files uploaded and managed within the platform
- Documentation — A tailored, in-app portal for the platform's concepts, guides, and reference
- Settings — An Admin-Only section for configuring the project and system settings
In addition to these core modules, custom modules offer a _blank canvas_ for creating altogether new/different
experiences within the App, such as proprietary dashboards, compound datasets, or third-party integrations (eg: a Stripe
Payments Console).
### Relevant Guides
- [Creating a Custom Module](/guides/extensions/modules)
## Layouts
Layouts provide different ways for presenting, browsing, visualizing, or even managing sets of data. Most commonly shown
on Collection Detail pages and contextual modals for item selection. Directus includes several Layout options
out-of-the-box, each with different features and configuration options.
### Table
This tabular layout supports all forms of data, and is therefore the default within the Collections module. It includes
the following features/options:
- Toggle & Reorder Field Columns (Option)
- Row Spacing (Option)
- Manual Ordering
- Column Sort
- Column Resizing
- Select All
### Cards
This tiled layout is ideal for collections that prioritize an image. It is the default for both the
[User Directory](/guides/users) (shows the avatar) and [File Library](/guides/files) (shows asset thumbnail). It
includes the following features/options:
- Image Source (Option)
- Title (Option)
- Subtitle (Option)
- Image Fit (Option)
- Fallback Icon (Option)
- Card Size
- Sort Field & Direction
- Select All
<!-- ### Calendar
This temporal layout is ideal for collections that prioritize a date and/or time. It is the default for the [Activity Page](/concepts/activity-and-versions). It includes the following features/options:
* @TODO
In addition to these core layouts, custom layouts allow for creating more tailored or proprietary ways to experience data within the App, such as charts, seating charts, or Maps. -->
### Relevant Guides
- [Creating a Custom Layout](/guides/extensions/layouts)
## Interfaces
Interfaces provide a multitude of ways to view or interact with field data on
[Item Detail](/concepts/app-overview#item-detail) page forms. Every interface supports a specific subset of field
[types](/reference/field-types) (eg: String), which determines how the data will be stored. For example, the _Text
Input_ interface can manage most types of data, but might not be ideal for dates, where a _Calendar_ interface excels.
Directus includes many Interfaces out-of-the-box:
- Text Input
- @TODO List all core interfaces, or link to an exhaustive reference?
In addition to these core interfaces, custom interfaces allow for creating more tailored or proprietary ways to view or
manage field data, such as bespoke layout builders, skeuomorphic knobs, or relational views for third-party data (eg:
Stripe Credit Card UI).
### Relevant Guides
- [Creating a Custom Interface](/guides/extensions/interfaces)
## Displays
Displays are the smaller, read-only counterpart to Interfaces, defining how a field's data will be displayed inline on
[Item Detail](/concepts/app-overview#item-detail) pages, Modals, and even within Interfaces themselves. For example, you
may have a "Status" field that uses a _Dropdown_ Interface on the Item Detail page, and a _Color Dot_ Display when the
field is referenced throughout the rest of the App. Directus includes many Displays out-of-the-box:
- Raw
- Formatted Value
- @TODO List all core interfaces, or link to an exhaustive reference?
In addition to these core displays, custom displays allow for creating customized ways to view or represent field data,
such as progress indicators, relational data tooltips, or specific formatting options.
### Relevant Guides
- [Creating a Custom Display](/guides/extensions/displays)

213
docs/concepts/app-overview.md
View File

@@ -1,213 +0,0 @@
# App Overview
> The Directus App is the presentation layer for your data, content, and assets. It uses a left-to-right visual
> hierarchy for organization and navigation. Below we cover the App's global elements and individual pages.
## Global Elements
<img class="full shadow" src="https://svgshare.com/i/Q8H.svg" />
<img class="full no-margin" src="https://svgshare.com/i/Q8J.svg" />
### 1. Module Bar
- **Project Logo** — Displays your configured project logo and project color (defaults to the Directus logo and color).
If configured, clicking this component will navigate to the Project URL. During platform activity, an indeterminate
progress indicator will also be shown here.
- **Modules** — Any available modules are listed below the project logo. These may be turned off or reordered based on
your [role's configuration](/concepts/users-roles-and-permissions), but by default this includes:
- [Collections](/concepts/app-overview)
- [User Directory](/concepts/app-overview)
- [File Library](/concepts/app-overview)
- [Documentation](/concepts/app-overview)
- [Settings](/concepts/app-overview) — Admin only
- [Custom Modules](/guides/extensions/modules) — If configured
- **Current User Menu** — This component displays the authenticated user's name and avatar. Hovering over this menu
exposes the Log Out button.
### 2. Navigation Bar
- **Project Name** — Shows the name of your current project (see [Project Settings](/guides/white-labeling)), as well as
the quality of your project's API connection.
- **Navigation** — This is a dynamic navigation based on your current module. Some modules also support
[Presets and/or Bookmarks](/guides/roles-and-permissions), which are ways to link to more specific data-sets.
### 3. Page
- **Header** — A fixed section at the top of each page, the header includes:
- Page Icon — Clicking this navigates back to the previous page
- Module Title — Clicking this navigates to the parent module/section
- Page Title — Displays the current page's title
- Action Buttons — On the right-side of the header are contextual buttons for specific page actions. Please note that
some primary action buttons have a "..." icon beside them that provides additional options when clicked.
- **Page Content** — This displays the content of the page you navigated to.
### 4. Page Sidebar
- **Page Components** — Lists any contextual page components available. The "Info" component is available on every page,
explaining the page's general purpose and relevant details. Clicking any sidebar component will accordion it open. If
the App window is large enough, the sidebar will automatically open, and can be closed by clicking the "X" in the
top-right.
- **Notifications Tray** — Fixed to the bottom of the page sidebar, this button opens a tray of recent user
notifications, and provides a link to the [Activity History](/concepts/app-overview) page.
## Collections
This module is the primary way for interacting with your database content. Here you can access your collections, browse
their items, and navigate to individual item forms.
### Collection Listing
A page that lists the collections available to the current user. This is the landing page of the module, and effectively
the same as its navigation listing.
### Collection Detail
Provides a configurable layout to browse or visualize items within a given collection. Like other browse pages, there
are many available features, including:
- [Creating Items](/guides/items#creating-items)
- [Browsing Items](/guides/items#browsing-items)
- [Searching](/guides/items#searching)
- [Layouts](/guides/items#layouts)
- [Advanced Filter](/guides/items#advanced-filter)
- [Bookmarking](/guides/items#bookmark)
- [Updating Items](/guides/items#updating-items)
- [Deleting Items](/guides/items#deleting-items)
- [Export Data](/guides/items#export-data)
### Item Detail
Most layouts on the browse page support navigating to individual item detail pages, where you a presented with a
[customizable form](/guides/fields#adjusting-fields-layout) for viewing/editing the item's content. Like other detail
pages, there are many available features, including:
- [Updating an Item](/guides/items#updating-item)
- [Reverting an Item](/guides/items#reverting-item)
- [Revisions](/guides/items#revisions)
- [Comments](/guides/items#comments)
## User Directory
A module includes a comprehensive listing of all system users within your project. This page has the same features and
configuration as [Collection Detail](/concepts/app-overview).
### User Detail
Similar to other [Item Detail](/concepts/app-overview) pages, this page provides a custom form for viewing system users.
This is also used for editing the "Profile Page" of the current user, which is accessible from the
[User Menu](/concepts/app-overview). Directus ships with a full-featured user system, with the following fields:
- **First Name** — The user's given name
- **Last Name** — The user's family name
- **Email** — The user's email address used for login/authenticating and email updates
- **Password** — The private string used for login/authenticating (stored as a secure hash)
- **Avatar** — An image displayed throughout the App that represents the user
- **Location** — Can be used for the user's city, country, office name, etc
- **Title** — The name of the position the user holds at their company or organization
- **Description** — A description or bio of the user
- **Tags** — A set of keywords useful when searching within the User Directory
- **Timezone** — (User Preference) The timezone of the user
- **Language** — (User Preference) The language to use for this user's App language
- **Theme** — (User Preference) Light, Dark, or Auto (based on the user's OS preferences)
- **Two-Factor Auth** — (User Preference) Enables authenticating with 2FA
- **Status** — (Admin Only) Determines if the user is active within the App/API
- **Role** — (Admin Only) The user's role determines their permissions and access
- **Token** — (Admin Only) A static string used for authenticating within the API
The sidebar's info component also includes the following readonly details:
- **User Key** — The primary key of the user
- **Last Access** — The timestamp of the user's last App or API action
- **Last Page** — The last App page accessed by the user
::: tip Extending Users
While the fields included out-of-the-box are locked from schema changes, you can extend Directus Users to include
additional proprietary fields within [Settings > Data Model](/concepts/data-model).
:::
## File Library
This module aggregates all files within the project into one consolidated library. This page has the same features and
configuration as [Collection Detail](/concepts/app-overview).
### File Detail
Similar to other [Item Detail](/concepts/app-overview) pages, this page provides a custom form for viewing assets and
embeds. Directus ships with a full-featured system for digital asset management, with the following fields:
- **Title** — Pulled from the file metadata if available, falls back to a formatted version of the filename
- **Description** — Pulled from the file metadata if available
- **Tags** — Pulled from the file metadata if available
- **Location** — Pulled from the file metadata if available
- **Storage** — The storage adapter where the asset is saved (readonly)
- **Filename Disk** — The actual name of the file within the storage adapter
- **Filename Download** — The name used when downloading the file via _Content-Disposition_
The sidebar's info component also includes the following readonly details:
- **Type** — The MIME type of the file, displayed in the App as a formatted media type
- **Dimensions** — (Images Only) The width and height of the image in pixels
- **Size** — The file-size the asset takes up within the storage adapter
- **Created** — The timestamp of when the file was uploaded to the project
- **Owner** — The Directus user that uploaded the file to the project
- **Folder** — The current parent folder that contains the file
- **Metadata** — Metadata JSON dump of the file's EXIF, IPTC, and ICC information
::: tip Extending Files
While the fields included out-of-the-box are locked from schema changes, you can extend Directus Files to include
additional proprietary fields within [Settings > Data Model](/concepts/data-model).
:::
## Documentation
This module is an internal set of guides, concepts, and reference docs for your project's specific version of Directus.
It also includes a dynamic [API Reference](/reference/api/introduction) that is dynamically tailored to your custom
schema. The docs are organized into four distinct sections:
- [Getting Started](/getting-started/introduction) — Novice Oriented. For a platform intro and installation.
- [Concepts](/concepts/app-overview) — Learning Oriented. For understanding the platform.
- [Guides](/concepts/roles-and-permissions) — Problem Oriented. Follow along with steps while working.
- [Reference](/reference/api/introduction) — Information Oriented. Look up info and specs while working.
::: tip Updating the Docs
Our docs are written in markdown (with some additional VuePress styling like this hint box), and available for
editing/fixing via [GitHub](https://github.com/directus/directus).
:::
## Activity History
This module provides a collective timeline of all actions taken within the project. This is a great way to audit user
activity or enforce accountability. This is the only system module that is not in the module bar by default — instead
being located within the notifications tray of the page sidebar. This page has the same features and configuration as
[Collection Detail](/concepts/app-overview).
### Activity Detail
Unlike other item detail pages, activity items are **readonly** (for proper accountability) and open in a modal window
with the following fields:
- **User** — The Directus user that performed the action
- **Action** — The specific action taken, eg: Create, Update, Delete, Authenticate, etc
- **Date** — The timestamp of when the action was performed
- **IP Address** — The IP address of the device from which the action was performed
- **User Agent** — The description of the browser that was used to perform the action
- **Collection** — The collection affected by the action
- **Item** — The item (within the above Collection) affected by the action
## Settings
This module is only available to users within [admin roles](/concepts/users-roles-and-permissions#administrators-role).
This is where your project is configured, and the first place to go after installation. It includes the following
sections:
- [Project Settings](/concepts/platform-overview)
- [Data Model](/concepts/data-model)
- [Roles & Permissions](/concepts/users-roles-and-permissions)
- [Presets & Bookmarks](/concepts/presets-and-bookmarks)
- [Webhooks](/guides/webhooks)

165
docs/concepts/application.md Normal file
View File

@@ -0,0 +1,165 @@
# The Directus Application
> The Directus App is the presentation layer for your data, content, and assets. It uses a left-to-right visual hierarchy for organization and navigation. Below we cover the App's global elements and individual pages.
The Directus App is decoupled from, and powered by, the Directus API. It provides a way for both technical admins and non-technical users to view and manage content of the connected database. It is written in [Vue.js](https://vuejs.org), is completely modular, and is highly customizable.
## App Section Hierarchy
<img class="full shadow" src="../assets/app-overview.svg" />
### 1. Module Bar
- **Project Logo** — Displays your configured project logo and project color (defaults to the Directus logo and color).
If configured, clicking this component will navigate to the Project URL. During platform activity, an indeterminate
progress indicator will also be shown here.
- **Module Navigation** — Allows navigating between the different modules your user has access to. [Customizing the Module Navigation](/guides/roles-and-permissions/#customizing-the-module-navigation) is done within the Role's configuration, but the default module list includes:
- [Collections](#collections)
- [User Directory](#user-directory)
- [File Library](#file-library)
- [Documentation](#documentation)
- [Settings](#settings) (Admin Roles Only)
- [Any Custom Modules](/concepts/modules/) (Only if Configured)
- **Current User Menu** — This component displays the authenticated user's name and avatar.
- [Sign Out](#) — Hovering over the User Menu exposes the button to log out of the platform.
### 2. Navigation Bar
- **Project Name** — Shows an icon and tooltip indicating the API's connection strength, and the name of your current project, which can be configured under [Project Settings](/guides/projects/#adjusting-project-settings).
- **Navigation** — This is a dynamic navigation based on your current module. Some modules also support [Bookmark Presets](/guides/presets/#creating-a-preset), which are a customizable links to specific data-sets.
### 3. Page
- **Header** — A fixed section at the top of each page, the header includes:
- Page Icon — Clicking this navigates back to the previous page.
- Module Name — Clicking this navigates to the parent module/section.
- Page Title — Displays dynamic title of the current page.
- Action Buttons — Right-aligned contextual buttons for specific page actions.
- **Page Content** — This displays the content of the page you navigated to.
### 4. Page Sidebar
- **Page Components** — Lists any contextual page components available. The "Info" component is available on every page,
explaining the page's general purpose and relevant details. Clicking any sidebar component will accordion it open. If
the App window is large enough, the sidebar will automatically open, and can be closed by clicking the "X" in the
top-right.
- **Notifications Tray** — Fixed to the bottom of the page sidebar, this button opens a tray of recent user
notifications, and provides a link to the [Activity Log](#activity-log) page.
## Collections
This module is the primary way for interacting with your database content. Here you can access your collections, browse
their items, and navigate to individual item forms.
### Collection Listing
A page that lists the collections available to the current user. This is the landing page of the module, and effectively
the same as its navigation listing.
### Collection Detail
This is the main gateway to your content items, providing a highly configurable Layout for browsing and visualizing the items within a collection. The header of this page includes key action buttons for creating, deleting, and batch editing items.
- [Adjusting a Collection Layout](/guides/collections/#adjusting-a-collection-layout)
- [Creating an Item](/guides/items/#creating-an-item)
- [Updating an Item](/guides/items/#updating-an-item)
- [Deleting an Item](/guides/items/#deleting-an-item)
- [Archiving an Item](/guides/items/#archiving-an-item)
- [Reordering Items](/guides/items/#reordering-items)
- [Exporting Items](/guides/items/#exporting-items)
- [Browsing Items](/guides/items/#browsing-items)
- [Searching](/guides/items/#searching-items)
- [Filtering](/guides/items/#filtering-items)
- [Bookmarking](/guides/items/#bookmarking-item-presets)
### Item Detail
Most Collection Detail Layouts support navigating to individual item detail pages where you a presented with a
[customizable form](/guides/fields#adjusting-fields-layout) for viewing/editing the item's content. Like other detail
pages, there are many available features, including:
- [Adjusting Field Arrangement](/guides/fields/#adjusting-field-arrangement)
- [Updating an Item](/guides/items/#updating-an-item)
- [Archiving an Item](/guides/items/#archiving-an-item)
- [Reverting an Item](/guides/items/#reverting-an-item)
- [Deleting an Item](/guides/items/#deleting-an-item)
- [Commenting on an Item](/guides/items/#commenting-on-an-item)
## User Directory
This module includes a comprehensive listing of all system users within your project. This page has the same features and
configuration as [Collection Detail](#collection-detail).
### User Detail
Similar to other [Item Detail](#item-detail) pages, this page provides a custom form for viewing system users. This is also used for editing the "Profile Page" of the current user, which is accessible from the [User Menu](#_1-module-bar). There are a number of [User Fields](/concepts/users/#user-fields) included out-of-the-box that can then be extended by following the normal [Creating a Field](/guides/fields/#creating-a-field) guide.
- [Setting up your User Profile](/guides/users/#setting-up-your-user-profile)
- [Creating a User](/guides/users/#creating-a-user)
- [Inviting a User](/guides/users/#inviting-a-user)
- [Configuring a User](/guides/users/#configuring-a-user)
- [Archiving a User](/guides/users/#archiving-a-user)
- [Deleting a User](/guides/users/#deleting-a-user)
## File Library
This module aggregates all files within the project into one consolidated library. This page has the same features and
configuration as [Collection Detail](#collection-detail).
### File Detail
Similar to other [Item Detail](#item-detail) pages, this page provides a custom form for viewing assets and embeds. There are a number of [File Fields](/concepts/files/#file-fields) included out-of-the-box that can then be extended by following the normal [Creating a Field](/guides/fields/#creating-a-field) guide.
- [Uploading a File](/guides/files/#uploading-a-file)
- [Accessing an Original File](/guides/files/#accessing-an-original-file)
- [Creating a Thumbnail Preset](/guides/files/#creating-a-thumbnail-preset)
- [Requesting a Thumbnail](/guides/files/#requesting-a-thumbnail)
## Documentation
This module is an internal set of guides, concepts, and reference docs for your project's specific version of Directus.
It also includes a dynamic [API Reference](/reference/api/introduction) that is dynamically tailored to your custom
schema. The docs are organized into these distinct sections:
- [Getting Started](/getting-started/introduction/) — Novice oriented, for a platform intro and installation.
- [Concepts](/concepts/activity) — Learning oriented, for understanding the platform.
- [Guides](/guides/api-config) — Problem oriented, follow along with steps while working.
- [Reference](/reference/command-line-interface) — Information oriented, look up info and specs while working.
- [API Reference](/reference/api/introduction/) — Information oriented, look up API resources while working.
- [Contributing](/contributing/introduction/) — Contributor oriented — resources for working on Open-Source Core.
::: tip Updating the Docs
Our docs are written in markdown (with some additional VuePress styling like this hint box), and available for
editing/fixing via [GitHub](https://github.com/directus/directus).
:::
::: tip Public Docs
The latest version of the Directus Docs are also available publicly. This online version includes additional sections, such as how to install the platform. [https://docs.directus.io](https://docs.directus.io)
:::
## Activity Log
This module provides a collective timeline of all actions taken within the project. This is a great way to audit user
activity or enforce accountability. This is the only system module that is not in the module bar by default — instead
being located within the notifications tray of the page sidebar. This page has the same features and configuration as
[Collection Detail](#collection-detail).
### Activity Detail
Unlike other item detail pages, activity items are **readonly** (for proper accountability) and open in a side drawer to display the [Activity Fields](/concepts/activity/#activity-fields).
## Settings
This module is only available to users within [Admin roles](/concepts/roles/#administrators-role).
This is where your project is configured, and the first place to go after installation. It includes the following
sections:
- [Project Settings](/guides/projects/#adjusting-project-settings)
- [Data Model](/concepts/databases/#database-mirroring)
- [Roles & Permissions](/concepts/roles)
- [Presets & Bookmarks](/concepts/collections/#collection-presets-bookmarks)
- [Webhooks](/guides/webhooks)

39
docs/concepts/collections.md Normal file
View File

@@ -0,0 +1,39 @@
# Collections
> Each Collection contains some number of fields, and is a container for a specific grouping of Items. Each collection represents a **table** in your database.
Directus automatically uses a built-in title formatter to display your database table names prettified, however you can use [schema translations](/concepts/translations/#schema-translations) to completely rename them if needed.
Collections can be organized in any way that is appropriate for your project. You can architect them platform-specific
(eg: _pages_ of a website), or in a more platform-agnostic way (eg: raw _customers_ of your business). While there's no
right or wrong way to structure your data-model, we recommend keeping your data as agnostic as possible so it is easier
to repurpose in the future. **In short, learn to see your data as its own asset — not only through the lens of your
immediate project needs**.
The only requirement of a collection is that it must contain a **Primary Key** field. This field stores a unique value that is used to reference the Collection's items throughout the database/platform.
#### Relevant Guides
- [Creating a Collection](/guides/collections/#creating-a-collection)
- [Configuring a Collection](/guides/collections/#configuring-a-collection)
- [Deleting a Collection](/guides/collections/#deleting-a-collection)
- [Adjusting a Collection Layout](/guides/collections/#adjusting-a-collection-layout)
## Collection Presets & Bookmarks
Presets store the exact state of a [collection detail](/concepts/application/#collection-detail) page. They are used to set layout defaults for a user, or to define bookmarks that can be used to quickly recall specific datasets. Each preset stores the following information:
- **Collection** — The collection of the preset
- **Layout** — The Layout the preset applies to
- **Layout Query** — Order direction, order field, pagination, etc
- **Layout Options** — The configuration of all layout options
- **Search** — Any fulltext search query applied
- **Filters** — Any advanced fitlers applied
- **User** — Optional; scopes to a specific user
- **Role** — Optional; scopes to a specific role
- **Bookmark Name** — Optional; determines if the preset is a bookmark
#### Relevant Guides
- [Creating a Preset](/guides/presets/#creating-a-preset)
- [Deleting a Preset](/guides/presets/#deleting-a-preset)

3
docs/concepts/data-model.md
View File

@@ -1,3 +0,0 @@
# Data Model
@TODO

30
docs/concepts/databases.md Normal file
View File

@@ -0,0 +1,30 @@
# Databases
> The Directus platform is primarily comprised of an API and App, working in concert to “mirror” the schema and content of your SQL database.
## Database Mirroring
**Instead of using a predefined “one-size-fits-all” data model to store your content, Directus “mirrors” your actual SQL database in real-time.** The principle is akin to a database client (like _phpMyAdmin_), but includes far more advanced tools, and is safe and intuitive enough for non-technical users. This approach has many unique advantages:
- A custom (pure) SQL database schema, tailored to your exact requirements
- Significant performance improvements through optimizations and indexing
- Complete transparency, portability, and security for your data
- Direct database access and the full power of raw/complex SQL queries
- Allows importing existing databases, unaltered and without any migrations
## Dynamic API
The Directus API uses _Database Mirroring_ to dynamically generate REST endpoints and a GraphQL schema based on the
connected database's architecture. It is written in [Node.js](https://nodejs.dev) and uses database abstraction to
support most [SQL database vendors](/guides/installation/cli/#_1-confirm-minimum-requirements).
#### Relevant Docs
- [API Reference](/reference/api/introduction/)
- [API Extensions](/concepts/extensions/#api-extensions)
## Database Abstraction
Directus supports mirroring all the most SQL databases. There are many different SQL database vendors, including popular choices such as MySQL, PostgreSQL, and SQLite. Each vendor has subtle (and sometimes not so subtle) differences in how they function, so Directus includes an abstraction layer that helps it avoid writing different code for each different type.
This means there is the possiblility of supporting other datastores in the future, such as NoSQL options like MongoDB, or even third-party data services like Firebase or Heroku. However these options are _fundamentally_ different from the relational SQL databases we currently support, and so more research is needed.

22
docs/concepts/displays.md Normal file
View File

@@ -0,0 +1,22 @@
# Displays <small></small>
> Displays are the smaller, read-only counterpart to Interfaces, defining how a field's data will be displayed inline throughout the App.
For example, you may have a "Status" field that uses a _Dropdown_ Interface on the Item Detail page, and a smaller _Badge_ Display when the field is referenced throughout the rest of the App. Directus includes many Displays out-of-the-box, below are the some key examples:
- **Raw** — The exact value, straight from the API
- **Formatted Value** — Provides options for string formatting
- **Boolean** — Customizable True/False icons
- **Color** — A color swatch preview
- **DateTime** — Formatted or relative datetimes
- **Image** — Thumbnail previews
- **Labels** — Small, custom colored badges
- **Rating** — Customizable stars
- **Related Values** — Displays relational display titles
- **User** — Avatar and name of a system user
In addition to the included core displays, custom displays allow for creating new and/or proprietary ways to view or represent field data. For example, you could create progress indicators, tooltips for relational data, specific formatting styles, or anything else.
### Relevant Guides
- [Creating a Custom Display](/guides/displays)

17
docs/concepts/extensions.md Normal file
View File

@@ -0,0 +1,17 @@
# Extensions <small></small>
> In addition to being highly customizable, Directus has also been built with many modular extension points throughout the App and API.
## App Extensions
Directus has been architected as completely modular and extensible, with four keystone App component types. Out-of-the-box components are configurable, or altogether new components can be created as extensions.
- [Modules](/concepts/modules/)
- [Layouts](/concepts/layouts/)
- [Interfaces](/concepts/interfaces/)
- [Displays](/concepts/displays/)
## API Extensions
- [Endpoints](/guides/api-endpoints)
- [Hooks](/guides/api-hooks)

33
docs/concepts/fields.md Normal file
View File

@@ -0,0 +1,33 @@
# Fields
> Fields are a specific type of value within a Collection, storing the data of your item's content. Each field represents a **column** in your database.
For example, an `articles` collection might have `title`, `body`, `author`, and `date_published` fields. Directus automatically uses a built-in title formatter to display your database column names prettified, and you can use [schema translations](/concepts/translations/#schema-translations) to completely rename them if needed.
Fields also mirror other characteristics from their associated column, including its `type`, `default`, `length`, `allow_null`, etc.
::: tip Relational Fields
Fields that reference other items (in the same collection or different) are called [relational fields](/concepts/relationships/). Linking or
connecting data relationally is an immensely powerful feature of relational databases and SQL queries.
:::
::: tip Aliases
Not all fields in Directus map directly to an actual database column within their table — these are called "alias" fields. For example, certain relational fields, like [One-to-Many (O2M)](/concepts/relationships/#one-to-many-o2m) and [Many-to-Many (M2M)](/concepts/relationships/#many-to-many-m2m), represent data that is stored in _other_ tables. Then there are [Presentation Fields](/guides/field-types/presentation-field/) that don't save data at all, such as dividers and action buttons.
:::
#### Relevant Guides
- [Creating a Standard Field](/guides/field-types/standard-field)
- [Creating a Presentation Field](/guides/field-types/presentation-field)
- [Creating a Many-to-One Field](/guides/field-types/many-to-one-field)
- [Creating a One-to-Many Field](/guides/field-types/one-to-many-field)
- [Creating a Many-to-Many Field](/guides/field-types/many-to-many-field)
- [Creating a Many-to-Any Field](/guides/field-types/many-to-any-field)
- [Creating Translated Fields](/guides/field-types/translated-fields)
- [Duplicating Fields](/guides/fields/#duplicating-a-field)
- [Adjusting Field Layout](/guides/fields/#adjusting-field-layout)
- [Deleting Fields](/guides/fields/#deleting-a-field)

43
docs/concepts/files-and-thumbnails.md
View File

@@ -1,43 +0,0 @@
# Files & Thumbnails
> Directus offers a full Digital Asset Management (DAM) system. This includes multiple storage adapters, nested folder
> organization, private file access, image editing, and on-demand thumbnail generation.
## Storage Adapters
Storage adapters allow project files to be stored in different locations or services. By default, Directus includes the
following adapters:
- **Local Filesystem** — The default, any filesystem location or network-attached storage
- **S3 or Equivalent** — Including AWS S3, DigitalOcean Spaces, Alibaba OSS, and others
- **Google Cloud Storage** — A RESTful web service on the Google Cloud Platform
## Files
Directus allows you to manage all your files in one place, including documents, images, videos, and more. Files can be
uploaded to the [File Library](/concepts/app-overview#file-library) in general, or directly to an item via a
[Single File](/guides/field-types/single-file) or [Multiple Files](/guides/field-types/multiple-files) field.
### Relevant Guides
- [Uploading a File](/guides/files#uploading-a-file)
- [Requesting an Original File](/guides/files#accessing-an-original-file)
## Embedded Assets
Directus also supports ingesting third-party embedded assets, such as YouTube or Vimeo videos. These are managed the
same as normal files, however the resource itself is stored on the external service, and referenced via its proprietary
UID.
## Crop & Transform Images
Our file middleware also allows for cropping and transforming image assets on the fly. This means you can simply request
an image, include any desired transformation parameters, and you'll be served the new asset as a response. This is very
useful for automatically generating many different thumbnails/versions of an original file.
To impede malicious users from consuming your storage by requesting a multitude of random sizes, Directus includes a
[Asset Allow-List](/guides/files#creating-thumbnail-presets) to limit what transformations are possible.
### Relevant Guides
- [Requesting a Thumbnail](/guides/files#requesting-a-thumbnail)

64
docs/concepts/files.md Normal file
View File

@@ -0,0 +1,64 @@
# Files
> Directus offers a full Digital Asset Management (DAM) system. This includes multiple storage adapters, nested folder organization, private file access, image editing, and on-demand thumbnail generation.
Directus allows you to manage all your files in one place, including documents, images, videos, and more. Files can be
uploaded to the [File Library](/concepts/application/#file-library) in general, or directly to an item via a
[Single File](/guides/field-types/single-file) or [Multiple Files](/guides/field-types/multiple-files) field.
#### Relevant Guides
- [Uploading a File](/guides/files/#uploading-a-file)
- [Accessing an Original File](/guides/files/#accessing-an-original-file)
- [Creating a Thumbnail Preset](/guides/files/#creating-a-thumbnail-preset)
- [Requesting a Thumbnail](/guides/files/#requesting-a-thumbnail)
## File Fields
Directus ships with a full-featured system for digital asset management, with the following fields:
- **Title** — Pulled from the file metadata if available, falls back to a formatted version of the filename
- **Description** — Pulled from the file metadata if available
- **Tags** — Pulled from the file metadata if available
- **Location** — Pulled from the file metadata if available
- **Storage** — The storage adapter where the asset is saved (readonly)
- **Filename Disk** — The actual name of the file within the storage adapter
- **Filename Download** — The name used when downloading the file via _Content-Disposition_
The sidebar's info component also includes the following readonly details:
- **Type** — The MIME type of the file, displayed in the App as a formatted media type
- **Dimensions** — (Images Only) The width and height of the image in pixels
- **Size** — The file-size the asset takes up within the storage adapter
- **Created** — The timestamp of when the file was uploaded to the project
- **Owner** — The Directus user that uploaded the file to the project
- **Folder** — The current parent folder that contains the file
- **Metadata** — Metadata JSON dump of the file's EXIF, IPTC, and ICC information
## Storage Adapters
Storage adapters allow project files to be stored in different locations or services. By default, Directus includes the
following adapters:
- **Local Filesystem** — The default, any filesystem location or network-attached storage
- **S3 or Equivalent** — Including AWS S3, DigitalOcean Spaces, Alibaba OSS, and others
- **Google Cloud Storage** — A RESTful web service on the Google Cloud Platform
## Embedded Assets
Directus also supports ingesting third-party embedded assets, such as YouTube or Vimeo videos. These are managed the
same as normal files, however the resource itself is stored on the external service, and referenced via its proprietary
UID.
## Thumbnail Transformations
Our file middleware also allows for cropping and transforming image assets on the fly. This means you can simply request
an image, include any desired transformation parameters, and you'll be served the new asset as a response. This is very
useful for automatically generating many different thumbnails/versions of an original file.
To impede malicious users from consuming your storage by requesting a multitude of random sizes, Directus includes a
[Asset Allow-List](/guides/files/#creating-thumbnail-presets) to limit what transformations are possible.
#### Relevant Guides
- [Requesting a Thumbnail](/guides/files/#requesting-a-thumbnail)

41
docs/concepts/interfaces.md Normal file
View File

@@ -0,0 +1,41 @@
# Interfaces <small></small>
> Interfaces determine how you view or interact with a field. In most cases, they offer some sort of input tailored to managing data of a specific type, but can also be used exclusively for presentation.
Interfaces provide different ways to view or interact with field data on the [Item Detail](/concepts/application/#item-detail) page's form. Every interface supports a specific subset of field [types](/concepts/types/) (eg: String), which determines how the data will be stored. For example, the _Text Input_ interface can manage most types of data, but might not be ideal for dates, where a _Calendar_ interface excels.
Directus includes many Interfaces out-of-the-box, below are the some key examples:
- **Checkboxes**
- **Code**
- **Color**
- **DateTime**
- **Divider**
- **Dropdown**
- **File**
- **Image**
- **Many-to-Many**
- **Many-to-One**
- **Markdown**
- **Notice**
- **Numeric**
- **One-to-Many**
- **Radio Buttons**
- **Repeater**
- **Slider**
- **Tags**
- **Text Input**
- **Textarea**
- **Toggle**
- **Translations**
- **WYSIWYG**
## Custom Interface Extensions
In addition to these core interfaces, custom interfaces allow for creating more tailored or proprietary ways to view or
manage field data, such as bespoke layout builders, skeuomorphic knobs, or relational views for third-party data (eg:
Stripe Credit Card UI).
#### Relevant Guides
- [Creating a Custom Interface](/guides/interfaces)

37
docs/concepts/internationalization.md
View File

@@ -1,37 +0,0 @@
# Internationalization
> Directus is maintained by people all over the world. Not only does Directus allow you to author and manage
> multilingual content, the App itself also supports multiple languages and locales.
## App Translations
Directus supports internationalization across its entire Admin App. Many languages are currently supported, with more
are being added all the time. Help the community by adding or refining your language through our
[CrowdIn](https://locales.directus.io/) integration.
## Schema Translations
Directus uses [database mirroring](/concepts/platform-overview#database-mirroring) to dynamically pull in your schema's
tables and columns, however this only covers one language. Therefore our platform supports schema translations for these
names, allowing you to properly support different languages for your Collection and Field names.
::: tip Overriding Technical
Names If your project requires more _technical_ table/column names (eg: `cust` or `f_name`), you can also use schema
translations to override those defaults (eg: `Customers` or `First Name`) in the primary language.
:::
## Content Translations
One of the most important features in Directus is the ability to author and manage multilingual content. While you can
accomplish this by creating _standard_ fields in the parent collection for each language, it is more extensible to use
our relational translation fields to dynamically manage content in as many languages as is required. Mixing standard and
translated fields also allows language-agnostic data (such as dates or toggles) to remain within the parent collection.
::: tip Custom Interfaces
For more advanced use-cases, such as connecting to a third-party translation service, you can read our extension guide
on [creating a custom interface](/guides/extensions/interfaces).
:::

14
docs/concepts/items.md Normal file
View File

@@ -0,0 +1,14 @@
# Items
> An Item is an object within a Collection that contains the values for one or more fields. Each collection represents a **record** in your database.
Items are the primary building blocks of your project content. Similar to a "row" within a spreadsheet, all data within Directus is accessed via these "atomic" data units. Items in and of themselves are fairly straightforward, however their real power comes from the complexity that begins to form when items are relationally connected to each other.
Items are referenced (both individually and relationally) by their unique "key", which is the value saved within their primary key field. This can techncially be anything, but is typically an auto-incrementing integer or a more complex UUID.
#### Relevant Guides
- [Creating an Item](/guides/items/#creating-an-item)
- [Archiving an Item](/guides/items/#archiving-an-item)
- [Reordering Items](/guides/items/#reordering-items)
- [Deleting an Item](/guides/items/#deleting-an-item)

48
docs/concepts/layouts.md Normal file
View File

@@ -0,0 +1,48 @@
# Layouts <small></small>
> Layouts determine how you view or interact with a Collection's Items. In most cases, they offer a way to browse items based on a specific type of data, but can also be used to interact with data.
Layouts provide different ways for presenting, browsing, visualizing, or even managing sets of data. Most commonly shown on Collection Detail pages and contextual drawers for item selection. Directus includes several Layout options out-of-the-box, each with different features and configuration options.
## Table Layout
This tabular layout supports all forms of data, and is therefore the default within the Collections module. It includes
the following features/options:
- Toggle & Reorder Field Columns (Option)
- Row Spacing (Option)
- Manual Ordering
- Column Sort
- Column Resizing
- Select All
## Cards Layout
This tiled layout is ideal for collections that prioritize an image. It is the default for both the
[User Directory](/guides/users/) (shows the avatar) and [File Library](/guides/files/) (shows asset thumbnail). It
includes the following features/options:
- Image Source (Option)
- Title (Option)
- Subtitle (Option)
- Image Fit (Option)
- Fallback Icon (Option)
- Card Size
- Sort Field & Direction
- Select All
<!-- ## Calendar
This temporal layout is ideal for collections that prioritize a date and/or time. It is the default for the [Activity Page](/concepts/activity-and-versions). It includes the following features/options:
* @TODO
-->
## Custom Layout Extensions
In addition to these core layouts, custom layouts allow for creating more tailored or proprietary ways to experience data within the App, such as charts, seating charts, or Maps.
#### Relevant Guides
- [Creating a Custom Layout](/guides/layouts)

19
docs/concepts/modules.md Normal file
View File

@@ -0,0 +1,19 @@
# Modules <small></small>
> Modules are the highest and broadest level of organization within the App. There are several modules included out-of-the-box, however you can also add your own.
The [Module Bar](/concepts/application/#_1-module-bar) lists all available Modules and allows you to switch between them. Each module also controls its own [Navigation Bar](/concepts/application/#_2-navigation-bar), so they can provide tailored access to their sub-pages. All core functionality within the App can be bucketed into one of the following core modules:
- [Collections](/concepts/application/#collections-module) — The primary way to view and interact with database content
- [User Directory](/concepts/application/#user-directory) — A dedicated section for the platform's system Users
- [File Library](/concepts/application/#file-library) — An aggregate of all files uploaded and managed within the platform
- [Documentation](/concepts/application/#documentation) — A tailored, in-app portal for the platform's concepts, guides, and reference
- [Settings](/concepts/application/#settings) — An Admin-Only section for configuring the project and system settings
## Custom Module Extensions
In addition to these core modules, custom modules offer a _blank canvas_ for creating altogether new/different experiences within the App, such as proprietary dashboards, compound datasets, or third-party integrations (eg: a Stripe Payments Console).
#### Relevant Guides
- [Creating a Custom Module](/guides/modules)

31
docs/concepts/permissions.md Normal file
View File

@@ -0,0 +1,31 @@
# Permissions
> Permissions are attached directly to a Role, and define what data that Role's Users can create, read, update, and delete within the platform.
Directus includes an extremely granular, filter-based permissions system for controlling access. There are several layers to this access control, including:
- **Collection** — The Collection scope of this permission
- **Action** — Create, Read, Update, or Delete
- **Item Permissions** — Filters actionable Items using [Filter Rules](/reference/filter-rules/)
- **Field Permissions** — Toggles which fields can be accessed
- **Validation** — Filters Item values using [Filter Rules](/reference/filter-rules/)
- **Presets** — Controls the default values for the action
- **Limit** — Sets a maximum number of items that are actionable
There are also other access control features that are tied directly to the Role. These include:
- **IP Access** — Restricts user access based on IP Address
- **App Access** — Restricts user access to the App
- **Admin Access** — Enables Settings and unrestricted user access
### Example
You could set the permissions such that a user can only **Update** (Action) the **Title, Body, Date Published, and Category** (Field Permissions) within **Articles** (Collection) that **they created and are still unpublished** (Item Permissions) **one item at a time** (Limit) if they are **currently at the NYC office** (IP Access). Additionally, the **default Category will be "Opinon"** (Preset), and the **Date Published must be in the future** (Validation).
And this is actually just a _simple_ example. Permissions and Validation support a comprehensive list of [Filter Operators](/reference/filter-rules/#filter-operators), [Relational Filtering](/reference/filter-rules/#filter-relational), [Logical Operators](/reference/filter-rules/#logical-operators), and [Dynamic Variables](/reference/filter-rules/#dynamic-variables).
#### Relevant Guides
- [Configuring Role Permissions](/guides/permissions/#configuring-role-permissions)
- [Configuring System Permissions](/guides/permissions/#configuring-system-permissions)

160
docs/concepts/platform-overview.md
View File

@@ -1,160 +0,0 @@
# Platform Overview
> The Directus platform is primarily comprised of an API and App, working in concert to "mirror" the schema and content
> of your SQL database.
## Database Mirroring
Instead of using a predefined "one-size-fits-all" data model to store your content, Directus "mirrors" your actual SQL
database in real-time. The principle is akin to a database client (eg: _phpMyAdmin_), but includes far more advanced
tools, and is safe and intuitive enough for non-technical users. This approach has many unique advantages:
- A custom SQL database schema, tailored to your exact requirements
- Significant performance improvements through optimizations and indexing
- Complete transparency, portability, and security for your data
- Direct database access and the full power of raw/complex SQL queries
- Allows importing existing databases, unaltered and without any migrations
## Directus API
The Directus API uses _Database Mirroring_ to dynamically generate REST endpoints and a GraphQL schema based on the
connected database's architecture. It is written in [Node.js](https://nodejs.org) and uses database abstraction to
support most [SQL database vendors](/guides/installation#databases).
### Relevant Docs
- [API Reference](/reference/api/introduction)
- [API Custom Endpoints](/concepts/api-extensions)
## Directus App
The Directus App is decoupled from, and powered by, the Directus API. It provides a way for both technical admins and
non-technical users to view and manage content of the connected database. It is written in [Vue.js](https://vuejs.org)
v3, is completely modular, and is highly customizable.
### Relevant Docs
- [App Overview](/concepts/app-overview)
- [App Extensions](/concepts/app-extensions)
## Projects & Environments
A Project is a complete instance of Directus. Each project primarily represents a database, but also includes a
configuration file and any related asset storage. This modular approach means you can also create different environments
(eg: Dev, Staging, Prod) by simply creating additional project instances.
<!-- ::: tip Migrating Environments
Directus includes [Export](#), [Import](#), [Backup](#), and [Restore](#) features to assist with custom migration workflows between environments.
You can also roll your own process by copying the database and assets between environments, either manually or via an automated script.
@TODO Reference Schema Revisions
::: -->
## Collections
A Collection is a grouping of similar Items. Each collection represents a table in your database. Directus automatically
uses a built-in [title formatter](/concepts/app-extensions) to display your database table names prettified, and you can
use [translations](/concepts/data-model) to completely rename them if needed.
::: tip Usage
Collections can be organized in any way that is appropriate for your project. You can architect them platform-specific
(eg: _pages_ of a website), or in a more platform-agnostic way (eg: raw _customers_ of your business). While there's no
right or wrong way to structure your data-model, we recommend keeping your data as agnostic as possible so it is easier
to repurpose in the future. In short, **learn to see your data as its own asset — not only through the lens of your
immediate project needs**.
:::
### Relevant Guides
- [Creating a Collection](/guides/collections#creating-a-collection)
- [Deleting a Collection](/guides/collections#deleting-a-collection)
## Presets
Presets store the exact state of a [collection detail](/concepts/app-overview) page. These are used to set layout
defaults for a user, or to define bookmarks that can be used to quickly recall specific datasets.
### Relevant Guides
- [Creating a Preset](/guides/presets#creating-a-preset)
- [Deleting a Preset](/guides/presets#deleting-a-preset)
## Fields
A Field is a specific type of value within a Collection. Each field represents a database column. Directus automatically
uses a built-in [title formatter](/concepts/app-extensions#title-formatter) to display your database column names
prettified, and you can use [translations](/guides/fields) to completely rename them if needed.
Each field also mirrors other characteristics from the column, including its `type`, `default`, `length`, `allow_null`,
etc.
::: tip Usage
You might have `title`, `body`, `author`, and `date_published` fields within an `articles` collection.
:::
::: tip Aliases
Not all fields in Directus map directly to an actual database column within their table. Some relational fields, like
One-to-Many (O2M) and Many-to-Many (M2M), represent data that is stored in different tables. Other fields are only for
presentation and don't save data at all, such as a divider. These are called "alias" fields.
:::
::: tip Relational Fields
Fields that reference other items (in the same collection or different) are called relational fields. Linking or
connecting data relationally is an immensely powerful feature of relational databases and SQL queries.
:::
### Relevant Guides
- [Creating a Standard Field](/guides/field-types/standard-field)
- [Creating a Presentation Field](/guides/field-types/presentation-field)
- [Creating a Many-to-One Field](/guides/field-types/many-to-one-field)
- [Creating a One-to-Many Field](/guides/field-types/one-to-many-field)
- [Creating a Many-to-Many Field](/guides/field-types/many-to-many-field)
- [Creating a Many-to-Any Field](/guides/field-types/many-to-any-field)
- [Creating Translated Fields](/guides/field-types/translated-fields)
- [Duplicating Fields](/guides/fields#duplicating-a-field)
- [Adjusting Field Layout](/guides/fields#adjusting-field-layout)
- [Deleting Fields](/guides/fields#deleting-a-field)
## Types
Directus has built-in database abstraction for managing all SQL database vendors. However, each of those vendors has a
different list of supported column datatypes. To standardize all of these differences, Directus has a single superset of
types that each map to the more specific vendor ones.
- String
- Text
- Boolean
- Integer
- Big Integer
- Float
- Decimal
- Timestamp
- DateTime
- Date
- Time
- JSON
- CSV
- UUID
@TODO confirm
## Items
An Item is an object containing the field values within a Collection. Each item represents a database record. Similar to
a "row" within a spreadsheet.
### Relevant Guides
- [Creating an Item](/guides/items#creating-an-item)
- [Archiving an Item](/guides/items#archiving-an-item)
- [Reordering Items](/guides/items#reordering-items)
- [Deleting an Item](/guides/items#deleting-an-item)

30
docs/concepts/projects.md Normal file
View File

@@ -0,0 +1,30 @@
# Projects
> A Project is a complete instance of Directus. Each project represents a **Database**, but also encapsulates a config file, asset storage, and any custom extensions.
Projects are the highest level of structure in Directus. While there are many customizable facets to a Project, you can essentially think of them as individual [Databases](concepts/databases/).
#### Relevant Guides
- [Creating a Project](/guides/projects/#creating-a-project)
- [Configuring a Project](/guides/projects/#configuring-a-project)
- [Adjusting Project Settings](/guides/projects/#adjusting-project-settings)
- [Upgrading a Project](/guides/projects/#upgrading-a-project)
- [Backing-up a Project](/guides/projects/#backing-up-a-project)
- [Migrating a Project](/guides/projects/#migrating-a-project)
- [Deleting a Project](/guides/projects/#configuring-a-project)
## Environments
This compartmentalized approach means you can also create different Environments (eg: Dev, Staging, Prod) simply by creating additional Project instances. In short, there is no difference between a Project and an Environment.
#### Relevant Guides
- [Migrating a Project](/guides/projects/#migrating-a-project)
## Multitenancy
Previous versions of Directus allowed managing multiple databases within a single installation. However this because overly complex in the scoping of routes, API endpoints, and custom code. In Directus 9+, to create multitenancy you have several options:
- **Project Scoping** — Creating a super-admin layer that provisions new tenant projects has been made easier by the Cloud-native model of Directus 9+. This method involves developing custom code that can dynamically spin up/down projects, but is also the most flexible, supporting scoped extensions and differentiated project settings.
- **Role Scoping** — In this method, you create one Role per tenant, and configure their permissions to properly scope them within a single project. This direction allows for tenants to share a single schema using _item_ scoped permissions, or different schemas by using _collection_ scoped permissions.

50
docs/concepts/relationships.md
View File

@@ -3,17 +3,15 @@
> As you might have guessed, relationships are a crucial part of any relational database. Directus supports all standard
> relationship types, as well as a few more _compound_ types that offer greater flexibility.
## Understanding Relationships
While it may seem complex at first, relational data is actually quite straightforward once you understand what's
happening behind the confusing terminology. Before diving into the details of each type, let's first cover a few basics
that will help you better visualize each in your mind's eye.
### PKs vs FKs
### Primary and Foreign Keys
Every [item](/concepts/platform-overview#items) in a relational database has a unique "key" that identifies it within
its [collection](/concepts/platform-overview#collections). Because it's required, the key is the first
[field](/concepts/platform-overview#fields) created within a collection, typically storing an "auto-increment" number,
Every [Item](/concepts/items/) in a relational database has a unique "key" that identifies it within
its [Collection](/concepts/collections/). Because it's required, the key is the first
[field](/concepts/fields/) created within a collection, typically storing an "auto-increment" number,
an automatically generated unique hash, or a manually entered value. They are often abbreviated to "PK" (Primary Key),
"ID" (Identifier), "UID" (Unique Identifier), or "UUID" (Universally Unique Identifier), depending on the type of value
they store. After it's created, the value of an item's PK should _never_ change.
@@ -23,7 +21,7 @@ is called a Foreign Key (FK).
::: tip Compound Keys
We've ignored compound keys in this explanation to help keep things as simple as possible.
To keep things simple, we've ignored compound keys in the above explanation.
:::
@@ -67,18 +65,18 @@ cities ("Many" Collection)
- country (stores the FK to a country)
```
::: tip
::: tip Manual Reordering
Manual Reordering To enable manual reordering for a O2M, simply add a field with the `sort` type to the "many" side
To enable manual reordering for a O2M, simply add a field with the `sort` type to the "many" side
(`cities` in the above example).
:::
::: tip Translations
The Translations interface allows [creating multilingual content](/concepts/internationalization#content-translations)
relationally. It is a standard O2M relationship, but also includes an additional field on the "many" collection to hold
the language key
The Translations interface allows [creating multilingual content](/concepts/translations/#content-translations)
relationally. It is a standard O2M relationship with an additional field on the "many" collection to hold
the language key.
:::
@@ -109,34 +107,34 @@ recipe_ingredients (Junction Collection)
Notice that the example above also has a `quantity` field on the junction table. You can add any contextual fields to
the junction, and they will also be included in the App's relational edit form.
::: warning M2M == O2Mx2
::: tip Actually just two O2Ms
An M2M is technically two relationships viewed as one. Each side has a O2M to the Junction Table that sits in the
middle. In that sense, there really is no "M2M".
:::
::: tip
::: tip Manual Reordering
Manual Reordering To enable manual reordering for a M2M, simply add a numeric field to the junction table and set it as
the [Collection Sort](/guides/collections#sort).
To enable manual reordering for a M2M, simply add a numeric field to the junction table and set it as
the [Collection Sort](/guides/collections/#sort).
:::
::: tip
::: tip Self-Referencing
Self-Referencing You can also have a M2M relationship that connects items within the _same_ collection. A common example
of this is "Related Articles", where each article might relate to many other articles.
You can also have a M2M relationship that connects items within the _same_ collection. As example
of this is "Related Articles", where an article might relate to many other articles.
:::
## One-to-One (O2O)
Directus does not include a one-to-one (O2O) relationship type or interface. However, O2O is essentially the same as a
Directus does not include a dedicated one-to-one (O2O) relationship type or interface. However, O2O is essentially the same as a
M2O (storing a foreign key). The only difference is that a O2O enforces the cardinality. In other words, selecting a
relational item in a O2O means that item can not be selected elsewhere (it can only be used once). This functionality
can be added by checking and constraining uniqueness via a [custom event hook](/concepts/api-extensions) or
[custom interface](/concepts/app-extensions).
can be added by checking and constraining uniqueness via a [custom event hook](/guides/api-hooks) or
[custom interface](/guides/interfaces).
An example of a O2O is: a _person_ only has one unique set of _fingerprints_, and those _fingerprints_ only belong to
one _person_.
@@ -148,12 +146,9 @@ but with one crucial difference: the junction table also stores the _parent coll
key" combines the collection name and FK to provide a unique reference to _any_ other item within the project. You can
then artificially limit which collections are valid through an "allow list".
An example of a M2A is a "page layout builder". These typically will have modular components across several different
collections (eg: "Heading", "Text Block", "Media Asset", etc), and a _Pages_ collections where you can piece them
together. Therefore, the junction table will link a specific page with specific components, allowing the creation of
relational page layouts.
An example of a M2A is a "Page Builder", which typically have different component Collections such as "Heading", "Text Block", or "Media Asset", and a _Pages_ collection on which you can add and arrange them. In this example the junction table will link a specific page with components from a number of different collections, allowing for the creation of relational page layouts.
---
<!--
@TODO
@@ -171,3 +166,4 @@ relational page layouts.
[ ] a2m [o2a-m2o]
[ ] a2a [o2a-a2o] (dynamic builder)
```
-->

32
docs/concepts/revisions.md Normal file
View File

@@ -0,0 +1,32 @@
# Revisions
> Revisions are created when an _original_ Item is updated. These alternate versions are tracked so that previous states can be recovered, or potential edits can be staged.
Every change made to items in Directus is stored as a complete versioned snapshot. The Revisions system is tightly coupled to the Activity Logs system, with each revision being linked to
the specific [Activity](/concepts/application/#activity-log) event which created it.
## Revision Fields
- **Data** — A full snapshot of the item _after_ the event
- **Delta** — The specific field data changed by this event
- **Parent** — If this revision was created via a nested relationship
<!-- @TODO ::: tip Customizing Version Data
Since versions store a full data snapshot and delta, the
`directus_revisions` collection can quickly grow quite large, increasing database size and
potentially decreasing performance. To remedy this, Directus allows
[configuring version scope](/concepts/app-overview) per collection to set the exact field data
saved.
:::
::: tip Creating Detached Versions
You can also create a new version for an item without saving the data to the parent item itself. This allows you to "stage" changes to an item that may already be live/published.
:::
-->
#### Relevant Guides
- [Reverting an Item](/guides/items/#reverting-an-item)

30
docs/concepts/roles.md Normal file
View File

@@ -0,0 +1,30 @@
# Roles
> Roles define a specific set of access permissions, and are the primary organizational structure for Users within the platform.
Each User is assigned a single Role which determines their [Permissions](/concepts/permissions/) within the App and API. Roles also include options for configuring platform access, Two-Factor Auth, Module Navigation, and Collection Navigation. You can create an unlimited number of roles, so organize your users in whatever way feels most appropriate.
Two default roles, _Public_ and _Administrators_, are available after installing a clean copy of Directus.
#### Relevant Guides
- [Creating a Role](/guides/roles/#creating-a-role)
- [Configuring a Role](/guides/roles/#configuring-a-role)
- [Configuring Role Permissions](/guides/permissions/#configuring-role-permissions)
- [Configuring System Permissions](/guides/permissions/#configuring-system-permissions)
- [Deleting a Role](/guides/roles/#deleting-a-role)
### Public Role
Not technically a role, "Public" can't be found in the `directus_roles` table. Instead, it represents the _lack_ of a role, providing a place to configure permissions for _unauthenticated_ users. This role can not be deleted.
::: warning Private by Default
All of the data within Directus is private by default. Permissions within the public role can be added by administrators on a case-by-case basis.
:::
### Administrators Role
During the installation process, Directus automatically creates an "Administrators" Role, which is used to provide the initial admin user with full platform access. However this is just a _normal_ role, and so it can still be updated, renamed, or even deleted. Keep in mind that your project must maintain at least one
role with Admin Access at all times.

33
docs/concepts/translations.md Normal file
View File

@@ -0,0 +1,33 @@
# Translations
> Directus is maintained by a global community of contributors who speak many different languages. Not only does Directus allow you to manage multilingual content, the App itself also supports multiple languages.
## App Translations
Directus supports internationalization across its entire Admin App. Many languages are currently supported, with more being added all the time. You can add or refine any languages through our [CrowdIn](https://locales.directus.io/) integration.
## Schema Translations
Directus uses [database mirroring](/concepts/databases/#database-mirroring) to dynamically pull in the technical names of your schema's tables ([Collections](/concepts/collections/)) and columns ([Fields](/concepts/fields/)), prettifying and formatting them for display throughout the App. You can then add additional schema translations to further support different languages.
::: tip Renaming Collections and Fields
If your project uses more _technical_ table or column names (eg: `cust` or `f_name`), you can also use schema translations to _rename_ Collections and Fields to something more intuitive (eg: `Customers` or `First Name`).
:::
## Content Translations
One of the most important features in Directus is the ability to manage multilingual content. While there are many different ways to accomplish this, such as creating _standard_ fields in the parent collection for each language, it is more extensible to use our _relational_ translation fields. These allow you to dynamically manage content in as many languages as is required, using a more intuitive interface.
Mixing standard and translated fields also allows language-agnostic data (such as dates or toggles) to remain within the parent collection.
### Integrating with Translation Services
There are two common ways to integrate with a third-party translation service.
For human-powered translation services, you can create a dedicated Role with limited permissions to properly scope their access to only the content they will be translating. You can also create [Workflows](/guides/permissions/#configuring-workflows) that require a certain internal Role to then approve the changes.
For machine-powered translation services, you could use the Directus API and Event Hooks to integrate the two platforms together. In this way, when your users create or update new content, an event hook can fire that fetches translations from the third-party service, saving that data into the translations.
Yet another option would be to create a [Custom Interface](/guides/interfaces/) that integrates with the third-party service to fetch translation in real-time.

32
docs/concepts/types.md Normal file
View File

@@ -0,0 +1,32 @@
# Types
> Every Field is configured with a specific "Type" which defines how its data is stored in the database. Often called a data-type, these are important in ensuring field values are saved cleanly and in a standardized format.
When creating a new field you'll be asked to choose a specific data-type. It's important to understand their purpose, because changing them later can cause massive data loss. For that reason, once you set a field's type, it can't be changed from within Directus.
The Type dictates the specific format of a field's _value_ when saving it to the database, helping to keep your data clean, standardized and valid. The type also tells the Directus API how to return your data, for example the `CSV` type is returned as an array of strings.
#### Relevant Guides
- [Creating a Field](/guides/fields/#creating-a-field)
## Directus Data Type Superset
Directus uses its built-in database abstraction to properly support all the different SQL vendors. However, these vendors do not share support for the same datatypes, instead, each SQL vendor maintains their own list. To standardize all of these differences, Directus has a single _superset_ of types that map to the vendor-specific ones.
- **String** — A shorter set of characters with a configurable max length
- **Text** — A longer set of characters with no real-world max length
- **Boolean** — A True or False value
- **Binary** — The data of a binary file
- **Integer** — A number without a decimal point
- **Big Integer** — A larger number without a decimal point
- **Float** — A less exact number with a floating decimal point
- **Decimal** — A higher precision, exact decimal number often used in finances
- **Timestamp** — A date, time, and timezone saved in ISO 8601 format
- **DateTime** — A date and time saved in the database vendor's format
- **Date** — A date saved in the database vendor's format
- **Time** — A time saved in the database vendor's format
- **JSON** — A value nested in JavaScript Object Notation
- **CSV** — A comma-separated value, returned as an array of strings
- **UUID** — A universally unique identifier saved in UUIDv4 format
- **Hash** — A string hashed using argon2 cryptographic hash algorithm

61
docs/concepts/users-roles-and-permissions.md
View File

@@ -1,61 +0,0 @@
# Users, Roles & Permissions
> Directus Users are the individual accounts that let you authenticate into the API and App. Each user belongs to a Role
> which defines its granular Permissions.
## Users
To use the App or API, you'll need a valid Directus User. Each user is assigned to a role that determines what they have
access to see and do. For instance, some users have access to the App, while others can only connect to the API.
Directus ships with a number of profile fields that help create a full-featured
[User Directory](/concepts/app-overview#user-directory), and setting fields that allow customizing your experience.
All Directus users are aggregated and shown on the [User Directory](/concepts/app-overview#user-directory) page of the
App
::: tip Extending Directus Users
While the included fields within Directus Users are required/locked, you can still _extend_ this collection with
additional custom fields as needed. You can do this via the normal [Create a new Field](/guides/fields) process from
within the system collection.
:::
### Relevant Guides
- [Setting up your User Profile](/guides/users#setting-up-your-user-profile)
- [Inviting a User](/guides/users#inviting-a-user)
- [Creating a User](/guides/users#creating-a-user)
- [Archiving a User](/guides/users#archiving-a-user)
- [Deleting a User](/guides/users#deleting-a-user)
## Roles
Each user is assigned to one Role, which determines their permissions within the App and API. There is no limit to the
number of roles you can create within Directus, so feel free to organize your users in whatever way feels most
appropriate.
### Public Role
Public is not technically a role, and can't be found in the `directus_roles` table. Instead, it represents the _lack_ of
a role, providing a place to configure permissions for unauthenticated users. This role can not be deleted, and has no
permissions by default.
### Administrators Role
Upon installation, Directus automatically creates this initial role to grant access to the first admin user. It is just
a normal role, and like any other it can be updated, renamed or deleted, however your project must maintain at least one
role with Admin Access at all times.
### Relevant Guides
- [Creating a Role](/guides/roles-and-permissions#creating-a-role)
- [Deleting a Role](/guides/roles-and-permissions#deleting-a-role)
## Permissions
Directus gives you granular, filter-based permissions for managing access-control.
### Relevant Guides
- [Managing Permissions](/guides/roles-and-permissions)

42
docs/concepts/users.md Normal file
View File

@@ -0,0 +1,42 @@
# Users
> Directus Users are the individual accounts that let you authenticate into the API and App. Each user belongs to a Role which defines its granular Permissions.
To use the App or API, you'll need a valid Directus User. Each user is assigned to a [Role](/concepts/roles/) that determines what they have access to see and do. This means that the experience of users may vary significantly depending on their role's access. For example, while some users may see _all_ platform content, others may only see a smaller subset of Modules, Collections, or Fields.
#### Relevant Guides
- [Setting up your User Profile](/guides/users/#setting-up-your-user-profile)
- [Creating a User](/guides/users/#creating-a-user)
- [Inviting a User](/guides/users/#inviting-a-user)
- [Configuring a User](/guides/users/#configuring-a-user)
- [Archiving a User](/guides/users/#archiving-a-user)
- [Deleting a User](/guides/users/#deleting-a-user)
## User Fields
Directus ships with a basic set of user fields that are displayed on the User Detail pages. While these system fields are required/locked, you can extend the Directus Users Collection with any number of custom fields to create a fully tailored [User Directory](/concepts/application/#user-directory). To add fields within system collections, simply follow the normal guide for [Creating a Field](/guides/fields/#creating-a-field).
Below are the system User fields included by default.
- **First Name** — The user's given name
- **Last Name** — The user's family name
- **Email** — The user's email address used for login/authenticating and email updates
- **Password** — The private string used for login/authenticating (stored as a secure hash)
- **Avatar** — An image displayed throughout the App that represents the user
- **Location** — Can be used for the user's city, country, office name, etc
- **Title** — The name of the position the user holds at their company or organization
- **Description** — A description or bio of the user
- **Tags** — A set of keywords useful when searching within the User Directory
- **Language** — (User Preference) The language to use for this user's App language
- **Theme** — (User Preference) Light, Dark, or Auto (based on the user's OS preferences)
- **Two-Factor Auth** — (User Preference) Enables authenticating with 2FA
- **Status** — (Admin Only) Determines if the user is active within the App/API
- **Role** — (Admin Only) The user's role determines their permissions and access
- **Token** — (Admin Only) A static string used for authenticating within the API
The sidebar's info component also includes the following readonly details:
- **User Key** — The primary key of the user
- **Last Page** — The last App page accessed by the user
- **Last Access** — The timestamp of the user's last App or API action

0
docs/contributing/code-of-conduct.md
View File

38
docs/contributing/codebase-overview.md Normal file
View File

@@ -0,0 +1,38 @@
# Codebase Overview
> **The core concepts behind Directus are simple, however the problems that must be solved to honor them can be remarkably complex.** We strive to design and engineer the most elegant solutions possible, so that our codebase remains accessible.
## Node Monorepo
The primary Directus repository is located at [`directus/directus`](https://github.com/directus/directus) and houses the Admin App (Vue.js 3), API (Node.js), project documentation (Markdown), API Specification (OpenAPI), and other smaller packages used internally. Directus follows a monorepo design similar to React or Babel — this page will outline our monorepo's design and structure.
## `/api`
Contains the Directus API (REST+GraphQL), written in node.js.
#### `/api/dist` — Does this look OK as a heading? Or should it be a description.
#### `/api/extensions`
#### `/api/src`
#### `/api/uploads`
## `/app`
Contains the Directus Admin App, written in Vue.js 3.
## `/docs`
Contains all the platform's documentation, written in markdown with additional VuePress formatting.
## `/packages`
TK
## `/`
The root of the project contains the following noteworthy files.
- **`.editorconfig`** — TK
- **`code_of_conduct.md`** — TK

0
docs/contributing/development-workflow.md
View File

133
docs/contributing/introduction.md
View File

@@ -1,23 +1,46 @@
# Contributing
> Our team truly appreciates every single pull-request, bug report, and feature request made by our community. If you
> have _any_ questions along the way, please reach out to our Core team on [Discord](https://directus.chat).
> Our team truly appreciates every single contributor, community member, GitHub star, pull-request, bug report, and feature request. Keeping Directus completely free and open-source is our way of saying: **Thank you!**
## Node Monorepo
::: tip We're here to help!
Our Node.js repository is located at `directus/directus` and houses the Admin App (Vue.js 3), Node.js API, project
documentation (Markdown), API Specification (OpenAPI), and other smaller packages used internally. Directus follows a
monorepo design similar to React or Babel — to learn more about our monorepo's design and structure, see our
[Codebase Overview](#codebase-overview) below.
If you have _any_ questions along your contributor journey, please feel free to come chat with us on our [Discord Community](https://directus.chat).
To contribute to the project, please follow the instructions located within our GitHub repository's
[contributing.md file](https://github.com/directus/directus/blob/main/contributing.md).
:::
## Code of Conduct
**The Directus [Code of Conduct](https://github.com/directus/directus/blob/main/code_of_conduct.md) is one of the ways we put our values into practice. We expect all of our staff, contractors and contributors to know and follow this code.**
**Our contributors and maintainers work extremely hard to build Directus as premium open-source software. Please be respectful of those efforts throughout our ecosystem. Trolling, harassing, insulting, or other unacceptable behavior by participants will not be tolerated.**
In the interest of fostering an open and welcoming environment, we as pledge to make participation in our project and community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
**Before continuing, please take a moment to read our full [Code of Conduct](https://github.com/directus/directus/blob/main/contributing.md).**
## Wait — Before you Begin
When contributing to this repository, it is important to first discuss the change you wish to make with the owners of this repository. This can be done via [GitHub Issue](https://github.com/directus/directus/issues), [GitHub Discussions](https://github.com/directus/directus/discussions), [Discord](https://directus.chat), [email](mailto:info@directus.io), or any other method.
Following this rule will help avoid wasted time caused by multiple people working on the same issue or writing code that will not be merged.
## Feature Requests
Feature requests are a great way to let our team know what should be prioritized next. You can
[submit a feature request](https://github.com/directus/directus/discussions/category_choices) or upvote
[existing submissions](https://github.com/directus/directus/discussions) all via our GitHub Discussions board.
[submit a new feature request](https://github.com/directus/directus/discussions/category_choices) or
[vote on existing submissions](https://github.com/directus/directus/discussions) via GitHub Discussions.
::: warning The 80/20 Rule
@@ -51,8 +74,6 @@ Issues. Please ensure the following for all submissions:
- You have confirmed the issue is not related to your own custom code
- Dev Only: You have cleared and reinstalled all dependencies
Please make sure to include all information required to reproduce your exact setup and issue in the issue report.
## Reporting Security Vulnerabilities
If you believe you have discovered a security issue within a Directus product or service, please reach out to us
@@ -64,77 +85,7 @@ team so that proper fixes can be issued to users. Our policy is to credit all re
order to receive credit, security researchers must follow responsible disclosure practices, including:
- They do not publish the vulnerability prior to the Directus team releasing a fix for it
- They do not divulge exact details of the issue, for example, through exploits or proof-of-concepts
## Code of Conduct
The Directus [Code of Conduct](https://github.com/directus/directus/blob/main/code_of_conduct.md) is one of the ways we
put our values into practice. We expect all of our staff, contractors and contributors to know and follow this code.
## Development Workflow
Before getting started, ensure you your local environment meets our [minimum requirements](/guides/installation/cli) and
you are familiar with Git. Please ensure you're on the "current" version of Node.js (see
[Node's release schedule](https://nodejs.org/en/about/releases/)).
::: tip
You will need to have a minimum of Node 12+ to build Directus!
:::
### 1. Fork the Directus repository
Go to the [repository](https://github.com/directus/directus) and fork it to your GitHub account. A fork is your copy of
the Directus repository. Forking the repository allows you to freely experiment with changes without affecting the
original project.
### 2. Clone from your repository
```bash
git clone git@github.com:YOUR-USERNAME/directus.git
```
### 3. Make a new branch
```bash
git checkout -b YOUR-BRANCH-NAME
```
### 4. Install the dependencies
```bash
npm install
```
### 5. Setup the Database & Env File
For this step, you'll need to already have a SQL database up-and-running, otherwise you can only use the SQLite driver,
which will create the database for you. Run the following command from within root of the project:
```bash
npm run cli -- init
```
### 6. Start the development server
Run the following command from the root directory.
```bash
npm run dev
```
::: tip
If you encounter errors during this installation process, make sure your node version meets the
[minimum requirements](/guides/installation/cli)
:::
### 7. Make your fixes/changes
At this point you are ready to start working on Directus! Before diving in however, it's worth reading through our docs
on [submitting a pull-request](#Submitting-a-Pull-Request).
- They do not divulge exact details of the issue, eg: through exploits or proof-of-concepts
## Submitting a Pull-Request
@@ -191,17 +142,3 @@ Before you begin or resume development, be sure to always sync, if you are going
changes!
:::
## Codebase Overview
### `/api`
Contains the Directus API (REST+GraphQL), written in node.js.
### `/app`
Contains the Directus Admin App, written in Vue.js 3.
### `/docs`
Contains all the platform's documentation, written in markdown with additional VuePress formatting.

0
docs/contributing/repo-overview.md
View File

62
docs/contributing/running-locally.md
View File

@@ -0,0 +1,62 @@
# Running Locally
> This guide explains how to install the _Development_ version of Directus locally so that you can work on the platform's source code. To install the _Production_ version locally, please follow to our [standard installation guides](/getting-started/installation/).
::: tip Minimum Requirements
You will need to have a **minimum of Node 12+** to _build_ a Development version of Directus, though it is recommended that you are on the [most "current" version of Node.js](https://nodejs.dev/en/about/releases/).
:::
## 1. Fork the Directus repository
Go to the [repository](https://github.com/directus/directus) and fork it to your GitHub account. A fork is your copy of
the Directus repository. Forking the repository allows you to freely experiment with changes without affecting the
original project.
## 2. Clone from your repository
```bash
git clone git@github.com:YOUR-USERNAME/directus.git
```
## 3. Make a new branch
```bash
git checkout -b YOUR-BRANCH-NAME
```
## 4. Install the dependencies
```bash
npm install
```
## 5. Setup the Database & Env File
For this step, you'll need to already have a SQL database up-and-running, otherwise you can only use the SQLite driver,
which will create the database for you. Run the following command from within root of the project:
```bash
npm run cli -- init
```
## 6. Start the development server
Run the following command from the root directory.
```bash
npm run dev
```
::: tip
If you encounter errors during this installation process, make sure your node version meets the
[minimum requirements](/guides/installation/cli)
:::
## 7. Make your fixes/changes
At this point you are ready to start working on Directus! Before diving in however, it's worth reading through our docs
on [submitting a pull-request](#Submitting-a-Pull-Request).

31
docs/contributing/translations.md
View File

@@ -1,18 +1,21 @@
# App Translations
# Translating the App
> TK
> Directus is maintained by a global community of contributors who speak many different languages. For that reason, the App itself also supports multiple languages.
## Translating the App
The Directus App has been translated into many different languages, and it's easy to add or improve the languages of your choice.
The Directus App has been translated into many different languages, and makes it easy to add or improve the languages of
your choice.
1. Navigate to our translation service at: [https://locales.directus.io](https://locales.directus.io)
2. **Check** if your desired language is listed
* If not, contact the Core Team on our [Community Chat](https://directus.chat) to request it
3. **Click the desired language**
4. Click the **"Translate All"** button in the header
5. **Log in to Crowdin**, or register an account as needed
6. **Click on the strings** to translate in the left sidebar
7. **Type translations**, or select an ideal match from the list of recommendations
8. Click **"Save"**
1. Navigate to our translation service at: https://locales.directus.io
2. Check to see if your desired language is already in our list \* If not, you can request it by contacting the core
team via our [Community Chat](https://directus.chat)
3. Click the desired language
4. Click the "Translate All" button in the header
5. Log in to Crowdin, or register an account as needed
6. Click on the strings to translate in the left sidebar
7. Type translations, or select an ideal match from the list of recommendations
8. Click "Save"
::: tip Missing Context
If a translation string is missing enough context to understand its usage, Crowdin allows you to request additional context.
:::

39
docs/getting-started/backing-directus.md
View File

@@ -1,14 +1,11 @@
# Backing Directus
> Directus is both _premium_ and _free_ — two things that don't often go together. It takes significant resources to
> maintain and advance the platform. If you'd like to help keep Directus active and open-source please consider
> supporting it through one of the methods below.
> Directus is both _premium_ and _free_ — two things that don't often go together. It takes significant resources to maintain the platform. If you'd like to help keep development active, please consider supporting Directus through one of the methods below.
## Financial Support
Talented full-time and part-time staff, infrastructure, and third-party services are just some of our organization's
expenses, and revenue from our Cloud services and donations from sponsors doesn't fully cover those costs. Below are a
few ways to help us keep the lights on and move towards self-sufficiency.
Talented full-time and part-time staff, infrastructure, and third-party services are just some of our organization's many
expenses. Below are a few ways to help us keep the lights on and move towards a self-sufficient open-source core product.
### GitHub Sponsors
@@ -16,32 +13,30 @@ Monthly donations via [GitHub Sponsors](https://github.com/sponsors/directus) ar
support. Donate to the organization, or directly to our core developers!
- [Directus](https://github.com/sponsors/directus) — Organization
- [rijkvanzanten](https://github.com/rijkvanzanten) — Technical Lead
- [WoLfulus](https://github.com/WoLfulus) — DevOps
- [Nitwel](https://github.com/Nitwel) — Developer
- [benhaynes](https://github.com/benhaynes) — Project Lead
- [rijkvanzanten](https://github.com/rijkvanzanten) — Technical Lead
- [WoLfulus](https://github.com/WoLfulus) — DevOps
- [Nitwel](https://github.com/Nitwel) — Developer
### Sponsored Work
[Commissioned Features](/getting-started/support#commissioned-features) and
[Expedited Fixes](/getting-started/support-expedited-features) are great ways to financially support the development of
[Commissioned Features](/getting-started/support/#commissioned-features) and
[Expedited Fixes](/getting-started/support/#expedited-fixes) are great ways to financially support the development of
Directus, and improve the codebase for the community.
### Merch
Our merchandise is a great way to support Directus — you get some swag, and we get some financial support and
advertising. Simply make an appropriate financial donation through
[GitHub Sponsors](https://github.com/sponsors/directus), message us with sizing/shipping details, and we'll get it
shipped!
Our merchandise is a great way to support Directus — you get some swag, and we get some financial support and advertising. Simply make an appropriate financial donation through [GitHub Sponsors](https://github.com/sponsors/directus) (or contact us for bulk pricing), and once we coordinate sizing and shipping details, we'll get it shipped!
## Other Contributions
Below are several ways anyone can help improve our ecosystem.
Below are several ways that _anyone_ can help improve the Directus ecosystem. These are free alternatives for when financial support is not a possibility.
### Code Pull Requests
Squashing bugs, optimizing the codebase, increasing test coverage, and adding new features, are all extremely valuable.
Not technical? We have plenty of documentation that can always use some extra attention. Learn more in our
[Contributors Guide](/getting-started/contributing).
[Contributors Guide](/contributing/introduction).
### Translations
@@ -51,17 +46,17 @@ Every translation enables users in new languages to use our international platfo
### Bug Reporting
If you encounter an issue within Directus, no matter how small, we would love to hear about it. Proper bug reporting
helps our team assess the platform's stability. [Report a bug](https://github.com/directus/directus/issues/new)
helps our team improve platform stability. [Report a bug on GitHub](https://github.com/directus/directus/issues/new)
### Brand Advocacy
You can create _perfect_ software, but if no one knows about it, it's all for naught. Marketing and advertising are
expensive, but you can help us avoid these costs with the following quick options:
- **GitHub Stars** — The primary metric by which we measure our success. It only takes five seconds to head to
[directus/directus](https://github.com/directus/directus) and click the star — enough in a short period of time and
Directus gets featured on GitHub's trending page!
- **Social Posts** — A quick post mentioning [@directus](https://twitter.com/directus) goes a long way, and we re-tweet
- **GitHub Stars** — The primary metric by which we measure our success. It only takes a few seconds to head to the
[Directus GitHub](https://github.com/directus/directus) and click the star. Enough activity in a short period of time and
we get even more exposure from being featured on GitHub's trending page!
- **Social Posts** — A quick post mentioning [@directus](https://twitter.com/directus) goes a long way — and we re-tweet
the team's favorite shout-outs to our 35K+ followers.
- **Testimonials** — _One sentence._ Even that was a sentence, and it was only two words! If you're a fan of Directus,
we'd love to hear why with a short endorsement. Shoot us an [email](mailto:info@directus.io),

30
docs/getting-started/installation.md
View File

@@ -1,7 +1,8 @@
# Installation
Directus can be installed in many different ways, on several different stacks. While our CLI is the easiest method, feel
free to use whichever option best suits your needs.
> Directus can be installed in many different ways and on several different stacks. You can choose between local, self-hosted on-premises, or our managed Cloud solution.
While our CLI is the recommended method for self-hosting, you can use whichever of these self-hosted options best suits your needs. These methods offer a high level of customization and are ideal for intermediate developers.
- [Command Line Interface (CLI)](/guides/installation/cli)
- [Docker](/guides/installation/docker)
@@ -9,26 +10,29 @@ free to use whichever option best suits your needs.
::: tip Development Environment
To work on the project's source code, please follow our [Contributing Guide](/getting-started/contributing).
To work on the Directus Core source code, please follow our [Contributing Guide](/contributing/introduction).
:::
## Deployment Guides
The following guides will walk you through the self-hosted installation process for specific third-party platforms. These options are only recommended for developers familiar with these services and comfortable with more advanced setup. While Directus is always completely free, you will likely need to pay for these services.
- [Generic Ubuntu](/guides/installation/ubuntu)
- [Amazon AWS](/guides/installation/aws)
- [DigitalOcean App Platform](/guides/installation/digitalocean-app-platform)
## One-Click Install Guides
## One-Click Installs
- [Platform.sh](/guides/installation/platformsh-one-click)
If you would like to completely avoid the manual installation process, the following self-hosted one-click apps will handle the heavy-lifting for you. While Directus is always completely free, you will likely need to pay for these services.
<!--
@TODO
- [Google App Engine](/guides/installation/google-app-engine)
- [One-Clicks](/guides/installation/one-clicks) (heroku / do / platform sh / etc)
- [Microsoft Azure](/guides/installation/microsoft-azure) -->
- [Directus DigitalOcean App](https://marketplace.digitalocean.com/apps/directus?action=deploy&refcode=4c0b6062c16e)
- [Directus Platform.sh App](https://console.platform.sh/projects/create-project?template=https%3A%2F%2Fraw.githubusercontent.com%2Fplatformsh%2Ftemplate-builder%2Fmaster%2Ftemplates%2Fdirectus%2F.platform.template.yaml)
## Optional Setup Guides
## Directus Cloud
- [Caddy](/guides/setup/caddy)
- [Nginx](/guides/setup/nginx)
In addition to the self-hosted options above, you can also choose to create Directus projects using our official Managed Cloud Service. This is the easiest way to get up-and-running with Directus — even for non-technical users. Unique features include dedicated hardware, automatic updates, automatic backups, usage-based pricing, and more.
- [Directus Cloud Dashboard](http://directus.cloud/)
- [Learn more about On-Demand Cloud](https://directus.io/on-demand-cloud/)
- [Learn more about Enterprise Cloud](https://directus.io/enterprise-cloud/)

96
docs/getting-started/introduction.md
View File

@@ -1,6 +1,6 @@
# Directus Docs
> These Docs will help get you up-and-running quickly, guide you through advanced features, and explain the concepts
> These Docs will help you get up-and-running quickly, guide you through advanced features, and explain the core concepts
> that make Directus so unique.
::: warning Version 9
@@ -13,34 +13,26 @@ Node.js. If you are looking for the previous **[Directus 8](https://github.com/d
## What is Directus?
**Directus is an open-source platform that provides a real-time API and intuitive Admin App for your custom database.**
Built on node.js and vue.js 3, it allows both administrators and non-technical users to view and manage the content/data
stored within pure SQL databases. It can be used as a headless CMS for managing project content, a database client for
modeling and viewing raw data, or as a standalone customizable WebApp.
**Directus is an Open Data Platform for managing the content of any SQL database. It provides a powerful API layer for developers and an intuitive App for non-technical users.** Written entirely in JavaScript (primarily [Node.js](https://nodejs.dev) and [Vue.js](https://vuejs.org)), Directus is completely open-source, modular, and extensible, allowing it to be fully tailored to your exact project needs.
Our platform can be used as a headless CMS for managing digital experiences, a database client for democratizing data, or as a standalone back-office web app for CRM, inventory, business intelligence, project management, etc.
::: tip What's in a name?
"Directus" ([duh REKT iss](http://audio.pronouncekiwi.com/Salli/Directus)) is latin for: _laid straight, arranged in
"Directus" ([duh REKT iss](http://audio.pronouncekiwi.com/Salli/Directus)) is Latin for: _laid straight, arranged in
lines_. The broadest goal of our platform is to present data in a simple, orderly, and intuitive way.
:::
## What makes it unique?
**Directus dynamically generates custom API endpoints based on your SQL database's custom schema in real-time —
something we call "Database Mirroring".** Whether you install fresh or on top of an existing database, you always
maintain complete control over your actual database... including tables, columns, datatypes, default values, indexes,
relationships, etc.
**Directus dynamically generates custom API endpoints based on your SQL database's schema in real-time — something we call "Database Mirroring".** Whether you install fresh or on top of an existing database, you always maintain end-to-end control over your actual database, including: tables, columns, datatypes, default values, indexes, relationships, etc.
Perhaps one of the biggest advantages of _Database Mirroring_ is that you have direct access to your pure and unaltered
data. That means you can even bypass the Directus middleware (API, SDK, App), and connect to your data with proper SQL
queries — effectively removing all bottlenecks, additional latency, or proprietary access limitations.
Perhaps one of the biggest advantages of _Database Mirroring_ is that you have direct access to your pure and unaltered data. That means you have the option to bypass the Directus middleware (API, SDK, App) and connect to your data with proper SQL queries. This effectively removes all bottlenecks, latency overhead, and proprietary access limitations.
Directus is a simple solution for complex problems. Every aspect of Directus is data-first and guided by the following
core principles:
Directus is a simple solution for complex problems, with a data-first approach guided by the following core principles:
- **Pure** — There is no predefined model or proprietary rules for your agnostic schema, and all system settings are
stored separately.
- **Pure** — There is no predefined model or proprietary rules for your schema, and all system settings are stored separately.
- **Open** — Our entire codebase is public and transparent, allowing for end-to-end audits. Nothing is obfuscated or
black-boxed.
- **Portable** — Data is stored in your bespoke database and can be migrated/exported/backed-up at any time. Absolutely
@@ -54,68 +46,68 @@ core principles:
## The Directus Ecosystem
### Open-Source Engine
### Open-Source Core
Completely free and open-source on the GPLv3 license, Directus is publicly available within our
[npm package](https://www.npmjs.com/package/directus) and main
[GitHub repository](https://github.com/directus/directus). It includes our dynamic API engine (node.js), the intuitive
Admin App (vue.js 3), this documentation (markdown), and all dependencies.
Our completely free and open-source (GPLv3) Open Data Platform. Directus includes our dynamic API engine (Node.js), the intuitive Admin App (Vue.js), this documentation (Markdown), and all dependencies.
### On-Demand Cloud
Our self-service platform for quick and affordable instances of Directus on a multitenant infrastructure.
### Enterprise Cloud
Dedicated hardware, custom limits, full white-labeling, uptime SLAs, and more are available on this premium managed
solution.
- **[GitHub Repository](https://github.com/directus/directus)**
- **[npm Package](https://www.npmjs.com/package/directus)**
- **[Docker Image](https://hub.docker.com/r/directus/directus)**
### Documentation
[Our online documentation](https://docs.directus.io) describes the most recent version of our platform. They are written
in publicly managed markdown files so the community can help keep them clean and up-to-date!
[Our documentation](https://docs.directus.io) describes the most recent version of our platform. They are written in
publicly managed markdown files so the community can help keep them clean and up-to-date. The docs are divided into the following sections:
- Getting Started: Novice Oriented. For a platform intro and installation.
- Concepts: Learning Oriented. For understanding the platform.
- Guides: Problem Oriented. Follow along with steps while working.
- Reference: Information Oriented. Look up info and specs while working.
- [Getting Started](/getting-started/introduction/) — Novice oriented, for a platform intro and installation.
- [Concepts](/concepts/platform-overview/) — Learning oriented, for understanding the platform.
- [Guides](/guides/projects/) — Problem oriented, follow along with steps while working.
- [Reference](/reference/command-line-interface/) — Information oriented, look up info and specs while working.
- [API Reference](/reference/api/introduction/) — Information oriented, look up API resources while working.
- [Contributing](/contributing/introduction/) — Contributor oriented — resources for working on Open-Source Core.
::: tip Versioned Docs
Docs for specific versions of Directus 9+ are available within the individual Project's App Documentation module.
Specific version of the Docs ship with each install of Directus 9. They can be found within the [Documentation module](/concepts/app-overview.html#documentation) of the App.
:::
<!-- ### Online Demo
### On-Demand Cloud
[Our online demo](https://demo.directus.io) (`admin@example.com` + `password`) is a quick way to try things out in an isolated sandbox. This entire instance resets each hour.
[Our self-service platform](https://directus.cloud) for quick and affordable instances of Directus on a multitenant infrastructure. Each project includes automatic updates, automatic backups, .
### Enterprise Cloud
Our premium managed solution. Powered by dedicated hardware in your selected region, this service offers high-availability, custom limits, SSO, API white-labeling, uptime SLAs, and more. [Contact our sales team](https://directus.io/contact/) to discuss pricing and options.
### Cloud Documentation
[Cloud-Specific Docs](https://directus.cloud/docs) include guides for managing projects within our Cloud Dashboard.
### Private Demos
Our On-Demand Cloud platform includes ability to [create private demo instances](https://directus.cloud/docs#creating-a-private-demo). Each demo runs the latest version of Directus, lasts for several hours, and is completely free, with no credit card required.
### System Status
The [Status Page](https://status.directus.io) provides up-to-date information on our various systems, including current and historical incident details and our 30-day uptime percentage.
The [Status Page](https://status.directus.cloud) provides up-to-date information on our various systems, including current and historical incident details and our 30-day uptime percentage. From this site you can access the global status or your Cloud project's dedicated status page.
-->
### Marketing Website
### Website
Our [marketing site](https://directus.io) provides general information, resources, and team info for the project.
### Social
For the latest product info and sneak-peeks into upcoming releases, be sure to follow us on
[Twitter](https://twitter.com/directus).
For the latest product info and sneak-peeks, be sure to follow us on [Twitter](https://twitter.com/directus).
### Community
Join our growing community of 2,600+ developers on [Discord](https://directus.chat). From community support to seeing
where the platform is heading next, it's a great way to get more involved.
Join our growing community of 4,000+ developers on [Discord](https://directus.chat) and Slack (legacy). From community support to seeing where the platform is heading next, it's a great way to get involved.
### Languages
### App Locales
In addition to managing multilingual content, the Directus Admin App itself can also be translated into different
languages. Our languages are managed through the [Directus CrowdIn](https://locales.directus.io/), which provides a
friendly interface and automatically submits pull-requests to the git repository.
We use [Crowdin](https://locales.directus.io/) to manage our numerous App translations. If you're looking to add or improve Directus in your language, you can [learn more here](#).
### Marketplace
Coming soon. A library of free and paid Directus extensions created by our core team and community members.
Coming in 2021, the [Directus Marketplace](https://directus.market/) will offer a unified portal to extensions created by our Core Team and community contributors.

101
docs/getting-started/quickstart.md
View File

@@ -1,20 +1,115 @@
# Quickstart
# Quickstart Guide
> If you're looking for the fastest way to get up-and-running with Directus, this guide will walk you through getting
> things installed, configured, and modeled.
@TODO — Create embedded video overview
## 1. Installation
Make sure you have the latest LTS version of [Node.js](https://nodejs.dev) installed, and have a running database ready
to connect to.
Run the following command in your terminal and follow the prompts.
```bash
npx create-directus-project example-project
```
![Successful installation](../assets/getting-started/quickstart/terminal-install.png)
Once the installation is complete, you can start Directus by navigating to your project folder (in this case
`example-project`) and running:
```
npx directus start
```
![Server started](../assets/getting-started/quickstart/terminal-start.png)
## 2. Login to App
With the server running, you're now able to login to your new Directus project and start using it.
Our start command stated that the server started at port `8055`, which means we can navigate to
[http://localhost:8055](http://localhost:8055) to open Directus in the browser.
Login using the admin credentials you configured during the installation in Step 1.
## 3. Create a Collection
Once logged in, you're greeted with the option to create your first Collection:
![Directus Empty State](../assets/getting-started/quickstart/empty-state.png)
Follow the prompts and create a Collection. For the sake of this demo, we'll be calling ours `articles`, but feel free
to make it your own!
::: tip More Info on Collections
For a more in-depth guide to setting up Collections, see [Collections](/guides/collections).
:::
## 4. Create a Field
With the Collection created, it's time to start adding some Fields. Click the **"Create Field"** button, and select
"Standard Field":
![Directus Add a Field](../assets/getting-started/quickstart/add-field.png)
We'll be calling our Field `title`. While Directus offers a range of powerful field customization options, we'll be sticking to the defaults for now. These defaults use the "String" datatype and "Text Input" interface
::: tip More Info on Fields
To learn more about the different types of Fields, and all available options, see [Fields](/guides/fields).
:::
## 5. Create an Item
Now that we have a Collection with a Field configured, it's time to start adding some content. Navigate to the
Collections Module (top left), open your created Collection, and click the "+" button in the top-right to get started.
![Directus Create Item](../assets/getting-started/quickstart/create-item.png)
Once you're happy with your creation, click the checkmark in the top-right to save your item to the database.
## 6. Set Role/Public Permissions
By default, all content entered into Directus is considered private. This means that no data will be returned by the
API, unless requested by an authenticated user that has the correct permissions. In order to have the API return our
items, we'll have to setup some permissions. Navigate to **Settings Module > Roles & Permissions**.
Directus ships with a special **"Public"** role that controls what data is returned to non-authenticated users. Select the
public role, find your collection, and click the icon under the "eye" icon (read/view permission) to allow the public role to read the
items in your collection.
![Directus Permissions](../assets/getting-started/quickstart/permissions.png)
::: tip More Info on Permissions
Permissions are extremely powerful and can get pretty in-depth. To learn all about the nuances in setting up permissions, see
[Roles & Permissions](/guides/roles-and-permissions).
:::
## 7. Connect to the API
Now that your project has some content in it, it's time to start using this content externally. Data can be accessed in
a number of ways, including the REST API, GraphQL, the CLI, or even straight from the database. In this case, we'll use
[the `/items/` REST API endpoint](/reference/api/items) to retrieve the item we just created.
Using your browser, or an API tool like [Postman](http://postman.com) or [Paw](https://paw.cloud), open
[http://localhost:8055/items/articles](http://localhost:8055/items/articles).
And there it is! The Article Item you just created is being served in beautiful JSON, ready to be used anywhere and everywhere!
```json
{
"data": [
{
"id": 1,
"title": "Hello World!"
}
]
}
```

27
docs/getting-started/support.md
View File

@@ -1,7 +1,6 @@
# Technical Support
# Help &amp; Support
> Directus is offered completely free and open-source for anyone wishing to self-host the platform. There are many
> resources, both free and paid, to help you get up-and-running smoothly.
> Directus is offered completely free and open-source for anyone wishing to self-host the platform. If you have questions along the way, there are many resources, both free and paid, to help you get up-and-running smoothly.
## Community Support
@@ -9,12 +8,12 @@
community and core developers often check this platform and answer posts. It has the added benefit of being an archival
resource for others developers with similar questions.
Our [Discord](https://directus.chat) community is another great way to get assistance. Please keep all questions on the
Our [Discord Community](https://directus.chat) is another great way to get assistance. Please keep all questions on the
`#help` channel, be considerate, and remember that you are getting free help from the community for a free product.
## Premium Support
Premium support is included with our Enterprise Cloud service. On-Demand Cloud customers and On-Premise users interested
Premium support is included with our Enterprise Cloud service. On-Demand Cloud customers and Self-Hosted users interested
in learning more about our monthly retainer agreements should contact us at
[support@directus.io](mailto:support@directus.io).
@@ -24,7 +23,7 @@ in learning more about our monthly retainer agreements should contact us at
If you need a specific feature added to Directus faster than the normal development timeline,
[reach out to us](https://directus.io/contact/) for a quote. Our parent agency will often help subsidize the cost of
developing new features if they pass our [80/20 Rule](/getting-started/contributing) and can be merged into the core
developing new features if they pass our [80/20 Rule](/contributing/introduction) and can be merged into the core
codebase. Other custom/proprietary development will be built bespoke within our robust extension system.
### Expedited Fixes
@@ -34,29 +33,17 @@ resolved sooner, [reach out to us](https://directus.io/contact/) for a quote.
## Frequently Asked Questions
<!--
@TODO
### Does Directus handle deploying or migrating projects?
Directus includes [export](#) and [backup](#) tools to assist in deploying data changes between
environments (eg: from _development_ to _production_), however there is no formal migration
workflow.
Additionally, since Directus stores all of your data in pure SQL, you can use almost any preexisting
workflow or toolkit for this process. -->
### Does Directus support Mongo/NoSQL?
Not currently. Directus has been built specifically for wrapping _relational_ databases. While we could force Mongo to
use tables, columns, and rows via Mongoose object modeling, that approach to non-structured doesn't make a lot of sense.
We realize many users are interested in this feature, and will continue to explore its possibility.
use tables, columns, and rows via Mongoose object modeling, that approach of "faking" a relational structure in a non-structured environment like Mongo doesn't make a lot of sense. We do realize many users are interested in this feature, and will continue to explore its possibility.
### Why haven't you added this feature, or fixed that issue yet?
Directus is primarily a free and open-source project, maintained by a small core team and community contributors who
donate their time and resources.
Our platform is feature-rich, however we strictly adhere to our [80/20 Rule](/getting-started/contributing) to avoid a
Our platform is feature-rich, however we strictly adhere to our [80/20 Rule](/contributing/introduction) to avoid a
messy/bloated codebase. Directus is also quite stable, however new issues still arise, some of which may be triaged with
a lower prioritization.

0
docs/extensions/accessing-data.md → docs/guides/accessing-data.md
View File

173
docs/guides/api-config.md Normal file
View File

@@ -0,0 +1,173 @@
# Configuring the API
[[toc]]
## Cache
Directus has a built-in way to do data-caching. Enabling this will cache the output of the request (based on the current
user and exact query parameters used) into to configured cache storage location. This will drastically improve API
performance, as subsequent requests are served straight from this cache. Enabling cache will also make Directus return
accurate cache-control headers. Depending on your setup, this will further improve performance by caching the request in
middleman servers (like CDNs) and even the browser.
You can enable the data-cache with the `CACHE_ENABLED` environment variable.
### Cache Store
In bigger projects, you most likely don't want to rely on local memory to keep the caches. Instead, you can use the
`CACHE_STORE` environment variable to tell Directus to use either `memcache` or `redis` to store the caches.
```
CACHE_ENABLED="true"
CACHE_STORE="redis"
CACHE_REDIS="redis://@127.0.0.1"
```
### Auto-Purging
Directus can automatically clear the caches whenever a create/update/delete action is performed. This allows you to keep
the Directus API real-time, while still getting the performance benefits on quick subsequent reads.
```
CACHE_AUTO_PURGE="true"
```
### TTL
Based on your project's needs, you might be able to aggressively cache your data, only requiring new data to be fetched
every hour or so. This allows you to squeeze the most performance out of your Directus instance. This can be incredibly
useful for applications where you have a lot of (public) read-access and where updates aren't real-time (for example a
website). `CACHE_TTL` uses [`ms`](https://www.npmjs.com/package/ms) to parse the value, so you configure it using human
readable values (like `2 days`, `7 hrs`, `5m`).
```
CACHE_TTL="1h"
```
### Assets
The cache-control header for the /assets endpoint is separate from the regular data-cache. This is useful as it's often
possible to cache assets for way longer than you would with the actual content.
```
ASSETS_CACHE_TTL="7d"
```
## oAuth (Single Sign-On / OpenID)
Directus' oAuth integration provides a powerful alternative way to authenticate into your project. Directus will ask you
to login on the external service, and if your user exists in Directus, you'll be logged in automatically.
Directus relies on [`grant`](https://www.npmjs.com/package/grant) for the handling of the oAuth flow. This means that
there's hundreds of services that are supported out of the box. For example, enabling logging in through GitHub is as
easy as creating an [oAuth app in GitHub](https://github.com/settings/developers) and adding the following to Directus:
```
OAUTH_PROVIDERS="github"
OAUTH_GITHUB_KEY="99d3...c3c4"
OAUTH_GITHUB_SECRET="34ae...f963"
```
::: warning PUBLIC_URL
The oAuth flow relies on the `PUBLIC_URL` variable for it's redirecting. Make sure that variable is configured
correctly.
:::
#### Multiple Providers
`OAUTH_PROVIDERS` accepts a CSV of providers, allowing you to specify multiple at the same time:
```
OAUTH_PROVIDERS ="google,microsoft"
OAUTH_GOOGLE_KEY = "<google_application_id>"
OAUTH_GOOGLE_SECRET= "<google_application_secret_key>"
OAUTH_GOOGLE_SCOPE="openid email"
OAUTH_MICROSOFT_KEY = "<microsoft_application_id>"
OAUTH_MICROSOFT_SECRET = "<microsoft_application_secret_key>"
OAUTH_MICROSOFT_SCOPE = "openid email"
OAUTH_MICROSOFT_AUTHORIZE_URL = "https://login.microsoftonline.com/<microsoft_application_id>/oauth2/v2.0/authorize"
OAUTH_MICROSOFT_ACCESS_URL = "https://login.microsoftonline.com/<microsoft_application_id>/oauth2/v2.0/token"
PUBLIC_URL = "<public_url_of_directus_instance>"
```
### Provider Specific Configuration
If you use one of the many supported providers, you often don't have to configure any more than just the key and secret
for the service. That being said, if you use a more tailored service (like the specific Microsoft application in the
example above), you might have to provide more configuration values yourself. Please see
https://github.com/simov/grant#configuration-description for a list of all available configuration flags.
## File Storage
By default, Directus stores every file you upload locally on disk. Instead of local file storage, you can configure
Directus to use S3 or Google Cloud Storage instead:
```
STORAGE_LOCATIONS="aws"
STORAGE_AWS_DRIVER="s3"
STORAGE_AWS_KEY="tp15c...510vk"
STORAGE_AWS_SECRET="yk29b...b932n"
STORAGE_AWS_REGION="us-east-2"
STORAGE_AWS_BUCKET="my-files"
```
### Multiple Storage Adapters
You can configure multiple storage adapters at the same time. This allows you to choose where files are being uploaded
on a file-by-file basis. To do this, you can provide a CSV of storage location names, and provide a config block for
each of them:
```
STORAGE_LOCATIONS="local,aws"
STORAGE_LOCAL_DRIVER="local"
STORAGE_LOCAL_ROOT="local"
STORAGE_AWS_KEY="tp15c...510vk"
STORAGE_AWS_SECRET="yk29b...b932n"
STORAGE_AWS_REGION="us-east-2"
STORAGE_AWS_BUCKET="my-files"
```
In the Admin App, files will automatically be uploaded to the first configured storage location (in this case `local`).
The used storage location is saved under `storage` in `directus_files`.
## Rate Limiting
You can use the built-in rate-limiter to prevent users from hitting the API too much. To enable the rate-limiter, simply
set
```
RATE_LIMITER_ENABLED="true"
```
This will kick-in the rate-limiter on a maximum of 50 requests a second. You can configure this using:
```
// 10 requests per 5 seconds
RATE_LIMITER_POINTS="10"
RATE_LIMITER_DURATION="5"
```
Once you have multiple copies of Directus running under a load-balancer, or your user base grows so much that memory is
no longer a viable place to store the rate limiter information, you can use an external `memcache` or `redis` instance
to store the rate limiter data:
```
RATE_LIMITER_ENABLED="true"
RATE_LIMITER_POINTS="10"
RATE_LIMITER_DURATION="5"
RATE_LIMITER_STORE="redis"
RATE_LIMITER_REDIS="redis://@127.0.0.1"
```

6
docs/extensions/api-endpoints.md → docs/guides/api-endpoints.md
View File

@@ -1,6 +1,6 @@
# Creating a Custom API Endpoint
# Custom API Endpoints <small></small>
> Custom API Endpoints allow you to extend the core functionality of the platform's API.
> Custom API Endpoints register new API routes which can be used to infinitely extend the core functionality of the platform.
## 1. Setup the Boilerplate
@@ -47,8 +47,6 @@ To deploy your endpoint, simply restart the API by running:
npx directus start
```
---
## Full Example:
```js

6
docs/extensions/api-hooks.md → docs/guides/api-hooks.md
View File

@@ -1,6 +1,6 @@
# Creating a Custom API Hook
# Custom API Hooks <small></small>
> Hooks allow running custom logic when specificed events occur within your project.
> Custom API Hooks allow running custom logic when a specified event occurs within your project. They can be registered as either "blocking" or immediate.
## 1. Create a Hook File
@@ -142,8 +142,6 @@ To deploy your hook, simply restart the API by running:
npx directus start
```
---
## Full Example:
```js

71
docs/guides/collections.md
View File

@@ -1,17 +1,13 @@
# Collections
> You can manage your collections within the Data Model section of the App's Settings, via the
> [API Collections Endpoint](/reference/api/collections), or directly within the database. If you're unfamiliar with
> Directus Collections, please start by reading our [Understanding Collections](/concepts/platform-overview#collections)
> docs.
> Collections are containers for specific groupings of Items. Each collection represents a **table** in your database. [Learn more about Collections](/concepts/collections/).
## Creating a Collection
1. Navigate to **Settings > Data Model**
2. Click the **Create Collection** action button in the header
3. Enter a unique **Collection Name**, keeping in mind that this is entered as a _key_ that determines the database
table name, and is then presented in the App using the
[Title Formatter](/reference/internal-helpers#title-formatter).
table name, and is then presented in the App using the internal Title Formatter.
4. Optional: Configure the collection's **Primary Key** name and type.
- Auto-Incremented Integer
- Generated UUID
@@ -41,29 +37,26 @@ the database, and it will automatically appear within Directus. The first time y
## Configuring a Collection
### Fields & Layout
- [Creating a Field](/guides/fields#creating-a-field)
- [Updating a Field](/guides/fields#updating-a-field)
- [Deleting a Field](/guides/fields#deleting-a-field)
- [Duplicating a Field](/guides/fields#duplicating-a-field)
- [Changing Field Order & Layout](/guides/fields#adjusting-field-layout)
### Collection Setup
- **Collection Name** — This is the key for the collection. It can not be modified, but you can override it with
Translations (see below)
- **Icon** — The icon used throughout the App when referencing this collection
- **Note** — A helpful note that explains the collection's purpose
- **Display Template** — A [Field Template](#) used to create dynamic titles for the collection's items
- **Hidden** — Toggles if the collection should be globally hidden. Keep in mind that Admin roles can always see all
collections.
- **Singleton** — Is this collection will only contain a single item (eg: an "About Us" form). When enabled, the
[Collection Detail](/concepts/app-overview#collection-detail) will be bypassed, and users are taken directly to the
[Item Detail](/concepts/app-overview#item-detail) page.
- **Translation** — Allows translating the collection name into different languages. These
[Schema Translations](/concepts/internationalization#schema-translations) are important for multilingual projects. You
can also "translate" a collection name into the default language — helpful for renaming technical table names.
1. Navigate to **Settings > Data Model > [Collection Name]**
2. Configure the following settings:
- **Collection Name** — This is the key for the collection. It can not be modified, but you can override it with Translations (see field below).
- **Icon** — The icon used throughout the App when referencing this collection
- **Note** — A helpful note that explains the collection's purpose
- **Display Template** — A [Field Template](#) that creates dynamic titles for the collection's items
- **Hidden** — Toggles if the collection should be globally hidden. Keep in mind that Admin roles can always see all
collections.
- **Singleton** — For collections that will only contain a single item (eg: an "About Us" form), the
[Collection Detail](/concepts/application/#collection-detail) will be bypassed, and users are taken directly to the [Item Detail](/concepts/application/#item-detail) page.
- **Translation** — Allows translating the collection name into different languages. These
[Schema Translations](/concepts/translations/#schema-translations) are important for multilingual projects. You
can also "translate" a collection name into the default language — helpful for renaming technical table names.
3. **Create and configure any fields** within this Collection.
- [Creating a Field](/guides/fields/#creating-a-field)
- [Updating a Field](/guides/fields/#updating-a-field)
- [Deleting a Field](/guides/fields/#deleting-a-field)
- [Duplicating a Field](/guides/fields/#duplicating-a-field)
- [Changing Field Order & Layout](/guides/fields/#adjusting-field-layout)
4. Optional: Configure the [Archive](#archive) and [Sort](#sort) options below.
### Archive
@@ -81,7 +74,7 @@ Items that have been archived are still returned normally via the API. It is up
:::
::: tip Status Field
::: tip Automatic Setup
When creating a new Collection, you have the option of creating an optional "Status" field. If you choose to include
this field, the collection's archive settings will automatically be configured for you.
@@ -91,10 +84,10 @@ this field, the collection's archive settings will automatically be configured f
### Sort
The sort feature enables manual drag-and-drop item reordering within the Directus App. This is typically shown on the
[Collection Detail](/concepts/app-overview#collection-detail) page/modal, and can also be used for sorting items within
a [Junction Table](#).
[Collection Detail](/concepts/application/#collection-detail) page/modal, and can also be used for sorting items within
a [Junction Table](/concepts/relationships/#many-to-many-m2m).
::: tip Sort Field
::: tip Automatic Setup
When creating a new Collection, you have the option of creating an optional "Sort" field. If you choose to include this
field, the collection's sort settings will automatically be configured for you.
@@ -112,3 +105,15 @@ field, the collection's sort settings will automatically be configured for you.
This action is permanent and can not be undone. Please proceed with caution.
:::
## Adjusting a Collection Layout
1. Navigate to **Collections > [Collection Name]**
2. Click **"Layout Options"** in the Page Sidebar
3. **Configure the Layout Options** as desired
::: tip User Preferences
Any changes made to the Collection Layout Options, page filters, search queries, and advanced filters, are instantly saved to your user preferences. This means that your experience will be the same when logging later, even if using a different device.
:::

5
docs/guides/configuring-the-api.md
View File

@@ -1,5 +0,0 @@
# Configuring the API
> TK
@TODO Environment Variables

0
docs/extensions/custom-migrations.md → docs/guides/custom-migrations.md
View File

15
docs/extensions/displays.md → docs/guides/displays.md
View File

@@ -1,6 +1,6 @@
# Create a Custom Display
# Custom Displays <small></small>
> Custom displays allow you to create new ways of viewing field values inline throughout the App.
> Displays are small inline components that allow you to create new ways of viewing field values throughout the App. [Learn more about Displays](/concepts/displays/).
## 1. Setup the Boilerplate
@@ -33,11 +33,14 @@ export default {
- `description` — A short description (<80 characters) of this display shown in the App.
- `icon` — An icon name from the material icon set, or the extended list of Directus custom icons.
- `handler` — A function, or reference to your Vue component.
- `types` — A CSV of supported [types](/concepts/platform-overview#types).
- `types` — A CSV of supported [types](/concepts/types/).
::: tip See
[the TypeScript definition](https://github.com/directus/directus/blob/20355fee5eba514dd75565f60269311187010c66/app/src/displays/types.ts#L24-L34)
for more info on what can go into this object. :::
::: tip
[See the TypeScript definition](https://github.com/directus/directus/blob/20355fee5eba514dd75565f60269311187010c66/app/src/displays/types.ts#L24-L34)
for more info on what can go into this object.
:::
### src/display.vue

16
docs/guides/fields.md
View File

@@ -1,8 +1,6 @@
# Fields
> You can manage your fields within the Data Model section of the App's Settings, via the
> [API Fields Endpoint](/reference/api/fields), or directly within the database. If you're unfamiliar with Directus
> Fields, please start by reading our [Understanding Fields](/concepts/data-model) docs.
> Fields are a specific type of value within a Collection, storing the data of your item's content. Each field represents a **column** in your database. [Learn more about Fields](/concepts/fields/).
## Creating a Field
@@ -18,6 +16,12 @@
- [Many-to-Any Field](/guides/field-types/many-to-any-field)
- [Translated Fields](/guides/field-types/translated-fields)
::: tip System Fields
While all out-of-the-box system fields are locked from editing or deleting, you are able to create new fields within the system collections. You can enable editing System Collections within the Collection sidebar component of [Settings > Data Model](/concepts/databases/).
:::
::: tip Database Fields
Keep in mind that a Directus Field is just a database column. Therefore you can import or create a column directly in
@@ -42,7 +46,7 @@ the database, and it will automatically appear within Directus. The first time y
::: tip
Learn more about the field options for [Adjusting the Field Layout](#adjusting-field-layout).
Learn more about the field options for [Adjusting the Field Layout](#adjusting-field-arrangement).
:::
@@ -58,9 +62,9 @@ It is not currently possible to duplicate relational fields or a collection's pr
:::
## Adjusting Field Layout
## Adjusting Field Arrangement
The layout of the collection's form is determined by the following field options.
The form design of the collection's fields is determined by the following options.
- **Field Visibility** — If the field is "Visible" or "Hidden"
- **Field Width** — How wide the field is shown relative to the form/page

104
docs/guides/files.md
View File

@@ -1,33 +1,21 @@
# Files & Thumbnails
# Files
> Directus offers a full-featured Digital Asset Management (DAM) system, multiple storage adapters, private file
> permissions, and on-demand image thumbnail generation.
> Directus includes a full-featured Digital Asset Management (DAM) system, complete with different Storage Adapters.
> [Learn more about Files](/concepts/files/).
## Uploading a File
@TODO
There are many ways that a file can be uploaded into Directus via the App. We'll cover the primary method below, but
keep in mind that files can also be added directly through different interfaces.
## Accessing an Original File
1. Navigate to the **File Library**
2. Click on the **"Create Item"** (+ icon) button located in the header
3. **Upload** the file by:
- Dragging a file from your desktop to the modal
- Click the modal area to manually select a file from your device
- Clicking the "..." icon and choosing "Import from URL"
The location of your actual file originals is based on the project's configuration, but you can consistently access them
via the API using the following URL.
```
example.com/assets/<file-id>
example.com/assets/1ac73658-8b62-4dea-b6da-529fbc9d01a4
```
![Original File](../assets/original.jpg) _Original File Used Below — 602KB and 1800x1200_
::: warning Direct File Access
While you may _technically_ be able to access your original files within their actual filesystem directory (eg:
`/uploads/<filename_disk>` for the default local storage configuration), it is recommended that you always use the
Directus API. This is the only way that you can take advantage of file permissions and other built-in features.
:::
## Creating Thumbnail Presets
## Creating a Thumbnail Preset
1. Navigate to **Settings > Project Settings**
2. Scroll to the **Storage Asset Presets** field
@@ -36,72 +24,14 @@ Directus API. This is the only way that you can take advantage of file permissio
5. Enter the **Fit**, **Width**, **Height**, and **Quality** for the preset
6. Click the **Save** action button in the header
### Storage Asset Transform
## Downloading an Original File
The **Storage Asset Transform** can be used in conjunction with the presets to force an allow-list or completely disable
the thumbnailing system. The options for this are:
- **All** — Any valid thumbnail request will be returned
- **None** — No thumbnails will be returned, not even presets
- **Presets Only** — Only valid Storage Asset Presets will be returned
TK (download button)
## Requesting a Thumbnail
Fetching thumbnails is as easy as adding query parameters to the original file's URL. If a requested thumbnail doesn't
yet exist, it is dynamically generated and immediately returned. When requesting a thumbnail, the following parameters
are all required.
TK
- **`fit`** — The **fit** of the thumbnail while always preserving the aspect ratio, can be any of the following
options:
- `cover` — Covers both width/height by cropping/clipping to fit
- `contain` — Contain within both width/height using "letterboxing" as needed
- `inside` — Resize to be as large as possible, ensuring dimensions are less than or equal to the requested width and
height
- `outside` — Resize to be as small as possible, ensuring dimensions are greater than or equal to the requested width
and height
- **`width`** — The **width** of the thumbnail in pixels
- **`height`** — The **height** of the thumbnail in pixels
- **`quality`** — The **quality** of the thumbnail (`0` to `100`)
- **`withoutEnlargement`** — Disable image up-scaling
- **`download`** — Add `Content-Disposition` header and force browser to download file
## Editing Images
```
example.com/assets/<file-id>?fit=<fit>&width=<width>&height=<height>&quality=<quality>
example.com/assets/1ac73658-8b62-4dea-b6da-529fbc9d01a4?fit=cover&width=200&height=200&quality=80
```
Alternatively, you can reference a specific thumbnail by its preset key.
- **`key`** — This **key** of the [Storage Asset Preset](/guides/files#creating-thumbnail-presets), a shortcut for the
above parameters
```
example.com/assets/<file-id>?key=<preset-key>
example.com/assets/1ac73658-8b62-4dea-b6da-529fbc9d01a4?key=card
```
### Cover vs Contain
For easier comparison, both of the examples below were requested at `200` width, `200` height, and `75` quality. The
`cover` thumbnail forces the dimensions, trimming the outside edges as needed. The `contain` thumbnail always maintains
its aspect ratio, shrinking the image to fit _within_ the dimensions and adding "letterboxing" as needed.
| Cover | Contain |
| ----------------------------------------------------------- | --------------------------------------------------------------- |
| ![Cover](../assets/200-200-cover-75.jpg)<br>_8KB • 200x200_ | ![Contain](../assets/200-200-contain-75.jpg)<br>_6KB • 200x133_ |
::: tip Aspect Ratio
Images are never stretched or distorted even when changing the aspect ratio.
:::
### Quality vs Filesize
The quality parameter can be any integer from `0-100`. Qualities closer to `0` have lower filesizes, but also poor image
quality due to compression artifacts. Values closer to `100` have larger filesizes, but better image quality. Below are
four possible qualities (200x200 cover) to visually compare the balance between compression and filesize.
| 25% | 50% | 75% | 100% |
| ----------------------------------------------- | ----------------------------------------------- | ----------------------------------------------- | -------------------------------------------------- |
| ![25%](../assets/200-200-cover-25.jpg)<br>_4KB_ | ![50%](../assets/200-200-cover-50.jpg)<br>_6KB_ | ![75%](../assets/200-200-cover-75.jpg)<br>_8KB_ | ![100%](../assets/200-200-cover-100.jpg)<br>_38KB_ |
TK (image editor on file detail page?)

37
docs/guides/installation/cli.md
View File

@@ -1,20 +1,10 @@
# Installing from CLI
> A command line interface (CLI) is a text-based user interface (UI) used to view and manage computer files. Common CLI
> clients are [Windows Terminal](https://en.wikipedia.org/wiki/Windows_Terminal) and
> [MacOS Terminal](<https://en.wikipedia.org/wiki/Terminal_(macOS)>).
> [Learn More about CLI](/reference/command-line-interface)
## 1. Confirm Minimum Requirements
## 1. Confirm the Minimum Requirements are met
**The only language or script requirement for Directus is an actively maintained version of
[Node.js](https://nodejs.org/en/about/releases/).** Currently that is v10+, however in April 2021, node v10 will leave
_Maintenance Long-Term Support (LTS)_ status, and node v12+ will become the new minimum requirement.
### Databases
Directus currently supports the following databases, with our minimum version being based on each vendor's official
support/LTS.
Directus requires two things to run: [Node.js](https://nodejs.dev) and a Database. For both these system requirements,
we aim to support the current LTS release (and newer). At the time of writing (early 2021), this means Node.js v10+ and
one of the following:
| Database | Version |
| ------------- | ------- |
@@ -22,13 +12,13 @@ support/LTS.
| MySQL | 5.7.8+ |
| SQLite | 3+ |
| MS-SQL Server | 13.0+ |
| OracleDB | TBD |
| OracleDB | 19+ |
| MariaDB | 10.2+ |
::: tip
::: tip Variants
Variants In addition to the databases above, other variants are also supported, including **AWS Aurora** (MySQL), and
**AWS Redshift** (PostgreSQL).
In addition to the databases above, other variants are also supported, including **AWS Aurora** (MySQL), **AWS
Redshift** (PostgreSQL), and **MariaDB**.
:::
@@ -41,8 +31,6 @@ inside the current directory. Create a new Directus project by running the follo
npx create-directus-project my-project
```
_my-project_ will also be the name of the new Directus project directory.
::: warning
Except for SQLite, the database must already be running before creating your Directus project.
@@ -65,10 +53,5 @@ npx directus start
## 4. View your Project
The default port used by Directus is 8055. To view your project locally, enter `http://localhost:8055` in your browser.
::: tip
You can confirm the port by looking for the message in your _terminal_ or _cli client_: **Server started at port 8055**
:::
The default port used by Directus is 8055. To view your project locally, go to
[http://localhost:8055](http://localhost:8055) in your browser.

20
docs/guides/installation/digitalocean-app-platform.md
View File

@@ -2,17 +2,21 @@
## 1. Setup a repo on GitHub
See the doc on [installing Directus manually](/guides/installation/manual) to learn how to configure this repo
See the doc on [installing Directus manually](/guides/installation/manual) to learn how to configure this repo.
## 2. Create a Managed Database instance
## 2. Sign up for a DigitalOcean account
Create your DigitalOcean account — [get $100 of free credit](https://m.do.co/c/4c0b6062c16e) by using our referral link.
## 3. Create a Managed Database instance
We recommend using Postgres 12. The exact size and need for a replica depends on your usage and project requirements.
## 3. Create a new App using your previously created repo
## 4. Create a new App using your previously created repo
Make sure to select the database you created in step 2 during the configuration wizard.
## 4. Configure the environment variables
## 5. Configure the environment variables
See [Environment Variables](/reference/environment-variables) for all available environment variables.
@@ -30,11 +34,3 @@ DB_SSL__CA=${my-database-component-name.CA_CERT}
Make sure to replace `my-database-component-name` with your actual database component name in the above env vars
:::
::: tip
For ease of configuration, you can rely on any of the other DigitalOcean provided aliases. See
[How to Use Environment Variables in App Platform](https://www.digitalocean.com/docs/app-platform/how-to/use-environment-variables/)
for more information.
:::

17
docs/guides/installation/digitalocean-one-click.md
View File

@@ -1,17 +0,0 @@
# DigitalOcean One-Click Install
## 1. Navigate to Directus on the DigitalOcean Marketplace
The [Directus page can be found here](https://marketplace.digitalocean.com/apps/directus), or you can browse for
Directus within the [entire marketplace](https://marketplace.digitalocean.com/).
## 2. Click on "Create Directus Droplet"
## 3. Follow the prompts
::: warning Paid Service
This is a paid service, so while Directus is completely free and open-source, you will likely need to enter a payment
method, and may incur charges.
:::

2
docs/guides/installation/docker.md
View File

@@ -82,7 +82,7 @@ services:
CACHE_REDIS: 'redis://cache:6379'
ADMIN_EMAIL: 'admin@example.com'
ADMIN_PASSWORD: 'password'
ADMIN_PASSWORD: 'd1r3ctu5'
networks:
directus:

22
docs/guides/installation/manual.md
View File

@@ -9,7 +9,7 @@ We've created a little CLI tool you can run that does this process automatically
## 1. Setup a Project Folder
And add a `package.json` by running the following command.
Create a new directory, and add a `package.json` by running the following command.
```bash
npm init -y
@@ -20,9 +20,11 @@ We recommend aliasing the `start` script to Directus' start for easier deploymen
```json
{
...
"scripts": {
"start": "directus start"
}
...
}
```
@@ -32,22 +34,12 @@ We recommend aliasing the `start` script to Directus' start for easier deploymen
npm install directus
```
## 3. Install one of the Database Drivers
Choose the [database vendor](/guides/installation/cli#databases) you will be working with, and install its driver.
```bash
npm install pg
```
## 4. Install Optional Dependencies
At this point you have the option of installing other dependencies. If you're planning on utilizing Redis/Memcached,
make sure to install `ioredis`/`memcached` respectively.
## 5. Setup a Configuration File
## 3. Setup a Configuration File
Finally, you'll need to setup your `.env` file, or configure the environment variables through other means, such as
Docker, etc.
You can use a copy of [the `example.env` file](https://github.com/directus/directus/blob/main/api/example.env) as a
starting point.
See [Environment Variables](/reference/environment-variables) for all available variables.

14
docs/guides/installation/platformsh-one-click.md
View File

@@ -1,14 +0,0 @@
# Platform.sh One-Click Install
## 1. Click the Install Link
As the name suggests, simply click on this direct link to:
[Install Directus on Platform.sh](https://console.platform.sh/projects/create-project?template=https%3A%2F%2Fraw.githubusercontent.com%2Fplatformsh%2Ftemplate-builder%2Fmaster%2Ftemplates%2Fdirectus%2F.platform.template.yaml)
... or manually browse for "Directus" on the [Platform.sh Marketplace](https://platform.sh/marketplace/).
::: warning Paid Service
This is a paid service, so while Directus is completely free and open-source, you will likely need to enter a payment
method, and may incur charges.
:::

1
docs/guides/installation/readme.md
View File

@@ -1 +0,0 @@
# Installation

6
docs/guides/installation/ubuntu.md Normal file
View File

@@ -0,0 +1,6 @@
# Ubuntu
DigitalOcean provides a great tutorial on how to run a Node.js based app in production. See
[How To Set Up a Node.js Application for Production on Ubuntu 20.04](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-node-js-application-for-production-on-ubuntu-20-04).
Instead of starting the app using `pm2 start hello.js`, you can start Directus using `pm2 start npm -- start`

6
docs/extensions/interfaces.md → docs/guides/interfaces.md
View File

@@ -1,6 +1,6 @@
# Create a Custom Interface
# Custom Interfaces <small></small>
> Custom interfaces allow you to create new ways of viewing or interacting with data on the Item Detail page.
> Custom Interfaces allow you to create new ways of viewing or interacting with field data on the Item Detail page. [Learn more about Interfaces](/concepts/interfaces/).
## 1. Setup the Boilerplate
@@ -33,7 +33,7 @@ export default {
- `description` — A short description (<80 characters) of this interface shown in the App.
- `icon` — An icon name from the material icon set, or the extended list of Directus custom icons.
- `component` — A reference to your Vue component.
- `types` — A CSV of supported [types](/concepts/platform-overview#types).
- `types` — A CSV of supported [types](/concepts/types/).
::: tip TypeScript

105
docs/guides/items.md
View File

@@ -1,25 +1,16 @@
# Items
> You can browse and manage items from within the App, via the [API Items Endpoint](/reference/api/items), or directly
> within the database. If you're unfamiliar with Directus Items, please start by reading our
> [Understanding Items](/concepts/platform-overview#items) docs.
## Managing Items
Managing items includes the basics of Create, Read, Update, and Delete — as well as more specific features such as
Archiving, Reverting, Commenting, and Reordering. Each of the guides below also includes a link to any relevant
concepts.
> Item are objects within a Collection which contain values for one or more fields. Each collection represents a **record** in your database. [Learn more about Items](/concepts/items/).
::: warning Permissions
All of the action on this page assume that the current user has permission to perform the action. If they do not, then
certain buttons or features may be disabled or altogether hidden.
The actions on this page assume the current user has permission to perform that action. However, certain features may be disabled or hidden based on permissions.
:::
### Creating Items
## Creating an Item
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection where you want to add an item
3. Click on the "Create Item" (+ icon) button located in the header
4. Complete the Item Detail form
@@ -32,14 +23,24 @@ If the Collection is configured as a "Singleton" in the data model settings, the
:::
### Updating Items
## Updating an Item
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the item you want to update
3. Click on the item within the desired layout (eg: on the row of the table)
3. Click on the item within the current layout (eg: on the row of the table)
4. Update the Item Detail form
5. Click the "Save Item" (✓ icon) button located in the header
::: tip Other Save Options
To the right of the primary Save button there is a "..." icon which contains the following alternate save options:
* Save and Stay (⌘S)
* Save and Create New (⌘⇧S)
* Save as Copy
:::
::: tip Singletons
If the Collection is configured as a "Singleton" in the data model settings, then the App will automatically skip step
@@ -47,9 +48,9 @@ If the Collection is configured as a "Singleton" in the data model settings, the
:::
### Deleting Items
## Deleting an Item
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the item you want to delete
3. Select the item(s) within the desired layout (eg: the checkbox on the table row)
4. Click the "Delete Item" (trash icon) button located in the header
@@ -62,9 +63,9 @@ icon) button located in the header.
:::
### Archiving an Item
## Archiving an Item
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the item you want to archive
3. Select the item(s) within the desired layout (eg: the checkbox on the table row)
4. Click the "Archive Item" (trash icon) button located in the header
@@ -83,9 +84,9 @@ icon) button located in the header.
:::
### Reverting Items
## Reverting an Item
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the item you want to archive
3. Click on an item to navigate to its Detail page
4. Click "Revisions" in the page sidebar
@@ -93,24 +94,24 @@ icon) button located in the header.
6. Click on the "Revert" button located in the drawer's header
7. Confirm the action within the dialog by clicking "Revert"
### Commenting on Items
## Commenting on an Item
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the item you want to comment on
3. Click on an item to navigate to its Detail page
4. Click "Comments" in the page sidebar
5. Type your message within the input
6. Click the "Submit" button
### Reordering Items
## Manually Sorting Items
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
2. Navigate to the collection of the items you want to reorder
3. Choose a layout that supports reordering (eg: the default "table" mode)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the items you want to sort
3. Choose a layout that supports manual sorting (eg: the default "table" mode)
4. Enable manual sorting. (eg: for the table layout, click on the Sort column's header)
5. Drag items by their handle into a new position
The new order is saved automatically, so make sure you wait until the App's loading indicator finishes before navigating
The new sort order is saved automatically, so make sure you wait until the App's loading indicator finishes before navigating
away from the page.
::: warning Requires Configuration
@@ -119,34 +120,44 @@ This feature is only available if a Sort column has been configured in the Colle
:::
## Browsing Items
## Ordering Items
In order to view, update or delete a specific item, you first need to be able to find it. Directus includes a number of
features to make browsing items as fast and efficient as possible, each of which are described below.
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to a collection of items
3. Choose a layout that supports manual ordering (eg: the default "table" mode)
4. Set the Order Field and Order Direction
* Table Layout: Click on the field's column header, clicking again changes order direction
* Card Layout: Adjust the two dropdowns in the layout's subheader
### Adjusting Item Layouts
::: tip Sort vs Order
**[Learn more about the concept of layouts.](#)**
**Ordering** is a non-destructive action (does _not_ change your data) used to browse items alphabetically or numerically. **Sorting** (when enabled) saves a value in a [Sort](/guides/collections/#sort) field, which can then be used to return data in a custom order.
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
:::
## Adjusting Item Layouts
**[Learn more about Layouts](/concepts/layouts/)**
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the items you want to browse
3. Click "Layout Options" in the page sidebar
4. Choose the desired "Layout" you want to use
5. Configure any other layout options that come after the layout dropdown
### Searching Items
## Searching Items
**[Learn more about the concept of search.](#)**
**[Learn more about Search](/guides/items/#searching-items)**
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the items you want to search
3. Type your search query into the input located in the header
### Filtering Items
## Filtering Items
**[Learn more about the concept of filtering.](#)**
**[Learn more about Filtering](/guides/items/#filtering-items).**
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the items you want to filter
3. Click "Advanced Filter" in the page sidebar
4. Click the "Add Filter" dropdown and select the field to filter on
@@ -154,22 +165,22 @@ features to make browsing items as fast and efficient as possible, each of which
6. Enter a value in the field filter's input(s)
7. Remove unwanted filters by hovering over the field and clicking "X"
### Bookmarking Item Presets
## Bookmarking Item Presets
**[Learn more about the concept of bookmarks.](#)**
**[Learn more about Bookmarks](/guides/items/#bookmarking-item-presets)**
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the items you want to bookmark
3. Configure the page as desired (eg: layout, options, search, filters, order, etc)
4. Click the "Create Bookmark" (bookmark icon) button in the header beside the page title
5. Rename bookmarks by right-clicking them in the navigation sidebar and selecting "Rename Bookmark"
6. Delete bookmarks by right-clicking them in the navigation sidebar and selecting "Delete Bookmark"
### Exporting Items
## Exporting Items
**[Learn more about the concept of exporting.](#)**
**[Learn more about Exporting](guides/items/#exporting-items)**
1. Navigate to the [Collections Module](/concepts/app-overview#collections)
1. Navigate to the [Collections Module](/concepts/application/#collections)
2. Navigate to the collection of the items you want to bookmark
3. Optional: Configure the dataset as desired (eg: layout, options, search, filters, order, etc)
4. Click "Export Data" in the page sidebar

4
docs/extensions/layouts.md → docs/guides/layouts.md
View File

@@ -1,6 +1,6 @@
# Create a Custom Layout
# Custom Layouts <small></small>
> Custom layouts allow you to create new ways of browsing or viewing data on the Collection Detail page.
> Custom Layouts allow for building new ways to view or interact with Items via the Collection Detail pages. [Learn more about Layouts](/concept/layouts/).
## 1. Setup the Boilerplate

4
docs/extensions/modules.md → docs/guides/modules.md
View File

@@ -1,6 +1,6 @@
# Create a Custom Module
# Custom Modules <small></small>
> Custom modules allow you to create completely new experiences within the platform.
> Custom Modules are completely open-ended components that allow you to create new experiences within the Directus platform. [Learn more about Modules](/concepts/modules/).
## 1. Setup the Boilerplate

3
docs/guides/oauth.md Normal file
View File

@@ -0,0 +1,3 @@
# Configuring SSO through oAuth
tk

85
docs/guides/permissions.md Normal file
View File

@@ -0,0 +1,85 @@
# Permissions
> Permissions are attached directly to a Role, defining what Users can create, read, update, and delete within the platform. [Learn more about Permissions](/concepts/permissions/).
## Configuring Role Permissions
Directus possesses an extremely granular, yet easy to configure, permissions system. When creating a new role,
permissions are disabled for all project collections by default — allowing you to give explicit access to only what is
required. Individual permissions are applied to the role, and each is scoped to a specific collection and CRUD action
(create, read, update, delete).
::: warning Saves Automatically
Every change made to the permissions of a role is saved automatically and instantly.
:::
::: warning Admin Roles
If a role is set to **Admin Access** then it is granted complete access to the platform, and therefore the permission
configuration field is disabled.
:::
1. Navigate to **Settings > Roles & Permissions > [Role Name]**
2. Scroll to the **Permissions** section
3. **Click the icon** for the collection (row) and action (column) you want to set
4. Choose the desired permission level: **All Access**, **No Access**, or **Use Custom**
**If you selected "All Access" or "No Access" then setup is complete.** If you chose to customize permissions then continue with the appropriate guide below based on the relevant _action_.
### Create (Custom Access)
5. **Field Permissions** control which fields accept a value on create. Fields are individually toggled.
6. **Field Validation** define the rules for field values on create
7. **Field Presets** control the field defaults when creating an item
### Read (Custom Access)
5. **Item Permissions** control which items can be read, as defined by the [Filter Rules](/reference/filter-rules)
entered.
6. **Field Permissions** control which fields can be read. Fields are individually toggled.
### Update (Custom Access)
5. **Item Permissions** control which items can be updated, as defined by the [Filter Rules](/reference/filter-rules))
entered.
6. **Field Permissions** control which fields can be updated. Fields are individually toggled.
7. **Field Validation** define the rules for field values on update, as defined by the
[Filter Rules](/reference/filter-rules) entered.
8. **Field Presets** control the field defaults when updating an item
### Delete (Custom Access)
5. **Item Permissions** control which items can be deleted, as defined by the [Filter Rules](/reference/filter-rules/))
entered.
## Configuring Workflows
Workflows are a way to add structured stages to the flow of content authoring. They are primarily defined through the permissions for a Collection, but can be further enhanced via email notifications, custom interfaces, and automation. Directus supports endlessly configurable workflows, so we will only cover one example below.
Let's assume you would like to create a structured workflow for an **Articles** collection. The first step is to [Create a Field](/guides/fields/#creating-a-field) that can track the article "status" — we'll call it **Status**, but it can be named anything.
Now you can configure your permissions based on the possible values of that Status field. In this case, those values will be various content stages, such as `draft`, `review`, `approved`, and `published`.
Next, you will want to create different Roles to scope each stage of the workflow. Let's keep this simple and assume there are only two roles called `author` and `manager`.
Finally, we would configure the permissions for these roles such that they are properly restricted to create content and update the status.
<!-- @TODO -->
## Configuring System Permissions
In addition to setting permissions for your project's collections, you can also tailor the permissions for system
collections. It is important to note that when [App Access](/guides/roles/#configuring-a-role) is enabled for a
role, Directus will automatically add permission for the necessary system collections. To edit system permissions,
simply click the "System Collections" toggle, and then edit permissions using the same steps as with project
collections.
::: tip Resetting System Permissions
To reset the role's system permissions for proper App access, expand the system collections and then click "Reset System
Permissions" at the bottom of the listing.
:::

5
docs/guides/presets.md
View File

@@ -1,7 +1,6 @@
# Collection Presets
> Presets store the exact state of a [collection detail](/concepts/app-overview) page. These can be used to set layout
> defaults for a user, or to define bookmarks that can be used to recall windows into specific datasets.
> Presets store the state of a Collection Detail page. They can be used to set layout defaults or define bookmarks to specific datasets. [Learn more about Presets](/concepts/presets/).
## Creating a Preset
@@ -26,7 +25,7 @@ search query, any advanced filters added, sort field, sort direction, and all ot
It's important to be aware of the difference between a collection's _defaults_ and its _bookmarks_, both of which are
configured by presets. A _default_ is how a user will initially view the collection detail without any further
customization, while a _bookmark_ is a named dataset that can be recalled at any point via the
[collection navigation](/concepts/users-roles-and-permissions).
[collection navigation](/guides/roles/#customizing-the-collection-navigation).
:::

64
docs/guides/projects.md
View File

@@ -1,7 +1,6 @@
# Projects
> Every installation of Directus creates a single project. If you're unfamiliar with Directus Projects, please start by
> reading our [Platform Overview](/concepts/platform-overview).
> A Project is a complete instance of Directus, including its **Database**, config file, asset storage, and any custom extensions. [Learn more about Projects](/concepts/projects/).
## Creating a Project
@@ -18,6 +17,55 @@ environment variables, each is explained in the following reference:
- [Environment Variables](/reference/environment-variables)
## Adjusting Project Settings
1. Navigate to **Settings > Project Settings**
2. Configure any of the following **branding fields**
- **Project Name** — The name used at the top of the [Navigation Bar](/concepts/applications) and on the login/public
pages
- **Project URL** — The URL when clicking the logo at the top of the [Module Bar](/concepts/app-overview)
- **Project Color** — The color used behind the logo at the top of the [Module Bar](/concepts/app-overview), on the
login/public pages, and for the browser's FavIcon
- **Project Logo** — A 40x40 pixel logo at the top of the [Module Bar](/concepts/app-overview) and on the login/public
pages. The image is _inset_ within the 64x64 pixel square filled with the Project Color, so we recommend using a SVG
or PNG logo with transparency to avoid a "boxy" look.
::: tip Browser FavIcon & Title
The Project Color and Logo are also used to set a dynamic favicon, and the Project Name is used in the browser's page
title. This makes it easier to identify different Directus projects in the browser.
:::
### Public Pages
In addition to the above global Project Settings, you can also apply the following styling to tailor your project's
[public pages](/concepts/app-overview).
- **Public Foreground** — An image centered in the public page's right-pane. Limited to a maximum width of 400px.
- **Public Background** — An image displayed behind the above foreground image, shown full-bleed within the public
page's right-pane. When a Public Background image is not set, the Project Color is used instead.
- **Public Note** — A helpful note displayed at the bottom of the public page's right-pane; supports markdown for
rich-text formatting
### Security
- **Auth Password Policy** — Allows setting a policy requirement for all user's passwords, with the following options:
- None — Not recommended
- Weak — Minimum of 8 characters
- Strong — Uppercase, lowercase, numbers, and special characters
- **Auth Login Attempts** — Sets the number of failed login attempts allowed before a user's account is locked. Once
locked, an Admin user is required to unlock the account.
### Files & Thumbnails
See [Creating a Thumbnail Preset](/guides/files/#creating-a-thumbnail-preset)
### App Overrides
See [Styles > Custom CSS](/guides/styles/#custom-css)
## Upgrading a Project
1. Backup your project
@@ -30,6 +78,18 @@ environment variables, each is explained in the following reference:
2. Make a copy of the **Env file** (`/api/.env`), and store it in a safe place
3. Run the **Backup API Endpoint** (`/backup`) to create a SQL dump of your database
## Migrating a Project
Directus doesn't rely on anything besides the database for it's operation. Therefore, migrating your Directus project
can be done by moving the whole database to a new location using a database dump.
::: tip File Storage
If you have files uploaded, make sure to copy those over as well, or use the same storage location in the new location
of Directus.
:::
## Deleting a Project
1. Optional: **Backup any local files** stored within the project's root directory

75
docs/guides/roles-and-permissions.md → docs/guides/roles.md
View File

@@ -1,7 +1,6 @@
# Roles & Permissions
# Roles
> During installation, Directus automatically includes an initial "Admin" role with complete project access. After that,
> you are free to extend and customize these as much as is needed.
> Roles define a specific set of access permissions, and are the primary organizational structure for Users within the platform. [Learn more about Roles](#).
## Creating a Role
@@ -98,76 +97,6 @@ unlabeled group.
7. Choose a **Collection** from the dropdown
8. Use the drag handles to **drag-and-drop** the groups/collections into the desired order
## Configuring Role Permissions
Directus possesses an extremely granular, yet easy to configure, permissions system. When creating a new role,
permissions are disabled for all project collections by default — allowing you to give explicit access to only what is
required. Individual permissions are applied to the role, and each is scoped to a specific collection and CRUD action
(create, read, update, delete).
::: warning Saves Automatically
Every change made to the permissions of a role is saved automatically and instantly.
:::
::: warning Admin Roles
If a role is set to **Admin Access** then it is granted complete access to the platform, and therefore the permission
configuration field is disabled.
:::
1. Navigate to **Settings > Roles & Permissions > [Role Name]**
2. Scroll to the **Permissions** section
3. **Click the icon** for the collection (row) and action (column) you want to set
4. Choose the desired permission level: **All Access**, **No Access**, or **Use Custom**
If you selected _All Access_ or _No Access_ then setup is complete. If you chose to customize the permissions, then a
modal will open with additional configuration options. Continue with the appropriate guide below based on the _action_
of the permission.
#### Create (Custom)
5. **Field Permissions** control which fields accept a value on create. Fields are individually toggled.
6. **Field Validation** define the rules for field values on create
7. **Field Presets** control the field defaults when creating an item
#### Read (Custom)
5. **Item Permissions** control which items can be read, as defined by the [Filter Rules](/reference/filter-rules)
entered.
6. **Field Permissions** control which fields can be read. Fields are individually toggled.
#### Update (Custom)
5. **Item Permissions** control which items can be updated, as defined by the [Filter Rules](/reference/filter-rules))
entered.
6. **Field Permissions** control which fields can be updated. Fields are individually toggled.
7. **Field Validation** define the rules for field values on update, as defined by the
[Filter Rules](/reference/filter-rules) entered.
8. **Field Presets** control the field defaults when updating an item
#### Delete (Custom)
5. **Item Permissions** control which items can be deleted, as defined by the [Filter Rules](/reference/filter-rules))
entered.
## Configuring System Permissions
In addition to setting permissions for your project's collections, you can also tailor the permissions for system
collections. It is important to note that when [App Access](/concepts/users-roles-and-permissions) is enabled for a
role, Directus will automatically add permission for the necessary system collections. To edit system permissions,
simply click the "System Collections" toggle, and then edit permissions using the same steps as with project
collections.
::: tip Resetting System Permissions
To reset the role's system permissions for proper App access, expand the system collections and then click "Reset System
Permissions" at the bottom of the listing.
:::
## Deleting a Role
1. Navigate to **Settings > Roles & Permissions > [Role Name]**

15
docs/guides/setup/caddy.md
View File

@@ -1,15 +0,0 @@
# Caddy Setup Guide
Run
```bash
caddy reverse-proxy --to 127.0.0.1:8055
```
or setup a caddy file with the following contents:
```
localhost
reverse_proxy 127.0.0.1:8055
```

17
docs/guides/setup/nginx.md
View File

@@ -1,17 +0,0 @@
# Nginx Setup Guide
You can configure `/etc/nginx/sites-available/default` with the following config to use it as a reverse proxy to
Directus:
```
. . .
location / {
proxy_pass http://localhost:8055;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
```

49
docs/guides/styles.md Normal file
View File

@@ -0,0 +1,49 @@
# Styles
> **Form Follows Function** is the guiding design principle of Directus. The minimal UI allows the platform to be easily tailored to your brand. [Learn more about the App](#).
## App Themes
The Directus App has been developed with customization and extensibility in mind. Colors and styles referenced within the codebase all use CSS variables, and therefore it is easy to make comprehensive changes to the App styling.
There are two themes included by default: Light and Dark. You can duplicate these files to create your own themes — with no limit to customization. Below are several code resources for key SCSS files.
- **Themes** — See the [Light Theme](https://github.com/directus/directus/blob/main/app/src/styles/themes/_light.scss)
or [Dark Theme](https://github.com/directus/directus/blob/main/app/src/styles/themes/_dark.scss)
- **Typography** — See the [Fonts](https://github.com/directus/directus/blob/main/app/src/styles/_type-styles.scss) and
[Type Styles](https://github.com/directus/directus/blob/main/app/src/styles/mixins/type-styles.scss)
- **Variables** — See the
[Global Variables](https://github.com/directus/directus/blob/main/app/src/styles/_variables.scss)
## Project Styling
See [Adjusting Project Settings](/guides/projects/#adjusting-project-settings)
## Custom CSS
You can also override any core CSS directly within the App through Project Settings. This makes it easy to edit the CSS variables listed in the themes above.
1. Navigate to **Settings > Project Settings**
2. Scroll to the **CSS Overrides** field
3. Enter any **valid CSS**
4. Click the **Save** action button in the header
### Example
Since App styles are inserted/removed whenever a component is rendered, you'll need to be aware of CSS priority. Using `:root` or `body` likely isn't scoped enough, you'll need to define a more specific scope, such as `#app`, or use `!important`.
```css
#app {
--family-sans-serif: 'Comic Sans MS';
}
```
::: warning Action Styling
The `--primary` variable (and its shades) control call-to-actions and all other elements within the App using the "Directus Blue". While it may be tempting to override this variable with your brand's color, please first review the following warnings:
- Avoid using yellow, orange, or red hues that give a sense of "danger"
- Avoid low-contrast colors like yellows, grays, etc, that might not be easily visible
- Avoid low-saturation colors like black, which might not properly highlight CTAs
:::

19
docs/guides/users.md
View File

@@ -1,11 +1,6 @@
# Users
> You are prompted to enter the details of your first admin user during the installation process. After that, you are
> free to create as many users as you'd like. There is no limit to the number of users in a project.
## Setting up your User Profile
@TODO
> Users are the individual accounts for authenticating into the API and App. Each user belongs to a Role which defines its Permissions. [Learn more about Users](#).
## Creating a User
@@ -28,8 +23,8 @@ their account.
## Configuring a User
1. Navigate to the **User Library**
2. Click on the user you wish to manage
3. Complete any of the [User Fields](/concepts/app-overview.md#user-detail)
2. **Click on the user** you wish to manage
3. **Complete the form** of [User Fields](/concepts/app-overview.md#user-detail)
::: warning User Preferences
@@ -37,7 +32,9 @@ This section of the User Detail is only visible/editable by the current user, an
:::
### Status
#### Status
The User's Status determines if an account is able to access the platform or not. Only the `active` state is able to authenticate, all others are simply descriptive inactive states.
- **Draft** — An incomplete user; no App/API access
- **Invited** — Has a pending invite to the project; no App/API access until accepted
@@ -51,7 +48,7 @@ Only admins can adjust this field's value.
:::
### Role
#### Role
Setting the user's role determines their access, permissions, and App presentation. You can adjust a user's role from
the User Detail page, or from the _Users in Role_ field within **Settings > Roles & Permissions > [Role Name]**.
@@ -62,7 +59,7 @@ Only admins can adjust this field's value.
:::
### Token
#### Token
A user's token is an alternate way to [authenticate into the API](/reference/api/authentication) using a static string.
When NULL, the token is disabled. When enabled, ensure that a secure string is used.

4
docs/guides/webhooks.md
View File

@@ -1,8 +1,6 @@
# Webhooks
> In addition to writing custom code for more complex [event hooks](/concepts/api-extensions), Directus provides a way
> to quickly configure webhooks through the App. These send HTTP requests when a specific event is triggered within the
> project.
> Webhooks are configured within the App (no code required) and send HTTP requests when a specific event is triggered. [Learn more about Webhooks](#).
## Creating Webhooks

92
docs/guides/white-labeling.md
View File

@@ -1,92 +0,0 @@
# White-Labeling a Project
> The Directus App UX/UI is meant to be _transparent_, and uses "form follows function" as the guiding design principle.
> This allows the platform to be completely tailored to your branding, end-to-end.
## Project Settings
1. Navigate to **Settings > Project Settings**
2. Configure any of the following **branding fields**
- **Project Name** — The name used at the top of the [Navigation Bar](/concepts/app-overview) and on the login/public
pages
- **Project URL** — The URL when clicking the logo at the top of the [Module Bar](/concepts/app-overview)
- **Project Color** — The color used behind the logo at the top of the [Module Bar](/concepts/app-overview), on the
login/public pages, and for the browser's FavIcon
- **Project Logo** — A 40x40 pixel logo at the top of the [Module Bar](/concepts/app-overview) and on the login/public
pages
::: tip Recommended Logo Styling
The 40x40 pixel Project Logo is inset within the 64x64 pixel Project Color square. To avoid a "boxy" look, we recommend
using a SVG or PNG logo with transparency.
:::
::: tip Browser FavIcon & Title
The project color and logo are also used to set the dynamic favicon, and the project title is used in the browser's
title. This furthers the bespoke appearance of your platform and makes it easier to differentiate between different
Directus projects.
:::
### Public Page Styling
In addition to the above options, you can also apply the following additional styling to your project's
[public pages](/concepts/app-overview).
- **Public Foreground** — An image shown on the right-side pane of public pages; max 400px width
- **Public Background** — An image displayed behind the above foreground image, shown full-bleed within the right-side
pane of public pages
- **Public Note** — A helpful note displayed at the bottom of the right-side pane of public pages; supports markdown for
rich-text formatting
::: tip Default Background Color
When a Public Background image is not set, the right-side pane of public pages uses the Project Color instead.
:::
## Themes & Custom CSS
The Directus App has been developed with customization and extensibility in mind. Colors and styles referenced within
the codebase all use CSS variables, and therefore it is easy to make comprehensive changes to the App styling.
- **Themes** — See the [Light Theme](https://github.com/directus/directus/blob/main/app/src/styles/themes/_light.scss)
or [Dark Theme](https://github.com/directus/directus/blob/main/app/src/styles/themes/_dark.scss)
- **Typography** — See the [Fonts](https://github.com/directus/directus/blob/main/app/src/styles/_type-styles.scss) and
[Type Styles](https://github.com/directus/directus/blob/main/app/src/styles/mixins/type-styles.scss)
- **Variables** — See the
[Global Variables](https://github.com/directus/directus/blob/main/app/src/styles/_variables.scss)
You can override any core CSS, including the above variables, directly within the App through project Settings.
1. Navigate to **Settings > Project Settings**
2. Scroll to the **CSS Overrides** field
3. Enter any **valid CSS**
4. Click the **Save** action button in the header
::: tip Action Styling
The `--primary` variable (and its shades) control call-to-actions and all other "Directus blue" elements within the App.
While it may be tempting to override this variable with your brand's color, please first review the following warnings:
- Avoid using yellow, orange, or red hues that give a sense of "danger"
- Avoid low-contrast colors like yellows, grays, etc, that might not be easily visible
- Avoid low-saturation colors like black, which might not properly highlight CTAs
:::
## API Reference
In addition to the static core docs, Directus also includes a Dynamic API Reference based on your project's schema. This
includes tailored endpoint info for each collection within your data model, customizing the documentation to your
specific project.
<!-- @TODO ## System Table Prefix
Most white-labeling takes place in the presentation layer of the platform's App, but in some cases
even the API and/or database needs to be a bit more agnostic. For that reason, Directus allows
changing the prefix used by system tables. By default this is set to use `directus_*` to avoid any
potential conflicts, but you can override this within the [Environment Variables](/reference/environment-variables). -->

6
docs/package-lock.json generated
View File

@@ -12026,6 +12026,12 @@
}
}
},
"vuepress-plugin-clean-urls": {
"version": "1.1.2",
"resolved": "https://registry.npmjs.org/vuepress-plugin-clean-urls/-/vuepress-plugin-clean-urls-1.1.2.tgz",
"integrity": "sha512-36r6XT9stybGSL9zHfFM6F+EBOF9rRDzGdNeias3AmU3AH5+DqsciMjRpHfecKXDKeVcc0PlNfG1Tf19CW5MzA==",
"dev": true
},
"vuepress-plugin-container": {
"version": "2.1.5",
"resolved": "https://registry.npmjs.org/vuepress-plugin-container/-/vuepress-plugin-container-2.1.5.tgz",

Some files were not shown because too many files have changed in this diff Show More