Kontent.ai parameters and enhancers

Parameters define the data that can be authored when components become part of a composition and can connect to external systems. Parameter enhancers alter the value of parameters on a component instance. For a CMS like Kontent.ai, the enhancer picks up that parameter and fetches the actual data from the CMS.

Usage considerations

Parameters are present for backwards compatibility with the earlier version of Uniform Mesh and reserved for special cases where you require control over how content is fetched from Kontent.ai. This approach requires manual addition of enhancers into your application code.

If you start a new project, Uniform highly recommends skipping this section and using Data Types instead.

After you install the Kontent.ai integration, new parameter types are available to be added to components. You can use these to incorporate content from Kontent.ai into your components and compositions.

In order to use Kontent.ai parameter types, credentials need to be saved on the integration settings page:

  1. In Uniform, open your project.

  2. Navigate to the Integrations tab.

  3. Scroll to the section Added integrations.

  4. Click Kontent.ai.

    no-linked-sources
    Once the integration is added you can link content sources.

  5. Click the round (+) button.

    source-configuration-empty
    The screen to configure and link to your Kontent.ai environment.

    The Delivery API Key must have permissions for content preview and also secure access if the project is configured to require it.

  6. Enter the required values and click Save.

    linked-source
    The screen once you've connected to your content source.

For users to select an item from Kontent.ai, you must add a parameter to a component. The parameter is used to store the identifier to the selected item when the user selects an item.

  1. In Uniform, navigate to your component.

  2. Add a new parameter using the parameter type Kontent.ai.

    add-kontentai-parameters
    Locate the available Kontent.ai parameters when adding a parameter to a component.

  3. The following parameters are available:

    NameDescription
    Single itemSelect a single item from Kontent.ai.
    Multiple itemsSelect multiple items from Kontent.ai.
    QueryThe query archetype will return a list of content entries containing the queried terms.

When you select a parameter to be added to the component, complete the following fields:

NameDescriptionNotes
NameA text field to enter a descriptive name for the parameter or its purpose.
Public IDName that uniquely identifies the parameter. This value is available to developers, and is auto generated from the Name given. It can't be changed once it's created.

Help text

A user is responsible for setting a value on the parameter. This text appears below the user-interface available for setting the parameter value.

configure-help-text
The user interface for setting the value on a text parameter with help text set to 'Enter a short description of the event.'
parameter-help-text
The help text in context of a composition.
Select Linked SourceA drop down list of available Kontent.ai sources.
Allowed Content TypesThe content types from Kontent.ai you want available when authoring compositions
RequiredIndicates whether the value is required when the component is used.

Click Save to save your changes. Opening the save menu lets you save and add another parameter. Make sure you then click Save to save the changes to the component.

Once the parameters are added and available in a component they can be authored within compositions in Canvas.

Single entry#

single-entry
The configuration options to select a single item from Kontent.ai.
multiple-entries
The configuration options to select multiple items from Kontent.ai.
query
The configuration options to query for a list of content entries containing the queried terms.

When an item is selected, Uniform only stores the identifier for the item. Your front-end application must retrieve the details for the item. Uniform provides an enhancer to simplify this process.

tip

Using the enhancer provided by Uniform saves you from having to write logic to interact directly with Kontent.ai.

The following is an example of what Uniform stores for the parameters:

Single entry#

{ "type": "kontentEntry", "value": { "entryCodename": "######################", "source": "######################" } }

There are two identifiers in this value:

  1. The item that was selected.
  2. The source key for the linked content source.
{ "type": "kontent-ai-multipleItems", "value": { "itemsCodenames": "######################", "source": "######################" } }

There are two identifiers in this value:

  1. The items those were selected.
  2. The source key for the linked content source.
{ "type": "kontent-ai-query", "value": { "options": "######################", "source": "######################" } }

There are two identifiers in this value:

  1. The options for query those were selected.
  2. The source key for the linked content source.

Uniform provides an enhancer so you don't need to write the API calls to Kontent.ai to retrieve data for items.

  1. In Kontent AI, get the following values:

    • Environment ID
    • Delivery API key

  2. Add the following npm packages to your front-end application:

    @kontent-ai/delivery-sdk @uniformdev/canvas @uniformdev/canvas-kontent

  3. Add the following import statement:

    import { DeliveryClient } from '@kontent-ai/delivery-sdk';

  4. Create Kontent Delivery client:

    const client = new DeliveryClient({ environmentId: '!!! YOUR KONTENT PROJECT ID !!!', previewApiKey: 'Bearer !!! YOUR KONTENT DELIVERY API KEY (OPTIONAL) !!!', defaultLanguage: '!!! YOUR KONTENT LANGAUGE CODENAME or default !!!', });

    About this step

    We recommend you moving the Kontent credentials to environment variables rather than hard-coding them in the front-end app.

  5. In a text editor, open the file where you retrieve the composition definition from Uniform.

    About this step

    You are looking for the code calls the async function getComposition. The code below assumes the object returned is set in a variable composition.

  6. Configure enhancer for the parameters:

Single entry#

  1. Add the following import statements:

    import { EnhancerBuilder, enhance } from '@uniformdev/canvas'; import { createKontentEnhancer, KontentClientList, CANVAS_KONTENT_PARAMETER_TYPES, } from '@uniformdev/canvas-kontent';

  2. Add the following code:

    if you want to use single source

    const clientList = new KontentClientList({ client }); const kontentEnhancer = createKontentEnhancer({ clients: clientList });

    if you want to use multiple sources

    const clientList = new KontentClientList([{ client }, { source: 'source name', client: Another_Kontent_Delivery_Client }]); const kontentEnhancer = createKontentEnhancer({ clients: clientList });

  3. Add the following code:

    await enhance({ composition, enhancers: new EnhancerBuilder().parameterType( CANVAS_KONTENT_PARAMETER_TYPES, kontentEnhancer ), context: {}, });

  1. Add the following import statements:

    import { EnhancerBuilder, enhance } from '@uniformdev/canvas'; import { createKontentMultiEnhancer, KontentClientList, CANVAS_KONTENT_MULTI_PARAMETER_TYPE, } from '@uniformdev/canvas-kontent';

  2. Add the following code:

    if you want to use single source

    const clientList = new KontentClientList({ client }); const kontentEnhancer = createKontentMultiEnhancer({ clients: clientList });

    if you want to use multiple sources

    const clientList = new KontentClientList([{ client }, { source: 'source name', client: Another_Kontent_Delivery_Client }]); const kontentEnhancer = createKontentMultiEnhancer({ clients: clientList });

  3. Add the following code:

    await enhance({ composition, enhancers: new EnhancerBuilder().parameterType( CANVAS_KONTENT_MULTI_PARAMETER_TYPE, kontentEnhancer ), context: {}, });

  1. Add the following import statements:

    import { EnhancerBuilder, enhance } from '@uniformdev/canvas'; import { createKontentQueryEnhancer, KontentClientList, CANVAS_KONTENT_QUERY_PARAMETER_TYPE, } from '@uniformdev/canvas-kontent';

  2. Add the following code:

    if you want to use single source

    const clientList = new KontentClientList({ client }); const kontentEnhancer = createKontentQueryEnhancer({ clients: clientList });

    if you want to use multiple sources

    const clientList = new KontentClientList([{ client }, { source: 'source name', client: Another_Kontent_Delivery_Client }]); const kontentEnhancer = createKontentQueryEnhancer({ clients: clientList });

  3. Add the following code:

    await enhance({ composition, enhancers: new EnhancerBuilder().parameterType( CANVAS_KONTENT_QUERY_PARAMETER_TYPE, kontentEnhancer ), context: {}, });

    About this step

    This registers the enhancer to be used for any occurrence of the Kontent AI Item parameter.

Next steps

Now, the parameter value in the composition is mutated to include the field values for the selected Kontent AI item (instead of just being identifiers).

Last modified
Next
Uniform elements in Kontent.ai