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

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.

api.setElement({
  fsPageTemplate: 'product', // (1)
  id: 'Product Page', // (2)
  type: 'product', // (3)
  displayNames: { // (4)
    EN: 'Product name EN',
    DE: 'Product name DE',
  },
  locale: 'en_GB' // (5)
});
  1. FirstSpirit page template uid - will be used when the page has to be created when adding content
  2. ID from shop system
  3. Page type (product, category or content)
  4. Display names for various languages - will be used when the page has to be created when adding content
  5. The current locale

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.

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: January 30, 2023