@commercetools-demo/cms-asset

@commercetools-demo/cms-asset

A collection of web components for implementing CMS functionality in commercetools projects.

Installation

npm install @commercetools-demo/cms-asset

or

yarn add @commercetools-demo/cms-asset

React Usage

Create a wrapper component

import React, { useRef, useEffect } from 'react';

interface Props {
  baseurl?: string;
  'business-unit-key'?: string;
  'available-locales'?: string;
  locale?: string;
}

const CMSAppWrapper: React.FC<Props> = ({ ...props }) => {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (ref.current) {
      const element = document.createElement('cms-app');

      Object.entries(props).forEach(([key, value]) => {
        if (typeof value === 'string') {
          element.setAttribute(key, value);
        }
      });

      ref.current.innerHTML = '';
      ref.current.appendChild(element);
    }
  }, []);

  return (
    <div
      ref={ref}
      // override styles here
      style={
        {
          '--selector-button-selected-background': 'rgb(23 58 95)',
        } as React.CSSProperties
      }
    />
  );
};

export default CMSAppWrapper;

And use it in your application

import '@commercetools-demo/cms-asset';
import CMSAppWrapper from '@commercetools-demo/cms-asset/assets/CMSAppWrapper';

return (
  <CMSAppWrapper
    baseurl="/service"
    'business-unit-key'="your-business-unit"
    locale="en"
    'available-locales'='["en", "de"]'
  />
)

Usage

This package provides three main web components:

• <cms-app> - The main CMS editor application
• <cms-renderer> - Renders a CMS page by key or route
• <content-item-renderer> - Renders a specific content item

1. CMS App Component

The main component for managing and editing CMS content.

<cms-app 
  baseurl="/service" 
  business-unit-key="your-business-unit" 
  locale="en"
  available-locales='["en", "de"]'
></cms-app>

Properties

Property	Attribute	Type	Description	Required
baseURL	baseurl	String	Base URL for API endpoints	Yes
businessUnitKey	business-unit-key	String	The business unit key for the CMS	Yes
locale	locale	String	The current locale	No
availableLocales	available-locales	Array (JSON string)	Available locales as JSON string	No

2. CMS Renderer Component

Renders a CMS page by key or route.

<cms-renderer 
  baseurl="/service" 
  business-unit-key="your-business-unit" 
  key="homepage"
  locale="en"
></cms-renderer>

OR

<cms-renderer 
  baseurl="/service" 
  business-unit-key="your-business-unit" 
  route="/home"
  locale="en"
></cms-renderer>

Properties

Property	Attribute	Type	Description	Required
baseURL	baseurl	String	Base URL for API endpoints	Yes
businessUnitKey	business-unit-key	String	The business unit key for the CMS	Yes
key	key	String	The key of the page to render	Either key or route required
route	route	String	The route of the page to render	Either key or route required
locale	locale	String	The current locale	No
availableLocales	available-locales	Array	Available locales	No

3. Content Item Renderer Component

Renders a specific content item.

<content-item-renderer 
  baseurl="/service" 
  business-unit-key="your-business-unit" 
  key="product-teaser-123"
  state="published"
></content-item-renderer>

Properties

Property	Attribute	Type	Description	Required
baseURL	baseurl	String	Base URL for API endpoints	Yes
businessUnitKey	business-unit-key	String	The business unit key for the CMS	Yes
key	key	String	The key of the content item to render	Yes
state	state	String	The state of the content item: "published" or "preview"	No (default: "published")

Required API Endpoints

The following API endpoints should be available at the specified baseURL:

Page Endpoints

• GET {baseURL}/{businessUnitKey}/pages - Get all pages
• GET {baseURL}/{businessUnitKey}/pages/{key} - Get a specific page by key
• POST {baseURL}/{businessUnitKey}/pages/{key} - Create a new page
• PUT {baseURL}/{businessUnitKey}/pages/{key} - Update a page
• DELETE {baseURL}/{businessUnitKey}/pages/{key} - Delete a page

Content Type Endpoints

• GET {baseURL}/content-type - Get all content types
• GET {baseURL}/content-type/{key} - Get a specific content type
• POST {baseURL}/content-type/{key} - Create a content type
• PUT {baseURL}/content-type/{key} - Update a content type
• DELETE {baseURL}/content-type/{key} - Delete a content type

Content Item Endpoints

• GET {baseURL}/{businessUnitKey}/content-items - Get all content items
• GET {baseURL}/{businessUnitKey}/content-items/{key} - Get a specific content item
• GET {baseURL}/{businessUnitKey}/preview/content-items/{key} - Get a content item in preview state
• GET {baseURL}/{businessUnitKey}/published/content-items/{key} - Get a content item in published state
• POST {baseURL}/{businessUnitKey}/content-items/{key} - Create a content item
• PUT {baseURL}/{businessUnitKey}/content-items/{key} - Update a content item
• DELETE {baseURL}/{businessUnitKey}/content-items/{key} - Delete a content item

State Management Endpoints

• GET {baseURL}/{businessUnitKey}/content-items/{key}/states - Get states for a content item

• PUT {baseURL}/{businessUnitKey}/content-items/{key}/states/draft - Save draft state for a content item

• PUT {baseURL}/{businessUnitKey}/content-items/{key}/states/published - Publish a content item

• DELETE {baseURL}/{businessUnitKey}/content-items/{key}/states/draft - Revert draft changes for a content item

• GET {baseURL}/{businessUnitKey}/pages/{key}/states - Get states for a page

• PUT {baseURL}/{businessUnitKey}/pages/{key}/states/draft - Save draft state for a page

• PUT {baseURL}/{businessUnitKey}/pages/{key}/states/published - Publish a page

• DELETE {baseURL}/{businessUnitKey}/pages/{key}/states/draft - Revert draft changes for a page

Version Management Endpoints

• GET {baseURL}/{businessUnitKey}/content-items/{key}/versions - Get versions for a content item

• GET {baseURL}/{businessUnitKey}/content-items/{key}/versions/{versionId} - Get a specific content item version

• POST {baseURL}/{businessUnitKey}/content-items/{key}/versions - Save a new content item version

• GET {baseURL}/{businessUnitKey}/pages/{key}/versions - Get versions for a page

• GET {baseURL}/{businessUnitKey}/pages/{key}/versions/{versionId} - Get a specific page version

• POST {baseURL}/{businessUnitKey}/pages/{key}/versions - Save a new page version

File Management Endpoints

• GET {baseURL}/media-library - Get media library items
• POST {baseURL}/upload-file - Upload a file to the media library

Data Source Endpoints

• GET {baseURL}/datasource - Get all datasources
• GET {baseURL}/datasource/{key} - Get a specific datasource
• POST {baseURL}/datasource/{key} - Create a datasource
• PUT {baseURL}/datasource/{key} - Update a datasource
• DELETE {baseURL}/datasource/{key} - Delete a datasource

Code Compilation Endpoint

• POST {baseURL}/compile-upload - Compile and upload code for a content type

Example Implementation

<!DOCTYPE html>
<html>
<head>
  <title>CMS Example</title>
  <script type="module" src="path/to/node_modules/@commercetools-demo/cms-asset/dist/index.js"></script>
</head>
<body>
  <!-- Render a specific page by key -->
  <cms-renderer 
    baseurl="/api/cms" 
    business-unit-key="my-business-unit" 
    key="homepage"
    locale="en">
  </cms-renderer>
  
  <!-- Render a content item -->
  <content-item-renderer 
    baseurl="/api/cms" 
    business-unit-key="my-business-unit" 
    key="banner-123">
  </content-item-renderer>
</body>
</html>

Contributing

Please refer to the project's GitHub repository for contribution guidelines.

License

This project is part of the commercetools demo platform.