mirror of
https://github.com/directus/directus.git
synced 2026-02-16 17:35:39 -05:00
159 lines
6.5 KiB
Markdown
159 lines
6.5 KiB
Markdown
# 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.
|
|
|
|
:::
|