Content Relationships using Linked Content - The Searchlistbox Field

This guide is intended to introduce you to the Linked Content Searchlistbox field. It assumes that you have some basic knowledge about Linked Content.

It builds on what we learned in the Intro to Content Relationships using Linked Content - The Dropdown List Field guide, where we added an Author Linked Content Dropdown field to our Post definition.

In this example, we are going to further extend our Post definition to allow editors to associate a Posts with other Posts (one-to-many). This can be helpful for displaying things like related articles.

Why a Searchlistbox?

If you need to provide a way for editors to associate an item with at least one or more other specific items from a list, then you'll need to use either a Checkbox List or a Searchlistbox field. A Checkboxlist field works great when displaying a finite number of items to select from, however, what happens when your list of items grows very large? You wouldn't want hundreds of items displaying on the input form. A solution to this is to use a Searchlistbox field.

Benefits of a Searchboxlist

  • You can sort items - with the Searchlistbox, you can adjust the order of your selected items, you cannot do this with a Checkbox List

  • More performant - the input form doesn't have to render all items from the list

  • Easier to find items - editors can search for content and use auto-complete suggestions to find the items they want to select

Adding a Linked Content Searchlistbox field to the Posts Definition

In order to build our relationship, we need to add a new Text field to store a comma-separated list of Content IDs for the selected Posts. We also need a Linked Content field that will handle the rendering of the searchlistbox and associated settings. We'll be adding this to our existing Post content definition and point it to the Posts list in Shared Content.

  1. Login to Agility CMS.

  2. Navigate to Settings > Content Definitions > Select Post.

  3. In the Edit Content List Definition flyout, select the Form Builder tab, and click the (+) button to add a new field. 

  4. n the Field Properties flyout, we need to create our Related Posts IDs field. Enter the following values:

    Field Label = Related Posts IDs
    Field Name = RelatedPostsIDs
    Description = Stores the Content IDs in a comma-separated format for of the selected related posts.
    Hide Field from Input Form = True (checked)
    Field Type = Text

  5. Click Save & New to apply the Related Posts IDs field and create a new field.

  6. In the Field Properties flyout, we need to create the Related Posts Linked Content Field. Enter the following values:

    Field Label = Related Posts
    Field Name = RelatedPosts
    Description = Allows editors to associate this post to other posts in the Posts list.

  7. For Field Type, click to open the dropdown and select Linked Content.

  8. Once you have select Linked Content, you'll notice there are now additional fields that appear under Field Properties.

  9. Content Definition specifies which content definition should be used for this linked content reference. We know that we want to relate the Posts to other Posts. Select Post.

  10. The Content View property will determine exactly how this Content Definition is used in relation to the field.

    Shared Content
    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 Posts from our Posts list, so this is the perfect option for our use case.

    Select Shared Content for the Content View property.

  11.  Once you've selected Shared Content as the Content View, you'll notice an additional field appears - prompting you to select which list in Shared Content. Select Posts.

  12. Lastly, you need to set the Render As property. This will determine how the Linked Content field is rendered in the input form.

    We've already determined that we want to use a Searchlistbox field over a Checkbox List, so select Searchlistbox.
  13. Once you've selected Searchlistbox 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 items' Content IDs to another field on our definition. In our case, we want to use the Related Posts IDs field we had previously created.

  14. For Save Value To Field, select the Related Posts IDs field.

  15. Confirm your settings for the Related Posts linked content field.

  16. On the Field Properties flyout for Related Posts Click Save & Close to apply the new linked content field.

  17. On the Edit Content List Definition flyout, click Save & Close to apply and save the changes to the Post definition.

Using the Searchlistbox 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 Related Posts field.

  1. Navigate to Shared Content > Select Posts > Select an existing item.

  2. Click into the Related Posts field and start type-in at least three characters in order to search and show auto-complete suggestions from your Posts list.


  3. Click to select an item.

  4. Continue typing to search for another item to select.

  5. Click and drag selected items to re-order them.

  6. Click Save and then click Publish to make your changes live.

Fetching Content and it's Linked Content using the Content Fetch API

Now that we've added our Related Posts linked content field to our Posts, when we call the Content Fetch API to get a Post, the details for each related post can be returned in the same API call.

To illustrate this, let's use a curl command.

Note that we've set the contentLinkDepth parameter to 1, ensuring that our linked content is automatically resolved, but only one level deep. If you were to set the contentLinkDepth parameter to 2, that would result in the API resolving linked content for both this Post's related posts and their related posts. This would be redundant and should be avoided.

0 out of 0 found this helpful



Please sign in to leave a comment.