Content Models

Content Models are the most important aspect of the Content First approach. You want to think about your content without fixating on where it is going or how it will be used. Make it reusable, flexible, and easy to manage. You first define your content by creating fields, then you can create relationships between other content.

Once you've defined your content model, you can initialize content based off that model.

Having your Content Models correctly set up within Agility CMS allows editors to make updates and publish this content with ease, across all your digital products.

Content Models in Agility CMS

Benefits of Content Models

  1. Not Just for Developers: Customize your content models right in the CMS using our visual builder.
  2. Optimize your Editors Experience: Group fields together, set required fields, default values and much more.
  3. Future Proof your Content: Define structured content that is de-coupled from your presentation layer.
  4. Evolve your Content Model Over Time: Seamlessly switch from editing content to your content models to allow for quick updates.
  5. Flexible: A content model can be re-used for various types of content.

How Content Models Work

The Content Model is just a structure of content, it does not represent an instance of content in itself. This allows you to define a model, then re-use it for various types of content.

A typical workflow with Content Models looks like:

  1. Create a new Content Model.
  2. Add fields to the Content Model.
  3. Initialize a content list based off the model - which will appear in the Content (area) for editors.
  4. Or, use newly created content model as child linked content in another Content Model or Page Module.
  5. Editors create content items within the content list and publish them.
  6. Developers call the Content Fetch API using the reference name of the initialized content list to return the content as JSON.

Field Types

A Content Model can have a variety of field types. Both Content Models and Page Modules share the same availability of field types.

Learn more about the types fields that are available..  

Example

The Content Model that defines an Author for a Blog Post may look something like:

Name => [Text]

Birthdate => [Date]

Profile Image => [Image]

The Author content model on agilitycms.com

Then, the content model is used to initialize a list of Authors which is accessible from the Content (area).

Content based off the Model in Agility CMS

The above figure shows the list called Authors that is based off the Author content model.

Content that has been initialized in Agility CMS

The above figure shows the Authors list is accessible in the Content (area) for editors to manage.

It can also be linked to from the Blog Post content model via an Author field so that editors can select an Author from the list to associate to their Blog Post.

How you can use linked content fields to relate an Author to a Blog Post in Agility CMS

The above figure shows how you can use a linked content field to associate a Blog Post to an Author.

Editors can now select an Author to relate to their Blog Post in Agility CMS

Editors can now select an Author to relate to their Blog Post within the Blog Post input form.

Creating new Content Model and Fetching Content

Creating a Content Model

When creating a content list or item, you need to have a Content Model that represents your content schema first. This allows you to create multiple lists/items from the same Content Model. For example, you may have more than one list of Blog Posts or types of Authors.

Step One: Login to Agility CMS.

Step Two: Go to Models > Content Models > Click "+ Add".

Creating a content model in Agility CMS

Step Three: In the New Content Model flyout, enter a Name (the Reference Name field will auto-populate), set a Description (optional), and click "Save". For example let the name be "myFirstModel"

Setting a description for Agility CMS content models

Step Four: Next, click the "+ Add a Field" button to create a new field.

Adding a content model field in Agility CMS

Step Five: In the Field Properties flyout, enter the name and type. For example a field name of "title" and a type of "text"

Entering name and type for Agility CMS content models 

Step Six: Click "Add Field" to apply the new field.

Click "add field" to apply Agility CMS content model field 

Step Seven: Click "Save" to finish creating the Content Model.

Initialize a new List in Content

Now that you've created the definition, we can now create lists based on that definition (Author).

Step One: Login to Agility CMS

Step Two: Navigate to Models > Content Models > Select a Content Model > Click "+" under "Content Using This Model"

Creating a new list in Agility CMS

Step Three: Enter Name. For example "myFirstList"

Example of a list in Agility CMS

Step Four: Click "Create Content".

Create Content Items in the List

Now that you have created the list, you can start creating content items inside it. Let's create one or two authors so we can query the API later and fetch your content.

Step One: Login to Agility CMS.

Step Two: Navigate to Content > Select a content list > and click the (+ New) button to open a stack panel to create a new content item.

Creating content items in an Agility CMS list 

Step Three: Enter some values for the fields. For example enter "myFirstTitle" in the title field.

Entering values in list field with Agility CMS 

Step Four: Click Publish to publish the content item and make it available to our live Content Fetch API. When publishing content in the CMS, you'll notice the status bar on the item turn from grey (Staging) to blue (Processing) to green (Published) when it is available to be consumed via the API.

Accessing the Content using the Content Fetch API

Now that we've created a new content model, created a new list and populated it with some content, we are ready to request the content from the API.

When using the Content Fetch API, you can make a direct HTTP request to the REST service or use an SDK in your favorite programming language to simplify making requests.

Step One: You need to know what the Reference Name for your list is, that is the required parameter in order to retrieve all content items in a list. *** It's important to note that ALL reference names MUST be lowercased when using the REST API. If you don't know your Reference Name, you can retrieve this from Agility CMS by navigating to Content > Select a List > Click the Settings tab > Note the Reference Name property.

Accessing content in Agility CMS with API

Your Content Model is the way that the content (ie: text, lists, images videos, etc.) is set up within Agility CMS, allowing editors to make updates and publish this content with ease, across all your digital products.

Step Two: In this example, we'll use a simple curl command to illustrate how to access the content we just created.


curl https://api.glty.io/046a1a87/fetch/en-us/list/myfirstlist 
 --header "APIKey: defaultlive.2b7f3a91559d794bedb688358be5e13af2b1e3ae8cd39e8ed2433bbef5d8d6ac"

Step Three: The response returned from the API is shown below.

{
  "items": [
    {
      "contentID": 25,
      "properties": {
        "state": 2,
        "modified": "2019-08-14T13:07:25.99",
        "versionID": 142,
        "referenceName": "myfirstlist",
        "definitionName": "myFirstModel",
        "itemOrder": 0
      },
      "fields": {
        "title": "myFirstTitle"
      },
      "seo": null
    }
  ],
  "totalCount": 1
}

Intro to Content Relationships using Linked Content - The Dropdown List Field

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.

Adding a Linked Content Dropdown List field to the Posts Model

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.

Step One: Login to Agility CMS.

Step Two: Navigate to Models > Content Models > Select Post.

Step Three: Next, click the "+ Add a Field" button to create a new field.

Step Four: 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

Step Five: Click "Add Field" to apply the Author ID field, then create a new field.

Step Six: 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

Step Seven: For Field Type, select Linked Content.

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

Step Nine: 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.

Step Ten: The "Link To" property will determine exactly how this Content Definition is used in relation to the field.

Step Eleven: Once you've selected "Content" as the "Link To", you'll notice an additional field appears.

Step Twelve: 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.

Step Thirteen: 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.

Step Fourteen: For Save Value To Field, select the Author ID field.

Step Fifteen: Confirm your settings for your Author linked content field.

Step Sixteen: On the Field Properties flyout for Author Click Add Field to apply the new linked content field.

Step Seventeen: 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.

Step Eighteen: On the Edit Content List Definition flyout, click Save 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.

Step One: Navigate to Content > Select Posts > Select an existing item.

Step Two: Click the dropdown to select an item from your Post Authors list.

Step Three: Click publish to save and publish your latest changes.

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

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.

curl https://api.aglty.io/046a1a87/fetch/en-us/item/15 
--header "APIKey: defaultlive.2b7f3a91559d794bedb688358be5e13af2b1e3ae8cd39e8ed2433bbef5d8d6ac"
{
  "contentID": 15,
  "properties": {
    "state": 2,
    "modified": "2019-08-14T17:11:15.22",
    "versionID": 159,
    "referenceName": "posts",
    "definitionName": "Post",
    "itemOrder": 0
  },
  "fields": {
    "title": "How this site works!",
    "author": { "contentid": 25 },
    "authorID": "25",
    "details": "<p>Here is some dummy content for the post details...</p>"
  }
}

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.

curl https://api.aglty.io/046a1a87/fetch/en-us/item/15?contentLinkDepth=1  
--header "APIKey: defaultlive.2b7f3a91559d794bedb688358be5e13af2b1e3ae8cd39e8ed2433bbef5d8d6ac"
{
  "contentID": 15,
  "properties": {
    "state": 2,
    "modified": "2019-08-14T17:11:15.22",
    "versionID": 159,
    "referenceName": "posts",
    "definitionName": "Post",
    "itemOrder": 0
  },
  "fields": {
    "title": "How this site works!",
    "author": {
      "contentID": 25,
      "properties": {
        "state": 2,
        "modified": "2019-08-14T13:07:25.99",
        "versionID": 142,
        "referenceName": "postauthors",
        "definitionName": "Author",
        "itemOrder": 0
      },
      "fields": {
        "name": "James Vidler",
        "image": {
          "label": null,
          "url": "https://046a1a87-cdn.agilitycms.cloud/Attachments/NewItems/P6150353_small_20190814170433_0.jpg",
          "target": null,
          "filesize": 26738,
          "pixelHeight": "433",
          "pixelWidth": "577",
          "height": 433,
          "width": 577
        }
      }
    },
    "authorID": "25",
    "details": "<p>Here is some dummy content for the post details...</p>"
  }
}

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.

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.

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

One: You can sort items-with the searchlistbox, you can adjust the order for your selected items, you cannot do this with a CheckboxList

Two: More performant - the input form doesnt have to render all the items from the list

Three: 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.

Step One: Login to Agility CMS

Step Two: Navigate to Settings > Content Definitions > Select Post

Step Three: In the Edit Content List model flyout, and click the Add Field button to add a new field.

Step Four: In 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  

Step Five: Click Add Field to apply the related Posts IDs field and create a new field

Step Six: In the field properties flyout, we need to create the Related Posts Linked Content Field Properties

Step Seven: For Field Type, click to open the dropdown and select Linked Content

Step Eight: Once you have selected linked content, you'll notice there are now additional fields that appear under field properties.

Step Nine: content model specifies which content model should be used for this linked content reference. We know that we want to relate the Posts to other Posts. Select Post.

Step Ten: The Link To property will determine exactly how this content model is used in relation to the field

Step Eleven: Once you've selected content as the Link To, you'll notice an additional field appears - prompting you to select which list in shared content. Select Posts

Step Twelve: Lastly, you need to set the render UI a property. This will determine how the linked content field is rendered in the input form.

Step Thirteen: Once you've selected Searchlistbox for the Render UI property, you'll notice there are now some additional fields displaying that need to be filled out.

Step Fourteen: Confirm your settings for the related posts ids field

Step Fifteen: On the field properties flyout for related posts click add field to apply the new linked content field

Step Seventeen: On the edit content list definition flyout, click save to apply and save the changes to the post definition.

Using the&nbsp;Searchlistbox Linked Content Field

Step One: Navigate to Content > Select Posts > Select an existing item.

Step Two: 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.

Step Three: Click to select an item.

Step Four: Continue typing to search for another item to select.

b: Click and drag selected items to re-order them.

Step Six: 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.

curl https://api.aglty.io/046a1a87/fetch/en-us/item/15?contentLinkDepth=1 
--header "APIKey: defaultlive.2b7f3a91559d794bedb688358be5e13af2b1e3ae8cd39e8ed2433bbef5d8d6ac"
{
  "contentID": 15,
  "properties": {
    "state": 2,
    "modified": "2019-08-15T16:22:34.45",
    "versionID": 165,
    "referenceName": "posts",
    "definitionName": "Post",
    "itemOrder": 0
  },
  "fields": {
    "title": "How this site works!",
    "author": {
      "contentID": 25,
      "properties": {
        "state": 2,
        "modified": "2019-08-14T13:07:25.99",
        "versionID": 142,
        "referenceName": "postauthors",
        "definitionName": "Author",
        "itemOrder": 0
      },
      "fields": {
        "name": "James Vidler",
        "image": {
          "label": null,
          "url": "https://046a1a87-cdn.agilitycms.cloud/Attachments/NewItems/P6150353_small_20190814170433_0.jpg",
          "target": null,
          "filesize": 26738,
          "pixelHeight": "433",
          "pixelWidth": "577",
          "height": 433,
          "width": 577
        }
      }
    },
    "authorID": "25",
    "details": "<p>Here is some dummy content for the post details...</p>",
    "relatedPostsIDs": "27,16",
    "relatedPosts": [
      {
        "contentID": 16,
        "properties": {
          "state": 2,
          "modified": "2019-08-15T16:28:01.053",
          "versionID": 167,
          "referenceName": "posts",
          "definitionName": "Post",
          "itemOrder": 1
        },
        "fields": {
          "title": "How to handle SEO with a JS app",
          "image": {
            "label": null,
            "url": "https://046a1a87-cdn.agilitycms.cloud/Attachments/NewItems/jamstack-acronym_20190326190136_0.png",
            "target": null,
            "filesize": 67338,
            "pixelHeight": "660",
            "pixelWidth": "966",
            "height": 660,
            "width": 966
          },
          "details": "<p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.</p>"
        },
        "seo": null
      },
      {
        "contentID": 27,
        "properties": {
          "state": 2,
          "modified": "2019-08-14T17:12:07.21",
          "versionID": 161,
          "referenceName": "posts",
          "definitionName": "Post",
          "itemOrder": 2
        },
        "fields": {
          "title": "Sample post",
          "author": { "contentid": 26 },
          "authorID": "26",
          "details": "<p>Sample content for sample post</p>"
        },
        "seo": null
      }
    ]
  }
}

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.

Updating a Linked Content Reference on Existing Content

The Reference Name of the Linked Content list is actually stored on the main/parent content item itself as a string.

When you create content items, a copy of that Reference Name is stored on the content item. If you later change the Linked Content property for that definition to point to another item/list then the old Reference Name will still be saved on each previous version of the content items. Any new content items you create will get the new Reference Names.

This can cause unintended consequences in your code where depending on which content item is accessed, you may get a different linked content reference.

A similar problem can occur if you add a new linked content property - by default, any existing content item will have a NULL value for that new property until you update the existing content item in the Content Manager.

Workarounds

If you are stuck in this state, there are a few things you can do to update the linked content references on the older content items:

  1. You can temporarily change the type of the Content Definition to a Text field and manually update the value to the Reference Name of the list/item you'd like to reference. Once you're done, change it back to a linked content list.
  2. Use the Export/Import functionality in Agility to update the previous items' linked content reference value.
  3. Use the Content Import API to update these values programmatically.

Future Considerations

Agility is looking at how we can make this more transparent so that developers understand, within the CMS, the consequences of updating a linked content reference value and what tools can be introduced to automate this.