Build your first component

Timing 20 minutes

This is part four of the getting started walkthrough series. Before you can complete the steps here, make sure you have created a project and environment, created a site and page, and set up your local development environment.

In this example, you'll be adding a code component that includes a title and text. To create the component, you will clone one of the existing components that are included out of the box in XM Cloud. Cloning an existing component saves development time by creating the boilerplate items and configurations that your component requires, and makes sure that the required base templates are configured to support the content authoring features in Pages.

This walkthrough describes how to:

Create and deploy the new component to XM Cloud

In the first step, you create the component structure in your local project.

JavaScript SDK

If you're using JSS, you create a React component. The component accepts the following properties:

rendering – contains information about the component's presentation (rendering).
params – an object containing parameters passed to the component from Sitecore.

The component uses the following Sitecore parameters:

Parameter	Description
`Styles`	CSS classes for the container.
`GridParameters`	CSS classes for the grid system (for example, Bootstrap).
`RenderingIdentifier`	A unique identifier for the component, used for analytics.

In addition, if you create a component that includes styles that can be configured in the right-hand side in Pages, you can use the data-class-change attribute in the relevant HTML element. In Pages, when the content author changes styles in the styling menu, those changes will be reflected in the preview canvas.

To create the new component:

Ensure you still have the cloned repository open in your code editor.
In the /headapps/nextjs-starter/src/components folder, create a new file and name it TitleAndText.tsx.

Paste the following code into the new file:

RequestResponse

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

interface Fields {
  Title: Field<string>;
  Text: Field<string>;
}

type TitleAndTextProps = {
  params: { [key: string]: string };
  fields: Fields;
};

export const Default = (props: TitleAndTextProps): JSX.Element => {
  const containerStyles = props.params && props.params.styles ? props.params.styles : '';
  const styles = `${props.params.GridParameters} ${containerStyles}`.trimEnd();

  return (
    <div className={`container-default component ${styles}`}>
      <div data-class-change className={containerStyles}>
        This container must be refreshed without reloading the page.
      </div>
      <h1 className="component-content title row">
        <Text field={props.fields.Title} />
      </h1>
      <div className="component-content text row">
        <Text field={props.fields.Text} />
      </div>
    </div>
  );
};

Save the file.
Add the change to a commit and push the change to your repo. This will automatically kick off a deployment to XM Cloud. You can follow its progress in the Deploy app. Proceed to the next step after the deployment is complete.

Create the rendering definition

Now you can create the rendering definition for the component. Rendering definitions are used to tell XM Cloud where in the project the component's .tsx file is, and what data it needs to render correctly. You'll do this by cloning an existing rendering rendering, thereby automatically generating all the required items, instead of having to do it manually. Then, you'll add the rendering to the headless module that was created when you created the site collection. You can find the module in /sitecore/system/Settings/Project.

To clone the component:

In the Cloud Portal, click the tile for the environment you created earlier, for example, XMC Getting Started.
In the pane on the right, click Open app.
On the top menu bar, click Content, then click Content Editor.
In the Content Editor, navigate to /sitecore/layout/Renderings/Feature/Headless Experience Accelerator/Page Content/Rich Text. On the Content tab, scroll down to the Customize Page section and, to ensure the component is visible in Pages, make sure the Editable check box is selected.
Right-click the rendering named Rich Text and click Scripts > Clone Rendering.
In the Create derivative rendering window, specify the following:
- On the General tab, enter the name TitleAndText.
- On the General tab, in the Add to module field, select Renderings/Project/XMC Getting Started/Getting Started Content.
- On the Parameters tab, select Make a copy of original rendering parameters. This decouples the rendering from the original component and reduces dependencies.
- On the Datasource tab, in the Datasource field, select Make a copy of original datasource.
Click Proceed, and close the window when the process is finished.
Navigate to /sitecore/templates/Project/XMC Getting Started/Getting Started Content/Text, and on the Builder tab, change the values for the fields you created:
- Title - select Single-Line Text.
- Text - select Multi-Line Text.
Make sure the Source column is empty for both fields.
In the upper-left corner, click Save.
Navigate to /sitecore/content/XMC Getting Started/XMC Getting Started/Presentation/Available Renderings.
Right-click the Available Renderings item and click Insert > Available Renderings.
Name the new item Getting Started Content and click OK. The new item opens automatically.
In the Renderings field, click Edit.
In the tree on the left, locate and select the rendering item you created previously at /Layout/Renderings/Project/XMC Getting Started/Getting Started Content/TitleAndText. Click the arrow to move it to the list on the right, then click OK.
In the upper-left corner, click Save.
To navigate back to the main XM Cloud dashboard, click the Launchpad .

Add the component to your site page

At this stage, you've completed the required configuration for the new component and it's available to use on your site. In this step, you can return to Pages and add the component to the page you created earlier, after which you'll be able to see it on your local development instance.

To add the component to your site page:

On the main XM Cloud Sites dashboard, on the new site tile, click Options > Edit in the page builder to open Pages, or, in a new browser tab, open https://pages.sitecorecloud.io/.
On the Components tab, in the Getting Started Content section, you can now see the Title and Text component. Drag it onto one of the plus icons on the page. You should now see the component rendered on the page, with a No text in field indicator for the title and text fields.
Enter some text for the title and text fields.
In your browser, navigate to your local host to see the new component rendered with the text you entered (for JSS, this is http://localhost:3000/ ; for .NET, this is http://localhost/5001/).

You've completed the walkthrough series! You can now continue to create new components, test your changes locally, and push to your source control provider - this kicks off a deployment in XM Cloud and makes new components available in Pages.

Do you have some feedback for us?

If you have suggestions for improving this article,