This template can be used to jumpstart your own custom element development with Kontent.ai. It contains all the necessary tools for creating a new Custom Element, a UI extension for content editors.

You can inspire yourself by browsing already created integrations here.

If you wish to include your integration into the mentioned list, please add the kontent-ai-integration topic into your github integration repository.

Additional Kontent.ai GitHub resources and tutorials can be found on kontent-ai.github.io.

The integration is created with Create React App.

This template aims to showcase the possibilities. It is storing the data from the displayed input, it is observing another text element specified in the configuration, and displays the context provided by the Kontent.ai app.

It is also showcasing how you can select other content items as well as assets within the custom element. First you will need to install npm dependencies with npm install. Then use npm run build to build the integration or npm run start to start a local development server. See https://create-react-app.dev/docs/available-scripts for more scripts.

The element requires a sample configuration with one property like the one below, to showcase config handling.

{
  "textElementCodename": "<Codename of a text element that this custom element can read>"
}

Every Kontent.ai custom element needs the Custom Element API to work properly. You should include it in your html file like this: https://github.com/kontent-ai/custom-element-template-react/blob/e184179039aa705a82722d778e503dfb511f7115/public/index.html#L8-L10

If you want your custom element to look like a part of the Kontent.ai app, you'll need to include the Kontent.ai CSS file. You can find it here in this repository. You have to include the font file as well. https://github.com/kontent-ai/custom-element-template-react/blob/e184179039aa705a82722d778e503dfb511f7115/public/index.html#L5-L7

Before you start any interaction with the Kontent.ai app, you'll need initialize the custom element. You can do that by calling the init function from the provided API like so https://github.com/kontent-ai/custom-element-template-react/blob/e184179039aa705a82722d778e503dfb511f7115/src/IntegrationApp.tsx#L18-L29 and waiting until the callback you passed into the init function is called. You'll receive the custom element configuration object of your specification, as well as additional context - more on that in the documentation. You can leverage state in React to store the important configuration while setting it inside of the initialization callback.

const [config, setConfig] = useState<Config | null>(null);

useEffect(() => {
  CustomElement.init((element, context) => {
    if (!isValidConfig(element.config)) {
      throw new Error('Not the config this element expects');
    }
    setConfig(element.config);
    // more logic
  });
}, []);

In certain circumstances, the Kontent.ai app might instruct your custom element to display itself in a disabled state. Disabled state means that the value of your element cannot be changed. This can happen when the edited item is published (therefore cannot be edited), or the current user does not have permission to edit the custom element.

In order for the custom element to always have up-to-date information about the disabled state, you should:

1. Save the element.disabled flag from the argument of the init function. https://github.com/kontent-ai/custom-element-template-react/blob/e184179039aa705a82722d778e503dfb511f7115/src/IntegrationApp.tsx#L25
2. Subscribe for the flag changes with CustomElement.onDisabledChanged function. In React you can do that like so. https://github.com/kontent-ai/custom-element-template-react/blob/e184179039aa705a82722d778e503dfb511f7115/src/IntegrationApp.tsx#L36-L38
3. Use the flag in your custom element to prevent the user from editing anything as the Kontent.ai will refuse to save any changes when your element should be disabled.

You might also want to set the value of your custom element. The value can only be of type string or null (null represents no value and if the element is required having null as value will fail the item's validation). However, you can easily JSON.stringify and conversly JSON.parse any json-serializable the saved value. To save a value, simply call the CustomElement.setValue and pass it the value. This value is accessible through the Delivery API, and can be used and rendered on your website, or in your application.

In some cases, the default height of custom elements will not be enough for the application you are trying to render inside of it. In that case, you can set your custom height with the CustomElement.setHeight function. This resize function can be changed as the required height value itself changes, which helps you omit the unpleasant scrolling of the iframe your element is rendered in. In the following React example we update the element's size whenever some value affecting the element's size changes and set the height to the document's height with a minimum of 100px.

const updateSize = useCallback(() => {
  const newSize = Math.max(document.documentElement.offsetHeight, 100);

  CustomElement.setHeight(Math.ceil(newSize));
}, []);

useLayoutEffect(() => {
  updateSize();
}, [updateSize, currentValue, searchResults]);

You can find all of the available Custom Element functions in our Custom Element API reference.

For Contributing please see CONTRIBUTING.md for more information.

Distributed under the MIT License. See LICENSE.md for more information.