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.
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:
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 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.
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:
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
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. Here are some helpful links on getting things set up:
- Installing CrafterCMS: Installing CrafterCMS
- Your first website project: Creating and working with your First Crafter Site
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.)
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:
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 ”
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:
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. You can find detailed how-to help here: Creating and working with your First Crafter Site
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?
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.