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. 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. Here is the demo link.

    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

    HINT:

    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 but when you make an API request, they are added to the end of the json response.

    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 checking for your 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 field belongs 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. However, the URL can be found here.

    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.

    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.