This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Contentstack

Contentstack is an API-first headless Content Management System (CMS).

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

With the extension, you can deliver content from Contentstack, 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 Contentstack.

Prerequisites

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

Clone the extension repository and add the code to your project.
Register the extension in your project.

Get started

To start using the Contentstack extension, follow these steps:

Add the following project configuration fields to the project schema from the Studio.

Add Contentstack project configuration fieldsjson

{
  "name": "Contentstack Extension",
  "fields": [
    {
      "label": "Contentstack Api Key",
      "field": "EXTENSION_CONTENTSTACK_API_KEY",
      "type": "encrypted",
      "translatable": false,
      "required": true
    },
    {
      "label": "Contentstack delivery token",
      "field": "EXTENSION_CONTENTSTACK_DELIVERY_TOKEN",
      "type": "encrypted",
      "translatable": false,
      "required": true
    },
    {
      "label": "Contentstack environment",
      "field": "EXTENSION_CONTENTSTACK_ENVIRONMENT",
      "type": "encrypted",
      "translatable": false,
      "required": true
    },
    {
      "label": "Contentstack region",
      "field": "EXTENSION_CONTENTSTACK_REGION",
      "type": "encrypted",
      "translatable": false,
      "required": true
    }
  ]
}

Set the Contentstack configuration values from the Studio.

Deliver content with the Contentstack extension

To deliver any type of media content with the Contentstack extension, follow these steps:

Create your content on Contentstack by setting up the following items: Stack, Content Type, Environment, and Content Entries.
For this example, we created the Blog Entry Content Type and two blog posts as Content Entries.
Upload the data source schemas to the Studio.
Create the dedicated Frontend components.
Add data sources to the dedicated page folder and configure data source filters in the Studio.
Add the Frontend components to a dedicated page version in the Studio.

Upload data source schemas

The Contentstack extension comes with the following out-of-the-box data sources for Contentstack:

contentstack/content to fetch a single content item from Contentstack.
contentstack/content-list to fetch multiple content items from Contentstack with filters and configurations.

To fetch content from Contentstack, you must upload to the Studio the following data source schemas.

Schema of the Contentstack Content data sourcejson

{
  "name": "Contentstack Content",
  "category": "Content",
  "icon": "source",
  "schema": [
    {
      "name": "Content Selection",
      "fields": [
        {
          "label": "ContentType ID",
          "field": "contentTypeUid",
          "type": "text",
          "translatable": false
        },
        {
          "label": "Entry UiD",
          "field": "entryUid",
          "type": "text",
          "translatable": false
        }
      ]
    }
  ]
}

Schema of the Contentstack Content List data sourcejson

{
  "name": "Contentstack Content List",
  "category": "Content",
  "icon": "source",
  "schema": [
    {
      "name": "Content Selection",
      "fields": [
        {
          "label": "ContentType ID",
          "field": "contentTypeUid",
          "type": "text",
          "translatable": false
        },
        {
          "label": "Limit",
          "field": "limit",
          "type": "number",
          "default": 12
        }
      ]
    }
  ]
}

Create Frontend components

To render on your website the data coming from these data sources, you must create Frontend components 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:

Create the Frontend component schemas by uploading the following schemas to the Studio.

Blog component schema linked to the contentstack/content data sourcejson

{
  "tasticType": "commercetools/ui/content/contentstack-blog",
  "name": "commercetools UI Contentstack Blog",
  "icon": "bookmark",
  "category": "Content",
  "schema": [
    {
      "name": "Content",
      "fields": [
        {
          "label": "Contentstack Content",
          "field": "data",
          "type": "dataSource",
          "dataSourceType": "contentstack/content",
          "required": true
        }
      ]
    }
  ]
}

Blog List component schema linked to the contentstack/content-list data sourcejson

{
  "tasticType": "commercetools/ui/content/contentstack-blog-list",
  "name": "commercetools UI Contentstack Blog List",
  "icon": "bookmark",
  "category": "Content",
  "schema": [
    {
      "name": "Content",
      "fields": [
        {
          "label": "Contentstack Content",
          "field": "data",
          "type": "dataSource",
          "dataSourceType": "contentstack/content-list",
          "required": true
        }
      ]
    }
  ]
}

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>
  );
};

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

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

index file of the Contentstack Blog Frontend componentTypeScript React

import React from 'react';
import Blog from 'components/commercetools-ui/content/blog';
import { ContentstackLoader } from 'frontastic/lib/image';

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

const ContentstackBlogTastic = ({ data }) => {
  const blog = data?.data?.dataSource as Contentstack;

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

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

export default ContentstackBlogTastic;

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

index file of the Contentstack Blog List Frontend componentTypeScript React

import React from 'react';
import Blog from 'components/commercetools-ui/content/blog';
import { Contentstack } from '../contentstack-blog';
import { ContentstackLoader } from 'frontastic/lib/image';

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

  return (
    {blogs.map((blog) => (
      <Blog key={blog.uid} {...blog} imageLoader={ContentstackLoader} />
      ))}

    );
};

export default ContentstackBlogListTastic;

Reference the index.tsx files for the contentstack-blog and contentstack-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/contentstack-blog': BlogTastic,
'commercetools/ui/content/contentstack-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 Contentstack Content and Contentstack Content List data sources to the page folder 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:

If necessary, create a page folder. Otherwise, from the Studio home page or from the left menu, go to Site builder.
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.
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 Contentstack Content and Contentstack Content List data sources. When you select a data source, the data source filter editor opens.
Configure the data source filters as follows and save:
- For the Contentstack Content data source, enter the following values for the Contentstack Content Entry that you want to render.
  - In Content selection > ContentType ID field, enter the Content Type ID.
    In this example, we enter blog_entry that is the Content Type ID of the Blog Entry Content Type that we created.
  - In Content selection > Entry UID field, enter the Entry ID.
    In this example, we enter the Entry ID of one of the blog posts that we created.
- For the Contentstack Content List data source:
  - In Content selection > ContentType ID field, enter the Unique ID of the Contestack Content Type that you created and that you want to render.
    In this example, we enter blog_entry that is the Content Type ID of the Blog Entry Content Type that we created.
  - In Content selection > 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.

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 the Contentstack Blog Frontend component.

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

If necessary, create a page version. Otherwise, from the Studio home page or from the left menu, go to Site builder.
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.
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.
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 Contentstack Blog and the Contentstack Blog List Frontend components to the 1/1 layout element.
Select the Frontend component. Then, in Component settings > Content select the data source to associate to the Frontend component. In this example, we select Contentstack Content.
Preview and save your changes. Your Contentstack content is now rendered on your commercetools Frontend website.