Using relationship resolving to include other content entries
Storyblok is the first headless CMS that works for developers & marketers alike.
In our previous articles you had the chance to learn how to structure your content for a blog, including authors and categories. The next step is to utilize Storyblok and the already available
home content entry to create your landing page and enhance it with featured posts.
The demo content
home content entry that you receive by creating a new space already includes three components: Teaser, Grid, and a nested Feature component. Those components can be removed or adjusted to your needs. What we’re about to do is to extend the list of available components with a new one:
The featured posts component
The featured posts component will be used as a container for all our post references. Think of it as a section we want to have on our start page beside a teaser and a grid that contains the information of our articles. Let’s start by navigating to Components in the left sidebar.
Once you’re on the components overview we will create a new component by pressing New on the top right corner.
Enter the name
featured_posts and press Save on the top right corner to create the new component.
We will now continue by adding one new field. This new field with the name
posts will be of type
Multi-Options as we will use it to select other stories of the
posts/ folder. To create a new field write the key:
posts in the Schema section and press Add.
Next, we will select the field type
multi-options by clicking on the Multi-Options symbol.
To allow the selection of other Stories, we will change the Source of the
posts field to Stories.
Once you select Stories as the source, you can now write the path
posts/ in the now available Path to folder or stories input located below the dropdown.
The last thing we currently need to do with the
featured_posts is to save it by pressing Save at the top right corner.
Using the featured posts component
We will now navigate back to the Content menu item and press on the Home entry that should be available as Storyblok will create it as an example for new spaces. If you do not have that entry, you can press + Entry on the top right corner, enter Home as the name, select the content type Page and press Create. You won’t have to do that step if you already have the Home entry available.
By default you will see the quickstart screen, as the tutorial aims to be technology independent we will ignore that setup in this article, however, you can follow the other tutorials that use Nuxt, Next, and many more.
The next step we’re about to do is to actually use our new
featured_posts component. To do that we will press Add block in the right sidebar.
You will now see a list of nestable components, you can define which components should be allowed to be nested in that place in the allowlist feature of the field in the page content type. As there is no allowlist enabled you should already be able to see Featured Posts as one of them. Let’s click on it to add it to the content.
Once you click on the component you want to add Storyblok will add the instance to the current content and open that instance in the sidebar. You should now already be able to select the posts you want to feature. I’ll feature My first Post as it was the first post we created in the initial tutorial. This list will be empty if you do not have any entries in a folder with the slug
posts so make sure to have a look at the first blog tutorial.
Once selected, we will have to Save and Publish our content entry to actually persist and make it available in the Content Delivery API. Pressing Publish will also save your content, if you would only Save the entry we will store a draft version, publishing will result in a newly published version. I’ll go ahead and publish the entry.
Next thing to do is to retrieve the content from our API, so you can use it in your application with your favorite technology. You can either have a look at our Content Delivery API and learn how to retrieve one story from there, or you can press the little arrow right next to the Publish button to access the Draft JSON option. Storyblok will open a new tab with the GET request that you can use to access your content. Here is a demo link for you: https://api.storyblok.com/v1/cdn/stories/home?version=draft&token=ask9soUkv02QqbZgmZdeDAtt&cv=1552140823
In that now available content you will be able to see a new object inside the
body field of the
page component. That object will have the field
component with the name
featured_posts (or any name you gave it during the creation step) and a field called
posts that contains the UUIDs of the referenced entries.
We can now follow two approaches to retrieve the post behind that uuid. We can either choose to send another request and retrieve multiple stories by uuids or we can use the
resolve_relations query param that Storyblok has available.
Including the content of referenced posts to the response
Keep in mind that this will alter the default content structure: Objects instead of `UUID` strings. That said it will not be reflected in the `input` Storyblok JS Bridge as it is an API operation and changes the default structure, so disabling the `input` or check for you references being `UUID` strings or objects needs to be done.
resolve_relations parameter is a way the API allows you to define a list of
component_name.field_name pairs that it should try to resolve. Resolving relationship will work with arrays of uuids (as we have from the multi-options field type) or with fields that contain one uuid as a string (the single-option field type for example). So what do we have to pass to the resolve_relation parameter? Let’s have a look at our data structure: the field that contains the array of UUIDs is called
posts and the component that fields belongs to is called
featured_posts so we end up with a parameter like:
resolve_relations=featured_posts.posts. Let’s add that to our request and see how the response will change. Here again is a demo link: https://api.storyblok.com/v1/cdn/stories/home?version=draft&token=ask9soUkv02QqbZgmZdeDAtt&cv=1552140823&resolve_relations=featured_posts.posts
We can now see that we now have the whole object of the referenced content available. That allows us to directly access the fields of that referenced content entry, without having to do another request.
The resolve_relations won’t work on the already resolved entry, so to load categories and author you would need to send another request and extend your content asynchronously.
With the resolve_relations parameter of Storyblok, you can easily include referenced resources to save API requests, even tho we do not charge extra for your API requests this is a quick and easy to use way to save you some time in development. You can use it for featured posts, resolving authors and categories on the post detail page. Maybe reference related or similar products on a product details page without performing another request.