diff --git a/app/src/modules/docs/components/links.yaml b/app/src/modules/docs/components/links.yaml index 13850796ad..b710981fa6 100644 --- a/app/src/modules/docs/components/links.yaml +++ b/app/src/modules/docs/components/links.yaml @@ -1,182 +1,43 @@ -- name: Getting Started - icon: play_circle_outline - to: '/getting-started' - children: - - to: '/getting-started/introduction' - name: Introduction - - to: '/getting-started/support' - name: Help & Support - - to: '/getting-started/backing-directus' - name: Backing Directus - -- name: Concepts +- name: App Overview + to: '/app/overview' icon: school - to: '/concepts' - children: - - to: '/concepts/activity' - name: Activity - - to: '/concepts/application' - name: Application - - to: '/concepts/collections' - name: Collections - - to: '/concepts/databases' - name: Databases - - to: '/concepts/displays' - name: Displays - - to: '/concepts/extensions' - name: Extensions - - to: '/concepts/fields' - name: Fields - - to: '/concepts/files' - name: Files - - to: '/concepts/interfaces' - name: Interfaces - - to: '/concepts/items' - name: Items - - to: '/concepts/layouts' - name: Layouts - - to: '/concepts/modules' - name: Modules - - to: '/concepts/permissions' - name: Permissions - - to: '/concepts/projects' - name: Projects - - to: '/concepts/relationships' - name: Relationships - - to: '/concepts/revisions' - name: Revisions - - to: '/concepts/roles' - name: Roles - - to: '/concepts/translations' - name: Translations - - to: '/concepts/types' - name: Types - - to: '/concepts/users' - name: Users -- name: Guides - to: '/guides' - icon: article - children: - - to: '/guides/api-config' - name: API Config - - to: '/guides/api-endpoints' - name: API Endpoints - - to: '/guides/api-hooks' - name: API Hooks - - to: '/guides/collections' - name: Collections - - to: '/guides/displays' - name: Displays - - to: '/guides/email-templates' - name: Email Templates - - to: '/guides/fields' - name: Fields - - to: '/guides/files' - name: Files - - to: '/guides/interfaces' - name: Interfaces - - to: '/guides/items' - name: Items - - to: '/guides/layouts' - name: Layouts - - to: '/guides/migrations' - name: Migrations - - to: '/guides/modules' - name: Modules - - to: '/guides/permissions' - name: Permissions - - to: '/guides/presets' - name: Presets - - to: '/guides/projects' - name: Projects - - to: '/guides/roles' - name: Roles - - to: '/guides/styles' - name: Styles - - to: '/guides/users' - name: Users - - to: '/guides/webhooks' - name: Webhooks +- name: Content Collections + to: '/app/content-collections' + icon: list_alt -- name: Reference - icon: code - to: '/reference' - children: - - to: '/reference/command-line-interface' - name: Command Line Interface - - to: '/reference/environment-variables' - name: Environment Variables - - to: '/reference/config-files' - name: Config Files - - to: '/reference/error-codes' - name: Error Codes - - to: '/reference/field-transforms' - name: Field Transforms - - to: '/reference/filter-rules' - name: Filter Rules - - to: '/reference/sdk' - name: JavaScript SDK +- name: Content Items + to: '/app/content-items' + icon: edit_note -- name: API Reference - icon: api - to: '/reference/api' - children: - - to: '/reference/api/introduction' - name: Introduction - - to: '/reference/api/authentication' - name: Authentication - - name: Global Query Parameters - to: '/reference/api/query' - - name: Data Access - to: '/reference/api/items' - - name: Assets - to: '/reference/api/assets' - - name: System - to: '/reference/api/system' - children: - - to: '/reference/api/system/activity' - name: Activity - - to: '/reference/api/system/authentication' - name: Authentication - - to: '/reference/api/system/collections' - name: Collections - - to: '/reference/api/system/extensions' - name: Extensions - - to: '/reference/api/system/fields' - name: Fields - - to: '/reference/api/system/files' - name: Files - - to: '/reference/api/system/folders' - name: Folders - - to: '/reference/api/system/permissions' - name: Permissions - - to: '/reference/api/system/presets' - name: Presets - - to: '/reference/api/system/relations' - name: Relations - - to: '/reference/api/system/revisions' - name: Revisions - - to: '/reference/api/system/roles' - name: Roles - - to: '/reference/api/system/server' - name: Server - - to: '/reference/api/system/settings' - name: Settings - - to: '/reference/api/system/users' - name: Users - - to: '/reference/api/system/utilities' - name: Utilities - - to: '/reference/api/system/webhooks' - name: Webhooks -# - name: Contributing -# to: '/contributing' -# children: -# - to: '/contributing/introduction' -# name: Introduction -# - to: '/contributing/codebase-overview' -# name: Codebase Overview -# - to: '/contributing/running-locally' -# name: Running Locally -# - to: '/contributing/translations' -# name: Translating the App +- name: User Directory + to: '/app/user-directory' + icon: people_alt + +- name: File Library + to: '/app/file-library' + icon: folder + +- name: Insights + to: '/app/insights' + icon: insights + +- name: Documentation + to: '/app/documentation' + icon: help_outline + +- name: Settings + to: '/app/settings' + icon: settings + +- name: Help & Support + to: '/getting-started/support' + icon: support_agent + +- name: Backing Directus + to: '/getting-started/backing-directus' + icon: card_giftcard + +- name: Glossary + to: '/getting-started/glossary' + icon: menu_book diff --git a/app/src/modules/docs/index.ts b/app/src/modules/docs/index.ts index 9d6a1f499b..ddae264dac 100644 --- a/app/src/modules/docs/index.ts +++ b/app/src/modules/docs/index.ts @@ -7,7 +7,7 @@ import StaticDocs from './routes/static.vue'; export default defineModule({ id: 'docs', name: '$t:documentation', - icon: 'info', + icon: 'help_outline', routes: [ { path: '', diff --git a/app/vite.config.js b/app/vite.config.js index d35459ab57..ef26cd9219 100644 --- a/app/vite.config.js +++ b/app/vite.config.js @@ -100,8 +100,8 @@ export default defineConfig({ const titleLine = code.match(titleRegex); - const title = titleLine[1] ?? null; - const modularExtension = Boolean(titleLine[2]); + const title = titleLine?.[1] ?? null; + const modularExtension = Boolean(titleLine?.[2]); const codeWithoutTitle = code.replace(titleRegex, ''); const newCode = `---\ntitle: "${title}"\nmodularExtension: ${modularExtension}${ diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 34cd83f41a..fa706ffc4d 100755 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -5,7 +5,7 @@ module.exports = { ga: 'UA-24637628-7', head: [ ['link', { rel: 'manifest', href: '/manifest.json' }], - ['link', { rel: 'mask-icon', href: '/safari-pinned-tab.svg', color: '#2CCDA6' }], + ['link', { rel: 'mask-icon', href: '/safari-pinned-tab.svg', color: '#00C897' }], ['link', { rel: 'shortcut icon', type: 'image/svg+xml', href: '/favicon.svg' }], [ 'link', @@ -35,9 +35,9 @@ module.exports = { }, ], ['meta', { name: 'application-name', content: 'Directus Docs' }], - ['meta', { name: 'theme-color', content: '#2CCDA6' }], + ['meta', { name: 'theme-color', content: '#00C897' }], ['meta', { name: 'apple-mobile-web-app-title', content: 'Directus Docs' }], - ['meta', { name: 'msapplication-TileColor', content: '#2CCDA6' }], + ['meta', { name: 'msapplication-TileColor', content: '#00C897' }], ['meta', { name: 'msapplication-config', content: '/browserconfig.xml' }], ], themeConfig: { @@ -90,579 +90,183 @@ module.exports = { path: '/getting-started/backing-directus', title: 'Backing Directus', }, - ], - }, - { - title: 'Concepts', - children: [ { type: 'page', - path: '/concepts/activity', - title: 'Activity', - }, - { - type: 'page', - path: '/concepts/application', - title: 'Application', - }, - { - type: 'page', - path: '/concepts/collections', - title: 'Collections', - }, - { - type: 'page', - path: '/concepts/databases', - title: 'Databases', - }, - { - type: 'page', - path: '/concepts/displays', - title: 'Displays', - }, - { - type: 'page', - 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', - path: '/concepts/relationships', - title: 'Relationships', - }, - { - type: 'page', - path: '/concepts/revisions', - title: 'Revisions', - }, - { - type: 'page', - path: '/concepts/roles', - title: 'Roles', - }, - { - type: 'page', - path: '/concepts/translations', - title: 'Translations', - }, - { - type: 'page', - path: '/concepts/types', - title: 'Types', - }, - { - type: 'page', - path: '/concepts/users', - title: 'Users', + path: '/getting-started/glossary', + title: 'Glossary', }, ], }, { - title: 'Guides', + title: 'App Guide', children: [ { type: 'page', - path: '/guides/migrating-from-v8', - title: 'Migrating from v8', + path: '/app/overview', + title: 'Overview', + }, + { + type: 'page', + path: '/app/content/content-collections', + title: 'Content Collections', + }, + { + type: 'page', + path: '/app/content/content-items', + title: 'Content Items', + }, + { + type: 'page', + path: '/app/user-directory', + title: 'User Directory', + }, + { + type: 'page', + path: '/app/file-library', + title: 'File Library', + }, + { + type: 'page', + path: '/app/insights', + title: 'Insights', + }, + { + type: 'page', + path: '/app/documentation', + title: 'Documentation', + }, + { + type: 'page', + path: '/app/settings', + title: 'Settings', + }, + ], + }, + { + title: 'Configuration', + children: [ + { + type: 'page', + path: '/configuration/overview', + title: 'Overview', + }, + { + type: 'page', + path: '/configuration/installation', + title: 'Installation', + children: [ + { + type: 'page', + path: '/configuration/installation/aws', + title: 'AWS', + }, + { + type: 'page', + path: '/configuration/installation/cli', + title: 'CLI', + }, + { + type: 'page', + path: '/configuration/installation/digitalocean-app-platform', + title: 'DigitalOcean', + }, + { + type: 'page', + path: '/configuration/installation/docker', + title: 'Docker', + }, + { + type: 'page', + path: '/configuration/installation/iis', + title: 'IIS', + }, + { + type: 'page', + path: '/configuration/installation/manual', + title: 'Manual', + }, + { + type: 'page', + path: '/configuration/installation/plesk', + title: 'Plesk', + }, + { + type: 'page', + path: '/configuration/installation/ubuntu', + title: 'Ubuntu', + }, + ] + }, + { + type: 'page', + path: '/configuration/config-options', + title: 'Config Options', + }, + { + type: 'page', + path: '/configuration/project-settings', + title: 'Project Settings', + }, + { + type: 'page', + path: '/configuration/data-model', + title: 'Data Model', + collapsable: false, + children: [ + { + type: 'page', + path: '/configuration/relationships', + title: 'Relationships', + }, + ] + }, + { + type: 'page', + path: '/configuration/users-roles-permissions', + title: 'Users, Roles & Permissions', + }, + { + type: 'page', + path: '/configuration/presets-bookmarks', + title: 'Presets & Bookmarks', + }, + { + type: 'page', + path: '/configuration/webhooks', + title: 'Webhooks', + }, + { + type: 'page', + path: '/configuration/activity-log', + title: 'Activity Log', }, { type: 'divider', }, + // { + // type: 'page', + // path: '/configuration/security', + // title: 'Security*', + // }, + // { + // type: 'page', + // path: '/configuration/localization', + // title: 'Localization*', + // }, + // { + // type: 'page', + // path: '/configuration/faq', + // title: 'Frequently Asked Questions*', + // }, { type: 'page', - path: '/guides/api-config', - title: 'API Config', - }, - { - type: 'page', - 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/email-templates', - title: 'Email Templates', - }, - { - 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', - title: 'Items', - }, - { - type: 'page', - path: '/guides/layouts', - title: 'Layouts', - }, - { - type: 'page', - path: '/guides/migrations', - title: 'Migrations', - }, - { - type: 'page', - 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/webhooks', - title: 'Webhooks', - }, - ], - }, - { - title: 'Reference', - children: [ - { - type: 'page', - path: '/reference/command-line-interface', - title: 'Command Line Interface', - }, - { - type: 'page', - path: '/reference/environment-variables', - title: 'Environment Variables', - }, - { - type: 'page', - path: '/reference/config-files', - title: 'Config Files', - }, - { - type: 'page', - path: '/reference/error-codes', - title: 'Error Codes', - }, - { - type: 'page', - path: '/reference/field-transforms', - title: 'Field Transforms', - }, - { - type: 'page', - path: '/reference/filter-rules', + path: '/configuration/filter-rules', title: 'Filter Rules', }, { type: 'page', - path: '/reference/sdk', - title: 'JavaScript SDK', - }, - { - title: 'Vue Components', - type: 'group', - children: [ - { - path: 'reference/app/components/', - title: 'Introduction', - type: 'page', - }, - { - path: 'reference/app/components/v-avatar', - title: 'Avatar', - type: 'page', - }, - { - path: 'reference/app/components/v-badge', - title: 'Badge', - type: 'page', - }, - { - path: 'reference/app/components/v-breadcrumb', - title: 'Breadcrumb', - type: 'page', - }, - { - path: 'reference/app/components/v-button', - title: 'Button', - type: 'page', - }, - { - title: 'Card', - children: [ - { - path: 'reference/app/components/v-card', - title: 'Card', - type: 'page', - }, - { - path: 'reference/app/components/v-card-actions', - title: 'Card Actions', - type: 'page', - }, - { - path: 'reference/app/components/v-card-subtitle', - title: 'Card Subtitle', - type: 'page', - }, - { - path: 'reference/app/components/v-card-text', - title: 'Card Text', - type: 'page', - }, - { - path: 'reference/app/components/v-card-title', - title: 'Card Title', - type: 'page', - }, - ], - }, - { - path: 'reference/app/components/v-checkbox', - title: 'Checkbox', - type: 'page', - }, - { - path: 'reference/app/components/v-chip', - title: 'Chip', - type: 'page', - }, - { - path: 'reference/app/components/v-detail', - title: 'Detail', - type: 'page', - }, - { - path: 'reference/app/components/v-dialog', - title: 'Dialog', - type: 'page', - }, - { - path: 'reference/app/components/v-divider', - title: 'Divider', - type: 'page', - }, - { - path: 'reference/app/components/v-drawer', - title: 'Drawer', - type: 'page', - }, - { - path: 'reference/app/components/v-error', - title: 'Error', - type: 'page', - }, - { - path: 'reference/app/components/v-fancy-select', - title: 'Fancy Select', - type: 'page', - }, - { - path: 'reference/app/components/v-field-select', - title: 'Field Select', - type: 'page', - }, - { - path: 'reference/app/components/v-field-template', - title: 'Field Template', - type: 'page', - }, - { - path: 'reference/app/components/v-form', - title: 'Form', - type: 'page', - }, - { - path: 'reference/app/components/v-hover', - title: 'Hover', - type: 'page', - }, - { - path: 'reference/app/components/v-icon', - title: 'Icon', - type: 'page', - }, - { - path: 'reference/app/components/v-info', - title: 'Info', - type: 'page', - }, - { - path: 'reference/app/components/v-input', - title: 'Input', - type: 'page', - }, - { - title: 'ItemGroup', - children: [ - { - path: 'reference/app/components/v-item-group', - title: 'Item Group', - type: 'page', - }, - { - path: 'reference/app/components/v-item', - title: 'Item', - type: 'page', - }, - ], - }, - { - title: 'List', - children: [ - { - path: 'reference/app/components/v-list-group', - title: 'List Group', - type: 'page', - }, - { - path: 'reference/app/components/v-list-item-content', - title: 'List Item Content', - type: 'page', - }, - { - path: 'reference/app/components/v-list-item-hint', - title: 'List Item Hint', - type: 'page', - }, - { - path: 'reference/app/components/v-list-item-icon', - title: 'List Item Icon', - type: 'page', - }, - { - path: 'reference/app/components/v-list-item', - title: 'List Item', - type: 'page', - }, - { - path: 'reference/app/components/v-list', - title: 'List', - type: 'page', - }, - ], - }, - { - path: 'reference/app/components/v-menu', - title: 'Menu', - type: 'page', - }, - { - path: 'reference/app/components/v-notice', - title: 'Notice', - type: 'page', - }, - { - path: 'reference/app/components/v-overlay', - title: 'Overlay', - type: 'page', - }, - { - path: 'reference/app/components/v-pagination', - title: 'Pagination', - type: 'page', - }, - { - title: 'Progress', - children: [ - { - path: 'reference/app/components/v-progress-circular', - title: 'Progress Circular', - type: 'page', - }, - { - path: 'reference/app/components/v-progress-linear', - title: 'Progress Linear', - type: 'page', - }, - ], - }, - { - path: 'reference/app/components/v-radio', - title: 'Radio', - type: 'page', - }, - { - path: 'reference/app/components/v-select', - title: 'Select', - type: 'page', - }, - { - path: 'reference/app/components/v-sheet', - title: 'Sheet', - type: 'page', - }, - { - path: 'reference/app/components/v-skeleton-loader', - title: 'Skeleton Loader', - type: 'page', - }, - { - path: 'reference/app/components/v-slider', - title: 'Slider', - type: 'page', - }, - { - path: 'reference/app/components/v-switch', - title: 'Switch', - type: 'page', - }, - { - path: 'reference/app/components/v-table', - title: 'Table', - type: 'page', - }, - { - title: 'Tabs', - children: [ - { - path: 'reference/app/components/v-tabs', - title: 'Tabs', - type: 'page', - }, - { - path: 'reference/app/components/v-tab', - title: 'Tab', - type: 'page', - }, - { - path: 'reference/app/components/v-tabs-items', - title: 'Tabs Items', - type: 'page', - }, - { - path: 'reference/app/components/v-tab-item', - title: 'Tab Item', - type: 'page', - }, - ], - }, - { - path: 'reference/app/components/v-text-overflow', - title: 'Text Overflow', - type: 'page', - }, - { - path: 'reference/app/components/v-textarea', - title: 'Textarea', - type: 'page', - }, - { - title: 'Transitions', - children: [ - { - path: 'reference/app/components/transition-bounce', - title: 'Transition Bounce', - type: 'page', - }, - { - path: 'reference/app/components/transition-dialog', - title: 'Transition Dialog', - type: 'page', - }, - { - path: 'reference/app/components/transition-expand', - title: 'Transition Expand', - type: 'page', - }, - ], - }, - { - path: 'reference/app/components/v-upload', - title: 'Upload', - type: 'page', - }, - ], + path: '/configuration/upgrades-migrations', + title: 'Upgrades & Migrations', }, ], }, @@ -671,119 +275,184 @@ module.exports = { children: [ { type: 'page', - path: '/reference/api/introduction', + path: '/reference/introduction', title: 'Introduction', }, { type: 'page', - path: '/reference/api/authentication', + path: '/reference/authentication', title: 'Authentication', }, { type: 'page', - title: 'Query Parameters', - path: '/reference/api/query', + title: 'Global Parameters', + path: '/reference/query', }, { type: 'page', - title: 'Data Access', - path: '/reference/api/items', + title: 'Items', + path: '/reference/items', }, { type: 'page', - path: '/reference/api/assets', - title: 'Assets', + path: '/reference/files', + title: 'Files', }, { - type: 'group', - title: 'System', - children: [ - { - type: 'page', - path: '/reference/api/system/activity', - title: 'Activity', - }, - { - type: 'page', - path: '/reference/api/system/authentication', - title: 'Authentication', - }, - { - type: 'page', - path: '/reference/api/system/collections', - title: 'Collections', - }, - { - type: 'page', - path: '/reference/api/system/extensions', - title: 'Extensions', - }, - { - type: 'page', - path: '/reference/api/system/fields', - title: 'Fields', - }, - { - type: 'page', - path: '/reference/api/system/files', - title: 'Files', - }, - { - type: 'page', - path: '/reference/api/system/folders', - title: 'Folders', - }, - { - type: 'page', - path: '/reference/api/system/permissions', - title: 'Permissions', - }, - { - type: 'page', - path: '/reference/api/system/presets', - title: 'Presets', - }, - { - type: 'page', - path: '/reference/api/system/relations', - title: 'Relations', - }, - { - type: 'page', - path: '/reference/api/system/revisions', - title: 'Revisions', - }, - { - type: 'page', - path: '/reference/api/system/roles', - title: 'Roles', - }, - { - type: 'page', - path: '/reference/api/system/server', - title: 'Server', - }, - { - type: 'page', - path: '/reference/api/system/settings', - title: 'Settings', - }, - { - type: 'page', - path: '/reference/api/system/users', - title: 'Users', - }, - { - type: 'page', - path: '/reference/api/system/utilities', - title: 'Utilities', - }, - { - type: 'page', - path: '/reference/api/system/webhooks', - title: 'Webhooks', - }, - ], + type: 'divider', + }, + { + type: 'page', + path: '/reference/cli', + title: 'CLI', + }, + { + type: 'page', + path: '/reference/sdk', + title: 'JS-SDK', + }, + { + type: 'divider', + }, + { + type: 'page', + path: '/reference/system/activity', + title: 'Activity', + }, + { + type: 'page', + path: '/reference/system/collections', + title: 'Collections', + }, + { + type: 'page', + path: '/reference/system/extensions', + title: 'Extensions', + }, + { + type: 'page', + path: '/reference/system/fields', + title: 'Fields', + }, + { + type: 'page', + path: '/reference/system/folders', + title: 'Folders', + }, + { + type: 'page', + path: '/reference/system/permissions', + title: 'Permissions', + }, + { + type: 'page', + path: '/reference/system/presets', + title: 'Presets', + }, + { + type: 'page', + path: '/reference/system/relations', + title: 'Relations', + }, + { + type: 'page', + path: '/reference/system/revisions', + title: 'Revisions', + }, + { + type: 'page', + path: '/reference/system/roles', + title: 'Roles', + }, + { + type: 'page', + path: '/reference/system/server', + title: 'Server', + }, + { + type: 'page', + path: '/reference/system/settings', + title: 'Settings', + }, + { + type: 'page', + path: '/reference/system/users', + title: 'Users', + }, + { + type: 'page', + path: '/reference/system/utilities', + title: 'Utilities', + }, + { + type: 'page', + path: '/reference/system/webhooks', + title: 'Webhooks', + }, + ], + }, + { + title: 'Extensions', + children: [ + { + type: 'page', + path: '/extensions/introduction', + title: 'Introduction', + }, + { + type: 'page', + path: '/extensions/api-endpoints', + title: 'API Endpoints', + }, + { + type: 'page', + path: '/extensions/displays', + title: 'Displays', + }, + { + type: 'page', + path: '/extensions/email-templates', + title: 'Email Templates', + }, + { + type: 'page', + path: '/extensions/hooks', + title: 'Hooks', + }, + { + type: 'page', + path: '/extensions/interfaces', + title: 'Interfaces', + }, + { + type: 'page', + path: '/extensions/layouts', + title: 'Layouts', + }, + { + type: 'page', + path: '/extensions/migrations', + title: 'Migrations', + }, + { + type: 'page', + path: '/extensions/modules', + title: 'Modules', + }, + { + type: 'page', + path: '/extensions/panes', + title: 'Panes', + }, + { + type: 'page', + path: '/extensions/themes', + title: 'Themes', + }, + { + type: 'page', + path: '/extensions/app-translations', + title: 'Translations', }, ], }, diff --git a/docs/.vuepress/enhanceApp.js b/docs/.vuepress/enhanceApp.js deleted file mode 100755 index 8742d752a6..0000000000 --- a/docs/.vuepress/enhanceApp.js +++ /dev/null @@ -1,8 +0,0 @@ -export default ({ - Vue, // the version of Vue being used in the VuePress app - options, // the options for the root Vue instance - router, // the router instance for the app - siteData, // site metadata -}) => { - router.addRoutes([{ path: '/', redirect: '/getting-started/introduction' }]); -}; diff --git a/docs/.vuepress/public/manifest.json b/docs/.vuepress/public/manifest.json index f3d0061b2d..4d62b97711 100644 --- a/docs/.vuepress/public/manifest.json +++ b/docs/.vuepress/public/manifest.json @@ -3,7 +3,7 @@ "name": "Directus Docs", "short-name": "Docs", "description": "Directus 9. An Instant App & API for your SQL Database.", - "theme-color": "#2CCDA6", + "theme-color": "#00C897", "version": "1.0", "scope": "/", "start_url": "/", diff --git a/docs/.vuepress/styles/palette.styl b/docs/.vuepress/styles/palette.styl index 653a5475bc..d3787db829 100755 --- a/docs/.vuepress/styles/palette.styl +++ b/docs/.vuepress/styles/palette.styl @@ -1,4 +1,4 @@ -$accentColor = #2CCDA6 +$accentColor = #00C897 $textColor = #172940 $borderColor = #F0F4F9 $codeBgColor = #F0F4F9 diff --git a/docs/.vuepress/theme/components/Navbar.vue b/docs/.vuepress/theme/components/Navbar.vue index 59f1da2e10..fde4e4aacd 100644 --- a/docs/.vuepress/theme/components/Navbar.vue +++ b/docs/.vuepress/theme/components/Navbar.vue @@ -93,7 +93,7 @@ $navbar-horizontal-padding = 30px padding $navbar-vertical-padding $navbar-horizontal-padding line-height $navbarHeight - 1.4rem - background-color: #2CCDA6; + background-color: #00C897; a, span, img display inline-block diff --git a/docs/.vuepress/theme/components/SidebarDivider.vue b/docs/.vuepress/theme/components/SidebarDivider.vue index 1eadf4ea7f..41faeb05cd 100644 --- a/docs/.vuepress/theme/components/SidebarDivider.vue +++ b/docs/.vuepress/theme/components/SidebarDivider.vue @@ -10,7 +10,8 @@ hr.sidebar-divider display inline-block color $textColor border-left 0.25rem solid transparent - margin 0.35rem 1rem 0.35rem 1.25rem - width: 100% + border-top-width 1px + margin 0.35rem 1.25rem 0.35rem 1.25rem + width: calc(100% - 2.5rem) box-sizing: border-box diff --git a/docs/.vuepress/theme/components/SidebarGroup.vue b/docs/.vuepress/theme/components/SidebarGroup.vue index 8930612dcb..099c25ba3b 100644 --- a/docs/.vuepress/theme/components/SidebarGroup.vue +++ b/docs/.vuepress/theme/components/SidebarGroup.vue @@ -76,7 +76,7 @@ export default { &.is-sub-group padding-left 0 & > .sidebar-heading - font-size 0.95em + font-size 1em line-height 1.4 font-weight normal padding-left 2rem diff --git a/docs/.vuepress/theme/layouts/Homepage.vue b/docs/.vuepress/theme/layouts/Homepage.vue new file mode 100644 index 0000000000..476b7e501e --- /dev/null +++ b/docs/.vuepress/theme/layouts/Homepage.vue @@ -0,0 +1,242 @@ + + + + + \ No newline at end of file diff --git a/docs/.vuepress/theme/styles/code.styl b/docs/.vuepress/theme/styles/code.styl index 0c1b8a8b5e..bc278a2e79 100644 --- a/docs/.vuepress/theme/styles/code.styl +++ b/docs/.vuepress/theme/styles/code.styl @@ -236,7 +236,7 @@ pre[class*="language-"] { .token.attr-value, .token.regex, .token.variable { - color: #2CCDA6; + color: #00C897; } .token.operator, diff --git a/docs/.vuepress/theme/styles/index.styl b/docs/.vuepress/theme/styles/index.styl index 09789a5655..97d1e93ccd 100644 --- a/docs/.vuepress/theme/styles/index.styl +++ b/docs/.vuepress/theme/styles/index.styl @@ -154,15 +154,16 @@ h2 padding-top ($navbarHeight + 4.5rem) h3 - font-size 1.25rem - line-height 1.875rem + font-size 1.1rem + line-height 1.125rem + font-weight 700 h2 + h3 padding-top ($navbarHeight + 0.5rem) !important h4 - font-size 1.1rem - line-height 1.125rem + font-size 1rem + line-height 1rem padding-top ($navbarHeight + 0.25rem) !important a.header-anchor diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..26d4d7d5b3 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +--- +layout: Homepage +--- diff --git a/docs/app/content-collections.md b/docs/app/content-collections.md new file mode 100644 index 0000000000..82113b5b56 --- /dev/null +++ b/docs/app/content-collections.md @@ -0,0 +1,135 @@ +# Collection Page + +> 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. + +[[toc]] + +## Creating an Item + +1. Navigate to the collection where you want to add an item +2. Click on the "Create Item" (+ icon) button located in the header +3. Complete the Item Detail form +4. Click the "Save Item" (✓ icon) button located in the header + +::: tip Singletons + +If the Collection is configured as a "Singleton" in the data model settings, then the App will automatically skip step +#2 above. + +::: + +## Manually Sorting Items + +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 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 + +This feature is only available if a Sort column has been configured in the Collection's data model settings. + +::: + +## Ordering Items + +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 + +::: tip Sort vs Order + +**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. + +::: + +## 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 + +### Table Layout + +Supports all forms of data, and is therefore the default within the Content module. It includes the following +features/options: + +- Toggle & Reorder Field Columns (Option) +- Row Spacing (Option) +- Manual Item Ordering +- Column Sort +- Column Resizing +- Select All + +### Card Layout + +This tiled layout is ideal for collections that prioritize an image, and is the default for both the +[User Directory](/guides/users/) and [File Library](/guides/files/). 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 Layout + +### Map Layout + +## Searching Items + +**[Learn more about Search](/guides/items/#searching-items)** + +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 + +**[Learn more about Filtering](/guides/items/#filtering-items).** + +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 +5. Adjust the operator (eg: "Contains") as needed by clicking on it +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 + +**[Learn more about Bookmarks](/guides/items/#bookmarking-item-presets)** + +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 + +1. Navigate to the collection of the items you want to bookmark +2. Optional: Configure the dataset as desired (eg: layout, options, search, filters, order, etc) +3. Click "Export Data" in the page sidebar +4. Choose the desired format: either CSV or JSON +5. Choose whether you want to use your current Filters and Settings in the export +6. Click the "Export" button to download the file to your device diff --git a/docs/app/content-items.md b/docs/app/content-items.md new file mode 100644 index 0000000000..fc2f739eb8 --- /dev/null +++ b/docs/app/content-items.md @@ -0,0 +1,93 @@ +# Item Page + +> A tailored form for viewing and editing an item's fields. This page also includes options for archiving, reverting, +> deleting, and commenting on the item. + +[[toc]] + +::: warning Permissions + +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. + +::: + +## Updating an Item + +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 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 +#3 above. + +::: + +## Deleting an Item + +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 +5. Confirm the action within the dialog by clicking "Delete" + +::: tip Deleting from the Item Detail page + +You can also click on an item to navigate to its Detail page. From there, you can click on the "Delete Item" (trash +icon) button located in the header. + +::: + +## Archiving an Item + +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 +5. Confirm the action within the dialog by clicking "Archive" + +::: warning Requires Configuration + +This feature is only available if an Archive column has been configured in the Collection's data model settings. + +::: + +::: tip Archiving from the Item Detail page + +You can also click on an item to navigate to its Detail page. From there, you can click on the "Archive Item" (archive +icon) button located in the header. + +::: + +## Reverting an Item + +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 +5. Click on the revision you wish to preview +6. Click on the "Revert" button located in the drawer's header +7. Confirm the action within the dialog by clicking "Revert" + +## Commenting on an Item + +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 diff --git a/docs/app/content.md b/docs/app/content.md new file mode 100644 index 0000000000..0b19c9f875 --- /dev/null +++ b/docs/app/content.md @@ -0,0 +1,20 @@ +# Content + +> This module is the primary way for interacting with your database content. Here you can browse/visualize collections +> of items, and navigate to their individual item forms. + +## Collection Overview + +This is the landing page of the module, and lists the same collections as its content navigation bar. Clicking on a +collection takes to you to the Collection Page. + +## Collection Page + +This is the main gateway to your items, providing highly configurable Layouts for browsing, visualizing, and managing +the items within a collection. Clicking on an item takes to you to the Item Page. +[Learn more about the Collection Page](/app/content/collection) + +## Item Page + +A tailored form for viewing and editing an item's fields. This page also includes options for archiving, reverting, +deleting, and commenting on the item. [Learn more about the Item Page](/app/content/item) diff --git a/docs/app/documentation.md b/docs/app/documentation.md new file mode 100644 index 0000000000..d02b409e1b --- /dev/null +++ b/docs/app/documentation.md @@ -0,0 +1,25 @@ +# Documentation + +> An internal set of guides and docs for the installed version of the platform, including an +> [API Reference](/reference/api/introduction) that is dynamically tailored to your custom schema. + +Docs for the latest version of the platform are available via [https://docs.directus.io](https://docs.directus.io), and +_version-specific_ docs are included within the App itself as a core module. Both sets come from the same source of +markdown files on [GitHub](https://github.com/directus/directus), making them easy for anyone to work with. + +Below are the six main sections of the platform's documentation, as well as descriptions of each. + +- [Getting Started](/getting-started/introduction/) — For anyone who is unfamiliar with the platform +- [App Guide](/app-guide/introduction/) — For users (non-technical or technical) of the platform's no-code App +- [Configuration](/configuration/introduction/) — For administrators installing and setting up the platform +- [API Reference](/api-reference/introduction/) — For developers connecting with data via the platform's API toolkit +- [Extensions](/extensions/introduction/) — For developers creating custom experiences on top of the platform +- [Contributing](/contributing/introduction/) — For developers working on the platform's open-source core + +::: tip In-App Exclusions + +Docs included within the app intentionally exclude certain pages, such as "Installation", as these sections are not +relevant to running instances of the platform. Additionally, some sections may be hidden based on your role as a user +versus a more technical administrator. + +::: diff --git a/docs/app/file-library.md b/docs/app/file-library.md new file mode 100644 index 0000000000..3280f2535d --- /dev/null +++ b/docs/app/file-library.md @@ -0,0 +1,71 @@ +# File Library + +> Directus includes a full-featured Digital Asset Management (DAM) system for storing, organizing, browsing, and +> transforming your various files and assets. + +[[toc]] + +## Browsing Files + +This module aggregates all files within the project into one consolidated library. This listing page has the same +features and functionality as the [Collection Page](/app/content/collection). + +## Viewing or Editing a File + +Provides a custom form for viewing assets and embeds, with core fields included out-of-the-box (see below), and the +ability for administrators to add additional custom fields. This page has the same features and functionality as the +[Item Page](/app/content/item). + +#### File Info + +- **Preview** — A preview of the image or file +- **Title** — A title for the file +- **Description** — A description of the file +- **Tags** — Keywords used for searchability +- **Location** — An optional location, eg: where a photo was taken +- **Storage** — Which storage adapter is used to store the file asset +- **Filename (Disk)** — LOCKED, this is the actual name of the file in storage +- **Filename (Download)** — This allows you to set the name of the file when it is downloaded + +The file sidebar also includes the following 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 + +#### Action Buttons + +- **Save** — Saves any edits made to the page +- **Edit** — Saves any edits made to the page +- **Download** — Saves any edits made to the page +- **Move Folder** — Saves any edits made to the page +- **Delete** — Permanently removes this file and its metadata. This action is permanent and can not be undone. + +## Editing an Image + +Clicking the "Edit" action button on the File Detail opens an image editor for rotating, cropping, or mirroring the +file. + +1. From the **File Library**, click a file to open it's detail page +2. Click the edit button in the top right to open the image editor +3. Make your changes and hit save in the top right to save the updates to the file + +## Replacing a File + +Clicking the image Preview on the File Detail page opens a modal where you can replace the file. This is useful if you +want to change the file, but keep existing file info and maintain all of the file's relationships. + +## Uploading a File + +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. + +1. From the **File Library**, click on the **"Create Item"** (+ icon) button located in the header +2. **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" diff --git a/docs/app/insights.md b/docs/app/insights.md new file mode 100644 index 0000000000..231dfb1bd6 --- /dev/null +++ b/docs/app/insights.md @@ -0,0 +1,29 @@ +# Insights + +> This [Module](#) allows the creation of custom [Dashboards](#), each with any number of highly configurable +> [Panels](#) for displaying data. + +[[toc]] + +## Browsing Dashboards + +Clicking into the Insights module immediately presents a listing of all dashboards you have access to. These are shown +in the navigation bar and a listing on the main page. + +## Viewing a Dashboard + +## Creating a Dashboard + +## Editing a Dashboard + +## Deleting a Dashboard + +## Creating a Panel + +## Editing a Panel + +- Resizing + +## Duplicating a Panel + +## Deleting a Panel diff --git a/docs/app/overview.md b/docs/app/overview.md new file mode 100644 index 0000000000..d656ed6e73 --- /dev/null +++ b/docs/app/overview.md @@ -0,0 +1,56 @@ +# The Application + +> The App is a no-code presentation layer for your data, content, and assets. It uses an intuitive left-to-right visual +> hierarchy for general organization and navigation. + +![Application Overview](../assets/app-overview.svg) + +## 1. Module Bar + +The leftmost section of the App is the module bar, which includes the: + +- **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 is done within the [Role's configuration](/guides/roles/#configuring-a-role), but the default module + list includes: + - [Content](#) — 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 + - [Insights](#insights) — Access to infinitely customizable data dashboards + - [App Guide](#) — 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 +- **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 + +The navigation bar is based on the current module, and includes: + +- **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 + +This is where the current page's content is shown, including: + +- **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. Sidebar + +The sidebar provides additional context and options for the current page, including: + +- **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. diff --git a/docs/app/settings.md b/docs/app/settings.md new file mode 100644 index 0000000000..83948486ff --- /dev/null +++ b/docs/app/settings.md @@ -0,0 +1,30 @@ +# Settings + +> This module is where your entire project is configured, making it the first place to go after installation. Since it +> is more technical than the rest of the app, it is only available to administrators. + +::: warning Administrators Only + +Only Administrators have access to the Settings module. + +::: + +Settings are split into five distinct sections, each described below. + +- [Project Settings](/guides/projects/#adjusting-project-settings) — Branding and other global options +- [Data Model](/concepts/databases/#database-mirroring) — Your database schema, form layout, and field options. +- [Roles & Permissions](/concepts/roles) — Create and manage access via roles and permissions +- [Presets & Bookmarks](/concepts/collections/#collection-presets-bookmarks) — Set default views of data and configure + bookmarks +- [Webhooks](/guides/webhooks) — Use platform events to trigger external services + +## Reporting a Bug from the App + +The navigation bar of Settings includes a direct link to report a bug in the platform. When using this button, helpful +debugging information about your project is automatically included, such as: version number, operating system, and +environment type. + +## Locating your Platform's Version + +The navigation bar of Settings displays the exact version of your platform. Clicking this button takes you to the GitHub +releases page that includes the full change logs. diff --git a/docs/app/user-directory.md b/docs/app/user-directory.md new file mode 100644 index 0000000000..fc1514c09d --- /dev/null +++ b/docs/app/user-directory.md @@ -0,0 +1,49 @@ +# User Directory + +> [Users](/getting-started/glossary#users) are the individual accounts for logging in to the App. Each user belongs to a +> [Role](/getting-started/glossary#roles) which defines its [Permissions](/getting-started/glossary#permissions). The +> User Directory shows all users within the project, each with their own customizable profile page. + +[[toc]] + +## Browsing Users + +Lists all users of the project, with a navigation that allows quick access to the different role groups. This page has +the same functionality as other [Collection Pages](#). + +## Viewing a User + +Users are referenced throughout the app, often for accountability purposes. Hovering over a user in this context will +provide a popover for basic information, and clicking that popover will navigate you to a readonly view of that user's +profile page. + +## Editing a User + +You can access your profile page from the User Directory or by clicking the [User Menu](#) in the Module Bar. The +profile page has the same features and functionality as the [Item Page](/app/content/item). Administrators can customize +the fields on this page, but the following are available by default. + +- **First Name** — The given name +- **Last Name** — The family/surname +- **Email** — A unique email address +- **Password** — A hashed system password +- **Avatar** — An image to represent the user +- **Location** — The city, country, office, or branch name +- **Title** — The professional staff title +- **Description** — A freeform text description +- **Tags** — Keywords for searchability +- **Language** — The preferred App language/locale +- **Theme** — Light or Dark mode (or based on system preferences) +- **Multi-Factor Authentication** — Configuration for MFA + +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 + +::: tip System Fields + +Administrators have access to additional system fields. [Learn More](#) + +::: diff --git a/docs/build.js b/docs/build.js index 2b34af6883..cb89c44703 100644 --- a/docs/build.js +++ b/docs/build.js @@ -7,7 +7,7 @@ console.log('Building docs...'); const tree = dirTree('.', { extensions: /\.md$/, - exclude: /(node_modules|.vuepress|.vscode|dist)/, + exclude: /(node_modules|.vuepress|.vscode|dist|README.md)/, normalizePath: true, attributes: ['type', 'extension'], }); diff --git a/docs/concepts/activity.md b/docs/concepts/activity.md deleted file mode 100644 index b4109ba309..0000000000 --- a/docs/concepts/activity.md +++ /dev/null @@ -1,35 +0,0 @@ -# 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. - -::: diff --git a/docs/concepts/application.md b/docs/concepts/application.md deleted file mode 100644 index bca1600e6b..0000000000 --- a/docs/concepts/application.md +++ /dev/null @@ -1,179 +0,0 @@ -# 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 - -![Application Overview](../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 is done within the [Role's configuration](/guides/roles/#configuring-a-role), 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) -- [Ordering Items](/guides/items/#ordering-items) -- [Exporting Items](/guides/items/#exporting-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-field-arrangement) 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. - -- [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/#downloading-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) diff --git a/docs/concepts/collections.md b/docs/concepts/collections.md deleted file mode 100644 index 0846ef551b..0000000000 --- a/docs/concepts/collections.md +++ /dev/null @@ -1,44 +0,0 @@ -# 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) diff --git a/docs/concepts/databases.md b/docs/concepts/databases.md deleted file mode 100644 index fecf90e08c..0000000000 --- a/docs/concepts/databases.md +++ /dev/null @@ -1,38 +0,0 @@ -# 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 widely used 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. diff --git a/docs/concepts/displays.md b/docs/concepts/displays.md deleted file mode 100644 index ac957291a1..0000000000 --- a/docs/concepts/displays.md +++ /dev/null @@ -1,27 +0,0 @@ -# Displays - -> 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) diff --git a/docs/concepts/fields.md b/docs/concepts/fields.md deleted file mode 100644 index 44ae985fef..0000000000 --- a/docs/concepts/fields.md +++ /dev/null @@ -1,35 +0,0 @@ -# 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 that don't save data at all, such as dividers and action buttons. - -::: - -#### Relevant Guides - -- [Creating a Field](/guides/fields/#creating-a-field) -- [Duplicating Fields](/guides/fields/#duplicating-a-field) -- [Adjusting Field Layout](/guides/fields/#adjusting-field-layout) -- [Deleting Fields](/guides/fields/#deleting-a-field) diff --git a/docs/concepts/files.md b/docs/concepts/files.md deleted file mode 100644 index d7933449d2..0000000000 --- a/docs/concepts/files.md +++ /dev/null @@ -1,60 +0,0 @@ -# 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 -or 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 -- **Azure Blob Storage** — Azure storage account containers - -## 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) diff --git a/docs/concepts/interfaces.md b/docs/concepts/interfaces.md deleted file mode 100644 index 1cf6e0939e..0000000000 --- a/docs/concepts/interfaces.md +++ /dev/null @@ -1,45 +0,0 @@ -# Interfaces - -> 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) diff --git a/docs/concepts/items.md b/docs/concepts/items.md deleted file mode 100644 index 5f6f0da80f..0000000000 --- a/docs/concepts/items.md +++ /dev/null @@ -1,19 +0,0 @@ -# Items - -> An Item is an object within a Collection that contains the values for one or more fields. Each item 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) diff --git a/docs/concepts/layouts.md b/docs/concepts/layouts.md deleted file mode 100644 index a468dc3f91..0000000000 --- a/docs/concepts/layouts.md +++ /dev/null @@ -1,52 +0,0 @@ -# Layouts - -> 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 - - - -## 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) diff --git a/docs/concepts/modules.md b/docs/concepts/modules.md deleted file mode 100644 index e8fd47f447..0000000000 --- a/docs/concepts/modules.md +++ /dev/null @@ -1,27 +0,0 @@ -# Modules - -> 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) diff --git a/docs/concepts/permissions.md b/docs/concepts/permissions.md deleted file mode 100644 index 17f05970e9..0000000000 --- a/docs/concepts/permissions.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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) diff --git a/docs/concepts/projects.md b/docs/concepts/projects.md deleted file mode 100644 index a874b47654..0000000000 --- a/docs/concepts/projects.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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. diff --git a/docs/concepts/relationships.md b/docs/concepts/relationships.md deleted file mode 100644 index 8c7cebe62a..0000000000 --- a/docs/concepts/relationships.md +++ /dev/null @@ -1,152 +0,0 @@ -# Relationships - -> 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. - -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. - -### Primary and Foreign Keys - -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. - -To link items together relationally, you simply save a reference of an item's PK in a different field. That _reference_ -is called a Foreign Key (FK). - -::: tip Compound Keys - -To keep things simple, we've ignored compound keys in the above explanation. - -::: - -### Perspective Matters - -Just like primary and foreign keys are directional, relationships are always relative to their "parent" collection. -Looking at the same relationship/key from the perspective of a different collection may change or reverse its type. - -## Many-to-One (M2O) - -A Many-to-One (M2O) relationship exists on a field that saves a single FK. For example, a _city_ can only be in one -_country_, but a _country_ can have many _cities_. So the M2O data model would look like this: - -``` -cities ("Many" Collection) -- id (PK) -- name -- country (M2O that stores the FK to a country) - -country ("One" Collection) -- id (PK, the value saved to "cities.country") -- name -``` - -## One-to-Many (O2M) - -A One-to-Many (O2M) relationship uses an alias field to reference one or more FKs in a M2O. This is the _exact same_ -relationship as the M2O above, but looking at it from the opposite perspective (see -[Perspective Matters](#perspective-matters)). So the O2M data model is the same, but adds an alias "cities" field to the -Country collection, like this: - -``` -country ("One" Collection) -- id (PK, the value saved to "cities.country") -- name -- *cities* (O2M alias field that pulls in references from "cities.country") - -cities ("Many" Collection) -- id (PK) -- name -- country (stores the FK to a country) -``` - -::: tip Manual Reordering - -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/translations/#content-translations) -relationally. It is a standard O2M relationship with an additional field on the "many" collection to hold the language -key. - -::: - -## Many-to-Many (M2M) - -A Many-to-Many (M2M) relationship uses a "Junction Table" to connect many items from one collection, to many items of -another collection. For example, a _recipe_ can have many _ingredients_, and _ingredients_ can be in many _recipes_. So -the M2M data model would look like this: - -``` -recipes (Collection) -- id (PK, the value saved to "recipe_ingredients.recipe") -- name -- *ingredients* (M2M/O2M alias field that pulls in references from recipe_ingredients) - -ingredients (Collection) -- id (PK, the value saved to "recipe_ingredients.ingredient") -- name -- *recipes* (M2M/O2M alias field that pulls in references from recipe_ingredients) - -recipe_ingredients (Junction Collection) -- id (PK) -- recipe (stores the FK to a recipe) -- ingredient (stores the FK to a ingredient) -- quantity -``` - -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. - -::: 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 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). - -::: - -::: tip Self-Referencing - -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 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](/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_. - -## Many-to-Any (M2A) - -Sometimes called a "matrix field" or "replicator", the Many-to-Any (M2A) relationship is essentially the same as a M2M, -but with one crucial difference: the junction table also stores the _parent collection name of the FK_. This "compound -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 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. diff --git a/docs/concepts/revisions.md b/docs/concepts/revisions.md deleted file mode 100644 index d37ac8be8a..0000000000 --- a/docs/concepts/revisions.md +++ /dev/null @@ -1,34 +0,0 @@ -# Revisions & Versioning - -> 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 - - - -#### Relevant Guides - -- [Reverting an Item](/guides/items/#reverting-an-item) diff --git a/docs/concepts/roles.md b/docs/concepts/roles.md deleted file mode 100644 index 2dfe8f51c4..0000000000 --- a/docs/concepts/roles.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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. diff --git a/docs/concepts/translations.md b/docs/concepts/translations.md deleted file mode 100644 index fe407d63d2..0000000000 --- a/docs/concepts/translations.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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. diff --git a/docs/concepts/types.md b/docs/concepts/types.md deleted file mode 100644 index d82899cf2e..0000000000 --- a/docs/concepts/types.md +++ /dev/null @@ -1,46 +0,0 @@ -# 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 - -::: tip Aliases - -There is also an **Alias** type that is used for all fields that do not have a corresponding database column. This -includes presentation-only fields, and certain relational fields, such as the One-to-Many. - -::: diff --git a/docs/concepts/users.md b/docs/concepts/users.md deleted file mode 100644 index 4983776beb..0000000000 --- a/docs/concepts/users.md +++ /dev/null @@ -1,49 +0,0 @@ -# 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 diff --git a/docs/configuration/activity-log.md b/docs/configuration/activity-log.md new file mode 100644 index 0000000000..62e61c15e9 --- /dev/null +++ b/docs/configuration/activity-log.md @@ -0,0 +1,28 @@ +# Activity Log + +> This module provides a collective timeline of all actions taken within the project. These detailed records allow for +> auditing user activity and enforcing accountability. + +The Activity Log is the only module that is not found in the module bar. Instead, it is accessed via the notifications +tray of the [Sidebar](#). This page has the same features and configuration as [Collection Page](#collection-detail). +It's also worth noting that the activity of a _specific_ item is available via the Revisions sidebar of its individual +[Item Page](/concepts/application/#item-detail). + +For proper accountability, activity items are **readonly** by design, though administrators may have access to make +certain updates. The following information is stored for each event's activity item: + +- **User** — The platform 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 + +::: warning External Changes + +The platform can only track the events which actually pass through it. Therefore, changes made to the database +_directly_ are not tracked. + +::: diff --git a/docs/configuration/data-model.md b/docs/configuration/data-model.md new file mode 100644 index 0000000000..6c7984b3be --- /dev/null +++ b/docs/configuration/data-model.md @@ -0,0 +1,301 @@ +# Data Model + +> The data model describes the structure of your database's schema using [Collections](#) (database tables) and +> [Fields](#) (database columns). + +[[toc]] + +## Creating a Collection + +1. Click the **Create Collection** action button in the Data Model header +2. Enter a unique **Collection Name** to be used as the database table name, API collection key, and App collection name + default. +3. Configure the name and type of the **Primary Key**. + - Auto-Incremented Integer + - Generated UUID + - Manually Entered String +4. Optional: Enable and rename any desired **System Fields**. + - Status + - Sort + - Created On + - Created By + - Updated On + - Updated By +5. Click the **Finish Setup** button + +::: danger Immutable Keys + +As of now, the key can not be modified after the collections has been created. + +::: + +::: tip Database Tables + +Keep in mind that a Directus Collection is just a database table. Therefore you can import or create a table directly in +the database, and it will automatically appear within Directus. The first time you manage that table, a +`directus_collections` record will be created with default values. + +::: + +## Configuring a Collection + +You can configure a collection by clicking on it within **Settings > Data Model**. On this page the following options +are available: + +- **Fields & Layout** — This manages the fields of this collection, and their form layout. For more information on this + configuration, refer to the sections below on Field Management. + - [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 Name** — This is the key for the collection. It can not be modified, but you can override it with + Translations (see field below). +- **Note** — A helpful note that explains the collection's purpose +- **Icon** — The icon used throughout the App when referencing this collection +- **Color** — A color for the icon, shown in the navigation and its header +- **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 Page](/concepts/application/#collection-detail) will be bypassed, taking users directly to the + [Item Page](/concepts/application/#item-detail). +- **Collection Naming Translations** — While the collection key can not be changed (as of now), this option allows + translating the collection name into different languages. By default, the platform uses the [Title Formatter](#) to + display collection keys as human readable names, but you can also use translations to explicitly rename more technical + table keys. + +### Archive + +The archive feature allows you to enable "soft-delete" within the collection. Archived items are hidden in the App by +default, but are still returned normally via the API unless they are filtered out. + +- **Archive Field** — The field that holds the archive value +- **Archive App Filter** — Allows users to view archived items +- **Archive Value** — The value saved in the Archive Field when archived +- **Unarchive Value** — The value saved in the Archive Field when unarchived + +::: 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. + +::: + +### Sort + +The sort feature enables manual drag-and-drop item reordering within the Directus App. This is typically shown on the +[Collection Page](/concepts/application/#collection-detail), but can also be used for sorting items within +[Junction Tables](#). Configuration is as easy as selecting the appropriate sort field: + +- **Sort Field** — Choose a field with the `integer` type. You may want to set this field to be "hidden" so it doesn't + show up within the Item Page form. + +::: 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. + +::: + +::: tip Interface Sorting + +To configure manual sorting within an Interface (eg: M2M, O2M, or M2A), configure as above, but also set the **Sort +Field** on the field's Relationship pane. + +::: + +### Accountability + +By default, the platform tracks all [activity](#) and [revisions](#) for collections. This option allows you to override +this, choosing what data is tracked. + +- **Activity & Revision Tracking** — supports the follow options: + - Track Activity & Revisions + - Only Track Activity + - Do Not Track Anything + +### Duplication + +The "Save as Copy" option on the Item Page offers a way to effectively duplicate the current item. However, since there +may be unique or relational data within this form, it's important to control exactly what will be copied. This option +allows for configuring which parent/relational field values will be copied. + +## Deleting a Collection + +1. Navigate to **Settings > Data Model > [Collection Name]** +2. Click the red **Delete Collection** action button in the header +3. Confirm this decision by clicking **Delete** in the dialog + +::: danger Irreversible Change + +This action is permanent and can not be undone. Please proceed with caution. + +::: + +## Adjusting the Collection Hierarchy + +Collections can be organized in several ways. + +## Adjusting the Collection Form + +The [Item Page](#) displays a custom form for viewing and editing each collection's fields. This form is is highly +configurable, with the following field options: + +- **Visibility** — Fields can be set to "visible" or "hidden" on the form. This is adjusted via the field's context menu + or edit drawer. +- **Width** — Fields have three different width options relative to the form/page. This is adjusted via the field's + context menu or edit drawer. + - Half — The field is shown at half the form width + - Full — (Default) The field is shown at the full form width + - Fill — The field is shown filling the page width +- **Sort** — Fields can be rearranged via their drag-and-drop handles. +- **Grouping** — Fields can be organized within different nested groups that are created using the normal Creating a + Field flow. Different style groupings are available for different use-cases. + +## Creating a Field + +1. Navigate to **Settings > Data Model > [Collection Name]** +2. Under Fields & Layout, click the **Create Field** button +3. **Choose the field type**, and follow its setup steps below. + +::: tip Database Columns + +Keep in mind that a Directus Field is just a database columns. Therefore you can create a columns directly in the +database, and it will automatically appear within Directus using intelligent defaults. You can then enhance the +experience further using the following steps. + +::: + +### Schema + +This pane controls the technical details of the field's database column. + +- **Key** — (Required) The database column name and field's API key. The key must be unique within its parent + Collection. As of now, all keys are sanitized: lowercased, alphanumeric, and with spaces removed. Keys can not be + changed once created, however you can use [Field Name Translations](#) to override how it's displayed in the App. +- **Type** — (Required) How the data is saved to the database; See [Directus Data Type Superset](/concepts/types). This + dropdown maybe be limited or even disabled based on your chosen Field category. +- **Length** — (Only for certain types) For String types this determines the number of characters that can be stored in + the database. For Float and Decimal types, this control becomes **Precision & Scale**. +- **On Create** — (Only for certain types) For some data types, this option allows you to control what value is saved + when an item is created. These values are fallbacks and can be overridden by the App/API. For example, the Timestamp + type allows you to "Save Current Date/Time". +- **On Update** — (Only for certain types) For some data types, this option allows you to control what value is saved + when an item is updated. These values are fallbacks and can be overridden by the App/API. For example, the UUID type + allows you to "Save Current User ID". +- **Default Value** — This is the initial value shown for a field when creating an item in the App. If creating an item + via the API, this is the fallback value saved to the database if a field value is not submitted. +- **Allow NULL** — Toggles if the database column is nullable. When disabled, a `NULL` value can not be saved to the + field's column. +- **Unique** — Toggles if the database column's values must all be unique. + +::: danger Immutable Keys + +As of now, the key can not be modified after the field has been created. + +::: + +### Relationship + +This pane is only shown when configuring relational fields (including images and translations). Depending on the type of +relationship, you'll be presented with one of the following set of options: + +- [Many-to-One](#) +- [One-to-Many](#) +- [Many-to-Many](#) +- [Many-to-Any](#) +- [Translations](#) + +::: tip Corresponding Field + +[Relationships go both ways](/concepts/relationships/#perspective-matters), so when creating a new relation Field, +Directus offers to automatically create the corresponding Field on the related Collection. + +::: + +### Field + +- **Required** — Toggles if a value for the Field is required. + - Empty strings (`''`) and `NULL` are **not** accepted as a valid value + - `0` and `false` are accepted as a valid value + - Default values are accepted as a valid value + - Permission Presets are accepted as a valid value +- **Readonly** — (App Only) Sets the field to be disabled. +- **Hidden** — (App Only) Hides the field in the App form. + - The field is still available in filters and Layout options. +- **Note** — (App Only) Displayed below the field in the App form, providing a helpful comment for App users. This note + supports markdown. +- **Field Name Translations** — (App Only) While the field key can not be changed (as of now), this option allows + translating the field name into different languages. By default, the platform uses the [Title Formatter](#) to display + field keys as human readable names, but you can also use translations to explicitly rename more technical column keys. + +### Interface + +This pane includes any customization options that may be defined by the Interface. + +### Display + +This pane includes any customization options that may be defined by the Display. + +### Conditions + +Conditions allow you to alter the current field's setup based on the values of other fields in the form. This allows you +to show/hide the field, make it readonly, or change the interface options. + +Each field can have one or more _rules_. Each rule has the following configuration options: + +- **Name**: The name of the rule. This is only used internally for convenience purposes +- **Rule**: The rule that controls whether or not these conditions are applied. Rule follows the + [Filter Rules](/reference/filter-rules) spec +- **Readonly**: Whether or not the field is readonly when the condition is matched +- **Hidden**: Whether or not the field is hidden when the condition is matched +- **Interface Options**: Any additional configuration for the selected interface + +These changes to the field are merged onto the base configuration of the field. This means you can have the field hidden +by default, and then only toggle the hidden state of the field in the condition. + +::: tip Order Matters + +The conditions are matched in order. The **last** condition that matches is the one that's used to apply the changes. + +::: + +## Configuring a Field + +1. Navigate to **Settings > Data Model > [Collection Name]** +2. Click the field you want to update +3. Make any desired updates referencing the [Creating a Field](#) docs above + +::: 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. To get started, enable System Collections within the sidebar filter of +[Settings > Data Model](/concepts/databases/). + +::: + +## Duplicating a Field + +1. Navigate to **Settings > Data Model > [Collection Name]** +2. Click the **More Options** icon for the field you want to duplicate +3. Click the **Duplicate Field** option + +::: warning Relational and Primary Key Fields + +It is not currently possible to duplicate relational fields or a collection's primary key. + +::: + +## Deleting a Field + +1. Navigate to **Settings > Data Model > [Collection Name]** +2. Click the **More Options** icon for the field you want to delete +3. Click the **Delete Field** option +4. Confirm this decision by clicking **Delete** in the dialog + +::: danger Irreversible Change + +This action is permanent and can not be undone. Please proceed with caution. + +::: diff --git a/docs/reference/common-issues.md b/docs/configuration/faq.md similarity index 85% rename from docs/reference/common-issues.md rename to docs/configuration/faq.md index ccc16eb77e..566588eb6d 100644 --- a/docs/reference/common-issues.md +++ b/docs/configuration/faq.md @@ -1,4 +1,4 @@ -# Common Issues +# Frequently Asked Questions > TK diff --git a/docs/reference/filter-rules.md b/docs/configuration/filter-rules.md similarity index 100% rename from docs/reference/filter-rules.md rename to docs/configuration/filter-rules.md diff --git a/docs/configuration/installation.md b/docs/configuration/installation.md new file mode 100644 index 0000000000..39367e2c82 --- /dev/null +++ b/docs/configuration/installation.md @@ -0,0 +1,3 @@ +# Installation + +> TK diff --git a/docs/guides/installation/aws.md b/docs/configuration/installation/aws.md similarity index 100% rename from docs/guides/installation/aws.md rename to docs/configuration/installation/aws.md diff --git a/docs/guides/installation/cli.md b/docs/configuration/installation/cli.md similarity index 100% rename from docs/guides/installation/cli.md rename to docs/configuration/installation/cli.md diff --git a/docs/guides/installation/digitalocean-app-platform.md b/docs/configuration/installation/digitalocean-app-platform.md similarity index 100% rename from docs/guides/installation/digitalocean-app-platform.md rename to docs/configuration/installation/digitalocean-app-platform.md diff --git a/docs/guides/installation/docker.md b/docs/configuration/installation/docker.md similarity index 100% rename from docs/guides/installation/docker.md rename to docs/configuration/installation/docker.md diff --git a/docs/guides/installation/iis.md b/docs/configuration/installation/iis.md similarity index 100% rename from docs/guides/installation/iis.md rename to docs/configuration/installation/iis.md diff --git a/docs/guides/installation/manual.md b/docs/configuration/installation/manual.md similarity index 100% rename from docs/guides/installation/manual.md rename to docs/configuration/installation/manual.md diff --git a/docs/guides/installation/plesk.md b/docs/configuration/installation/plesk.md similarity index 100% rename from docs/guides/installation/plesk.md rename to docs/configuration/installation/plesk.md diff --git a/docs/guides/installation/ubuntu.md b/docs/configuration/installation/ubuntu.md similarity index 100% rename from docs/guides/installation/ubuntu.md rename to docs/configuration/installation/ubuntu.md diff --git a/docs/configuration/localization.md b/docs/configuration/localization.md new file mode 100644 index 0000000000..bccff2c7a5 --- /dev/null +++ b/docs/configuration/localization.md @@ -0,0 +1,11 @@ +# Localization + +> TK + +## Content Translations + +## Multilingual App & Locales + +## Iconography + +## RTL Support diff --git a/docs/configuration/overview.md b/docs/configuration/overview.md new file mode 100644 index 0000000000..983ac7350c --- /dev/null +++ b/docs/configuration/overview.md @@ -0,0 +1,6 @@ +# Configuring the Platform + +> The vast flexibility of Directus is due to its thoughtful configuration options. This section guides administrators +> through the process of installing a blank instance and then completely tailoring the project to your needs. + +**Include GUI Sections Here** diff --git a/docs/guides/presets.md b/docs/configuration/presets-bookmarks.md similarity index 75% rename from docs/guides/presets.md rename to docs/configuration/presets-bookmarks.md index 1235694594..4f925b63ca 100644 --- a/docs/guides/presets.md +++ b/docs/configuration/presets-bookmarks.md @@ -15,11 +15,20 @@ - **Name** — If left blank, this preset will act as a Default for the collection/layout; if given a name, it will be shown as a bookmark -After you have completed the form, the layout preview will be populated with live data. You can now tailor the layout as -desired by updating the preview or the filter component in the page sidebar. +After you have completed the form, the layout preview will be populated with live data. **You can now tailor the layout +as desired by updating the preview or the filter component in the page sidebar.** -Each preset saves all of the information needed to recreate a view of the collection/layou, including: the full-text -search query, any advanced filters added, sort field, sort direction, and all other specific layout options. +Each preset saves all of the information needed to recreate a view of the collection/layout, including: + +- **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 ::: tip Defaults vs Bookmarks diff --git a/docs/configuration/project-settings.md b/docs/configuration/project-settings.md new file mode 100644 index 0000000000..9b103b48cc --- /dev/null +++ b/docs/configuration/project-settings.md @@ -0,0 +1,81 @@ +# Project Settings + +> This is where you can adjust all of the **global** settings for your project. Changes saved here are instantly +> reflected throughout the platform. + +## Branding + +- **Project Name** — The name used at the top of the [Navigation Bar](/concepts/application/#_2-navigation-bar) and on + the login/public pages +- **Project URL** — The URL when clicking the logo at the top of the [Module Bar](/concepts/application/#_1-module-bar) +- **Project Color** — The color used behind the logo at the top of the + [Module Bar](/concepts/application/#_1-module-bar), 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/application/#_1-module-bar) 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. +- **CSS Overrides** — Allows for adding CSS rules to override the App's default styling. Be aware that the App's core + code, and therefore its DOM selectors, can change at any time. These updates are not considered a breaking change. + +::: tip Browser FavIcon & Title + +The Project Color is also used to set a dynamic favicon and the Project Name is used in the browser's page title, making +it easier to identify different Directus projects. + +::: + +## Public Pages + +In addition to the above global Project Settings, you can also apply the following styling to tailor your project's +[public pages](/guides/projects/#public-pages). + +- **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 + +The platform's file middleware allows for cropping and transforming image assets on the fly. This means you can simply +request an original image, include any desired transformation parameters, and you'll be served the new asset as a +response. + +To impede malicious users from consuming your storage by requesting a large number of random sizes, you can use the +following options to limit what transformations are possible. + +- **Storage Asset Presets** — Allows setting specific image transformations to simplify requests or limit usage. + - Key — A unique identifier allowing faster and easier image transformation requests + - Fit — Contain (preserve aspect ratio), Cover (force exact size), Fit Inside, or Fit Outside + - Width — The width of the image + - Height — The height of the image + - Quality — The compression or quality of the image + - Without Enlargement — When enabled, images won't be upscaled + - Format — Allows changing the output format to: JPG, PNG, WebP, or TIFF + - Transforms — Allows adding additional transformations using [Sharp](https://sharp.pixelplumbing.com/api-constructor) +- **Storage Asset Transform** — For enabling, disabling, or limiting image transformations +- **Storage Default Folder** — Sets the default folder where new assets are added. This does not affect existing files. + Be aware that fields may override this value. + +## Mapping + +- **Mapbox Access Token** — Create a [Mapbox Access Token](https://docs.mapbox.com/help/glossary/access-token/) and + enter it here to improve the platform's mapping experience. +- **Basemaps** — Allows overriding the Mapbox defaults with custom tiles + +## Module Bar + +Allows the following customization of links displayed in the module bar. Show or hide modules by toggling the checkbox, +reorder links by dragging on the sort handle, or create new custom links with these fields: + +- **Name** — The title of the module link, also shown in a tooltip on hover +- **Icon** — Choose an icon for the module button +- **URL** — Should start with a `/` for links within the [Directus App](/concepts/application/#the-directus-application) diff --git a/docs/configuration/relationships.md b/docs/configuration/relationships.md new file mode 100644 index 0000000000..3138a22887 --- /dev/null +++ b/docs/configuration/relationships.md @@ -0,0 +1,320 @@ +# Relationships + +> 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. + +[[toc]] + +### Introduction + +While it may seem complex at first, relational data is actually quite straightforward once you understand what's +happening behind the sometimes confusing terminology. Before diving into the details of each type, let's first cover a +few basics that will help you better visualize them in your mind's eye. + +### Primary and Foreign Keys + +Every [Item](/glossary#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. + +To link items together relationally, you simply save a reference to an item's PK in a different field. That _reference_ +is called a Foreign Key (FK). If the primary key is a _person_, the foreign key is like their _business card_. It +references the actual person, providing just enough information to find them. + +::: tip Composite & Compound Keys + +In the above explanation we've ignored _composite_ and _compound_ keys, which are essentially unique keys created by +combining _multiple_ field/column values. + +::: + +### Perspective Matters + +Just like primary and foreign keys, relationships are always described relative to their "parent" collection. Looking at +the same relationship/key from the perspective of the opposite collection would reverse it. This means that a +many-to-one relationship can also be seen as a one-to-many relationship, it just depends on which collection is +considered the parent. + +## Many-to-One (M2O) + +The Many-to-One is the only relationship type with an actual field on the parent Collection. This field saves the +foreign key to a single related item. For example, a _city_ can only be in one _country_, but a _country_ can have many +_cities_. + +Below is an example of a M2O relationship: + +``` +cities (the "Many" Collection) +- id (Primary Key) +- name +- country (the M2O field that stores the country key) + +countries (the "One" Collection) +- id (Primary Key) +- name +``` + +### Setup + +![M2O](../assets/guides/fields/m2o.png) + +The parent collection and field are already known (it's the field you're currently creating), so configuring those are +disabled. All you need to configure is the related collection and its primary key field. + +If you select or enter an **existing** Related Collection (highlights green) then the primary key field is known and +automatically selected. If you enter the name of a **new** Related Collection (doesn't already exist), you will also be +prompted to enter the name of its primary key field, which will default to an auto-increment integer type. + +You also have the option to create a **Corresponding Field** during this process. This allows you to more easily create +the O2M alias (see below) that pairs with with this M2O. + +**Relational Triggers** allow for control over what happens when a relationship is broken. There is one option: + +- **On Delete of [Related Collection]** — When the related item (O2M) is deleted... + - Nullify the parent M2O field (default) + - Set the parent M2O field to its default value + - Delete the parent collection's item (cascade) + - Prevent the deletion + +## One-to-Many (O2M) + +The One-to-Many relationship is the **exact same relationship** as a Many-to-One (above), just seen from the opposite +collection's perspective. The O2M is stored as an [Alias](/glossary/#alias) field on its parent Collection that +dynamically lists all items connected via the opposite Many-to-One. So, while the M2O will show a single country for the +parent city, the O2M shows all cities for the parent country. + +Below is an example of a O2M relationship: + +``` +countries (the "One" Collection) +- id (Primary Key) +- name +- *cities* (the O2M alias field that lists references from "cities.country") + +cities (the "Many" Collection) +- id (Primary Key) +- name +- country (the M2O field that stores the country key) +``` + +### Setup + +![O2M](../assets/guides/fields/o2m.png) + +The parent collection and field are already known (it's the field you're currently creating), so configuring those are +disabled. All you need to configure is the related collection and its M2O field. + +You can select or enter an **existing** Related Collection (highlights green) or create a **new** one by entering a +unique collection name. Next, you can select an existing field (highlights green) or create a new one by entering a +field name unique to its collection. + +The related field will store the value of this collection's primary key field, so both must have the same type. For this +reason, when selecting existing fields, options will be disabled if they don't have a matching type. + +You also have the option to create a **Corresponding Field** during this process. This allows you to more easily create +the M2O field (see above) that pairs with with this O2M. + +The optional **Sort Field** can be used enable manual reordering of items within this O2M field. This is configured by +selecting an existing numeric type field (highlights green) from the Related Collection, or entering the name of a new +field to be created. + +**Relational Triggers** allow for control over what happens when a relationship is broken. There are two options: + +- **On Deselect of [Related Collection]** — When the value of the M2O is deselected... + - Nullify the M2O field value (default) + - Delete the M2O item (cascade) +- **On Delete of [Parent Collection Item]** — When this O2M item is deleted... + - Nullify the related M2O field (default) + - Set the related M2O field to its default value + - Delete the related collection's item (cascade) + - Prevent the deletion + +## Translations (O2M) + +The Translations relationship is just a special version of the standard O2M. Just like the O2M, it creates an +[Alias](/glossary/#fields) field that is used to list all related items (the translations). Translations themselves are +stored in a separate collection, which is then further related to _third_ collection that stores all languages. + +### Setup + +![Translations](../assets/guides/fields/translations.png) + +The easiest way to add translations is to use the wizard, which only asks for the Translation field name. All required +fields and relationships will then be automatically created and configured. + +![Translations](../assets/guides/fields/translations-2.png) + +If you choose to switch to **manual setup**, you will be presented with a similar relationship setup to O2M or M2M. The +parent collection and primary key are know, so those fields are disabled. + +Next, we configure the Translation Collection. Set to "Auto Fill" by default, this will enter intelligent naming based +on related names, and disables all fields. Disabling Auto Fill will enable all fields, allowing you to name the +collection that holds the translations, as well as the two fields (each a M2O) that store foreign keys to the parent +item and language. + +Lastly, you would select/create the Languages collection, which stores the languages available for this translations +field. It is common practice to reuse a single languages collection throughout your project, unless translation fields +need to support different language sets. For the language `code` we recommend using the IETF language tag (eg: `en-US`) +which combines the ISO 639-1 and ISO 3166‑1 standards, but anything can be used (eg: `english`). + +## Many-to-Many (M2M) + +The Many-to-Many relationship is actually just **two relationships combined** (O2M+M2O) that join together three +different collections. The M2M is stored as an [Alias](/glossary/#alias) field on its parent Collection that dynamically +lists all items connected via a [junction collection](#). For example, a _recipe_ can have many _ingredients_, and +_ingredients_ can be in many _recipes_. + +Below is an example of a M2M relationship: + +``` +recipes (Collection) +- id (Primary Key) +- name +- *ingredients* (M2M/O2M alias field that lists references from "recipe_ingredients") + +ingredients (Collection) +- id (Primary Key) +- name +- *recipes* (M2M/O2M alias field that lists references from "recipe_ingredients") + +recipe_ingredients (Junction Collection) +- id (Primary Key) +- recipe (stores the recipe key) +- ingredient (stores ingredient key) +- quantity (other optional data on the connection) +``` + +Notice that the example above also has a `quantity` field on the Junction Collection, which tracks how much of each +ingredient is needed for the recipe. You can add any other _contextual_ fields to the junction, and they will also be +included at the top of the App's relational Item Page form. + +::: tip Self-Referencing + +You can also have a M2M relationship that connects items within the _same_ collection. An example of this is "Related +Articles", where an article might relate to many other articles. + +::: + +### Setup + +![M2M](../assets/guides/fields/m2m.png) + +The parent collection and field are already known (it's the field you're currently creating), so configuring those are +disabled. + +Next you should configure the Related Collection. If you select or enter an **existing** Related Collection (highlights +green) then the primary key field is known and automatically selected. If you enter the name of a **new** Related +Collection (doesn't already exist), you will also be prompted to enter the name of its primary key field, which will +default to an auto-increment integer type. + +Lastly, we configure the [Junction Collection](#), which sits between the two related collections, storing all links +between the two. You can leave this set to "Auto-Fill", which sets intelligent naming defaults, or disable it to select +existing options or enter custom names. + +You also have the option to create a **Corresponding Field** during this process. This allows you to more easily create +the reverse M2M field on the _related_ collection. + +The optional **Sort Field** can be used enable manual reordering of items within this O2M field. This is configured by +selecting an existing numeric type field (highlights green) from the Junction Collection, or entering the name of a new +field to be created. + +**Relational Triggers** allow for control over what happens when a relationship is broken. There are three options: + +- **On Deselect of [Junction Collection]** — When the value of this M2M is deselected... + - Nullify the junction field (default) + - Delete the junction item (cascade) +- **On Delete of [Parent Collection Item]** — When this M2M item is deleted... + - Nullify the junction field (default) + - Set the junction field to its default value + - Delete the related junction item (cascade) + - Prevent the deletion +- **On Delete of [Related Collection Item]** — When the related M2M item is deleted... + - Nullify the junction field (default) + - Set the junction field to its default value + - Delete the related junction item (cascade) + - Prevent the deletion + +## Many-to-Any (M2A) + +Sometimes called a "matrix field" or "replicator". Like the M2M, the M2A is stored as an [Alias](/glossary/#alias) field +on its parent Collection that dynamically lists all items connected via a [junction collection](#). However, there is +one key difference: one side of the junction also stores a **collection key**. This combination of collection name and +primary key means that you can effectively store a reference to _any_ item in the database. You can then artificially +limit which collections are valid through an related collections "allow list". + +An common example of a M2A is a "Page Builder", which has a _Pages_ collection that includes any number of different +"section" Collections, such as: "Heading", "Text", and "Image". In this example the junction table will link different +sections (from different collections) with a page, creating relational layouts. + +Below is an example of a M2A relationship: + +``` +pages (Collection) +- id (Primary Key) +- name +- *sections* (O2M/M2A alias field that lists references from "sections") + +headings (Collection) +- id (Primary Key) +- title +- *section* (alias field that lists references from "sections") + +text (Collection) +- id (Primary Key) +- text +- *section* (alias field that lists references from "sections") + +images (Collection) +- id (Primary Key) +- file +- *section* (alias field that lists references from "sections") + +page_sections (Junction Collection) +- id (Primary Key) +- page (stores the page key) +- section (stores section key) +- section_collection (determines which collection the section_id belongs to) +``` + +### Setup + +![M2A](../assets/guides/fields/m2a.png) + +The parent collection and field are already known (it's the field you're currently creating), so configuring those are +disabled. + +Next, we configure the [Junction Collection](#), which sits between the related collections, storing all links between +them. You can leave this set to "Auto-Fill", which sets intelligent naming defaults, or disable it to select existing +options or enter custom names. + +Lastly, you should select any desired Related Collections. Unlike other relationships, you can't _create_ these related +collections here, so ensure all related collections you need are created before hand. + +The optional **Sort Field** can be used enable manual reordering of items within this M2A field. This is configured by +selecting an existing numeric type field (highlights green) from the Junction Collection, or entering the name of a new +field to be created. + +**Relational Triggers** allow for control over what happens when a relationship is broken. There are three options: + +- **On Delete of [Parent Collection Item]** — When a M2A item is deleted... + - Nullify the junction field (default) + - Set the junction field to its default value + - Delete the related junction item (cascade) + - Prevent the deletion +- **On Deselect of [Junction Collection]** — When the value of this M2A is deselected... + - Nullify the junction field (default) + - Delete the junction item (cascade) + +## One-to-One (O2O) + +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](/guides/api-hooks) or +[custom interface](/guides/interfaces). + +An example of this is a _person_ only has one unique set of _fingerprints_, and those _fingerprints_ only belong to one +_person_. diff --git a/docs/configuration/security.md b/docs/configuration/security.md new file mode 100644 index 0000000000..6b11fbe343 --- /dev/null +++ b/docs/configuration/security.md @@ -0,0 +1,23 @@ +# Security + +> TK + +## HTTPS + +## Password Salting/Hashing/Algorithm & Password Policy + +## Static Tokens + +## Encrypted Fields & Encrypted Database + +## Private File Links + +## MFA (Required) & SSO + +## Granular Access Control & IP WHite-Listing & App Access + +## Rate Limiting + +## Encrypted + +## Parameterized Database Queries diff --git a/docs/guides/migrating-from-v8.md b/docs/configuration/upgrades-migrations.md similarity index 57% rename from docs/guides/migrating-from-v8.md rename to docs/configuration/upgrades-migrations.md index 2b8c84d491..e90dba4a03 100644 --- a/docs/guides/migrating-from-v8.md +++ b/docs/configuration/upgrades-migrations.md @@ -1,4 +1,57 @@ -# Migrating from v8 +# Upgrades & Migrations + +> 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/). + +## Upgrading / Updating a Project + +1. Backup your project +2. Run `npm update` +3. Run `npx directus database migrate:latest` to update the DB + +## Backing-up a Project + +1. Make a copy of the **files within each storage adapter**, and store them in a safe place +2. Make a copy of the **Env file** (`/api/.env`), and store it in a safe place +3. Create a database dump + +## 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. + +::: + +## Downgrading a Project + +Directus can be reverted to an earlier version by going to your terminal, navigating into your project folder and +running `npm install directus@`. + +If you ran any database migrations for a newer version, you can revert those by running +`npx directus database migrate:down` + +## Deleting a Project + +1. Optional: **Backup any local files** stored within the project's root directory +2. Optional: **Backup any custom code and extensions** within the project's root directory +3. Optional: **Backup your entire database**, only system tables, or only project tables +4. **Delete the project's root directory** from the server +5. **Delete all Directus system tables** (`directus_*`) from the database + +::: tip Pure SQL + +After completing this process, you will be left with a pure SQL database, with no trace that Directus was ever +installed. Any external services connecting to your database's project tables directly (eg: SQL queries) should continue +working normally. + +::: + +## Migrating from v8 There are two ways to migrate from an existing Directus 8.X instance: diff --git a/docs/configuration/users-roles-permissions.md b/docs/configuration/users-roles-permissions.md new file mode 100644 index 0000000000..abb500a42a --- /dev/null +++ b/docs/configuration/users-roles-permissions.md @@ -0,0 +1,222 @@ +# Users, Roles & Permissions + +> [Users](/getting-started/glossary#users) are the individual accounts for authenticating into the API and App. Each +> user belongs to a [Role](/getting-started/glossary#roles) which defines its access +> [Permissions](/getting-started/glossary#permissions). + +[[toc]] + +## Creating a User + +1. Navigate to the **User Library** +2. Click the **Create User** action button in the header +3. Enter an **Email Address** +4. Optional: Complete the **other user form fields** + +## Inviting a User + +1. Navigate to the **User Library** +2. Click the **Invite Users** button in the header +3. Enter **one or more email addresses**, separated by new lines, in the modal +4. Click **Invite** + +At this point the invited user(s) will receive an email with a link to the App where they set a password and enable +their account. + +## Configuring a User + +1. Navigate to the **User Library** +2. **Click on the user** you wish to manage +3. **Complete the form** of [User Fields](/concepts/application/#user-detail) + +The User Detail is only editable by the current user and admins, and the following fields are only available to admins: + +- **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 + - **Active** — The only status that has proper access to the App and API + - **Suspended** — A user that has been temporarily disabled; no App/API access + - **Archived** — A soft-deleted user; no App/API access +- **Role** — The user's role determines their permissions and access +- **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. + +## Archiving a User + +1. Navigate to the **User Library** +2. Click the user you with to archive to go to their User Detail page +3. Click the orange **Archive User** action button in the header +4. Confirm this decision by clicking **Archive** in the dialog + +::: warning Disables Access + +Archiving uses _soft-delete_, therefore archived users are unable to access the App or API. + +::: + +## Deleting a User + +1. Navigate to the **User Library** +2. Select one or more users you wish to delete +3. Click the red **Delete User** action button in the header +4. Confirm this decision by clicking **Delete** in the dialog + +::: danger Irreversible Change + +Unlike the soft-delete of archiving, this process is a hard-delete. Therefore, this action is permanent and can not be +undone. Please proceed with caution. + +::: + +## Creating a Role + +1. Navigate to **Settings > Roles & Permissions** +2. Click the **Create Role** action button in the header +3. Enter a unique **Role Name** +4. Enabling **App Access** allows logging in to the App +5. Enabling **Admin Access** gives full permission to project data and Settings + +## Configuring a Role + +- **Permissions** — Defines the role's access permissions +- **Role Name** — This is the name of the role +- **Role Icon** — The icon used throughout the App when referencing this role +- **Description** — A helpful note that explains the role's purpose +- **App Access** — Allows logging in to the App +- **Admin Access** — Gives full permission to project data and Settings +- **IP Access** — An allow-list of IP addresses from which the platform can be accessed, empty allows all +- **Require 2FA** — Forces all users within this role to use two-factor authentication +- **Users in Role** — A list of all users within this role +- **Module Navigation** — Overrides the visible modules +- **Collection Navigation** — Overrides the collection module's navigation + +## Deleting a Role + +1. Navigate to **Settings > Roles & Permissions > [Role Name]** +2. Click the red **Delete Role** action button in the header +3. Confirm this decision by clicking **Delete** in the dialog + +::: warning Users in a Deleted Role + +If you delete a role that still has users in it, those users will be given a `NULL` role, which denies their App access +and limits them to the [Public Role](/concepts/roles/#public-role) permissions. They can then be reassigned to a new +role by an admin. + +::: + +::: warning Last Admin + +You must maintain at least one role/user with Admin Access so that you can still properly manage the project. + +::: + +::: warning Public Role + +You can not delete the Public role, as it is part of the core platform. To disable it completely, simply turn off all +Public access permissions. + +::: + +## Configuring 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. + +::: warning Read Field Permissions + +The Directus App always requires read access to the Primary Key field (eg: `id`) so it can uniquely identify items. +Also, if a Collection has "Archive" or "Sort" fields configured, those fields will also need read access to use the +App's soft-delete and manual sorting features. + +::: + +### Update (Custom Access) + +5. **Item Permissions** control which items can be updated, as defined by [Filter Rules](/reference/filter-rules). +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 + [Filter Rules](/reference/filter-rules). +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 Public Permissions + +The Public permissions control what project data is accessible without authentication. This is managed via the Public +"role", which is included in the system by default and can not be deleted. + +::: warning Private by Default + +All of the data within the platform is private by default. Permissions for the public role can be granted on a +case-by-case basis by administrators. + +::: + +### Configuring System Permissions + +In addition to permissions for _your_ custom collections, you can also customize 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 "System Collections" at the bottom of the permissions configuration. + +There are two pre-configured options you can use for resetting the role's system permissions and ensure proper App +access. To access these, click "System Collections" to expand, and then click one of the buttons at the bottom of the +listing. + +- **App Access Minimum** — The minimum permissions required to properly access the App +- **Recommended Defaults** — More permissive but balanced for a better App user experience + +## 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 simple example below. + +1. To create a structured workflow for **Articles**, the first step is [Creating a Field](#) to track the article + "status" — we'll call it **Status**, but it can be named anything. +2. Next, create different Roles for each stage of the workflow, such as `author` and `manager`. +3. Finally, configure the Role permissions based on the possible values of that Status field, such as `draft`, `review`, + `approved`, and `published`, so that they are properly restricted to create content and update the status. + - The Author can create content, but only save a status of `draft` or `review`. + - The Manager has additional permissions that allow them to save statuses of `approved` or `published`. diff --git a/docs/guides/webhooks.md b/docs/configuration/webhooks.md similarity index 96% rename from docs/guides/webhooks.md rename to docs/configuration/webhooks.md index 5ed40c84a4..104479ff60 100644 --- a/docs/guides/webhooks.md +++ b/docs/configuration/webhooks.md @@ -15,7 +15,7 @@ - **Status** — Whether the webhook is active (enabled) or inactive (disabled) - **Data** — Whether the event's data should be sent along with the request - **Trigger Actions** — The specific actions that will trigger the event -- **Trigger Collections** — The specific collections for which the above actions will trigger the event +- **Trigger Collections** — The specific collections for which the above actions will trigger events ## Disabling Webhooks diff --git a/docs/guides/api-endpoints.md b/docs/extensions/api-endpoints.md similarity index 100% rename from docs/guides/api-endpoints.md rename to docs/extensions/api-endpoints.md diff --git a/docs/extensions/app-translations.md b/docs/extensions/app-translations.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/guides/displays.md b/docs/extensions/displays.md similarity index 100% rename from docs/guides/displays.md rename to docs/extensions/displays.md diff --git a/docs/guides/email-templates.md b/docs/extensions/email-templates.md similarity index 100% rename from docs/guides/email-templates.md rename to docs/extensions/email-templates.md diff --git a/docs/guides/api-hooks.md b/docs/extensions/hooks.md similarity index 100% rename from docs/guides/api-hooks.md rename to docs/extensions/hooks.md diff --git a/docs/guides/interfaces.md b/docs/extensions/interfaces.md similarity index 100% rename from docs/guides/interfaces.md rename to docs/extensions/interfaces.md diff --git a/docs/concepts/extensions.md b/docs/extensions/introduction.md similarity index 100% rename from docs/concepts/extensions.md rename to docs/extensions/introduction.md diff --git a/docs/guides/layouts.md b/docs/extensions/layouts.md similarity index 100% rename from docs/guides/layouts.md rename to docs/extensions/layouts.md diff --git a/docs/guides/migrations.md b/docs/extensions/migrations.md similarity index 100% rename from docs/guides/migrations.md rename to docs/extensions/migrations.md diff --git a/docs/guides/modules.md b/docs/extensions/modules.md similarity index 100% rename from docs/guides/modules.md rename to docs/extensions/modules.md diff --git a/docs/extensions/panes.md b/docs/extensions/panes.md new file mode 100644 index 0000000000..85d886b2fe --- /dev/null +++ b/docs/extensions/panes.md @@ -0,0 +1,3 @@ +# Panes + +> TK diff --git a/docs/guides/styles.md b/docs/extensions/themes.md similarity index 100% rename from docs/guides/styles.md rename to docs/extensions/themes.md diff --git a/docs/getting-started/glossary.md b/docs/getting-started/glossary.md new file mode 100644 index 0000000000..e9e38e63c2 --- /dev/null +++ b/docs/getting-started/glossary.md @@ -0,0 +1,377 @@ +# Glossary + +> This is list of platform-specific terminology, and their meanings. Most are simply more approachable names for +> technical database terms. + +[[toc]] + +## Admin / Administrator + +An "Administrators" Role (with Admin access enabled) is included when you first install the platform. All admin roles +bypass the permissions check, providing unrestricted access to all data within the App and API. Additionally, only roles +with the admin option enabled can manage Settings within the app. + +## Alias + +[Fields](#fields) that do not map directly to an actual database column are called "alias" fields. For example, +presentation fields (such as dividers and groups) and certain relational types that display data stored elsewhere (such +as [One-to-Many (O2M)](#) and [Many-to-Many (M2M)](#)). + +## API + +The Application Programming Interface (API) provided by the platform is how you can programmatically connect your +project's content, files, and system information to external code (like a website) or with other third-party services. + +## App + +An intuitive no-code application for managing database content. Powered by the API, the modular and highly extensible +App is written in [Vue.js](https://vuejs.org). + +## Activity + +Activity is a log of all events that take place within the platform. Used for accountability, each activity record +tracks the event type, user, timestamp, IP address, user-agent, and any associated revision data. + +## Collections + +Collections are containers for specific types of Items and contain any number of fields. Each collection represents a +**table** in your database. By default, the [title formatter](#) is used to display any existing database table names as +human-readable collection titles. + +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) + +## Dashboards + +Dashboards within the Insights module organize different [Panels](#) into an at-a-glance view. They can be used to group +data based on department, objective, business process or anything you choose. + +## Database Abstraction + +Directus supports mirroring all the most widely used SQL databases, including PostgreSQL, MySQL, Microsoft SQL Server, +SQLite, OracleDB, MariaDB, and other variants. 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 type. + +This means there is also the possibility 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. + +## 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 + +## Displays + +Displays are the smaller, read-only counterpart to [Interfaces](#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) + +## Environments + +Environments (eg: dev, staging, prod) are tracked as separate Project instances. You can then use schema/content +migrations to promote data between them. + +## Extensions + +The platform has been built to be modular and extensible. This helps keep the core codebase simple and clean (see the +[80/20 Rule](#)), while allowing the flexibility needed to satisfy all use-cases... no matter how complex. There are +many different types of supported extensions, each offering a way to deeply customize, override, or extend the core +platform. [Learn more about Extension Types](#). + +## 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](#collections) might have `title`, `body`, +`author`, and `date_published` field. Fields mirror the characteristics of their associated column, including its +`name`, `type`, `default`, `length`, `allow_null`, etc. + +### Relevant Guides + +- [Creating a Field](/guides/fields/#creating-a-field) +- [Duplicating Fields](/guides/fields/#duplicating-a-field) +- [Adjusting Field Layout](/guides/fields/#adjusting-field-layout) +- [Deleting Fields](/guides/fields/#deleting-a-field) + +## Files & Assets + +As you might have guessed, files includes images, videos, PDFs, text documents, or anything else. While files can +technically be stored as code in the database, it is far more common to manage them as individual assets on a "drive". +The platform supports many options for uploading, storing, transforming, and retrieving different types of files, and it +an excellent Digital Asset Management system. + +## Interfaces + +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. Examples include text inputs, +toggles, WYSIWYG editors, dropdowns, sliders, image galleries, and more. + +In addition to the many core interfaces included out-of-the-box, _custom_ interfaces allow for creating more tailored or +proprietary options, such as seating charts, QR codes, or Stripe customer info. + +### Relevant Guides + +- [Creating a Custom Interface](#) + +## Items + +Item are objects within a Collection which contain 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 +the platform is accessed via these "atomic" data units. Items 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 [primary key](#). + +#### 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) + +## Junction Collections + +The platform allows you to group Items within different Collections. But often times it is important to "link" items +across different collections (such as relating `recipes` and `ingredients`) — this is called a relationship. There are +several different types of relationships, but only some (M2M and M2A) require an additional collection to properly +connect data. For instance, if you have a `recipes` collection and an `ingredients` collection, you would also need a +`recipe_ingredients` junction collection to sit between and connect the two. + +## Layouts + +Layouts determine how you view or interact with a Collection. In most cases, they offer a way to browse items based on a +specific type of data, but can also be used to visualize or interact with data. Directus includes several Layout options +out-of-the-box, each with different features and configuration options. + +- **Table** — Works with any type of data, showing items as rows and their fields as columns. +- **Cards** — Ideal for image data, this layout shows items as a grid of image cards. +- **Calendar** — Ideal for "temporal" data that is sorted by date or datetime. +- **Map** — Ideal for "geospatial" data that is shown on a world map. + +In addition to these core layouts, custom layouts allow for creating more tailored or proprietary ways to experience +data within the App, such as Gantt charts, seating maps, or spreadsheets. + +### Relevant Guides + +- [Creating a Custom Layout](/guides/layouts) + +## Modules + +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 to provide tailored access to sub-pages. All core functionality +within the App can be bucketed into one of the following modules: + +- [Content](#) — 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 +- [Insights](#insights) — Access to infinitely customizable data dashboards +- [App Guide](#) — 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](#) + +## Multitenancy + +Multitenancy is an architecture that allows multiple tenants (eg: customers) to be managed by the platform. There are +two main ways to achieve multitenancy: + +- **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. + +## Panels + +Panels are modular units of data visualization that exist within the Insights module. Each panel exists within a +[Dashboard](#dashboards) and can be positioned and resized as needed. [Panels are a Modular Extension Type](#). + +## Permissions + +Permissions are attached directly to a Role, defining what a user can can create, read, update, and delete within the +platform. Extremely granular, these filter-based permissions control access for the entire system. + +## Presets + +Presets store the exact state of a [collection page](#) page. They 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) + +## Primary Key (PK) + +When we're trying to view or reference a specific [Item](#) within a [Collection](#), you need some sort of unique +identifier to know exactly where to look. Much like an address for a house, the primary key field provides the location +of an item within its collection. For that reason, every collection must have a primary key field, and so they are +configured when you create the collection. There are different types of identifiers you can use, but the field is often +called `id`. + +## Projects + +A Project is a complete instance of the platform. Each project represents a **Database**, but also encapsulates a config +file, asset storage, and any custom extensions. Projects are the highest level of organization in Directus. + +- [Creating a Project](#) +- [Configuring a Project](#) +- [Adjusting Project Settings](#) +- [Upgrading a Project](#) +- [Backing-up a Project](#) +- [Migrating a Project](#) +- [Deleting a Project](#) + +## Relationships + +The platform allows you to group Items within different Collections. But often times it is important to "link" items +across different collections (such as relating `recipes` and `ingredients`) — this is called a relationship, a crucial +concept within any _relational_ database. There are several different types of relationships, each serving a specific +purpose. [Learn more about Relationships](#). + +## Revisions + +Revisions are created whenever an Item is updated. These alternate versions are tracked so that previous states can be +recovered. Every change made to items in Directus is stored as a complete versioned snapshot and a set of specific +changes made (the delta). The revisions system is tightly coupled to the activity logs system, with each revision linked +to the activity event where it was created. + +## Roles + +Roles define a specific set of access permissions, and are the primary organizational structure for Users within the +platform. You can create an unlimited number of roles, so organize your users in whatever way feels most appropriate. + +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. + +There is also a "Public" role that determines access for unauthenticated access. + +### 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) + +## Storage Adapters + +Storage adapters allow project files to be stored in different locations or services. By default, Directus includes the +following drivers: + +- **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 +- **Azure Blob Storage** — Azure storage account containers + +## Title Formatter + +Special Casing — If you are trying to update the specific casing (uppercase/lowercase) for a word (eg: `Dna` to `DNA`) +you will want to add the edge-case to the +[Format Title package](https://github.com/directus/directus/tree/main/packages/format-title/src). If you feel the case +passes our [80/20 rule](https://docs.directus.io/contributing/introduction/#feature-requests) you should submit a Pull +Request to the codebase, otherwise you can update this in your instance. + +## Translations + +The platform supports internationalization across its entire Admin App. Many languages are currently supported, with +more being added all the time. Anyone can add or refine any languages through the integration with +[CrowdIn](https://locales.directus.io/). + +In addition to the App itself being multilingual, the platform allows translating your schema too. By default, +collections and field names come from the database's naming, but you can override this in different languages. + +The platform also includes different ways to manage multilingual content. The built-in translation interface supports +authoring content in any number of languages, side-by-side reference editing, and mixing in language agnostic content +(such as dates or toggles). + +## Types + +The "type" defines how field content is stored in the database and how it is returned by the API. Often called a +data-type, these are important in ensuring field values are saved in a standardized format. Changing a field's type can +cause data loss, so types are locked within the platform after a field is created. + +### 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 +- **Alias** — For fields that do not have a database column [Learn More](#) + +## Users + +An active User is required to access a project. 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 +permissions. diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index 4d6a07f51a..c9c2349444 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -1,25 +1,24 @@ -# Directus Docs +# Getting Started > 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. -::: tip Version 9 - -This is the documentation for the new **[Directus 9](https://github.com/directus/directus)** platform written in -Node.js. If you are looking for the previous **[Directus 8](https://github.com/directus/v8-archive/releases/latest)** -(PHP) docs, you can find them [here](https://v8.docs.directus.io). - -::: - ## What is Directus? -**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 the requirements of any project. +**Directus is an Open Data Platform built to democratize the database.** Its no-code app is safe and intuitive enough to +make data accessible to everyone, while still providing the granular configuration and technical tools required by +power-users and data scientists. For developers, a data connection toolkit provides a dynamic REST+GraphQL API, +JavaScript SDK, and options for authorization, caching, and more. -The platform can be used for an individual purpose, such as headless content management, or more broadly to democratize -an entire organization's data (customers, inventory, business intelligence, projects, etc). +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 the requirements of any project. +Below are the key features of the platform: + +- **No-Code App for anyone to manage data** +- **Data Connection Toolkit with REST & GraphQL** +- **Supports Any SQL Database** +- **Authorization & Caching** +- **Completely Free & Open Source** ::: tip What's in a name? @@ -28,16 +27,50 @@ lines_. The broadest goal of our platform is to present data in a simple, orderl ::: +## Use Cases + +As flexible as the database itself, Directus can power any data-driven project. Below are some examples of common ways +the platform is used: + +- **Headless CMS** — Whether you’re building on JAMstack, server-side (SSR), static websites (SSG), etc — Open Data + Platforms offer a modern and flexible way to manage every omnichannel digital experience. +- **Apps, Games & IoT** — A powerful data backbone for any software or smart device, including: native or hybrid apps, + VR/AR, customer kiosks, installations, microcontrollers, digital signage, and even smart appliances. +- **No-Code App Builder** — Ditch the spreadsheet. Now anyone can create beautiful custom apps for managing customers, + projects, inventory, knowledgebases, task lists, marketing, or anything else... all with zero code. +- **Back-Office & BI Tools** — Gain insights into company KPIs and enable no-code exploration of business data. Coalesce + previously siloed department data to give your team meaningful and actionable analytics. +- **Digital Asset Management** — Aggregate all of your digital files in one place for improved organization, + searchability, delivery, and integration with other datasets, all while enabling on-the-fly file transformations. +- **Raw Data Visualization** — Establish a “single source of truth” for all of your disparate data while enabling + non-technical users to build custom dashboards that generate meaningful insights from complex datasets. + +## 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 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 + no vendor lock-in. +- **Limitless** — Create unlimited users, roles, languages, collections, and items. No arbitrary restrictions or paywall + limitations. +- **Extensible** — Every aspect of the platform is modular, allowing you to adapt, customize, and infinitely extend the + Core engine. +- **Unopinionated** — Choose your database (all SQL vendors), API (REST or GraphQL), and infra (self-hosted or Cloud). + ## Database Mirroring -**What makes Directus so unique is that it dynamically generates custom API endpoints based on your SQL database's -schema in real-time — something we call "[Database Mirroring](/concepts/databases/#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. +What makes Directus so unique is that it dynamically generates custom API endpoints based on your SQL database's schema +in real-time — something we call "[Database Mirroring](/concepts/databases/#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. Below is an overview to how Directus mirrors the database, and our non-technical naming convention. -- **[Project](/concepts/projects/)** — A Database (also includes asset storage and the config file) +- **[Project](/concepts/projects/)** — A Database, asset storage, and config file - **[Collection](/concepts/collections/)** — A Database Table - **[Fields](/concepts/fields/)** — A Database Column - **[Item](/concepts/items/)** — A Database Record/Row @@ -65,109 +98,23 @@ extension types in the platform's App and API. - **[Hooks](/guides/api-hooks/)** — (API) Event and interval hooks for triggering custom logic - **[Email Templates](/guides/email-templates/)** — (API) Custom structure and formatting for emails -## 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 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 - no vendor lock-in. -- **Limitless** — Create unlimited users, roles, languages, collections, and items. No arbitrary restrictions or paywall - limitations. -- **Extensible** — Every aspect of the platform is modular, allowing you to adapt, customize, and infinitely extend the - Core engine. -- **Unopinionated** — Choose your database (all SQL vendors), API (REST or GraphQL), and infra (self-hosted or Cloud). - ## The Directus Ecosystem -### Open-Source Core - -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. - -- **[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 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](/getting-started/introduction/) — Novice oriented, for a platform intro and installation. -- [Concepts](/concepts/activity/) — 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 - -Specific version of the Docs ship with each install of Directus 9. They can be found within the -[Documentation module](/concepts/application#documentation) of the App. - -::: - -### On-Demand Cloud - -[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.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. - -### 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, be sure to follow us on [Twitter](https://twitter.com/directus). - -### Videos - -Our [YouTube Channel](https://www.youtube.com/c/DirectusVideos) has video tutorials, release updates, feature overviews, -and more. - -### Community - -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. - -### App Locales - -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](/contributing/translations/). - -### Marketplace - -Coming in 2021, the [Directus Marketplace](https://directus.market/) will offer a unified portal to extensions created -by our Core Team and community contributors. - -### Awesome List - -Head to [awesome-directus](https://github.com/directus-community/awesome-directus) for a list of awesome things related -to Directus. +- **[GitHub](https://github.com/directus/directus)** — The open-source repository and version control +- **[NPM Package](https://www.npmjs.com/package/directus)** — The official Directus node package +- **[Docker Image](https://hub.docker.com/r/directus/directus)** — The official Directus docker image +- **[Documentation](https://docs.directus.io)** — Docs for the most recent version of our platform +- **[On-Demand Cloud](https://directus.cloud)** — Our self-service managed solution (multitenant) +- **[Enterprise Cloud](https://directus.cloud)** — Our tailored managed solution (single tenant) +- **[Cloud Documentation](https://directus.cloud/docs)** — Docs for the managed cloud dashboard +- **[Private Demos](https://directus.cloud/docs#creating-a-private-demo)** — Instructions on creating a free cloud demo +- **[System Status](https://status.directus.cloud)** — Up-to-date information on our various cloud systems +- **[Website](https://directus.io)** — General information, resources, and team info +- **[Twitter](https://twitter.com/directus)** — The latest product info and sneak-peeks +- **[Videos](https://www.youtube.com/c/DirectusVideos)** — Our YouTube channel with video tutorials and feature + overviews +- **[Discord](https://directus.chat)** — A growing community of 4K+ developers +- **[Crowdin](https://locales.directus.io/)** — Service for managing the App's many language translations +- **[Marketplace](https://directus.market/)** — Coming in 2021, will offer a unified portal for platform extensions +- **[Awesome List](https://github.com/directus-community/awesome-directus)** — A list of awesome things related to + Directus diff --git a/docs/guides/api-config.md b/docs/guides/api-config.md deleted file mode 100644 index cd4e6ddfab..0000000000 --- a/docs/guides/api-config.md +++ /dev/null @@ -1,184 +0,0 @@ -# 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" -``` - -## Auth - -#### Multiple Providers - -You can configure multiple providers for handling authentication in Directus. This allows for different options when -logging in. To do this, you can provide a CSV of provider names, and provide a config block for each of them: - -``` -AUTH_PROVIDERS="google,adobe" - -AUTH_GOOGLE_DRIVER="openid" -AUTH_GOOGLE_CLIENT_ID="" -AUTH_GOOGLE_CLIENT_SECRET= "" -AUTH_GOOGLE_ISSUER_URL="https://accounts.google.com" -AUTH_GOOGLE_ALLOW_PUBLIC_REGISTRATION="true" -AUTH_GOOGLE_DEFAULT_ROLE_ID="" -AUTH_GOOGLE_ICON="google" - -AUTH_ADOBE_DRIVER="oauth2" -AUTH_ADOBE_CLIENT_ID="" -AUTH_ADOBE_CLIENT_SECRET="" -AUTH_ADOBE_AUTHORIZE_URL="https://ims-na1.adobelogin.com/ims/authorize/v2" -AUTH_ADOBE_ACCESS_URL="https://ims-na1.adobelogin.com/ims/token/v3" -AUTH_ADOBE_PROFILE_URL="https://ims-na1.adobelogin.com/ims/userinfo/v2" -AUTH_ADOBE_ALLOW_PUBLIC_REGISTRATION="true" -AUTH_ADOBE_DEFAULT_ROLE_ID="" -AUTH_ADOBE_ICON="adobe" -``` - -### OAuth 2.0 and OpenID - -Directus' OAuth 2.0 and OpenID integrations provide powerful alternative ways to authenticate into your project. -Directus will ask you to login on the external service, and return authenticated with a Directus account linked to that -service. - -Directus supports hundreds of OAuth 2.0 and OpenID services, but requires some configuration to authenticate users -correctly. For example, enabling authentication through GitHub requires creating an -[OAuth 2.0 app in GitHub](https://github.com/settings/developers) and adding the following configuration to Directus: - -``` -AUTH_PROVIDERS="github" -AUTH_GITHUB_CLIENT_ID="99d3...c3c4" -AUTH_GITHUB_CLIENT_SECRET="34ae...f963" -AUTH_GITHUB_AUTHORIZE_URL="https://github.com/login/oauth/authorize" -AUTH_GITHUB_ACCESS_URL="https://github.com/login/oauth/access_token" -AUTH_GITHUB_PROFILE_URL="https://api.github.com/user" -``` - -::: warning PUBLIC_URL - -These flows rely on the `PUBLIC_URL` variable for redirecting. Make sure that variable is configured correctly. - -::: - -## 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" -``` - -## File-Based Configuration - -In case you prefer using a configuration file instead of environment variables, you can use the `CONFIG_PATH` -environment variable to instruct Directus to use a local configuration file instead of environment variables. See -[Config Files](/reference/config-files.md) for more information. diff --git a/docs/guides/collections.md b/docs/guides/collections.md deleted file mode 100644 index 7291368915..0000000000 --- a/docs/guides/collections.md +++ /dev/null @@ -1,159 +0,0 @@ -# Collections - -> 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 internal Title Formatter. -4. Optional: Configure the collection's **Primary Key** name and type. - - Auto-Incremented Integer - - Generated UUID - - Manually Entered String -5. Optional: Enable and rename any desired **System Fields**. - - Status - - Sort - - Created On - - Created By - - Updated On - - Updated By -6. Click the **Finish Setup** button - -::: danger Immutable Keys - -The collection name, primary key name/type, and system field names can not be modified after the collection is created. - -::: - -::: tip Database Tables - -Keep in mind that a Directus Collection is just a database table. Therefore you can import or create a table directly in -the database, and it will automatically appear within Directus. The first time you manage that table, a -`directus_collections` record will be created with default values. - -::: - -## Configuring a Collection - -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 - -The archive feature allows you to enable the collection with a custom soft-delete option. Soft-delete allows users to -remove items from the App, but maintains the actual database record for easy recovery. - -- **Archive Field** — The field that holds the archive value -- **Archive App Filter** — Allows users to view archived items -- **Archive Value** — The value saved in the Archive Field when archived -- **Unarchive Value** — The value saved in the Archive Field when unarchived - -::: warning API Responses - -Items that have been archived are still returned normally via the API. It is up to you to filter them out as needed. - -::: - -::: 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. - -::: - -### Sort - -The sort feature enables manual drag-and-drop item reordering within the Directus App. This is typically shown on the -[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). - -To configure manual sorting for a collection: - -1. Navigate to **Settings > Data Model > [Collection Name]** -2. Create a field with the **Integer** type - - Optional: Set the field to be **Hidden** -3. Select the field you just created in the **Sort Field** dropdown - -::: 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. - -::: - -::: tip Interface Sorting - -To configure manual sorting within an Interface (eg: M2M, O2M, or M2A), configure as above, but also set the **Sort -Field** on the field's Relationship pane. - -::: - -## Renaming a Collection - -While you can not change the **Key** of a collection via Directus (as of now), you can change its **Name** and -translations. - -1. Navigate to **Settings > Data Model > [Collection Name]** -2. Click the Add New button under **Collection Name Translations** -3. Choose the desired **Language** (your primary language for "renaming") -4. Enter a **Translation** -5. Click the **Save** button - -::: tip Special Casing - -If you are trying to update the specific casing (uppercase/lowercase) for a word (eg: `Dna` to `DNA`) you will want to -add the edge-case to the -[Format Title package](https://github.com/directus/directus/tree/main/packages/format-title/src). If you feel the case -passes our [80/20 rule](https://docs.directus.io/contributing/introduction/#feature-requests) you should submit a Pull -Request to the codebase, otherwise you can update this in your instance. - -::: - -## Deleting a Collection - -1. Navigate to **Settings > Data Model > [Collection Name]** -2. Click the red **Delete Collection** action button in the header -3. Confirm this decision by clicking **Delete** in the dialog - -::: danger Irreversible Change - -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. - -::: diff --git a/docs/guides/fields.md b/docs/guides/fields.md deleted file mode 100644 index 8baa3b915d..0000000000 --- a/docs/guides/fields.md +++ /dev/null @@ -1,256 +0,0 @@ -# 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. [Learn more about Fields](/concepts/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 -the database, and it will automatically appear within Directus. The first time you manage that column, a -`directus_fields` record will be created with default values. - -::: - -## Creating a Field - -1. Navigate to **Settings > Data Model > [Collection Name]** -2. Under Fields & Layout, click the **Create Field** button -3. **Choose the field type**, and follow its specific setup guide. (See below) - - [Schema Setup](#schema-setup) - - [Relationship Setup](#relationship-setup) - - [Field Setup](#field-setup) - - [Interface Options](#interface-options) - - [Display Options](#display-options) - - [Conditions](#conditions) - -### Schema Setup - -This pane controls the technical details of the field's database column. - -- **Key** — (Required) The database column name and field's API key. The key must be unique within its parent - Collection. As of now, all keys are sanitized: lowercased, alphanumeric, and with spaces removed. Keys can not be - changed once created, however you can use [Translations](/concepts/translations/#schema-translations) to override the - field's display name in the App. -- **Type** — (Required) How the data is saved to the database; See [Directus Data Type Superset](/concepts/types). This - dropdown maybe be limited or even disabled based on your chosen Field category. -- **Length** — (Only for certain types) For String types this determines the number of characters that can be stored in - the database. For Float and Decimal types, this control becomes **Precision & Scale**. -- **On Create** — (Only for certain types) For some data types, this option allows you to control what value is saved - when an item is created. These values are fallbacks and can be overridden by the App/API. For example, the Timestamp - type allows you to "Save Current Date/Time". -- **On Update** — (Only for certain types) For some data types, this option allows you to control what value is saved - when an item is updated. These values are fallbacks and can be overridden by the App/API. For example, the UUID type - allows you to "Save Current User ID". -- **Default Value** — This is the initial value shown for a field when creating an item in the App. If creating an item - via the API, this is the fallback value saved to the database if a field value is not submitted. -- **Allow NULL** — Toggles if the database column is nullable. When disabled, a `NULL` value can not be saved to the - field's column. -- **Unique** — Toggles if the database column's values must all be unique. - -### Relationship Setup - -This pane is only shown when configuring relational fields (including images and translations). - -::: tip Matching Existing Schema - -To select existing Collections or Fields, use the list icon button on the right-side of the input — exact schema matches -are shown in blue. Collections or Fields without a match will be created on save. For more control over the primary key -field type, first follow the normal [Create a Collection](/guides/collections/#creating-a-collection) flow before -configuring the relationship. - -::: - -::: tip Corresponding Field - -[Relationships go both ways](/concepts/relationships/#perspective-matters), so when creating a new relation Field, -Directus offers to automatically create the corresponding Field on the related Collection. - -::: - -#### Many-to-One - -The [Many-to-One](/concepts/relationships/#many-to-one-m2o) is the only Relationship type that creates/uses an actual -field on the parent Collection. If the chosen Related Collection already exists, the primary key field is automatically -selected. If the Related Collection does not already exist, you will be prompted to enter the name of its new primary -key field. - -![M2O](../assets/guides/fields/m2o.png) - -#### One-to-Many - -The [One-to-Many](/concepts/relationships/#one-to-many-o2m) creates an [Alias](/concepts/fields/#fields) field on the -parent Collection. To configure, enter or select a Related Collection and a field therein for storing the foreign key. -The related field must have a data type that matches the type of "This" Collection's primary key field. - -![O2M](../assets/guides/fields/o2m.png) - -The optional **Sort Field** can be used enable the reordering of items within the O2M field. Configured by entering the -name/key of a Field (numeric type only) from the Related Collection. - -#### Many-to-Many - -The [Many-to-Many](/concepts/relationships/#many-to-many-m2m) creates an [Alias](/concepts/fields/#fields) field on the -parent Collection. To configure, enter or select a Related Collection and a field therein for storing the foreign key. - -To configure the Junction Collection, you can leave "Auto Fill" enabled to let Directus generate intelligent defaults, -or disable it to select existing options or enter custom naming. - -![M2M](../assets/guides/fields/m2m.png) - -#### Many-to-Any - -The [Many-to-Any](/concepts/relationships/#many-to-any-m2a) creates an [Alias](/concepts/fields/#fields) field on the -parent Collection. To configure, select one or more Related Collections. The primary key field of each will -automatically be referenced. - -To configure the Junction Collection, you can leave "Auto Fill" enabled to let Directus generate intelligent defaults, -or disable it to select existing options or enter custom naming. - -![M2A](../assets/guides/fields/m2a.png) - -#### Translations - -[Translations](/concepts/translations/#content-translations) creates an [Alias](/concepts/fields/#fields) field on the -parent Collection. The easiest way to create this is to use the modal wizard, which only asks for the Translation field -name: - -![Translations](../assets/guides/fields/translations.png) - -If you choose to switch to the **manual editor**, enter or select a Related Collection and a field therein for storing -the foreign key. - -To configure the Translations Collection, you can leave "Auto Fill" enabled to let Directus generate intelligent -defaults, or disable it to select existing options or enter custom naming. - -![Translations](../assets/guides/fields/translations-2.png) - -### Field Setup - -- **Required** — Toggles if a value for the Field is required. - - Empty strings (`''`) and `NULL` are **not** accepted as a valid value - - `0` and `false` are accepted as a valid value - - Default values are accepted as a valid value - - Permission Presets are accepted as a valid value -- **Readonly** — (App Only) Sets the field to be disabled. -- **Hidden** — (App Only) Hides the field in the App form. - - The field is still available in filters and Layout options. -- **Note** — (App Only) Displayed below the field in the App form, providing a helpful comment for App users. This note - supports markdown. -- **Field Name Translations** — (App Only) A repeater for translating the Field Name into different locales. It can also - be used to "rename" the field in the primary language without updating the field Key. - -### Interface Options - -This pane includes any customization options that may be defined by the Interface. - -### Display Options - -This pane includes any customization options that may be defined by the Display. - -### Conditions - -Conditions allow you to alter the current field's setup based on the values of other fields in the form. This allows you -to show/hide the field, make it readonly, or change the interface options. - -Each field can have one or more _rules_. Each rule has the following configuration options: - -- **Name**: The name of the rule. This is only used internally for convenience purposes -- **Rule**: The rule that controls whether or not these conditions are applied. Rule follows the - [Filter Rules](/reference/filter-rules) spec -- **Readonly**: Whether or not the field is readonly when the condition is matched -- **Hidden**: Whether or not the field is hidden when the condition is matched -- **Interface Options**: Any additional configuration for the selected interface - -These changes to the field are merged onto the base configuration of the field. This means you can have the field hidden -by default, and then only toggle the hidden state of the field in the condition. - -::: tip Order matters - -The conditions are matched in order. The **last** condition that matches is the one that's used to apply the changes. - -::: - -## Updating a Field - -1. Navigate to **Settings > Data Model > [Collection Name]** -2. Click the field you want to update -3. Follow the specific setup guide for the field type... - -::: tip - -Learn more about the field options for [Adjusting the Field Layout](#adjusting-field-arrangement). - -::: - -## Renaming a Field - -While you can not change the **Key** of a field via Directus (as of now), you can change its **Name** and translations. - -1. Navigate to **Settings > Data Model > [Collection Name]** -2. **Click the Field** you want to update -3. Navigate to the **Field Tab** -4. Click the Add New button under **Field Name Translations** -5. Choose the desired **Language** (your primary language for "renaming") -6. Enter a **Translation** -7. Click the **Save** button - -::: tip Special Casing - -If you are trying to update the specific casing (uppercase/lowercase) for a word (eg: `Dna` to `DNA`) you will want to -add the edge-case to the -[Format Title package](https://github.com/directus/directus/tree/main/packages/format-title/src). If you feel the case -passes our [80/20 rule](https://docs.directus.io/contributing/introduction/#feature-requests) you should submit a Pull -Request to the codebase, otherwise you can update this in your instance. - -::: - -## Duplicating a Field - -1. Navigate to **Settings > Data Model > [Collection Name]** -2. Click the **More Options** icon for the field you want to duplicate -3. Click the **Duplicate Field** option - -::: warning Relational and Primary Key Fields - -It is not currently possible to duplicate relational fields or a collection's primary key. - -::: - -## Adjusting Field Arrangement - -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 - - Half — The field is shown at half the form width - - Full — (Default) The field is shown at the full form width - - Fill — The field is shown filling the page width -- **Field Sort** — The order of fields within the form -- **Field Group** — If the field is a "group" type - - - -2. Click the **More Options** icon for any fields to adjust visibility -3. Click the **More Options** icon for any fields to adjust width -4. **Rearrange fields and groups** with their drag-and-drop handles - -## Deleting a Field - -1. Navigate to **Settings > Data Model > [Collection Name]** -2. Click the **More Options** icon for the field you want to delete -3. Click the **Delete Field** option -4. Confirm this decision by clicking **Delete** in the dialog - -::: danger Irreversible Change - -This action is permanent and can not be undone. Please proceed with caution. - -::: diff --git a/docs/guides/files.md b/docs/guides/files.md deleted file mode 100644 index 19d32bac33..0000000000 --- a/docs/guides/files.md +++ /dev/null @@ -1,43 +0,0 @@ -# Files - -> Directus includes a full-featured Digital Asset Management (DAM) system, complete with different Storage Adapters. -> [Learn more about Files](/concepts/files/). - -## Uploading a File - -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. - -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" - -## Creating a Thumbnail Preset - -1. Navigate to **Settings > Project Settings** -2. Scroll to the **Storage Asset Presets** field -3. Click **Add a New Item** -4. Enter a unique **Key** for the preset -5. Enter the **Fit**, **Width**, **Height**, and **Quality** for the preset -6. Click the **Save** action button in the header - -## Downloading an Original File - -The File Library and the Image and File interfaces all include buttons to download the original copy of a file. - -1. Navigate to the **File Library** -2. Click a file to open it's detail page -3. Click the download button in the top right. - -## Editing Images - -The detail page for a file contains an image editor you can use for some basic editing like rotating, cropping, or -mirroring the file. - -1. Navigate to the **File Library** -2. Click a file to open it's detail page -3. Click the edit button in the top right to open the image editor -4. Make your changes and hit save in the top right to save the updates to the file diff --git a/docs/guides/items.md b/docs/guides/items.md deleted file mode 100644 index 3a2542d583..0000000000 --- a/docs/guides/items.md +++ /dev/null @@ -1,193 +0,0 @@ -# Items - -> 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 - -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 an Item - -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 -5. Click the "Save Item" (✓ icon) button located in the header - -::: tip Singletons - -If the Collection is configured as a "Singleton" in the data model settings, then the App will automatically skip step -#3 above. - -::: - -## Updating an Item - -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 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 -#3 above. - -::: - -## Deleting an Item - -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 -5. Confirm the action within the dialog by clicking "Delete" - -::: tip Deleting from the Item Detail page - -You can also click on an item to navigate to its Detail page. From there, you can click on the "Delete Item" (trash -icon) button located in the header. - -::: - -## Archiving an Item - -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 -5. Confirm the action within the dialog by clicking "Archive" - -::: warning Requires Configuration - -This feature is only available if an Archive column has been configured in the Collection's data model settings. - -::: - -::: tip Archiving from the Item Detail page - -You can also click on an item to navigate to its Detail page. From there, you can click on the "Archive Item" (archive -icon) button located in the header. - -::: - -## Reverting an Item - -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 -5. Click on the revision you wish to preview -6. Click on the "Revert" button located in the drawer's header -7. Confirm the action within the dialog by clicking "Revert" - -## Commenting on an Item - -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 - -## Manually Sorting Items - -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 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 - -This feature is only available if a Sort column has been configured in the Collection's data model settings. - -::: - -## Ordering Items - -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 - -::: tip Sort vs Order - -**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. - -::: - -## 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 - -**[Learn more about Search](/guides/items/#searching-items)** - -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 - -**[Learn more about Filtering](/guides/items/#filtering-items).** - -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 -5. Adjust the operator (eg: "Contains") as needed by clicking on it -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 - -**[Learn more about Bookmarks](/guides/items/#bookmarking-item-presets)** - -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 - -**[Learn more about Exporting](guides/items/#exporting-items)** - -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 -5. Choose the desired format: either CSV or JSON -6. Choose whether you want to use your current Filters and Settings in the export -7. Click the "Export" button to download the file to your device diff --git a/docs/guides/permissions.md b/docs/guides/permissions.md deleted file mode 100644 index c77d822583..0000000000 --- a/docs/guides/permissions.md +++ /dev/null @@ -1,104 +0,0 @@ -# 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. - -::: warning Read Field Permissions - -The Directus App always requires read access to the Primary Key field (eg: `id`) so it can uniquely identify items. -Also, if a Collection has "Archive" or "Sort" fields configured, those fields will also need read access to use the -App's soft-delete and manual sorting features. - -::: - -### 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 Public Permissions - -Public permissions are managed the same as [normal role permissions](#configuring-role-permissions), however they are -done through the Public Role. - -## 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. - -::: - -## 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. diff --git a/docs/guides/projects.md b/docs/guides/projects.md deleted file mode 100644 index 5cffee030a..0000000000 --- a/docs/guides/projects.md +++ /dev/null @@ -1,124 +0,0 @@ -# Projects - -> 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 - -To install Directus, choose one of the following methods. - -- [Command Line Interface (CLI)](/guides/installation/cli) -- [Docker](/guides/installation/docker) -- [Manually](/guides/installation/manual) - -## Configuring a Project - -All project configuration is handled by the `.env` file within the `/api` directory. This file accepts a number of -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/application/#_2-navigation-bar) and on - the login/public pages -- **Project URL** — The URL when clicking the logo at the top of the [Module Bar](/concepts/application/#_1-module-bar) -- **Project Color** — The color used behind the logo at the top of the - [Module Bar](/concepts/application/#_1-module-bar), 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/application/#_1-module-bar) 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 is 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](/guides/projects/#public-pages). - -- **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) - -### Modules - -- **Module Bar** — Allows the customisation of links displayed in the module bar: - - Module Visibility — Show or hide modules by toggling the checkbox. - - Link Reordering — Reorder links by dragging on the sort handle. - - Link Creation — URLs should start with a `/` for links within the - [Directus App](/concepts/application/#the-directus-application). - -## Upgrading / Updating a Project - -1. Backup your project -2. Run `npm update` -3. Run `npx directus database migrate:latest` to update the DB - -## Backing-up a Project - -1. Make a copy of the **files within each storage adapter**, and store them in a safe place -2. Make a copy of the **Env file** (`/api/.env`), and store it in a safe place -3. Create a database dump - -## 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. - -::: - -## Downgrading a Project - -Directus can be reverted to an earlier version by going to your terminal, navigating into your project folder and -running `npm install directus@`. - -If you ran any database migrations for a newer version, you can revert those by running -`npx directus database migrate:down` - -## Deleting a Project - -1. Optional: **Backup any local files** stored within the project's root directory -2. Optional: **Backup any custom code and extensions** within the project's root directory -3. Optional: **Backup your entire database**, only system tables, or only project tables -4. **Delete the project's root directory** from the server -5. **Delete all Directus system tables** (`directus_*`) from the database - -::: tip Pure SQL - -After completing this process, you will be left with a pure SQL database, with no trace that Directus was ever -installed. Any external services connecting to your database's project tables directly (eg: SQL queries) should continue -working normally. - -::: diff --git a/docs/guides/roles.md b/docs/guides/roles.md deleted file mode 100644 index 150c70d8a9..0000000000 --- a/docs/guides/roles.md +++ /dev/null @@ -1,126 +0,0 @@ -# Roles - -> Roles define a specific set of access permissions, and are the primary organizational structure for Users within the -> platform. [Learn more about Roles](/concepts/roles/). - -## Creating a Role - -1. Navigate to **Settings > Roles & Permissions** -2. Click the **Create Role** action button in the header -3. Enter a unique **Role Name** -4. Enabling **App Access** allows logging in to the App -5. Enabling **Admin Access** gives full permission to project data and Settings - -## Configuring a Role - -- **Permissions** — Defines the role's access permissions -- **Role Name** — This is the name of the role -- **Role Icon** — The icon used throughout the App when referencing this role -- **Description** — A helpful note that explains the role's purpose -- **App Access** — Allows logging in to the App -- **Admin Access** — Gives full permission to project data and Settings -- **IP Access** — An allow-list of IP addresses from which the platform can be accessed, empty allows all -- **Require 2FA** — Forces all users within this role to use two-factor authentication -- **Users in Role** — A list of all users within this role -- **Module Navigation** — Overrides the visible modules -- **Collection Navigation** — Overrides the collection module's navigation - -### Customizing the Module Navigation - -The options in the [Module Bar](/concepts/application/#_1-module-bar) can be overridden with custom options per role. -When this setting is empty, the default modules are used. - -1. Navigate to **Settings > Roles & Permissions > [Role Name]** -2. Scroll to the **Module Navigation** field -3. Click the **Add a new item** button to add a module -4. Choose an **Icon** to display for the module -5. Choose a **Name** for the module -6. Enter a relative (App) or absolute (external) **link** for the module -7. Use the drag handles to **drag-and-drop** the modules into the desired order - -If you are looking to replicate the default modules, paste the following configuration into the Module Navigation field -using the Raw Value field label option. - -```json -[ - { - "icon": "box", - "name": "Collections", - "link": "/collections" - }, - { - "icon": "people_alt", - "name": "User Directory", - "link": "/users" - }, - { - "icon": "folder", - "name": "File Library", - "link": "/files" - }, - { - "icon": "info", - "name": "Documentation", - "link": "/docs" - } -] -``` - -::: warning Settings Module - -The settings module is not controlled by this configuration. It is always added to the end of the list for any user's -with Admin Access. - -::: - -::: tip Customizing Existing Modules - -You can enter the link to an existing module to customize its name or icon. For example, you can use `/collections` to -override the Collections module. - -::: - -### Customizing the Collection Navigation - -The collections in the [Navigation Bar](/concepts/application/#_2-navigation-bar) can be overridden with custom options -per role. When this setting is empty, all collections that the user has permission to see are shown alphabetically in a -single, unlabeled group. - -1. Navigate to **Settings > Roles & Permissions > [Role Name]** -2. Scroll to the **Collection Navigation** field -3. Click the **Add New Group** button to add a Grouping -4. Enter a **Group Name**, or leave it empty to simply show a divider -5. Choose if the group's **Accordion** will be... - - Always Open (Default) - - Start Open - - Start Collapsed -6. Click the **Add New Collection** button to add a Collection -7. Choose a **Collection** from the dropdown -8. Use the drag handles to **drag-and-drop** the groups/collections into the desired order - -## Deleting a Role - -1. Navigate to **Settings > Roles & Permissions > [Role Name]** -2. Click the red **Delete Role** action button in the header -3. Confirm this decision by clicking **Delete** in the dialog - -::: warning Users in a Deleted Role - -If you delete a role that still has users in it, those users will be given a `NULL` role, which denies their App access -and limits them to the [Public Role](/concepts/roles/#public-role) permissions. They can then be reassigned to a new -role by an admin. - -::: - -::: warning Last Admin - -You must maintain at least one role/user with Admin Access so that you can still properly manage the project. - -::: - -::: warning Public Role - -You can not delete the Public role, as it is part of the core platform. To disable it completely, simply turn off all -Public access permissions. - -::: diff --git a/docs/guides/users.md b/docs/guides/users.md deleted file mode 100644 index dc3522dda9..0000000000 --- a/docs/guides/users.md +++ /dev/null @@ -1,93 +0,0 @@ -# Users - -> 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](/concepts/users/). - -## Creating a User - -1. Navigate to the **User Library** -2. Click the **Create User** action button in the header -3. Enter an **Email Address** -4. Optional: Complete the **other user form fields** - -## Inviting a User - -1. Navigate to the **User Library** -2. Click the **Invite Users** button in the header -3. Enter **one or more email addresses**, separated by new lines, in the modal -4. Click **Invite** - -At this point the invited user(s) will receive an email with a link to the App where they set a password and enable -their account. - -## Configuring a User - -1. Navigate to the **User Library** -2. **Click on the user** you wish to manage -3. **Complete the form** of [User Fields](/concepts/application/#user-detail) - -::: warning User Preferences - -This section of the User Detail is only visible/editable by the current user, and admins. - -::: - -#### 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 -- **Active** — The only status that has proper access to the App and API -- **Suspended** — A user that has been temporarily disabled; no App/API access -- **Archived** — A soft-deleted user; no App/API access - -::: warning Admin Only - -Only admins can adjust this field's value. - -::: - -#### 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]**. - -::: warning Admin Only - -Only admins can adjust this field's value. - -::: - -#### 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. - -## Archiving a User - -1. Navigate to the **User Library** -2. Click the user you with to archive to go to their User Detail page -3. Click the orange **Archive User** action button in the header -4. Confirm this decision by clicking **Archive** in the dialog - -::: warning Disables Access - -Archiving uses _soft-delete_, therefore archived users are unable to access the App or API. - -::: - -## Deleting a User - -1. Navigate to the **User Library** -2. Select one or more users you wish to delete -3. Click the red **Delete User** action button in the header -4. Confirm this decision by clicking **Delete** in the dialog - -::: danger Irreversible Change - -Unlike the soft-delete of archiving, this process is a hard-delete. Therefore, this action is permanent and can not be -undone. Please proceed with caution. - -::: diff --git a/docs/reference/api/assets.md b/docs/reference/api/assets.md deleted file mode 100644 index 2d3ee11640..0000000000 --- a/docs/reference/api/assets.md +++ /dev/null @@ -1,122 +0,0 @@ -# Assets - -> The `/assets` endpoint can be used to stream or retrieve the actual file contents from assets managed within Directus. - -- [Accessing an Original File](#accessing-an-original-file) -- [Requesting a Thumbnail](#requesting-a-thumbnail) -- [Downloading a File](#downloading-a-file) - -::: tip Uploading Files - -To learn more about uploading files, see the [Upload a File](/reference/api/system/files/#upload-a-file) and -[Import a File](/reference/api/system/files/#import-a-file) endpoints. - -::: - -## Accessing an Original File - -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/ -example.com/assets/1ac73658-8b62-4dea-b6da-529fbc9d01a4 -``` - -![Original File](../../assets/original.jpg) _Original File Used — 602KB and 1800x1200_ - -::: warning Direct File Access - -While you may _technically_ be able to expose your storage adapters root filesystem and access your raw files through -there, 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. - -::: - -## Requesting a Thumbnail - -Fetching thumbnails is as easy as adding a `key` query parameter to the original file's URL. In the Admin App, you can -configure different asset presets that control the output of any given image. If a requested thumbnail doesn't yet -exist, it is dynamically generated and immediately returned. - -- **`key`** — This **key** of the [Storage Asset Preset](/guides/files#creating-thumbnail-presets), a shortcut for the - below parameters - -Alternatively, if you have "Storage Asset Transform" set to all, you can use the following parameters for more fine -grained control: - -- **`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 (`1` to `100`) is `Optional` -- **`withoutEnlargement`** — Disable image up-scaling -- **`format`** — What file format to return the thumbnail in. One of `jpg`, `png`, `webp`, `tiff` - -``` -example.com/assets/?fit=&width=&height=&quality= -example.com/assets/1ac73658-8b62-4dea-b6da-529fbc9d01a4?fit=cover&width=200&height=200&quality=80 -``` - -For even more advanced control over the file generation, Directus exposes -[the full `sharp` API](https://sharp.pixelplumbing.com/api-operation) through the `transforms` query parameter. This -parameter accepts a two-dimensional array with the format `[Operation, ...arguments]`, for example: - -``` -?transforms=[ - ["blur", 45], - ["tint", "rgb(255, 0, 0)"], - ["expand", { "right": 200, "bottom": 150 }] -] -``` - -### Downloading an asset - -To automatically download the file when opening it in a browser, add the `download` query parameter. - -- **`download`** — Add `Content-Disposition` header and force browser to download file - -### 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)
_8KB • 200x200_ | ![Contain](../../assets/200-200-contain-75.jpg)
_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)
_4KB_ | ![50%](../../assets/200-200-cover-50.jpg)
_6KB_ | ![75%](../../assets/200-200-cover-75.jpg)
_8KB_ | ![100%](../../assets/200-200-cover-100.jpg)
_38KB_ | - -## Downloading a File - -To download an asset with the correct filename, you need to add the `?download` query parameter to the request and the -`download` attribute to your anchor tag. This will ensure the appropriate -[Content-Disposition](https://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html) headers are added. Without this, the -download will work on the _same_ domain, however it will have the file's "id" as the filename for cross-origin requests. - -Example: - -```html -Download -``` diff --git a/docs/reference/api/authentication.md b/docs/reference/api/authentication.md deleted file mode 100644 index b7d8fabb64..0000000000 --- a/docs/reference/api/authentication.md +++ /dev/null @@ -1,47 +0,0 @@ -# Authentication - -> By default, all data in the system is off limits for unauthenticated users. To gain access to protected data, you must -> include an access token with every request, or -> [configure permissions for the public role](/concepts/roles/#public-role). - -## Authenticating with Tokens - -In order to authenticate to the API, you have to pass an authentication token. The token can be passed in two ways: - -### Query Parameter - -Pass the token in the `access_token` query parameter: `?access_token=` - -``` -?access_token=eyJh...KmUk -``` - -### Authorization Header - -Pass the token in the Authorization header: `Authorization: Bearer ` - -``` -Authorization: Bearer eyJh...KmUk -``` - -## Types of Tokens - -There are two types of tokens that can be used to authenticate within Directus: - -### Temporary Token (JWT) - -These are the tokens as returned by the [login](/reference/api/system/authentication/#login) endpoint/mutation. These -tokens have a relatively short expiration time, and are thus the most secure option to use. The tokens are returned with -a `refresh_token` that can be used to retrieve a new access token via the -[refresh](/reference/api/system/authentication/#refresh) endpoint/mutation. - -### Static Token - -Each user can have one static token that will never expire. This is useful for server-to-server communication, but is -also less secure than the JWT token. This token is saved to the database (`directus_users.token`) in plain-text. - -::: tip Retrieving a Token - -Looking for how to get an access token? See [the login endpoint/mutation](/reference/api/system/authentication/#login). - -::: diff --git a/docs/reference/app/app.md b/docs/reference/app/app.md deleted file mode 100644 index f361754dd4..0000000000 --- a/docs/reference/app/app.md +++ /dev/null @@ -1,25 +0,0 @@ -# App Reference - -The purpose of the app reference is to allow more and easier access to our internal components when developing custom -interfaces, displays or modules. - -## App Structure - -The Vue frontend app is structured into many departments to combine similar purpose components. - -| Folder | Content | Example | -| ------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| `components` | In here are our base components that are designed to be as general and everywhere fitting as possible | It contains `v-button` | -| `composables` | Composables are reusable pieces of logic that can be used inside Vue component | `use-shortcut` to easily react to button combinations pressed | -| `directives` | Directives are functions that are available on Vue components in templates | contains `v-focus` or `v-tooltip` | -| `displays` | Displays are functions / components that are used in the system to display data | `display-image` is used to display image data inside the app | -| `interfaces` | Interfaces are the individual blocks that allow editing and viewing individual pieces of data | `interface-color` is a color picker allowing for easy selection of any color | -| `lang` | Containing all translations used across the directus app | Contains translations like `en-US` | -| `layouts` | Layouts change the way items are represented inside the collection view | The card and tabular layout are inside here | -| `modules` | Modules organize in which major parts the app is structured | Here are the files or settings module which are always visible from the sidebar | -| `routes` | Basic routes the app needs that shouldn't be customized | Routes for authentication or password reset | -| `stores` | Here lay all stores used in the app containing all relevant data that gets fetched from the api | The `fields` store containing all accessible fields for the user | -| `styles` | All general styles, css-vars, mixins and themes are stored inside here | The `form-grid` mixin allowing to style form like grids | -| `types` | Contains types used to generalize data for typescript | `field-schema` which is used to model the schema of fields | -| `utils` | Utility functions that helps minimize repetition | `notify` which is used to easily generate notifications inside the app | -| `views` | Views are the top-level parent component that are used in all modules | `private-view` which renders the basic structure like sidebar, headers and content sections | diff --git a/docs/reference/app/components/index.md b/docs/reference/app/components/index.md deleted file mode 100644 index 38730ec7a5..0000000000 --- a/docs/reference/app/components/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Directus Vue Components - -Directus comes shipped with it's own Vue component library you can use to enrich your extensions, while making them fit -within the context of the Directus app. - -These components can be used in any of the "front-end extensions", including [Interfaces](/guides/interfaces/), -[Displays](/guides/displays/), and [Modules](/guides/modules/). - -::: warning Breaking Changes - -While we aim to make the components as backwards compatible as possible, we **do not** consider internal-API changes in -the components as a breaking change of Directus. Please keep an eye -[the release notes](https://github.com/directus/directus/releases), and make sure your extension still works before -updating Directus. - -::: diff --git a/docs/reference/app/components/transition-bounce.md b/docs/reference/app/components/transition-bounce.md deleted file mode 100644 index c83e01a4ec..0000000000 --- a/docs/reference/app/components/transition-bounce.md +++ /dev/null @@ -1,39 +0,0 @@ -# Transition Bounce - -Bounces items in or out depending if the get added or removed from the view. - -```html - - - -``` - -## Reference - -#### Slots - -| Slot | Description | Data | -| --------- | -------------------------------------------- | ---- | -| _default_ | The elements that should get animated in/out | | diff --git a/docs/reference/app/components/transition-dialog.md b/docs/reference/app/components/transition-dialog.md deleted file mode 100644 index e89e672e0c..0000000000 --- a/docs/reference/app/components/transition-dialog.md +++ /dev/null @@ -1,39 +0,0 @@ -# Transition Dialog - -Fades items in or out depending if the get added or removed from the view. - -```html - - - -``` - -## Reference - -#### Slots - -| Slot | Description | Data | -| --------- | -------------------------------------------- | ---- | -| _default_ | The elements that should get animated in/out | | diff --git a/docs/reference/app/components/transition-expand.md b/docs/reference/app/components/transition-expand.md deleted file mode 100644 index 535e593cd8..0000000000 --- a/docs/reference/app/components/transition-expand.md +++ /dev/null @@ -1,54 +0,0 @@ -# Transition Expand - -Use around a `v-if` or `v-show` component to have it expand in and out of view. - -```html - - - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ----------------------- | -------------------------------------------------- | ------- | --------- | -| `x-axis` | Expand on the horizontal instead vertical axis | `false` | `Boolean` | -| `expanded-parent-class` | Add a custom class to the element that is expanded | `''` | `String` | - -#### Slots - -| Slot | Description | Data | -| --------- | ---------------------------------------- | ---- | -| _default_ | Elements that should be animated go here | | - -#### Events - -n/a - -#### CSS Variables - -n/a diff --git a/docs/reference/app/components/v-avatar.md b/docs/reference/app/components/v-avatar.md deleted file mode 100644 index 0fadfdfa2c..0000000000 --- a/docs/reference/app/components/v-avatar.md +++ /dev/null @@ -1,42 +0,0 @@ -# Avatar - -The avatar component can be used to display a person or something similar. It will generate a grey box in which either a -profile picture or an icon or text can be inserted. - -```html -RVZ - - - - - - - - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------ | ------------------------- | ------- | --------- | -| `size` | Size in px | `null` | `Number` | -| `tile` | Render as a tile (square) | `false` | `Boolean` | - -#### Slots - -| Slot | Description | Data | -| --------- | ------------------------------------------------------- | ---- | -| _default_ | Default slot to display your elements inside the avatar | -- | - -#### Events - -n/a - -#### CSS Variables - -| Variable | Default | -| ------------------ | -------------------------- | -| `--v-avatar-color` | `var(--background-normal)` | -| `--v-avatar-size` | `48px` | diff --git a/docs/reference/app/components/v-badge.md b/docs/reference/app/components/v-badge.md deleted file mode 100644 index 52b30c421b..0000000000 --- a/docs/reference/app/components/v-badge.md +++ /dev/null @@ -1,49 +0,0 @@ -# Badge - -Display a small dot in the corner of the component. - -```html -ABC -``` - -## Colors - -You can set the color, background color and border color with the `--v-badge-color`, `--v-badge-background-color` and -`--v-badge-border-color` css vars respectively: - -```html - - ABC - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ---------- | ---------------------------------------------------------------------------- | ------- | ------------------ | -| `value` | The value that will be displayed inside the badge Only 2 characters allowed) | `null` | `[String, Number]` | -| `dot` | Only will show a small dot without any content | `false` | `Boolean` | -| `bordered` | Shows a border around the badge | `false` | `Boolean` | -| `left` | Aligns the badge on the left side | `false` | `Boolean` | -| `bottom` | Aligns the badge on the bottom side | `false` | `Boolean` | -| `icon` | Shows an icon instead of text | `null` | `String` | -| `disabled` | Don't render the badge | `false` | `Boolean` | - -#### CSS Variables - -| Variable | Default | -| ---------------------------- | ------------------------ | -| `--v-badge-color` | `var(--white)` | -| `--v-badge-background-color` | `var(--danger)` | -| `--v-badge-border-color` | `var(--background-page)` | -| `--v-badge-offset-x` | `0px` | -| `--v-badge-offset-y` | `0px` | -| `--v-badge-size` | `16px` | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ---- | -| _default_ | | | diff --git a/docs/reference/app/components/v-breadcrumb.md b/docs/reference/app/components/v-breadcrumb.md deleted file mode 100644 index ae75033af2..0000000000 --- a/docs/reference/app/components/v-breadcrumb.md +++ /dev/null @@ -1,35 +0,0 @@ -# Breadcrumb - -A breadcrumb can help you display on what site you are currently on by displaying a structure like `my / custom / page`. - -```html - -``` - -## Breadcrumb Item - -An item for the items prop has these 4 options: - -| Prop | Description | -| ---------- | --------------------------------------------------------- | -| `to` | The reroute link | -| `name` | The name which will be displayed | -| `icon` | Displays an icon with the given name in front of the name | -| `disabled` | If the router link should be clickable | - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------- | -------------------------------------------------------- | ---------- | -------------- | -| `items` | An array of objects which information about each section | `() => []` | `Breadcrumb[]` | - -#### CSS Variables - -| Variable | Default | -| ------------------------------- | --------------------------- | -| `--v-breadcrumb-color` | `var(--foreground-subdued)` | -| `--v-breadcrumb-color-hover` | `var(--foreground-normal)` | -| `--v-breadcrumb-color-disabled` | `var(--foreground-subdued)` | -| `--v-breadcrumb-divider-color` | `var(--foreground-subdued)` | diff --git a/docs/reference/app/components/v-button.md b/docs/reference/app/components/v-button.md deleted file mode 100644 index 9fa40cc940..0000000000 --- a/docs/reference/app/components/v-button.md +++ /dev/null @@ -1,108 +0,0 @@ -# Button - -A simple button component to make your life interactive! - -```html -Click me! -``` - -## Sizes - -The button component supports the following sizes through the use of props: - -- x-small -- small -- (default) -- large -- x-large - -## Colors - -You can set the color, background color, hover color, and background hover color with the `--v-button-color`, -`--v-button-background-color`, `--v-button-color-hover`, and `--v-button-background-color-hover` css variables -respectively: - -```html -Click me - - -``` - -## Loading - -The button has a loading state that can be enabled with the `loading` prop. By default, the button will render a -`v-spinner`. You can override what's being shown during the loading state by using the `#loading` slot: - -```html - - - -``` - -The loading slot is rendered _on top_ of the content that was there before. Make sure that your loading content doesn't -exceed the size of the default state content. This restriction is put in place to prevent jumps when going from and to -the loading state. - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------------ | ------------------------------------------------------------------------- | ---------- | -------------------- | -| `icon` | Remove padding / min-width. Meant to be used with just an icon as content | `false` | `Boolean` | -| `outlined` | No background | `false` | `Boolean` | -| `rounded` | Enable rounded corners | `false` | `Boolean` | -| `type` | HTML `type` attribute | `'button'` | `String` | -| `disabled` | Disabled state | `false` | `Boolean` | -| `loading` | Loading state | `false` | `Boolean` | -| `to` | Render as vue router-link | `null` | `string or Location` | -| `href` | Render as anchor | `null` | `String` | -| `align` | Align content in button. One of `left | `'center'` | `String` | -| `dashed` | Render the border dashed. Meant to be used with `outlined`. | `false` | `Boolean` | -| `tile` | Render without border radius | `false` | `Boolean` | -| `download` | Add the `download` attribute (used in combo with `href`) | `null` | `String` | -| `full-width` | | `false` | `Boolean` | -| `exact` | | `false` | `Boolean` | -| `secondary` | | `false` | `Boolean` | -| `value` | | `null` | `[Number, String]` | - -#### Slots - -| Slot | Description | Data | -| --------------- | -------------------------------------------- | ---- | -| _default_ | Button content | | -| `loading` | Content that's rendered during loading state | | -| `prepend-outer` | Content that's rendered before the button | | -| `append-outer` | Content that's rendered after the button | | - -#### Events - -| Event | Description | Value | -| ------- | --------------------- | ------------ | -| `click` | User clicks on button | `MouseEvent` | - -#### CSS Variables - -| Variable | Default | -| -------------------------------------- | ---------------------------- | -| `--v-button-width` | `auto` | -| `--v-button-height` | `44px` | -| `--v-button-color` | `var(--foreground-inverted)` | -| `--v-button-color-hover` | `var(--foreground-inverted)` | -| `--v-button-color-active` | `var(--foreground-inverted)` | -| `--v-button-color-disabled` | `var(--foreground-subdued)` | -| `--v-button-background-color` | `var(--primary)` | -| `--v-button-background-color-hover` | `var(--primary-125)` | -| `--v-button-background-color-active` | `var(--primary)` | -| `--v-button-background-color-disabled` | `var(--background-normal)` | -| `--v-button-font-size` | `16px` | -| `--v-button-font-weight` | `600` | -| `--v-button-line-height` | `22px` | -| `--v-button-min-width` | `140px` | diff --git a/docs/reference/app/components/v-card-actions.md b/docs/reference/app/components/v-card-actions.md deleted file mode 100644 index d39b6dd3db..0000000000 --- a/docs/reference/app/components/v-card-actions.md +++ /dev/null @@ -1,21 +0,0 @@ -# Card Actions - -This component is used to add actions like `cancel` or `save` to an existing `v-card`. - -```html - - Would you like to save the changes? - - Cancel - Save - - -``` - -## Reference - -#### Slots - -| Slot | Description | Data | -| --------- | ----------------------------- | ---- | -| _default_ | Where all the actions will go | | diff --git a/docs/reference/app/components/v-card-subtitle.md b/docs/reference/app/components/v-card-subtitle.md deleted file mode 100644 index 8487e24af7..0000000000 --- a/docs/reference/app/components/v-card-subtitle.md +++ /dev/null @@ -1,17 +0,0 @@ -# Card Subtitle - -This component is used to give a `v-card` an already stylized subtitle. - -```html - - A less important subtitle - -``` - -## Reference - -#### Slots - -| Slot | Description | Data | -| --------- | -------------------------- | ---- | -| _default_ | Where the subtitle will go | | diff --git a/docs/reference/app/components/v-card-text.md b/docs/reference/app/components/v-card-text.md deleted file mode 100644 index 1a1a07c799..0000000000 --- a/docs/reference/app/components/v-card-text.md +++ /dev/null @@ -1,17 +0,0 @@ -# Card Text - -This component is used to give a `v-card` an already stylized text. - -```html - - This card can do nothing! - -``` - -## Reference - -#### Slots - -| Slot | Description | Data | -| --------- | ----------------------- | ---- | -| _default_ | Where your text will go | | diff --git a/docs/reference/app/components/v-card-title.md b/docs/reference/app/components/v-card-title.md deleted file mode 100644 index 4155933c7e..0000000000 --- a/docs/reference/app/components/v-card-title.md +++ /dev/null @@ -1,17 +0,0 @@ -# Card Title - -This component is used to give a `v-card` an already stylized title. - -```html - - My Own Title - -``` - -## Reference - -#### Slots - -| Slot | Description | Data | -| --------- | ----------------------- | ---- | -| _default_ | Where the title will go | | diff --git a/docs/reference/app/components/v-card.md b/docs/reference/app/components/v-card.md deleted file mode 100644 index 8e353b6894..0000000000 --- a/docs/reference/app/components/v-card.md +++ /dev/null @@ -1,77 +0,0 @@ -# Card - -A card is nothing but a v-sheet with predefined building blocks to enforce consistency. - -## Usage - -```html - - Hello, world! - This is a card - Consectetur enim ullamco sint sit deserunt proident consectetur. - - Save - - -``` - -Cards can be used to consistently style dialogs: - -```html - - - - - Are you sure you want to delete 1 item? - - Cancel - Yes - - - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ---------- | ------------------------------------------------- | ------- | --------- | -| `disabled` | Disable the card, prevents all cursor interaction | `false` | `Boolean` | -| `tile` | Render without rounded corners | `false` | `Boolean` | - -#### Events - -n/a - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ---- | -| _default_ | | | - -#### CSS Variables - -| Variable | Default | -| --------------------------- | --------------------------- | -| `--v-card-min-width` | `none` | -| `--v-card-max-width` | `400px` | -| `--v-card-min-height` | `none` | -| `--v-card-max-height` | `min-content` | -| `--v-card-padding` | `16px` | -| `--v-card-background-color` | `var(--background-subdued)` | -| `--v-card-height` | `auto` | - ---- - -# Card Title - -Functional component that enforces consistent styling. - -## Usage - -```html -Hello, world! -``` diff --git a/docs/reference/app/components/v-checkbox.md b/docs/reference/app/components/v-checkbox.md deleted file mode 100644 index a2989d2685..0000000000 --- a/docs/reference/app/components/v-checkbox.md +++ /dev/null @@ -1,124 +0,0 @@ -# Checkbox - -Display a single checkbox on which you can model a boolean. - -```html - -``` - -## Colors - -The colors can be changed via the css variables `--v-checkbox-color`. - -```html - - - - - - -``` - -## Boolean vs arrays - -Just as with checkboxes, you can use `v-model` with both an array and a boolean: - -```html - - - -``` - -Keep in mind to pass the `value` prop with a unique value when using arrays in `v-model`. - -## Indeterminate - -The indeterminate state can be set with the `indeterminate` prop. We recommend using the `v-model` directive with the -indeterminate prop, so the checkbox can set change it too: - -```html - - - -``` - -If you can't, you should listen to the `update:indeterminate` event and respond to that: - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------------------- | ------------------------------------------------------------------------ | --------------------------- | ------------------ | -| `value` | Value for checkbox. Similar to value attr on checkbox type input in HTML | `null` | `String` | -| `input-value` | Value that's used with `v-model`. Either boolean or array of values | `false` | `[Boolean, Array]` | -| `label` | Label for the checkbox | `null` | `String` | -| `disabled` | Disable the checkbox | `false` | `Boolean` | -| `indeterminate` | Show the indeterminate state | `false` | `Boolean` | -| `icon-on` | What icon to use for the on state | `'check_box'` | `String` | -| `icon-off` | What icon to use for the off state | `'check_box_outline_blank'` | `String` | -| `icon-indeterminate` | What icon to use for the indeterminate state | `'indeterminate_check_box'` | `String` | -| `block` | Show as styled block. Matches input size | `false` | `Boolean` | -| `custom-value` | | `false` | `Boolean` | - -#### Slots - -| Slot | Description | Data | -| --------- | ---------------------------------- | ---- | -| `prepend` | Rendered right before the checkbox | | -| `append` | Rendered right after the label | | -| _default_ | | | - -#### Events - -| Event | Description | Value | -| ---------------------- | -------------------------- | -------------------------- | -| `change` | New state for the checkbox | Boolean or array of values | -| `update:indeterminate` | New state for the checkbox | Boolean or array of values | - -#### CSS Variables - -| Variable | Default | -| -------------------- | ---------------- | -| `--v-checkbox-color` | `var(--primary)` | diff --git a/docs/reference/app/components/v-chip.md b/docs/reference/app/components/v-chip.md deleted file mode 100644 index 051e3fa638..0000000000 --- a/docs/reference/app/components/v-chip.md +++ /dev/null @@ -1,87 +0,0 @@ -# Chip - -Chips are small round components that can be used to display tags or similar data. - -```html -I'm a chip! -``` - -## Sizes - -The chip component supports the following sizes through the use of props: - -- x-small -- small -- (default) -- large -- x-large - -```html -I'm a chip! -``` - -## Colors - -You can set the color, background color, hover color, and background hover color with the `--v-chip-color`, -`--v-chip-background-color`, `--v-chip-color-hover`, and `--v-chip-background-color-hover` css variables respectively: - -```html -I'm a chip! - -``` - -## Clicks / Closes - -There are two events, one when clicking on the chip called `click` and one when clicking on the enabled close icon -called `close`. - -```html -Hello! -I'm closeable! -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------------ | ---------------------------------------------------- | --------- | --------- | -| `active` | Change visibility. Can be reacted to via `sync` | `null` | `Boolean` | -| `close` | Displays a close icon which triggers the close event | `false` | `Boolean` | -| `close-icon` | Which icon should be displayed instead of `close ` | `'close'` | `String` | -| `outlined` | No background | `false` | `Boolean` | -| `label` | Label style | `true` | `Boolean` | -| `disabled` | Disabled state | `false` | `Boolean` | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ---- | -| _default_ | | -- | - -#### Events - -| Event | Description | Value | -| --------------- | ---------------------------------------------------------------------------------------------- | ----- | -| `click` | Triggers when clicked somewhere on the chip | | -| `close` | Triggers when the `close` prop is enabled and gets clicked (Doesn't trigger the `click` event) | | -| `update:active` | | | - -#### CSS Variables - -| Variable | Default | -| --------------------------------- | ------------------------------ | -| `--v-chip-color` | `var(--foreground-normal)` | -| `--v-chip-background-color` | `var(--background-normal-alt)` | -| `--v-chip-color-hover` | `var(--white)` | -| `--v-chip-background-color-hover` | `var(--primary-125)` | -| `--v-chip-close-color` | `var(--danger)` | -| `--v-chip-close-color-disabled` | `var(--primary)` | -| `--v-chip-close-color-hover` | `var(--primary-125)` | diff --git a/docs/reference/app/components/v-detail.md b/docs/reference/app/components/v-detail.md deleted file mode 100644 index 987fec3f44..0000000000 --- a/docs/reference/app/components/v-detail.md +++ /dev/null @@ -1,37 +0,0 @@ -# Detail - -Use the detail component to hide not so important information or elements. - -```html - -
I'm hidden until you open the component
-
-``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------------ | ----------------------- | ------------------------- | --------- | -| `active` | Used with `v-model` | `undefined` | `Boolean` | -| `label` | Label of detail | `i18n.global.t('toggle')` | `String` | -| `start-open` | Have it open by default | `false` | `Boolean` | -| `disabled` | Disable any interaction | `false` | `Boolean` | - -#### Events - -| Event | Description | Value | -| -------- | --------------------------- | --------- | -| `toggle` | New active value of divider | `boolean` | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------------------------- | --------------------- | -| _default_ | Content of the detail section | | -| `title` | Content to render in divider | `{ active: boolean }` | - -#### CSS Variables - -n/a diff --git a/docs/reference/app/components/v-dialog.md b/docs/reference/app/components/v-dialog.md deleted file mode 100644 index e3f5b24fbb..0000000000 --- a/docs/reference/app/components/v-dialog.md +++ /dev/null @@ -1,43 +0,0 @@ -# Dialog - -Renders an overlay with a flex slot rendering whatever content you pass. - -```html - - -

Are you sure you want to delete this item?

- No - Yes -
-
-``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------------ | --------------------------------------------------- | ----------- | --------- | -| `persistent` | Disable closing by clicking on the side | `false` | `Boolean` | -| `active` | Can be used in combination with `v-model` | `undefined` | `Boolean` | -| `placement` | Display it either in the `center` or to the `right` | `'center'` | `String` | - -#### Slots - -| Slot | Description | Data | -| ----------- | --------------------------------------------- | ---- | -| _default_ | Whatever should be rendered inside the dialog | | -| `activator` | Insert an activator for the dialog | | - -#### Events - -| Event | Description | Value | -| -------- | ----------------------- | --------- | -| `toggle` | Change the active state | `boolean` | -| `esc` | Escape has been pressed | `boolean` | - -#### CSS Variables - -| Variable | Default | -| -------------------- | ------- | -| `--v-dialog-z-index` | `100` | diff --git a/docs/reference/app/components/v-divider.md b/docs/reference/app/components/v-divider.md deleted file mode 100644 index 3fc3ddacf7..0000000000 --- a/docs/reference/app/components/v-divider.md +++ /dev/null @@ -1,35 +0,0 @@ -# Divider - -Divides content. Made to be used in `v-list` or `v-tabs` components. - -```html -New Section -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------------- | ----------------------------------------------------- | ------- | --------- | -| `vertical` | Render the divider vertically | `false` | `Boolean` | -| `inline-title` | Render the title inline with the divider, or under it | `true` | `Boolean` | -| `large` | Renders a larger divider | `false` | `Boolean` | - -#### Events - -n/a - -#### Slots - -| Slot | Description | Data | -| --------- | ------------------------------------------------------------------------ | ---- | -| _default_ | Label on the divider. This isn't rendered in vertical mode. | | -| `icon` | Icon on the divider. Rendered in all modes, inline with title if present | | - -#### CSS Variables - -| Variable | Default | -| ------------------------- | ------------------------------ | -| `--v-divider-color` | `var(--border-normal)` | -| `--v-divider-label-color` | `var(--foreground-normal-alt)` | diff --git a/docs/reference/app/components/v-drawer.md b/docs/reference/app/components/v-drawer.md deleted file mode 100644 index b95192d0e6..0000000000 --- a/docs/reference/app/components/v-drawer.md +++ /dev/null @@ -1,48 +0,0 @@ -# Drawer - -A more robust dialog that is rendered at the side and provides more space than a usual dialog. Can be helpful for -relational or nested data. - -```html - -
This text will show up in the drawer
-
-``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| --------------- | ------------------------------------------------------ | -------------------------- | --------- | -| `title`\* | The title of the drawer | | `String` | -| `subtitle` | The subtitle of the drawer | `null` | `String` | -| `active` | Can be used with `v-model` to open or close the drawer | `undefined` | `Boolean` | -| `persistent` | Disallow closing the drawer by clicking out of it | `false` | `Boolean` | -| `icon` | An icon for the drawer | `'box'` | `String` | -| `sidebar-label` | A label for the sidebar | `i18n.global.t('sidebar')` | `String` | - -#### Events - -| Event | Description | Value | -| -------- | ---------------------------------------------------------------- | --------- | -| `cancel` | When escape is pressed or the drawer gets canceled in other ways | | -| `toggle` | When the drawer gets opened or closed | `boolean` | - -#### Slots - -| Slot | Description | Data | -| ----------------- | ------------------------------------------------------ | ---- | -| `activator` | Elements placed inside here can activate the drawer | `on` | -| `sidebar` | Display components to the side of the drawer like tabs | | -| `subtitle` | Add a custom subtitle | | -| `actions:prepend` | Prepend actions to the drawer | | -| `actions` | Add actions to the top right corner | | -| `header:append` | Append your elements to the header | | -| _default_ | Where the content of the drawer goes | | - -#### CSS Variables - -| Variable | Default | -| ---------------------- | ------- | -| `--v-drawer-max-width` | `856px` | diff --git a/docs/reference/app/components/v-error.md b/docs/reference/app/components/v-error.md deleted file mode 100644 index 27c3165cb7..0000000000 --- a/docs/reference/app/components/v-error.md +++ /dev/null @@ -1,15 +0,0 @@ -# Error - -Display an api request error. - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| --------- | --------------------------------------- | ------- | ----- | -| `error`\* | The error returned from the api request | | `any` | diff --git a/docs/reference/app/components/v-fancy-select.md b/docs/reference/app/components/v-fancy-select.md deleted file mode 100644 index bfe9093b51..0000000000 --- a/docs/reference/app/components/v-fancy-select.md +++ /dev/null @@ -1,67 +0,0 @@ -# Fancy Select - -Mimics the functionality of a select, where only the current value is shown, but does it in a different visual -representation. - -## Usage - -```html - -``` - -## FancySelectItem - -| Prop | Description | Type | -| ------------- | ------------------------------------------ | ---------------------- | -| `icon` | Which icon to display | `string` | -| `value` | Which value the item represents | `string or number` | -| `text` | The displayed text | `undefined or string` | -| `description` | Optional description to display | `undefined or string` | -| `divider` | If set to true, display an divider instead | `undefined or boolean` | -| `iconRight` | Display an optional icon to the right | `undefined or string` | - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ---------- | --------------------------------------- | ------- | ------------------- | -| `items`\* | The list of possible items to display | | `FancySelectItem[]` | -| `value` | used to model the selected items | `null` | `[String, Number]` | -| `disabled` | Disable selecting / deselecting a value | `false` | `Boolean` | - -#### Events - -| Event | Description | Value | -| ------- | -------------------------- | --------- | -| `input` | Syncs value with `v-model` | `boolean` | - -#### Slots - -n/a - -#### CSS Variables - -n/a diff --git a/docs/reference/app/components/v-field-select.md b/docs/reference/app/components/v-field-select.md deleted file mode 100644 index 1ebb57070e..0000000000 --- a/docs/reference/app/components/v-field-select.md +++ /dev/null @@ -1,25 +0,0 @@ -# Field Select - -Allows for easy selection of field inside a collection. Also works with relations inside a collection. - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------------- | ---------------------------------------------------------- | ------------ | ---------- | -| `collection`\* | From where the fields should be selected | | `String` | -| `disabled` | Disables this component | `false` | `Boolean` | -| `value` | Can be used to model the selected field | `null` | `string[]` | -| `depth` | If greater than `0`, it also considers relations of fields | `1` | `Number` | -| `inject` | Inject you own fields, collections or relations | `() => ({})` | `Object` | - -#### Events - -| Event | Description | Value | -| ------- | --------------------- | ---------- | -| `input` | The changed selection | `string[]` | diff --git a/docs/reference/app/components/v-field-template.md b/docs/reference/app/components/v-field-template.md deleted file mode 100644 index 601b2fab5c..0000000000 --- a/docs/reference/app/components/v-field-template.md +++ /dev/null @@ -1,27 +0,0 @@ -# Field Template - -Similar to the v-field-select. Allows you to select fields or relational fields from a collection with the benefit of -being able to add text in between. - -Models a template string like `My name is {name} and I'm {age} years old`. - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------------- | ---------------------------------------------------------- | ------- | --------- | -| `collection`\* | From where the fields should be selected | | `String` | -| `disabled` | Disables this component | `false` | `Boolean` | -| `value` | Can be used to model the template string | `null` | `String` | -| `depth` | If greater than `0`, it also considers relations of fields | `2` | `Number` | - -#### Events - -| Event | Description | Value | -| ------- | --------------------------- | -------- | -| `input` | The changed template string | `String` | diff --git a/docs/reference/app/components/v-form.md b/docs/reference/app/components/v-form.md deleted file mode 100644 index 5c870aba58..0000000000 --- a/docs/reference/app/components/v-form.md +++ /dev/null @@ -1,41 +0,0 @@ -# Form - -Renders a form using interfaces based on the passed collection name. - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------- | -| `collection` | The collection of which you want to render the fields | `undefined` | `String` | -| `fields` | Array of fields to render. This can be used instead of the collection prop | `undefined` | `Field[]` | -| `initial-values` | Object of the starting values of the fields | `null` | `FieldValues` | -| `model-value` | The edits that were made after the form was rendered. Being used in `v-model` | `null` | `FieldValues` | -| `loading` | Display the form in a loading state. Prevents the ctx menus from being used and renders skeleton loaders for the fields | `false` | `Boolean` | -| `batch-mode` | If enabled, allows to select multiple entries | `false` | `Boolean` | -| `primary-key` | The primary key of the given collection | `null` | `[String, Number]` | -| `disabled` | Disables any interaction with the form | `false` | `Boolean` | -| `validation-errors` | Add custom validation to any field | `() => []` | `ValidationError[]` | - -**Note**: You have to pass either the collection or fields prop. - -#### Slots - -n/a - -#### Events - -| Event | Description | Value | -| -------------------- | ------------------------ | ----- | -| `update:model-value` | Edits have been updated. | | diff --git a/docs/reference/app/components/v-hover.md b/docs/reference/app/components/v-hover.md deleted file mode 100644 index 32a992fded..0000000000 --- a/docs/reference/app/components/v-hover.md +++ /dev/null @@ -1,50 +0,0 @@ -# Hover - -Adds hover functionality to any component you place inside. Can be used to display different states of a component -depending if you are hovering over it. - -```html - - - -``` - -## Delays - -You can control how long the hover state persists after the user leaves the element with the `close-delay` prop. -Likewise, you can set how long it will take before the hover state is set with the `open-delay` prop: - -```html - - - - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------------- | -------------------------------------------- | ------- | --------- | -| `close-delay` | Delay (ms) before the hover state is removed | `0` | `Number` | -| `open-delay` | Delay (ms) before the hover state is applied | `0` | `Number` | -| `disabled` | Disables the hover state from happening | `false` | `Boolean` | -| `tag` | What HTML tag to use for the wrapper | `'div'` | `String` | - -#### Events - -n/a - -#### Slots - -| Slot | Description | Data | -| --------- | ----------------------------------------------------------- | ---- | -| _default_ | Place your components that should use the hover effect here | | diff --git a/docs/reference/app/components/v-icon.md b/docs/reference/app/components/v-icon.md deleted file mode 100644 index 8871fd2492..0000000000 --- a/docs/reference/app/components/v-icon.md +++ /dev/null @@ -1,70 +0,0 @@ -# Icon - -The icon component allows you to render any [Material Design Icons](https://material.io/icons). It also supports -rendering of custom SVG based icons. - -## Sizes / Colors - -The icon component supports multiple sizes and colors. The color prop accepts any valid CSS color. Color changes are -done via the css variable `--v-icon-color` like in the example below. - -```html - - -``` - -## Custom Size - -If the default sizes don't give you the exact size you require, you can add the `size` prop with any custom pixel value. -Note: we recommend using one of the pre-defined sizes to ensure a consistent look across the platform. - -## Outline - -You can render the outline variant of the Material Icon by setting the `outline` property. - -## Click events - -When you add a click event to the icon, the icon will automatically add a pointer cursor. - -## Left / Right - -Oftentimes, you'll use the icon next to some text, for example in a button. When doing this, you can use the `left` / -`right` props to add some spacing to the icon: - -```html - - - Add new - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ---------- | ------------------------------------ | ------- | --------- | -| `name`\* | Which icon to display | | `String` | -| `filled` | Removes the outline style if enabled | `false` | `Boolean` | -| `sup` | | `false` | `Boolean` | -| `left` | Displays the icon more to the left | `false` | `Boolean` | -| `right` | Displays the icon more to the right | `false` | `Boolean` | -| `disabled` | Disables the icon | `false` | `Boolean` | - -#### CSS Variables - -| Variable | Default | -| ---------------------- | -------------- | -| `--v-icon-color` | `currentColor` | -| `--v-icon-color-hover` | `currentColor` | -| `--v-icon-size` | `24px` | - -#### Events - -| Event | Description | Value | -| ------- | ------------------------------- | ----- | -| `click` | Fires when clicking on the icon | | diff --git a/docs/reference/app/components/v-info.md b/docs/reference/app/components/v-info.md deleted file mode 100644 index 2d52115091..0000000000 --- a/docs/reference/app/components/v-info.md +++ /dev/null @@ -1,33 +0,0 @@ -# Info - -Renders a stylized informational placard. It's similar in `v-notice` in it's use case. - -```html -We couldn't find the user you're looking for. -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| --------- | --------------------------------------------- | -------- | ---------------------------------------------- | -| `title`\* | The title to display in the info | | `String` | -| `icon` | What icon to render above the title | `'box'` | `String` | -| `type` | One of `info`, `success`, `warning`, `danger` | `'info'` | `'info' or 'success' or 'warning' or 'danger'` | -| `center` | Display the info centered | `false` | `Boolean` | - -#### Events - -n/a - -#### Slots - -| Slot | Description | Data | -| --------- | ------------------------------------------------------------ | ---- | -| _default_ | Default content area. Is rendered within a styled `

` tag. | | -| `append` | After the main body copy. Can be used to inject buttons etc. | | - -#### CSS Variables - -n/a diff --git a/docs/reference/app/components/v-input.md b/docs/reference/app/components/v-input.md deleted file mode 100644 index 5d2e6e58df..0000000000 --- a/docs/reference/app/components/v-input.md +++ /dev/null @@ -1,69 +0,0 @@ -# Input - -Displays the usual input. Can be used to model strings and numbers. - -```html - -``` - -## Attributes & Events - -The HTML `` element supports a huge amount of attributes and events. In order to support all of these, all props -that aren't specially handled (see list below) will be passed on to the `` element directly. This allows you to -change anything you want on the input. - -## Prefixes / Suffixes - -You can add any custom (text) prefix/suffix to the value in the input using the `prefix` and `suffix` slots. - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ---------------- | -------------------------------------------------------------- | -------- | ------------------ | -| `value` | Used with `v-model` to mirror the entered value | `null` | `[String, Number]` | -| `autofocus` | Autofocusses the input on render | `false` | `Boolean` | -| `disabled` | Set the disabled state for the input | `false` | `Boolean` | -| `full-width` | Render the input with 100% width | `true` | `Boolean` | -| `prefix` | Prefix the users value with a value | `null` | `String` | -| `suffix` | Show a value at the end of the input | `null` | `String` | -| `slug` | Force the value to be URL safe | `false` | `Boolean` | -| `slug-separator` | What character to use as separator in slugs | `'-'` | `String` | -| `active` | Force the focus state | `false` | `Boolean` | -| `trim` | Trim the start and end whitespace | `false` | `Boolean` | -| `nullable` | When active, sets an empty entry to null | `true` | `Boolean` | -| `type` | Can be `text` or `number` | `'text'` | `String` | -| `max` | The maximum number that can be entered | `null` | `Number` | -| `min` | The minimum number that can be entered | `null` | `Number` | -| `step` | In which unit steps should be counted up or down | `1` | `Number` | -| `db-safe` | Make the value save to be used with the DB | `false` | `Boolean` | -| `hide-arrows` | Hide the arrows that are used to increase or decrease a number | `false` | `Boolean` | - -Note: all other attached attributes are bound to the input HTMLElement in the component. This allows you to attach any -of the standard HTML attributes like `min`, `length`, or `pattern`. - -#### Slots - -| Slot | Description | Data | -| --------------- | ------------------------------------------------- | ------------------------------------------------- | -| `prepend-outer` | Before the input | `{ disabled: boolean, value: string or number; }` | -| `prepend` | In the input, before the value, before the prefix | `{ disabled: boolean, value: string or number; }` | -| `append` | In the input, after the value, after the suffix | `{ disabled: boolean, value: string or number; }` | -| `append-outer` | After the input | `{ disabled: boolean, value: string or number; }` | -| `input` | | | - -#### CSS Variables - -| Variable | Default | -| ----------------------------- | --------------------------- | -| `--v-input-font-family` | `var(--family-sans-serif)` | -| `--v-input-placeholder-color` | `var(--foreground-subdued)` | - -#### Events - -| Event | Description | Value | -| --------- | --------------------------------- | ------------------ | -| `click` | Fires when the input gets clicked | | -| `keydown` | When a key has been pressed | | -| `input` | Updated the modeled value | `String or Number` | diff --git a/docs/reference/app/components/v-item-group.md b/docs/reference/app/components/v-item-group.md deleted file mode 100644 index 0648a12160..0000000000 --- a/docs/reference/app/components/v-item-group.md +++ /dev/null @@ -1,155 +0,0 @@ -# Item Group - -Provides the ability to make groups of items out of any nested component. Can be reused to make more advanced selectable -elements like a list of cards, or a button group. - -## Usage - -```html - - - -``` - -The `v-item-group` component will keep the final state for the selection; every nested `v-item` component will be -registered to the context of the first `v-item-group` parent up in the tree. This means that `v-item` can be in any -nested component or sibling: - -```html - - -

- -
-
- - - -
- -``` - -It also means you can theoretically nest item-groups inside of items: - -```html - - -
- - - -
- -
-
- - - -
-
-
-
-
- - - -
-
-``` - -(That being said, if you ever find yourself in this situation, think long and hard if what you're doing makes sense) - -### Active / Toggle - -Every `v-item` provides the `active` state and a `toggle` function to the default slot. Use this to render custom markup -/ styling and to toggle the active state for this item: - -```html - -

Am I active? {{ active }}

- Toggle active state -
-``` - -### Custom values - -By default, the `v-item-group` component will use the index of the child as model value (eg `[2, 4]`). The child -`v-item` component accepts a `value` prop that lets you choose what is used as identifier for the v-item. This can be -useful when you're working with a predefined list of items: - -```html - - - -``` - -In this case, the selection state for all items selected would be `[15, 414, 'jolly']` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ----------- | ----------------------------------------------------- | -------------- | ---------------------- | -| `value` | Used with `v-model` to model the selected items | `undefined` | `(string or number)[]` | -| `mandatory` | If enabled, at least one item has to be selected | `false` | `Boolean` | -| `max` | The maximum amount of items that can be selected | `-1` | `Number` | -| `multiple` | If enabled, multiple elements can be selected | `false` | `Boolean` | -| `scope` | Items that do not have the same scope will be ignored | `'item-group'` | `String` | - -#### Events - -| Event | Description | Value | -| ------- | -------------------------------- | -------------------- | -| `input` | Used to update the modeled value | (String or Number)[] | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------------------------------------------------------- | ---- | -| _default_ | All items placed inside here will be part of the item group | | diff --git a/docs/reference/app/components/v-item.md b/docs/reference/app/components/v-item.md deleted file mode 100644 index 8c5b934f38..0000000000 --- a/docs/reference/app/components/v-item.md +++ /dev/null @@ -1,21 +0,0 @@ -# Item - -Should be used in combination with `v-item-group` to model the state of active / inactive items. For more information -have a look at the item group component. - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------- | ----------------------------------------------------- | -------------- | --------- | -| `value` | Which value to represent when active | `null` | `String` | -| `scope` | Only matches to a group when both scopes are the same | `'item-group'` | `String` | -| `active` | If the item is currently activated | `undefined` | `Boolean` | -| `watch` | If the active state should update after initial set | `true` | `Boolean` | - -#### Slots - -| Slot | Description | Data | -| --------- | --------------------------- | ---- | -| _default_ | Where the item content goes | | diff --git a/docs/reference/app/components/v-list-group.md b/docs/reference/app/components/v-list-group.md deleted file mode 100644 index 19a9d91060..0000000000 --- a/docs/reference/app/components/v-list-group.md +++ /dev/null @@ -1,49 +0,0 @@ -# List Group - -Used to display nested items inside a list. - -```html - - Item 1 - Item 2 - Item 3 - - - - - Item 1-1 - Item 1-2 - Item 1-2 - - -``` - -## Reference - -#### Events - -| Event | Description | Value | -| ------- | ----------- | ----- | -| `click` | | | - -#### Props - -| Prop | Description | Default | Type | -| ---------- | ----------- | ----------- | ------------------ | -| `multiple` | | `true` | `Boolean` | -| `to` | | `null` | `String` | -| `active` | | `false` | `Boolean` | -| `exact` | | `false` | `Boolean` | -| `disabled` | | `false` | `Boolean` | -| `scope` | | `undefined` | `String` | -| `value` | | `undefined` | `[String, Number]` | -| `dense` | | `false` | `Boolean` | - -#### Slots - -| Slot | Description | Data | -| ----------- | ----------- | ---- | -| `activator` | | | -| _default_ | | | diff --git a/docs/reference/app/components/v-list-item-content.md b/docs/reference/app/components/v-list-item-content.md deleted file mode 100644 index 340f4dea84..0000000000 --- a/docs/reference/app/components/v-list-item-content.md +++ /dev/null @@ -1,18 +0,0 @@ -# List Item Content - -Add properly formatted content to the `v-list-item`. - -## Reference - -#### CSS Variables - -| Variable | Default | -| ----------------------------------- | -------------------------- | -| `--v-list-item-content-padding` | `9px 0` | -| `--v-list-item-content-font-family` | `var(--family-sans-serif)` | - -#### Slots - -| Slot | Description | Data | -| --------- | ---------------------- | ---- | -| _default_ | Where the content goes | | diff --git a/docs/reference/app/components/v-list-item-hint.md b/docs/reference/app/components/v-list-item-hint.md deleted file mode 100644 index 1721a9e2de..0000000000 --- a/docs/reference/app/components/v-list-item-hint.md +++ /dev/null @@ -1,17 +0,0 @@ -# List Item Hint - -Adds a hint to the `v-list-item` component. - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------- | ----------- | ------- | --------- | -| `center` | | `false` | `Boolean` | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ---- | -| _default_ | | | diff --git a/docs/reference/app/components/v-list-item-icon.md b/docs/reference/app/components/v-list-item-icon.md deleted file mode 100644 index b243b9f4f5..0000000000 --- a/docs/reference/app/components/v-list-item-icon.md +++ /dev/null @@ -1,30 +0,0 @@ -# List Item Icon - -Adds an icon to a `v-list-item`. - -```html - - - This is a person - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------- | ---------------- | ------- | --------- | -| `center` | Centers the icon | `false` | `Boolean` | - -#### CSS Variables - -| Variable | Default | -| -------------------------- | --------------------------- | -| `--v-list-item-icon-color` | `var(--foreground-subdued)` | - -#### Slots - -| Slot | Description | Data | -| --------- | ------------------- | ---- | -| _default_ | Where the icon goes | | diff --git a/docs/reference/app/components/v-list-item.md b/docs/reference/app/components/v-list-item.md deleted file mode 100644 index 280c75f722..0000000000 --- a/docs/reference/app/components/v-list-item.md +++ /dev/null @@ -1,49 +0,0 @@ -# List Item - -Used inside a `v-list` to display an item inside the given list. - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ---------- | -------------------------------------------------- | ----------- | -------------------- | -| `value` | What value to represent when active | `undefined` | `[String, Number]` | -| `large` | If the item should be displayed larger | `false` | `Boolean` | -| `dense` | Makes the item smaller | `false` | `Boolean` | -| `to` | Where the item should link to | `null` | `string or Location` | -| `href` | Same as `to` except that it takes an external link | `null` | `String` | -| `disabled` | Disables the item | `false` | `Boolean` | -| `active` | If the item should be active or not | `false` | `Boolean` | -| `dashed` | Adds a dashed style | `false` | `Boolean` | -| `exact` | | `false` | `Boolean` | -| `download` | | `null` | `String` | - -# - -### CSS Variables - -| Variable | Default | -| --------------------------------------- | --------------------------------------------------------------------- | -| `--v-list-item-min-height-large` | `40px` | -| `--v-list-item-min-height` | `var(--v-list-item-min-height)` | -| `--v-list-item-padding-large` | `0 8px` | -| `--v-list-item-padding` | `0 8px 0 calc(8px + var(--v-list-item-indent, 0px))` | -| `--v-list-item-margin-large` | `4px 0` | -| `--v-list-item-margin` | `2px 0` | -| `--v-list-item-min-width` | `none` | -| `--v-list-item-max-width` | `none` | -| `--v-list-item-max-height` | `auto` | -| `--v-list-item-border-radius` | `var(--border-radius)` | -| `--v-list-item-margin-bottom` | `0` | -| `--v-list-item-color` | `var(--v-list-color, var(--foreground-normal))` | -| `--v-list-item-color-hover` | `var(--v-list-color-hover, var(--foreground-normal))` | -| `--v-list-item-color-active` | `var(--v-list-color-active, var(--foreground-normal))` | -| `--v-list-item-background-color-hover` | `var(--v-list-background-color-hover, var(--background-normal-alt))` | -| `--v-list-item-background-color-active` | `var(--v-list-background-color-active, var(--background-normal-alt))` | - -#### Slots - -| Slot | Description | Data | -| --------- | --------------------------- | ---- | -| _default_ | Where the item content goes | | diff --git a/docs/reference/app/components/v-list.md b/docs/reference/app/components/v-list.md deleted file mode 100644 index f3e764b1d0..0000000000 --- a/docs/reference/app/components/v-list.md +++ /dev/null @@ -1,59 +0,0 @@ -# List - -Display usual lists. Also works with nested data. - -```html - - Item 1 - Item 2 - Item 3 - - - - - Item 1-1 - Item 1-2 - Item 1-2 - - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------------- | ----------------------------------------------------------- | ---------- | ---------------------- | -| `active-items` | Used with `v-model` to model all selected items in the list | `() => []` | `(number or string)[]` | -| `large` | Displays each list item a bit larger | `false` | `Boolean` | -| `multiple` | Allows to select multiple items in the list | `true` | `Boolean` | -| `mandatory` | At least one item has to be selected | `true` | `Boolean` | - -#### CSS Variables - -| Variable | Default | -| ---------------------------------- | ------------------------------ | -| `--v-list-padding` | `4px 0` | -| `--v-list-max-height` | `none` | -| `--v-list-max-width` | `none` | -| `--v-list-min-width` | `220px` | -| `--v-list-min-height` | `none` | -| `--v-list-color` | `var(--foreground-normal-alt)` | -| `--v-list-color-hover` | `var(--foreground-normal-alt)` | -| `--v-list-color-active` | `var(--foreground-normal-alt)` | -| `--v-list-background-color-hover` | `var(--background-normal-alt)` | -| `--v-list-background-color-active` | `var(--background-normal-alt)` | - -#### Events - -| Event | Description | Value | -| ------- | ------------------------------------ | ----- | -| `input` | Used to update the current selection | | - -#### Slots - -| Slot | Description | Data | -| --------- | -------------------------- | ---- | -| _default_ | Render all list items here | | diff --git a/docs/reference/app/components/v-menu.md b/docs/reference/app/components/v-menu.md deleted file mode 100644 index e75560ccba..0000000000 --- a/docs/reference/app/components/v-menu.md +++ /dev/null @@ -1,42 +0,0 @@ -# Menu - -Renders a dropdown menu. Can be attached to an activator element or free floating. - -**NOTE** - -Due to the fact that a menu is rendered through a teleport, dialogs don't work great when rendered from within a menu. - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------------------------ | ----------------------------------------------------------------- | ----------- | ----------- | -| `placement` | Where to position the popper. | `'bottom'` | `Placement` | -| `value` | Value to control menu active state | `undefined` | `Boolean` | -| `close-on-click` | Close the menu when clicking outside of the menu | `true` | `Boolean` | -| `close-on-content-click` | Close the menu when clicking the content of the menu | `true` | `Boolean` | -| `attached` | Attach the menu to an input | `false` | `Boolean` | -| `show-arrow` | Show an arrow pointer | `false` | `Boolean` | -| `disabled` | Menu does not appear | `false` | `Boolean` | -| `trigger` | Activate the menu on a trigger. One of `manual`, `click`, `hover` | `null` | `String` | -| `delay` | Time in ms before menu activates after trigger | `0` | `Number` | - -#### CSS Variables - -| Variable | Default | -| -------------------- | ------- | -| `--v-menu-min-width` | `100px` | - -#### Events - -| Event | Description | Value | -| ------- | ---------------------------- | --------- | -| `input` | Used to model the value prop | `Boolean` | - -#### Slots - -| Slot | Description | Data | -| ----------- | ------------------------------------------------- | ---- | -| `activator` | The activator for the menu | | -| _default_ | Elements that should be displayed inside the menu | | diff --git a/docs/reference/app/components/v-notice.md b/docs/reference/app/components/v-notice.md deleted file mode 100644 index eb44db810b..0000000000 --- a/docs/reference/app/components/v-notice.md +++ /dev/null @@ -1,31 +0,0 @@ -# Notice - -Render a small notice to warn of something or to give tips on how to use things. - -```html -I'm a notice! -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------- | ------------------------------------------------------------------ | ---------- | ---------------------------------------------------------- | -| `type` | One of `info`, `success`, `warning`, `danger` | `'normal'` | `'normal' or 'info' or 'success' or 'warning' or 'danger'` | -| `icon` | Custom icon name, or false if you want to hide the icon completely | `null` | `[String, Boolean]` | -| `center` | Render notice content centered | `false` | `Boolean` | - -#### CSS Variables - -| Variable | Default | -| ----------------------------- | --------------------------- | -| `--v-notice-color` | `var(--foreground-subdued)` | -| `--v-notice-background-color` | `var(--background-subdued)` | -| `--v-notice-icon-color` | `var(--foreground-subdued)` | - -#### Slots - -| Slot | Description | Data | -| --------- | ------------------------------------ | ---- | -| _default_ | Whatever should be inside the notice | | diff --git a/docs/reference/app/components/v-overlay.md b/docs/reference/app/components/v-overlay.md deleted file mode 100644 index f5740b9e8d..0000000000 --- a/docs/reference/app/components/v-overlay.md +++ /dev/null @@ -1,53 +0,0 @@ -# Overlay - -The overlay is a fairly barebones component that's meant to be used with modals / confirms / other attention requiring -actions. - -```html - - Close overlay - -``` - -## Color - -The colors can be changed via the css variable `--v-overlay-color`. - -```html - - Close overlay - - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ---------- | ------------------------- | ------- | --------- | -| `active` | Show / hide the overlay | `false` | `Boolean` | -| `absolute` | Add `position: absolute;` | `false` | `Boolean` | - -#### CSS Variables - -| Variable | Default | -| --------------------- | ---------------------- | -| `--v-overlay-color` | `var(--overlay-color)` | -| `--v-overlay-z-index` | `600` | - -#### Events - -| Event | Description | Value | -| ------- | ----------- | ----- | -| `click` | | | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ---- | -| _default_ | | | diff --git a/docs/reference/app/components/v-pagination.md b/docs/reference/app/components/v-pagination.md deleted file mode 100644 index 998150e3c9..0000000000 --- a/docs/reference/app/components/v-pagination.md +++ /dev/null @@ -1,33 +0,0 @@ -# Pagination - -Add a pagination to a list or similar to allow for access to multiple pages. - -## Usage - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ----------------- | ------------------------------------------------ | ----------- | --------- | -| `length`\* | The amount of pages to render | `null` | `Number` | -| `value` | Currently selected page | `null` | `Number` | -| `disabled` | Disables the pagination | `false` | `Boolean` | -| `total-visible` | Specify the max total visible pagination numbers | `undefined` | `Number` | -| `show-first-last` | Show first/last buttons | `false` | `Boolean` | - -#### Events - -| Event | Description | Value | -| ------- | --------------------- | -------- | -| `input` | When the page changes | `number` | - -#### CSS Variables - -| Variable | Default | -| ----------------------------- | ---------------- | -| `--v-pagination-active-color` | `var(--primary)` | diff --git a/docs/reference/app/components/v-progress-circular.md b/docs/reference/app/components/v-progress-circular.md deleted file mode 100644 index 740645d846..0000000000 --- a/docs/reference/app/components/v-progress-circular.md +++ /dev/null @@ -1,40 +0,0 @@ -# Progress Circular - -Displays a circular progress bar as the name suggests. Can be used to show that something is loading or how much -something is done. - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| --------------- | ------------------------------------------------------- | ------- | --------- | -| `indeterminate` | If set to true displays no value but spins indefinitely | `false` | `Boolean` | -| `value` | Which value to represent going from 0 to 100 | `0` | `Number` | - -#### CSS Variables - -| Variable | Default | -| ---------------------------------------- | -------------------------- | -| `--v-progress-circular-color` | `var(--foreground-normal)` | -| `--v-progress-circular-background-color` | `var(--border-normal)` | -| `--v-progress-circular-transition` | `400ms` | -| `--v-progress-circular-speed` | `2s` | -| `--v-progress-circular-size` | `28px` | -| `--v-progress-circular-line-size` | `3px` | - -#### Events - -| Event | Description | Value | -| -------------------- | ----------- | ----- | -| `animationiteration` | | | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ---- | -| _default_ | | | diff --git a/docs/reference/app/components/v-progress-linear.md b/docs/reference/app/components/v-progress-linear.md deleted file mode 100644 index f12c96bbc1..0000000000 --- a/docs/reference/app/components/v-progress-linear.md +++ /dev/null @@ -1,42 +0,0 @@ -# Progress Linear - -Displays a linear progress bar. Can be used to show that something is loading or how much something is done. - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| --------------- | -------------------------------------- | ------- | --------- | -| `value` | Which value to represent from 0 to 100 | `0` | `Number` | -| `absolute` | Sets position to absolute | `false` | `Boolean` | -| `fixed` | Sets position to fixed | `false` | `Boolean` | -| `indeterminate` | Play a general loading animation | `false` | `Boolean` | -| `rounded` | Rounds up the corners of the progress | `false` | `Boolean` | -| `top` | Positions the bar at the top | `false` | `Boolean` | -| `bottom` | Positions the bar at the bottom | `false` | `Boolean` | - -#### CSS Variables - -| Variable | Default | -| -------------------------------------- | -------------------------- | -| `--v-progress-linear-height` | `4px` | -| `--v-progress-linear-color` | `var(--foreground-normal)` | -| `--v-progress-linear-background-color` | `var(--border-normal)` | -| `--v-progress-linear-transition` | `400ms` | - -#### Events - -| Event | Description | Value | -| -------------------- | ----------- | ----- | -| `animationiteration` | | | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ---- | -| _default_ | | | diff --git a/docs/reference/app/components/v-radio.md b/docs/reference/app/components/v-radio.md deleted file mode 100644 index df5cc0dc49..0000000000 --- a/docs/reference/app/components/v-radio.md +++ /dev/null @@ -1,41 +0,0 @@ -# Radio - -Classic radio buttons. Nothing special. - -```html - - - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------------- | ------------------------------------------- | -------------------------- | --------- | -| `value`\* | What value to represent when selected | | `String` | -| `input-value` | Selected value. Used as value for `v-model` | `null` | `String` | -| `label` | Label to render next to the radio | `null` | `String` | -| `disabled` | Disable the radio button | `false` | `Boolean` | -| `icon-on` | Change the icon to display when enabled | `'radio_button_checked'` | `String` | -| `icon-off` | Change the icon to display when disabled | `'radio_button_unchecked'` | `String` | -| `block` | Render the radio in a block like style | `false` | `Boolean` | - -#### Events - -| Event | Description | Value | -| -------- | ------------------------------------------------------------- | -------- | -| `change` | When the state of the radio button changes. Used in `v-model` | `string` | - -#### Slots - -| Slot | Description | Data | -| ------- | --------------------------------------------------------------------------------- | ---- | -| `label` | Custom override for label slot. Allows you to render custom markup in label slot. | | - -#### CSS Variables - -| Variable | Default | -| ----------------- | ---------------- | -| `--v-radio-color` | `var(--primary)` | diff --git a/docs/reference/app/components/v-select.md b/docs/reference/app/components/v-select.md deleted file mode 100644 index 85f4b850bb..0000000000 --- a/docs/reference/app/components/v-select.md +++ /dev/null @@ -1,58 +0,0 @@ -# Select - -Renders a dropdown input. - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ---------------------------- | -------------------------------------------------------------- | --------- | ------------ | -| `items`\* | The items that should be selectable | | `ItemsRaw` | -| `item-text` | Which prop should be taken to render the text | `'text'` | `String` | -| `item-value` | Which prop should be taken to mirror the selected value | `'value'` | `String` | -| `item-icon` | Which prop should be taken to render the icon | `null` | `String` | -| `value` | Mirror with `v-model` the currently selected values | `null` | `InputValue` | -| `multiple` | Allow to select multiple values | `false` | `Boolean` | -| `placeholder` | A placeholder if no item is selected yet | `null` | `String` | -| `full-width` | Display the select in full width | `true` | `Boolean` | -| `disabled` | Disable any interaction with the select | `false` | `Boolean` | -| `show-deselect` | Allow to deselect all currently selected items | `false` | `Boolean` | -| `allow-other` | Allow to enter custom values | `false` | `Boolean` | -| `close-on-content-click` | Close the dropdown when an selection has been made | `true` | `Boolean` | -| `inline` | display the selection inline with other text | `false` | `Boolean` | -| `multiple-preview-threshold` | The maximum amount of selected items to display in the preview | `3` | `Number` | - -#### CSS Variables - -| Variable | Default | -| ------------------------ | -------------------------- | -| `--v-select-font-family` | `var(--family-sans-serif)` | - -#### Slots - -| Slot | Description | Data | -| --------- | --------------------------------- | ---- | -| `prepend` | Prepend anything to the selection | | - -#### Events - -| Event | Description | Value | -| ------- | ----------- | ----- | -| `input` | | | diff --git a/docs/reference/app/components/v-sheet.md b/docs/reference/app/components/v-sheet.md deleted file mode 100644 index fb9ff16758..0000000000 --- a/docs/reference/app/components/v-sheet.md +++ /dev/null @@ -1,47 +0,0 @@ -# Sheet - -A sheet is a component that holds other components. It provides a visual difference (layer) on the page. It's often used -when grouping fields. - -```html - -``` - -## Sizing - -The sheet component has props for `height`, `width`, `min-height`, `min-width`, `max-height`, and `max-width`. All of -these props are in pixels. - -## Color - -The color can be changed via the css variable called `--v-sheet-color`. - -```html - - -``` - -## Reference - -#### CSS Variables - -| Variable | Default | -| ---------------------------- | --------------------------- | -| `--v-sheet-background-color` | `var(--background-subdued)` | -| `--v-sheet-height` | `auto` | -| `--v-sheet-min-height` | `var(--input-height)` | -| `--v-sheet-max-height` | `none` | -| `--v-sheet-width` | `auto` | -| `--v-sheet-min-width` | `none` | -| `--v-sheet-max-width` | `none` | -| `--v-sheet-padding` | `8px` | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ---- | -| _default_ | | | diff --git a/docs/reference/app/components/v-skeleton-loader.md b/docs/reference/app/components/v-skeleton-loader.md deleted file mode 100644 index eed4beab67..0000000000 --- a/docs/reference/app/components/v-skeleton-loader.md +++ /dev/null @@ -1,22 +0,0 @@ -# Skeleton Loader - -Render a placeholder while the proper content is still loading. - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------ | ----------------------------------- | --------- | -------- | -| `type` | Name of another component to mirror | `'input'` | `String` | - -#### CSS Variables - -| Variable | Default | -| -------------------------------------- | --------------------------- | -| `--v-skeleton-loader-color` | `var(--background-page)` | -| `--v-skeleton-loader-background-color` | `var(--background-subdued)` | diff --git a/docs/reference/app/components/v-slider.md b/docs/reference/app/components/v-slider.md deleted file mode 100644 index ae9c2e792b..0000000000 --- a/docs/reference/app/components/v-slider.md +++ /dev/null @@ -1,93 +0,0 @@ -# Slider - -A standard slider as everybody knows them. - -```html - -``` - -## Color - -The colors can be changed via the css variables `--v-slider-color`, `--v-slider-fill-color` and -`--v-slider-thumb-color`. - -```html - - -``` - -## Thumb Label - -You can show the current value of the slider when the user is sliding by enabling the thumb label. This can be done by -setting the `show-thumb-label` prop: - -```html - -``` - -## Ticks - -You can render an indicator for every step of the slider. This allows the user to know what kind of steps are available -when sliding the slider. You can enable this with the `show-ticks` prop. - -```html - -``` - -## Prepend / Append slot - -You can add any custom content before and after the slider (inline). This can be used to render things like buttons to -decrease / increase the value, or a label that shows a preview of what the value with a unit is going to be. - -```html - - - - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------------------- | --------------------------------------------------- | ------- | --------- | -| `max` | Maximum allowed value | `100` | `Number` | -| `min` | Minimum allowed value | `0` | `Number` | -| `show-thumb-label` | Show the thumb label on drag of the thumb | `false` | `Boolean` | -| `show-ticks` | Show tick for each step | `false` | `Boolean` | -| `step` | In what step the value can be entered | `1` | `Number` | -| `value` | Current value of slider. Can be used with `v-model` | `0` | `Number` | -| `always-show-value` | Always the current selected value | `false` | `Boolean` | - -#### Events - -| Event | Description | Value | -| -------- | ------------------------------------------- | -------- | -| `change` | Fires only when the user releases the thumb | `number` | -| `input` | Fires continuously | `number` | - -#### CSS Variables - -| Variable | Default | -| ------------------------ | ---------------------- | -| `--v-slider-color` | `var(--border-normal)` | -| `--v-slider-thumb-color` | `var(--primary)` | -| `--v-slider-fill-color` | `var(--primary)` | - -#### Slots - -| Slot | Description | Data | -| ------------- | ------------------------------ | ---- | -| `prepend` | Prepend anything to the slider | | -| `thumb-label` | | | -| `type-text` | | | -| `append` | Append anything to the slider | | diff --git a/docs/reference/app/components/v-switch.md b/docs/reference/app/components/v-switch.md deleted file mode 100644 index 06e20d8a8d..0000000000 --- a/docs/reference/app/components/v-switch.md +++ /dev/null @@ -1,76 +0,0 @@ -# Switch - -Render a switch that either can model a single boolean value or model an array in combination with the `value` prop. - -```html - -``` - -## Colors - -Color changes are done using the css variable `--v-switch-color`. - -```html - - -``` - -## Boolean vs arrays - -Just as with regular checkboxes, you can use `v-model` with both an array and a boolean: - -```html - - - -``` - -Keep in mind to pass the `value` prop with a unique value when using arrays in `v-model`. - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------------- | ------------------------------------------------------ | ------- | ------------------ | -| `value` | If modeling an array, what value the switch represents | `null` | `String` | -| `input-value` | Model the selected state using `v-model` | `false` | `[Boolean, Array]` | -| `disabled` | Disables the switch | `false` | `Boolean` | -| `label` | Displays a label next to the switch | `null` | `String` | - -#### CSS Variables - -| Variable | Default | -| ------------------ | -------------------------- | -| `--v-switch-color` | `var(--foreground-normal)` | - -#### Events - -| Event | Description | Value | -| -------- | ------------------------------------ | ----- | -| `change` | When the state of the switch changes | | - -#### Slots - -| Slot | Description | Data | -| ------- | ----------------------------------------------- | ---- | -| `label` | Alternative way of adding a label to the switch | | diff --git a/docs/reference/app/components/v-tab-item.md b/docs/reference/app/components/v-tab-item.md deleted file mode 100644 index a8e8793a04..0000000000 --- a/docs/reference/app/components/v-tab-item.md +++ /dev/null @@ -1,42 +0,0 @@ -# Tab Item - -Individual tab content. To be used in a `v-tabs-items` context. - -```html - - This is the content for the first tab. - This is the content for the second tab. - -``` - -If you're using a custom value in the `value` prop, make sure the corresponding tab uses the same value to match: - -```html - - Home - Settings - - - - This is the content for home. - Settings content - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------- | --------------------------------------- | ------- | -------- | -| `value` | Custom value to use for selection state | `null` | `String` | - -#### Events - -n/a - -#### Slots - -| Slot | Description | Data | -| --------- | ---------------- | ----------------------------------------- | -| _default_ | Tab item content | `{ active: boolean, toggle: () => void }` | diff --git a/docs/reference/app/components/v-tab.md b/docs/reference/app/components/v-tab.md deleted file mode 100644 index eade5c6561..0000000000 --- a/docs/reference/app/components/v-tab.md +++ /dev/null @@ -1,38 +0,0 @@ -# Tab - -Individual tab. To be used inside a `v-tabs` context. - -```html - - Schema - Options - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ---------- | ------------------------------------------------------ | ------- | --------- | -| `disabled` | Disable the tab | `false` | `Boolean` | -| `value` | A custom value to be used in the selection of `v-tabs` | `null` | `String` | - -#### Events - -n/a - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ------------------------------------------ | -| _default_ | | `{ active: boolean, toggle: () => void; }` | - -#### CSS Variables - -| Variable | Default | -| --------------------------------- | --------------------------- | -| `--v-tab-color` | `var(--foreground-subdued)` | -| `--v-tab-background-color` | `var(--background-page)` | -| `--v-tab-color-active` | `var(--foreground-normal)` | -| `--v-tab-background-color-active` | `var(--background-page)` | diff --git a/docs/reference/app/components/v-table.md b/docs/reference/app/components/v-table.md deleted file mode 100644 index 769a73046d..0000000000 --- a/docs/reference/app/components/v-table.md +++ /dev/null @@ -1,165 +0,0 @@ -# Table - -Used to display data like a list of objects in a table like view. - -```html - -``` - -## Headers - -| Property | Description | Default | -| ---------- | ------------------------------------------------------------ | ------- | -| `text`\* | Text displayed in the column | -- | -| `value`\* | Name of the object property that holds the value of the item | -- | -| `align` | Text alignment of value. One of `left`, `center`, `right` | `left` | -| `sortable` | If the column can be sorted on | `true` | -| `width` | Custom width of the column in px | -- | - -## Custom element / component for header - -You can override the displayed header name by using the dynamic `header.[name]` slot. `[name]` is the `value` property -in the header item for this column sent to `headers`. - -```html - - - -``` - -In this slot, you have access to the `header` through the scoped slot binding. - -## Custom element / component for cell value - -You can override the columns in a row by using the dynamic `item.[name]` slot. `[name]` is the `value` property in the -header item for this column sent to `headers`. - -```html - - - -``` - -In this slot, you have access to the `item` through the scoped slot binding. - -## Resizable rows - -Adding the `show-resize` prop allows the user to resize the columns at will. You can keep your headers updated by using -the `v-model` directive or listening to the `update:headers` event: - -```html - - - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------------------- | ------------------------------------------------------------------------------------------------- | --------------------------- | ------------- | -| `headers`\* | What columns to show in the table. Supports the `v-model` directive | | `HeaderRaw[]` | -| `items`\* | The individual items to render as rows | | `Item[]` | -| `disabled` | Disable edits to items in the form (drag/select) | `false` | `Boolean` | -| `fixed-header` | Make the header fixed | `false` | `Boolean` | -| `inline` | Display the table inline with other text | `false` | `Boolean` | -| `item-key` | Primary key of the item. Used for keys / selections | `'id'` | `String` | -| `loading-text` | What text to show when table is loading with no items | `i18n.global.t('loading')` | `String` | -| `loading` | Show progress indicator | `false` | `Boolean` | -| `manual-sort-key` | What field to use for manual sorting | `null` | `String` | -| `must-sort` | Requires the sort to be on a particular column | `false` | `Boolean` | -| `no-items-text` | What text to show when table doesn't contain any rows | `i18n.global.t('no_items')` | `String` | -| `row-height` | Height of the individual rows in px | `48` | `Number` | -| `selection-use-keys` | What field to use for selection | `false` | `Boolean` | -| `selection` | What items are selected. Can be used with `v-model` as well | `() => []` | `any` | -| `server-sort` | Handle sorting on the parent level. | `false` | `Boolean` | -| `show-manual-sort` | Show manual sort drag handles | `false` | `Boolean` | -| `show-resize` | Show resize handlers | `false` | `Boolean` | -| `show-select` | Show checkboxes | `false` | `Boolean` | -| `sort` | What column / order to sort by. Supports the `v-model` directive. `{ by: string, desc: boolean }` | `null` | `Sort` | - -#### Events - -| Event | Description | Value | -| ---------------- | --------------------------------------------------- | ----------------------------------- | -| `update:sort` | `v-model` event for `sort` prop | `{ by: string, desc: boolean }` | -| `click:row` | When a row has been clicked | `{item: any, event: PointerEvent }` | -| `update:items` | When changes to the items where made | | -| `manual-sort` | When a user manually sorts the items | | -| `update:headers` | `v-model` event for `headers` prop or `HeaderRaw[]` | | -| `item-selected` | Emitted when an item is selected or deselected | `{ item: any, value: boolean }` | -| `select` | Emitted when selected items change | `any[]` | - -#### Slots - -| Slot | Description | Data | -| ------------------------ | ---------------------------- | ---- | -| `header.${header.value}` | A slot for each header | | -| `item.${header.value}` | A slot for each item | | -| `item-append` | Adds to the end of each item | | -| `footer` | Could be used for pagination | | - -#### CSS Variables - -| Variable | Default | -| ----------------------------- | -------------------------- | -| `--v-table-height` | `auto` | -| `--v-table-sticky-offset-top` | `0` | -| `--v-table-color` | `var(--foreground-normal)` | -| `--v-table-background-color` | `var(--background-page)` | diff --git a/docs/reference/app/components/v-tabs-items.md b/docs/reference/app/components/v-tabs-items.md deleted file mode 100644 index 2b23084dfc..0000000000 --- a/docs/reference/app/components/v-tabs-items.md +++ /dev/null @@ -1,32 +0,0 @@ -# Tabs Items - -Tabs Items mirror a tab and display information for a selected tab. If a tab item is not selected, it automatically gets -hidden. - -```html - - Home Section - News Section - Help Section - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ------- | ------------- | ----------- | ---------------------- | -| `value` | v-model value | `undefined` | `(string or number)[]` | - -#### Events - -| Event | Description | Value | -| ------- | --------------- | ------------------------------- | -| `input` | Updates v-model | `readonly (string or number)[]` | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ---- | -| _default_ | | | diff --git a/docs/reference/app/components/v-tabs.md b/docs/reference/app/components/v-tabs.md deleted file mode 100644 index 443739019b..0000000000 --- a/docs/reference/app/components/v-tabs.md +++ /dev/null @@ -1,62 +0,0 @@ -# Tabs - -Tabs work like tabs in the browser and are there to split data into quickly accessible pages. - -```html - - Tab 1 - Tab 2 - Tab 3 - -``` - -## With Tab Items - -To be able to display a page depending on the tab use tab items. - -```html - - Tab 1 - Tab 2 - Tab 3 - - - - -

This is the first page

-
- -

This is the second page

-
- -

This is the third page

-
-
-``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| ---------- | ------------------------------------- | ----------- | ---------------------- | -| `value` | The currently selected tab | `undefined` | `(string or number)[]` | -| `vertical` | Display the tabs in a vertical format | `false` | `Boolean` | - -#### CSS Variables - -| Variable | Default | -| -------------------------- | -------------------------- | -| `--v-tabs-underline-color` | `var(--foreground-normal)` | - -#### Events - -| Event | Description | Value | -| ------- | ------------------------------- | ----- | -| `input` | Used to update the selected tab | | - -#### Slots - -| Slot | Description | Data | -| --------- | ----------- | ---- | -| _default_ | | | diff --git a/docs/reference/app/components/v-text-overflow.md b/docs/reference/app/components/v-text-overflow.md deleted file mode 100644 index 3592bc6d8c..0000000000 --- a/docs/reference/app/components/v-text-overflow.md +++ /dev/null @@ -1,15 +0,0 @@ -# Text Overflow - -Can be used to display text in a single line and hide any overflow. - -```html - -``` - -## Reference - -#### Props - -| Prop | Description | Default | Type | -| -------- | --------------------------------- | ------- | ------------------------------------------ | -| `text`\* | The text that should be displayed | | `[String, Number, Array, Object, Boolean]` | diff --git a/docs/reference/app/components/v-textarea.md b/docs/reference/app/components/v-textarea.md deleted file mode 100644 index 0b60027527..0000000000 --- a/docs/reference/app/components/v-textarea.md +++ /dev/null @@ -1,52 +0,0 @@ -# Textarea - -Renders a textarea in which multiline text can be entered. - -```html - -``` - -## Attributes & Events - -The HTML `