Flat taxonomy model
#Overview
Join our community to suggest new recipe ideas!
This guide shows how to create a flat taxonomy model that connects content entries to categories.
You'll create a category model and reference it in another model to select content entries as categories.
Flat taxonomy model
This recipe is a great option if you need a taxonomy setup that is fast & simple to use. It is also a good setup to use if your project works with flat categories that do not require to be connected in a way that establishes a hierarchy.
This image shows what a frontend using this setup could look like:
Flat taxonomy - frontend visual example
#Prerequisites
REQUIRED:You need to have a Hygraph account. If you don't have one, you can sign up here.REQUIRED:You need to have a Hygraph project. Look into the following section to learn more about your options.
#What you can do
Use this guide to create a Flat taxonomy model. You have two options:
OPTION 1:Create a project. This is the way to go if you want to follow the entire tutorial for learning purposes.OPTION 2:Use an existing project of yours. This is the way to go if you already have a project and want to add this model. In this case, you may need to adjust parts of the tutorial to your own project schema.
- Take plan limits into consideration when adding a recipe to your own project.
- Are you new to Hygraph? You may want to check out our Getting Started Tutorial!
#Not in the mood to start building?
This is the way to go if you're curious about how we built the taxonomy recipes but don't want to follow the step-by-step creation process. This project contains the entire Taxonomy Cookbook so you can compare recipes or look into what instances they contain.
#Core concepts
In this guide, you'll work with different schema elements to create a Flat taxonomy model. Let's look into them:
- Model: Your schema is the content structure of your project. You can define your schema by creating models, adding fields, reusable components, and sidebar widgets, integrating remote sources, and establishing relationships with other models.
- References: References are relations between two or more content entries in your project. With references, you can reuse content entries by connecting them. Once the relation is configured, you can also create related content directly from the content form.
#Step-by-step guide
This video follows the same step-by-step tutorial offered in this document.
#1. Create the category model
This model will let you create categories as content entries. For the sake of this example, we will only include a couple of fields to store basic information, but you may want to add more fields depending on your needs.
To create the model, navigate to the Schema builder and click +Add next to Models. Use the following information:
| Field | Input |
|---|---|
| Display name | Category - Book Genre |
| API ID | CategoryBookGenre |
| API ID Plural | CategoryBookGenres |
Click Add Model to save.
Let's add fields to this model. We will add a Single line text field to use as category name, and a Rich Text field for the category description.
For the category name, add a Single line text field from the right sidebar, and use the following information:
| ----------- | --------------------- | ---------------------------- |
| Settings | Display name | Category name |
| Settings | API ID | categoryName |
| Settings | Use as title field | Leave this checkbox selected |
| Validations | Make field required | Select this checkbox |
| Validations | Set field as unique | Select this checkbox |
Click Add to save.
This configuration ensures all entries are created with the category names as titles, for quick identification in the content table. These titles must also be unique, which will contribute to a good user experience for editors selecting categories for a content entry.
Next, you want to include a rich text field for the description, which will also allow some formatting. Add a Rich text field from the right sidebar, using the following information:
| Tab | Field | Input |
|---|---|---|
| Settings | Display name | Category description |
| Settings | API ID | categoryDescription |
| Validations | Make field required | Select this checkbox |
Click Add to save.
We created a model for the categories because creating categories as content entries means they can be easily referenced in other models and components later on. This setup also makes adding new categories or editing existing ones very easy.
In the next step, we will create the Flat Taxonomy model with a reference field that links this model.
#2. Create the final model
For this example, we'll create a model that contains some basic book data, and allows selecting literary genres as book categories.
This simplified example focuses on linking categories, so make sure to carefully think what other fields your model might need when working on a flat taxonomy setup for your own project.
To create this model, navigate to the Schema builder and click +Add next to Models. Use the following information:
| Field | Input |
|---|---|
| Display name | Flat Taxonomy Model |
| API ID | FlatTaxonomyModel |
| API ID Plural | FlatTaxonomyModels |
Click Add Model to save.
This model will contain a Single line text field for the book title, a Rich Text field for the book description, an Asset picker field to add book related images, and a Reference field to link categories.
First, we'll add the title. Add a Single line text field from the right sidebar, and use the following information:
| Tab | Field | Input |
|---|---|---|
| Settings | Display name | Book Title |
| Settings | API ID | bookTitle |
| Settings | Use as title field | Leave this checkbox selected |
| Validations | Make field required | Select this checkbox |
Click Add to save.
This configuration ensures that all book entries contain a title that will allow easy identification in the content table.
Next, you want to include a rich text field for the description, which will also allow some formatting. Add a Rich text field from the right sidebar, using the following information:
| Tab | Field | Input |
|---|---|---|
| Settings | Display name | Book Description |
| Settings | API ID | bookDescription |
Click Add to save.
Next, you want editors to be able to include at least one image in the content form when writing about books. Add an Asset picker field from the right sidebar, using the following information:
| Tab | Field | Input |
|---|---|---|
| Settings | Display name | Image |
| Settings | API ID | image |
| Settings | Description | Add one or more images for the book here |
| Settings | Allow multiple assets | Select this checkbox |
Click Add to save.
Finally, we will add a reference field that connects the model we created in the previous step. Referencing the category model here will allow editors to quickly link category content entries directly from the content form.
Add a Reference field from the right sidebar, using the following information:
| Tab | Field | Input |
|---|---|---|
| Define | Allow only one model to be referenced | Select this radio button. |
| Define | Model to reference | use the dropdown to select Category - Book Genre |
| Define | Reference direction | Use the radio button to select One-way reference |
| Define | Relation cardinality | One to Many |
| Define | Allow multiple (…) | Select this checkbox |
| Configure | Display name | Genre |
| Configure | API ID | genre |
| Configure | Description | Select one or more literary genres |
Click Add to save.
Your model is ready! This is how you build a flat taxonomy model in Hygraph. Our Related product pages recipe uses models and references in a similar way to connect 3 models and potentially allow the user to navigate an online bookstore by genre, books and authors. Make sure to check it out if you're looking for a flat taxonomy setup that's a bit more complex than this one.
You could make a bit more out of this by adding an additional reference field with the same configuration to add a subcategory, and allowing your frontend to handle the hierarchy using the field IDs.
#Resulting content form
If you followed this tutorial, your resulting content form should look like this:
Resulting content form
Editors will be able to easily link categories using a reference field. Since our reference field allows multiple values, they will be able to select more than one.