Use 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 type | Description |
---|---|
Sitecore Item | Select one or more items from Sitecore. |
Sitecore Item
This parameter type allows a Uniform user to select one or more Sitecore items.
Add parameter to component
In order 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.
In Uniform, navigate to your component.
Add a new parameter using the parameter type Sitecore Item.
The following values can be specified:
Name Description Allowed Template If 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 Locations Defines 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 e.g. `./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 Items Indicates whether the user can select only one item (the default), or more than one item. Required Indicates whether the value is required when the component is used. Sitecore Item parameter configuration.
Edit parameter value
When you use a component with a Sitecore Item parameter, by default no item will be selected. You must select an item.
Click Select new item.
Find the item you want to select.
Click Select to save your selection.
You will see details about the item you selected, including the path and some metadata.
About this stepAfter 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 unselect 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.
Configure an enhancer
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.
Using the enhancer provided by Uniform saves you from having to write logic to interact directly with Sitecore.
If you are migrating Sitecore renderings & layouts, that section of the documentation provides specific information on how to configure an enhancer.
How Uniform stores the selected item
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.
Add the enhancer
Uniform provides an enhancer so you don't need to write the API calls to Sitecore to retrieve data for items.
For more information about the enhancer, see the package documentation.
In Sitecore, get the following values:
- URL of your Sitecore instance
- Sitecore API key
- Site configuration name
About this stepThese are the same values used to configure the Sitecore integration in Canvas.
Create a file
.npmrc
in the root of your front-end application://registry.npmjs.org/:_authToken=${NPM_TOKEN}
About this stepYou must use the npm access token you received from Uniform here. You can either set an environment variable
NPM_TOKEN
on your local development machine to the value, or you can replace${NPM_TOKEN}
in the.npmrc
file with the value.Add the following npm packages to your front-end application:
@uniformdev/canvas-sitecore
In a text editor, open the file where you retrieve the composition definition from Uniform.
About this stepYou are looking for the code calls the async function
getComposition
. The code below assumes the object returned is set in a variablecomposition
.Add the following import statements:
import { EnhancerBuilder, enhance } from '@uniformdev/canvas';
import {
CANVAS_SITECORE_PARAMETER_TYPES,
createItemEnhancer,
} from '@uniformdev/canvas-sitecore';Add the following code:
const enhancer = createItemEnhancer({
config: {
UNIFORM_API_URL: '!!! YOUR SITECORE API URL !!!',
UNIFORM_API_SITENAME: '!!! YOUR SITECORE SITE NAME !!!',
}
});About this stepWe recommend you moving the Sitecore credentials to environment variables rather than hard-coding them in the front-end app.
Add the following code:
await enhance({
composition,
enhancers: new EnhancerBuilder().parameterType(
CANVAS_SITECORE_PARAMETER_TYPES,
enhancer,
),
context: {},
});About this stepThis registers the enhancer to be used for any occurrence of the Sitecore Item parameter.
Now, the parameter value in the composition is mutated to include the field values for the selected Sitecore items (instead of just being identifiers).