Storyblok Raises $80M Series C - Read News

Skip to main content

How to build relationships: Post and Categories? #2

  • Home
  • Tutorials
  • How to build relationships: Post and Categories? #2

On May 13th, 2024, Storyblok started gradually rolling out a new design for its Visual Editor. Therefore, the Visual Editor product screenshots depicted in this resource may not match what you encounter in the Storyblok App. For more information and a detailed reference, please consult this FAQ on the new Visual Editor design.

During this article, you will learn how to build a relationship between two content-types using a headless CMS. Our previous article covered how you can reference one author in your posts. In this tutorial we will add categories to that structure. You will also learn how to use that relationship to receive your content via Storybloks content delivery API.

Requirements and Goal

Make sure you've your blog setup from the first article or another content-type you want to build a relationship within your Storyblok space. Our goal for this article is to create a relationship between posts and categories. One post should be able to have multiple categories. One category should be referenced in multiple posts.

Goal Description

Add a Content-Type Category

Same as in our previous article we will create a new Content-Type to do so we will create a new folder called Categories with the Default Content-Type category. Since this Content-Type does not exist yet we will again press the Create new 'category' during the folder creation, also this time we will disable the visual editor to keep things simple for the beginning.

Create our first Category

Now we're already able to create our first category in the Categories folder. Navigate into Categories and press the New button on the top right corner to create the new content-entry. You will be able to add a name, slug and content-type where the content-type should already be category, if not check your folder settings if you've added category as your Default Content-Type for the Categories folder.

Define your Category fields

Since we've not defined any schema for this content-type yet we press Define schema to add the fields we want. We're going to build out the category with the fields below. You're not limited to those fields append and remove fields as you want.

  1. Key: name, Type: Text - to allow input a name of the category
  2. Key: image, Type: Image - to allow upload a category image

After adding the schema keys for your content-type we will press the Save Schema at the top right corner of the application and move forward to adding content to our newly created form.

Fill with content

You should now already be able to add the name and upload a category image as shown below. I've named my first category Design and uploaded the illustrations from Undraw. We've also created Tech and Finance using the same approach. After that, you will be able to access your categories using the Draft JSON option from the top right corner. Make sure to press Save and Publish so we will have those categories available later.

Accessing your Category via API

You should already be familiar with how to access a single entry via slug and also how to access multiple entries using the folder slug if you've read the previous articles. If you have a look at one of the content entries you again will notice the same uuid field which will be used to create relationships between content types.

Extend your post with a categories field

From the last article your final result should look the screen below where you can see a title, image, content and author field.

Define the new field

To define the new field we will press the Define Schema button and add a new key categories with the type Multi-Options since we want to allow a multi select. Add Stories as the type of source you want to use. To only show content entries from the Categories folder we will configure the Path to folder of stories with categories/. Make sure to select Use UID instead of ID otherwise you would end up with the numeric ID rather than the UID. Do not forget to press Save Schema at the top right corner to save your content-type schema.

Choose your Categories

You should now be able to see a multi-select with your category entries. Let's select the categories you want and press Save.

Accessing a Post with the categories field

If we now access a single post we should see a field categories with an array of uuid of the categories we've selected in the interface. You can click the image to access the performed request.

JSON result with the selected categories

Get the Categories of one Post

If we're on the detail page of a post we may want to load the detail information of the connected categories. Therefore we somehow need to filter our categories by the uuid we've available in our post. The Storyblok Content Delivery API allows you to use the by_uuids query parameter to filter by exactly that. You can add one or multiple uuids if you want to receive multiple categories in our response. You can click the image to perform the request.

Request to receive the categories of a post by uuids

Get all Posts by Category

Let’s think about an category detail page containing all posts by that category. To create a page like this we need to filter our list of posts by a specific uuid of one category. For this case, you’re able to use the filter_query[KEY][OPERATION] parameter of the Content Delivery API. Since we want to know if a value in_array the categories array our parameter will look like filter_query[categories][in_array] with the uuid of the category as a parameter.

Request all posts of a curtain category

Next Steps

You should now be able to create a one to many relationship between to content types, request them using the filter_query parameter and allow you editors to manage categories for their posts. If did not add authors yet make sure to check out our previous tutorial.

  1. Build your own Blog using the technology you want!
  2. Use Storybloks Image Service for your blog overview, author avatar and category images.
  3. Add the Storyblok JS Bridge and enable the visual edit-mode.
  4. Check out more params of the Content Delivery API

We’re always searching for a way to improve Storyblok to get a better experience for you – therefore we would love to receive your feedback!


Dominik Angerer

Dominik Angerer

A web performance specialist and perfectionist. After working for big agencies as a full stack developer he founded Storyblok. He is also an active contributor to the open source community and one of the organizers of Scriptconf and Stahlstadt.js.