1. Creation of a page in FirstSpirit

The following instructions describe how Shop-driven Pages and FirstSpirit-driven Pages can be created in FirstSpirit in the context of FirstSpirit Connect for Commerce. This document is addressing developers who are involved in the implementation of the project.

1.1. Shop-driven Pages

In order for the Connect for Commerce module to create a Shop-driven Page and link it to its equivalent in the shop system, the values listed below are required:

id

id corresponds to the identifier of the page in the shop system and is stored in the FormData of the page to be created. More information about mapping of ids can be found in the chapter Identifier mapping.

type

type corresponds to the page type (product, category or content) and is also stored in the FormData of the page. The combination of type and id makes a page uniquely identifiable and assignable to a page in the shop system.
Pages of type product always have an equivalent in the products report, pages of type category have an equivalent in the categories report and pages of type content have an equivalent in the content pages report.

fsPageTemplate

The fsPageTemplate specifies which FirstSpirit page template the page to be created is based on.

displayNames

The optional displayNames object defines the desired display names in the languages available in the FirstSpirit project.
It is important that the attribute names correspond to the abbreviation of the language configured in FirstSpirit. If no displayNames are passed or if there is not a value passedfor all project languages, the display name for the missing languages will be set according to the scheme <pageType>_<id>. More information about the usage of languages in FirstSpirit can be found in the FirstSpirit documentation.

The creation of Shop-driven Pages is fundamentally dependent on whether and how the Frontend API is used. The various cases are described below.

1.1.1. Page creation via Frontend API

With using the setPage function, Shop-driven Pages do not have to be created manually, but are created by using the Add Content button within the slot of the store page if they do not already exist. The Add Content button is automatically rendered to empty slots when using the setPage function.

Furthermore, Shop-driven Pages can be created using the createPage function. The section Use Cases > Create Page of the Frontend API documentation shows code examples for creating Shop-driven Pages.

1.1.2. Page creation via executable

The FirstSpirit Connect for Commerce - Create Reference Page Executable is available for creating Shop-driven Pages without using the Frontend API. This can be called from the storefronts context using Omnichannel Manager via the execute method of TPP-SNAP API.

The arguments mentioned above are passed to the executable in the form of an object when it is called.

Example function for calling the FirstSpirit Connect for Commerce - Create Reference Page Executable via TPP-SNAP API of the Omnichannel Manager
const createReferencePage = () => {
    const payload = {
        id: 'pageId',
        fsPageTemplate: 'product',
        type: 'product',
        displayNames: {
            DE: 'Displayname DE',
            EN: 'Displayname EN'
        }
    };
    TPP_SNAP.execute('class:FirstSpirit Connect for Commerce - Create Reference Page', payload);
};

The executable can also be used analogously in other contexts, such as in BeanShell scripts.

1.2. FirstSpirit-driven Pages

For systems in which the shop system specifies the page structure, it is necessary that when creating a FirstSpirit-driven Page an equivalent of the page in the shop system is also created. In this case, the Connect for Commerce module can generate the corresponding page using the bridge. The prerequisite for this is that the corresponding endpoint is implemented in the bridge and the checkbox Disable bridge content pages creation is not activated.

Screenshot showing the 'General' tab of the Connect for Commerce project component
Figure 1. Project component - Configuration dialog - General

1.2.1. Page creation via Frontend API

When using the Frontend API, after a page has been created via the Plus button in the ContentCreator, the Connect for Commerce module is communicated with to check whether an equivalent of the page needs to be created in the shop system.

1.2.2. Page creation via executable

The FirstSpirit Connect for Commerce - Preview Message Receiver is available for creating FirstSpirit-driven Pages without using the Frontend API. In this case, the corresponding handler for onRequestPreviewElement must be implemented using Omnichannel Manager’s TPP-SNAP API.

Example handler for invoking FirstSpirit Connect for Commerce - Preview Message Receiver via Omnichannel Manager’s TPP-SNAP API
let lastRequestedPreviewId;
TPP_SNAP.onRequestPreviewElement(async (previewId) => {
      if (this.lastRequestedPreviewId === previewId) return; /* do nothing if previewId did not change */
      this.lastRequestedPreviewId = previewId;
      const status = await TPP_SNAP.getElementStatus(previewId);
      if (status.storeType === 'SITESTORE' && status.id) {
        const topic = 'requestedPreviewElement';
        const pageRefId = `${status.id}`;
        const language = status.language;
        const payload = { pageRefId, language };
        TPP_SNAP.execute(
          'class:FirstSpirit Connect for Commerce - Preview Message Receiver',
          {
            topic,
            ...payload,
          },
          false
        );
        TPP_SNAP.setPreviewElement(previewId);
      }
    });
  }

FirstSpirit Connect for Commerce is a product of Crownpeak Technology GmbH, Dortmund, Germany.
Only a license agreed upon with Crownpeak Technology GmbH is valid for using the module.

3. Help

The Technical Support of the Crownpeak Technology GmbH provides expert technical support covering any topic related to the FirstSpirit™ product. You can get and find more help concerning relevant topics in our community.

4. Disclaimer

This document is provided for information purposes only. Crownpeak Technology GmbH may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. Crownpeak Technology GmbH specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.