UI extensions - File structure
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 asnameor 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:
window.contentfulApp.init(function (extension) {
var value = extension.field.getValue();
extension.field.setValue('Hello world!');
});<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8"/>
<title>Sample Editor Extension</title>
<script src="https://cdn.jsdelivr.net/npm/@contentful/app-sdk@4"></script>
</head>
<body>
<div id="content"></div>
<script type="text/javascript">
window.contentfulApp.init(function (extension) {
var value = extension.field.getValue()
extension.field.setValue("Hello world!")
})
</script>
</body>
</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.
| Property | Required | Type | Description |
|---|---|---|---|
id |
yes, if omitted it gets auto-generated | String |
Extension id |
name |
yes | String |
Extension name |
fieldTypes |
no | Array<String>* |
The field types of a content type where an extension can be used |
src |
src or srcdoc is required |
String |
URL where the root HTML document of the extension can be found |
srcdoc |
src or srcdoc is required |
String |
Path to the local extension HTML document |
sidebar |
no | Boolean |
Controls 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:
{
"id": "extension",
"name": "My first extension",
"srcdoc": "./app.html",
"fieldTypes": ["Text"]
}Next steps
Not what you’re looking for? Try our FAQ.
