Quick Start: Using Pages
Let's take a look at how to use the Pages Section in Agility to empower your Editors to control their own pages and the content that lives within them.
We'll go through how to create a Page, add a Component to it, and then how to access Pages and Components 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, and what front-end components (Component Models) will be displayed on the page.
1. To start, head to the Pages Section and click Add Page in the top-right.
2. Choose a Page Model and give the page a Name. 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 Model is Required
If you don't have any Page Models defined, you'll need to create one first. A Page Model dictates what Zones can be on the Page.
Add a Component
Now that you've created a page we'll need to add some content to it that can later be retrieved with the Content Fetch API.
If a Page has no components, it'll have the metadata we need for the page, but won't have any actual content.
1. Click + Add Component which will automatically pop-out the available components on the right-hand side.
2. Drag and Drop any Components you'd like to add to the page and then hit Done.
3. Fill out any additional information you'd like to include in the SEO or Page Properties tabs
4. Click Publish
Access the Page
Now that you have a page with a component, 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 Component that has been added to it.
To retrieve the details of your page, you'll first need to gather some information to authenticate and request the 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, 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 Properties 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 a dictionary of Components (Page Modules and their fields) ordered by what Zone they should be rendered in.
Access the Sitemap
To retrieve the sitemap of our pages, we'll need to gather some info again to authenticate and request the 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, 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 lowercase
- 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.
It's important to note here that the call is still temporarily using our old terminology. A Component as a Module, etc.
Next Steps for Development
Agility recommends using our supported framework SDKs, starters, and examples to help you implement page routing.
Now that you know the basics of how to retrieve a sitemap and lookup the details of a page, you can implement logic in your website to do the following:
- Lookup the Sitemap from Agility using the Content Fetch API.
- Check the incoming URL requested and see if that matches a Page in Agility.
- If it doesn't match, return a 404 or fallback to any custom/static routes you may have in your site.
- If it does match a page, lookup the Page using the Content Fetch API.
- Using the page returned from the API, set the appropriate
<head>content using the Title and SEO fields. - Loop through each Component that is in the Zone object and match that with some logic that will render an HTML template for each one.