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

Update docs once more

Browse Source
This commit is contained in:
rijkvanzanten
2020-12-01 18:01:00 -05:00
parent 2aed82773a
commit f8977a885d
55 changed files with 537 additions and 580 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -6,7 +6,7 @@
## Activity
This is a log of all events that have occured within the project. Activity can be accessed in two
This is a log of all events that have occurred within the project. Activity can be accessed in two
ways, via the main [Activity Module](/concepts/app-overview#actvity-history), or within the sidebar
of individual [Item Detail](/concepts/app-overview#item-detail) pages. The following information is
stored for each event's activity item:
@@ -20,12 +20,20 @@ stored for each event's activity item:
- Item
- Comment (when applicable)
::: tip Readonly For proper accountability, activity records are readonly. Administrators should
avoid changing, deleting, or truncating this data. :::
<!-- prettier-ignore-start -->
::: tip Readonly
For proper accountability, activity records are readonly. Administrators should
avoid changing, deleting, or truncating this data.
:::
<!-- prettier-ignore-end -->
::: warning External Events Directus can only track events that pass through the platform's
<!-- prettier-ignore-start -->
::: warning External Events
Directus can only track events that pass through the platform's
middleware. Changes made directly to the database, or by other external means, are not included in
the activity log. :::
the activity log.
:::
<!-- prettier-ignore-end -->
## Versions
@@ -36,15 +44,21 @@ information stored for each version:
- Data — A full snapshot of the item _after_ the event
- Delta — The specific field data changed by this event
::: tip Customizing Version Data Since versions store a full data snapshot and delta, the
<!-- @TODO ::: tip Customizing Version Data
Since versions store a full data snapshot and delta, the
`directus_revisions` collection can quickly grow quite large, increasing database size and
potentially decreasing performance. To remedy this, Directus allows
[configuring version scope](/concepts/app-overview) per collection to set the exact field data
saved. :::
saved.
::: -->
::: tip Creating Detached Versions You can also create a new version for an item without saving the
<!-- prettier-ignore-start -->
::: tip Creating Detached Versions
You can also create a new version for an item without saving the
data to the parent item itself. This allows you to "stage" changes to an item that may already be
live/published. :::
live/published.
:::
<!-- prettier-ignore-end -->
### Relevant Guides

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

@@ -127,9 +127,13 @@ The sidebar's info component also includes the following readonly details:
- **Last Access** — The timestamp of the user's last App or API action
- **Last Page** — The last App page accessed by the user
::: tip Extending Users While the fields included out-of-the-box are locked from schema changes, you
<!-- prettier-ignore-start -->
::: tip Extending Users
While the fields included out-of-the-box are locked from schema changes, you
can extend Directus Users to include additional proprietary fields within
[Settings > Data Model](/concepts/data-model). :::
[Settings > Data Model](/concepts/data-model).
:::
<!-- prettier-ignore-end -->
## File Library
@@ -161,9 +165,13 @@ The sidebar's info component also includes the following readonly details:
- **Folder** — The current parent folder that contains the file
- **Metadata** — Metadata JSON dump of the file's EXIF, IPTC, and ICC information
::: tip Extending Files While the fields included out-of-the-box are locked from schema changes, you
<!-- prettier-ignore-start -->
::: tip Extending Files
While the fields included out-of-the-box are locked from schema changes, you
can extend Directus Files to include additional proprietary fields within
[Settings > Data Model](/concepts/data-model). :::
[Settings > Data Model](/concepts/data-model).
:::
<!-- prettier-ignore-end -->
## Documentation
@@ -179,9 +187,13 @@ dynamically tailored to your custom schema. The docs are organized into four dis
- [Reference](/reference/api/introduction)\*\* — Information Oriented. Look up info and specs
while working.
::: tip Updating the Docs Our docs are written in markdown (with some additional VuePress styling
<!-- prettier-ignore-start -->
::: 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). :::
[GitHub](https://github.com/directus/directus).
:::
<!-- prettier-ignore-end -->
## Activity History

16
docs/concepts/internationalization.md
View File

@@ -15,9 +15,13 @@ Directus uses [database mirroring](#) to dynamically pull in your schema's table
however this only covers one language. Therefore our platform supports schema translations for these
names, allowing you to properly support different languages for your Collection and Field names.
::: tip Overriding Technical Names If your project requires more _technical_ table/column names (eg:
<!-- prettier-ignore-start -->
::: tip Overriding Technical
Names If your project requires more _technical_ table/column names (eg:
`cust` or `f_name`), you can also use schema translations to override those defaults (eg:
`Customers` or `First Name`) in the primary language. :::
`Customers` or `First Name`) in the primary language.
:::
<!-- prettier-ignore-end -->
## Content Translations
@@ -27,6 +31,10 @@ each language, it is more extensible to use our relational translation fields to
content in as many languages as is required. Mixing standard and translated fields also allows
language-agnostic data (such as dates or toggles) to remain within the parent collection.
::: tip Custom Interfaces For more advanced use-cases, such as connecting to a third-party
<!-- prettier-ignore-start -->
::: tip Custom Interfaces
For more advanced use-cases, such as connecting to a third-party
translation service, you can read our extension guide on
[creating a custom interface](/guides/extensions/interfaces). :::
[creating a custom interface](/guides/extensions/interfaces).
:::
<!-- prettier-ignore-end -->

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

@@ -59,12 +59,16 @@ Directus automatically uses a built-in [title formatter](/concepts/app-extension
database table names prettified, and you can use [translations](/concepts/data-model) to completely
rename them if needed.
::: tip Usage Collections can be organized in any way that is appropriate for your project. You can
<!-- prettier-ignore-start -->
::: tip Usage
Collections can be organized in any way that is appropriate for your project. You can
architect them platform-specific (eg: _pages_ of a website), or in a more platform-agnostic way (eg:
raw _customers_ of your business). While there's no right or wrong way to structure your data-model,
we recommend keeping your data as agnostic as possible so it is easier to repurpose in the future.
In short, **learn to see your data as its own asset — not only through the lens of your immediate
project needs**. :::
project needs**.
:::
<!-- prettier-ignore-end -->
### Relevant Guides
@@ -92,17 +96,29 @@ completely rename them if needed.
Each field also mirrors other characteristics from the column, including its `type`, `default`,
`length`, `allow_null`, etc.
::: tip Usage You might have `title`, `body`, `author`, and `date_published` fields within an
`articles` collection. :::
<!-- prettier-ignore-start -->
::: tip Usage
You might have `title`, `body`, `author`, and `date_published` fields within an
`articles` collection.
:::
<!-- prettier-ignore-end -->
::: tip Aliases Not all fields in Directus map directly to an actual database column within their
<!-- prettier-ignore-start -->
::: tip Aliases
Not all fields in Directus map directly to an actual database column within their
table. Some relational fields, like One-to-Many (O2M) and Many-to-Many (M2M), represent data that is
stored in different tables. Other fields are only for presentation and don't save data at all, such
as a divider. These are called "alias" fields. :::
as a divider. These are called "alias" fields.
:::
<!-- prettier-ignore-end -->
::: tip Relational Fields Fields that reference other items (in the same collection or different)
<!-- prettier-ignore-start -->
::: tip Relational Fields
Fields that reference other items (in the same collection or different)
are called relational fields. Linking or connecting data relationally is an immensely powerful
feature of relational databases and SQL queries. :::
feature of relational databases and SQL queries.
:::
<!-- prettier-ignore-end -->
### Relevant Guides

78
docs/concepts/relationships.md
View File

@@ -12,18 +12,23 @@ type, let's first cover a few basics that will help you better visualize each in
### PKs vs FKs
Every [item](#) in a relational database has a unique "key" that identifies it within its
[collection](#). Because it's required, the key is the first [field](#) 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.
Every [item](/concepts/platform-overview#items) in a relational database has a unique "key" that
identifies it within its [collection](/concepts/platform-overview#collections). Because it's
required, the key is the first [field](/concepts/platform-overview#fields) created within a
collection, typically storing an "auto-increment" number, 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).
::: Compound Keys We've ignored compound keys in this explanation to help keep things as simple as
possible. :::
<!-- prettier-ignore-start -->
::: tip Compound Keys
We've ignored compound keys in this explanation to help keep things as simple as
possible.
:::
<!-- prettier-ignore-end -->
### Perspective Matters
@@ -50,9 +55,9 @@ country ("One" Collection)
## 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](#)). So the O2M data model is the same, but adds an alias
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:
```
@@ -67,12 +72,20 @@ cities ("Many" Collection)
- country (stores the FK to a country)
```
::: 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). :::
<!-- prettier-ignore-start -->
::: 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).
:::
<!-- prettier-ignore-end -->
::: Translations The Translations interface allows [creating multilingual content](#) relationally.
It is a standard O2M relatinship, but also includes an additional field on the "many" collection to
hold the language key :::
<!-- prettier-ignore-start -->
::: tip Translations
The Translations interface allows [creating multilingual content](/concepts/internationalization#content-translations) relationally.
It is a standard O2M relationship, but also includes an additional field on the "many" collection to
hold the language key
:::
<!-- prettier-ignore-end -->
## Many-to-Many (M2M)
@@ -101,15 +114,27 @@ recipe_ingredients (Junction Collection)
Notice that the example above also has a `quantity` field on the junction table. You can add any
contextual fields to the junction, and they will also be included in the App's relational edit form.
:::warning M2M == O2M x2 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". :::
<!-- prettier-ignore-start -->
::: warning M2M == O2Mx2
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".
:::
<!-- prettier-ignore-end -->
::: 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](#). :::
<!-- prettier-ignore-start -->
::: 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](#).
:::
<!-- prettier-ignore-end -->
::: Self-Referencing You can also have a M2M relationship that connects items within the _same_
<!-- prettier-ignore-start -->
::: tip
Self-Referencing You can also have a M2M relationship that connects items within the _same_
collection. A common example of this is "Related Articles", where each article might relate to many
other articles. :::
other articles.
:::
<!-- prettier-ignore-end -->
## One-to-One (O2O)
@@ -117,20 +142,21 @@ Directus does not include a one-to-one (O2O) relationship type or interface. How
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](#) or [custom interface](#).
constraining uniqueness via a [custom event hook](/concepts/api-extensions) or
[custom interface](/concepts/app-extensions).
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 (M2X)
## Many-to-Any (M2A)
Sometimes called a "matrix field" or "replicator", the Many-to-Any (M2X) relationship is essentially
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 M2X is a "page layout builder". These typically will have modular components across
An example of a M2A is a "page layout builder". These typically will have modular components across
several different collections (eg: "Heading", "Text Block", "Media Asset", etc), and a _Pages_
collections where you can piece them together. Therefore, the junction table will link a specific
page with specific components, allowing the creation of relational page layouts.

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

@@ -8,26 +8,35 @@
To use the App or API, you'll need a valid Directus User. Each user is assigned to a role that
determines what they have access to see and do. For instance, some users have access to the App,
while others can only connect to the API. Directus ships with a number of profile fields that help
create a full-featured [User Directory](#), and setting fields that allow customizing your
experience.
create a full-featured [User Directory](/concepts/app-overview#user-directory), and setting fields
that allow customizing your experience.
All Directus users are aggregated and shown on the [User Directory](#) page of the App
All Directus users are aggregated and shown on the
[User Directory](/concepts/app-overview#user-directory) page of the App
::: Extending Directus Users While the included fields within Directus Users are required/locked,
<!-- prettier-ignore-start -->
::: tip Extending Directus Users
While the included fields within Directus Users are required/locked,
you can still _extend_ this collection with additional custom fields as needed. You can do this via
the normal [Create a new Field](#) process from within the system collection. :::
the normal [Create a new Field](#) process from within the system collection.
:::
<!-- prettier-ignore-end -->
::: System vs Custom Users If your project requires a users, members, customers, etc., we recommend
<!-- prettier-ignore-start -->
::: tip
System vs Custom Users If your project requires a users, members, customers, etc., we recommend
creating your own collection to manage these instead of trying to repurpose the Directus Users
system. :::
system.
:::
<!-- prettier-ignore-end -->
### Relevant Guides
- [Setting up your User Profile](#)
- [Inviting a User](#)
- [Creating a User](#)
- [Archiving a User](#)
- [Deleting a User](#)
- [Setting up your User Profile](/guides/users#setting-up-your-user-profile)
- [Inviting a User](/guides/users#inviting-a-user)
- [Creating a User](/guides/users#creating-a-user)
- [Archiving a User](/guides/users#archiving-a-user)
- [Deleting a User](/guides/users#deleting-a-user)
## Roles
@@ -45,12 +54,12 @@ users. This role can not be deleted, and has no permissions by default.
Upon installation, Directus automatically creates this initial role to grant access to the first
admin user. It is just a normal role, and like any other it can be updated, renamed or deleted,
however your project must maintain at least one role with [Admin Access](#) at all times.
however your project must maintain at least one role with Admin Access at all times.
### Relevant Guides
- [Creating a Role](#)
- [Deleting a Role](#)
- [Creating a Role](/guides/roles-and-permissions#creating-a-role)
- [Deleting a Role](/guides/roles-and-permissions#deleting-a-role)
## Permissions
@@ -58,4 +67,4 @@ Directus gives you granular, filter-based permissions for managing access-contro
### Relevant Guides
- [Managing Permissions](#)
- [Managing Permissions](/guides/roles-and-permissions)

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

@@ -7,15 +7,15 @@
## Financial Support
Talented full-time and part-time staff, infrastructure, and third-party services are just some of
our organization's expenses, and revenue from our Cloud services and donations from sponsors dosen't
our organization's expenses, and revenue from our Cloud services and donations from sponsors doesn't
fully cover those costs. Below are a few ways to help us keep the lights on and move towards
self-sufficiency.
### GitHub Sponsors
Monthly donations via [GitHub Sponsors](#) are the most reliable form of financial support, and
donations made directly to our core developers are currently **doubled** by GitHub's matching
program!
Monthly donations via [GitHub Sponsors](https://github.com/sponsors/directus) are the most reliable
form of financial support, and donations made directly to our core developers are currently
**doubled** by GitHub's matching program!
- [rijkvanzanten](https://github.com/rijkvanzanten) — Technical Lead
- [WoLfulus](https://github.com/WoLfulus) — DevOps
@@ -23,14 +23,16 @@ program!
### Sponsored Work
[Commissioned Features](#) and [Expedited Fixes](#) are great ways to financially support the
development of Directus, and improve the codebase for the community.
[Commissioned Features](/getting-started/support#commissioned-features) and
[Expedited Fixes](/getting-started/support-expedited-features) are great ways to financially support
the development of Directus, and improve the codebase for the community.
### Merch
Our merchandise is a great way to support Directus — you get some swag, and we get some financial
support and advertising. Simply make an appropriate financial donation through [GitHub Sponsors](#),
message us with sizing/shipping details, and we'll get it shipped!
support and advertising. Simply make an appropriate financial donation through
[GitHub Sponsors](https://github.com/sponsors/directus), message us with sizing/shipping details,
and we'll get it shipped!
## Other Contributions
@@ -40,17 +42,19 @@ Below are several ways anyone can help improve our ecosystem.
Squashing bugs, optimizing the codebase, increasing test coverage, and adding new features, are all
extremely valuable. Not technical? We have plenty of documentation that can always use some extra
attention. Learn more in our [Contributors Guide](#).
attention. Learn more in our [Contributors Guide](/getting-started/contributing).
### Translations
Every translation enables users in new languages to use our international platform. Our
[Crowdin integration](#) makes polishing existing translations or creating new ones a breeze.
[Crowdin integration](https://locales.directus.io) makes polishing existing translations or creating
new ones a breeze.
### Bug Reporting
If you encounter an issue within Directus, no matter how small, we would love to hear about it.
Proper bug reporing helps our team assess the platform's stability. [Report a bug](#)
Proper bug reporting helps our team assess the platform's stability.
[Report a bug](https://github.com/directus/directus/issues/new)
### Brand Advocacy
@@ -58,10 +62,11 @@ You can create _perfect_ software, but if no one knows about it, it's all for na
advertising are expensive, but you can help us avoid these costs with the following quick options:
- **GitHub Stars** — The primary metric by which we measure our success. It only takes five
seconds to head to [directus/directus](#) and click the star — enough in a short period of time
and Directus gets featured on GitHub's trending page!
seconds to head to [directus/directus](https://github.com/directus/directus) and click the star
— enough in a short period of time and Directus gets featured on GitHub's trending page!
- **Social Posts** — A quick post mentioning [@directus](https://twitter.com/directus) goes a long
way, and we re-tweet the team's favorite shout-outs to our 30K+ followers.
way, and we re-tweet the team's favorite shout-outs to our 35K+ followers.
- **Testimonials** — _One sentence._ Even that was a sentence, and it was only two words! If
you're a fan of Directus, we'd love to hear why with a short endorsement. Shoot us an
[email](#), [Tweet](#), or [Discord](#) message with your name, title, and company.
[email](mailto:info@directus.io), [Tweet](https://twitter.com/directus), or
[Discord](https://directus.chat) message with your name, title, and company.

10
docs/getting-started/contributing.md
View File

@@ -9,14 +9,16 @@
Our Node.js repository is located at `directus/directus` and houses the Admin App (vue.js 3),
Node.js API, project documentation (markdown), and API Specification (OpenAPI). Directus follows a
monorepo design similar to React or Babel — to learn more about our monorepo's design and structure,
see our [Codebase Overview](#) below.
see our [Codebase Overview](#codebase-overview) below.
To contribute to the project, please follow the instructions located within our GitHub repoitory's
[contributing.md file](#).
[contributing.md file](https://github.com/directus/directus/blob/main/contributing.md).
::: tip PHP API Port While the Node.js version of Directus defines the official specification and is
<!-- ::: tip PHP API Port
While the Node.js version of Directus defines the official specification and is
our team's primary focus, we also support a community-lead PHP API port in Laravel. This secondary
codebase is located in a separate git repository at [`directus/php`](#). :::
codebase is located in a separate git repository at [`directus/php`](#).
::: -->
## Feature Requests

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

@@ -4,24 +4,24 @@ Directus can be installed in many different ways, on several different stacks. C
recommended method, but there are many ways to get started with our platform depending on your
needs.
- [Command Line Interface (CLI)](/guides/installation/cli.md)
- [Docker](/guides/installation/docker.md)
- [Manually](/guides/installation/manual.md)
- [Command Line Interface (CLI)](/guides/installation/cli)
- [Docker](/guides/installation/docker)
- [Manually](/guides/installation/manual)
::: tip Development Environment Developers looking to work on the project's source code should
follow our [Contributing Guide](/getting-started/contributing). :::
## Deployment Guides
- [Amazon AWS](#)
- [DigitalOcean Droplet](#)
- [DigitalOcean One-Click](/guides/installation/digitalocean-one-click.md)
- [Google App Engine](#)
- [Heroku](/guides/installation/heroku.md)
- [Microsoft Azure](#)
- [Amazon AWS](/guides/installation/aws)
- [DigitalOcean Droplet](/guides/installation/digitalocean-droplet)
- [DigitalOcean One-Click](/guides/installation/digitalocean-one-click)
- [DigitalOcean App Platform](/guides/installation/digitalocean-app-platform)
- [Google App Engine](/guides/installation/google-app-engine)
- [Heroku](/guides/installation/heroku)
- [Microsoft Azure](/guides/installation/microsoft-azure)
## Optional Setup Guides
- [Caddy](#)
- [Nginx](#)
- [HAProxy](#)
- [Caddy](/guides/setup/caddy)
- [Nginx](/guides/setup/nginx)

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

@@ -11,10 +11,13 @@ users to view and manage the content/data stored within pure SQL databases. It c
headless CMS for managing project content, a database client for modeling and viewing raw data, or
as a standalone customizable WebApp.
::: details What's in a name? Directus
([duh REKT iss](http://audio.pronouncekiwi.com/Salli/Directus)) is latin for: _laid straight,
<!-- prettier-ignore-start -->
::: details What's in a name?
Directus ([duh REKT iss](http://audio.pronouncekiwi.com/Salli/Directus)) is latin for: _laid straight,
arranged in lines_. The broadest goal of Directus is to present data in a simple, orderly, and
intuitive way. :::
intuitive way.
:::
<!-- prettier-ignore-end -->
## What makes it unique?
@@ -48,7 +51,7 @@ guided by the following core principles:
### Open-Source Engine
Completely free and open-source on the GPLv3 license, Directus is publically available within our
Completely free and open-source on the GPLv3 license, Directus is publicly available within our
[npm package](https://www.npmjs.com/package/directus) and main
[GitHub repository](https://github.com/directus/directus). It includes our dynamic API engine
(node.js), the intuitive Admin App (vue.js 3), this documentation (markdown), and all dependencies.
@@ -70,7 +73,7 @@ They are written in publicly managed markdown files so the community can help ke
up-to-date!
- Getting Started: Novice Oriented. For a platform intro and installation.
- Concepts: Learning Oriented. For understanding the platfom.
- Concepts: Learning Oriented. For understanding the platform.
- Guides: Problem Oriented. Follow along with steps while working.
- Reference: Information Oriented. Look up info and specs while working.

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

@@ -32,10 +32,12 @@ custom/proprietary development will be built bespoke within our robust extension
### Expedited Fixes
We triage all reported bugs based on priority and how long the fix is estimated to take. If you need
a specific issue resolved sooner, [reach out to us](#) for a quote.
a specific issue resolved sooner, [reach out to us](https://directus.io/contact/) for a quote.
## Frequently Asked Questions
<!--
@TODO
### Does Directus handle deploying or migrating projects?
Directus includes [export](#) and [backup](#) tools to assist in deploying data changes between
@@ -43,7 +45,7 @@ environments (eg: from _development_ to _production_), however there is no forma
workflow.
Additionally, since Directus stores all of your data in pure SQL, you can use almost any preexisting
workflow or toolkit for this process.
workflow or toolkit for this process. -->
### Does Directus support Mongo/NoSQL?
@@ -63,16 +65,18 @@ quite stable, however new issues still arise, some of which may be triaged with
prioritization.
If you require more expeditious updates, you can contact us regarding
[sponsoring expedited fixes](#) or [commissioning new features](#). You can also
[submit a pull request](#) — after all, it is open-source!
[sponsoring expedited fixes](#expedited-fixes) or
[commissioning new features](#commisioned-features). You can also
[submit a pull request](https://github.com/directus/directus/pulls) — after all, it is open-source!
### Can you give an ETA for this feature/fix?
If it is [sponsored work](#), then yes, delivery dates are part of our statement of work agreements.
If it is sponsored work, then yes, delivery dates are part of our statement of work agreements.
Otherwise, most likely not. This is open-source software, work is prioritized internally, and all
timelines are subject to change.
### But this is an emergency, my very important project requires it now!
We understand, and are here to help. If you need something prioritized, you can reach out to us to
discuss [premium support](#), [sponsoring expedited fixes](#) or [commissioning new features](#).
discuss [premium support](#premium-support), [sponsoring expedited fixes](#expedited-features) or
[commissioning new features](#commissioned-features).

32
docs/guides/collections.md
View File

@@ -70,12 +70,20 @@ easy recovery.
- **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. :::
<!-- prettier-ignore-start -->
::: 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.
:::
<!-- prettier-ignore-end -->
::: Status Field When creating a new Collection, you have the option of creating an optional
<!-- prettier-ignore-start -->
::: tip Status Field
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. :::
automatically be configured for you.
:::
<!-- prettier-ignore-end -->
### Sort
@@ -83,9 +91,13 @@ The sort feature enables manual drag-and-drop item reordering within the Directu
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"
<!-- prettier-ignore-start -->
::: tip 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. :::
configured for you.
:::
<!-- prettier-ignore-end -->
## Deleting a Collection
@@ -93,5 +105,9 @@ configured for you. :::
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. :::
<!-- prettier-ignore-start -->
::: danger Irreversible Change
This action is permanent and can not be undone. Please proceed with
caution.
:::
<!-- prettier-ignore-end -->

8
docs/guides/extensions/interfaces.md
View File

@@ -37,9 +37,11 @@ export default {
- `component` — A reference to your Vue component.
- `types` — A CSV of supported [types](#).
::: See
[the TypeScript definition](https://github.com/directus/directus/blob/20355fee5eba514dd75565f60269311187010c66/app/src/interfaces/types.ts#L5-L18)
for more info on what can go into this object. :::
<!-- prettier-ignore-start -->
::: tip
See [the TypeScript definition](https://github.com/directus/directus/blob/20355fee5eba514dd75565f60269311187010c66/app/src/interfaces/types.ts#L5-L18) for more info on what can go into this object.
:::
<!-- prettier-ignore-end -->
### src/interface.vue

8
docs/guides/extensions/layouts.md
View File

@@ -31,9 +31,13 @@ export default {
- `name` — The human-readable name for this layout.
- `component` — A reference to your Vue component.
::: See
<!-- prettier-ignore-start -->
::: tip
See
[the TypeScript definition](https://github.com/directus/directus/blob/20355fee5eba514dd75565f60269311187010c66/app/src/layouts/types.ts#L4-L9)
for more info on what can go into this object. :::
for more info on what can go into this object.
:::
<!-- prettier-ignore-end -->
### src/layout.vue

9
docs/guides/extensions/modules.md
View File

@@ -37,9 +37,12 @@ export default {
- `icon` — An icon name from the material icon set, or the extended list of Directus custom icons.
- `routes` — Details the routes in your module per the Vue router.
::: See
[the TypeScript definition](https://github.com/directus/directus/blob/20355fee5eba514dd75565f60269311187010c66/app/src/modules/types.ts#L6-L17)
for more info on what can go into this object. :::
<!-- prettier-ignore-start -->
::: tip
See [the TypeScript definition](https://github.com/directus/directus/blob/20355fee5eba514dd75565f60269311187010c66/app/src/modules/types.ts#L6-L17)
for more info on what can go into this object.
:::
<!-- prettier-ignore-end -->
### src/module.vue

46
docs/guides/fields.md
View File

@@ -1,8 +1,9 @@
# Fields
> You can manage your fields within the Data Model section of the App's Settings, via the
> [API Fields Endpoint](#), or directly within the database. If you're unfamiliar with Directus
> Fields, please start by reading our [Understanding Fields](#) docs.
> [API Fields Endpoint](/reference/api/fields), or directly within the database. If you're
> unfamiliar with Directus Fields, please start by reading our
> [Understanding Fields](/concepts/data-model) docs.
## Creating a Field
@@ -10,18 +11,22 @@
2. Under Fields & Layout, click the **Create Field** button
3. **Choose the field type**, and follow its specific setup guide...
- [Standard Field](#)
- [Presentation Field](#)
- [Many-to-One Field](#)
- [One-to-Many Field](#)
- [Many-to-Many Field](#)
- [Many-to-Any Field](#)
- [Translated Fields](#)
- [Standard Field](/guides/field-types/standard-field)
- [Presentation Field](/guides/field-types/presentation-field)
- [Many-to-One Field](/guides/field-types/many-to-one-field)
- [One-to-Many Field](/guides/field-types/one-to-many-field)
- [Many-to-Many Field](/guides/field-types/many-to-many-field)
- [Many-to-Any Field](/guides/field-types/many-to-any-field)
- [Translated Fields](/guides/field-types/translated-fields)
::: tip Database Fields Keep in mind that Directus Fields are just a database columns. Therefore you
<!-- prettier-ignore-start -->
::: tip Database Fields
Keep in mind that Directus Fields are just a database columns. 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. :::
default values.
:::
<!-- prettier-ignore-end -->
## Duplicating a Field
@@ -29,8 +34,12 @@ default values. :::
2. Click the **More Options** icon for the field you want to delete
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. :::
<!-- prettier-ignore-start -->
::: warning Relational and Primary Key Fields
It is not currently possible to duplicate relational
fields or a collection's primary key.
:::
<!-- prettier-ignore-end -->
## Adjusting Field Layout
@@ -44,7 +53,8 @@ The layout of the collection's form is determined by the following field options
- **Field Sort** — The order of fields within the form
- **Field Group** — If the field is a "group" type
1. Create any desired groupings by **[Creating a Field Group](#)**
<!-- @TODO 1. Create any desired groupings by **[Creating a Field Group](/guides/fields)** -->
2. Click the **More Options** icon for any fields/groups 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
@@ -56,5 +66,9 @@ The layout of the collection's form is determined by the following field options
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. :::
<!-- prettier-ignore-start -->
::: danger Irreversible Change
This action is permanent and can not be undone. Please proceed with
caution.
:::
<!-- prettier-ignore-end -->

22
docs/guides/files.md
View File

@@ -19,10 +19,14 @@ example.com/assets/1ac73658-8b62-4dea-b6da-529fbc9d01a4
![Original File](../assets/original.jpg) _Original File Used Below — 602KB and 1800x1200_
::: warning Direct File Access While you may _technically_ be able to access your original files
<!-- prettier-ignore-start -->
::: warning Direct File Access
While you may _technically_ be able to access your original files
within their actual filesystem directory (eg: `/uploads/<filename_disk>` for the default local
storage configuration), it is recommended that you always use the Directus API. This is the only way
that you can take advantage of file permissions and other built-in features. :::
that you can take advantage of file permissions and other built-in features.
:::
<!-- prettier-ignore-end -->
## Creating Thumbnail Presets
@@ -33,13 +37,17 @@ that you can take advantage of file permissions and other built-in features. :::
5. Enter the **Fit**, **Width**, **Height**, and **Quality** for the preset
6. Click the **Save** action button in the header
::: tip Storage Asset Transform The **Storage Asset Transform** can be used in conjunction with the
<!-- prettier-ignore-start -->
::: tip Storage Asset Transform
The **Storage Asset Transform** can be used in conjunction with the
presets to force an allow-list or completely disable the thumbnailing system. The options for this
are:
- **All** — Any valid thumbnail request will be returned
- **None** — No thumbnails will be returned, not even presets
- **Presets Only** — Only valid Storage Asset Presets will be returned :::
- **Presets Only** — Only valid Storage Asset Presets will be returned
:::
<!-- prettier-ignore-end -->
## Requesting a Thumbnail
@@ -88,7 +96,11 @@ dimensions and adding "letterboxing" as needed.
| ----------------------------------------------------------- | --------------------------------------------------------------- |
| ![Cover](../assets/200-200-cover-75.jpg)<br>_8KB • 200x200_ | ![Contain](../assets/200-200-contain-75.jpg)<br>_6KB • 200x133_ |
::: Aspect Ratio Images are never stretched or distorted even when changing the aspect ratio. :::
<!-- prettier-ignore-start -->
::: Aspect Ratio
Images are never stretched or distorted even when changing the aspect ratio.
:::
<!-- prettier-ignore-end -->
### Quality vs Filesize

3
docs/guides/installation/aws.md Normal file
View File

@@ -0,0 +1,3 @@
# AWS
@TODO

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

@@ -21,8 +21,11 @@ vendor's official support/LTS.
| OracleDB | TBD |
| MariaDB | 10.1+ |
::: Variants In addition to the databases above, other variants are also supported, including **AWS
Aurora** (MySQL), and **AWS Redshift** (PostgreSQL). :::
<!-- prettier-ignore-start -->
::: tip
Variants In addition to the databases above, other variants are also supported, including **AWS Aurora** (MySQL), and **AWS Redshift** (PostgreSQL).
:::
<!-- prettier-ignore-end -->
## 2. Create a Project
@@ -32,8 +35,12 @@ Create a new Directus project by running the following npm command.
npx create-directus-project my-project
```
:::warning Except for SQLite, the database must already be running before creating your Directus
project. :::
<!-- prettier-ignore-start -->
::: warning
Except for SQLite, the database must already be running before creating your Directus
project.
:::
<!-- prettier-ignore-end -->
## 3. Start your Project

1
docs/guides/installation/digitalocean-app-platform.md Normal file
View File

@@ -0,0 +1 @@
# DigitalOcean App Platform

3
docs/guides/installation/digitalocean-droplet.md Normal file
View File

@@ -0,0 +1,3 @@
# DigitalOcean Droplet
@TODO

3
docs/guides/installation/google-app-engine.md Normal file
View File

@@ -0,0 +1,3 @@
# Google App Engine
@TODO

3
docs/guides/installation/microsoft-azure.md Normal file
View File

@@ -0,0 +1,3 @@
# Microsoft Azure
@TODO

2
docs/guides/items.md
View File

@@ -1,5 +1,7 @@
# Items
@TODO
Browse:
## Creating Items

38
docs/guides/presets.md
View File

@@ -1,8 +1,8 @@
# Collection Presets
> Presets store the exact state of a [collection detail](#) page. These can be used to set layout
> defaults for a user, or to define bookmarks that can be used to recall windows into specific
> datasets.
> Presets store the exact state of a [collection detail](/concepts/app-overview) page. These can be
> used to set layout defaults for a user, or to define bookmarks that can be used to recall windows
> into specific datasets.
## Creating a Preset
@@ -25,16 +25,28 @@ Each preset saves all of the information needed to recreate a view of the collec
including: the full-text search query, any advanced filters added, sort field, sort direction, and
all other specific layout options.
::: Defaults vs Bookmarks It's important to be aware of the difference between a collection's
<!-- prettier-ignore-start -->
::: Defaults vs Bookmarks
It's important to be aware of the difference between a collection's
_defaults_ and its _bookmarks_, both of which are configured by presets. A _default_ is how a user
will initially view the collection detail without any further customization, while a _bookmark_ is a
named dataset that can be recalled at any point via the [collection navigation](#). :::
named dataset that can be recalled at any point via the [collection navigation](/concepts/users-roles-and-permissions).
:::
<!-- prettier-ignore-end -->
::: System Defaults You can also adjust the defaults and bookmarks for the Directus Activity,
Directus Files, and Directus Users collections. :::
<!-- prettier-ignore-start -->
::: System Defaults
You can also adjust the defaults and bookmarks for the Directus Activity,
Directus Files, and Directus Users collections.
:::
<!-- prettier-ignore-end -->
::: Order of Defaults Multiple defaults can be configured for a user, either for different layouts
of even the same layout. In this case, the preset priority is: User, then Role, then Global. :::
<!-- prettier-ignore-start -->
::: Order of Defaults
Multiple defaults can be configured for a user, either for different layouts
of even the same layout. In this case, the preset priority is: User, then Role, then Global.
:::
<!-- prettier-ignore-end -->
## Deleting a Preset
@@ -42,5 +54,9 @@ of even the same layout. In this case, the preset priority is: User, then Role,
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. :::
<!-- prettier-ignore-start -->
:::danger Irreversible Change
This action is permanent and can not be undone. Please proceed with
caution.
:::
<!-- prettier-ignore-end -->

23
docs/guides/projects.md
View File

@@ -1,7 +1,7 @@
# Projects
> Every installation of Directus creates a single project. If you're unfamiliar with Directus
> Projects, please start by reading our [Platform Overview](#).
> Projects, please start by reading our [Platform Overview](/concepts/platform-overview).
## Creating a Project
@@ -11,27 +11,18 @@ To install Directus, choose one of the following methods.
- [Docker](/guides/installation/docker.md)
- [Manually](/guides/installation/manual.md)
### Deployment Guides
- [Amazon AWS](#)
- [DigitalOcean Droplet](#)
- [DigitalOcean One-Click](/guides/installation/digitalocean-one-click.md)
- [Google App Engine](#)
- [Heroku](/guides/installation/heroku.md)
- [Microsoft Azure](#)
## 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](#)
- [Environment Variables](/reference/environment-variables)
## Upgrading a Project
1. Backup your project
2. Run `npm update`
<!-- 3. Run `directus migrate:latest` to update the DB ——— @TODO finalize when CLI is finalized -->
3. Run `directus database migrate:latest` to update the DB
## Backing-up a Project
@@ -47,6 +38,10 @@ accepts a number of environment variables, each is explained in the following re
4. **Delete the project's root directory** from the server
5. **Delete all Directus system tables** (`directus_*`) from the database
::: Pure SQL After completing this process, you will be left with a pure SQL database, with no trace
<!-- prettier-ignore-start -->
::: 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. :::
directly (eg: SQL queries) should continue working normally.
:::
<!-- prettier-ignore-end -->

103
docs/guides/roles-and-permissions.md
View File

@@ -13,8 +13,7 @@
## Configuring a Role
- **Permissions** — Defines the role's access permissions, see [Configuring Role Permissions](#)
and [Configuring System Permissions](#)
- **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
@@ -24,15 +23,13 @@
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, see
[Customizing the Module Navigation](#)
- **Collection Navigation** — Overrides the collection module's navigation, see
[Customizing the Collection Navigation](#)
- **Module Navigation** — Overrides the visible modules
- **Collection Navigation** — Overrides the collection module's navigation
### Customizing the Module Navigation
The options in the [Module Bar](#) can be overridden with custom options per role. When this setting
is empty, the default modules are used.
The options in the [Module Bar](/concepts/app-overview) 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
@@ -43,7 +40,7 @@ is empty, the default modules are used.
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.
Module Navigation field using the Raw Value field label option.
```json
[
@@ -78,9 +75,9 @@ or icon. For example, you can use `/collections` to override the Collections mod
### Customizing the Collection Navigation
The collections in the [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.
The collections in the [Navigation Bar](/concepts/app-overview) 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
@@ -101,11 +98,19 @@ new role, permissions are disabled for all project collections by default — al
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. :::
<!-- prettier-ignore-start -->
::: warning Saves Automatically
Every change made to the permissions of a role is saved automatically
and instantly.
:::
<!-- prettier-ignore-end -->
:::warning Admin Roles If a role is set to **Admin Access** then it is granted complete access to
the platoform, and therefore the permission configuration field is disabled. :::
<!-- prettier-ignore-start -->
::: 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.
:::
<!-- prettier-ignore-end -->
1. Navigate to **Settings > Roles & Permissions > [Role Name]**
2. Scroll to the **Permissions** section
@@ -120,43 +125,45 @@ appropriate guide below based on the _action_ of the permission.
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, as defined by the
[Filter Rules](#) entered.
7. **Field Presets** control the field defaults when creating an item, as defined by the
[Item Object](#) entered.
6. **Field Validation** define the rules for field values on create
7. **Field Presets** control the field defaults when creating an item
#### Read (Custom)
5. **Item Permissions** control which items can be read, as defined by the [Filter Rules](#)
entered.
5. **Item Permissions** control which items can be read, as defined by the
[Filter Rules](/reference/filter-rules) entered.
6. **Field Permissions** control which fields can be read. Fields are individually toggled.
#### Update (Custom)
5. **Item Permissions** control which items can be updated, as defined by the [Filter Rules](#)
entered.
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](#) entered.
8. **Field Presets** control the field defaults when updating an item, as defined by the
[Item Object](#) entered.
[Filter Rules](/reference/filter-rules) entered.
8. **Field Presets** control the field defaults when updating an item
#### Delete (Custom)
5. **Item Permissions** control which items can be deleted, as defined by the [Filter Rules](#)
entered.
5. **Item Permissions** control which items can be deleted, as defined by the
[Filter Rules](/reference/filter-rules)) entered.
## Configuring System Permissions
In addition to setting permissions for your project's collections, you can also tailor the
permissions for system collections. It is important to note that when [App Access](#) is enabled for
a role, Directus will automatically add permission for the neccesary system collections. To edit
system permissions, simply click the "System Collections" toggle, and then edit permissions using
the same steps as with project collections.
permissions for system collections. It is important to note that when
[App Access](/concepts/users-roles-and-permissions) is enabled for a role, Directus will
automatically add permission for the necessary system collections. To edit system permissions,
simply click the "System Collections" toggle, and then edit permissions using the same steps as with
project collections.
::: Resetting System Permissions To reset the role's system permissions for proper App access,
<!-- prettier-ignore-start -->
::: 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. :::
listing.
:::
<!-- prettier-ignore-end -->
## Deleting a Role
@@ -164,12 +171,24 @@ listing. :::
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](#)
permissions. They can then be reassigned to a new role by an admin. :::
<!-- prettier-ignore-start -->
::: 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](/concepts/users-roles-and-permissions)
permissions. They can then be reassigned to a new role by an admin.
:::
<!-- prettier-ignore-end -->
:::warning Last Admin You must maintain at least one role/user with Admin Access so that you can
still properly manage the project. :::
<!-- prettier-ignore-start -->
:::warning Last Admin
You must maintain at least one role/user with Admin Access so that you can
still properly manage the project.
:::
<!-- prettier-ignore-end -->
:::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. :::
<!-- prettier-ignore-start -->
:::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.
:::
<!-- prettier-ignore-end -->

3
docs/guides/setup/caddy.md Normal file
View File

@@ -0,0 +1,3 @@
# Caddy Setup Guide
@TODO

3
docs/guides/setup/nginx.md Normal file
View File

@@ -0,0 +1,3 @@
# Nginx Setup Guide
@TODO

51
docs/guides/users.md
View File

@@ -4,12 +4,16 @@
> After that, you are free to create as many users as you'd like. There is no limit to the number of
> users in a project.
## Setting up your User Profile
@TODO
## 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](#))
4. Optional: Complete the **other user form fields**
## Inviting a User
@@ -19,7 +23,7 @@
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
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
@@ -28,8 +32,12 @@ password and enable their account.
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. :::
<!-- prettier-ignore-start -->
::: User Preferences
This section of the User Detail is only visible/editable by the current user,
and admins.
:::
<!-- prettier-ignore-end -->
### Status
@@ -39,7 +47,11 @@ and admins. :::
- **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. :::
<!-- prettier-ignore-start -->
::: warning Admin Only
Only admins can adjust this field's value.
:::
<!-- prettier-ignore-end -->
### Role
@@ -47,14 +59,17 @@ Setting the user's role determines their access, permissions, and App presentati
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. :::
<!-- prettier-ignore-start -->
::: warning Admin Only
Only admins can adjust this field's value.
:::
<!-- prettier-ignore-end -->
### 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. :::
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
@@ -63,8 +78,12 @@ NULL, the token is disabled. When enabled, ensure that a secure string is used.
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. :::
<!-- prettier-ignore-start -->
::: warning Disables Access
Archiving uses _soft-delete_, therefore archived users are unable to
access the App or API.
:::
<!-- prettier-ignore-end -->
## Deleting a User
@@ -73,5 +92,9 @@ access the App or API. :::
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. :::
<!-- prettier-ignore-start -->
::: 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.
:::
<!-- prettier-ignore-end -->

13
docs/guides/webhooks.md
View File

@@ -1,8 +1,8 @@
# Webhooks
> In addition to writing custom code for more complex [event hooks](#), Directus provides a way to
> quickly configure webhooks through the App. These send HTTP requests when a specific event is
> triggered within the project.
> In addition to writing custom code for more complex [event hooks](/concepts/api-extensions),
> Directus provides a way to quickly configure webhooks through the App. These send HTTP requests
> when a specific event is triggered within the project.
## Creating Webhooks
@@ -30,5 +30,8 @@
2. Click the red **Delete Webhook** 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. :::
<!-- prettier-ignore-start -->
::: danger Irreversible Change
This action is permanent and can not be undone. Please proceed with caution.
:::
<!-- prettier-ignore-end -->

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

@@ -9,25 +9,34 @@
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](#) and on the login/public
pages
- **Project URL** — The URL when clicking the logo at the top of the [Module Bar](#)
- **Project Color** — The color used behind the logo at the top of the [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](#) and on the login/public
pages
- **Project Name** — The name used at the top of the [Navigation Bar](/concepts/app-overview) and
on the login/public pages
- **Project URL** — The URL when clicking the logo at the top of the
[Module Bar](/concepts/app-overview)
- **Project Color** — The color used behind the logo at the top of the
[Module Bar](/concepts/app-overview), on the login/public pages, and for the browser's FavIcon
- **Project Logo** — A 40x40 pixel logo at the top of the [Module Bar](/concepts/app-overview) and
on the login/public pages
::: Recommended Logo Styling The 40x40 pixel Project Logo is inset within the 64x64 pixel Project
Color square. To avoid a "boxy" look, we recommend using a SVG or PNG logo with transparency. :::
<!-- prettier-ignore-start -->
::: tip Recommended Logo Styling
The 40x40 pixel Project Logo is inset within the 64x64 pixel Project
Color square. To avoid a "boxy" look, we recommend using a SVG or PNG logo with transparency.
:::
<!-- prettier-ignore-end -->
::: Browser FavIcon & Title The project color and logo are also used to set the dynamic favicon, and
<!-- prettier-ignore-start -->
::: tip Browser FavIcon & Title
The project color and logo are also used to set the dynamic favicon, and
the project title is used in the browser's title. This furthers the bespoke appearance of your
platform and makes it easier to differentiate between different Directus projects. :::
platform and makes it easier to differentiate between different Directus projects.
:::
<!-- prettier-ignore-end -->
### Public Page Styling
In addition to the above options, you can also apply the following additional styling to your
prject's [public pages](#).
project's [public pages](/concepts/app-overview).
- **Public Foreground** — An image shown on the right-side pane of public pages; max 400px width
- **Public Background** — An image displayed behind the above foreground image, shown full-bleed
@@ -35,8 +44,11 @@ prject's [public pages](#).
- **Public Note** — A helpful note displayed at the bottom of the right-side pane of public pages;
supports markdown for rich-text formatting
::: Default Background Color When a Public Background image is not set, the right-side pane of
public pages uses the Project Color instead. :::
<!-- prettier-ignore-start -->
::: tip Default Background Color
When a Public Background image is not set, the right-side pane of public pages uses the Project Color instead.
:::
<!-- prettier-ignore-end -->
## Themes & Custom CSS
@@ -61,25 +73,26 @@ project Settings.
3. Enter any **valid CSS**
4. Click the **Save** action button in the header
::: Action Styling The `--primary` variable (and its shades) control call-to-actions and all other
"Directus blue" elements within the App. While it may be tempting to override this variable with
your brand's color, please first review the following warnings:
<!-- prettier-ignore-start -->
::: tip Action Styling The `--primary` variable (and its shades) control call-to-actions and all
other "Directus blue" elements within the App. While it may be tempting to override this variable
with your brand's color, please first review the following warnings:
- Avoid using yellow, orange, or red hues that give a sense of "danger"
- Avoid low-contrast colors like yellows, grays, etc, that might not be easily visible
- Avoid low-saturation colors like black, which might not properly highlight CTAs
:::
- Avoid low-saturation colors like black, which might not properly highlight CTAs :::
<!-- prettier-ignore-end -->
## API Reference
In addition to the static core docs, Directus also includes a [Dynamic API Reference](#) based on
your project's schema. This includes tailored endpoint info for each collection within your data
model, customizing the documentation to your specific project.
In addition to the static core docs, Directus also includes a Dynamic API Reference based on your
project's schema. This includes tailored endpoint info for each collection within your data model,
customizing the documentation to your specific project.
## System Table Prefix
<!-- @TODO ## System Table Prefix
Most white-labeling takes place in the presentation layer of the platform's App, but in some cases
even the API and/or database needs to be a bit more agnostic. For that reason, Directus allows
changing the prefix used by system tables. By default this is set to use `directus_*` to avoid any
potential conflicts, but you can override this within the [Environment Variables](#).
potential conflicts, but you can override this within the [Environment Variables](#). -->

18
docs/reference/api/activity.md
View File

@@ -1,18 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Activity',
'description':
'All events that happen within Directus are tracked and stored in the activities
collection. This gives you full accountability over everything that happens.',
'x-collection': 'directus_activity',
},
}
---
# Activity
All events that happen within Directus are tracked and stored in the activities collection. This
gives you full accountability over everything that happens.

15
docs/reference/api/assets.md
View File

@@ -1,15 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Assets',
'description':
'Image typed files can be dynamically resized and transformed to fit any need.',
},
}
---
# Assets
Image typed files can be dynamically resized and transformed to fit any need.

17
docs/reference/api/authentication.md
View File

@@ -1,17 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Authentication',
'description':
'All events that happen within Directus are tracked and stored in the activities
collection. This gives you full accountability over everything that happens.',
},
}
---
# Authentication
All events that happen within Directus are tracked and stored in the activities collection. This
gives you full accountability over everything that happens.

18
docs/reference/api/collections.md
View File

@@ -1,18 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Collections',
'description':
'Collections are the individual collections of items, similar to tables in a
database. Changes to collections will alter the schema of the database.',
'x-collection': 'directus_collections',
},
}
---
# Collections
Collections are the individual collections of items, similar to tables in a database. Changes to
collections will alter the schema of the database.

17
docs/reference/api/extensions.md
View File

@@ -1,17 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Extensions',
'description':
'Directus can easily be extended through the addition of several types of
extensions, including layouts, interfaces, and modules.',
},
}
---
# Extensions
Directus can easily be extended through the addition of several types of extensions, including
layouts, interfaces, and modules.

17
docs/reference/api/fields.md
View File

@@ -1,17 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Fields',
'description':
'Fields are individual pieces of content within an item. They are mapped to columns
in the database.',
'x-collection': 'directus_fields',
},
}
---
# Fields
Fields are individual pieces of content within an item. They are mapped to columns in the database.

18
docs/reference/api/files.md
View File

@@ -1,18 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Files',
'description':
'Files can be saved in any given location. Directus has a powerful assets endpoint
that can be used to generate thumbnails for images on the fly.',
'x-collection': 'directus_files',
},
}
---
# Files
Files can be saved in any given location. Directus has a powerful assets endpoint that can be used
to generate thumbnails for images on the fly.

15
docs/reference/api/folders.md
View File

@@ -1,15 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Folders',
'description': 'Group files by virtual folders.',
'x-collection': 'directus_folders',
},
}
---
# Folders
Group files by virtual folders.

17
docs/reference/api/items.md
View File

@@ -1,17 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Items',
'description':
'Items are individual pieces of data in your database. They can be anything, from
articles, to IoT status checks.',
},
}
---
# Items
Items are individual pieces of data in your database. They can be anything, from articles, to IoT
status checks.

15
docs/reference/api/permissions.md
View File

@@ -1,15 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Permissions',
'description': 'Permissions control who has access to what and when.',
'x-collection': 'directus_permissions',
},
}
---
# Permissions
Permissions control who has access to what and when.

18
docs/reference/api/presets.md
View File

@@ -1,18 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Presets',
'description':
'Presets hold the preferences of individual users of the platform. This allows
Directus to show and maintain custom item listings for users of the app.',
'x-collection': 'directus_presets',
},
}
---
# Presets
Presets hold the preferences of individual users of the platform. This allows Directus to show and
maintain custom item listings for users of the app.

2
docs/reference/api/query/fields.md
View File

@@ -1 +1,3 @@
# Fields
@TODO

18
docs/reference/api/relations.md
View File

@@ -1,18 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Relations',
'description':
'What data is linked to what other data. Allows you to assign authors to articles,
products to sales, and whatever other structures you can think of.',
'x-collection': 'directus_relations',
},
}
---
# Relations
What data is linked to what other data. Allows you to assign authors to articles, products to sales,
and whatever other structures you can think of.

18
docs/reference/api/revisions.md
View File

@@ -1,18 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Revisions',
'description':
"Revisions are individual changes to items made. Directus keeps track of changes
made, so you're able to revert to a previous state at will.",
'x-collection': 'directus_revisions',
},
}
---
# Revisions
Revisions are individual changes to items made. Directus keeps track of changes made, so you're able
to revert to a previous state at will.

15
docs/reference/api/roles.md
View File

@@ -1,15 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Roles',
'description': 'Roles are groups of users that share permissions.',
'x-collection': 'directus_roles',
},
}
---
# Roles
Roles are groups of users that share permissions.

17
docs/reference/api/server.md
View File

@@ -1,17 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Server',
'description':
"Access to where Directus runs. Allows you to make sure your server has everything
needed to run the platform, and check what kind of latency we're dealing with.",
},
}
---
# Server
Access to where Directus runs. Allows you to make sure your server has everything needed to run the
platform, and check what kind of latency we're dealing with.

15
docs/reference/api/settings.md
View File

@@ -1,15 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Settings',
'description': 'Settings control the way the platform works and acts.',
'x-collection': 'directus_settings',
},
}
---
# Settings
Settings control the way the platform works and acts.

15
docs/reference/api/users.md
View File

@@ -1,15 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Users',
'description': 'Users are what gives you access to the data.',
'x-collection': 'directus_users',
},
}
---
# Users
Users are what gives you access to the data.

16
docs/reference/api/utilities.md
View File

@@ -1,16 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag':
{
'name': 'Utilities',
'description':
'Directus comes with various utility endpoints you can use to simplify your
development flow.',
},
}
---
# Utilities
Directus comes with various utility endpoints you can use to simplify your development flow.

10
docs/reference/api/webhooks.md
View File

@@ -1,10 +0,0 @@
---
{
'layout': 'APIReferenceLayout',
'tag': { 'name': 'Webhooks', 'description': 'Webhooks.', 'x-collection': 'directus_webhooks' },
}
---
# Webhooks
Webhooks.

17
docs/reference/environment-variables.md
View File

@@ -55,10 +55,13 @@ Database user's password. Required when using `pg`, `mysql`, `mysql2`, `oracledb
Where to read/write the SQLite database. Required when using `sqlite3`.
::: Additional Database Variables All `DB_*` environment variables are passed to the `connection`
<!-- prettier-ignore-start -->
::: tip Additional Database Variables
All `DB_*` environment variables are passed to the `connection`
configuration of a [`Knex` instance](http://knexjs.org). Based on your project's needs, you can
extend the `DB_*` environment variables with any config you need to pass to the database instance.
:::
<!-- prettier-ignore-end -->
## Security
@@ -145,11 +148,13 @@ limiter used, you must also provide the following configurations.<br>**Default:
- **Memcache**
- **`RATE_LIMITER_MEMCACHE`** — Location of your memcache instance
::: Additional Rate Limiter Variables All `RATE_LIMITER_*` variables are passed directly to a
<!-- prettier-ignore-start -->
::: tip Additional Rate Limiter Variables All `RATE_LIMITER_*` variables are passed directly to a
`rate-limiter-flexible` instance. Depending on your project's needs, you can extend the above
environment variables to configure any of
[the `rate-limiter-flexible` options](https://github.com/animir/node-rate-limiter-flexible/wiki/Options).
:::
<!-- prettier-ignore-end -->
## Cache
@@ -161,8 +166,12 @@ Whether or not caching is enabled.<br>**Default: `false`**
How long the cache is persisted.<br>**Default: `30m`**
:::warning Forced Flush Regardless of TTL, the cache is always flushed for every create, update, and
delete action. :::
<!-- prettier-ignore-start -->
::: warning Forced Flush
Regardless of TTL, the cache is always flushed for every create, update, and
delete action.
:::
<!-- prettier-ignore-end -->
### `CACHE_NAMESPACE`

10
docs/reference/error-codes.md
View File

@@ -1,5 +1,7 @@
# Error Codes
@TODO
| Error Code | Description |
| --------------------- | ---------------------------------------------- |
| `FAILED_VALIDATION` | Validation for this particular item failed |
@@ -12,5 +14,9 @@
| `ROUTE_NOT_FOUND` | Endpoint does not exist |
| `SERVICE_UNAVAILABLE` | Could not use external service |
:::warning Security To prevent leaking which items exist, all actions for non-existing items will
return a `FORBIDDEN` error. :::
<!-- prettier-ignore-start -->
::: warning Security
To prevent leaking which items exist, all actions for non-existing items will
return a `FORBIDDEN` error.
:::
<!-- prettier-ignore-end -->

6
docs/reference/filter-rules.md
View File

@@ -4,6 +4,8 @@
> define their rules. This page describes the syntax for creating flat, relational, or complex
> filter rules.
@TODO check+extend
## Syntax
- **Field** — Any valid root field, [relational field](#), or [logical operator](#)
@@ -72,8 +74,8 @@
## Relational
You can target related values by nesting field names. For example, if you have a relational
[Many-to-One](#) `author` field, you can set a rule for the `author.name` field using the following
syntax.
[Many-to-One](/guides/field-types/many-to-one-field) `author` field, you can set a rule for the
`author.name` field using the following syntax.
```json
{