Quick Start: Using Pages

In this tutorial, we'll go through how to use Pages in Agility CMS to empower your editors to control their own pages and exactly what content is on them.

We'll go through how to create a Page, add a Page Module to it, then show you how to access your pages and their modules using the Content Fetch API.

Create a Page

Pages are a built-in structured content items that allow editors to manage their name, URL, SEO properties, and what frontend components (Page Modules) will be displayed on the page.

Login to Agility CMS and navigate to the Pages (area). Click the Add a Page button on the dashboard.

How to create a page in Agility CMS

Select a Page Template to use and give the page a Title. The Page Path (URL) of the page will automatically be generated based off the Title field. You can always change the Title afterwards - without changing the Page Path.

A Page Template is Required

If you do not have any Page Templates defined, you'll need to create one first. A Page Template dictates what Content Zones can be on the page.

Add a Page Module

Now that you've created a page, we need to add some content to it that can be later retrieved with the API.

If a Page has no page modules, it has all the metadata we need for the page, but won't have any actual content.

All Agility instances come with the built-in Rich Text Area page module, but feel free to add any other Page Module you may already have defined.

Click the + button on the Content Zone or click the Add One Now button.

Adding a module in Agility CMS

Once you've selected a Page Module, you'll be presented with its fields to fill out. This is the content that editors will enter that will determine what content is presented on your frontend.

Content field for editors in Agility CMS

Enter the content and then click Save. Click the Back < arrow to return to your page view.

Returning to page view in Agility CMS

Access the Page

Now that you have a page with a page module, you can now query the Page via the Content Fetch API to retrieve the metadata of the Page as well as the details of each Page Module has been added to it.

To retrieve the details of our page, we'll need to collect some information we'll need to authenticate and request this content.

  • Guid - this is the ID of your instance, you can retrieve this by navigating to API Keys
  • API Key - this is the key you'll use to authenticate with Agility CMS, you can retrieve this by navigating to API Keys
  • API Type - this is the type of API request we are making, valid values are fetch (published content) or preview (returns content that is not published)
  • ID - this is the Page ID for the page you want to query, you can retrieve this by clicking on the Settings tab of the Page
  • Locale - this is the locale code of the content you want to request (i.e. en-us)
curl -X GET "https://api.aglty.io/8fdc8afa-u/preview/en-us/page/3?contentLinkDepth=2" -H  "accept: application/json" -H  "APIKey: defaultpreview.36d9c831f95d7604d2a1bab3f0603a52705b2823a4a14841eddb639133a444a1"
{
  "pageID": 3,
  "name": "about-me",
  "path": null,
  "title": "About Me",
  "menuText": "About Me",
  "pageType": "static",
  "templateName": "One Column Template",
  "redirectUrl": "",
  "securePage": false,
  "excludeFromOutputCache": false,
  "visible": {
    "menu": true,
    "sitemap": true
  },
  "seo": {
    "metaDescription": "",
    "metaKeywords": "",
    "metaHTML": "",
    "menuVisible": null,
    "sitemapVisible": null
  },
  "scripts": {
    "excludedFromGlobal": false,
    "top": null,
    "bottom": null
  },
  "properties": {
    "state": 1,
    "modified": "2021-09-20T15:20:56.493",
    "versionID": 6
  },
  "zones": {
    "MainContentZone": [
      {
        "module": "RichTextArea",
        "item": {
          "contentID": 10,
          "properties": {
            "state": 1,
            "modified": "2021-09-20T15:23:16.143",
            "versionID": 26,
            "referenceName": "aboutme_richtextarea",
            "definitionName": "RichTextArea",
            "itemOrder": 0
          },
          "fields": {
            "textblob": "<p>Hello World 🌎</p>"
          }
        }
      }
    ]
  }
}

As you can see from the response of the page object, we have all the info we need about the page as well as an dictionary of Page Modules (and their fields) ordered by what Content Zone (zone) they should be rendered in. 

Access the Sitemap

As you've learned, you can query a page by its ID, but how would you access a listing of all pages in the CMS? You'll need to access a list of pages in order to implement proper page routing and more.

To retrieve the sitemap of our pages, we'll need to collect some information we'll need to authenticate and request this content.

  • Guid - this is the ID of your instance, you can retrieve this by navigating to API Keys
  • API Key - this is the key you'll use to authenticate with Agility CMS, you can retrieve this by navigating to API Keys
  • API Type - this is the type of API request we are making, valid values are fetch (published content) or preview (returns content that is not published)
  • Channel Name - this is the reference name of your sitemap as its defined in Settings > Sitemaps, this value must be lowercased
  • Locale - this is the locale code of the content you want to request (i.e. en-us)
curl -X GET "https://api.aglty.io/8fdc8afa-u/preview/en-us/sitemap/flat/website" -H  "accept: application/json" -H  "APIKey: defaultpreview.36d9c831f95d7604d2a1bab3f0603a52705b2823a4a14841eddb639133a444a1"
{{
  "/home": {
    "title": "Home",
    "name": "home",
    "pageID": 2,
    "menuText": "Home",
    "visible": {
      "menu": true,
      "sitemap": true
    },
    "path": "/home",
    "redirect": null,
    "isFolder": false
  },
  "/about-me": {
    "title": "About Me",
    "name": "about-me",
    "pageID": 3,
    "menuText": "About Me",
    "visible": {
      "menu": true,
      "sitemap": true
    },
    "path": "/about-me",
    "redirect": null,
    "isFolder": false
  }
}

The response from this API call is a dictionary of all page routes defined in Agility for the sitemap you requested. This format is especially useful for page routing or generating a sitemap.xml file.

Next Steps for Website Development

Agility recommends using our supported framework SDKs, starters, and examples to help you implement page routing. 

Now that you know the basics how to retrieve a sitemap and lookup the details of a page, you can now implement logic in your website to do the following:

  1. Lookup the Sitemap from Agility using the Content Fetch API.
  2. Check the incoming URL requested and see if that matches a Page in Agility.
  3. If it does not match a page, return a 404 or fallback to any custom/static routes you may have in your site.
  4. If it does match a page, lookup the Page using the Content Fetch API.
  5. Using the page returned from the API, set the appropriate <head> content using the Title and SEO fields.
  6. Loop through each Page Module that is in the zone object and match that with some logic that will render an HTML template for each one.