Made withDirectusClip

Lesson 2 - Customizing Your Data Model - Onboarding

D

Directus

Creator on the Directus channel

Watch on YouTube ↗

14K viewsJun 26, 202313:29 runtime

Learn how to expertly customize your Directus data model to fit any project's needs. This guide walks you through creating and configuring collections, fields, and relationships from the ground up. Discover how to manage collection settings like display templates, singleton…

Chapters

#directus#clip#cmscrm

Customizing Your Data Model in Directus

This document outlines key concepts for customizing collections, fields, and relationships within the Directus Data Studio.

Customizing Collections

Access: The data model is managed under Settings > Data Model.
Layout & Appearance: You can customize a collection's icon, color, and add an internal note for documentation.
Display Template: Controls how items from this collection are displayed when referenced elsewhere in the app. Keep it short and avoid JSON fields.
Singleton Collections: Treat a collection as a single object (e.g., for global website settings). Instead of a list, it opens directly to the detail page.
Name Translations: Change how a collection's name is displayed throughout the app for different users or languages without altering the actual table name (e.g., renaming posts to Blog Posts).
Advanced Settings:
- Archiving: Enable soft-deletes by specifying a status field.
- Sorting: Assign an integer field to enable manual sorting.
- Accountability: Track activity and revisions for content-rich collections. This can be disabled for simpler collections to save database space.

Creating and Configuring Fields

Creation: Create fields using the simple wizard or the "Advanced Mode" for more control.
Field Customization: Each field has several configuration tabs:
- Schema: Define the underlying database properties like data type, default value, and whether the value must be unique.
- Interface: Configure the look and feel of the input component (e.g., for a tags field, you can add presets).
- Display: Control how the field's data is shown in list layouts (e.g., as labels).
- Validation: Set up rules to ensure data integrity (e.g., field is not null).

Important
Conditional Fields: Use the Conditions tab to create dynamic forms. You can show, hide, or alter fields based on the values of other fields. For example, you can hide a tags field if the status is set to draft.

Creating a New Collection

Navigate to Settings > Data Model and click Create Collection.
Provide a name (e.g., my_new_collection).
Choose a Primary Key type, such as a generated UUID (recommended).
Optionally add pre-configured System Fields like status, sort, user_created, and date_created.

Note
When you create a collection or a field in the Directus app, the API automatically makes the corresponding change to your SQL database schema (e.g., creating a new table or adding a new column).

Professional Tips & Best Practices

Tip

Plan Ahead: Before building in Directus, model your data on paper or with a diagramming tool like draw.io or FigJam to visualize relationships.

Leverage Relationships: Take full advantage of Directus's powerful relationship-building capabilities to link your collections.

Schema as Code: Use the schema endpoints in the API to export your entire data model (collections, fields, relations) as a JSON file. This allows you to version-control your schema in a Git repository.

Introduction to the Data Model

Hi Brian here, welcome back to another lesson in our onboarding series. Today we're talking about our data model. How can we customize our data model? How can we create our own collections, fields, and relationships? And then I'll share a few tips and tricks with you. Let's get started.

Let's load up our sample Directus project. So we'll go over here, I'm going to open up posts. Over here on the left I can see I've got all of my different collections of content, and our data model is actually controlled from the settings panel. So I just go into settings, I make sure I look for data model, and this gives me a list of all of my collections. Let's open up one of these, let's just take the post for example.

Exploring Collection Settings

Our data model for posts here are all of the individual fields for our posts. So we have a sort field that's hidden, we have a primary ID field, we have status, we have links, we have titles, we have slugs, we have categories, we have authors, summary, we have the actual content, and then we have a relationship for our SEO collection. So these are the different fields, and Directus makes it super easy to control the layout for all those fields. I can go in and edit those fields, which we'll do in just a moment. But if we keep scrolling down, we'll see the collection setup.

Collection Configuration and Display

So here we've got a shortened note about this particular collection. We could set an icon and a color, and if you're like me, you're going to get really into this because you'll want to have everything nice and organized and color-coded. Alright, so let's dive back into our post collection and continue running through the fields.

The display template is basically how items within this post collection or any other collection are referenced throughout the app. So that's if they're displayed in another collection or any of the different views inside the app. You want to keep this to as short as possible and make sure that you're not using any of the JSON fields because it could display kind of funky on the screen.

Singleton Collections and Name Translations

Next, we have hidden. So do we want to hide this particular collection from the app? Which is very useful for like parent and child relationships where you want to hide the child.

And then we have our Singleton collection. So we'll treat this collection as a single object. This is really great for stuff like globals on a website or settings that apply across. What it will do whenever you click into that collection, instead of showing a list of items, it will show a single item detail page.

Next, we have our collection naming translations. This is so that for your users, mostly, this will allow you to rename a collection. So in the case of posts here, if I didn't want to say post, I wanted to show this as blog posts, we'll change the name here. We've got a blog post, the plural unit would be blog posts. And now when I update this, throughout the app you will see, if I open this up, this says blog posts. We say blog posts over here, and anytime we are referencing that collection throughout the data studio app, it will use the terms that you set instead of the actual name. This is super handy for stuff like the page builder that we'll get into.

Archival, Sorting, and Accountability Settings

So let's go back and we'll continue working our way through here. Do we want to archive or enable a soft delete on this collection? A very helpful feature, you just select the field that controls that, the archive value, and the unarchived value. Great.

Do we have a particular sort field for this? Just an integer that we can use to sort the different values. And then we have our accountability. So do we want to track activity and revisions? We covered revisions in a previous video, but do we want to track only activity or we don't want to track anything? So this is super helpful for content collections, but if it's something really simple and you don't really care about the activity tracking, you know, you don't need to track that activity. Set it up that way so that you know you're not storing unnecessary records.

Creating and Configuring a New Field

You can also set up the duplication settings. So whenever you save as a copy inside the data studio app, you can set which fields will be duplicated across that collection. So that's it for the collection settings. Let's dive in on actually how to edit and create a new field inside a collection.

There's several ways you could do this. I can create a new field and use our little wizard UI, which is very nice. Once you get very familiar with Directus, you might even jump straight into the advanced mode. So you pick which type of field, and then you get to run through all the different options. For now, let's just choose to add something simple like tags to this particular blog post. So we'll go in, we'll create a new field, and we can see the different interfaces that are available to you. I'm just going to choose tags here, and we'll give this a key of tags. We've got JSON or CSV as the format. I'm just going to choose JSON here. We could set a default value on any field, which is nice. I can also require tags to be set whenever a user is creating a new blog post.

Here I'll just go in and add a couple of tags for case study, video, showcase, whatever. These are will be presets that show exactly like this that the user can pick. And of course you could set it up where they can allow other users. So whenever you select a particular interface, that interface will have different options, just like this. So next we could save this and we will see that tags have been added to our data model, to our fields for this particular collection. And before I run off, let me actually save this and then we can go into a particular blog post and take a look at those tags. So we'll scroll down, scroll down, boom, there it is. So we've got our attack presets and other tag that you will like. I just hit enter to save that value. Now any of these fields I can always take a look at the raw value and you could just see this is how this is going to be stored in the database: just JSON values. Excellent, so we'll discard that for now. Let's go back to our post collection and we've got our tags here.

Advanced Field Editing Options

Let's edit this field and and run through the other options that are available to you. So this is what you'll see when you're creating a field through the advanced mode or if you edit any of the existing fields. So you've got your schema tab that has some settings like the type, the length, the default value. We saw those when we were creating this. You could choose whether this value has to be unique, which for tags probably not, but if you've got something like an email address or a UUID that you're storing, you'll definitely want to make sure that field is checked.

Do we want to disable editing this value within the app? Do we want to make it required? Is it hidden? We can also go in and add helpful notes. These will display as references, as handy little pieces of information to your users when they are editing content. So you know, maybe don't apply more than five tags per post.

Then we have our field name translations, just like our collection name translations, you can translate this field for different users of your app in as many different languages as you want. Moving on to the interface, that's all these settings for that particular interface, and of course that will change depending on the interface that you're using. The display section is how this data is displayed throughout the different layouts inside Directus. So do we want to use a formatted JSON value or do we want to show as labels?

Next, we have our validation. So I could set up specific validation rules like tags isn't null. This will throw an error and we could say, hey, tags need to be applied. And you can set up different filters depending on the type of data that is being stored. This is being stored in JSON, so we can't do a lot of fancy validation with that, but on other fields, field types, you certainly can.

Setting Up Conditional Field Logic

And that brings us to the conditions, which are you could set up conditional fields with. So if a particular field doesn't have the right value, show on value. So I could configure a rule and then I can change whether this is hidden or, you know, I can control the different interface options based on that criteria. So if I say if the status is equal to draft, we are going to hide this particular field. And we could check out the effect of that if we go into one of our blog posts. So this one is set to scheduled. I can see tags down here at the bottom. If I change this to draft, oops, tags have disappeared. So conditional fields are very handy when setting up clean, easy-to-use interfaces for your content editors, and I encourage you to take a deep dive into those and figure out how to make that editing experience much smoother.

How to Create a New Collection

Quickly run through creating a collection and then we'll wrap this one up. So to create a new collection, you go to the data model, look for the create collection option up here on the top right and give this a name. You can use any kind of format that you want. I prefer lowercase snake case, that's kind of the convention that I follow for all of my projects, but I see plenty of people that do not follow that conviction. Directus will work fine either way, but we just create a new collection. Is this a Singleton? We'll set up a primary key field and you could choose various options here between an integer or big integer, generated UUID which works very well, or a manually entered string. Typically I just use the generated UUID and keep it simple with ID.

Next, we have our system optional fields or optional system fields. You can go in and any of these you can check the box to already apply these. These have defaults configured to them. Status is a dropdown that has draft, published, and archived. Sort is just an integer. And the other thing I can go in here and do is just change the keys of these very quickly. So if you prefer created_at or updated_at for that format for your dates, easy to change, not a big deal. Then you just hit save and now you have a new collection. Behind the scenes, the Directus API has created a new table inside your SQL database as well. And any of these changes that you make to the field, so if I go in and add a new title field that is a string, the API will make that change to your SQL database as well. So that's creating a collection.

Tips for Customizing Your Data Model

Let's dive into just a couple of quick tips on customizing your data model. My first recommendation is when you're working on more complex projects or even just simple projects to start out with, it can be helpful to model your data on paper or a diagramming tool like draw.io or FigJam, whatever tool that you prefer there, just to get an idea of how everything maps before you start building inside Directus. Number two, take advantage of the powerful relationships that are available inside Directus. We've got some great documentation on that, and I'll be covering relationships a little deeper in another video. And for you folks who prefer to have all of your schema, all of your data in code, so your actual data model, you can use our schema endpoints which will export all of this data model, your collections, fields, and relations into JSON format so you can check that into your Git repository. That's all I've got for you today. Hopefully this is a few helpful tips for you. I'll catch you on the next lesson. See ya.