Converters - Reusing Spartacus Components in Contentful

As part of your migration from SmartEdit to Contentful, reusing existing Spartacus components can significantly streamline the transition process. Our converter tool is designed to facilitate this by mapping Contentful data definitions to SmartEdit component definitions. This documentation outlines how to use the converter to ensure a smooth and efficient migration.

Configuration

Converters can be configured by importing the providers using withConverters. withConverters requires that CmsComponentData be passed. Using this approach allows us to use the same injectionToken as Spartacus without requiring our library to be installed with the exact same version as the one used on your project.

import { NcrContentfulModule,withConverters } from '@ncremental/ncr-contentful';
 
@NgModule({
declarations: [AppComponent],
imports: [
...
NcrContentfulModule.forRoot(withConverters(CmsComponentData))
]

see Example Usage below and start building your own converters.

Understanding the Converter

The converter serves as a bridge between Contentful and SmartEdit, allowing you to take advantage of your existing Spartacus components without extensive rework. By translating Contentful data structures into the format expected by SmartEdit components, the converter enables these components to receive and render the data as if it were sourced from SmartEdit.

Key Benefits

• Efficiency: Accelerate the migration process by leveraging existing components.
• Consistency: Maintain a consistent user experience during and after the migration.
• Cost-Effectiveness: Reduce development time and costs associated with building new components from scratch.

How It Works

The converter operates by intercepting data fetched from Contentful and transforming it into the structure required by Spartacus components. This process involves the following steps:

1. Data Fetching: Retrieve content data from Contentful.
2. Mapping: Apply mapping rules to convert the Contentful data format to the SmartEdit data structure.
3. Rendering: Pass the transformed data to the Spartacus component, which renders it as per usual.

Implementing the Converter

To implement the converter in your project, follow these steps:

1. Configuration: Set up the converter with mappings that correspond to your specific Contentful data models and Spartacus component structures.
2. Integration: Integrate the converter into your content fetching workflow, ensuring it processes Contentful data before it reaches the Spartacus components.
3. Testing: Thoroughly test the converted data with your Spartacus components to ensure accurate rendering and functionality.

Example Usage

Here’s a straightforward example of using the converter to map a Contentful Paragraph component model to a Spartacus CMS Paragraph component.

import {Injectable} from "@angular/core";
import {CmsComponentData} from "@spartacus/storefront";
import {of} from "rxjs";
import {CmsParagraphComponent} from "@spartacus/core";
import {AbstractConverter, NcrEntry} from "@ncremental/ncr-contentful";
 
 
export type TypeParagraph = NcrEntry<{
    title: string;
    html: string;
    classList: string[];
}>;
 
 
@Injectable({
    providedIn: 'root'
})
export class CMSParagraphConverter extends AbstractConverter<
    TypeParagraph,
    CmsParagraphComponent
> {
    override async convert(source: TypeParagraph): Promise<CmsComponentData<CmsParagraphComponent>> {
        return {
            uid: source.sys.id,
            data$: of({
                content: source.fields.html,
                container: source.fields.classList.join(' '),
                title: source.fields.title
            })
        };
    }
}
 

Once you have your converter, it’s simply a matter of updating your configuration to use the converter. Note that the component should still be loading your existing component. You do not need a new component for this.

import {NgModule} from "@angular/core";
import {provideConfiguration} from "@ncremental/ncr-contentful";
import {CmsParagraphModule} from "@spartacus/storefront";
import {CMSParagraphConverter} from "./cms-paragraph.converter";
 
@NgModule({
    imports: [CmsParagraphModule],
    providers: [
        provideConfiguration({
            components: {
                ncrComponentsParagraph: {
                    component : () =>
                        import('../custom-paragraph/custom-paragraph.component.ts').then((m) => m.CustomParagraphComponent),
                    converter: CMSParagraphConverter
                }
            }
        })
    ]
})
export class CustomCmsParagraphModule{}
 

Conclusion

By utilizing the converter, you can make your migration from SmartEdit to Contentful smoother and more efficient. Reusing existing Spartacus components minimizes the need for additional development work, helping you maintain focus on creating exceptional user experiences.

For more detailed information on configuring and using the converter, refer to our technical documentation or contact our support team.