1. Introduction

This document is aimed at administrators and developers and describes the required steps to set up FirstSpirit Connect for Commerce. Additional information about the architecture and functionalities provided by Connect for Commerce can be found in the main documentation.

Required skills and estimations for MVP implementations are outlined in the main documentation.

2. Getting Started

The following section describes the required steps to set up Connect for Commerce.

2.1. FirstSpirit project

In order to use Connect for Commerce, a FirstSpirit project is required. It is possible to use either a reference project or an individual project. In both cases, it is necessary to contact Technical Support to set up the project.

2.1.1. Reference project

The Crownpeak Technology GmbH provides the FirstSpirit Connect for Commerce Reference Project, hereinafter referred to as the reference project, which contains ready-made page templates and section templates. The page templates and section templates provide a basis for further development in order to cover more specific use cases.

2.1.2. Individual project

It is also possible to create a new project that can be configured according to your own ideas.

Please note the following points:

Configuration

After the project has been installed on the FirstSpirit server, the Connect for Commerce module must be configured.

BasicWorkflows (optional)

The release and deletion of content by the editorial team is handled via workflows. BasicWorkflows serves the purpose of being an alternative to project-specific workflows.

Setting up the BasicWorkflows module

The use of BasicWorkflows in the ContentCreator requires the selection of the provided BasicWorkflows status provider in the Project Properties  ContentCreator area within the ServerManager.

Screenshot showing the selection of the 'Element Status Provider' in the 'ContentCreator' area of the ServerManager
Figure 1. Element status provider

Templates

The BasicWorkflows require different templates. These usually require an import via the context menu into the FirstSpirit project that is used.

Assignment of rights

Last but not least, the workflows in the individual administrations must be permitted in order to be executed on FirstSpirit elements. To do this, the assignment of rights can be opened in the SiteArchitect on the root nodes of the administration via the context menu entry Extras  Change rights.

The rights set on the root node of the administrations to execute the workflows are assigned to the group Everyone. If this is not desired, the rights need to be adjusted manually.

Further information about installation, configuration and functionality of the workflows can be found in the BasicWorkflows documentation.
YouTube-DAP-Integration (optional)

YouTube videos can be displayed in a report using the YouTube-DAP-Integration. The videos displayed in the report can be referenced using the provided Data Access Plugin. The setup is described in the associated readme file.

Interactive Video (optional)

In order to use the Interactive Video, the YouTube-DAP-Integration module must be installed and configured. Additionally, the page templates that are provided with the module need to be imported.

Templates und Data Access Plugins

Different page templates are required to create various page types.

For product detail pages, a page template with the UID product must be created.

For category detail pages, a page template with the UID category must be created.

As all other pages are treated as content pages, the UID of the template is not relevant for the function in this case. Different page templates can therefore be created for content pages. All page templates must contain the following input components described below.

The text input components id and type need to be added for each page template. In the id field, the Connect for Commerce module stores the identifier of the associated page from the shop system. The value entered in this field should not normally be changed. For this reason, it is recommended to hide the field.

The type field is used to identify the page type. In order to set the type automatically when a page is created, default values should be set. This field should also be hidden to prevent subsequent changes.

Input components for identifying a page 
<?xml version="1.0" encoding="UTF-8"?>
<CMS_MODULE>

  <CMS_INPUT_TEXT name="id" hFill="yes" hidden="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>

An associated Data Access Plugin (DAP) exists for the types content, product and category. It enables the linking of the provided data and its integration into editorial content. For example, in the case of the product type, it is possible to link products and create product teasers.

It is sufficient to add an FS_INDEX input component to the section template in which content is to be linked to a product:

FS_INDEX input component in section template 
<FS_INDEX name="st_product" height="1" useLanguages="no">
    <LANGINFOS>
        <LANGINFO lang="*" label=""/>
    </LANGINFOS>
    <SOURCE name="FirstSpirit Connect for Commerce/FirstSpirit Connect for Commerce - Products Data Access Plugin"/>
</FS_INDEX>

Content can be linked to both categories and other content pages in the same way. Only the DAP to be linked must be exchanged accordingly. The following three DAPs are available:

  • FirstSpirit Connect for Commerce - Products Data Access Plugin

  • FirstSpirit Connect for Commerce - Categories Data Access Plugin

  • FirstSpirit Connect for Commerce - ContentPages Data Access Plugin

2.2. Definition of the external preview URL

The storefront can be displayed in the ContentCreator using the Omnichannel Manager. The URL of the storefront, which contains preview content, must therefore be specified in the ContentCreator properties.

The configuration is set in the ServerManager under Project Properties  ContentCreator.

Screenshot showing the 'External Ppreview URL' configuration in the 'ContentCreator' section of the ServerManager
Figure 2. Extternal preview URL

2.3. Configuration of the project component

Some project-specific information is required for the use of the Connect for Commerce module. It needs to be specified via the project component, which must be added to the project. If the reference project is used, the project component is already added.

The configuration must be set in ServerManager in the Project Properties  project component area.

Screenshot showing the project components area within the Project Properties
Figure 3. Project Properties - project component

A list of all existing project components can be seen in the main panel. The entry FirstSpirit Connect for Commerce - Project Configuration should be selected and the corresponding configuration dialog opened via Configure.

The following settings can be made in the General tab:

  • The absolute path to the ContentCreator extension file

  • Use ContentCreator Extension

  • Deactivate the creation of content pages via Bridge

If the Connect for Commerce Frontend API is not used, the ContentCreator extension must be used. This corresponds to a JavaScript file, which needs to be accessible from the ContentCreator. The script enables the communication between ContentCreator and the FirstSpirit Connect for Commerce module. The implementation of the ContentCreator extension is provided on GitHub.

When using the Frontend API, the checkbox Use ContentCreator Extension must be deactivated.

The Connect for Commerce module can handle the creation of content pages in two different ways:

  1. When creating a content page in the ContentCreator, an equivalent of the page in the shop system is created via the bridge. This is only necessary if the page structure that is displayed in the storefront must be identical to the structure from the shop system.

  2. The checkbox Deactivate creation of content pages via bridge can be used to prevent the behavior of the first case. In this way, content pages can be created whose content and structure is defined exclusively by FirstSpirit.

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

The following settings are set in the Bridge tab:

  • The API URL of the bridge

  • The access data for logging in to the bridge

The connection to the bridge can also be tested using the Test bridge connection button.

Screenshot showing the 'Bridge' tab of the Connect for Commerce project component
Figure 5. project component - Configuration dialog - Bridge

In the Reports tab, the number of category levels can be optionally defined for both the category and product reports. These limit the display of the category tree within the corresponding report to the number of desired levels, for which the value 3 is set by default.

Screenshot showing the 'Reports' tab of the Connect for Commerce project component
Figure 6. project component - Configuration dialog - Reports

In the Cache tab, both the maximum number and the lifespan of elements in the cache can be set. The size of the cache is a balance between memory consumption and response speed and is project-dependent, just like the lifespan setting, which represents a balance between the freshness of the data and minimal load in the shop system / bridge.

Some details about the input field:

  • The cache lifespan must be entered in the specified format.

  • Incorrect entries reset the value to the last version.

  • Entering non-numbers or emptying the field resets the configuration to the default value of 5 minutes.

  • Overflowing values are added up. For example, entering 61 seconds will be saved as 1 minute and 1 second. The next time you open the project app, the converted value will be displayed.

The configuration is applied immediately. However, elements already contained in the cache will only be removed with the next request to the bridge and only according to the specified rules.

Screenshot showing the 'Cache' tab of the Connect for Commerce project component
Figure 7. project component - Configuration dialog - Cache

The use of the interactive video also requires the configuration of the YouTube-DAP-Integration. This is explained in the associated readme file.

The reference project also includes the CXT ContentCreator: Feature Configuration ProjectApp. It contains a predefined configuration where adjustments to it can lead to a change in the behavior of the ContentCreator. The configuration should therefore only be adjusted after prior consultation with Technical Support.

2.3.1. Connecting the bridge

The bridge represents the implementation of the FirstSpirit Connect for Commerce API and is the connection between FirstSpirit and the shop system.

Deployment of the bridge

Information on implementing the bridge can be found in the corresponding How-To guide.

Connection test

The project component offers the possibility to test the connection between the Connect for Commerce module and the bridge.

The log window shows the result of the connection test in a detail. Successful requests are clearly displayed as well as failed ones. It also shows if an endpoint is deprecated and removed in the near future.

bridge test connection success en
Figure 8. Example Output: Successful connection test
bridge test connection disabled features en
Figure 9. Example Output: Deactivated feature
bridge test connection missing project uuid header en
Figure 10. Example Output: The header with the project UUID was apparently not sent to the bridge.
bridge test connection bridge down en
Figure 11. Example Output: Failed connection test

2.4. Frontend

Two different options are available for connecting the storefront.

Please note that only one of the two options described below needs to be implemented.

2.4.1. Integration of the Connect for Commerce Frontend API

Information on using the Frontend API can be found in the documentation.

2.4.2. Custom implementation of the frontend integration

Basically, the following points must be taken into account for the self-implementation:

3. Reference Project

The FirstSpirit Connect for Commerce module provides different ways to access shop content and use it in FirstSpirit. This requires different components both within the FirstSpirit project and in the storefront. The following subchapters describe these components and the dependencies between them using the reference project provided.

The reference project serves as a guide and includes sample templates and best practices for developers to enable a quick and smooth implementation. You can also find the reference project on GitHub.

3.1. Languages

In order to be able to maintain store content in multiple languages with FirstSpirit, it is necessary to create a clear assignment between store languages and project languages. The languages defined in the FirstSpirit project should therefore be selected so that their abbreviations correspond to the abbreviations of the store languages.

Within the reference project, DE and EN are preconfigured as available languages. However, if the shop requires language abbreviations in the locale format (e.g. en_GB), the two languages DE and EN must be removed and replaced by project languages with appropriate abbreviations. When assigning shop languages to project languages, no distinction is made between upper and lower case letters.

Further information on the selection and configuration of languages in the project can be found in the FirstSpirit online documentation.

3.2. Pages

In contrast to the delivery of content, using Connect for Commerce shifts its creation and maintenance to FirstSpirit. Therefore FirstSpirit provides the ContentCreator. In it, both the pages created with FirstSpirit and the already existing shop pages can be displayed and enriched with editorial content using the Omnichannel Manager.

Editorial content in FirstSpirit is always created and edited on the basis of a page.

The reference project provides the following page templates for content, product, and category pages:

  • Homepage

  • Contentpage

  • Categorypage

  • Productpage

  • Landingpage

Homepage

The homepage page template is an example of so-called static pages, such as the start page, the login page, or the shopping cart. Static pages have a fixed URL and generally exist only once within a shop. They are predefined by the shop and have their own layout, which distinguishes them from the other pages. For this reason, they each require their own template.

Content pages

The content page templates form the basis for the project’s standard pages and are therefore referenced multiple times.

Category / Product pages

Both the category and product pages are used to display the products originating from the connected shop system. Product pages represent the detailed view of a specific product. In contrast, category pages provide an overview of all products belonging to a category.

The category and product information from the connected shop is integrated, among other things, via two reports provided by the Connect for Commerce module in the ContentCreator.

Landing pages

Landing pages are also content pages and can be topic-oriented or temporary pages, among others.

3.3. Content Areas

The page templates contained in the reference project have predefined content areas that are mapped to the editable content areas marked in the storefront.

A list of the available content areas can be found in the following table:

Page Template

Content Areas

Homepage

stage, content

Content Page

stage, content

Category Page

stage, sup_content, sub_content

Product Page

stage, sup_content, sub_content

Landing page

stage, left_content, right_content, content, sub_content

In order to mark an area in the storefront as an editable content area, it is necessary to provide the HTML element with the reference name of the content area to be used from the page template:

Example: Marking a content area 
<div data-fcecom-slot-name="stage">
  ...
</div>

It needs to be ensured that the names of the content areas from the storefront and the FirstSpirit project match. This is necessary to guarantee successful mapping of the content areas.

3.4. Sections

Within the reference project the maintainable areas of a shop page are represented by the content areas of a FirstSpirit page template. Sections can be added to them; each one corresponds to the equivalent component of the shop page.

For this, the reference project provides the following section templates:

  • Banner

  • Carousel

  • Interactive Video

  • Interactive Image

  • Text/Image

  • Featured Products

  • Modal

  • Multi-Slot Container

  • Teaser Grid

Banner

The banner corresponds to a single image in horizontal format, which is, by default, included in the header of a page.

The section allows the selection of a cropable image, the specification of a headline, a subtitle and a link. The text color as well as the position is specifiable for the headline, the subtitle and the link.

Carousel

The carousel resembles the banner in form and editability. Unlike it, however, it embeds multiple images that rotate continuously.

Interactive Video

The interactive video allows products to be displayed and referenced at specific times in a video.
The section requires the selection of a video in which text/image or product elements can be displayed at any point of time.

Text/Image element
A text/image element consists of an image, a caption, a text, and an internal link.

Product element
A product element contains a product photo, a product name, a product description and optionally an image and a text.

In order to use the Interactive Video the installation and configuration of the modules YouTube-DAP-Integration and Interactive Video is mandatory. Otherwise this section has no functionality.
Interactive Image

The interactive image allows products to be displayed and referenced on an image map.

The section requires the selection of an image in which links to product detailpages can be displayed. In addition, a headline and text can be maintained alongside the image.

Text/Image

The text/image section expects the input of a text. In addition, it allows the specification of a headline and the selection of an image that can be positioned left or right of the text.

Featured Products

The Featured Products is a layout component that, in addition to entering a heading and a text, enables the automatic arrangement of product elements. The arrangement of the elements depends on their number: Up to a number of three elements are displayed next to each other. Additional elements are grouped together, also up to three elements, and displayed in additional lines below.

A product element contains the product image, the product name and the product description. The information for a product element comes by default from the FirstSpirit Connect for Commerce - Products Data Access Plugin.

Modal

The modal is a layout component that presents information in a pop-up dialog box that overlays the primary content.

It allows the selection of an image as well as the input of a heading, a subheading and a text. Additionally it allows the definition of a reference.

The modal is not a standard section template and can only be selected by editing the page information in the ContentCreator navigation. In the reference project, the modal component is only allowed for the homepage page template.
Multi-Slot Container

The Multi Slot Container is a layout component that enables the automatic arrangement of content, category or product elements in addition to entering a heading. The arrangement of the elements depends on their number: Up to a number of four elements, they are displayed side by side and scaled accordingly. Additional elements are grouped together, also up to four elements, and displayed in additional lines below.

All elements allow the input of a headline, a subtitle and a teaser text as well as the selection of an image for which an alternative text can be specified. Furthermore, the display of each element contains a button whose label is freely definable and which refers to the detailed view of the respective element. This button is only visible if the multi slot container contains only one element.

In addition to the input options mentioned above, the content element allows the definition of a reference. Also in this case all reference types available in the reference project are allowed for this.

In addition to the input components mentioned above, the category element has a component for selecting a category. If no image is selected for a category, the category element displays a default image.

The information for a category and product element comes by default from the FirstSpirit Connect for Commerce - Categories Data Access Plugin and FirstSpirit Connect for Commerce - Products Data Access Plugin. They serve as a fallback and are overwritten by entries in the named components.

Teaser Grid

The teaser grid is a layout component that allows free arrangement and scaling of different elements.

The elements can correspond to an image or a video, for each of which a link as well as a headline, a subtitle and a text can be defined.

The editorial contents maintained in FirstSpirit can contain the following references, which link them with other contents.

For this, the reference project provides the following reference templates:

  • Category and product link

  • Content link

  • External link

  • CTA reference

  • Interactive product reference

  • DOM reference

Category and product links

The Connect for Commerce module provides a report for products and categories in the ContentCreator. They serve to display the category and product information coming from the shop system, which can be used for links to category or product detail pages.

Therefore, the reference project contains the link templates category_link and product_link, which correspond to a category or product link. They enable category or product detail pages to be referenced.

Content link

The reference project provides the link template content_link. It allows the linking of pages that are maintained within the reference project.

External link

The external_link reference template corresponds to an external reference and works similarly to the content reference. For an external reference, a URL is needed instead of a page reference, as with the content reference.

CTA reference

A call-to-action reference is provided with the cta_link reference template in the reference project.
The reference text is displayed as either a light or dark CTA button. In addition, a link can be selected from the previous link types.

Interactive product reference

The section template Interactive Image uses only the interactive_product_link reference template.
It functions similarly to the product link with the exception that a caption can also be maintained.

DOM references

The dom_category_link, dom_content_link, dom_external_link, and dom_product_link reference templates included in the reference project function similarly to the equivalent reference templates described previously. These link templates are used in the DOM text editor and provide an additional field for the link text.

4. References

Below you will find an overview of all references that support you in setting up Connect for Commerce:

Documentations:

APIs:

Reference implementations on GitHub:

Modules:

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.

6. 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.

7. 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.