By Allan Thraen, on Jun 17, 2019

Getting started with Contentful UI Extensions: Part 1

I was recently invited to give a talk at a Contentful meetup in Copenhagen. I'm passionate about integrating and building add-ons for content management, so the first topic that came to mind was introducing newbies to the fun of building UI extensions that enhance the editorial experience within Contentful. This series of blog posts is based on that presentation.

Why extend?

Now, why would you want to extend a perfectly good editorial interface like Contentful in the first place? It’s pretty straight forward. The better the editorial experience you can provide your content workers (i.e. editors), the more efficient they'll be - and the better content they'll produce in the end. Better content SEO and/or more conversions will lead to improved profits, just as improved efficiency can lead to saved costs. However, make sure that your improvements are just that – improvements. There are plenty of examples of add-ons and extensions that simply complicate things without solving any problems. This results in a monster of a CMS with dependencies through the roof.

Customizing the editorial process

The process of customizing the editorial process goes beyond UI Extensions. In fact, one of the simplest ways to improve content quality is simply to add the proper validation and appearance to your fields. If a field has to be one of a short list of values, don't just have a textbox. Instead, have a dropdown list to avoid confusion and save typing time. And if a field should always hold an email, ensure that it's validated to contain just that and nothing else. However, it can be a tricky balance to maintain just enough validation and lockdown while still empowering the editors to achieve their goals.

In Contentful there is quite an impressive API available, so it's also possible to achieve many editorial goals using that. For instance, connecting the webhooks and API to a service like Zapier or Microsoft Flow makes it possible to have content pushed to and from other sources. It’s also possible to connect your blog section to a tool like Open Live Writer so that bloggers can use a desktop app to create content.

Finally, there is the approach of building UI Extensions, which I'll describe in more detail now.

UI Extension Types

Since Contentful is a complete multi-tenant SaaS based system, all UI extensions are essentially relying on iframes with code executed in the browser to function.

As I write this blog post, there are essentially 4 main UI Extension Types:

  • Field Extension. This is by far the most common. This is simply where you change the appearance of fields of a certain type used on a certain content type.
  • Entry Extension. This fairly-recent addition is the ability to change the appearance of the entire edit-interface for a certain content type.
  • Sidebar Extension. This started off being just field extensions, visually placed in the right-hand sidebar. But now, it's also possible of adding them to a custom sidebar for any content type without being attached to a specific field.
  • Dialog Extension. This is not really an extension point in itself, but it deserves a mention. Any of the above extensions can use custom dialogs to improve the user experience.

Extensions typically consist of at least one html file and one json file (and whatever dependencies they might need) and can be stored either in a storage provided by Contentful or hosted by yourself (or on a service such as Github).

Example: Color Picker Field

colorpicker

The first example I'll share is an ultra-simple color picker. Sometimes you want to give the editors the power to pick a color, such as a background color or a text color. The best approach is to give them a dropdown with limited options that fit with your corporate visual identity. But we don't have time for rational solutions and the following color picker is more fun to make.

The simplest approach is to create the extension directly in Contentful. To do this, go to Settings Extensions and you can create a new extension just as easily as you would create a piece of content.

extensionmenu

As mentioned, create a new extension, give it a name and select which field types it should apply to (assuming you’re creating a field extension that alters the appearance of a specific field). You can also leave the field types unchecked, and instead use your extension as an entry extension. Or check the 'Sidebar' checkbox and it will be available in a custom sidebar.

Regarding the field types, one thing that had me baffled a little was the terminology: A symbol is just a short string (<256 chars). Text is a long string. An object can hold any json object. Entry and asset are really just references. The plural form (symbols, entries, assets) can hold an array of that type (matching with the "This is a list" checkbox in the content type modelling tool).

colorextensioneditor

Notice how you can pick to have it self hosted or hosted by Contentful (the default).

If it's hosted by Contentful, you can edit the source directly below, in the editor.

The code you are editing is basically an HTML file. The file typically, as a minimum, contains a javascript reference to the contentful-ui-extensions-sdk (hosted on a CDN). And it comes with a premade piece of javascript code that gives you an 'api' object with full access to all the operations you could want.

In the case of my Color Picker, I found the jscolor library and reference for that, as well as a reference to the default contentful UI extensions css file. I find this the simplest approach, but you can also choose to go down the path of using Forma 36 to get the full Contentful design.

This is my html/js code I entered:

As you can see I've tried to fill the code with step-by-step comments. Pretty straight forward, right?

Now we can save our extension and start using it.

In order to use it on a field, we basically have to go to a content type, add a field of the right type (in this case short string) and select the Color Picker under appearance - and we're in business!

color-contenttype

I hope you enjoyed this post!

In the next post in this series we'll have a look at another field extension that also takes certain predefined parameters and is uploaded and managed through the CLI. Later in the series we'll explore the sidebar extensions and see just how much power the javascript SDK gives you! Drop a comment below with questions or feedback – it’s much appreciated.

This article was originaly published on Codeart.dk.

Allan Thraen
Copenhagen, Denmark

Allan Thraen is the founder of CodeArt, a technical agency in Denmark focused on integrating, extending and optimizing how organizations work with the web with a focus on content management, search and AI. Allan is a frequent tech blogger and often gives original developer talks at meetups and industry conferences.

Community Contributor
Become a contributer