This repository provides core field editors and samples of Contentful extensions, developed using the UI Extensions SDK.
- In core field editor extensions you will find code of some of our core editor components.
- Custom extension examples is a curated list of common problems solvable with an extension.
- Managing extensions explains how to manage extensions in a Contentful space using our
CLI. - Resources offers a collection of useful links.
We're progressively opening our core field editors within this repository, allowing you to understand how each component works, and create your own extensions based on them rather than starting from scratch.
Each example comes with a README file explaining how to build and use it. They're showing various types of integrations with popular frameworks or build systems like:
- npm
- Gulp
- Makefile
- Webpack
- Babel
List of examples:
Basic Rating Dropdown is a basic extension meant to help you get started with custom extensions development. Uses a dropdown to change the value of a number field and makes some CMA requests.
Rich Text Editor integrates the Alloy rich-text/HTML editor to edit “Text” fields. Great to personalize the entry editor and enable HTML editing as an alternative to Markdown.
Slug Generator automatically generates its value from an entry's title field. For example typing “Hello World” into the title field will set the extensions input field to “hello-world”. It will also check the uniqueness of the slug across a customizable list of content types.
JSON Editor provides a JSON formatter and validator based on the Codemirror library. It can be used with fields of type “Object”.
JSON Form Editor integrates the JSON Editor library to display an edit form based on a predefined JSON Schema. Form input gets stored as a JSON object.
Translator translates text from the default locale to other locales in a space using the Yandex translation API.
YouTube ID extracts the video id from a valid YouTube URI. Useful as a simple way to integrate with 3rd party media services.
Diffing Published and Draft shows the diff between draft value and published value of a short text field.
Chessboard displays a chessboard and stores the board position as a JSON object. You can drag pieces on the chessboard and the position data will be updated automatically. The extension also supports collaborative editing.
External API demonstrates accessing an external API and storing the underlying data within contentful.
Optimizely Audiences demonstrates how structured content can be tagged with audience Ids loaded from an Optimizely project.
Shopify integrates your shopify account to search and select products to display on your frontend.
Marketo forms adds the ability to get all the Marketo provided context of your forms into your Contentful entry.
tl;dr This section explains how to manage extensions in a Contentful space through the Contentful CLI.
Extensions are managed within a Contentful space through the Content Management API's extensions endpoint. To make it more convenient we added support for extensions to the Contentful CLI.
- Installed Contentful CLI so the
contentfulcommand is available - An account at Contentful with admin access to a space
Extensions can be hosted within the Contentful web app in two forms:
- Internally hosted: The extension's source code was uploaded to Contentful as a bundled string where all local dependencies need to be inlined into one single file. Internal extensions are uploaded by using the
srcdocproperty and have a limit of 200kb. Use internal hosting if you don't want to host anything on your own and can accept the drawbacks (need for a non-standard build, file size limitation). Note that internal hosting is not supported on Internet Explorer and Microsoft Edge. - 3rd party hosted: The extension's source code was uploaded to a 3rd party server by using the
srcproperty. Relative links in the root HTML are supported as expected. Use 3rd party hosting when you want to be as flexible as possible with your development and deployment process.
The following table describes the properties that can be set on an extension.
| Property | Required | Type | Description |
|---|---|---|---|
| id | yes | String | Extension id |
| name | yes | String | Extension name |
| fieldTypes | yes | Array<String> * | The field types of a content type where an extension can be used |
| src | ** | String | URL where the root HTML document of the extension can be found |
| srcdoc | ** | 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.
** One of src or srcdoc is required.
The properties of an extension can be stored in a descriptor JSON file for convenience. The descriptor file can be passed to the CLI so the properties don't have to be provided individually.
{
"id": "foo-extension",
"fieldTypes": ["Symbol", "Text"],
"name": "My wonderful foo extension",
"sidebar": false,
"src": "https://foo.com/extension"
}{
"id": "foo-extension",
"fieldTypes": ["Symbol", "Text"],
"name": "My wonderful foo extension",
"sidebar": false,
"srcdoc": "./dist/bundle.html"
}contentful extension is composed of 5 subcommands that you can use to manage extensions:
Create
contentful extension create [options]
Creates an extension for the first time. Successive modifications made to the extension to use the update subcommand.
Update
contentful extension update [options]
Modifies an existing extension.
Delete
contentful-extension delete [options]
Permanently deletes an extension.
Read
contentful extension get [options]
Reads the extension payload from Contentful.
List
contentful-extension list [options]
Use this subcommand to see what extensions are created for a given space.
To learn how the commands work in the CLI, either use the CLI's inline help
contentful extension --helpor head over to the documentation of the CLI.
Contentful API use optimistic locking to ensure that accidental non-idemptotent operations (update or delete) can't happen.
This means that the CLI needs to know the current version of the extension when using the update and delete subcommands. On these case you have to specify the version of the extension using the --version option.
If you don't want to use the --version option on every update or deletion, the alternative is to use --force. When the --force option is present the CLI will automatically use the latest version of the extension. Be aware that using --force option might lead to accidental overwrites if multiple people are working on the same extension.
If you need to manage extension programmatically consider using one of the Content Management SDKs we are offering.