Mr Branding: Off With Your Head! Build Better Web Apps with a Headless CMS

Wednesday, July 26, 2017

Off With Your Head! Build Better Web Apps with a Headless CMS

Building Sites with Elemeno, a headless CMS

The "Headless CMS" is a relatively new type of tool, but what is it? What makes it different? And, how do you get started with one?

Traditional CMSs typically have two major components: a back end where you create and manage your content, and a front end which displays the content. The front end is almost always a website which is often built using outdated techniques, tools, and libraries.

Headless CMSs take a different approach, only having a back end where you create and manage your content. They typically deliver your content via a robust API which allows you to easily retrieve your content in a developer-friendly way. This separation of concerns means the CMS does only one thing: manage your content. Headless CMSs don't dictate how or where you display your content. You can deliver your content to any device or platform, using practically any programming language, framework or library.

Looking for more CMS topics? Check out these great links:

And check out SitePoint Premium for more books, courses and free screencasts.

Building a Simple Portfolio Site with Elemeno

Let’s take a look at how we would build a simple portfolio site using Elemeno, a popular Headless CMS cofounded by yours truly. We'll use a typical Node.js development stack, but the same principles could be applied to any language or framework.

The tools we'll be using include:

Node.js, a server-side JavaScript runtime environment
Express, a web framework
Pug, a templating library (formerly known as Jade)
Elemeno, a headless CMS

We’ll get started first by setting up our project on Elemeno. Elemeno is a hosted product, so there's nothing to install and no databases to set up. Simply create an account, if you don’t already have one, then create a new project. You can get started 100% free by choosing the development plan, which will fit our needs perfectly for this demo.

Defining content models

The next step is to define our content models. You can think of a content model as the template of inputs that will be displayed when creating content. Elemeno has two different types of content models: Singles and Collections. Collections allow you to create many items from the same content model. This is perfect for things like collections of products, articles, or projects. Singles allow you to create a single item from a content model. This is ideal for things like contact info, or about us pages.

For our simple portfolio site, we'll create a Collection to store information about our projects. We'll need to determine what information we want to display for each project, and what type of input is best suited to capture that information. For our portfolio, each project will have:

Title (Plain Text)
Description (Markdown)
Date (Date and Time)
Screenshot / Photo (Image Picker)
URL (Plain Text)

When creating a collection on Elemeno, you start by giving your collection a name at the very top of the screen. We’ll call our collection “Portfolio”. You'll see that our collection starts with a single “title” input on the left side of the screen, and a list of input elements on the right. To define our content model we simply drag and drop input elements from the list onto our blank slate on the left. These inputs are exactly what you'll see when creating the content items for your portfolio.

After placing each input element, click on the input to change its settings. We'll set the “label” for each input and leave the other options to their default setting for now.

Our Portfolio collection should now look something like this:

Elemeno interface: Portfolio collection screen shot

Once we’re happy with what we have, we can click the “Save” button to create the collection.

Creating Items

Now that we have our Portfolio collection defined, we can start creating items. Simply click the “Create the first item” button to get started. Fill out each of the inputs and click the “Save and Publish Now” button to create our Portfolio item. Next, create a few more items to fill up our Portfolio Collection a little bit.

Now we’re ready to jump into the code and start building our site. First we’ll need to ensure we have Node.js and NPM installed for our development environment. You can do a simple check by opening Terminal and entering the following command:

node -v

You should see your installed version show up, or command not found: node if Node isn't installed. If you need to install Node, simply download the installer from the Node.js website.

First create a new directory to store our project files, and then navigate to that folder in a Terminal window. We need a couple of node packages for our project, so we’ll use NPM to install them by entering the following command:

npm install elemeno express pug

We'll create a new file called server.js, and we’ll get started by including the packages we just downloaded:

var Elemeno = require('elemeno'),
    express = require('express'),
    pug = require('pug');

We’ll create a new Express application by simply calling Express:

var app = express();

Now we need to create a new directory called views to hold all of our Pug template files. Then we’ll configure Express to tell it where our templates live, and which templating engine we’re using. Note: you can use any other supported templating engine based on personal preference.

app.set('views', './views');
app.set('view engine', 'pug');

We can now create the route for our landing page. We’ll keep things nice and simple by defining all of our routes right inside server.js. To define our first route, we’ll use:

app.get('/', function(req, res) {
    res.render('index.pug');
});

This simply tells Express when someone makes a GET request to our root / we want to render our index.pug template.

The next step is to create the index.pug template inside of our views directory. Create a new file, save it as index.pug and for now we'll just fill it with something simple like:

h1 Hello World!

Now back in server.js we just need to tell Express which server port it should listen on:

app.listen(3000, function () {
    console.log('Portfolio listening on port 3000');
});

From a Terminal window you can now type node server and hit enter to get our website up and running.

Voila! We have a super basic node website. In your web browser go to localhost:3000 and you should see our super awesome “Hello World!” message.

Including content

Now let’s include the content from Elemeno in our website. We’ll start by creating an API Key which will allow us to access the content from our portfolio website. Go to the Settings screen on Elemeno, find the API Keys section and click the “Create API Key” button. We'll give our key a name of “Website” and we’ll leave the other settings to their defaults. We'll see our new API Key listed, click on it to view the details and copy the “Access Token” value.

Back in our server.js file, we'll create a new instance of the Elemeno client near the top of our file:

var Elemeno = require('elemeno'),
    express = require('express'),
    pug = require('pug');

var app = express();
var elemeno = new Elemeno('PASTE-ACCESS-TOKEN-HERE');

Paste in the Access Token we copied from Elemeno. Now inside our index route we'll fetch a list of projects from our Portfolio collection

app.get('/', function(req, res) {
    elemeno.getCollectionItems('portfolio', function(err, response) {
        res.render('index.pug', {projects: response.data});
    });
});

We pass the slug for our Portfolio collection, portfolio, to the getCollectionItems function. This function will return an array of objects representing the items in our collection. We then render our Pug template and pass along the data that was returned.

Continue reading %Off With Your Head! Build Better Web Apps with a Headless CMS%

by Chris Erwin via SitePoint

Mr Branding