Walkthrough: Building a simple custom component

Note

Use the Content Editor for the steps described in this topic.

XM Cloud comes with a set of default components for simple text, images, page content, and so on. You can also create a new component. This topic describes the tasks involved in creating a component. In this example, you create a component called CustomComponent1 that renders a simple text field.

To help you decide whether you need to create a custom component, you can check this flowchart.

This walkthrough describes how to:

  • Create a JSON component item with a data source template and a rendering parameters template.

  • Create a default variant for the component that renders a text field.

  • Create a component file for your front-end JSS app that corresponds to the component item defined in the Content Editor.

  • Add base templates to the parameters template of your component to ensure that the component supports the functionality you need.

Note

For information about making the custom component available in your preferred editor, see Make a custom component available in Pages or Experience Editor.

Create a JSON component item

Creating a custom component involves creating a JSON component, a rendering parameters template, and a data source template.

To create a JSON component item:

  1. In the Content Editor, navigate to /sitecore/layout/Renderings/Feature, right-click, and then click Insert > Rendering Folder. Enter a name, for example, Custom Components.

  2. Right-click the Custom Components folder, click Json Rendering, and enter the name CustomComponent1.

    Create a JSON component in the Content Editor
  3. Navigate to sitecore/Templates/Feature, right-click, and then click Insert > Template Folder. Enter the name CustomTemplates.

  4. Right-click the CustomTemplates folder, and then click Insert > New Template.

  5. In the dialog box, enter a name, for example, MyParameters, and select the Templates/Foundation/Headless Experience Accelerator/Presentation/Rendering Parameters/Base Rendering Parameters item. Select the CustomTemplates folder as the location for your parameters template and click Next.

  6. Right-click the CustomTemplates folder, and then click Insert > New Template.

  7. In the dialog, enter a name, for example, MyDatasource, and select the /Templates/System/Templates/Standard template item. Select the CustomTemplates folder as the location for your data source template and click Next.

  8. To add a text field named SomeText to the data source template, follow these steps:

    • Right-click MyDatasource, and then click Insert > Template section. Enter a name for the section. Or, click inside the Add a new section field on the Builder tab.

    • Click MyDatasource again and, on the Builder tab, click inside the field below the section you've just added.

    • Enter the name SomeText and select a field type, for example, Rich Text.

    Create a data source template and add a text field
  9. In the content tree, navigate to the CustomComponent1 component:

    • In the Datasource Template field, click Insert link, and select the MyDatasource item you've just created.

    • In the Datasource Location field, insert this query: query:$site/*[@@name='Data']/*[@@name='CustomComponent1DataSources']|query:$sharedSites/*[@@name='Data']/*[@@name='CustomComponent1DataSources'].

       

Create a default variant for the component

Components must have a default variant. In this example, you create a variant that renders a text field and name it, for example, Default. Later, when you create the component TSX file on the rendering host site, you will reference the Default variant using that exact name.

The following screenshot shows the built-in Rich Text component in Pages, and where to select variants. It'll look similar for your custom component:

Select a variant for a component in Pages

To create a default variant:

  1. Navigate to sitecore/Content/[site collection]/[site], right-click Data, and then click Insert > Insert from Template.

  2. In the Insert from Template dialog, navigate to Templates/Common and select Folder. In the Item Name field, enter the name CustomComponent1DataSources. This folder is used to store the data sources of your component.

  3. Navigate to sitecore/Content/[site collection]/[site]/Presentation/Headless Variants and click Insert > Variants. Enter the name Custom Component Variant.

  4. Right-click Custom Component Variant, and then click Insert > Variant Definition. Enter the name Default. The name you give here must be consistent with the name used later in the component TSX file.

    Create the Default variant for a custom component

Create a TSX file for your component

Your front-end JSS app must have a JavaScript component that is consistent with the component you have just created in the Content Editor.

Note

The component TSX files are typically located in the following directory:

src/components.

To create a TSX file for your component:

  • In the directory where the TSX files are located, add a component file with the same name as the name you defined in the Component Name field of the component item. In this example, CustomComponent1.tsx:

    The Component Name field in the Content Editor
    Example of a JSS component file

The following example of a JavaScript component renders the SomeText field that you added to the data source item of the component:

Note

The exported method is called Default in accordance with the variant definition you created earlier.

RequestResponse
import React from 'react';

import { Field, Text } from '@sitecore-jss/sitecore-jss-nextjs';

interface Fields {

  SomeText: Field<string>;

} 

type CustomComponent1Props = {

  params: { [key: string]: string };

  fields: Fields;

};

export const Default = (props: CustomComponent1Props): JSX.Element => {

  return (

    <div className={`component customcomponent1 ${props.params.styles}`}>

      <div className="component-content">

        <div>

          <Text field={props.fields.SomeText} />

        </div>

      </div>

    </div>

  );

};

Add base templates to the parameters template

Depending on the functionality you want your component to support, you need to add certain base templates to the rendering parameters template of your component. For example, this is relevant if you want the component to support grids and styles, variants, and dynamic placeholders.

Note

We recommend that you assign all of the following base templates to the rendering parameters template: BaseRenderingParameters, IDynamicPlaceholder, _PerSiteStandardValues, and IRenderingId.

To add base templates to the parameters template:

  1. Navigate to sitecore/Templates/Feature/CustomTemplates and click MyParameters.

  2. On the Content tab, in the Data section, assign the base templates you need to the parameters template:

    • The /sitecore/templates/Foundation/Headless Experience Accelerator/Presentation/Rendering Parameters/Base Rendering Parameters template includes these templates:

      • IStyling for styles support. This template adds a new field in the control properties for that component and an additional button on the edit frame of the component.

      • IComponentVariant for variant support. This template adds a variant drop-down in the control properties and Variant Selector drop-down on the edit frame.

      • Grid Parameters for grid support. This template adds a grid field in the control properties and an additional button on the edit frame of the component.

    • The /sitecore/templates/Foundation/Experience Accelerator/Dynamic Placeholders/Rendering Parameters/IDynamicPlaceholder template supports dynamic placeholder keys by adding a placeholder in addition to, for example, a title or some text.

    • The /sitecore/templates/Foundation/Experience Accelerator/StandardValues/_PerSiteStandardValues template supports site-specific standard values.

      Note

      Only add this base template if you are planning to use standard values for specific sites. This is to avoid unnecessarily affecting the performance.

    • The /sitecore/templates/Foundation/Experience Accelerator/Markup Decorator/Rendering Parameters/IRenderingId supports HTML identifiers. This template adds an ID field to the component configuration, which renders an attribute to an element in the HTML code.

      Add base templates to a custom component

Now that you've built a simple custom component, you can make it available in your preferred editor, so that content authors can start using the component when designing pages.

Do you have some feedback for us?

If you have suggestions for improving this article,