Skip to content

Getting started

The Connect for Commerce Frontend API is divided into a client and a server module. The client module will be included in your storefront's clientside 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 use Connect for Commerce to its fullest, you need the following artifacts:

FirstSpirit project

In order for your FirstSpirit project to work you need to configure the following things:

  • Add an input component id and type to your page templates: 
    <?xml version="1.0" encoding="UTF-8"?>
<CMS_MODULE>

  <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" hidden="yes" preset="copy" singleLine="no" useLanguages="no">
    <LANGINFOS>
      <LANGINFO lang="*" label="type"/>
    </LANGINFOS>
  </CMS_INPUT_TEXT>

</CMS_MODULE>
  • Remove path to the Content Creator Extensions in the module configuration as they are already included in the Frontend API client module.

You can also use our reference project from GitHub.

Backend Server

Note

Our reference backend 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 server

You can also implement a backend using the module on your own. Just use the NPM module.

Frontend

Progressive Web Apps

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 client module is available as a NPM module.

npm install fcecom-frontend-api-client --save

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.setElement({
  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)
});
  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
  6. The current locale
FS Driven Pages
// FS Driven Pages
api.setElement({
  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, 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>

Implementing hooks

In order to interact with the Content Creator 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 Content Creator 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

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
  • FirstSpirit 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: September 7, 2023