From 1535db76466f9f16de63bc0dd767c8025adeefe2 Mon Sep 17 00:00:00 2001 From: Ben Haynes Date: Tue, 6 Oct 2020 16:19:36 -0400 Subject: [PATCH] Docs updates --- app/src/modules/docs/components/sections.ts | 24 +++--- docs/concepts/app-extensions.md | 2 +- docs/concepts/app-overview.md | 10 +-- .../{technical-support.md => support.md} | 0 docs/guides/collections.md | 4 +- docs/guides/extensions/layouts.md | 2 +- docs/guides/presets.md | 34 +++++++- ...-and-roles.md => roles-and-permissions.md} | 57 +------------ docs/guides/users.md | 80 +++++++++++++++++++ 9 files changed, 137 insertions(+), 76 deletions(-) rename docs/getting-started/{technical-support.md => support.md} (100%) rename docs/guides/{users-and-roles.md => roles-and-permissions.md} (78%) create mode 100644 docs/guides/users.md diff --git a/app/src/modules/docs/components/sections.ts b/app/src/modules/docs/components/sections.ts index aabe62e35a..c6b25b9078 100644 --- a/app/src/modules/docs/components/sections.ts +++ b/app/src/modules/docs/components/sections.ts @@ -24,8 +24,8 @@ const sections: Section[] = [ to: '/docs/getting-started/introduction', }, { - name: 'Technical Support', - to: '/docs/getting-started/technical-support', + name: 'Support & FAQ', + to: '/docs/getting-started/support', }, { name: 'Contributing', @@ -83,10 +83,6 @@ const sections: Section[] = [ to: '/docs/guides', default: 'readme', children: [ - { - name: 'Projects', - to: '/docs/guides/projects', - }, { name: 'Collections', to: '/docs/guides/collections', @@ -96,12 +92,20 @@ const sections: Section[] = [ to: '/docs/guides/fields', }, { - name: 'Users & Roles', - to: '/docs/guides/users-and-roles', + name: 'Presets', + to: '/docs/guides/presets', }, { - name: 'Presets & Bookmarks', - to: '/docs/guides/presets', + name: 'Projects', + to: '/docs/guides/projects', + }, + { + name: 'Roles & Permissions', + to: '/docs/guides/roles-and-permissions', + }, + { + name: 'Users', + to: '/docs/guides/users', }, { name: 'Webhooks', diff --git a/docs/concepts/app-extensions.md b/docs/concepts/app-extensions.md index b810e27bf1..65b8dd9442 100644 --- a/docs/concepts/app-extensions.md +++ b/docs/concepts/app-extensions.md @@ -21,7 +21,7 @@ In addition to these core modules, custom modules offer a _blank canvas_ for cre ## Layouts -Layouts provide different ways for presenting, browsing, visualizing, or even managing sets of data. Most commonly shown on Item Browse pages and contextual modals for item selection. Directus includes several Layout options out-of-the-box, each with different features and configuration options. +Layouts provide different ways for presenting, browsing, visualizing, or even managing sets of data. Most commonly shown on Collection Detail pages and contextual modals for item selection. Directus includes several Layout options out-of-the-box, each with different features and configuration options. ### Table diff --git a/docs/concepts/app-overview.md b/docs/concepts/app-overview.md index 19605ecbe7..7c2b0e0e7a 100644 --- a/docs/concepts/app-overview.md +++ b/docs/concepts/app-overview.md @@ -42,11 +42,11 @@ 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 Browse +### 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. -### Item Browse +### Collection Detail Provides a configurable layout to browse or visualize items within a given collection. Like other browse pages, there are many available features, including: @@ -73,7 +73,7 @@ Most layouts on the browse page support navigating to individual item detail pag ## User Directory -A module includes a comprehensive listing of all system users within your project. This page has the same features and configuration as [Item Browse](#). +A module includes a comprehensive listing of all system users within your project. This page has the same features and configuration as [Collection Detail](#). ### User Detail @@ -108,7 +108,7 @@ While the fields included out-of-the-box are locked from schema changes, you can ## File Library -This module aggregates all files within the project into one consolidated library. This page has the same features and configuration as [Item Browse](#). +This module aggregates all files within the project into one consolidated library. This page has the same features and configuration as [Collection Detail](#). ### File Detail @@ -151,7 +151,7 @@ Our docs are written in markdown (with some additional VuePress styling like thi ## Actvity History -This module provides a collective timeline of all actions taken within the project. This is a great way to audit user activity or enforce accountability. This is the only system module that is not in the module bar by default — instead being located within the notifications tray of the page sidebar. This page has the same features and configuration as [Item Browse](#). +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](#). ### Activity Detail diff --git a/docs/getting-started/technical-support.md b/docs/getting-started/support.md similarity index 100% rename from docs/getting-started/technical-support.md rename to docs/getting-started/support.md diff --git a/docs/guides/collections.md b/docs/guides/collections.md index a81b666996..5e8dc304cb 100644 --- a/docs/guides/collections.md +++ b/docs/guides/collections.md @@ -45,7 +45,7 @@ Keep in mind that Directus Collections are just a database tables. Therefore you * **Note** — A helpful note that explains the collection's purpose * **Display Template** — A [Field Template](#) used to create dynamic titles for the collection's items * **Hidden** — Toggles if the collection should be globally hidden. Keep in mind that Admin roles can always see all collections. -* **Singleton** — Is this collection will only contain a single item (eg: an "About Us" form). When enabled, the [Item Browse](#) will be bypassed, and users are taken directly to the [Item Detail](#) page. +* **Singleton** — Is this collection will only contain a single item (eg: an "About Us" form). When enabled, the [Collection Detail](#) will be bypassed, and users are taken directly to the [Item Detail](#) page. * **Translation** — Allows translating the collection name into different languages. These [Schema Translations](#) are important for multilingual projects. You can also "translate" a collection name into the default language — helpful for renaming technical table names. ### Archive @@ -67,7 +67,7 @@ When creating a new Collection, you have the option of creating an optional "Sta ### Sort -The sort feature enables manual drag-and-drop item reordering within the Directus App. This is typically shown on the [Item Browse](#) page/modal, and can also be used for sorting items within a [Junction Table](#). +The sort feature enables manual drag-and-drop item reordering within the Directus App. This is typically shown on the [Collection Detail](#) page/modal, and can also be used for sorting items within a [Junction Table](#). ::: Sort Field 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. diff --git a/docs/guides/extensions/layouts.md b/docs/guides/extensions/layouts.md index cfdd5fbc03..ef56b6f999 100644 --- a/docs/guides/extensions/layouts.md +++ b/docs/guides/extensions/layouts.md @@ -1,6 +1,6 @@ # Create a Custom Layout -> Custom layouts allow you to create new ways of browsing or viewing data on the Item Browse page. +> Custom layouts allow you to create new ways of browsing or viewing data on the Collection Detail page. ## 1. Setup the Boilerplate diff --git a/docs/guides/presets.md b/docs/guides/presets.md index a26352cbf0..652c2dad82 100644 --- a/docs/guides/presets.md +++ b/docs/guides/presets.md @@ -1,3 +1,33 @@ -# Managing Presets & Bookmarks +# Presets & Bookmarks -> TK +> Presets define the default state of Collection Detail + +## Creating a Preset + +1. Navigate to **Settings > Presets & Bookmarks** +2. Click the **Create Preset** action button in the header +3. Complete the **other preset form fields** outlined below + +* **Collection** — The collection of this preset; supports any project collection, Directus Files, or Directus Users +* **Scope** — The users that will have access to this preset, either Global, a specific Role, or an individual User +* **Layout** — The collection detail's layout this preset applies to +* **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. + +Each preset saves the following information for the collection/preset: + +* **Search Query** — Any full-text search entered into the search bar +* **Filters** +* **Layout Query** +* **Layout Options** + +## Deleting a Preset + +1. Navigate to **Settings > Presets & Bookmarks > [Preset]** +2. Click the red **Delete Preset** 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. +::: diff --git a/docs/guides/users-and-roles.md b/docs/guides/roles-and-permissions.md similarity index 78% rename from docs/guides/users-and-roles.md rename to docs/guides/roles-and-permissions.md index 09bf01d454..625e0fd603 100644 --- a/docs/guides/users-and-roles.md +++ b/docs/guides/roles-and-permissions.md @@ -1,6 +1,6 @@ -# Managing Users, Roles & Permissions +# Roles & Permissions -> New Directus projects automatically include an "Admin" role, and a single user configured during installation. You can then extend and customize these as much as is needed. +> During installation, Directus automatically includes an initial "Admin" role with complete project access. After that, you are free to extend and customize these as much as is needed. ## Creating a Role @@ -153,56 +153,3 @@ You must maintain at least one role/user with Admin Access so that you can still :::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. ::: - -## 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** (see [Configuring a User](#)) - -## Inviting a User - -1. Navigate to **Settings > Roles & Permissions > [Role Name]** -2. Scroll to the **Users in Role** field -3. Click the **Invite Users** button -4. Enter **one or more email addresses**, separated by commas, in the modal -5. Click **Invite** - -## Configuring a User - -1. Navigate to the **User Library** -2. Click on the user you wish to manage -3. Complete any of the [User Fields](/concepts/app-overview.md#user-detail) - -::: User Preferences -This section of the User Detail is only visible/editable by the current user, and admins. -::: - -### Status - -* **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](#) using a static string. When NULL, the token is disabled. When enabled, ensure that a secure string is used. - -:::warning Admin Only -Only admins can adjust this field's value. -::: diff --git a/docs/guides/users.md b/docs/guides/users.md new file mode 100644 index 0000000000..f0d2f63d35 --- /dev/null +++ b/docs/guides/users.md @@ -0,0 +1,80 @@ +# Users + +> You are prompted to enter the details of your first admin user during the installation process. After that, you are free to create as many users as you'd like. There is no limit to the number of users in a project. + +## 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** (see [Configuring a User](#)) + +## Inviting a User + +1. Navigate to **Settings > Roles & Permissions > [Role Name]** +2. Scroll to the **Users in Role** field +3. Click the **Invite Users** button +4. Enter **one or more email addresses**, separated by commas, in the modal +5. Click **Invite** + +At this point the invited user(s) will recieve 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 any of the [User Fields](/concepts/app-overview.md#user-detail) + +::: User Preferences +This section of the User Detail is only visible/editable by the current user, and admins. +::: + +### Status + +* **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](#) using a static string. When NULL, the token is disabled. When enabled, ensure that a secure string is used. + +:::warning Admin Only +Only admins can adjust this field's value. +::: + +## 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. +:::