Layout Management in a Headless CMS

While Agility is a Headless CMS and can boast all the benefits that come with that, there is one area where we take a different approach than others. Layout Management.

Yep, we are opinionated about it and stand by it!

One of the main concepts of a Headless CMS is that the CMS should make no assumptions about how Developers will use it.  This means as an architect you often start with a blank slate and you configure your content architecture exactly to your specifications.

That's great, and something we provide out-of-the-box with Content Models, but there are some limitations to this approach when using a Headless CMS to build websites and it affects both Developers AND Editors.

Let's take a closer look.

Using Content Models to Manage Layout Content

Let's go through some content architecture that's using Content Models for each type of layout and see how it holds up. For simplicity, let's start with a single landing page for an upcoming video game.

Layout: Home

How would you architect your content for this layout? Likely, you would create a Content Model that represents the content that is editable on this page.

Content Model: Landing Page

And here's how it might look in Agility:

And here's what you would get back from the Agility Content Fetch API for this item: 

In your code, you would then create a static layout, consume this content item via the API and then use its properties to populate the content in the HTML you've already scaffolded out. Easy right?

Is there anything wrong with this approach? Well, no. It meets the basic requirements of allowing the editor to change the content and even create versions of this content for other languages.

So what's the big deal then? Well, this site and its content are likely to evolve and grow way beyond a single layout. Keeping the current architecture in mind, let's see what would have to happen to handle these common requests in the below scenarios.

Common Scenarios

Editor: I need to create a new landing page specifically for the press. It will have the exact same content layout as the home page, but just different content.

You would need to go back into your code and add another static layout in your website to handle the routing for your new landing page, then create a new item in the CMS to represent the content for that page, take note of the content ID and then likely spend some time refactoring your code now that you are using it in two different places.

Editor: I need to be able to set the SEO properties for each layout such as Meta Tags and Meta Description.

You would need to add these additional fields to the Landing Page content model, go back in your code, read those properties, and output them in the appropriate place.

Editor: On the home page, we want the YouTube video to be BELOW the Main Rich Text, but on our press page we want the YouTube video to remain ABOVE the Main Rich Text.

This is where it gets tricky. Both the home page and press page are using the same content model and HTML template. The editor does not have the ability to set the order of content being rendered on the page, because that's hardcoded in your HTML template. Now you have some decisions to make. Do you hard-code some logic in your website to adjust the order only if the current page is the home page? Or do you split your code altogether and use a slightly different HTML template for each page? Neither option sounds great or scalable, but you have to get it done so you reluctantly choose one, deploy it and move on.

Editor: Our CEO doesn't like it, can we have the YouTube video ABOVE the Main Rich Text area on the homepage again?

🤬 Ya... we've all been there.

Editor: I need to create a new page for our online leaderboards, it needs to show the top 10 players, but also provide a detailed leaderboard where people can explore the entire list.

Alright, sounds fun. You get to play around with the Oculus Leaderboards API, create a new content model for this new type of page, create a new static layout route, and mess around with some responsive tables. A few coffees later, and a sleepless night, and you get it done. This new leaderboard page now has two main components on the page, one is the top leaders, and the other is the full leaderboard.

Editor: Oh, can we have the top leaders on our home page as well?

Ok, that didn't come up as a requirement during discussions, but that's fine. It's not too complicated to extract that functionality into a reusable component. So you do just that, you spend some time refactoring your code and then you add it to your landing page HTML template and deploy your update.

Editor: The top leaders are showing on the press page, we don't want it to show there.

Oh, right! It's using a shared HTML template between home and press page. You now need to handle that logic in your code as well, further complicating your solution.

Limitations

As you can see in the above scenarios, the editor's needs are impossible to predict. It's not their fault, its the nature of the game. So what are the problems here with our architecture?

It's not flexible for the editor, so the developer spends most of their time taking orders, tinkering with existing code, and wishing they were doing something else!

So what does that ultimately mean?

• Editors cannot create/manage layouts on their own without a developer
• Editors cannot control which components are on each layout
• Developers get bored or burnt out
• More development resources/expenses required
• Productivity on the website suffers

And, who's at fault in this? I'll give you a hint, it's not the editor and its not the developer... It's the architecture! 

A Better Way: Integrated Layout Management

We always encourage developers and architects to strive to use the best tool for the job. While setting up simple content models to represent your page content can be quick and easy, it doesn't always scale well. To address this, Agility has built-in Layout Management. 

Using Layout Management, you can empower editors to create and manage layouts for your app using re-usable building blocks (i.e. Component Models). Editors can manage your site's page tree, page-level SEO properties, and determine what content and functionality will be on each page. As a developer and architect, you still have the full control over what components are available to the editor, where they can place them on the layout, and what they do.

Benefits

• Empowered editors who can do more without a developer
• Happier developers who can focus on new functionality and enhancements, and less time responding to new content requirements
• Increased productivity
• Fewer resources/expenses required

What's in a Layout?

Layouts consist of the following core components:

• Layout - name, url, seo properties, and other layout-level properties
• Layout Model - the template that defines zones where editors can place components
• Zones - the areas on the layout in which editors can add components
• Component Models - the functional components the editor can add to each zone

Example Layout

Here we have a page that is using a Page Template with a single Content Zone. This allows editors to add/remove/re-order any component to this layout and have each component rendered, one on top of the other. 

On the website, an API call is made to fetch the layout, its zones, and its components.

The website then parses the response and renders the modules in that order.

Layout become even more powerful when you implement dynamic routing. You can do this in your app by requesting the sitemap from Agility and match the incoming requested URL.

From the above response, you can easily determine if an incoming request matches a Layout in Agility. If it does, then you would make the appropriate Get Page API call to get the layout's content, and lastly pass the fields for each component to a component in your web app who will be responsible for rendering that content.

If build your web app to support layout routing and component rendering, you'll find that your editors can do more, and you'll be able to spend more time building cool stuff.