Extend the content editing features with custom elements

What is a custom element?

Custom elements are small HTML apps that exist in a sandboxed <iframe> in Kontent.ai and interact with Kontent.ai through the Custom Elements API. They enable you to extend the default content type elements to include the functionality you need.

Have a look at a few examples of extending Kontent.ai capabilities using custom elements:

• Enable selecting assets from a 3rd-party digital asset management system (DAM), such as Bynder.
• Add an AI-powered content personalization system like Recombee.
• Let your content creators write the way they're used to by implementing a custom Markdown WYSIWYG text editor.

Available custom elements

Check out the available custom elements created and maintained by our community. Choose a custom element that suits your needs, host the element securely, and add the element to Kontent.ai.

Host your custom element securely

Custom elements are HTML applications loaded in an <iframe>. They need to be hosted so the browser can fetch the file.

You need to host your custom element yourself or use a service like Netlify.

• If you decide to host your custom element on your own servers, you need to:
  • Set up the appropriate domain certificate for the server.
  • Make sure the server sends the X-frame-options (or Content-Security-Policy) header to specify an allowed origin, in this case, https://app.kontent.ai. For more details, see the MDN Web Docs.
• If you'd like to test your custom element locally, use a secure tunnel to your localhost. You can use a service like ngrok that connects to your local application and provides a secure public URL for access from Kontent.ai.

Your custom element is separated from the rest of Kontent.ai through the sandbox attribute on the <iframe>. The following sandbox flags are enabled:

• allow-forms – allows form submission
• allow-scripts – allows JavaScript to run inside the <iframe>
• allow-popups – allows popups
• allow-same-origin – allows the document to maintain its origin
• allow-modals – allows modal dialogs
• allow-storage-access-by-user-activation – allows storage access (e.g. cookies or local storage)
  • Keep in mind that this is a 3rd party context. You need to set cookies attributes SameSite=None; Secure to use cookies.

Add the custom element to your project

To have your custom element appear in content items, you need to add it to the content type of the items.

1. In Content model, open a content type for editing.
2. Click Custom element on the right to add a new custom element.
3. Name the element.
4. In Hosted code URL (HTTPS), paste the URL where you host your custom element.
5. (Optional) In Parameters {JSON}, enter JSON configuration parameters if your custom element needs any.
6. Click Save changes.

If you set the custom element as required, Kontent.ai checks if the element contains any value. Any other value than null is considered valid and won't prevent an item from getting published.

How to use JSON parameters

The JSON parameters enable you to configure your element and reuse it in various contexts. In some cases, you may want different settings for different projects, content types, or even elements. 

For example, a custom element that provides a WYSIWYG editor might be configured to accept JSON parameters for activating and deactivating spellcheck and tools like inserting images. This way, you would enable spellcheck or images only in places where it makes sense.

You might also change the custom editor's HTML so that all its features can be activated and deactivated via JSON parameters. That way, each custom element can have a different feature set.

Default values for custom elements

You can use the JSON parameters to set a default value for your custom element.

For example, you can add {"default_value": "Enter your text here"} to the JSON parameters. When you initialize your element, check whether there's already some value in the element. If there isn't, use the value from the JSON parameters.

Authoring experience with custom elements

Once you've added your custom element to a content type, you can use the custom element in content items. For example, if you add a custom Markdown editor, it looks like this:

When you get the content item via Delivery API, you get markdown content in the custom element's value.

JSON
"markdown_editor": {
  "type": "custom",
  "name": "Markdown editor",
  "value": "## Hello world\nThis is a sentence with **bold** and *italics* in it.\n> And blockquotes!"
}
"markdown_editor": {
  "type": "custom",
  "name": "Markdown editor",
  "value": "## Hello world\nThis is a sentence with **bold** and *italics* in it.\n> And blockquotes!"
}