UI Extensions

UI extensions - File structure

Use the App Framework for any new projects. We recommend creating apps instead of UI extensions. Read the app FAQ to learn why.

The minimal file structure of extensions consists of two files:

  • An HTML file (e.g. index.html) which holds the code of the extension
  • A JSON file (e.g. extension.json) which describes the extension’s properties such as name or the supported field types

Let’s take a closer look at these files to understand what they do.

Source code: index.html

The index.html file is the building block for an extension and it is embedded into the Contentful entry editor as an <iframe>.

The index.html includes the following:

  • the markup code and the logic.

  • reference to the App SDK which,

    • enables the extension to communicate with the Contentful web app.

    • exposes the contentfulApp.init() method. This is the main entry point for all the extension-related code.

Following is an example of the contentfulApp.init() method:

1window.contentfulApp.init(function (extension) {
2  var value = extension.field.getValue();
3  extension.field.setValue('Hello world!');
4});
1<!doctype html>
2<html lang="en">
3  <head>
4    <meta charset="UTF-8"/>
5    <title>Sample Editor Extension</title>
6    <script src="https://cdn.jsdelivr.net/npm/@contentful/app-sdk@4"></script>
7  </head>
8  <body>
9    <div id="content"></div>
10    <script type="text/javascript">
11      window.contentfulApp.init(function (extension) {
12        var value = extension.field.getValue()
13        extension.field.setValue("Hello world!")
14      })
15    </script>
16  </body>
17</html>

Descriptor file: extension.json

The extension.json file, also known as the Descriptor file, is used to describe the properties of an extension. Although this file is optional, it is recommended to create it. The Contentful CLI is supporting descriptor files. Descriptor files should be committed to version control next to the source code of the extension as they describe the configuration fo the extension.

The following table describes the properties that can be set on an extension.

PropertyRequiredTypeDescription
idyes, if omitted it gets auto-generatedStringExtension id
nameyesStringExtension name
fieldTypesnoArray<String>*The field types of a content type where an extension can be used
srcsrc or srcdoc is requiredStringURL where the root HTML document of the extension can be found
srcdocsrc or srcdoc is requiredStringPath to the local extension HTML document
sidebarnoBooleanControls the location of the extension. If true it will be rendered on the sidebar

* Valid field types are: Symbol, Symbols, Text, Integer, Number, Date, Boolean, Object, Entry, Entries, Asset, Assets.

Following is an example of a extension.json file:

1{
2  "id": "extension",
3  "name": "My first extension",
4  "srcdoc": "./app.html",
5  "fieldTypes": ["Text"]
6}

Next steps