# Bloomreach

[Bloomreach](https://www.bloomreach.com/) is a digital experience platform for content management and delivery.

commercetools Frontend comes with an out-of-the-box Bloomreach extension to integrate Bloomreach in your commercetools Frontend project.

On this page, we'll walk you through how to set up the Bloomreach extension.

**Prerequisites**

- A [Bloomreach account](https://www.bloomreach.com/en/request-demo)
- A Bloomreach [Delivery API URL](https://documentation.bloomreach.com/content/reference/delivery-api#api-base-url)

If the `content-bloomreach` extension is not available in your commercetools Frontend project at this path `packages/PROJECT_NAME/backend`, before proceeding with the following configurations, you must:

1. Copy the `content-bloomreach` extension from [the scaffold repository](https://github.com/FrontasticGmbH/scaffold-b2c/tree/main/backend/content-bloomreach) to your project.
2. [Register the extension in your project](/frontend-development/extensions.md#define-extensions).

## Get started

To start using the Bloomreach extension, follow these steps:

1. [Add the following project configuration field to the project schema](/frontend-development/api-hub-configuration.md#add-project-configuration-fields-to-the-project-schema) from the Studio.

   ```json title="Add Bloomreach project configuration field"
   {
     "name": "Bloomreach Extension",
     "fields": [
       {
         "label": "Delivery API URL",
         "field": "EXTENSION_BLOOMREACH_DELIVERY_API_URL",
         "type": "encrypted",
         "translatable": false,
         "required": true
       }
     ]
   }
   ```

2. [Set the Bloomreach configuration value](/frontend-development/api-hub-configuration.md#enter-project-configuration-values-in-project-settings) from the Studio.

## Deliver content with the Bloomreach extension

To deliver content with the Bloomreach extension, you must first create a Channel and then add Pages to it. Within each page, you can create Documents to display content such as images or text.

For more information on creating content in Bloomreach, visit the following resources:

- [Create a Channel](https://documentation.bloomreach.com/content/docs/milestone-1-create-a-channel)
- [Manage pages in a Channel](https://documentation.bloomreach.com/content/docs/manage-pages-in-a-channel)
- [Create a Document](https://documentation.bloomreach.com/content/docs/create-a-document)

### Upload data source schemas

The commercetools Frontend Bloomreach extension comes with the following out-of-the-box [data sources](/frontend-development/development-concepts.md#data-sources) for Bloomreach:

- `bloomreach/content`: to fetch a single content item from Bloomreach.
- `bloomreach/content-list`: to fetch multiple content items from Bloomreach with filters and configurations.

To fetch content from Bloomreach, you must [upload to the Studio](/frontend-studio/using-data-sources-in-the-studio.md) the following data source schemas.

```json title="Schema for Bloomreach Content data source"
{
  "customDataSourceType": "bloomreach/content",
  "name": "Bloomreach Content",
  "category": "Content",
  "icon": "source",
  "schema": [
    {
      "name": "Content Selection",
      "fields": [
        {
          "label": "Channel",
          "field": "channel",
          "type": "text",
          "translatable": false
        },
        {
          "label": "Page",
          "field": "page",
          "type": "text",
          "translatable": false
        }
      ]
    }
  ]
}
```

```json title="Schema for Bloomreach Content List data source"
{
  "customDataSourceType": "bloomreach/content-list",
  "name": "Bloomreach Content List",
  "category": "Content",
  "icon": "source",
  "schema": [
    {
      "name": "Content Selection",
      "fields": [
        {
          "label": "Channel",
          "field": "channel",
          "type": "text",
          "translatable": false
        },
        {
          "label": "Pages",
          "field": "pages",
          "type": "text",
          "translatable": false
        }
      ]
    }
  ]
}
```

### Create frontend components

To render on your website the data coming from these data sources, you must create [Frontend components](/frontend-development/development-concepts.md#components), linked to the aforementioned data sources.

1. Create the Frontend component schemas by [uploading the following schemas to the Studio](/frontend-development/creating-a-frontend-component.md#create-a-frontend-component-schema).

   ```json title="Schema for the Bloomreach Content Frontend component"
   {
     "tasticType": "commercetools/ui/content/bloomreach-blog",
     "name": "commercetools UI Bloomreach Blog",
     "icon": "bookmark",
     "category": "Content",
     "schema": [
       {
         "name": "Content",
         "fields": [
           {
             "label": "Bloomreach Content",
             "field": "data",
             "type": "dataSource",
             "dataSourceType": "bloomreach/content",
             "required": true
           }
         ]
       }
     ]
   }
   ```

   ```json title="Schema for the Bloomreach Content List Frontend component"
   {
     "tasticType": "commercetools/ui/content/bloomreach-blog-list",
     "name": "commercetools UI Bloomreach Blog List",
     "icon": "bookmark",
     "category": "Content",
     "schema": [
       {
         "name": "Content",
         "fields": [
           {
             "label": "Bloomreach Content",
             "field": "data",
             "type": "dataSource",
             "dataSourceType": "bloomreach/content-list",
             "required": true
           }
         ]
       }
     ]
   }
   ```

2. In your commercetools Frontend project, under `components/commercetools-ui/content/blog`, add the following `index.tsx` file for the `Blog` React component.

   ```tsx title="index file of the Blog React component"
   const Blog = ({ title, summary, banner }) => {
     return (
       <div className="w-[280px]">
         <h4 className="py-4 pr-8 text-lg font-bold dark:text-white">
           {title}
         </h4>
         <div className="relative h-[160px] w-[280px]">
           <Image
             src={banner}
             objectFit="cover"
             layout="fill"
             className="rounded-sm"
           />
         </div>
              <p className="box-border pt-4 pr-4 dark:text-white">{summary}</p>
       </div>
     );
   };
   ```

3. In your commercetools Frontend project, add the `index.tsx` files for the `bloomreach-blog` and `bloomreach-blog-list` Frontend components.

   - Add the following `index.tsx` file under `tastics/content/bloomreach-blog`.

     ```tsx title="index file of the Bloomreach Blog Frontend component"
     import React from 'react';
     import Blog from 'components/commercetools-ui/content/blog';
     import { BloomreachLoader } from 'frontastic/lib/image';

     export interface Bloomreach {
       uid: string;
       summary: string;
       title: string;
       banner: string;
     }

     const BloomreachBlogTastic = ({ data }) => {
       const blog = data?.data?.dataSource as Bloomreach;
       if (!blog) return <></>;

       return <Blog {...blog} imageLoader={BloomreachLoader} />;
     };

     export default BloomreachBlogTastic;
     ```

   - Add the following `index.tsx` file under `tastics/content/bloomreach-blog-list`.

     ```tsx title="index file of the Bloomreach Blog List Frontend component"
     import React from 'react';
     import Blog from 'components/commercetools-ui/content/blog';
     import { BloomreachLoader } from 'frontastic/lib/image';
     import { Bloomreach } from '../bloomreach-blog-list';

     const BloomreachBlogListTastic = ({ data }) => {
       const blogs = (data?.data?.dataSource ?? []) as Bloomreach[];
       return (
         <div className="flex flex-wrap items-center gap-4">
           {blogs.map((blog) => (
             <Blog key={blog.uid} {...blog} imageLoader={BloomreachLoader} />
           ))}
         </div>
       );
     };
     export default BloomreachBlogListTastic;
     ```

4. Register the frontend components in the `tastics/index.tsx` file.

   ```tsx title="Register the Bloomreach Blog and Bloomreach Blog List components" highlightLines="8,9"
   export const tastics = {
   ...
   'commercetools/ui/checkout': Checkout,
   'commercetools/ui/thank-you': ThankYou,
   'commercetools/ui/cart': Cart,
   'commercetools/ui/footer': Footer,
   'commercetools/ui/header': Header,
   'commercetools/ui/content/bloomreach-blog': BloomreachBlogTastic,
   'commercetools/ui/content/bloomreach-blog-list': BloomreachBlogListTastic,   ...
   default: NotFound,
   };
   ```

### Add data sources and configure data source filters

Now, add the [**Bloomreach Content** and **Bloomreach Content List** data sources](/frontend-development/bloomreach.md#upload-data-source-schemas) to the [page folder](/frontend-studio/page-folders.md) where you want to render the content and then configure the data source filters.

To add the data sources to the page folder and configure the data source filters, follow these steps:

1. If necessary, [create a page folder](/frontend-studio/page-folders.md#create-a-page-folder). Otherwise, from the Studio home page or from the left menu, go to **Site builder**.

2. In the page folder list, hold the pointer over the page folder where you want to render the content and click the **Settings** icon: the **Page folder settings** dialog opens.

3. In the **Data source** section, click **+ Add data source filter**: the list of the available data sources opens. From the list, you can select the **Bloomreach Content** and **Bloomreach Content List** data sources. When you select a data source, the [data source filter editor](/frontend-studio/using-the-data-source-filter-editor.md) opens.

4. Configure the data source filters as follows and save:

   - For the **Bloomreach Content** data source, enter the following:

     - In **Content Selection**, enter the Bloomreach Channel, and the name of the Bloomreach page to display.

     ![Add data source for single page](https://docs.commercetools.com/frontend-development/images/bloomreach-data-source-single-page.png)

   - For the **Bloomreach Content List** data source, enter the following:

     - In **Content Selection**, enter the Bloomreach Channel, and the name of each Bloomreach Page you wish to display, separated by commas.

     ![Add data source for multiple pages](https://docs.commercetools.com/frontend-development/images/bloomreach-data-source-multiple-page.png)

### Add Frontend components to the page version

Finally, you must add the [Frontend components you created](/frontend-development/bloomreach.md#create-frontend-components) to the [page version](/frontend-studio/page-versions.md) where you want to render the content. Thus, the data retrieved from the data source is rendered on the page version through the Frontend component.

To add the Frontend components to the page version, follow these steps:

1. If necessary, [create a page version](/frontend-studio/page-versions.md#create-a-page-version). Otherwise, from the Studio home page or from the left menu, go to **Site builder**.

2. Use the page folder list and the status sections to navigate to the page version where you want to add the Frontend components. Then, hold the pointer over the page version and click the **Edit** icon: the [page builder](/frontend-studio/using-the-page-builder.md) opens.

3. Edit the layout of the page version as you wish. In this example, we add a **1/1** layout element to the **MAIN** [layout section](/frontend-studio/using-the-page-builder.md#layout-section).

4. Use the [**Components** pane](/frontend-studio/using-the-page-builder.md#components-pane) to find the Frontend components to add. Drag the **Bloomreach Blog** and the **Bloomreach Blog List** Frontend components to the **1/1** layout element.

   ![Add components to page](https://docs.commercetools.com/frontend-development/images/bloomreach-add-components-to-page.png)

5. Select the **Bloomreach Blog** Frontend component, then, in **Component settings > Content** select the **Bloomreach Content** data source.

6. Select the **Bloomreach Blog List** Frontend component, then, in **Component settings > Content** select the **Bloomreach Content List** data source.

7. [Preview and save](/frontend-studio/using-the-page-builder.md#menu-bar) your changes. Your Bloomreach page is now rendered on your commercetools Frontend website.

   ![A page displayed from Bloomreach](https://docs.commercetools.com/frontend-development/images/bloomreach-page.png)

## Related pages

- [Area overview page with navigation](/frontend-development.md)
- [Previous page: Amplience](/frontend-development/amplience.md)
- [Next page: Contentful](/frontend-development/contentful.md)
- [Search documentation and API specs](/search.md)