Custom elements JavaScript API

Inclusion in your app

When implementing your custom elements, you need to reference the Custom Elements JS API in your HTML5 app.

JavaScript
<script src="https://app.kontent.ai/js-api/custom-element/v1/custom-element.min.js"></script>
<script src="https://app.kontent.ai/js-api/custom-element/v1/custom-element.min.js"></script>

For more details, see our tutorial on Integrating your own content editing features.

init method

Use the init method to initialize your custom element.

The init method expects a callback function which takes element and context as parameters. This callback function is called once your custom element is registered within Kontent.ai.

JavaScript
CustomElement.init(callback);
CustomElement.init(callback);

Context object

When using the custom element in a content component, the Context object refers to the parent content item of the content component, not the component itself. It's currently not possible to retrieve information about the component or access its other elements.

Element object

setValue method

Use the setValue method to set a custom element value. When the value is set to null, the element is considered empty.

If you want the custom element content to be searchable in the content items list, specify the keywords or the plain text using value object.

If a custom element is set as required in the UI, Kontent.ai checks the element's value. Any value other than null is considered a valid value and won't generate a validation error message.

Custom elements can contain up to 100,000 characters. If an element exceeds this number, Kontent.ai will display an error.

JavaScript
CustomElement.setValue(value: string | null | ValueObject);
CustomElement.setValue(value: string | null | ValueObject);

ValueObject object

onDisabledChanged method

Use the onDisabledChanged method to define what should happen with a custom element when it's disabled for editing. The method takes a callback function.

When disabled, the element is in read-only mode. This means that the element is shown in a content item but cannot be changed.

For example, custom elements can be disabled in these cases:

• The content item is published.
• User is viewing an older version of a content item.
• User doesn't have editing permissions.

JavaScript
CustomElement.onDisabledChanged(callback);
CustomElement.onDisabledChanged(callback);

setHeight method

Use the setHeight method to set a custom height of a custom element. The value will be set in pixels.

JavaScript
CustomElement.setHeight(height);
CustomElement.setHeight(height);

getElementValue method

Use the getElementValue method to retrieve the value of a different element. You can retrieve another element's value even if the custom element is disabled.

The getElementValue method works on elements that are:

• Used in the same content group as the custom element itself.
• Specified in the custom element's configuration, specifically, in the Allow the custom element to read values of specific elements field.

If you need to get values of multiple elements, call the getElementValue method for each such element. If you need to get the value multiple times, call the method multiple times.

JavaScript
CustomElement.getElementValue(elementCodename, callback);
CustomElement.getElementValue(elementCodename, callback);

Data type of content elements

• Custom element – string
• Date & Time – ISO-8601 formatted string
• Multiple choice – array of selected options. Each option is returned as an object based on the following schema: { id: <uuid>, name: <string>, codename: <string> }.
• Text – string
• URL slug – string

Other content elements are currently not supported.

observeElementChanges method

Use the observeElementChanges method to receive notifications about changes in other elements.

The observeElementChanges method can listen to any element changes and does not depend on the list of elements allowed for reading.

The observeElementChanges method does not return a specific element value but only notifies that the change occurred. The method takes a callback function as a second parameter. Use this method together with the getElementValue method to keep updated information about an element value.

JavaScript
CustomElement.observeElementChanges(elementCodenames, callback);
CustomElement.observeElementChanges(elementCodenames, callback);

observeItemChanges method

Use the observeItemChanges method to receive notifications about changes in the item.

The observeItemChanges method can listen to changes of the item's attributes – its name, codename, or collection.

The method only notifies about the change, it doesn't return the new value of the changed attributes. It takes a callback function that is called whenever any of the attributes is changed. The callback function is called with a parameter that contains the item's new details.

JavaScript
CustomElement.observeItemChanges(callback);
CustomElement.observeItemChanges(callback);

ItemChangedDetails object

selectAssets method

Use the selectAssets method to enable the custom element to select assets from Kontent.ai.

The method takes a config object and, if a user selects assets from the dialog, returns a promise with an array of asset references containing the selected asset's ID. If the selection dialog is closed, the method returns null.

JavaScript
CustomElement.selectAssets(config: Config): Promise<AssetReference[] | null>
CustomElement.selectAssets(config: Config): Promise<AssetReference[] | null>

Config object

AssetReference object

The object containing an ID reference to the selected asset.

getAssetDetails method

Use the getAssetDetails method to get metadata about a specific asset. After getting IDs with the selectAssets method, you can then get more information about each of the assets returned.

The getAssetDetails method takes an array of asset IDs as strings and returns a promise with an array of asset objects. The method returns a null if the specified items don't exist.

JavaScript
getAssetDetails(assetIds): Promise<Asset[] | null>
getAssetDetails(assetIds): Promise<Asset[] | null>

Asset object

Asset description object

selectItems method

Use the selectItems method to enable the custom element to select content items from Kontent.ai.

The method takes a config object and, if a user selects content items from the dialog, returns a promise with an array of content item references containing the selected item's ID. If the selection dialog is cancelled, the method returns null.

JavaScript
CustomElement.selectItems(config: Config): Promise<ContentItemReference[] | null>
CustomElement.selectItems(config: Config): Promise<ContentItemReference[] | null>

Config object

ContentItemReference object

getItemDetails method

Use the getItemDetails method to get details about a specific content item. After getting IDs with the selectItem method, you can then get details about each of the items returned.

The getItemDetails method takes an array of content item IDs as strings and returns a promise with an array of content item objects. The method returns a null if the specified items don't exist.

JavaScript
CustomElement.getItemDetails(itemIds): Promise<ContentItem[] | null>
CustomElement.getItemDetails(itemIds): Promise<ContentItem[] | null>

ContentItem object