By Eugene Kudashev, on Jul 6, 2016

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

Imagine you're responsible for maintaining the CMS at your company. Your editor comes to you and says: "Hey, John, 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 be able 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.

Examples

1. Third-party service integration: Wistia

ui-extensions-sdk wistia

This extension connects a Wistia video project to Contentful to store a video ID in the entry. In general, any kind of third-party data can be integrated into the web app, so that editors have direct, seamless access to that content.

2. Customize existing fields: alternative JSON editor

ui-extensions-sdk json-form-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 an alternative 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.

3. Adding new features: a diff field extension

ui-extensions-sdk diff

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">
  <head>
    <meta charset="UTF-8"/>
    <title>Sample Editor Extension</title>
    <link rel="stylesheet" href="https://contentful.github.io/ui-extensions-sdk/cf-extension.css">
    <script src="https://contentful.github.io/ui-extensions-sdk/cf-extension-api.js"></script>
  </head>
  <body>
    <div id="content"></div>
    <script type="text/javascript">
      window.contentfulExtension.init(function (extension) {
        var value = extension.field.getValue()
        extension.field.setValue("Hello world!")
      })
    </script>
  </body>
</html>
 

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>
$ export CONTENTFUL_MANAGEMENT_ACCESS_TOKEN=<yourAccessToken>

# 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.

ui-extensions-sdk appearance tab

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!