Discover a faster, simpler approach to building your admin interface with the help of a modern headless CMS

A couple of weeks ago, I attended a Meetup hosted by Squeed. My old colleague, Joakim Kemeny, was talking about Server-Driven UI (SDUI), which I’ll be sure to link to when he has his blog post up.

After some interesting talks, I approached a couple of younger people who looked like students. I was curious about what brought them to this corner of the world. If I’ve learned anything from speaking to younger audiences, they’ll be sure to let you know if what you’re talking about is interesting or mundane.

After asking them what they’d been up to, they told me they were working on a proof of concept for a custom-built website; their potential customers could add products through a separate admin interface.

When I told them why they didn’t have to spend time building an admin interface from scratch, it sounded almost too good to be true.

That’s why I’m sharing my approach here.

What Usually Defines an Admin Interface

When you believe you need an admin interface, it is usually for a couple of reasons:

• Some need access to certain controls that others should not have.
• You want people to be able to edit product information on your site, stuff that will update more often than the code around it.
• You want to see reports or dashboards of how your operations are running.

While many other reasons exist for needing an admin interface, these are the most common ones I’ve encountered.

This article’s outline is that you’re not shipping the admin interface to the customers as a service but providing it to certain users within an organization.

All right, so let’s whip something up. How hard can it be?

The Overly Difficult Path: Building It Yourself

It’s hard to blame anyone for thinking this admin interface needs to be built by yourself. After all, your controls, data, and reports are all unique to your company, and you perceive it as something that needs to be built by yourselves.

I’ve built countless admin interfaces myself, and while I and those around me get really excited at the endless possibilities while building this customized experience, there never seems to be enough time or money to build a well-thought-out user admin interface.

Why? Because our paying customers aren’t the ones using these admin interfaces.

I could show you examples, but any of us who have ever used an admin interface for something that was homegrown knows they rarely provide a good user experience. In fact, we’d be happy if they were just secure enough (which they also often aren’t).

So, if we’re not building this admin interface ourselves, what are we exactly looking to acquire from a third-party vendor or open-source project to avoid spending that time?

The content management, of course!

Content Management — The Common Denominator

If we take a step back and focus less on the way we present our admin interface and its contents, let’s instead think about the content itself that you’re planning to have.

Here are a couple of examples of content:

• Office(s) opening hours
• Contact information
• Product information

All that we’re looking for here is a way to create content and manage it. How unique is that to warrant a homegrown system?

Not very!

Content Management Systems

Chances are you’ve probably heard of WordPress, Umbraco, or any other traditional CMS. A CMS like WordPress bundles in all kinds of things for intended convenience, like UI management, content management, and much, much more.

The problem with these systems is that while they may cater well to some companies, you’ve got a development team building pages from code, and having a big CMS like this will likely just get in the way.

The main issue with these systems is the coupling of UI and content, which in turn creates a weird vibe in the company, where UI creation and content management responsibilities become ambiguous and confusing.

A couple of things that may have happened to you or someone around you while working with a traditional CMS (like WordPress):

• A feature request comes in to the developers, which doesn’t actually require code changes, only changes in the CMS.
• Developers try to create a feature, but the CMS is getting in the way of developing it, forcing developers to create hacky workarounds.
• The content editors sitting in the CMS add a UI component to a page in a way that wasn’t expected and is now causing buggy behavior. Now there are meetings about whether this is a bug or just an unintended usage of the site builder.

This is why there’s another type of CMS out there, known as a headless CMS.

Headless Content Management Systems In a Nutshell

The main purpose of a headless CMS is to decouple the UI and the content.

I usually refer to a headless CMS as a “point-and-click database” with an API layer on top.

I’m going to show you how simple it is by using Contentful, a market-leading CMS vendor and one with an easy learning curve. Like others, it also has a fair free tier that will be enough for those who are just starting out.

Create a content type

In a headless CMS, you need content and the data structure for the content. The structure is usually referred to as having content types, and added together as a whole, they make up your content model.

Below, I’ve created a content type called “CTA component.”

As you can tell, there’s no UI involved here, just content.

Let’s take a look at the field types I’ve created inside this content type.

Here, we can see that a “CTA component” consists of a headline, a subline, some text, a target page (useful for linking the user somewhere on a website), and other things.

This content type is actually taken from one of Contentful’s starter templates, so for simplicity, I’m rolling with that here. We could have a lengthy discussion here about what constitutes a “CTA component” from a content perspective, but let’s cover that later.

Time to create content entries

Now that I’ve got my content type, I can create content entries or just entries using this type.

As you can see above, I’ve added some sample data, and once I’m happy with it, I press “Publish,” and the content is “in production.”

Consume the content

Now that you have your content, you can consume it via popular standards like REST or GraphQL.

Contentful ships a GraphQL playground that you can install in under a minute.

Once you know how to consume the content, it’s up to your company how you choose to display that content, be it via hero banners, article pages, footers, etc.

What We’ve Learned

What we’ve seen from the above is that:

• It’s very simple to create content types and content for those who have been given authorization to log in.
• The interface to manage content is simple and intuitive
• Consuming the data is straightforward and requires no API development on your end.

The biggest takeaway is that your backend development needs have been drastically reduced. You’ve got your database, the API layer, and other things. It wouldn’t surprise me if you went from a 50/50 between the frontend and backend to an 80/20 at the very least.

Added Benefits

On top of not having to build a lot of things by yourself, there’s a couple of benefits I’ll list briefly that you get in a headless CMS environment:

• Giving a clear UX/UI responsibility to one area, not anyone who deals with content.
• Giving the content management responsibility to the content editors or marketing specialists. If the need arises, it’s easier to have that conversation when it doesn’t start with “If I add this component, I get a bug.”

Potential Risks

• Getting a headless CMS and handing out access to anyone in the organization will most likely cause a degradation in content quality. Start small and centralized, and keep an eye on content quality and reuse.
• Do try to avoid creating page-centric content, as it will not be as reusable as possible and, therefore, have degraded quality. If you see new content being created with high similarity to other content apart from the content type being called “Banner” and the other “Footer Banner,” you’re likely heading down this path. That said, some similarities are not an absolute taboo; just be mindful of it.

How Do I Content Model?

We’ve been going lightning-mode into why a headless CMS could help reduce needed work by potentially up to 90%, but how do you then dive into this new and scary world of content modelling?

My good friend, Henrik Ståhl, has written an excellent article on the topic (he even has the certifications to prove it) of content modeling, which I suggest reading if you want a crash course.

If you’re curious, I advise you to simply give it a spin. You’ll be impressed with how fast you’ll be up and running.

My only advice is to avoid page-centric content, especially if you’re building something for a mid-to-large company. Just because the CMS is decoupled with UI doesn’t mean your mindset will be. It takes time to get used to the idea that, for example, a Hero Banner with content that consists of a heading, a preamble, and a text can be presented in more ways than a Hero Banner.

Another CMS Called Sanity

While this is not an article meant for comparing different CMS, if you feel the price point of Contentful runs a bit high, I’d recommend Sanity. It’s got more of a developer-centric feel to it and requires more setup from your end, but it’s more performant, cheaper, and more flexible than Contentful. Unfortunately, it is also a bit more complex to understand with their non-standard GROQ queries than GraphQL or REST.

If you want a safe bet for success, I’d recommend Contentful.

Bottom Line

I hope you’ve enjoyed my topic as much as those young entrepreneurs that I met faced with building their first professional admin interface for content. Also, I hope you will give thought to using a headless CMS the next time you are building something for someone to manage later with content.

Thanks for reading.

Shipping an Admin Interface 10x Faster was originally published in Better Programming on Medium, where people are continuing the conversation by highlighting and responding to this story.