How to include content of referenced stories using resolve relations

Contents
    Try Storyblok

    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

    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

    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 {1} in the left sidebar.

    Storyblok space components
    1
    2

    Storyblok space components

    Once you’re on the components overview we will create a new component by pressing New {2} on the top right corner like the image above.

    featured_posts component
    1

    Storyblok featured_posts component

    Enter the name featured_posts and press Next {1} on the top right corner to create the new component.

    Creating a Storyblok new component

    Creating a Storyblok 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 {1} section and press Add {2}.

    Defining featured_posts components
    1
    2

    Defining featured_posts components

    After that, click on the posts field and in the next modal, click on the select dropdown below Type to select Multi-Options.

    selecting multi-options for featured posts

    selecting multi-options for featured posts

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

    Selecting stories from the source
    1
    2

    Selecting stories from the source

    Once you select Stories {1} as the source, you can now write the path posts/ {2} in the now available Path to folder or stories input located below the dropdown, however, this is optional. You can also restrict to content type option on Storyblok.

    writing posts as the default path

    writing posts as the default 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.

    Using the featured posts component

    We will navigate back to the Content page in our Storyblok space by clicking on Content {1} on the sidebar. Press on the Home {2} 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 {3} 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.

    Using featured posts component
    1
    2
    3

    Using featured posts component

    By default, you will see the quickstart screen showing your draft token and some other useful information you can find here.

    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 {1} in the right sidebar.

    Adding a new block to our application
    1

    Adding a new block to our application

    You will now see a list of nestable components, let’s click on Featured Posts {1} to add it to the content.

    Adding featured posts to the content block
    1

    Adding featured posts to the content block

    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 Posts component

    Featured Posts component

    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 {1} will also save your content, if you would only Save {2} the entry, it will store a draft version, publishing will result in a newly published version. Let’s go ahead and save and publish the entry.

    Save and publish featured posts
    1
    2

    Save and publish featured posts

    The next thing to do is to retrieve the content from our API, so you can use it in your application with your preferred technology. We can do this in two ways, namely:

    • ​​We can make an API call to fetch the home​ story and make another API call to retrieve the feature_posts​ using their UUIDs.

    • We can add a query parameter to our API request stating the relationship we want to resolve. With this approach, we won't have to make two API requests.

    ​​Retrieving referenced post in two steps

    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 (Api V2) option. Storyblok will open a new tab with the GET request that you can use to access your content.

    DEMO LINK:

    A demo link can be found here.

    Home stories draft JSON

    Home stories draft JSON

    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 the resolved relationship will not be included in the content of the home​ story but under the rel​ array below the story​ when using an API request. That said, it will also 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 your references being UUID​ strings or objects need 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 belong to is called featured_posts so we end up with a parameter like resolve_relations=featured_posts.posts. Let’s add that to the end of our request and see how the response will change. 

    The URL should look like this now: https://api.storyblok.com/v2/cdn/stories/home?version=draft&token=iZQea1zPq7vfywVh8tdRxQtt&cv=1642873857&resolve_relations=featured_posts.posts

    Featured posts JSON data

    Featured posts JSON data

    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.

    IMPORTANT:

    If you use the storyblok-js-client and storyblok-bridge the resolved relations (in this case the featured_posts) will be added to the original place of UUIDs as well as in rels but when you use an API request, they are only added to the rels array.

    Resolve relations JSON

    Resolve relations JSON

    Resolving relationship with graphql

    If you use the Storyblok Graphql endpoint in your app, you can also resolve the relationship between content entries using the story id and specifying the relationship as seen below.

    {
      PageItem(id: {STORY_ID}, resolve_relations: {RELATIONSHIP}) {
        id
        content {
          body
          component
        }
      }
    }

    Example:

    {
      PageItem(id: "106765222", resolve_relations: "teaser-first-lvl.rel,teaser-second-lvl.rel") {
        id
        content {
          body
          component
        }
      }
    }

    The result can be seen below.

    Storyblok graphql query

    Storyblok graphql query

    Wrapping Up

    With the resolve_relations parameter of Storyblok, you can easily include referenced resources to save API requests, even though 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.