Quick Start: Using Layouts
Let's take a look at how to use the Layouts Section in Agility to empower your Editors to control their own layouts and the content that lives within them.
We'll go through how to create a Layout, add a Component to it, and then how to access Layouts and Components using the Content Fetch API.
Create a Layout
Layouts 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 Layouts Section and click Add Layout in the top-right.
2. Choose a Layout Model and give the layout a Name. The Layout Path (URL) of the layout will automatically be generated based off the Title field. You can always change the Title afterwards - without changing the Layout Path.
A Layout Model is Required
If you don't have any Layout Models defined, you'll need to create one first. A Layout Model dictates what Zones can be on the Layout.
Add a Component Model
Now that you've created a layout we'll need to add some content to it that can later be retrieved with the Content Fetch API.
If a Layout has no components, it'll have the metadata we need for the layout, 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 layout. This is the content that Editors will enter that will determine what content is presented on your front-end.
3. Fill out any additional information you'd like to include in the SEO or Layout Properties tabs
4. Click Publish
Access the Layout
Now that you have a layout with a component, you can now query the Layout via the Content Fetch API to retrieve the metadata of the Layout as well as the details of each Component that has been added to it.
To retrieve the details of your layout, 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 Layout ID for the layout you want to query, you can retrieve this by clicking on the Properties tab of the Layout
- 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 Layout 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 layouts, 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 (layout) 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 Layout will be shown as a page, 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 (layout) routing.
Now that you know the basics of how to retrieve a sitemap and lookup the details of a layout, 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 Layout 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 layout, lookup the Layout using the Content Fetch API.
- Using the layout 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.