Amplience

Get started

To start using the Amplience extension, follow these steps:

1. Add the following project configuration field to the project schema from the Studio.

   Add Amplience project configuration fieldjson

   {
     "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 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 (create the content type schema, content type, and content items).

2. Upload the data source schemas to the Studio.

3. Create the dedicated Frontend components.

4. Add data sources to the dedicated page folder and configure data source filters in the Studio.

5. Add the Frontend components to a dedicated 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 using the following schema for the blog content.

   Blog content type schemajson

   {
     "$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.

3. Create three blog content items 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:

• 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 Amplienece, you must upload to the Studio the following data source schemas.

{
  "name": "Amplience Content",
  "customDataSourceType": "amplience/content",
  "category": "Content",
  "icon": "source",
  "schema": [
    {
      "name": "Content Selection",
      "fields": [
        {
          "label": "Content ID",
          "field": "contentId",
          "type": "text",
          "translatable": false
        }
      ]
    }
  ]
}

{
  "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 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 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.

   Blog component schema linked to the amplience/content data sourcejson

   {
     "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
           }
         ]
       }
     ]
   }
   Blog List component schema linked to the amplience/content-list data sourcejson

   {
     "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.

   index file of the Blog React componentTypeScript React

   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.

     index file of the amplience-blog Frontend componentTypeScript React

     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.

     index file of the amplience-blog-list Frontend componentTypeScript React

     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.

   Blog and Blog List Frontend components in the components index fileTypeScript React

   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 to the page folder 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. 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 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 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.
   • For the Amplience Content List data source:
     • In Configuration > Content Type field, enter the unique URL of your Amplience content type schema. In this example, we enter the URL of the Blog content type schema that we created.
     • In Configuration > Limit, set the maximum number of content items that you want to retrieve.

Add Frontend components to the page version

Finally, you must add the Frontend components you created to the page version 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. 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 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.

4. Use the 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.

   

6. Preview and save your changes. Your Amplience content is now rendered on your commercetools Frontend website.