Milestone 4: Create a Component - Bloomreach Commerce Experience Cloud - The Headless Digital Experience Platform Built for Commerce

Milestone 4: Create a Component

< Milestone 3: Set up a Development Project

Milestone Overview

Goal

Create a basic component including site configuration and frontend code.

Estimated Time to Complete

10-20 minutes

Summary

In this milestone, you will configure a new component for your channel using the Site Management API (or the pre-release Site Development webapp) and implement the frontend code to render that component. It will be a very minimalistic component with only one string property and no content.

In the video below, you can see a short demonstration of configuring a component through the Site Management API using Postman:

To simplify things for your first time configuring a component, you'll be using the Site Development webapp, a pre-release version of a UI layer on top of the Site Management API that is currently being developed by Bloomreach and will be integrated into a future release of Headless Experience Manager.

The Site Development webapp is pre-release software and is provided as-is and not supported by Bloomreach.

Obtain an API Authorization Token

Before you can use the Site Management API, you need to obtain an API authorization token.

  1. In Headless Experience Manager, navigate to Setup > brXM API token management.
  2. Click on the + API token button in the top right.
  3. Fill in a Token name, choose an Expiration date (up to 1 month in the future), check the Read and Write checkboxes next to Site Management API, and click on Create.
  4. Copy the token to the clipboard or write it down. This is the only time it will be displayed.
See API authorization for more information and detailed instructions with screenshots.

Configure the Component Properties and Parameters

The pre-release Site Development webapp is available at the following URL:

https://bloomreach-content-tools.netlify.app/

Point your browser to the above URL to load the webapp.

Select the Settings tab and enter your Headless Experience Manager account name (for example "trials-1234abcd") in the namespace field and your API authorization token in the apiKey field.

Click on Test connection to verify you entered the correct information. If you see a Connection Successful message, click on Save.

You are now ready to make configuration changes.

Select the Components tab and verify that your project/channel is selected in the dropdown (getting-started-vsQ3J in the screenshot below).

Open the sample group:

Click on Add component and enter the following values:

  • extends: "base/component"
  • label: "My Component"
  • ctype: "MyComponent"

You can leave the other fields blank.

Click OK to add the component.

Select My Component.

Click on the + and choose Add Simple Parameter.

A new string parameter will be added. Click on the pencil icon to edit the parameter,

Change the name to "title" and enter "My First Component!" for defaultValue.

Click on < to return to the main component editor and click on the disk icon to save your component.

If you prefer to use the Site Management API directly instead of the Site Development webapp, you can use the Channel Component endpoint with a PUT request of the following URL:

PUT https://[account_name].bloomreach.io/management/site/v1/channels/getting-started-vpAcR/component_groups/sample/components/my-component

Use the following payload:

{
   "id":"sample/my-component",
   "extends":"base/component",
   "hidden":false,
   "system":false,
   "xtype":null,
   "ctype":"MyComponent",
   "contentType":null,
   "label":"My Component",
   "icon":null,
   "parameters":[
      {
         "name":"title",
         "valueType":"string",
         "required":false,
         "hidden":false,
         "overlay":false,
         "defaultValue":"My First Component!",
         "system":false,
         "config":null
      }
   ],
   "fieldGroups":[
      
   ]
}
Bloomreach provides a Postman collection for the Site Management API to make working with the API easier for developers.

Add the Component to the Page

Now that you have configured the component, you can already add it to the page in your channel.

Open your channel in the Experience manager and make sure you have selected your development project in For project.

Before you can make changes to the page, it must be added to the development project. Open the Page menu and choose Add to project:

Open the left drawer and select the Components tab.  "My Component" should be available in the library:

Click on My Component to select it, then click inside the container on the page to add the component. Because you did not yet implement the component in your frontend app, you will see a text Component "My Component" is not defined:

Everything in the backend is now in place and you can move on to implementing the component in your frontend app.

Implement the Frontend Code for the Component

In your frontend app, create a file src/components/MyComponent.jsx and implement the component as in the code below:

src/components/MyComponent.jsx

export function MyComponent({ component, page }) {

  const { title, showTitle } = component.getParameters();

  return (
    <div>
      <p>Title here below:</p>
      <h2>{showTitle && title}</h2>
    </div>
  );
}

In src/App.js, import MyComponent:

import {MyComponent} from "./components/MyComponent";

And add MyComponent to the mapping property of the BrPage element:

}} mapping={{ Content, MyComponent }}>

Return to the Experience manager. You should now see the component's title property displayed. Click on the component to open the right drawer and edit the component properties. Try changing the title property to see the preview update automatically.

Congratulations, you developed your first component for Headless Experience Manager!

Full Code

Find the complete code for milestone 4 in React, Angular, and Vue in Github:

https://github.com/bloomreach/content-getting-started/tree/Milestone_4_Create_a_Component

Next

Now that you have some hands-on experience with basic Headless Experience Manager development, you can dive into the developer documentation and learn about more advanced topics:

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?