Contentful UI Extensions for Everyone 😁 🎉

Contentful allows users to install extensions to the web app interface so that the current user interface can be "extended" to look or do something different than what is presently available. If you aren't a developer-type, they may look intimidating to install at first but rest assured—after this workshop, you will be a UI extensions pro. 👍

Jump to:

• What is a UI extension and why do they matter?
• Who can make a UI extension?
• Where can I find example extensions?
• Okay, enough of the small talk—let's install an extension!
• FAQs

---

What is a UI extension and why do they matter?

You probably already use extensions everyday in your web browser. They allow you to customize your browsing experience and access other services outside what is native to your browser (such a 🌈 picker—I have this one installed!).

Contentful UI extensions are slightly different because users can't just go to a "store," browse for extensions, and click a button to install the extension. Contentful requires the extension code (plain HTML files) to be uploaded to Contentful in order for the user to be able to access the custom functionality. The extension code is then included in all of the code that makes up the web app (which is built on top of our Management API).

Giving users the ability to customize the web app is important because Contentful doesn't always know (or can accommodate) custom use cases. Also, sometimes extensions can help fill a gap in the interface for a feature that would be very helpful for our users (and may even be on our product roadmap) but is not built yet. An example would be our slug generator, which can now be added as an Appearance option for our short-text field. But did you know it was once a feature that was only available as a UI extension?

Who can make a UI extension?

Any user with some knowledge of code can write their own extension by using our UI Extensions SDK. 👊

Where can I find example extensions?

We have a Github repository with sample UI extensions and most recently, users are sharing their own creations here. 🍻

Okay, enough of the small talk—let's install an extension!

For the workshop, we will be installing a popular extension: Rich-text editor

This extension gives users another appearance option for the long-text field type.

What you will need

• A Contentful space ID
• Your personal access token
• The files for the extension in a folder on your desktop

Create a content type

To start, let's go into our Contentful space and create a sample content type that will use the the Text field (if you don't have one already). You can add a short-text Text field (I'm going to name mine Title) and a long-text Text field.

When you click on Create and configure > Appearance, you will see that we have five different built-in options for how this field can currently look right now: Single line, Multiple line, Markdown, Dropdown, and Radio. You can use the default appearance.

Save your content type.

Preparing to install the extension

In order to install the extension, we will be using the folder on our desktop that contains the two files we need for the extension:

Makefile

extension.json

index.html

package.json

Now, the next step is where it could look tricky (but it's really not!).

• Open the command line on your computer. For Mac users, you can find it from the Spotlight Search (cmd + space-bar) and typing in Terminal.

The command line is basically a way for you to "command" your computer what to do without having to use the user interface that comes with your computer.

✅ You may have heard about our CLI tools. Anytime you hear that, think "Command Line Interface."

We will be using a command called npm to perform the next few steps. This is something that needs to be installed on your computer first in order for you to be able to access the command. The easiest way to do it is to install Node.js.

• Once you have npm, install our CLI tool from the terminal.

• This is the command: npm install -g contentful-extension-cli

⚠️ For new extensions, use npm install -g contentful-cli since the extensions CLI is getting deprecated.

Installing the extension to your space

• Open the Makefile file from your text editor of choice.

• Add in your access token and space ID to the top two lines: export CONTENTFUL_MANAGEMENT_ACCESS_TOKEN=<your token here> export SPACE=<id of space where you want to install this extension>

• Save and close the file.

Now, from the command line, we are going to move into the folder where the files for the extension are stored. Any action we make in the command line moving forward will be using the contents in this folder.

• The command is: cd <yourFolder>

• Once you are in the extension folder, run this command to make sure you have all the dependencies of the extension on your computer: npm install

Dependencies are other packages in npm that this project uses. In our case, this project contains the contentful-extension-cli dependency.

• Next, run this command: make create

• This will upload and serve the extension from Contentful.

Time to test out the extension!

• Click into the content type we previously created (with the long-text field).
• Next to the long-text field, click on Settings > Appearance.

💥 💥 💥

• To test out your new editor, change the Appearance of your long-text field to Rich Text Editor.

• Click on Save and create a new entry!

✅ To see the extensions you have installed in your space, go to Space settings > Extensions.

FAQs

• Extensions are installed on a space-basis
• What fields can be changed using the UI extension? (https://www.contentful.com/developers/docs/concepts/editor-interfaces/)