The Nearly-Headless CMS

If you’ve been paying attention to the CMS scene lately, you’ve probably heard the terms “headless” and “decoupled.” These terms describe websites and applications where the CMS is not used to render the actual site or application. For instance, it could be a website where the front-end is a JavaScript framework like AngularJS or React, and the CMS supplies the content via a JSON API. A List Apart recently hosted a very timely and informative ALA On Air panel titled “Love Your CMS,” which touched on the topic and sparked good discussion around the pros and cons of the approach. I recommend watching the archived video (or reading the provided transcript). I found it instructive to hear Ryan Irelan talk about the difference between “headless” and “decoupled,” and why he considers them to be related but not exactly the same.

At Bluecadet, we didn’t set out to do headless CMS development for its own sake. We were curious about it and could see the potential benefits, but we only ended up doing it when it solved specific problems we faced on two very different projects.

The first was a website for Haruki Murakami. We wanted to create as seamless an experience as possible, which meant experimenting with different animated transitions between sections on the site. We eventually settled on AngularJS to support those transitions, so the challenge was how to merge AngularJS with WordPress, the CMS we were using. There are a few themes that do this, but after some testing and much research we decided to use the JSON API plugin. The client got a familiar CMS to work with, but also a very tightly-orchestrated front-end layer that captured their creative vision for the project.

The second project wasn’t a website—it was a Cinder (C++) touchscreen application for the Art Institute of Chicago that helps visitors learn more about James Ensor’s multi-piece drawing, “The Temptation of Saint Anthony.” Prior to this project, we had completed another touchscreen project with the content managed via XML, and we felt that we (and our clients) could benefit from a CMS instead of hand-editing XML files. Since we have a lot of experience with CMSes for websites, the challenge was how to connect a CMS to a touchscreen application. Again, JSON was the glue—we had done some research into serving up JSON from WordPress, and once we found a JSON parsing library for C++/Cinder the two big pieces came together. We were able to quickly build the CMS in WordPress, giving content authors a familiar interface, as well as reducing potential data errors. This had a profound impact, bridging two sides of our agency’s practice that had previously operated in fairly separate spheres. Once we finished this first headless CMS, the rest came along quickly. We now use them with JavaScript applications, iOS/Android applications, and touchscreens.

Why do I tell these stories? The key lesson for us was that a headless CMS helped solve a problem. We didn’t dive into headless CMSes because it was trendy, we did it because we needed to solve specific problems (in the first case an aesthetic/creative one, and in the second a data-management one). The other important outcome was that we could let each piece of the project do what it does best—by letting the CMS simply manage content, we could use better tools for rendering the presentation layer. We were also able to let our team members focus on what they did best: with the James Ensor touchscreen, our CMS developers were able to take care of the data management problem while our Cinder developers could focus on the touchscreen application.

Use your existing CMS#section2

So let’s say that you’ve got some very good reasons to go headless. Maybe you want to have control over the front-end markup and animation in a way that stretches past what your CMS’s theming layer can support. Perhaps you want cleaner separation of front-end and content-management tasks—it can be easier to staff multiple projects when the responsibility for building a site doesn’t require everyone to know both the front-end rendering layer in addition to the backend of the CMS. Or perhaps you’re not building a website at all. Maybe you’re building a native iOS or Android application, but you need a familiar, yet robust, way to provide data for it.

The good news is that your preferred CMS likely already has what you need. WordPress and Drupal both have modules and plugins to enable a RESTful API, which I’ve found to be the most straightforward way to provide data in a headless architecture. For WordPress there’s the aforementioned JSON API plugin, as well as WP-API (which is being developed with the goal of eventual inclusion in WordPress core). Drupal has the Services module and Services Views, which allows developers to turn Drupal output created with Views into API endpoints.

If you’re interested in the WordPress side of things, WPEngine’s Torque magazine has a number of posts that cover the basics. For Drupal, this is a very handy video tutorial covering Services Views.

One to many (even if it’s just one)#section3

So far, the examples I’ve described are headless with a one-to-one relationship between the CMS and the front-end rendering application. A useful thing resulted from our work on those applications, however: my teammates and I started to decouple our expectations on the CMS side as well. For all the talk of dividing content from presentation, it’s still absurdly easy to build assumptions into your CMS for a single form of delivery. You start out knowing that the CMS will be used for a website, so everything from the order of the fields to the name of your fields is influenced by the form that it will take on the site. But what if your CMS later needs to support different products besides that initial website? This is something that Jeff Eaton and others on the ALA on Air panel addressed quite well, by drawing a distinction between the intertwined content management and web publishing responsibilities of most CMSes.

I’ve found that having to build CMSes that serve many individual products has made me focus more on flexibility. So even if I’m building something that is only being used for a website right now, in the back of my mind I’m wondering what would be required if we had to support a native iOS or Android application using the same CMS. I’ve started thinking of these as nearly-headless (or headless-ready) CMSes.

That relates back to one of the key tenets of the web: separating content from presentation. It’s why we have CSS separate from our markup, and rely on class hooks so that we can style things in ways that do not affect the semantics of the content.

Right now I’m at the very beginning of a CMS project that has to serve multiple products: multiple different touchscreen applications, iOS/Android apps, and a responsive website. If we hadn’t had the initial experience creating headless CMSes for those individual product types, we’d be nervous. But right now we’ve got confidence that we’ve done all of the separate pieces before, even if we’ve never tried to do everything using one CMS.

Downsides#section4

There are a few potential downsides: it increases the number of variables in the system, for one. So not only do you have to deal with Drupal or WordPress, you also have to deal with AngularJS, React, or whatever renders your front-end. (I should interject here that I’m wary of using JavaScript frameworks purely for convenience, especially if the CMS could readily handle the front-end rendering requirements of the project. But that’s a subject for another time.)

This is less an issue for native mobile applications, because those are always going to be separate from the CMS anyway. Still, simply having multiple software systems can be tricky, because each piece comes with its own assumptions and opinions on how things can/should be done. It also means that your team’s expertise has to cover different codebases. (Although that’s potentially an upside, if your team already has that expertise in both camps.)

My litmus test is pretty simple: does going headless with the CMS solve a key problem, and is it enough to outweigh the complexity added to the project?

Try it out#section5

I hope you come away from this thinking that this subject is not as mysterious as it might appear—you can use popular, well-supported CMSes to do this today. If you’ve been wondering how to get complex data into a JavaScript (or native) application, the tools you need are likely available for your CMS of choice. That means that you or someone on your team already has the skills and experience, and the question then shifts from whether you can, to when the time is right to do it.