# Amplience

[Amplience](https://amplience.com/) is an API-first headless content management platform.

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

With the extension you can deliver content from Amplience, such as images, videos, and other media assets, to your commercetools Frontend website.

For demonstration purposes, in this document you will learn how to render on your commercetools Frontend website one or multiple blog posts that you created on Amplience.

**Prerequisites**

- An [Amplience account](https://amplience.com/login/)
- An Amplience Content Hub to store your content and media assets. To create a Content Hub, log in to your Amplience account and request [Amplience support](https://support.amplience.com/support/home) to create it.

If the `content-amplience` 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-amplience` extension from [the scaffold repository](https://github.com/FrontasticGmbH/scaffold-b2c/tree/main/backend/content-amplience) to your project.
2. [Register the extension in your project](/frontend-development/extensions.md#define-extensions).

## Get started

To start using the Amplience 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 Amplience project configuration field"
   {
     "name": "Amplience Extension",
     "fields": [
       {
         "label": "Amplience Hub Name",
         "field": "EXTENSION_AMPLIENCE_HUB_NAME",
         "type": "encrypted",
         "translatable": false,
         "required": true
       }
     ]
   }
   ```

2. [Set the value for the **Amplience Hub Name** configuration field](/frontend-development/api-hub-configuration.md#enter-project-configuration-values-in-project-settings) from the Studio.

   The value must match the name of the Amplience Content Hub you created as a prerequisite.

## Deliver content with the Amplience extension

To deliver any type of media content with the Amplience extension you must follow these steps:

1. [Create content on Amplience](/frontend-development/amplience.md#create-content-on-amplience) (create the content type schema, content type, and content items).

2. [Upload the data source schemas to the Studio](/frontend-development/amplience.md#upload-data-source-schemas).

3. [Create the dedicated Frontend components](/frontend-development/amplience.md#create-frontend-components).

4. [Add data sources to the dedicated page folder and configure data source filters](/frontend-development/amplience.md#add-data-sources-and-configure-data-source-filters) in the Studio.

5. [Add the Frontend components to a dedicated page version](/frontend-development/amplience.md#add-frontend-components-to-the-page-version) in the Studio.

In this document, we present an example of how to render one or multiple blog posts.

### Create content on Amplience

To use the Amplience extension, you need to create on Amplience the content that you want to deliver on your website. In this example, we create three blog content items.

To create the blog content items, follow these steps:

1. [Create a content type schema](https://amplience.com/developers/docs/dev-tools/guides-tutorials/schema-editor/) using the following schema for the blog content.

   ```json title="Blog content type schema"
   {
     "$schema": "http://json-schema.org/draft-07/schema#",
     "$id": "https://schema-cofe.com/blog",
     "title": "Blog",
     "description": "Blog",
     "allOf": [
       {
         "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
       }
     ]
     "type": "object",
     "properties": {
       "title": {
         "title": "Title",
         "description": "The blog's title",
         "allOf": [
           {
             "$ref": "http://bigcontent.io/cms/schema/v1/localization#/definitions/localized-string"
           }
         ]
       },
       "banner": {
         "title": "Banner",
         "allOf": [
           {
             "$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
           }
         ]
       },
       "summary": {
         "title": "Summary",
         "description": "Short summary on what the blog is about.",
         "type": "string",
         "format": "markdown"
       }
     },
     "propertyOrder": []
   }
   ```

2. Use the **Blog** content type schema you created to [register a content type](https://amplience.com/developers/docs/dev-tools/guides-tutorials/content-types/#registering-content-types).

3. [Create three blog content items](https://amplience.com/developers/docs/user-guides/produce-content/create/) by selecting the **Blog** content type you created and adding content of your choice such as text, images, videos, or other media assets. In this example, we call the content items **Blog 1**, **Blog 2**, and **Blog 3**. You have now created three blog content items on Amplience.

### Upload data source schemas

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

- `amplience/content` to fetch a single content item from Amplience.
- `amplience/content-list` to fetch multiple content items from Amplience with filters and configurations.

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

```json title="Schema of the Amplience Content data source"
{
  "name": "Amplience Content",
  "customDataSourceType": "amplience/content",
  "category": "Content",
  "icon": "source",
  "schema": [
    {
      "name": "Content Selection",
      "fields": [
        {
          "label": "Content ID",
          "field": "contentId",
          "type": "text",
          "translatable": false
        }
      ]
    }
  ]
}
```

```json title="Schema of the Amplienece Content List data source"
{
  "name": "Amplience Content List",
  "customDataSourceType": "amplience/content-list",
  "category": "Content",
  "icon": "bookmark",
  "schema": [
    {
      "name": "Configuration",
      "fields": [
        {
          "label": "Content Type",
          "field": "contentType",
          "type": "text",
          "translatable": false
        },
        {
          "label": "Limit",
          "field": "limit",
          "type": "number",
          "default": 12
        }
      ]
    },
    {
      "name": "Advanced",
      "fields": [
        {
          "label": "Filters",
          "field": "filters",
          "type": "text",
          "translatable": false
        },
        {
          "type": "description",
          "text": "In the format of white space separated key-value pairs. For example, sorting1=val1 sorting2=val2"
        },
        {
          "label": "Sorting",
          "field": "sort",
          "type": "text",
          "translatable": false
        },
        {
          "type": "description",
          "text": "In the format of white space separated key-value pairs. For example, filter1=val1 filter2=val2"
        },
        {
          "label": "Resolve hierarchy tree",
          "field": "resolveHierarchyTree",
          "type": "boolean",
          "default": false
        }
      ]
    }
  ]
}
```

### Create Frontend components

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

- `amplience/content` to fetch a single content item from Amplience.
- `amplience/content-list` to fetch multiple content items from Amplience with filters and configurations.

To render on your website the data coming from these data sources, you must create [Frontend components](/frontend-development/development-concepts.md#components) that are linked to the mentioned data sources. In this example, we create the Frontend components to display a single or multiple blog content items.

To create the components, follow these steps:

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="Blog component schema linked to the amplience/content data source"
   {
     "tasticType": "commercetools/ui/content/blog",
     "name": "commercetools UI Amplience Blog",
     "icon": "bookmark",
     "category": "Content",
     "schema": [
       {
         "name": "Content",
         "fields": [
           {
             "label": "Amplience Content",
             "field": "data",
             "type": "dataSource",
             "dataSourceType": "amplience/content",
             "required": true
           }
         ]
       }
     ]
   }
   ```

   ```json title="Blog List component schema linked to the amplience/content-list data source"
   {
     "tasticType": "commercetools/ui/content/blog-list",
     "name": "commercetools UI Amplience Blog List",
     "icon": "bookmark",
     "category": "Content",
     "schema": [
       {
         "name": "Content",
         "fields": [
           {
             "label": "Amplience Content",
             "field": "data",
             "type": "dataSource",
             "dataSourceType": "amplience/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 `amplience-blog` and `amplience-blog-list` Frontend components.

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

     ```tsx title="index file of the amplience-blog Frontend component"
     import React from 'react';
     import Blog, { Props } from 'components/commercetools-ui/content/blog';

     const BlogTastic = ({ data }) => {
       const blog = data?.data?.dataSource as Props;

       if (!blog) return <></>;
     };

     export default BlogTastic;
     ```

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

     ```tsx title="index file of the amplience-blog-list Frontend component"
     import React from 'react';
     import Blog, { Props } from 'components/commercetools-ui/content/blog';

     const BlogListTastic = ({ data }) => {
       const blogs = (data?.data?.dataSource ?? []) as Props[];

       return (
         <div className="flex flex-wrap items-center gap-4">
           {blogs.map((blog) => (
             <Blog key={blog._meta.deliveryId} {...blog} />
           ))}
         </div>
       );
     };

     export default BlogListTastic;
     ```

4. Reference the `index.tsx` files for the `amplience-blog` and `amplience-blog-list` Frontend components in the `index.tsx` file under `frontastic/tastics`.

   ```tsx title="Blog and Blog List Frontend components in the components index file" 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/amplience-blog': BlogTastic,
   'commercetools/ui/content/amplience-blog-list': BlogListTastic,
   'commercetools/ui/content/tile': Tile,
   'commercetools/ui/content/spacer': Spacer,
   'commercetools/ui/content/showcase': Showcase,
   ...
   default: NotFound,
   };
   ```

### Add data sources and configure data source filters

Now you need to add the [**Amplience Content** and **Amplience Content List** data sources](/frontend-development/amplience.md#upload-data-source-schemas) to the [page folder](/frontend-studio/page-folders.md) where you want to render the content, then you need to 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 **Amplience Content** and **Amplience 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 **Amplience Content** data source: in the **Content ID** field, enter the [Content ID](https://amplience.com/developers/docs/knowledge-center/key-terms/#content-id) of the Amplience content item that you want to render. In this example, we enter the Content ID of the **Blog 1** content item [that we created](/frontend-development/amplience.md#create-content-on-amplience).
   - For the **Amplience Content List** data source:
     - In **Configuration** > **Content Type** field, enter the unique URL of your [Amplience content type schema](https://amplience.com/developers/docs/dev-tools/guides-tutorials/schema-editor/). In this example, we enter the URL of the **Blog** content type schema [that we created](/frontend-development/amplience.md#create-content-on-amplience).
     - In **Configuration** > **Limit**, set the maximum number of content items that you want to retrieve.

You can also manage data source filters from the page builder, the **Templates** area, and the **Dynamic pages** area. For more information, see [Using the data source filter editor](/frontend-studio/using-the-data-source-filter-editor.md).

### Add Frontend components to the page version

Finally, you must add the [Frontend components you created](/frontend-development/amplience.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.

In this example, we add both the **Amplience Blog** and the **Amplience Blog List** Frontend components to the same page version. In general, you should add the Frontend component that meets your needs.

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 component. 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 component to add. Then, drag it to the layout element. In this example, we drag both the **Amplience Blog** and the **Amplience Blog List** Frontend components to the **1/1** layout element.

5. Select the Frontend component. Then, in **Component settings > Content** select the data source to associate to the Frontend component. In this example, we select **Amplience Content** for the **Amplience Blog** Frontend component and **Amplience Content List** for the **Amplience Blog List** Frontend component.

   ![The Amplience Blog and Amplience Blog List Frontend components and the Component settings section in the page builder](https://docs.commercetools.com/frontend-development/..images/select-component-data-source.png)

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

   ![A preview page with a single blog item and three blog items](https://docs.commercetools.com/frontend-development/images/blog-previews.png)

## Related pages

- [Area overview page with navigation](/frontend-development.md)
- [Previous page: Overview](/frontend-development/integrations-overview.md)
- [Next page: Bloomreach](/frontend-development/bloomreach.md)
- [Search documentation and API specs](/search.md)