Agility CMS allows you to link content to other content you have created. This is tremendously useful for building relationships in your content architecture.
The way in which you relate content is facilitated by using Linked Content fields in your Content/Module Definitions. There are a variety of Linked Content field types for different purposes. For example, you may want to create a one-to-one, many-to-one or one-to-many relationships.
Not only is this helpful for Editors in the CMS, but it can also be useful for Developers as they model their content architecture and directly influence what content is returned by the Content Fetch API. The Content Fetch API will automatically resolve linked content references and provide all the associated content in a single API call.
This guide is intended to introduce you to this concept by adding a Linked Content Dropdown field (one-to-one relationship) to an existing Content List and inspecting how that changes our API output.
In this example, we are going to build on the tutorial Creating new Content Types and Fetching Content which covered adding a new list of Post Authors to your Agility CMS instance. If you don't already have a list of Post Authors, create it so you can follow along.
Adding a Linked Content Dropdown List field to the Posts Definition
In order to build our relationship, we need to add a new Number field to store the Content ID of the selected Author. We also need a Linked Content field that will handle the rendering of the dropdown and associated settings. We'll be adding this to our existing Post content definition and point it to our Post Authors list in Shared Content.
Login to Agility CMS.
Navigate to Settings > Content Definitions > Select Post.
In the Edit Content List Definition flyout, select the Form Builder tab, and click the (+) button to add a new field.
In the Field Properties flyout, we need to create our Author ID field. Enter the following values:Field Label = Author ID
Field Name = AuthorID
Description = Stores the Content ID of the selected item from the Author Linked Content field.
Hide Field from Input Form = True (checked)
Field Type = Number
Click Save & New to apply the Author ID field and create a new field.
In the Field Properties flyout, we need to create the Author Linked Content Field. Enter the following values:Field Label = Author
Field Name = Author
Description = Allows editors to associate this post to an author in the Post Authors list
For Field Type, click to open the dropdown and select Linked Content.
Once you have select Linked Content, you'll notice there are now additional fields that appear under Field Properties.
Content Definition specifies which content definition should be used for this linked content reference. We know that we want to relate the Posts to an author. Select Author.
The Content View property will determine exactly how this Content Definition is used in relation to the field.New Content
Selecting New Content will result in a new Content List being created automatically based on the Content Definition with an auto-generated Reference Name and would link this field to that list. This is useful for situations where you want to create a content item and then have a list of one or many items that are ONLY associated with that content item and not accessible to any other content. If we wanted to have a list of media slides only associated with this Post, this might be a good solution. For our case, you do not want editors to be creating different lists of Authors for each Post, so we will not select this option for our use case.
Selecting User Selectable will allow editors to manually select which list of authors (content lists available in Shared Content based on the Author definition) they want to associate this field to. The editor would first select a list (i.e. Post Authors) and then select an Author from that list. Since we want editors to always use the Post Authors list for Posts, this would be a redundant step and we will not select this option for our use case.
Selecting Shared Content allows us to specify exactly which list in Shared Content should be used for this reference for Posts. We want editors to select Authors from our Post Authors list, so this is the perfect option for our use case.
Select Shared Content for the Content View property.
Once you've selected Shared Content as the Content View, you'll notice an additional field appears.
Under Shared Content, click to select the Post Authors list.
Lastly, you need to set the Render As property. This will determine how the Linked Content field is rendered in the input form and how editors can interact with it. Should it just be a shortcut to another list or should an editor be able to select one or perhaps many items from the list? There are several options here so we'll go through each one before making a decision.
A Link rendered field will simply provide a shortcut link for the editor to the associated content list. An editor is unable to select any specific items from the list. We want the editor to interact with the list and select an Author. We will not choose this option for our use case.
A Grid rendered field will embed the associated content list within the input form and is generally more useful than a standard Link type because the editor can jump to a specific item in the list (to manage content) and can even optionally adjust the sort order of the items and have it specific to this content item. The editor is unable to select any specific item from the list and associate it to the current content item. We want the editor to interact with the list and select a single Author. We will not choose this option for our use case.
A Checkboxlist rendered field will display a list of checkboxes for each item in the associated content list and allow the editor to select one or many items from the list. An example use case for this would be if we wanted to associate this Post to one or many Categories. For our case, you wouldn't have more than one Author associated to a Post so it's not the best fit for us. We will not choose this option for our use case.
A Searchlistbox rendered field will display a search input field and allow editors to search for items in the associated list and select one or many items from it. An example use case for this would be if we wanted to associate this Post to one or many other Posts. Since our list of Posts could grow to be quite large (i.e. > 100), we wouldn't want to use a Checkbox List and have it render over 100 checkboxes in our input form. If your list can grow quite large and you need to allow the editor to select one or more than a Searchlistbox field is recommended. For our case, you wouldn't have more than one Author associated to a Post so it's not the best fit for us. We will not choose this option for our use case.
A Dropdown List rendered field will display a dropdown with an option for each item in the associated content list and only allow the editor to select a single item. This is perfect for our use case for displaying a dropdown for our available Post Authors. We will select this option.
Select Dropdown List for the Render As property.
Once you've selected Dropdown List for the Render As property, you'll notice there are now some additional fields displaying that need to be filled out.
For our use case, we just need to set the Save Value to Field property - this will instruct the field to save the selected item's Content ID to another field on our definition. In our case, we want to use the Author ID field we had previously created.
For Save Value To Field, select the Author ID field.
Confirm your settings for your Author linked content field.
On the Field Properties flyout for Author Click Save & Close to apply the new linked content field.
When creating new fields, it's important to re-evaluate the order of the fields that the editor will see in the input form. In our case, the Author linked content field is displaying last (Author ID is hidden, so it won't be displayed at all). Logically speaking, setting the Author is probably the first thing an editor will do when they start writing a new Post.
Let's move the Author field above the Image field, but below the Title field so it's second in the order of fields.
You can do this by clicking-to-drag on the Author field and dragging it underneath the Title field. You can also do the same for the Author ID field just to keep them together.
On the Edit Content List Definition flyout, click Save & Close to apply and save the changes to the Post definition.
Using the Dropdown List Linked Content Field
Now that we've added this field, we'll need to go back to our existing Posts content list and set some content for the new Author field.
Navigate to Shared Content > Select Posts > Select an existing item.
Click the dropdown to select an item from your Post Authors list.
Click Publish to save and publish your latest change.
Fetching Content and it's Linked Content using the Content Fetch API
Now that we've added our Author linked content field to our Posts, we can retrieve the associated author details along with the post when retrieving it via the Content Fetch API.
To illustrate this, let's use a curl command.
Uh-oh, what happened here? We got our author object back, but it only contains a contentID property and not the actual name of the Author.
This occurred because the method Get Content Item has a default contentLinkDepth of 0. This means that it will not resolve any linked content references on the requested item.
To solve this problem, we simply need to set a contentLinkDepth value of at least 1. Let's try this again.
There we go, we now have all the data we need for this Post in a single API call!
Note: We are currently evaluating what the default contentLinkDepth should be and we may change this so it defaults to at least 1 as opposed to 0.