Two-level taxonomy model
#Overview
Join our community to suggest new recipe ideas!
This guide shows how to create a two-level taxonomy model that lets you select parent categories that display reference fields to add related sub-categories.
You'll create an enumeration for the parent categories, two sub-category models, a category selector component, and a final sample model for a drinks page that lets you add some basic information about the drink, and select parent categories and sub-categories for it.
Two-level taxonomy model
This recipe is a great option if you need a taxonomy setup that allows referencing sub-category entries based on the parent category selected. A setup like this ensures that after selecting a parent category, editors will only be able to reference sub-categories related to it.
This image shows what a frontend using this setup could look like:
Two-level 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 Two-level 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 Two-level 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.
- Enumerations: an enumeration is a predefined set of values representing a list of possible options. You can use them to group values within a type.
- Component: a pre-defined set of fields that can be reused across models and content entries. You can think of a component as a flexible, reusable template: you define the fields that will be used inside a component once and then fill them with different content every time you use it in a content entry.
- Basic component field: A component is a special field type in your Hygraph schema that defines which components of which type can be used in a model. Component fields can be of basic or modular types. A basic component field can only have one component attached to it. You can limit the number of component instances to one or allow multiple component instances to be added to the content entry.
- 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 enumeration
Our two-level taxonomy model will contain an enumeration field to select a drink type.
Navigate to the Schema builder of your Hygraph project, and click +Add next to Enumerations on the left sidebar. We'll use the following information to create the first one:
| Field | Input |
|---|---|
| Display name | Drinks |
| API ID | Drinks |
The next step is to add enumeration values, which are the options you will get when using this later as a dropdown menu.
For every enumeration value, you need to enter a Display name, an API ID, and click Add.
We'll add the following values:
| Display name | API ID |
|---|---|
| Wine | wine |
| Juice | juice |
Finally, click Add enumeration to save.
We've only added two values because the next step involves creating one model for each of the values that we created here, and we don't want you to waste time creating endless models that would not add quality to the current example.
Since the focus of this guide is the taxonomy, what matters the most is the dynamic where we use an enumeration field to set conditional visibility for reference fields linking the models we will create next.
#2. Create the sub-category models
We will create two models for our sub-categories. 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 first model, navigate to the Schema builder and click +Add next to Models. Use the following information:
| Field | Input |
|---|---|
| Display name | Drink - Wine |
| API ID | DrinkWine |
| API ID Plural | DrinkWines |
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:
| Tab | Field | Input |
|---|---|---|
| Settings | Display name | Name |
| Settings | API ID | name |
| Settings | Description | Add a name here |
| 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 category entries are created with the names as titles, for quick identification in the content table. These titles must also be unique, which will avoid editors adding the wrong entry when selecting categories.
Next, you want 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 | Description |
| Settings | API ID | description |
| Settings | Description | Write a description here |
| 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.
Since our second category model will contain the same set of fields, we will go ahead and duplicate the model that we've just created, and then edit its details.
In the Drink - Wine model, click the 3 dots context menu at the top of the screen, and select Duplicate.
Duplicate model
The system will duplicate the model and will rename it to Copy of (model name).
Click on the Settings tab at the top and replace the existing information with the following:
| Field | Input |
|---|---|
| Display name | Drink - Juice |
| API ID | DrinkJuice |
| API ID Plural | DrinkJuices |
Click Update Model to save.
In the next step, we will create a component for category selection that uses what we've built so far.
#3. Create the component
In this section you'll create a component for category selection, that we'll later include in the final model as a basic component field.
Creating a component for the two-level taxonomy setup, allows you potentially reuse it in multiple models.
Since the different levels of category selection would exist at the same level in the schema if added to a model directly, this setup also helps when querying the data, as the query would clearly show these fields as part of the category selection component.
In the Schema builder, click +Add next to Components and use the following information:
| Field | Input |
|---|---|
| Display name | Two-level taxonomy component |
| API ID | TwoLevelTaxonomyComponent |
| API ID Plural | TwoLevelTaxonomyComponents |
Click Add component to save.
Now that you've created the component itself, it's time to add fields to it. You'll add an enumeration field using the enumeration you built earlier, and two reference fields that link to the models you created in the previous step.
This simplified example focuses on linking categories, so make sure to carefully think what other fields your component might need when working on a taxonomy setup for your own project.
Find the Enumeration field on the right sidebar, click Add, and use the following information to create the enumeration:
| Tab | Field | Input |
|---|---|---|
| Settings | Display name | Drink selector |
| Settings | API ID | drinkSelector |
| Settings | Enumeration | Use the dropdown menu to select Drinks. |
| Settings | Description | Select a drink from the menu |
Click Add to save.
For the purpose of this example, we're not allowing multiple values. If your category selection requires more than one parent category being selected at the same time, consider allowing multiple values here.
This enumeration field will allow us to set conditions for the 2 reference fields we're about to add. We did not make this field required because conditional visibility does not support required fields.
Finally, we will add two reference fields that connect the models we created in the previous step. Referencing the category models 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 Drink - Wine |
| 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 | Wine |
| Configure | API ID | wine |
| Configure | Description | Select one or more types of wine |
| Configure | Show based on condition | Select this checkbox and then use the dropdowns to select Drink selector is Wine. |
Click Add to save.
We'll repeat the process to add the final reference, 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 Drink - Juice |
| 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 | Juice |
| Configure | API ID | juice |
| Configure | Description | Select one or more types of juice |
| Configure | Show based on condition | Select this checkbox and then use the dropdowns to select Drink selector is Juice. |
Click Add to save.
In the next step, we will create the Two-level Taxonomy model, which will contain a couple of basic information fields and a basic component field for the component we've just created.
#2. Create the final model
For this example, we'll create a basic model for a drinks page. We'll add a drink name & description, and a component field for category selection.
To create this model, navigate to the Schema builder and click +Add next to Models. Use the following information:
| Field | Input |
|---|---|
| Display name | Two-level Taxonomy Model |
| API ID | TwoLevelTaxonomyModel |
| API ID Plural | TwoLevelTaxonomyModels |
Click Add Model to save.
This model will contain a Single line text field for the drink name, a Rich Text field for the drink description, and a Basic component field for category selection.
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 | Drink name |
| Settings | API ID | drinkName |
| 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 that all the resulting content entries contain a unique 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 | Description |
| Settings | API ID | description |
Click Add to save.
Next, you will add the basic component field. Find the Basic component field on the right sidebar, using the following information:
| Tab | Field | Input |
|---|---|---|
| Settings | Display name | Category selector |
| Settings | API ID | categorySelector |
| Settings | Description | Select a category and subcategories |
| Settings | Select a component | Use the dropdown to select Two-level taxonomy component. |
Click Add to save.
Your model is ready! This is how you build a two-level taxonomy model in Hygraph where the sub-categories that editors can select are tied to the parent category.
#Resulting content form
If you followed this tutorial, your resulting content form should look like this:
Resulting content form
When using the category selection component, editors will be able to use a dropdown menu to select a parent category, which will determine which reference field will display to select sub-categories.
In this example, the editor creates a content entry about orange juice and when selecting categories for the drink, they select that it’s a juice of the citrus variety.
#Useful links
- Components documentation: Learn more about components, available component field types, and how to use them.
- Enumerations: Learn more about enumerations and how to configure them.
- References: Learn more about the different reference field types and how to configure them.