Features • Demo • Deploy • Configuration • Saved value • Developing • Contributors • License • Resources

This custom element extension for Kontent.ai allows users to search and link selected products from commercetools into their structured content.

Features

• Editors can
  • Search for products in the commercetools project in all languages
  • Select a single product (or one of its variants)
  • Select multiple products (or their variants)

The element also offers an optional debug panel for diagnostics.

Demo

Quick Deploy

Netlify has made this easy. If you click the deploy button below, it will guide you through the process of deploying it to Netlify and leave you with a copy of the repository in your account as well.

Commercetools setup

In order to use this custom element extension with your commercetools account, you'll need to set up the integration in your Merchant Center.

Adding a new API client

• The custom element will be connecting to your commercetools account and searching for products to include into your Kontent.ai content item element. In order to set up this communication, a new API client has to be created under Settings -> Developer settings -> Create new API client.

• Next, a dialog for your Kontent.ai API client will be opened. Fill out the Name input field and under Scopes select Products(all) and Project Settings under the View category. This will give the extension read-only access to your product list, so it can be searched through while linking products to your content in Kontent.ai.
• After your scopes and client name has been put in, click the Create API client button in the top right of the screen.

• All the important information you'll need to set up the custom element will be right in front of you.

• Copy all the generated credentials as these will be needed for the custom element setup that takes place inside the Kontent.ai application. The following section describes each of the generated settings and shows you, how to create the final configuration object for your element.

⚠ WARNING: You won't be able to access the credentials screen once you close it. Be sure to copy and place all the generated credentials into your custom element configuration, otherwise, you'll be forced to re-create the API client.

• Once you configure your custom element with the generated credentials, you can close the credentials window and confirm, that your API client has been successfully created.

Configuring the Custom Element

You will need to add the custom element to a content type filling in the hosted code URL and the following JSON parameters:

Name	Type	Description
isMultiSelect	boolean	If set to true, it will be possible to select multiple products. If set to false, it will be possible to only select a single product
commercetools	object	This contains all the details required to connect to the commercetools API. The values for this object will be derived from an API client that you configure in commercetools with the exception of the defaultCulture. When generating the API client, be sure to select the view_products and view_project_settings scopes.
commercetools.defaultCulture	string	Set this to the IETF language tag of the language in commercetools to use by default for search.
commercetools.projectKey	string	This is the commercetools project key.
commercetools.clientId	string	This is the commercetools API client ID.
commercetools.secret	string	This is the commercetools API client secret.
commercetools.oauthUrl	string	This is the base URL to use for authenticating with commercetools.
commercetools.apiUrl	string	This is the base URL to use for commercetools API calls.
commercetools.scope	string	This is the list of scopes that the client has. This should include the view_products and view_project_settings scopes.

Sample parameters JSON:

{
  "isMultiSelect": true,
  "commercetools": {
    "defaultCulture": "en",
    "projectKey": "your-project",
    "clientId": "your-client-id",
    "secret": "your-client-secret",
    "oauthUrl": "https://auth.sphere.io",
    "apiUrl": "https://api.sphere.io",
    "scope": "view_products:your-project view_project_settings:your-project"
  }
}

What is Saved

The custom element will store the selected product's information in the following format:

[{
  "id": "<GUID_OF_PRODUCT>",
  "variantId": "<Variant_ID>",
  "culture": "<IETF_LANGUAGE_TAG>"
}]

This value will be accessible though the Kontent.ai Delivery API once the content item, containing the custom element, will be saved (through preview), or published (production).

Developing

# Initial project setup
$ npm install

# Compile and minify for production
$ npm run build

# Compile and run on local server
$ npm start

The custom element is created with Create React App.

Contributors

We have collected notes on how to contribute to this project in CONTRIBUTING.md.

License

MIT

Additional Resources

• Kontent.ai Integration documentation
• Custom Element documentation
• Custom Element API reference