Tutorial: How to Map Component Data Sources in XM Cloud

Overview

Previously, you learned how to use XM Cloud Components to centrally manage the content of a Text Teaser component and use that component in XM Cloud Pages. You then learned how to create a data model for the Text Teaser component and make it available. Now you will evolve the component itself so it can be used as a reusable visual building block in XM Cloud where the content can be different on each page. To accomplish this, you will map a data source to the visual elements in your component.

For this tutorial, you will:

1. Connect the created Text Teaser data source to the Text Teaser Component on the page and map each visual element to fields.
2. Share your changes with other authors in XM Cloud
3. Configure XM Cloud so that whenever an author drags the Text Teaser component onto the page, they are asked to select an existing piece of content or create a new one.

Prerequisites

In order to complete the following tutorial, you will need these resources:

1. A valid organization login for the Sitecore Cloud portal
2. An existing XM Cloud environment and site created in Tutorial: How to Set Up and Utilize XM Cloud
3. The Text Teaser component created in Tutorial: Create a Component using XM Cloud Component Builder
4. The Text Teaser data source created in Tutorial: How to Create a Component Data Template in XM Cloud
5. A FEaaS data source configuration done in Tutorial: How to make a data template available to the Component builder in XM Cloud

Map data source fields to XM Cloud Component visual elements

The Text Teaser component that was created in a previous tutorial uses static data in XM Cloud Components. As part of using the new Text Teaser data template, you need to map this Text Teaser data source to the visual elements in XM Cloud Components.

Map component heading element to Headline text field

You are going to start by mapping the headline text field.

1. Switch to the Components tab in the top menu to launch the Components visual builder.

2. Scroll to the section labelled Basic Components. This section will list all the components you have made available in the Basic Components section. Currently, there is only the Text Teaser.

   

3. Click on the Text Teaser card to launch the editor on this component

   

4. Click on the primary headline in the Component so that you enter the 'editing' mode for that field.

   

   As you select visual elements in the editor you will see the details on the right change to show you the new options for that visual element. In this case, you can see the Text part in the Content area which is where you need to go next.

5. On the right side panel, click on the Text option. This will show that the text is currently Static

6. Change the mode from Static to Mapped. This will show you the source mapping options.

   

7. Find and select the Text Teaser source in the list of available sources.

   

   Note that the Sample shows some example fields and their values. This can help you make sure you have the right type of source selected for the component you are editing.

8. Click on the Next button to advance to the Path configuration step. This is where you will map the fields from the template to the visual element.

9. Select the Headline field to map the data from that Text Teaser field to the heading element in the component.

   

10. Click Complete to finish the mapping process.

Map component sub-heading element to Subheadline text field

You will now repeat the process for the the subtitle/subheading element. You will select the subheading visual element and map that to the Text field "Subheadline" in the Text Teaser template

1. Click on the secondary headline/subheadline in the Component so that you enter the 'editing' mode for that field.

   

   The pane on the right updates and you can see the Text part in the Content area which is where you need to go next.

2. On the right side panel, click on the Text option. This will show that the text is currently Static

3. Change the mode from Static to Mapped. This will show you the source mapping options.

4. Click on the Next button to advance to the Path configuration step. This is where you will map the fields from the template to the visual element.

5. Select the Subheadline field to map the data from that Text Teaser field to the heading element in the component.

   

6. Click Complete to finish the mapping process.

Mapping a Rich Text field to an HTML Block element

In the Text Teaser component that was created in the previous tutorial, the right-side of the component is intended to have a full description (or 'teaser') for the user to read. Initially, the copied content that was used contains several paragraphs and list items, which does not map to a single field. Additionally, the paragraph tags do not render the formatting from a Rich Text field, so even if you have a single paragraph tag this will not meet the need.

In order to create a section of rich content and then map it to a Rich Text field on a data source and preserve the formatting, you need to do some cleanup to the existing content and put in the correct type of element: an HTML Block. In this section of the tutorial, you will clean up the component and map the Rich Text field to an HTML Block.

1. In the Components builder, select the right-side of the Text Teaser component and remove all of the paragraphs of content that are currently there.

   

2. Above the empty placeholder, click on the Add element button.

3. Select the HTML Block element to insert it into the placeholder.

   

4. Click on the HTML Block element that was inserted to focus your editing selection.

5. On the right side panel, click on the HTMLContent option. This will show that the text is currently None

6. Map the HTML Block to the Content field on the Text Teaser data source

   

7. Click Complete to save the mapping changes.

Make the changes to the component available to authors

Now that you have completed all of the mapping changes you will need to make the changes available to Pages by staging the component again.

1. In the Components builder tool, click on the Restage button above the component

   

Update the existing Text Teaser to use a data source

In the previous tutorial, you added a Text Teaser component to the home page. After making these mapping changes, the existing component will now need a data source to display correctly as there is no more static content on the component. You will now go to Pages and fix the component so that it can pull the data from one of the Text Teaser data sources that were created in this tutorial.

1. Return to the XM Cloud Tools pane. If you've closed that tab, you can get there with these instructions:

   • Login to the Sitecore Cloud Portal
   • Select your App from the Apps list
   • From the flyout panel, select Open app
   • At the very top switch to Tools

2. In the Tools page, select the Pages card to launch the Pages editor. The home page will display and you can see that the Text Teaser component is blank.

   

3. Click on the blank component to select it.

4. In the context menu above the component, click on the Delete action button. This will remove the current version of the component from the page.

   

5. In the left page, scroll down the Components listing to find the Text Teaser component.

   

6. Drag the Text Teaser component onto the Pages canvas to add the component to the page. A dialog will display prompting you to assign a content item (data source) to the component.

   

7. Expand and navigate the displayed Content items tree to find the Text Teasers folder: Company Dev/Company Dev/Data/Teasers

8. Select the How to Use Components content item.

   

9. Click the Assign button to connect this content item to the Text Teaser component on the page.

Related XM Cloud Documentation

• Get your content from an XM data source
• Map data from an XM data source to a component