Contentful, my way: build custom extensions with this new SDK

July 6, 2016


Imagine you're responsible for maintaining the content management tools at your company. Your editor comes to you and says: "Hey, I really would love to have an HTML editor right inside Contentful. Do you think that's possible? Would be so wonderful!" Up until today you'd have to slowly shake your head and say "no." But things have changed.

The DIY approach

We thought that instead of waiting for us to release these features your team needs, you would rather prefer to build them on your own — and to adjust them to the processes and workflows of your team.

UI Extensions SDK

We've released the UI Extensions SDK so that developers can extend the basic functionality of the Contentful Web App. Whether it's about slightly improving an existing field (say, creating a different interface for editing JSON fields) or building something completely new (for example, integrating third-party data in Contentful) — this is all possible, and not too difficult.

Two examples

1. Customize existing fields: alternative JSON editor

For example, if you'd like to change how JSON editor works and enable field-by-field key-value pairs editing — instead of dealing with a huge JSON blob in one field — you can build a custom editor using this SDK. We've built a JSON form editor (displayed above) as an example to give some idea of what can be built.

2. Adding new features: a diff field extension

Of course this SDK enables creating something completely new — for example, an extension that would display the diff between draft and published states of a field.

More examples

You're more than welcome to look at and experiment with some other examples of extensions that we have built.

The tech side

The guide gives specific step-by-step instructions on creating and deploying extensions; below is a high-level overview of what the process looks like.

The extensions are built by creating an HTML page which is then embedded into the Contentful entry editor as an iframe. To communicate with the web app, extensions rely on the UI Extensions SDK.

<!doctype html>
<html lang="en">
    <meta charset="UTF-8"/>
    <title>Sample Editor Extension</title>
    <link rel="stylesheet" href="">
    <script src=""></script>
    <div id="content"></div>
    <script type="text/javascript">
      window.contentfulExtension.init(function (extension) {
        var value = extension.field.getValue()
        extension.field.setValue("Hello world!")

Extensions can be configured to work with specific types of fields by defining the metadata in the extension.json file:

  "id": "extension",
  "name": "My first extension",
  "srcdoc": "./app.html",
  "fieldTypes": ["Text"]

The contentful extension command line tool helps uploading extensions to the specified Contentful space.

# Configure your environment
$ export SPACE_ID=<yourSpaceId>

# Create an extension
$ contentful extension create --space-id $SPACE_ID

# Update the extension
$ contentful extension update --space-id $SPACE_ID

# Update the extension in the local dev environment
$ python -m SimpleHTTPServer
$ contentful extension update --space-id $SPACE_ID --force \ --src 'http://localhost:8000/app.html'

# Delete the extension 
$ contentful extension delete --space-id $SPACE_ID

The extension becomes available space-wide after it's been selected in the Appearance tab in the field settings.

What's coming next

These are just the first steps on our journey towards extensibility. This release doesn't include open-sourced core extensions, but that will definitely happen a bit later. We also plan to set up an "extensions store", where anyone could publish and share the extensions they've built with everyone in the Contentful developer community.

This release is special: we don't know — at all — what extensions will start appearing and how this SDK is going to be used. We're sure, though, that it will add just the right amount of customizability to our app, while still keeping the essentials minimal, clean and useful.

And now it's the time to try the new SDK. We're eager to see what you will build!

Further reading

About the author
Don't miss the latest
Get updates in your inbox
A monthly newsletter to help you build better digital experiences with Contentful.
add-circle arrow-right remove style-two-pin-marker subtract-circle