FirstSpirit Connect for Commerce: How-To Guides

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.1.3. Bulk page creation via executable

In addition to creating individual Shop-driven Pages via the FirstSpirit Connect for Commerce - Create Reference Page Executable, it is also possible to create pages for all products / subcategories of a category programmatically. The FirstSpirit Connect for Commerce - Bulk Create Product Pages Executable and FirstSpirit Connect for Commerce - Bulk Create Category Pages Executable are available for this purpose, which are primarily intended for use in BeanShell scripts or schedule entries.

The following parameters can be passed to the executables when they are called:

context: context corresponds to the FirstSpirit context and must be specified when calling the executable within a BeanShell script. When calling within a schedule entry script, the context is automatically provided and does not need to be passed as a parameter.
bulk_product_page_creation_template / bulk_category_page_creation_template: This mandatory parameter is used to select the FirstSpirit page template to be used.
bulk_product_page_creation_subcategory / bulk_category_page_creation_subcategory: By specifying a subcategory, the creation of pages can be restricted to products / subcategories of a specific category.
bulk_product_page_creation_subfolder / bulk_category_page_creation_subfolder: Specifies the subfolder below the directory for product or category pages within which the created pages are to be created. The name must correspond to the default for reference names in FirstSpirit and therefore must not contain any special characters or spaces with the exception of the underscore. The reference name of the generated subfolder is prefixed with c_ (for categories) or p_ (for products) to ensure uniqueness. The display name corresponds to the specified name of the subfolder. If this parameter is not specified, all pages are created at the top level within the directory for product or category pages.
bulk_product_page_creation_release / bulk_category_page_creation_release: This parameter is used to configure the automatic release of the created pages.

Example call of the FirstSpirit Connect for Commerce - Bulk Create Product Pages Executable via BeanShell script

import de.espirit.firstspirit.access.*;
import de.espirit.firstspirit.access.script.Executable;

parameters = new HashMap();
parameters.put("context", context);
parameters.put("bulk_product_page_creation_subcategory", "smart-tvs");
parameters.put("bulk_product_page_creation_template", "page_marginalia");
parameters.put("bulk_product_page_creation_subfolder", "smart_tvs");
parameters.put("bulk_product_page_creation_release", "true");
moduleAgent = context.requireSpecialist(ModuleAgent.TYPE);
executable = moduleAgent.getTypeForName("FirstSpirit Connect for Commerce - Bulk Create Product Pages", Executable.class).newInstance();
executable.execute(parameters, null, null);

Call the FirstSpirit Connect for Commerce - Bulk Create Category Pages Executable via schedule entry script

#!executable-class
FirstSpirit Connect for Commerce - Bulk Create Category Pages

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);
      }
    });
  }

2. Legal notices

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.