prismic.io CMS backend
Last updated 31 January 2018
The prismic.io CMS backend add-on is currently in beta.
Table of Contents
prismic.io is an add-on for providing a CMS backend.
Adding prismic.io to an application provides a full-featured writing room to write content in a user-friendly editor, based on the custom types that you define. The content can then be accessed via a REST API, and development kits are provided in the most popular languages: JavaScript, PHP, Java, Ruby, Python, C# and Scala.
Provisioning the add-on
Prismic.io can be attached to a Heroku application via the CLI:
$ heroku addons:create prismic
-----> Adding prismic to sharp-mountain-4005... done, v18 (free)
Once prismic has been added a PRISMIC_ENDPOINT config var will be available in the app configuration and will contain the URL used to request your API. This can be confirmed using the heroku config:get command.
$ heroku config:get PRISMIC_ENDPOINT
https://<repo-name>.prismic.io/api
After installing prismic, the application should be configured to fully integrate with the add-on.
Local setup
After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.
Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command for each value that you want to add to your .env file.
$ heroku config:get PRISMIC_ENDPOINT -s >> .env
For more information, see the Heroku Local article.
Full blog sample in NodeJS
If you’re starting from scratch in JavaScript, you can use the prismic.io command line tool to bootstrap your project. Here is how you can create a blog from a template in just a few minutes. To start from an existing project or a different technology, skip to the next section.
Start by installing the prismic.io CLI:
$ npm install -g prismic-cli
Source code
In the directory of your project, after adding the addon, initialize the source code:
$ prismic heroku --template NodeJS-blog
Initialize local project...
Running npm install...
Your project in ready! Go to the undefined folder and follow the instructions in the README.
The heroku command will ensure the environment variable set by Heroku will be used as the endpoint, and the template option specify that you want the blog template.
Custom types
Open the writing room, from the Heroku console or via the CLI:
$ heroku addons:open prismic
Opening prismic for sharp-mountain-4005
In the writing room, create the bloghome custom type:
{
"Main" : {
"headline" : {
"type" : "StructuredText",
"config" : {
"placeholder" : "Main title...",
"single" : "heading1"
}
},
"description" : {
"type" : "StructuredText",
"config" : {
"placeholder" : "Sub-title",
"single" : "heading2"
}
},
"image" : {
"type" : "Image"
}
}
}
Then create the post custom type:
{
"Blog Post" : {
"uid" : {
"type" : "UID",
"config" : {
"placeholder" : "unique-identifier-for-blog-post-url"
}
},
"title": {
"type": "Text",
"config": {
"label": "Title"
}
},
"date" : {
"fieldset" : "Post properties",
"type" : "Date",
"config" : {
"label" : "Post date"
}
},
"body" : {
"fieldset" : "Post content",
"type" : "Slices",
"config" : {
"labels" : {
"image-with-caption" : [ {
"name" : "emphasized",
"display" : "Emphasized"
}, {
"name" : "image-full-width",
"display" : "Full"
} ]
},
"choices" : {
"text" : {
"type" : "StructuredText",
"fieldset" : "Text",
"config" : {
"multi" : "paragraph, heading2, heading3, strong, em, hyperlink, ulist, list-item",
"placeholder" : "Post text..."
}
},
"quote" : {
"type" : "StructuredText",
"fieldset" : "Quote",
"config" : {
"placeholder" : "Post quote...",
"single" : "paragraph"
}
},
"image-with-caption" : {
"type" : "Group",
"fieldset" : "Post image and caption",
"config" : {
"fields" : {
"illustration" : {
"type" : "Image",
"config" : {
"constraint" : {
"width" : 640
}
}
},
"caption" : {
"type" : "StructuredText",
"config" : {
"single" : "heading3",
"placeholder" : "Image caption..."
}
}
}
}
}
}
}
}
}
}
Write some content
Start by filling in your photo, your name and a headline for your blog’s homepage.
Go to “Content” and hit “New”, choose the Blog’s home type and fill it with your own content. Save and publish!
Now, write a few blog posts. Make sure to fill in the mandatory UID field that is used for your post’s URL. Save and publish!
Start your blog!
You can run it locally like any other application on Heroku:
$ heroku local
And you can of course deploy it!
Using in an existing project
Prismic.io can be used the same way from your local machine or from Heroku servers. While the data is available from a REST API, it is recommended to use the kit provided for your language.
Node.js
Just install the npm package:
$ npm install prismic.io
The API object can then be queried:
var prismic = require('prismic.io');
app.route('/:uid').get(function(req, res) {
var uid = req.params.uid;
prismic.api(process.env.PRISMIC_ENDPOINT, {req:req}).then(function(api) {
return api.getByUID('basic-page', uid));
}).then(function(doc) {
res.render('index', {
pageContent: doc
});
});
});
Client-side JavaScript
If you’re building client-side JavaScript from npm packages, you can install it like indicated above in the Node.js section.
Otherwise you can use the version from the CDN:
https://npmcdn.com/prismic.io@2.0.0/dist/prismic.io.min.js
You can then query your repository in a similar way to the Node.js example above.
Ruby/Rails
To install the gem on your computer, run in shell:
$ gem install prismic.io --pre
then add in your code:
require 'prismic'
endpoint = ENV['PRISMIC_ENDPOINT']
api = Prismic.api(endpoint)
doc = api.getByUID('basic-page', params[:uid])
PHP
Install the kit from Composer:
$ composer require prismic/php-sdk
Then use prismic in your code:
$uid = $_GET('uid');
$doc = $api->getByUID("basic-page", $uid);
Writing room
For more information on the features available within prismic.io writing room please see the docs at prismic.io/docs.
The writing room allows you to define custom types, write content, and publish documents that will be available through your API.
The writing room can be accessed via the CLI:
$ heroku addons:open prismic
Opening prismic for sharp-mountain-4005
or by visiting the Heroku Dashboard, going to the application you want to access, and selecting prismic.io from the Add-ons menu.
Configuring previews and edit button.
With prismic.io, you can preview draft content or future releases directly on your live website. You can also have an edit button display on your website for writers who are logged in.
More information on configuring previews can be found in our online documentation
Removing the add-on
Prismic.io can be removed via the CLI.
This will destroy all associated data and cannot be undone!
$ heroku addons:destroy prismic
-----> Removing prismic from sharp-mountain-4005... done, v20 (free)
Support
All prismic.io support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at contact@prismic.io.