Recap

In Going Headless: A CMS Story, what and why go headless – Part 1 we looked at what a headless CMS is and why you might want to use a headless system. In Going Headless: A CMS & Hosting Tutorial – Part 2 we purchased hosting and installed the CMS with the modules and themes.

If you don’t already have a running CMS and the headless theme ready to install, have a read of Going Headless: A CMS Story, what and why go headless – Part 1 and Going Headless: A CMS & Hosting Tutorial – Part 2 as we’ll go straight from Part 2 and get some content into the system.

Content

You’ll hear it all the time; content is king. And it’s true. You can have an awful website and great content and you’ll attract visitors but have awful content and a great website and you will have no visitors. On that note, we’ll use Lorem ipsum for our content.

Open your CMS in the browser and login.
Go to /admin/content or hit Content on the left.
At the top hit the 'Add content' button
Click 'Basic page'.
Open a new tab in your browser and go to the Lorem ipsum Generator.
At the bottom hit the button 'Generate Lorem Ipsum'.
Select and Copy 4 paragraphs.
Back in your CMS paste in the 4 paragraphs to the body.
In the title add ‘Lorem ipsum’.
Click Save

On the view tab of the new content, you’ll see the content in the CMS View, we will remove this later as our goal is to show the content in the Frontend, not the CMS. You may have also noticed the URL is '/node/1', not great for SEO. Our page also needs a bit of colour and an image that goes with it. While we’re there we'll add a subtitle.

Content Fields

We can fix some of this with fields. Fields are the parts that make up the content for example we have seen title and body fields already and we can add as many of these as we want, so let’s start with Background colour:

Open your CMS in the browser and go to '/admin/structure' or click Structure on the main menu.
Click 'Content types' and choose 'Manage fields' next to 'Basic page'.
Click the 'Create new field' button at the top.
Select Colour and hit the 'Continue' button (if you don’t have Colour you have not installed the module for 'Color Field' module, go back to Going Headless: A CMS & Hosting Tutorial – Part 2 and take a look at the modules section).
In label add 'Background colour' and hit the 'Continue' button.
Click the 'Save settings' button.

We’ve just added a Field to the Basic content, so every time we create or edit Basic content we can choose a background colour. Let’s see what that looks like:

Click Content on the main menu of the CMS or go to '/admin/content'.
Click Edit next to our 'Lorem ipsum' content.

Don’t change anything yet, but you’ll see we have 2 new fields to add colour and opacity. Not exactly what we want though, typing these in is not simple.

Back to Admin -> Structure -> Content types -> Manage fields next to Basic page -> Edit Background colour.
Untick 'Record opacity'
Click the 'Save settings' button.

We’ve removed the opacity field as we don’t need it.

Make sure you are still on Admin -> Structure -> Content types -> Manage Basic page.
Click 'Manage form display' at the top.
This is how we manage what the user sees when they edit content.
Next to Background colour hit the dropdown.
Select 'Color HTML5' (Note the US spelling).

While we are here, we should move the Background colour under the Title.

Click and hold the little arrows on the left and drag Background colour under Title.
Click the 'Save button' at the bottom.
Click Content on the main menu of the CMS or go to '/admin/content'.
Click 'Edit' next to our 'Lorem ipsum' content.
Click the box under Background colour and select a colour (select off the Background colour to deselect).
Hit 'Save' at the top.
Under the title click 'Lorem ipsum' to view.

Again, we can see the content, but now we can see a new background colour with the hex value we can use later.

We’ll add Font colour now:

Go to Admin -> Structure -> Content types -> 'Manage fields' next to 'Basic page'.
Click the 'Create new field' button at the top.
Select 'Colour' and hit the 'Continue' button.
In label add 'Font colour' and hit the 'Continue' button.
Deselect Record opacity and click Save.
Click 'Manage form display' at the top.
Drag Font colour under Title.
Change the dropdown on 'Font colour' to 'Color HTML5'
Click Save at the bottom.

Next, we will add a Subtitle. The main difference here from above is the type, when you create a new field this time, have a look at the different types. Let’s run through it.

Go to Admin -> Structure -> Content types -> 'Manage fields' next to 'Basic page'.
Click the 'Create new field' button at the top.
Select Plain text and hit the 'Continue' button.
In label add 'Subtitle'
Select the option 'Text (plain)' and hit the 'Continue' button.
Click the 'Save settings' button.
Click 'Manage form display' at the top.
Drag 'Subtitle' under 'Title'.
Click the 'Save' at the bottom.

We now have a Subtitle and 2 colours for our content, we will add an image next. Do the same as above, but:

Field to add = File upload
Label = Main image
Option = Image

All other options are default so leave as-is and click 'Save settings' at the bottom.

Now you know how to add new Fields to content types. Some types of content may need different fields e.g. Article (think blog) may want comments and scheduled publish but basic content (think 'About' page) might want a bunch of images as a slideshow or a video.

When you create a wireframe and design your website, you will usually know these fields before you start creating content types.

Menus

We’ve not touched on menus yet, these are simple, so we don’t need to do much. Let’s start by creating a new menu for our articles:

Got to Structure -> Menus -> Add menu
Under Title type ‘Articles’
Save

Our content is not added to any menus by default, we need to change that:

Go to Structure -> Content types -> Manage fields pulldown for Basic page and hit edit.
Click Menu settings (towards the bottom)
Make sure only Main navigation is ticked under Available menus
Make sure Default parent link is set to <main>
Select 'Make the Menu Settings mandatory for this content type'.
Save

Do the same for Article content type, but change 'Available menus' to 'Articles' and the Default parent link to <articles>.

We now have 2 menus we are actively using, so when we create any basic content that contents' link will be added to our main menu with the title automatically. Doing the same with article is fine for this tutorial, but could get unruly, very quickly, if we have lots of articles. It may be a neater option to have a page with all articles, paginated, filtered by tags. We would do all this using Views, but Views are outside the scope of this tutorial.

Links

Our URL is still a problem, it says 'node/x' instead of something to do with the title. We can easily fix this with 'URL aliases':

Click Configuration -> URL aliases.
Click Patterns at the top.
Click the 'Add Pathauto pattern' button at the top.
Select 'Content' as the 'Pattern type' and we see the form change to reflect our change
In 'Path pattern' add 'articles/[node:title]'
Select 'Article' from content type.
Add the Label 'Articles Page Title'
Click Save

Now we have a pattern for the article type, let’s do our Basic page. Same as above with the options:

Path pattern = [node:title]
Select Basic page from content type.
Label = Basic Page Title

What we have done here is create a URL using the title of the page for our basic pages, our articles are all in the '/articles/' url but will still use the title as the URL. This will automatically work for all new content. Let’s check our Lorem ipsum page

Click Admin -> Content
Edit Lorem ipsum

On the right under URL alias, you’ll see No alias because we created this before the pattern.

Click URL alias.
Select ‘Generate automatic URL alias’.
Save

Now when you click view the Lorem ipsum page we see the correct URL '/lorem-ipsum'.

Edit it again and give it the subtitle ‘Maecenas pellentesque, ligula id condimentum cursus, metus orci gravida felis, in bibendum libero sem sit amet’.

Add a main image to the page, you can use any image, but you’ll need to add an alt to describe the image.

If you try to Save the page, you will be asked to add a Menu link title. This will be added for new content from the title, but for this page simply add ‘Lorem ipsum’.

You should be able to save now.

Frontend

We need a Next.js project in a Git Repo on GitHub or something similar. There are a few ways to do this but I’ve done the basic manual install and I suggest you do the same.

npx create-next-app@latest

I answered the questions as:

What is your project named? ... frontend
Would you like to use TypeScript? ... No
Would you like to use ESLint? ... Yes
Would you like to use Tailwind CSS? ... No
Would you like to use `src/` directory? ... No
Would you like to use App Router? (recommended) ... Yes
Would you like to customize the default import alias (@/*)? » No

You can answer anything you like, but this is my preference. The problem for me is the installer creates the App in another folder, so I simply move everything back one folder. You may or may not need to do this depending on your setup.

Next, we create a repo in Github (mine is Huyton Web Services Github Next.js if you want to clone it, but this repo will contain much more code) and push everything to it.

To install the Frontend, I'm going to use the Next.js on Shared Hosting and my local and I'd suggest you do the same.

Basic setup

Once we have a working Next.js app we will set it up so it's ready for production, for example we need to split things up a bit, having everything in an app folder is no good. Let’s create a few folders in the root:

data
components
styles
public

In layout.js change the import for globals.css to:

import "../styles/globals.css";

And move the globals.css file from the app folder into the styles/ folder.

Delete all code within globals.css, delete the folder fonts/ within the /app/ folder.

Rename layout.js to _app.js and change the code to:

import "../styles/globals.css";
export const apiDomain = "http://localhost:8080"; // Use your domain
export default function MyApp({ Component, pageProps }) {
  return (
    <main>
        <Component {...pageProps} />
    </main>
  );
}

On line 3 change the domain to the one for your CMS, later we could use an environment variable to switch this depending on the server you are on, but hard coding this is fine for now. Make sure this does not end in a ‘/’ to make things easier later.

Delete page.module.css and favicon.ico from the /app/ folder (you can add your own back in later using these docs if you like).

Remove all the code from page.js except the basic export so it looks like this:

 export default function FolderPage() {
    return (
        <main>
            <h1>Hello world</h1>
        </main>
    );
}

Rename page.js to [[...folder]][[...page]].js (watch the square brackets and dots number), so it can catch all pages one folder deep e.g. '/article/great-article-1' and '/about' will run through this file which saves on duplication (we could split this back out later if we needed to).

Rename your /app/ folder to /pages/.

Your folder structure should look like this (spot the extra file content.js, we'll add that in a moment)

If you are running on production run

npm run build

When finished, run

npm run start

If you are running locally run

npm  run dev

Test by going to the main domain and making sure it all works as expected, i.e. you see ‘Hello World’ in large letters.

Getting content

We will create a js file that will get our content for us, create a file in the data/ folder called content.js, add the code:

import {apiDomain} from "@/pages/_app";
export async function getContent(url = '/') {
    const contentUrl = apiDomain + url + '?_format=json';
    const res = await fetch(
        contentUrl,
        {
            method: 'GET',
            headers: {
                'Accept': 'application/vnd.api+json',
                'Content-Type': 'application/vnd.api+json',
            },
        }
    );
    // Catch the not found error
    if(res.status === 404){
        // Return 404 page
        return {
            'title': "Page not found",
            'heading': "Page not found",
            'body': "<p>Page not found.</p>",
            'meta_title' : '404 | Page not found',
            'meta_description' : 'Missing page',
            'error' : 404,
        }
    }
    try{
        // Return the full response
        return  await res.json();
    }catch(e){
        return {
            'title': "API issue",
            'heading': "The API is gone away, we're trying to find it",
            'body': "<p>We've lost our API and are looking for it, please try refreshing the page and if that doesn't work there is a larger issue, and we're looking into it</p>",
            'meta_title' : '404 | API issue',
            'meta_description' : 'Missing API',
            'error' : 404,
        }
    }
}

This file will:

Create a url from the domain we added before, the URL we pass in and using the format json.
We check the status from the CMS and if its 404 we return a 404 page we can use later.
If the response has a problem, we also return a 404 page.
If everything is ok, we return the response.

We will want to transform the response later and remove all the useless data coming back from the CMS and add in anything that is static, but for now the response holds all the data we need so we can just return it.

In our [[...folder]][[...page]].js we want to import the new data/content.js and create server side props to get the content and pass it back to our page. It should now look like:

import {getContent} from "@/data/content";
export async function getServerSideProps() {
    const content = await getContent('/lorem-ipsum');
    return { props: { content }}
}
export default function FolderPage({ content }) {
    console.log(content);
    return (
        <main>
            <h1>Hello world</h1>
        </main>
    );
}

You can see the URL passed in is the one we created in the CMS, our Lorem ipsum page. At the moment that’s hard-coded so we can test the data coming back. If you check your console (F12), you will see the full object for the Lorem ipsum page.

Change the content URL to ‘/home’ on line 4 to test another page:

const content = await getContent(‘/home’);

You will see a change in the object in the console. This will show your home page content. Now try '/' and the object will still be the same because you have told Drupal to use '/home' as the home page (if you pass in nothing, we have set a default to '/' so you will get the home page too).

Add in some fields so we can see the content on the page:

import {getContent} from "@/data/content";
export async function getServerSideProps() {
    const content = await getContent('/lorem-ipsum');
    return { props: { content }}
}
export default function FolderPage({ content }) {
    console.log(content);
    return (
        <main>
            <h1>{content.title[0].value}</h1>
            <h2>{content.field_subtitle[0].value}</h2>
            <div dangerouslySetInnerHTML={{ __html: content.body[0].processed }} />
        </main>
    );
}

On line 14 you’ll see the badly named dangerouslySetInnerHTML. This is a reminder that the content added in and parsed as HTML without any checks so could contain anything. We know this comes from our CMS, so we can be happy with this.

Most of the content that comes from the CMS will be in array format, even when there is only ever 1 (like Title and Body), so we’re going to transform the data coming back to make it a little easier to render on the frontend. If we have an API contract with something like swagger this may cause issues because the developer rendering the data may not expect the transformation, so transform with caution.

Also, I will do the transform as part of the function to get the data, you may want to abstract this, but for this example it makes sense.

Open your file data/content.js
Add a jsonresponse variable before the try.
Make the response the jsonresponse variable.

Now we have the ability to make changes to the data before we return it.

Change our return to an object (same as the 404 above).
Fill in the details and do some checks.

Our data/content.js page looks like:

import {apiDomain} from "@/pages/_app";

export async function getContent(url = '/') {
    const contentUrl = apiDomain + url + '?_format=json';
    const res = await fetch(
        contentUrl,
        {
            method: 'GET',
            headers: {
                'Accept': 'application/vnd.api+json',
                'Content-Type': 'application/vnd.api+json',
            },
        }
    );

    // Catch the not found error
    if(res.status === 404){
        // Return 404 page
        return {
            'title': "Page not found",
            'heading': "Page not found",
            'body': "<p>Page not found.</p>",
            'meta_title' : '404 | Page not found',
            'meta_description' : 'Missing page',
            'error' : 404,
        }
    }

    let jsonResponse;
    try{
        jsonResponse =  await res.json();
    }catch(e){
        return {
            'title': "API issue",
            'heading': "The API is gone away, we're trying to find it",
            'body': "<p>We've lost our API and are looking for it, please try refreshing the page and if that doesn't work there is a larger issue, and we're looking into it</p>",
            'meta_title' : '404 | API issue',
            'meta_description' : 'Missing API',
            'error' : 404,
        }
    }

    let mainImage = jsonResponse.field_main_image && jsonResponse.field_main_image[0] ? jsonResponse.field_main_image[0] : null;
    if (!mainImage && jsonResponse.field_image && jsonResponse.field_image[0] ) mainImage = jsonResponse.field_image[0];
    
    return {
    	'title': jsonResponse.title[0].value,
    	'heading': jsonResponse.field_subtitle && jsonResponse.field_subtitle[0] ? jsonResponse.field_subtitle[0].value : '',
    	'body': jsonResponse.body[0].processed,
    	'meta_title' : jsonResponse.metatag[0] ? jsonResponse.metatag[0].attributes.content : jsonResponse.title[0].value,
    	'meta_description' : jsonResponse.metatag[1] ? jsonResponse.metatag[1].attributes.content : 'A great meta description',
    	'created' : jsonResponse.created[0].value,
    	'background_colour': jsonResponse.field_background_colour ? jsonResponse.field_background_colour[0].color : '#FFFFFF',
    	'font_colour': jsonResponse.field_font_colour ? jsonResponse.field_font_colour[0].color : '#000000',
    	'main_image': mainImage,
    	'error' : null,
	}
}

We are now passing back the data from the fields we added previously and if they don’t exist, we still return them, but empty or with default values in the case of colour.

Let’s add in the rest of the content we get from the CMS:

Image

In the next.config.js (or .mjs) add the image remote pattern

images: {
    remotePatterns: [
        {
            protocol: 'https',
            hostname: 'cms.trampcreative.co.uk'
        },
    ],
},

Open the file [[...folder]][[...page]].js

Above the title add in our image if we have one

{content.main_image &&
    <Image
        src={content.main_image.url}
        width={content.main_image.width}
        height={content.main_image.height}
        alt={content.main_image.alt}
    />
}

Meta data

We are getting data for the meta title and description so we should use that:

Open the file [[...folder]][[...page]].js
Import Head from next/head
Add the component for Head to the <main> of [[...folder]][[...page]].js

Inside Head add meta title and meta name description

<Head>
    <title>{content.meta_title}</title>
    <meta name="description" content={content.meta_description} />
</Head>

Colours

We added some colours to the content so we can change the look. This is just for fun and I don’t recommend giving access to editors to change the look of the page (could have a choice of page template in the CMS).

Open the file [[...folder]][[...page]].js

In the <Head> add the styles if there is a body colour

{content.background_colour &&
    <style>{`
        body{
            background: ${content.background_colour};
            color: ${content.font_colour};
        }
    `}</style>
}

You can change the colours in the CMS to some really nasty colours and they'll show up (try red background and green font colour).

Headless Theme

We can now enable our Headless theme to view the pages of the CMS in the Frontend, not as part of the CMS:

Login to the CMS.
Hit Appearance on the left.
Scroll down to the Uninstalled themes.
Click 'Install and set as default' under our Headless theme

If you logout or view content you will see the CMS Frontend theme called Headless otherwise, we see the Admin theme called Gin and we won't see any content unless we are logged in, and neither will search engines. Also, unpublished content is not available on the Frontend, so we show it in the Backend. There is much more that we could do, but it is out of scope of this tutorial.

GET the Menus

We have content, but no way of knowing what content there is or how to get to it, so we have menus we have created on the CMS. We have 2 menus, 'articles' and 'main' that are populated with links to our test content. We will create a new data file to get the menu depending on the name and send the data back. Before we do that, we need to enable our menu endpoint:

Open the CMS and login.
Hit 'Configuration' on the left.
Scroll to the bottom and click 'Menu Linkset Settings'.
Enable the menu linkset endpoint.
Save configuration.

Now we can get the data:

Create a file in the data/ folder called menu.js
Add the code:

import {apiDomain} from "@/pages/_app";
export async function getMenu(menu='main') {
    const menuUrl = `${apiDomain}/system/menu/${menu}/linkset`;
    const res = await fetch(
        menuUrl,
        {
            method: 'GET',
            headers: {
                'Accept': 'application/vnd.api+json',
                'Content-Type': 'application/vnd.api+json',
            },
        }
    );

    if (!res.ok)
        return [];

    let jsonResponse;
    try{
        jsonResponse = await res.json();
    }catch(e){
        return [];
    }

    if(jsonResponse.linkset[0] === undefined) return [];
    if(jsonResponse.linkset[0].item === undefined) return [];

    return jsonResponse.linkset[0].item;
}

The file is similar to our data/content.js, we import the domain name, we have an async function and we call it getMenu which we need to pass in the menu name using 'main' as the default. We construct our URL and GET the json version of the data. We add some error checks and send back an empty array if there are any issues. If everything works as expected, we send back the first item of the first linkset i.e. our menu array:

In the file [[...folder]][[...page]].js
Under our getContent line add a new line
```
const mainMenu = await getMenu();
```
Add mainMenu to our props
Add a new component for our menu (this is basic for now, but we can add any menu here)
Add the component called MainMenu that takes in one prop called mainMenu and we pass in the array mainMenu

Our [[...folder]][[...page]].js file now looks like:

import {getContent} from "@/data/content";
import {getMenu} from "@/data/menu";
import {MainMenu} from "@/components/mainMenu/MainMenu";
import Image from "next/image";
import Head from "next/head";
import {domain} from "@/pages/_app";

export async function getServerSideProps({resolvedUrl}) {
    const content = await getContent(resolvedUrl);
    const mainMenu = await getMenu();
    return { props: { content, mainMenu, resolvedUrl }}
}

export default function FolderPage({ content, mainMenu, resolvedUrl }) {
    return (
        <main>
            <Head>
                <title>{content.meta_title}</title>
                <meta name="description" content={content.meta_description} />
                <link rel="canonical" href={domain + resolvedUrl} />
                {content.background_colour &&
                    <style>{`
                        body{
                            background: ${content.background_colour};
                            color: ${content.font_colour};
                        }
                    `}</style>
                }
            </Head>
            <MainMenu mainMenu={mainMenu} />
            {content.main_image &&
                <Image
                    src={content.main_image.url}
                    width={content.main_image.width}
                    height={content.main_image.height}
                    alt={content.main_image.alt}
                    priority={true}
                />
            }
            <h1>{content.title}</h1>
            <h2>{content.heading}</h2>
            <div dangerouslySetInnerHTML={{ __html: content.body }} />
        </main>
    );
}

Let’s create our first component of the system for our main menu:

In components/ create a folder called mainMenu/
Inside this folder, create a file called MainMenu.js
Add the code:

import Link from "next/link";

export function MainMenu({mainMenu}){
    return(
        <ul>
            {
                mainMenu.map((link)=>{
                    return (
                        <li key={link.href}><Link href={link.href}>{link.title}</Link></li>
                    )
                })
            }
        </ul>
    );
}

Not the most pretty main menu, but we can add a menu and theme later once our content is coming through correctly.

Now, if you click on the links in the Frontend, we see the page URL change but not the content. We need to hook up our content change depending on the page we are on:

Open the page [[...folder]][[...page]].js
In our function getServerSideProps we pass in resolvedUrl
We then pass this to our getContent function
Lines 5 and 6 look like:

export async function getServerSideProps({resolvedUrl}) {
	const content = await getContent(resolvedUrl);

resolvedUrl is the URL of the page and as the URL changes, so does this. If we pass this to our getContent the content will change as the URL does.

We’re still missing the articles menu, lets add that in:

Open the page [[...folder]][[...page]].js
Under the const for mainMenu add in the articlesMenu in the same way:
```
const articlesMenu = await getMenu('articles');
```
Add articles menu to our props.
In the MainMenu component pass in articlesMenu
Open mainMenu/MainMenu.js
Pass in articlesMenu
Manually add in an <li> as the last list item for 'Articles'.
Map articlesMenu and add them in as a sub list.
Your code will look like:

import Link from "next/link";

export function MainMenu({mainMenu, articlesMenu}){
    return(
        <nav>
            <h3>Main Menu</h3>
            <ul>
                {mainMenu.map((link)=>{
                    return (
                        <li key={link.href}><Link href={link.href}>{link.title}</Link></li>
                    );})
                }
                <li>Articles
                    <ul>
                        {articlesMenu.map((link)=>{
                            return (
                                <li key={link.href}><Link href={link.href}>{link.title}</Link></li>
                            );})
                        }
                    </ul>
                </li>
            </ul>
        </nav>
    );
}

This adds the the articles as a sub list that most menu systems can turn into a drop down or submenu. If you add a theme or menu system you can configure this or if you style it yourself you can add in the CSS for it.

Finishing up

In this tutorial we’ve gone through creating content on the CMS and how to add fields to add more to it. We’ve changed different types of content and added a bunch of content to the CMS. We’ve looked at how to add the content to the Frontend and the layout of the different fields, including the meta tags in the head. We’ve created a menu system to see the main pages and a sub menu to see the articles.

What we haven’t looked at are the Views and Blocks in the CMS, what they are and how to show them in the Frontend. We have not looked at a contact page and comments and how to pass the data back to the CMS. Lastly, we have not looked at formatting the Frontend, either with Themes or manually.

If there is interest, I can add another tutorial for these things.

As things are, this will wrap up the headless CMS tutorial. Don’t forget to read Going Headless: A CMS Story, what and why go headless – Part 1 and Going Headless: A CMS & Hosting Tutorial – Part 2.

All the files are available on our Huyton Web Services GitHub page, but we may change this later so check the releases.

Don’t forget if you have anything to say, please comment or contact us if you want Huyton Web Services to build a headless system or if you need any help.

Going Headless: A Next.js API Consumer – Part 3

Dave Slack | Thursday, September 26, 2024