Using relationship resolving to include other content entries

Contents

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

The default 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: featured_posts

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.

create component

Once you’re on the components overview we will create a new component by pressing New on the top right corner.

featured posts

Enter the name featured_posts and press Save on the top right corner to create the new component.

press new

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.

posts field

Next, we will select the field type multi-options by clicking on the Multi-Options symbol.

multi options

To allow the selection of other Stories, we will change the Source of the posts field to Stories.

multi option source

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.

posts path

The last thing we currently need to do with the featured_posts is to save it by pressing Save at the top right corner.

save 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.

home entry

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.

add block

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 whitelist feature of the field in the page content type. As there is no whitelist 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.

click featured posts

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.

featured post selection

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.

featured post and publish

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

open draft json

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.

the content

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.

The 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

the content with resolving

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. An important note here is that the resolve_relations won’t work on the now resolved entry, so to load categories and author you would need to send another request and extend your content asynchronously.

Conclusion

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.


About the author

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 Stahlstadt.js.


More to read...