Sitecore XM and XP parameters

After you install the Sitecore XM/XP integration, the following parameter types are available. You can use these to incorporate content from Sitecore XM/XP into your components and compositions.

Parameter typeDescription
Sitecore ItemSelect one or more items from Sitecore.

This parameter type allows a Uniform user to select one or more Sitecore items.

To allow a user to select one or more items from Sitecore, you must add a parameter to a component. The parameter is used to store the identifiers to the selected items when the user selects items.

  1. In Uniform, navigate to your component.

  2. Add a new parameter using the parameter type Sitecore Item.

  3. The following values can be specified:

    NameDescription
    Allowed TemplateIf you select a template, the user will only be able to select an item based on the selected template. If not template is selected (the default), then the user can select any item.
    DataSource LocationsDefines what items the user can select from. It can be either a specific item (defined by its ID) or an item relative to the current page item (defined by relative path, such as ./data/banners). The relative path option has 2 requirements:
    • the root component definition (component public ID: page) must have the page item parameter defined (parameter public ID: pageitem)
    • the pageitem parameter of the root component of the composition must point to an existing item
    Allow Selecting Multiple ItemsIndicates whether the user can select only one item (the default), or more than one item.
    RequiredIndicates whether the value is required when the component is used.
    parameter-config
    Sitecore Item parameter configuration.

When you use a component with a Sitecore Item parameter, by default no item will be selected. You must select an item.

  1. Click Select new item.

    edit-value-default

  2. Find the item you want to select.

    select-new-item

  3. Click Select to save your selection.

  4. You will see details about the item you selected, including the path and some metadata.

    item-selected

    About this step

    After your selection is saved, you are presented with the following options:

    • If you want to edit the selected item in Sitecore, click Edit.
    • If you want to un-select the item, click Unlink.
    • If the option to select multiple items was specific for the parameter, you can select additional items by clicking Select new item.

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 Sitecore.

tip

If you are migrating Sitecore renderings & layouts, that section of the documentation provides specific information on how to configure an enhancer.

The following is an example of what Uniform stores for the parameter.

{ "type": "sitecoreItem", "value": "######################" }

The item ID is stored as the value. If multiple items are selected, the value is a string of the selected item IDs separated by the pipe character.

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

  1. In Sitecore, get the following values:

    • URL of your Sitecore instance
    • Sitecore API key
    • Site configuration name

    About this step

    These are the same values used to configure the Sitecore integration in Canvas.

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

    @uniformdev/canvas-sitecore

  3. 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 asynchronous function getComposition. The code below assumes the object returned is set in a variable composition.

  4. Add the following import statements:

    import { EnhancerBuilder, enhance } from '@uniformdev/canvas'; import { CANVAS_SITECORE_PARAMETER_TYPES, createItemEnhancer, } from '@uniformdev/canvas-sitecore';

  5. Add the following code:

    const enhancer = createItemEnhancer({ config: { UNIFORM_API_URL: '!!! YOUR SITECORE API URL !!!', UNIFORM_API_SITENAME: '!!! YOUR SITECORE SITE NAME !!!', } });

    About this step

    Uniform recommends you moving the Sitecore credentials to environment variables rather than hard-coding them in the front-end app.

  6. Add the following code:

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

    About this step

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

Next steps

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

Last modified
Next
Sitecore data types