Skip to content

Getting started

The Connect for Commerce Frontend API is divided into a client and a server module. The client module needs to be included in your storefront's client-side JavaScript and the server module needs to be implemented in a Node.js server application. We provide an Express-based reference implementation for said application on GitHub.

To learn more about Connect for Commerce, visit our documentation.

Prerequisites

In order to take full advantage of Connect for Commerce, you need the following artifacts:

FirstSpirit project

You can either use our reference project from GitHub for an easy setup or use your own FirstSpirit project by configuring following things:

  • Add the input components id and type to your page templates: 
    <CMS_MODULE>

    <CMS_GROUP name="technical">
        <LANGINFOS>
            <LANGINFO lang="*" label="Technical"/>
            <LANGINFO lang="DE" label="Technische Informationen"/>
        </LANGINFOS>

        <CMS_COMMENT>This section is needed to define the type of template and link it to data from the bridge. Changes to these templates can impact the functionality of the product FirstSpirit Connect for Commerce.
        </CMS_COMMENT>

        <CMS_INPUT_TEXT name="id" hFill="yes" singleLine="no" useLanguages="no">
            <LANGINFOS>
                <LANGINFO lang="*" label="Id"/>
            </LANGINFOS>
        </CMS_INPUT_TEXT>

        <CMS_INPUT_TEXT name="type" hFill="yes" preset="copy" singleLine="no" useLanguages="no">
            <LANGINFOS>
                <LANGINFO lang="*" label="Type"/>
                <LANGINFO lang="DE" label="Typ"/>
            </LANGINFOS>
        </CMS_INPUT_TEXT>
    </CMS_GROUP>

</CMS_MODULE>
  • Remove the path to the Content Creator Extension in the project app configuration of the Connect for Commerce module as it is already included in the Frontend API client module.
  • Select CaaS Connect Preview Rendering Plugin in the project component CXT ContentCreator: Preview ConfigurationProjectApp and install the web application CaaS Connect Web App into the ContentCreator web app (global or projectwide).
  • Disable Preview: Create Section in the CXT ContentCreator: Feature Configuration Project App. The Frontend API will add its own button to create sections.

Backend Server

In order to communicate with the CaaS a backend service is needed. We provide a reference implementation on Github.

Note

Our reference backend service requires at least Node.js v18.

  1. Clone this repository and follow the setup instructions.
  2. Copy the config/default.yml to config/local.yml and enter the required values as described in the comments.
  3. Run: 
    npm i # install
npm start # start backend service

You can also implement your own backend service using the Frontend API server module.

Frontend

Progressive Web Apps / Single Page Applications

This page explains how to build Progressive Web Apps (PWA) / Single Page Applications (SPA). If your use case involves server-side rendered content, have a look at how to use Connect for Commerce with static pages.

Install in your storefront

The Frontend API client module is available as a NPM module.

npm install fcecom-frontend-api-client

Initialize

In your storefront's JavaScript entrypoint, you need to initialize the Frontend API.

import { EcomApi, LogLevel } from 'fcecom-frontend-api-client';

const api = new EcomApi(
  'http://localhost:3001/api', // (1)
  LogLevel.DEBUG               // (2)
);

api.setDefaultLocale('de_DE'); // (3)

await api.init();
  1. The URL to your backend service
  2. The loglevel to use for clientside logs
  3. Default language to use (can also be set on the server)

Setting elements

When navigating to a page within the storefront, you should call the following code to let the API know its contents. The API differentiates between Shop driven and FirstSpirit driven pages.

Shop Driven Pages
api.setPage({
  isFsDriven: false,           // (1)
  fsPageTemplate: 'product',   // (2)
  id: 'Product Page',          // (3)
  type: 'product',             // (4)
  displayNames: {              // (5)
    EN: 'Product name EN',
    DE: 'Product name DE',
  },
  locale: 'en_GB',             // (6)
  ensureExistence: true        // (7)
});
  1. Flag to mark if it is an FS driven page
  2. FirstSpirit page template uid - will be used when the page has to be created when adding content
  3. ID from shop system
  4. Page type (product, category or content)
  5. Display names for various languages - will be used when the page has to be created when adding content. The language abbreviation must correspond to the according language defined in the FirstSpirit project. Either two letters or in locale format, all uppercase.
  6. The current locale
  7. If the page does not exist, it can be created. For this to work, the pageTarget has to be a representation of a shop-driven page.
FS Driven Pages
api.setPage({
  isFsDriven: true,            // (1)
  fsPageId: 'Content Page',    // (2)
  locale: 'en_GB'              // (3)  
});
  1. Flag to mark if it is an FS driven page
  2. ID of the page in the CaaS
  3. The current locale

Rendering content

The slots that should contain content from FirstSpirit need to be marked with the data-fcecom-slot-name attribute. Empty slots will be populated with an "Add content" button by this API. If a slot contains sections, it is your responsibility to render its contents. In order to be able to edit these sections with TPP, you need to add their previewId to the DOM using data-preview-id.

Your HTML could look like this:

<div data-fcecom-slot-name="sup_content">
  <!-- Empty section -->
</div>

<div data-fcecom-slot-name="sub_content">
  <div data-preview-id="a8e2d8dd-a279-481a-b26d-a65aecd2ffaa">
    <!-- Section contents -->
  </div>
  <div data-preview-id="2a7cfeca-ce26-4f06-9587-475b81dd7fde">
    <!-- Section contents -->
  </div>
</div>

The name of the data-fcecom-slot-name attribute needs to match the name of a content area of a page template.

Implementing hooks

In order to interact with the ContentCreator while editing, you can provide various callbacks:

  • contentChange - To react to sections being edited
  • createSection - To react to sections being added
  • openStoreFrontUrl - To react to a navigation intent triggered by a report
  • requestPreviewElement - To react to a navigation intent triggered by the ContentCreator navigation
  • createPage - To react to pages being created

You can learn more about the hooks on their dedicated page.

Static pages

When using server-side rendered content you can include the Frontend API client library in a specific artifact that renders content based on HTML-attributes.

Include in your storefront

Simply add the static.js file to your frontend using a <script>-tag and add it to the bottom of your HTML to ensure that the DOM is present before the script is being executed.

To configure the API, the following attributes have to be added to the <script>-tag:

  • data-fs-base-url - The URL to your backend service
  • data-fs-log-level - The loglevel to use for clientside logs

Adding information

Information about the current element are written to the <body> element. The following attributes need to be present:

  • data-fs-page-id - ID from the shop system
  • data-fs-page-type - Page type (product, category or content)
  • data-fs-page-template - FirstSpirit page template uid - will be used when the page has to be created when adding content
  • data-fs-name-<language> - Display names for different languages. <language> has to correspond to the abbreviation of the corresponding language defined in FirstSpirit. Will be used when the page has to be created when adding content.

Implementing hooks

In order to interact with the Content Creator while editing, you can provide the same callbacks as mentioned above. They can be added or removed using the global FCECOM.addHook() and FCECOM.removeHook() methods.

There are a few default callbacks beeing added if no other callback is provided:

  • openStoreFrontUrl - Will navigate to the URL received in the payload
  • sectionCreated - Will reload the page
  • contentChanged - Will reload the page

Troubleshooting

Each part of the Connect for Commerce stack writes logs in case of an error:

  • Frontend API client - Logs to browser console
  • Frontend API server - Logs to stdout
  • Connect for Commerce module - Logs to FirstSpirit Tomcat server log
  • Reference bridges - Log to stdout

In addition to that, we use fixed codes when the stack encounters an error when performing an action from within the Content Creator. These codes are displayed with a dialog to allow editors to react. You can find a list of these codes in our Connect for Commerce documentation.

Last update: January 30, 2024