CMS for NodeJS: Using CrafterCMS Javascript SDK on the Server with Node JS

In this blog, we will focus on the language-specific bindings for Javascript, the CrafterCMS Javascript SDK applied on the server side with Node JS. A deep dive on the Javascript SDK and architecture can be found in this blog post: Introducing CrafterCMS Javascript SDK

Pre-requisites for Using the Library

• NPM / Yarn installed
  • The SDK releases are published to Node Package Manager (NPM.)  Example: https://www.npmjs.com/package/@craftercms/content
  • NPM will help you easily download the proper dependencies.  You can all so use NPM or Yarn to build and execute your application.
  • In our example, I will use Yarn to manage my package.json file and to assist me in building my application.
• Access to a running Crafter Engine instance and site.

Building a Simple Javascript Application

The point of our application in this blog is to demonstrate how to include and use CrafterCMS’s Javascript SDK in an application and to use it to retrieve content from a running Crafter Engine instance.   We’re going to keep the application extremely bare bones in order to illustrate that this library is independent of any specific frameworks or platforms such as Node.js, React, Angular, Vue etc.

For those looking to get right into the meat of the integration, use of the SDK starts at Step 4.

Step 1: Create a basic structure and build for the app

The first thing we want to do is to create a directory for our application source.  I will call my directory simple-node. Inside that directory add a file called package.json with the following content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
 "name": "simple-node",
 "version": "1.0.0",
 "description": "Simple Node JS Server that will use CrafterCMS Javascript SDK",
 "main": "server.js",
 "scripts": {
 "test": "echo \"Error: no test specified\" && exit 1"
 },
 "author": "",
 "license": "ISC",
 "dependencies": {
 "@craftercms/classes": "^1.0.0",
 "@craftercms/content": "^1.0.0",
 "@craftercms/models": "^1.0.0",
 "@craftercms/search": "^1.0.0",
 "@craftercms/utils": "^1.0.0",
 "express": "^4.16.3",
 "url-search-params-polyfill": "^5.0.0",
 "xmlhttprequest": "^1.8.0"
 },
 "proxy": {
 "/api": {
 "target": "http://localhost:8080"
 },
 "/static-assets": {
 "target": "http://localhost:8080"
 }
 }
}

This file describes our application, how to build it and what is needed to build it.  In the content above we can see:

• The application metadata.
• The application dependencies we are requiring are the various CrafterCMS Javascript SDK dependencies ( “@craftercms/content”: “^1.0.0”, “@craftercms/search”: “^1.0.0”, etc.)
• The application build/dev dependencies that help us compile the application for distribution (xmlhttprequest”: “^1.8.0.)
• Configuration for your CrafterCMS endpoint.

Step 2: Perform an initial build

Run yarn in your application directory.  This will download all of your dependencies.

Step 3: Create an application Javascript

Note that in our package.json we’ve listed server.js listed as the main for the application.

Create a server.js file and place the following content in the file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

console.log('server is starting');

var express = require('express');
var app = express();
var server = app.listen(3000, listening);

app.get('/', test);

function listening() {
 console.log('listening...'); 
}

function test(request, response) {
 response.send('Hello World!');
}

app.use(express.static('website'));

Now run the application by typing: node server.js

Finally, access your application via the browser at http://localhost:3000

Step 4: Calling CrafterCMS API’s with our application

Now that we have a very basic, working application it’s time to use the CrafterCMS Javascript SDK.

Crafter Engine Instance

In order to use the CrafterCMS APIs, you will need a running Crafter Engine instance with a project set up that you have access to.  It’s easy to get started. Install CrafterCMS and create your first site.

Import the APIs into your application javascript

Add the following code at the very top of your server.js script file.  Here we are declaring the classes we will use and indicating where they are imported from (the SDK.)

1
2
3
4
5
6

var classes = require('@craftercms/classes'),
    content = require('@craftercms/content'),
    crafterConf = classes.crafterConf,
    ContentStoreService = content.ContentStoreService;

XMLHttpRequest = require("xmlhttprequest").XMLHttpRequest;

Configure the SDK for your Crafter Engine endpoint base URL (server name, port etc)

Now that you have declared the CrafterCMS SDK services you want to use you are almost ready to start retrieving content.  Before we can, we need to make sure the SDK APIs know where Crafter Engine “endpoint” / server is and what site to pull the content from.  To do that we have two options:

• We can create a configuration object and pass it with each call
• Or we can explicitly supply the endpoint configuration with each call

Since we’re going to use the same endpoint and site, we’ll set up a configuration object and pass it when we call the APIs.  To configure the endpoint we add the following code to our script after the import statements:

1
2
3
4

crafterConf.configure({
 baseUrl: 'http://localhost:8080',
 site: 'editorial'
});

The configuration above states that our API calls will reference the site in Crafter Engine that has the “editorial” ID. By default, the configuration assumes that Crafter Engine is running locally on port 8080. To change this, add the following:

baseUrl: “YOUR_PROTOCOL//YOUR_DOMAIN:YOUR_PORT ”

1
2
3
4

crafterConf.configure({
 site: 'editorial',
 baseUrl: "https://mydotcomsite"
});

If you want the system to assume that the app and the API endpoints are on the same server you can set base URL to an empty string (“”)

Call a CrafterCMS API and get content

MAKE THE CODE CHANGES:

Now that the library is imported and configured, we’re ready to use it.  Let’s add the code to our example to make a request for content and put it on the screen for the user.   Below is the entire server.js script for our application with changes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

console.log('server is starting');

var express = require('express');
var classes = require('@craftercms/classes'),
 content = require('@craftercms/content'),
 crafterConf = classes.crafterConf,
 ContentStoreService = content.ContentStoreService;

XMLHttpRequest = require("xmlhttprequest").XMLHttpRequest;

var app = express();
var server = app.listen(3000, listening);

app.get('/', test);

crafterConf.configure({
 baseUrl: 'http://localhost:8080',
 site: 'editorial'
});

function listening() {
 console.log('listening...'); 
}

function test(request, response) {
 ContentStoreService.getItem('/site/website/index.xml')
 .subscribe(item => {
var htmlTitle = item.descriptorDom.page['hero_title_html'];
  response.send('Hello World: ' + htmlTitle);
 });
}

app.use(express.static('website'));

What we’ve done is replace the code in the test function that was hardcoded to write “Hello World” on the screen for the user with the code that calls CrafterCMS for content and write the retrieved content on the screen instead.

Let’s take a closer look at the API call; ContentStoreService.getItem

• The first parameter is the path of the content item we want to return.  The example uses the home page of the editorial site.

TEST THE APPLICATION

After you have made your changes, stop the Node server (Ctrl+C) and restart it. Once it’s restarted, reload your application in the browser to see content coming from your CrafterCMS site:

Congrats!  Your application’s content is now externalized and managed in the CMS.

Step 5: Update your content using the CMS

Now that our code is complete our content authors can update the content at any time via the CMS and we don’t need to rebuild or redeploy the application.  Let’s use Crafter Studio to update the content for our app. 

In Crafter Studio, find the content you want to edit

In our case, the content we’re consuming is the hero title.  Let’s make an edit to that content:

In your site’s content preview, turn on the editing pencils and click the pencil for the Hero Title (as shown above.)

Note that the author has a preview of the content.  This is something very different and ultimately much better than what you see with other Headless CMS systems.

With Crafter, it’s always possible to provide the user with a preview of the content they are editing regardless of the front end framework.  Preview capability is key because it makes editing content easier for authors.

Make a content change and save

After you click the pencil for the Hero text make the change and then click the Save and Close button at the bottom of the form.  You will see your update in the CMS right away.

Refresh the example application

Wow! Those changes in the CMS look great (if I do say so myself :D!)  Now it’s time to see the changes in our application.  Simple, just refresh your application in the browser. No code updates required!

It’s really just that simple!  A few lines of code allows us to create applications with content, configuration and other strings that we can update at any time without needing to update or redeploy our application code.

What about the full API, workflow and publishing?

This blog is meant only to cover the basics of using the CrafterCMS SDK with Node JS. A deep dive on the Javascript SDK and architecture can be found in this blog post: Introducing CrafterCMS Javascript SDK.

Conclusion

CrafterCMS’s Javascript SDK gives front end and full stack developers who work in Javascript and Javascript related technology a native programming API to work with that makes building content-rich applications much easier to do.

When we stop and think about it, almost every application has content in it.  If that content is easy to update and updating the content can be done by non-technical users at any time without a build or deployment everybody wins:

• The content in the application is richer and much fresher
• Developers spend time developing rather than making non-code related updates
• Removing non-feature related deployment distractions gives us more time and makes our teams more agile.
• Our business users can make their changes at any time which makes the business more agile.

Headless CMS capabilities provide non-technical users with the ability to update, workflow and publish an application’s content at any time without the involvement of developers and IT.

CrafterCMS’s headless capabilities go beyond traditional headless CMS systems by providing authors with an in-context preview for content editing and giving developers the freedom to use whatever front-end technology they want.