examples/cms-agilitycms/README.md
This example showcases Next.js's Static Generation feature using Agility CMS as the data source.
IMPORTANT- This example uses Agility CMS's Page Management features. This means that the CMS ultimately drives what pages are available and what content is on each page. This enables Editors to focus on managing their pages, while allowing you, (the Developer) to focus on building UI components for the editors to compose their pages.
Once you have access to the environment variables you'll need, deploy the example using Vercel.
Execute create-next-app with npm, Yarn, or pnpm to bootstrap the example:
npx create-next-app --example cms-agilitycms cms-agilitycms-app
yarn create next-app --example cms-agilitycms cms-agilitycms-app
pnpm create next-app --example cms-agilitycms cms-agilitycms-app
The key principle behind Agility CMS is that Editors should have full control of their pages and what content is on each page without getting into code.
This means you'll not only be defining Content for your Posts and Authors, but you'll also be defining UI Components to compose your pages. This site will consist of a single Page Template and a collection of Modules that represent the UI components you see on the page.
NOTE -
ModulesandPage Templatesin Agility CMS simply correspond toReact Componentsin your website.
Once you've gone through the steps below, you'll be able to dynamically manage pages (and what is on them) directly through the CMS without requiring a developer.
Agility CMSFirst, create an account on Agility CMS.
After creating an account you'll be asked to create a new project. Use any name of your liking as the Project Name and select the Blank (advanced users) template to create a blank Agility CMS instance.
To create an Author Content Definition in the Agility CMS Content Manager, follow these steps:
Name: Set the Field Label to "Name" and the Field Type to "Text".Picture: Set the Field Label to "Picture" and the Field Type to "Image".By following these steps, you will be able to define an Author Content Definition in the Agility CMS Content Manager.
List based on your Author Content DefinitionFrom within the Agility CMS Content Manager, navigate to Shared Content and click the + (New) button, then fill the form like so:
Content ListPost Content DefinitionFrom within the Agility CMS Content Manager, navigate to Settings > Content Definitions and click New to create a new Content Definition.
Post.Next, add these fields via the Form Builder tab (you don't have to modify any other settings):
Title - Set Field Type to TextSlug - Set Field Type to TextDate - Set Field Type to Date/TimeAuthorID - Set Field Type to Number and enable Hide field from input formAuthor - Do the following:
Linked ContentAuthorShared ContentAuthorsDropdown ListAuthorIDExcerpt - Set Field Type to TextContent - Set Field Type to HTMLCover Image - Set Field Type to ImageWhen you are done, click Save & Close to save your Post content definition.
Dynamic Page List based on your Posts Content DefinitionFrom within the Agility CMS Content Manager, navigate to Shared Content and click the + (New) button, then fill the form like so:
Dynamic Page ListPostPosts. This will also pre-populate Reference Name for youGo to Shared Content, select the Authors list and click the + New button to create a new content item:
Click on Save and Publish once you're done.
Next, select the Posts list and click the + New button to create a new content item:
For each post content item, you need to click Publish after saving. If not, the post will be in the Staging state.
Intro ModuleNavigate to Settings > Module Definitions and click New to create a new Module Definition.
IntroDisplays an intro message.In this case, we are not adding any fields to control the output or behavior, since the content is actually hard-coded in the template.
Click Save & Close to save the definition.
Hero Post ModuleNavigate to Settings > Module Definitions and click New to create a new Module Definition.
Hero PostDisplays the latest Post.In this case, we are not adding any fields to control the output or behavior, since the latest post will be used by default and all of the data is associated to the post itself.
Click Save & Close to save the definition.
More Stories ModuleNavigate to Settings > Module Definitions and click New to create a new Module Definition.
More StoriesDisplays a listing of Posts.Next, add the following field:
Title - Set Field Type to TextClick Save & Close to save the definition.
Post Details ModuleNavigate to Settings > Module Definitions and click New to create a new Module Definition.
Post DetailsDisplays the details of a Post.In this case, we are not adding any fields to control the output or behavior, since the data is associated to the post itself.
Click Save & Close to save the definition.
One Column Page TemplateNavigate to Settings > Page Templates and click New to create a new Page Template.
One Column TemplateWebsite+ (New)
Main Content Zone, it will populate Reference Name for youSave to apply the Main Content ZoneClick Save & Close to save the page template.
homeNavigate to Pages and click the + (New) button in the page tree to create a new Page.
PageOne Column TemplateHome - Page Title and Page Name fields will be auto-populated.Click Save to create the /home page.
Next, let's add the Intro, Hero Post and More Stories modules to the Main Content Zone of the home page:
Click the + (New) button on Main Content Zone and select Intro to add the module to the page
Click Save & Close on the module to return back to the page
Click the + (New) button on Main Content Zone and select Hero Post to add the module to the page
Click Save & Close on the module to return back to the page
Click the + (New) button on Main Content Zone and select More Stories to add the module to the page
More StoriesClick Save & Close on the module to return back to the page
Then click Publish on the page in order to publish the page and all of its modules.
postsNavigate to Pages and click the Website channel, then click the + (New) button in the page tree to create a new Folder in the root of the site:
FolderPosts, Folder Name will be auto-populated to postsClick Save to create the /posts folder.
Important: Click Publish on the folder.
posts-dynamicNavigate to Pages and select the existing /posts folder. Click the + (New) button in the page tree to create a new Dynamic Page underneath the posts page.
Dynamic PageOne Column TemplatePostsposts-dynamic##Slug####Title##Click Save to create the /posts/posts-dynamic dynamic page.
Next, let's add the Post Details and More Stories modules to the Main Content Zone of the posts-dynamic page:
Main Content Zone and select Post Details to add the module to the pageMain Content Zone and select More Stories to add the module to the page
More Storiesposts-dynamic pageThen click Publish on the page in order to publish the page and all of its modules.
Copy the .env.local.example file in this directory to .env.local (which will be ignored by Git):
cp .env.local.example .env.local
Go to the Getting Started section from the menu and click on API Keys. You should see a new modal called Content API Details, then click in the Show API Key(s) button within it.
Then set each variable on .env.local:
AGILITY_CMS_GUID should be the Instance GUID fieldAGILITY_CMS_API_FETCH_KEY should be the Live API Key fieldAGILITY_CMS_API_PREVIEW_KEY should be the Preview API Key field - this is used when the site is in Preview Mode and allows your site to pull the latest content, regardless of whether it is published or not.AGILITY_CMS_SECURITY_KEY should be the Security Key field that can be found in Settings > Global Security - this is used to communicate between the CMS and your site to validate Preview ModeYour .env.local file should look like this:
AGILITY_CMS_GUID=...
AGILITY_CMS_API_FETCH_KEY=...
AGILITY_CMS_API_PREVIEW_KEY=...
AGILITY_CMS_SECURITY_KEY=...
npm install
npm run dev
# or
yarn install
yarn dev
Your blog should be up and running on http://localhost:3000! If it doesn't work, post on GitHub discussions.
You can deploy this app to the cloud with Vercel (Documentation).
To deploy your local project to Vercel, push it to GitHub/GitLab/Bitbucket and import to Vercel.
Important: When you import your project on Vercel, make sure to click on Environment Variables and set them to match your .env.local file.
Alternatively, you can deploy using our template by clicking on the Deploy button below.
Now that you've deployed your app to Vercel, take note of the URL of your deployed site. This will be registered in Agility CMS so that when editors click the Preview button within Agility CMS, your app is loaded in Preview Mode. Learn more about Next.js Preview Mode).
To enable the Preview Mode, you'll need to add your site to Domain Configuration in Agility CMS:
WebsiteProductionhttps://<your-vercel-domain>.vercel.appGo to one of your Posts and update the title. For example, you can add [Staging] in front of the title. Click Save, but DO NOT click Publish. By doing this, the post will be in the staging state.
To enter Preview Mode, click the Preview button on the details of your Post. This redirects you to the / page, however you will now be in Preview Mode so you can navigate to your Post you want to view on the website.
You should now be able to see the updated title. To exit the preview mode, you can click Click here to exit preview mode at the top.
NOTE - To set up preview on a specific
Post(as opposed to the/page), click on the Settings tab of thePostlist in Shared Content. For Item Preview Page set it to~/posts/posts-dynamicand for Item Preview Query String Parameter set it tocontentid.