Resolve linked content

Jan Cerman

10 minutes

0% complete

When your content creators build pages by linking content items together, your app needs to know how to get all these individual items and resolve them.

How linked items help you

One of the benefits of using an API-first CMS like Kontent.ai is that your content is all structured and ready to be reused. You can define many elements for a given content item and use different ones in different contexts. For example, you might have a full article with catchy copy and captivating images but only want to use its title and a brief description in a list of articles. When you put your content into various structured items and then link those together to build relationships, you can define what gets used where. Some benefits from having content in separate items:

You can have separate workflows for separate pieces of content. For example, you can have a homepage with many testimonials and have some published and some in other steps.
You can reuse the items, so you only have to edit content once for the changes to appear in many places. For example, you can have an author's bio appear on all the articles they’ve written.
You don’t need to plan exactly what content will be included in each section – you only need to give the opportunity to add linked items. For example, you can have a product listing where you later decide which products will appear and in which order.

With Kontent.ai, you can link content together in two ways:

Using a linked items element you can limit the items, including what types can be included and how many. This way is covered here.
In a rich text element, your items are included within the text, which requires additional work from your app to render them. Read how to deal with structure in your rich text.

This article looks at how to use linked items to add an author with a name and bio to your articles. You might do this if you have an author who is writing multiple articles and wants the chance to edit their bio separately. If you have not yet done so, create at least one author and link it to an article.

Add your relationships to your model

If you're using strongly typed models, you should remember to add your Author model as well as add a linked items element to your Simple Article model.

Retrieve authors with articles

Now, you can retrieve any articles along with their associated authors. When retrieving articles, make sure the depth query parameter is higher than 0 (the default value is 1) so that the authors will be returned. Note that any other filtering or order you do to the article will not affect what items are returned within the Linked items element. The following examples show how to retrieve a single article (named The Origin of Coffee) with its author (a linked item).

If you want to include more than one level of linked items in the response, set the depth query parameter to 2 or more.

JavaScript

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
const KontentDelivery = require('@kontent-ai/delivery-sdk');

const deliveryClient = KontentDelivery.createDeliveryClient({
  environmentId: '8d20758c-d74c-4f59-ae04-ee928c0816b7',
});

const response = await deliveryClient.item('the_origin_of_coffee')
  .depthParameter(1)
  .toPromise();

In the default JSON response, the codename for your author (jane in our example) appears in the value of your author element. If you have multiple authors, they would appear in the same order in the author element as they do in the UI. Jane's name and bio appear in the modular_content collection under her codename. To use Jane within your article, you need to match the codename from the author element with the values you want to use from the jane collection.

JSON

{
  "item": {
    "system": {
      "id": "4735c956-4be4-482c-b874-bba201a22f44",
      "name": "The Origin of Coffee",
      "codename": "the_origin_of_coffee",
      "language": "en-US",
      "type": "simple_article",
      "sitemap_locations": [],
      "last_modified": "2020-02-03T12:36:02.7767984Z"
    },
    "elements": {
      "title": {
        "type": "text",
        "name": "Title",
        "value": "The Origin of Coffee"
      },
      "author": {
        "type": "modular_content",
        "name": "Author",
        "value": [
          "jane_doe"
        ]
      }
    }
  },
  "modular_content": {
    "jane_doe": {
      "system": {
        "id": "3bf1c09b-4552-4e2c-8de5-ffce79f773e0",
        "name": "Jane Doe",
        "codename": "jane_doe",
        "language": "en-US",
        "type": "author",
        "sitemap_locations": [],
        "last_modified": "2020-02-03T12:30:14.641708Z"
      },
      "elements": {
        # Omitted for brevity
        }
      }
    }
  }
}

Retrieve subpages

When using Web Spotlight to manage your website content, you can retrieve subpages the same way as your linked items.The following example shows how to retrieve a single page (Insurance listing) with its subpages (travel, car, and health insurance). Both the Insurance listing page and its subpages are of the Page type.

If you're using strongly typed models, you should remember to add a subpages element to your Page model.

Sign in with your Kontent.ai credentials or sign up for free to unlock the full lesson, track your progress, and access exclusive expert insights and tips!