FirstSpirit Connect

For Spryker Commerce OS

e-Spirit AG

2021-04-01
Table of Contents

1. Introduction

FirstSpirit is used to create versatile and project-specific content. Thanks to the FirstSpirit Connect for Spryker Commerce OS module, it is possible to transfer these contents to the e-commerce shop system Spryker Commerce OS and use it there.

In the remainder of the document the abbreviated form "Spryker" is used instead of "Spryker Commerce OS".

Furthermore, the entire documentation is geared towards connecting to the Spryker B2C Demo Shop in version 202009.0. Mention of the shop therefore refers exclusively to the B2C Demo Shop.

The module combines the functional strengths of both systems, delivering the key advantages and create a successful overall system made up of two areas that work in parallel and are largely decoupled from one another:

Components on the FirstSpirit side
These components are used for creating and maintaining editorial data. The data is transferred in JSON format to the relevant CaaS instance, and queried from there by Spryker.
Components on the Spryker side
These components are used for the integration of the editorial content created in FirstSpirit. Spryker imports this data and integrates it into the shop.

Included in the delivery of the FirstSpirit Connect for Spryker Commerce OS module is the reference project FirstSpirit Connect Reference Project, which is available as a GitHub repository. This documentation is consistently based on the reference project and provides an explanation of the functions made available by the module using common use cases.

This document is aimed at both Spryker and FirstSpirit developers, who should be able to perform the integration using this document as a guide.

It is not intended as a manual for FirstSpirit editors.

It is assumed that the reader is confident in the use of FirstSpirit and Spryker as well as CaaS and Omnichannel Manager.

1.1. Range of functions

FirstSpirit Connect enables editors to do the following:

  • Creating native shop content with FirstSpirit
  • Access to product and category information
  • Display shop elements and editorial content in the FirstSpirit preview simultaneously
  • Transfer of content into the Spryker Commerce OS

The corresponding functions are made available when the module is installed and configured in ContentCreator.

Familiar FirstSpirit tools are used to maintain the content, meaning that editors who are already familiar with FirstSpirit do not require any additional knowledge. The content is made available to Spryker as part of a deployment so that it can be imported. Spryker then integrates the information into the shop.

Consequently there is no difference for Spryker in the delivering of editorial contents to the live state. Even if the FirstSpirit server is shut down due to maintenance work, for example, this does not affect Spryker.

1.2. Architecture

The connection of FirstSpirit and Spryker is realized by an architecture made up of a range of components (see figure Architecture).

These components are:

  • The modules installed on the FirstSpirit server:

    • FirstSpirit Connect
    • Omnichannel Manager
    • Content as a Service
  • Spryker Instance
Architecture
Figure 1. Architecture


The individual components always interact according to the following schema:

  1. In FirstSpirit, the creation and editing of editorial content takes place in ContentCreator. With the help of the Omnichannel Manager, the storefront is embedded in it.
  2. The storefront in turn accesses the Preview CaaS and determines the current FirstSpirit content from it. It also integrates the JavaScript required for Omnichannel Manager, which enables the content in ContentCreator to be edited and highlighted.
  3. The transfer of the editorial content into the Preview CaaS takes place automatically with each save action.
  4. The filling of the Online CaaS with the released content is triggered by a deployment. The Online CaaS makes the content available to the importer, who transfers it to Spryker and persists it there.

Spryker thus represents the main component of this architecture. In addition to providing all shop functionality, it imports the content created or maintained in FirstSpirit from the Online CaaS and integrates it into the shop. There is only a loose link between FirstSpirit and Spryker. They primarily work in parallel with one another.

1.3. Concept

The FirstSpirit Connect module offers the possibility to maintain editorial contents in FirstSpirit and to transfer them afterwards via deployment to Spryker. For this, content processing in both systems must be coordinated and compatible with each other. The subchapters below describe the underlying concept used to archieve this compatibility.

1.3.1. Pages

Similar to FirstSpirit, pages in Spryker are based on a structure of different components. In order to exchange editorial content between the two systems, these components must be coordinated.

Within the reference project FirstSpirit Connect Reference Project included in the delivery, the CMS slots from Spryker are represented by the content areas of a page template in FirstSpirit. Sections corresponding to a CMS block can be added to them.

Page Rendering
Figure 2. Page Rendering


With FirstSpirit, CMS blocks can be generated that are displayed in a page via CMS slots.

1.3.2. Preview

The integration realized with the FirstSpirit Connect module only allows FirstSpirit to generate and maintain editorial content and to publish it in the form of CMS blocks. However, Spryker still determines the framework of a page whose CMS slots integrate the generated blocks.

To present the preview of a page, FirstSpirit determines its current view in the storefront. The storefront in turn queries the editorial content from the Preview CaaS and replaces the corresponding CMS blocks. FirstSpirit displays the result using the Omnichannel Managers in ContentCreator.

1.3.3. Deployment

The transmission of the content created in FirstSpirit into the live state is done by Spryker. For this, the content must be provided, which happens in form of the Online CaaS. From it Spryker imports the editorial content and persists it in its data system.

1.4. Technical requirements

To use the FirstSpirit Connect module, the following technical requirements must be met:

  • the modules FirstSpirit Connect, Content as a Service and Omnichannel Manager in their current versions
  • FirstSpirit (Legacy or Isolated Mode) in version 2020-08 or higher
  • Java 11
  • Spryker Commerce OS 202009.0 with the extensions Category CMS Blocks and Product CMS Blocks
  • php in version 7.3 or higher

When using the supplied reference project FirstSpirit Connect Reference Project, the current version of the BasicWorkflows module is also required.

1.5. Important information

This chapter contains information that should be observed when using the FirstSpirit Connect module.

1.5.1. Configuration of the glue web server

During deployment, the content maintained in FirstSpirit is retrieved from the Online CaaS using the importer. It transfers the data to Spryker and persists them in the backend in its data system.

Since the Online CaaS potentially contains a large amount of data, the transfer of the contents requires a certain time span. Therefore, early timeouts during the import should be avoided. Due to this reason the web server of the glue API needs to be configured to allow http requests for a duration of at least 60 seconds.

1.5.2. Configuration of the FirstSpirit project settings page

The CaaS generations assume that a template for the project settings is maintained in the FirstSpirit project. Otherwise, the generation job terminates early and reports the following error in the job logs:

Exception with missing project settings page. 

error during script execution : java.lang.IllegalStateException:
Invalid value for key 'usedCaasProjects' - Value is not a HashMap (zero).
This can happen when a deployment does not include a single PageRef (blue), which is not supported (e.g. remote-media-project).

For this reason, a template must exist in the project and be configured in the project options in ServerManager, even if it has no content.

Configuration of the project settings page in the project options
Figure 3. Configuration of the project settings page in the project options


1.5.3. Use of the Spryker B2C Demo Shop

As mentioned before, the entire documentation is geared to the connection of the Spryker B2C Demo Shop. When using it, some difficulties may occur that are neither caused by the FirstSpirit Connect module nor by the integration. However, they are listed below and a possible solution is outlined.

Preview page not found in ContentCreator

If the ContentCreator cannot find the preview page, the page certificate is invalid or does not exist. In this case, the page must be opened in a separate browser tab to renew the SSL certificate and allow the page to be displayed. The preview page is then visible again in ContentCreator.

Missing RAM on Composer calls

There is a RAM limit for PHP by default, but it is too low to execute Composer actions. For this reason, the limit defined in the php.ini configuration file in the etc/php/7.2/cli directory must be disabled:

Deactivation of the RAM limit. 

[...]
set memory_limit=-1
[...]

2. Spryker - Installation and configuration

FirstSpirit is used to create and maintain editorial data that is transferred to and persisted by the CaaS. To integrate the data, Spryker needs access to the CaaS. This is provided by the Spryker modules firstspirit-preview and firstspirit-caas, which require an installation and configuration in Spryker. The firstspirit-preview module enables the storefront to be displayed in ContentCreator. The contents are retrieved from the CaaS using the firstspirit-caas module.

The following chapters describe all steps required for installation and configuration as well as additional extensions in Spryker.

2.1. Spryker-Modules

Both the retrieval of the CaaS contents by Spryker and their display and editing in ContentCreator is done using various Spryker modules. These modules require an installation in Spryker and an extension of the configuration. They also require various JavaScript and CSS files to be included in Spryker.

The following chapters describe how to perform the necessary steps.

2.1.1. Installation of the Spryker modules

The maintenance of shop contents in ContentCreator requires the installation of several Spryker modules, which are included in the delivery in the form of zip files. They have to be stored in any directory below the Spryker project directory, which must be announced to Composer as another repository. This is done via the following command to be executed in the project directory, which extends the composer.json file of the Spryker server accordingly.

Extension of the composer.json file. 

composer config repo.espirit artifact ./PATH-TO-DIRECTORY

The Spryker modules to be installed use the namespace ESpirit, which must be announced to Spryker. This requires an extension of the KernelConstants in the environment-independent file config_default.php in the directory config/Shared:

Extension of the KernelConstants. 

$config[KernelConstants::CORE_NAMESPACES] = [
   'SprykerShop',
   'SprykerEco',
   'Spryker',
   'Generated',
   'ESpirit'
];

The Spryker modules are then installed using the following commands, which must also be executed in the Spryker project directory in the specified order.

Installation commands. 

composer require e-spirit/firstspirit-caas
composer require e-spirit/firstspirit-preview
composer require e-spirit/firstspirit-data-state-writer
composer require e-spirit/firstspirit-data-cleanup
composer require e-spirit/firstspirit-data-import
composer require e-spirit/firstspirit-data-inconsistency-check
composer require e-spirit/firstspirit-data-rest-api
composer require e-spirit/firstspirit-cms-data-connector
composer require e-spirit/firstspirit-cms-data-storage

The commands load the modules from the created repository and install them automatically.

The last step of the installation corresponds to the generation of the transfer objects of the Data Import module and the creation of the database schema contained in the CMS Block Data Connector module:

Generation of the transfer objects and creation of the database schema. 

vendor/bin/console transfer:generate
vendor/bin/console propel:install

2.1.2. Twig Templates

The FirstSpirit Connect module provides different ways to access shop content from Spryker and use it in FirstSpirit. These possibilities are described in the following of this documentation on the basis of the supplied reference project in the form of use cases.

If the sections and page templates contained in the reference project should be used, this requires different Twig templates in Spryker.

The sections correspond to different Spryker molecules, atoms and organisms, which are summarized in the folder FirstSpiritReferenceComponents. This is part of the delivery and is provided in the form of another Spryker module, which is to be installed using the following command:

Installation command. 

composer require e-spirit/firstspirit-reference-components

In order to make the components provided with the module usable in Spryker, the corresponding path must be specified in Spryker. This is done by adapting the files settings.js and tsconfig.json.

Within the settings.js file in the directory Spryker-directory/frontend an extension of the context is necessary:

Adaptation of the settings.js file. 

[...]

dirs: [
   join(globalSettings.context, paths.core),
   join(globalSettings.context, './vendor/e-spirit'),
   join(globalSettings.context, paths.eco),
   join(globalSettings.context, paths.project)
],

An additional include must be added to the tsconfig.json file in the Spryker directory:

Adaptation of the tsconfig.json file. 

[...]

"include": [
   "./vendor/spryker-shop/**/*",
   "./vendor/spryker-eco/**/*",
   "./src/Pyz/Yves/**/*",
   "./vendor/e-spirit/**/*"
],

The generic Twig template fs_molecule_block.twig controls the output of the supplied molecules. It is a part of the zip file b2c-demo-shop-extensions-<VERSION>.zip included in the delivery and must be stored under the path src/Pyz/Shared/CmsBlock/Theme/default/template in Spryker.

The integration of the Twig templates in Spryker takes place via the following command, which finally is to be executed in the Spryker project directory.

Integration of the Twig templates. 

npm run yves

The FirstSpirit templates allow the extension of existing static pages, product, and category pages and the creation of dynamic content pages or a magazine. Therefore, the reference project contains the page templates homepage, productpage, categorypage, contentpage, and magazine_detail_page. In addition, the following Twig templates are required in Spryker:

The Twig template home.twig, which can be found under the path src/Pyz/Yves/HomePage/Theme/default/views/home, needs some changes. These are explained in the description of the static pages. The same applies to the Twig templates pdp.twig, page-layout-catalog.twig and catalog-with-cms-slot.twig which are necessary to edit product and category pages.

They are available in Spryker under the following paths:

  • src/Pyz/Yves/ProductDetailPage/Theme/default/views/pdp
  • src/Pyz/Yves/CatalogPage/Theme/default/templates/page-layout-catalog
  • src/Pyz/Yves/CatalogPage/Theme/default/views/catalog-with-cms-slot

The remaining Twig templates are part of the zip file included in the delivery and have to be stored under the following paths:

  • Product pages: src/Pyz/Yves/CmsBlockWidget/Theme/default/components/molecules/product-cms-block
  • Dynamic Content Pages: src/Pyz/Shared/Cms/Theme/default/templates/fs-content-page

2.1.3. Slots import

In both Spryker and FirstSpirit, pages are based on a structure of different components. In Spryker, these include the CMS slots, which are represented in FirstSpirit by the content areas of a page template. The slots bind CMS blocks, each of which corresponds to a FirstSpirit section.

The Twig template home.twig represents a static page on the Spryker side and is mapped by the page template homepage in the provided reference project. It contains the content areas fs_slt_2 and fs_slt_3, for which the corresponding slots must exist in Spryker.

The slots are imported using the file cms_slot.csv, which is stored in Spryker in the directory /data/import/common/common. It must be replaced by the file of the same name from the delivery, which additionally contains the following two lines:

Import file cms_slot.csv. 

template_path,slot_key,content_provider,name,description,is_active
[...]
@HomePage/views/home/home.twig,fs-slt-2,FirstSpiritCmsSlotBlock,Banner,Banner content section for the homepage.,1
@HomePage/views/home/home.twig,fs-slt-3,FirstSpiritCmsSlotBlock,Homepage Content,Homepage main content section.,1

Afterwards, the new slots are taken over via the following command, which has to be executed in the Spryker project directory.

Import command. 

vendor/bin/console data:import cms-slot

2.1.4. Extension of the configuration

In FirstSpirit, the creation and editing of editorial content takes place in ContentCreator. The storefront is embedded in it using the Omnichannel Manager.

To enable the display of the shop contents from Spryker in ContentCreator, an extension of the environment-specific configuration is necessary. To do this, a token must be defined in the file config_default-[environment].php in the directory config/Shared as well as the host and port of the FirstSpirit start page. Furthermore, the operation of CaaS requires the specification of some parameters. These parameters are necessary both for production operation and for the use of the CaaS in the preview.

Extension of the configuration. 

// ----------- FirstSpirit Preview Configurations
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_AUTHENTICATION_INIT_TOKEN] = '<ADD TOKEN>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_WEB_HOST] = '<ADD FS PREVIEW HOST>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_CAAS_CONTENT_PAGE_COLLECTION] = '<CAAS COLLECTION>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_CAAS_CATEGORY_PAGE_COLLECTION] = '<CAAS COLLECTION>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_CAAS_PRODUCT_PAGE_COLLECTION] = '<CAAS COLLECTION>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_DISPLAY_BLOCK_RENDER_ERRORS] = true;

// ----------- FirstSpirit Data Import Configurations
$config[FirstSpiritDataImportConstants::FIRSTSPIRIT_DATA_IMPORT_BLOCK_DATA_CAAS_PATH] = '/_aggrs/blocks';
$config[FirstSpiritDataImportConstants::FIRSTSPIRIT_CAAS_REQUEST_PAGESIZE] = <VALUE>;

// ----------- FirstSpirit CaaS Configurations
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_HOSTNAME_PREVIEW] = '<ADD CAAS HOST>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_PORT_PREVIEW] = '<ADD CAAS PORT>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_SCHEME_PREVIEW] = '<ADD CAAS SCHEME>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_APIKEY_PREVIEW] = '<ADD APIKEY>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_DATABASE_PREVIEW] = '<ADD CAAS DATABASE>';

$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_HOSTNAME_ONLINE] = '<ADD CAAS HOST>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_PORT_ONLINE] = '<ADD CAAS PORT>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_SCHEME_ONLINE] = '<ADD CAAS SCHEME>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_APIKEY_ONLINE] = '<ADD APIKEY>';
$config[FirstSpiritCaaSConstants::FIRSTSPIRIT_CAAS_DATABASE_ONLINE] = '<ADD CAAS DATABASE>';

FirstSpirit Preview Configurations

The token is used for authentication and must be specified in the ContentCreator settings as a query parameter of the external preview URL during the configuration in FirstSpirit. It can be defined arbitrarily.

Specifying the fully qualified host of the FirstSpirit home page (e.g. http://localhost:8000) is a requirement of the HeadersSecurityExtensionPlugins to be installed. It uses the information to enable previewing in ContentCreator.

The mentions of the CaaS collections for content, category and product pages enable access to the editorial content stored in the Preview CaaS and its display in the ContentCreator.

The error parameter enables the display of error outputs in the page. Using the value true therefore only makes sense for Dev and QA instances.

FirstSpirit Data Import Configurations

The path is used to query and persist the block data stored in the Online CaaS. It is required by the FsDataImportConsole command, which triggers the importer in the context of a FirstSpirit deployment.

With the help of the pagesize the number of documents that the CaaS returns on a request can be defined. The parameter is optional and may have a value from 1 to 100. By default, the maximum value of 100 is defined for it.

FirstSpirit CaaS Configurations

The CaaS host, port, and scheme to use (http or https) allow Spryker to connect to the CaaS. Access to the data stored in it requires a valid API Key that needs read access to the corresponding project. The name of the project stored in CaaS must be specified in the configuration file as the value of the database parameter.

For more information on using the CaaS, see the Content as a Service Documentation.

To ensure that the used classes FirstSpiritPreviewConstants, FirstSpiritDataImportConstants and FirstSpiritCaaSConstants can be found, they have to be included in the configuration file via use statements:

Integration of the classes. 

use ESpirit\Shared\FirstSpiritPreview\FirstSpiritPreviewConstants;
use ESpirit\Shared\FirstSpiritDataImport\FirstSpiritDataImportConstants;
use ESpirit\Shared\FirstSpiritCaaS\FirstSpiritCaaSConstants;

2.1.5. Extension of the basic template

The Omnichannel Manager enables the display and editing of external content in ContentCreator, for which it requires some preview-specific data attributes. In Spryker, it also requires a preview-specific JavaScript file, which is included by the FirstSpiritPreview module.

The JavaScript file must be added to the Twig template, which is responsible for the basic layout of all shop pages. By default this is the page-blank.twig template, which is stored under the path src/Pyz/Yves/ShopUi/Theme/default/templates/page-blank. In the same template, the data attributes must also be determined by the Twig function fsIncludeDataAttributes.

The Twig template is adapted by calling the Twig functions fsIncludeDataAttributes and fsIncludeOcmScript and by extending the template data. The Twig function fsIncludeOcmScript can be passed the URL to a local copy of the JavaScript file as an optional parameter. By default, it retrieves the file from the CDN.

Adaptation of the Twig template. 

{% block template %}
   {% set isNewFrontendBuildSupported = true %}
   <body [...] {{ fsIncludeDataAttributes() }}>
   {{ parent() }}
{% endblock %}

{% block footerScripts %}
   {% include molecule('check-touch') only %}
   {{ fsIncludeOcmScript() }}
   {{ parent() }}
{% endblock %}

2.2. Plugins

In addition to the installation of the Spryker modules, the following plugins must be included:

  • HeadersSecurityExtensionPlugin
  • FsTwigExtensionPlugin
  • FirstSpiritPreviewSlotBlockWidgetCmsSlotContentPlugin
  • FirstSpiritDataImportsResourceRoutePlugin
  • FirstSpiritDataCleanupsResourceRoutePlugin
  • FirstSpiritCmsPagesResourceRoutePlugin
HeadersSecurityExtensionPlugin and FsTwigExtensionPlugin

The HeadersSecurityExtensionPlugin uses the hosts of the FirstSpirit home page defined in the configuration file config_default-[environment].php to enable the storefront to be displayed in ContentCreator. Therefore, it checks if storefront queries contain the Token also defined in the configuration file or if a logged in user exists. If one of the two options applies, the plugin sets the Content Security Policy Header and extends the Cookie header.

The FsTwigExtensionPlugin enables the maintenance of CMS placeholders and CMS blocks in FirstSpirit. Therefore, it accesses information provided by the CmsController to be installed. The information is needed for mapping between the data stored in FirstSpirit and in Spryker.

The integration of both plugins is done with the following code, which has to be added to the ShopApplicationDependencyProvider in the directory src/Pyz/Yves/ShopApplication.

Extension of the ShopApplicationDependencyProvider. 

use ESpirit\Yves\FirstSpiritPreview\Plugin\HeadersSecurityExtensionPlugin;
use ESpirit\Yves\FirstSpiritPreview\Plugin\FsTwigExtensionPlugin;

[...]

protected function getApplicationPlugins(): array
{
   return [
      new HeadersSecurityExtensionPlugin(),
      new FsTwigExtensionPlugin()
   ];
}

FirstSpiritPreviewSlotBlockWidgetCmsSlotContentPlugin

The FirstSpiritPreviewSlotBlockWidgetCmsSlotContentPlugin enables the output of all blocks contained in a slot. In contrast to the CmsSlotBlockWidget included in Spryker, which is limited to the output of the Spryker data, the plugin only considers the information from the CaaS. The inclusion of the plugin requires an extension of the ShopCmsSlotDependencyProvider in the src/Pyz/Yves/ShopCmsSlot directory.

Extension of the ShopCmsSlotDependencyProvider. 

<?php

namespace Pyz\Yves\ShopCmsSlot;

use ESpirit\Yves\FirstSpiritPreviewSlotBlockWidget\FirstSpiritPreviewSlotBlockWidgetConfig;
use ESpirit\Yves\FirstSpiritPreviewSlotBlockWidget\Plugin\FirstSpiritPreviewSlotBlockWidget\
   FirstSpiritPreviewSlotBlockWidgetCmsSlotContentPlugin;
[...]

class ShopCmsSlotDependencyProvider extends SprykerShopShopCmsSlotDependencyProvider
{
   protected function getCmsSlotContentPlugins(): array
   {
      return [
         CmsSlotBlockConfig::CMS_SLOT_CONTENT_PROVIDER_TYPE
            => new CmsSlotBlockWidgetCmsSlotContentPlugin(),
         FirstSpiritPreviewSlotBlockWidgetConfig::FS_CMS_SLOT_CONTENT_PROVIDER_TYPE
            => new FirstSpiritPreviewSlotBlockWidgetCmsSlotContentPlugin(),
      ];
   }
}

FirstSpiritDataImportsResourceRoutePlugin and FirstSpiritDataCleanupsResourceRoutePlugin

The FirstSpiritDataImportsResourceRoutePlugin and FirstSpiritDataCleanupsResourceRoutePlugin each provide an API endpoint. This endpoint allows the FirstSpirit deployment to address the importer.

The FirstSpiritDataImportsResourceRoutePlugin controls the transfer of editorial content from the Online CaaS to Spryker and its persistence there. In contrast, the FirstSpiritDataCleanupsResourceRoutePlugin is used to find and delete obsolete data in Spryker.

Both plugins and the following FirstSpiritCmsPagesResourceRoutePlugin must be added to the GlueApplicationDependencyProvider.

FirstSpiritCmsPagesResourceRoutePlugin

If a new page is created within the ContentCreator, the creation of a CMS page in Spryker is required in parallel. Because the ContentCreator displays the storefront, the newly created page would otherwise not be visible in the preview. Instead, it would already be available in the live state if it were created in Spryker with a deployment.

The FirstSpiritCmsPagesResourceRoutePlugin is used to create the new page. This plugin and the other two ResourceRoutePlugins described above must be added to the GlueApplicationDependencyProvider in the src/Pyz/Glue/GlueApplication directory:

Extension of the GlueApplicationDependencyProviders. 

use ESpirit\Glue\FirstSpiritDataRestApi\Plugin\FirstSpiritDataImportsResourceRoutePlugin;
use ESpirit\Glue\FirstSpiritDataRestApi\Plugin\FirstSpiritDataCleanupsResourceRoutePlugin;
use ESpirit\Glue\FirstSpiritDataRestApi\Plugin\FirstSpiritCmsPagesResourceRoutePlugin;

[...]

protected function getResourceRoutePlugins(): array
{
   return [
      new FirstSpiritDataImportsResourceRoutePlugin(),
      new FirstSpiritDataCleanupsResourceRoutePlugin(),
      new FirstSpiritCmsPagesResourceRoutePlugin()
      [...]
   ];
}

2.3. Widgets

In addition to the Spryker modules and the plugins the delivery contains the following widgets. They enable the expandability of the navigations contained in the shop, as well as the usage of the DOM references and the Shoppable Image contained in the reference project. Only if these elements are used a registration of the widgets is required.

  • FirstSpiritPreviewContentNavigationWidget
  • FirstSpiritCategoryLinkWidget
  • FirstSpiritProductLinkWidget
  • FirstSpiritContentLinkWidget
  • FirstSpiritExternalLinkWidget
  • FirstSpiritProductFlyoutWidget

FirstSpiritPreviewContentNavigationWidget
The FirstSpiritPreviewContentNavigationWidget creates the possibility to maintain the navigations contained in the store with FirstSpirit and to add further menu items. It replaces the existing ContentNavigationWidget in Spryker and provides various attributes required for displaying the corresponding navigation in the preview. Therefore the existing ContentNavigationWidget, which is stored under the path /src/Pyz/Yves in Spryker, has to be replaced by the FirstSpiritPreviewContentNavigationWidget included in the delivery. Finally, the use of the FirstSpiritPreviewContentNavigationWidget requires a registration. This is done by modifying the TwigDependencyProvider in the directory /src/Pyz/Yves/Twig/, in which the ContentNavigationTwigPlugin has to be replaced by the FirstSpiritPreviewNavigationWidgetTwigPlugin.

Adaptation of the TwigDependencyProviders. 

<?php

namespace Pyz\Yves\Twig;

use ESpirit\Yves\FirstSpiritPreviewNavigationWidget\Plugin\Twig\FirstSpiritPreviewNavigationWidgetTwigPlugin;
[...]

class TwigDependencyProvider extends SprykerTwigDependencyProvider
{
   [...]

   protected function getTwigPlugins(): array
   {
      return [
         [...]
         new FirstSpiritPreviewNavigationWidgetTwigPlugin(),
      ];
   }

   [...]
}

FirstSpiritCategoryLinkWidget und FirstSpiritProductLinkWidget
The FirstSpiritCategoryLinkWidget and the FirstSpiritProductLinkWidget are used to display editorial DOM links to category or product detail pages. In both cases, the widget determines the corresponding category or product using a unique identifier and passes the result to the Twig template that controls the display of the respective link in Spryker. Each of the two widgets references its corresponding Twig template. The Twig templates are provided by the previously installed FirstSpiritPreview module.

FirstSpiritContentLinkWidget und FirstSpiritExternalLinkWidget
The FirstSpiritContentLinkWidget and the FirstSpiritExternalLinkWidget enable DOM links to editorial content, whereby the type of content differs in each case. The FirstSpiritExternalLinkWidget only allows the referencing of external content. In contrast, the FirstSpiritContentLinkWidget is used to display internal DOM links to dynamic content pages or magazine articles maintained within the FirstSpirit project. An important aspect is that the target URL of the internal links to dynamic content pages depends on the output: While the link in the live state refers to the published CMS page, the corresponding preview URL must be used in the preview. In both cases, the widget controls the determination of the required URL.

FirstSpiritProductFlyoutWidgets
The registration of the FirstSpiritProductFlyoutWidget is only required if the Shoppable Image provided with the delivery is used in the project. The widget controls the display of flyouts for the products linked to the Shoppable Image.

Registration
The four link widgets and the flyout widget are registered using the following code, which must be added to the ShopApplicationDependencyProvider in the folder src/Pyz/Yves/ShopApplication.

Extension of the ShopApplicationDependencyProvider. 

use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritCategoryLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritProductLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritContentLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritExternalLinkWidget;
use ESpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritProductFlyoutWidget;

[...]

protected function getGlobalWidgets(): array
{
   return [
      [...]
      FirstSpiritCategoryLinkWidget::class,
      FirstSpiritProductLinkWidget::class,
      FirstSpiritContentLinkWidget::class,
      FirstSpiritExternalLinkWidget::class,
      FirstSpiritProductFlyoutWidget::class
   ];
}

2.4. Controllers

The previously installed CmsBlockTwigFunctionPlugin allows mapping between the content stored in FirstSpirit and in Spryker. For this, it assumes that the view data of a page contains its ID and type. The controllers of Spryker do not provide this information by default. For this reason, the following controllers must be overwritten both for content and category pages and in the case of the homepage, which corresponds to a static page:

  • IndexController
  • CatalogController
  • CmsController
  • PreviewController

The overwriting is done by creating the corresponding classes, which are all part of the zip file b2c-demo-shop-extensions-<VERSION>.zip included in the delivery. They must be copied into the directory Controller to be created below src/Pyz/Yves/HomePage|CatalogPage|CmsPage.

If the classes already exist under the path specified for them, the controllers are already overwritten project-specifically. In this case, it need to be ensured that the view parameters are extended accordingly.

In contrast to the other pages, the product pages require the adaptation of the ProductController which already exists in Spryker. It is contained in the directory src/Pyz/Yves/ProductDetailPage/Controller/ProductController and must be extended by the definition of the page type and the Product SKU. The following code snippet shows the changes to be made:

Extension of the ProductController. 

<?php
namespace Pyz\Yves\ProductDetailPage\Controller;

[...]
use ESpirit\Shared\FirstSpiritPreview\FirstSpiritPreviewConstants;

class ProductController extends SprykerShopProductController
{
   protected function executeDetailAction(array $productData, Request $request): array
   {
      [...]

       $viewData['cart'] = $quoteTransfer;
       $viewData[FirstSpiritPreviewConstants::VIEW_DATA_PAGE_TYPE_KEY] = FirstSpiritPreviewConstants::PRODUCT_PAGE_TYPE;
       $viewData[FirstSpiritPreviewConstants::VIEW_DATA_PAGE_ID_KEY] = $productData['sku'];

       return $viewData;
   }
}

In addition to the controllers mentioned above, the delivery includes further render controllers which enable individual CMS elements to be updated in the preview. They are addressed by the FirstSpiritPreviewRoutePlugin which initially does not exist in Spryker and therefore requires registration in the RouterDependencyProvider file in the Pyz/Yves/Router directory. Within the file, the method getRouteProvider has to be extended as follows.

Extension of the method getRouteProvider. 

use ESpirit\Yves\FirstSpiritPreview\Plugin\Route\FirstSpiritPreviewRoutePlugin;

[...]
protected function getRouteProvider(): array
{
   return [
      [...]
      new FirstSpiritPreviewRoutePlugin()
   ];
}

2.5. Main navigation

By default, the Spryker B2C Demo Shop contains different navigations, which can be created and edited in Spryker. The integration realised with the FirstSpirit Connect module offers the possibility to maintain these navigations with FirstSpirit and to add further menu items.

Within the reference project the functionality is implemented exemplarily for the main navigation. Its usage requires the already described referencing of the FirstSpiritPreviewContentNavigationWidgets, the creation of a placeholder, and the addition of a preview ID.

The placeholder to be created corresponds to another menu item. This is required to display the navigation in the preview and must be added to the navigation-header.twig file in the src/Pyz/Yves/ShopUi/Theme/default/components/molecules/navigation-header directory:

Adjustment of the navigation-header.twig file. 

[..]
<ul class="menu {{ menuClass }} grid grid--center grid--no-wrap">
   {% for node in data.nodes %}
      [..]
   {% endfor %}

   {% if isFsPreview() %}
      <li class="fs-navigation-extension"
         style="padding-left: 1rem; transform: translate(0,15% );">
      </li>
   {% endif %}
</ul>
[..]

In addition, a preview ID is required to display the main navigation in the preview. This preview ID is to be defined in the navigation-multilevel-node.twig file in the directory src/Pyz/Yves/ShopUi/Theme/default/components/molecules/navigation-multilevel-node:

Adjustment of the navigation-multilevel-node.twig file. 

{% block attributes %}
   {% if isFsPreview() and data.node.previewId is defined and data.node.previewId is not empty %}
      data-preview-id="{{ data.node.previewId }}" style="min-height: unset;"
   {% endif %}
{% endblock %}

After the changes have been made, it may be necessary to empty the cache for the twig templates and to rebuild the frontend.

2.6. Query Container

The previously installed <sp_install_module,Cms Block Data Connector module>> creates a Zed table. During the import, the editorial contents determined from the Online CaaS are stored in this table. The CMS blocks are persisted in another table.

Since the CMS blocks do not contain placeholders, they are not published by Spryker by default. For this reason, it is necessary to overwrite the CmsBlockStorageQueryContainer and thus adapt the standard behavior of Spryker for publishing CMS blocks. The query container is overwritten by creating the class CmsBlockStorageQueryContainer.php. It is part of the zip file b2c-demo-shop-extensions-<VERSION>.zip included in the delivery and must be copied into the directory src/Pyz/Zed/CmsBlockStorage/Persistence to be created.

2.7. Technical user

The integration realized with the FirstSpirit Connect module only allows FirstSpirit to create and maintain editorial content and to publish it in the form of JSON objects. The integration of these contents and the creation of the preview, however, still takes place in Spryker.

In the preview case, FirstSpirit determines the current view of a page in the storefront and displays it in ContentCreator using the Omnichannel Manager. To integrate the editorial content into the shop, Spryker imports it from the Online CaaS and persists it in its internal data system.

As both the preview and the import process are protected by authentication, a technical user must be specified in the project component of the FirstSpirit Connect module. This corresponds to a customer, who in turn is assigned to a Zed user. The assignment can be done in the menu Users ControlUser via the button Assign Customers.

For a more detailed description of the steps required for the assignment, see the chapters Assigning Customers and Previewing a Page of the Spryker documentation.

2.8. Import command

The integration of the contents created or maintained in FirstSpirit into the Shop takes place through Spryker. Therefore, Spryker imports the data from the Online CaaS and persists them in its data system. The transfer of the information must take place with each FirstSpirit deployment, which for this reason each time triggers a Spryker sided import command.

The command instructs the importer to import the block data stored in the Online CaaS. To do this, it uses the FirstSpirit Data Import Block CaaS Path stored in the configuration file config_default-[environment].php. Using this path, the importer accesses the CaaS aggregation that is created by the FirstSpirit deployment.

The import command must be registered in Spryker in the getConsoleCommands. This requires the following extension to the ConsoleDependencyProvider.php file in the src/Pyz/Zed/Console directory:

Extension of the getConsoleCommands. 

use ESpirit\Zed\FirstSpiritDataImport\Communication\Console\FsDataImportConsole;

[...]

$commands = [
   // Default commands
   [...]

   // FirstSpirit Data importers
   new FsDataImportConsole(FsDataImportConsole::DEFAULT_NAME)
];

2.9. Synchronization

During deployment, the content maintained in FirstSpirit is retrieved from the Online CaaS using the importer. It transfers the data to Spryker and persists them in the backend in its data system. The display of the data in the live state additionally requires its transmission to Yves. The transmission of the data requires the registration of an event subscriber, several queues and a message processor.

See the Publish and Synchronization chapter of the Spryker documentation for more information.

The registration of the EventSubscriber is done with the following code to be added to the EventDependencyProvider in the directory Pyz/Zed/Event.

EventDependencyProvider. 

use ESpirit\Zed\FirstSpiritCmsDataStorage\Communication\Plugin\Event\Subscriber\FirstSpiritCmsDataStorageEventSubscriber;

[...]

class EventDependencyProvider extends SprykerEventDependencyProvider
{
   [...]

   public function getEventSubscriberCollection()
   {
      $eventSubscriberCollection = parent::getEventSubscriberCollection();

      /**
      * Storage Events
      */
      [...]
      $eventSubscriberCollection->add(new FirstSpiritCmsDataStorageEventSubscriber());

      /**
      * Search Events
      */
      [...]

      return $eventSubscriberCollection;
   }
}

Registration of the queues requires the following adaption of the RabbitMqConfig file in the Pyz/Client/RabbitMq directory:

RabbitMqConfig. 

<?php
namespace Pyz\Client\RabbitMq;

use ESpirit\Shared\FirstSpiritCmsDataStorage\FirstSpiritCmsDataStorageConfig;
[...]

class RabbitMqConfig extends SprykerRabbitMqConfig
{
   [...]

   protected function getPublishQueueConfiguration(): array
   {
      return [
         PublisherConfig::PUBLISH_QUEUE => [
            [...]
         ],
         GlossaryStorageConfig::PUBLISH_TRANSLATION,
         FirstSpiritCmsDataStorageConfig::PUBLISH_FS_CMS_BLOCK_DATA_CONNECTOR,
         FirstSpiritCmsDataStorageConfig::PUBLISH_FS_CMS_PAGE_DATA_CONNECTOR,
      ];
   }

   protected function getSynchronizationQueueConfiguration(): array
   {
      return [
         [...]
         FirstSpiritCmsDataStorageConfig::SYNC_FS_CMS_BLOCK_DATA,
         FirstSpiritCmsDataStorageConfig::SYNC_FS_CMS_PAGE_DATA
      ];
   }

   [...]
}

The registration of the event subscriber necessary for the queues requires an adjustment of the QueueDependencyProvider in the directory Pyz/Zed/Queue:

QueueDependencyProvider. 

<?php
namespace Pyz\Zed\Queue;

use ESpirit\Shared\FirstSpiritCmsDataStorage\FirstSpiritCmsDataStorageConfig;
[...]

class QueueDependencyProvider extends SprykerDependencyProvider
{
   protected function getProcessorMessagePlugins(Container $container)
   {
      return [
         [...]
         FirstSpiritCmsDataStorageConfig::PUBLISH_FS_CMS_BLOCK_DATA_CONNECTOR => new EventQueueMessageProcessorPlugin(),
         FirstSpiritCmsDataStorageConfig::PUBLISH_FS_CMS_PAGE_DATA_CONNECTOR => new EventQueueMessageProcessorPlugin(),
         FirstSpiritCmsDataStorageConfig::SYNC_FS_CMS_BLOCK_DATA => new SynchronizationStorageQueueMessageProcessorPlugin(),
         FirstSpiritCmsDataStorageConfig::SYNC_FS_CMS_PAGE_DATA => new SynchronizationStorageQueueMessageProcessorPlugin(),
      ];
   }
}

3. FirstSpirit - Installation and Configuration

Various components must be installed and configured in order to use the functions of the FirstSpirit Connect module. The following subchapters explain the steps required.

3.1. Configuration of the project component

A project-specific configuration is necessary for the use of the FirstSpirit Connect module. This is done via the project component, which is already added to the supplied reference project.

To use the FirstSpirit Connect module, the Content as a Service module must also be configured. The necessary steps are described in the Content as a Service Documentation.

For the media usage, the generation of media into the CaaS has been defined in the CaaS project component. This configuration is explicitly not to be used in productive operation. For productive operation, the media usage must be converted to the use of a CDN.

To configure the project component, open the ServerManager and select Project propertiesProject components.

Server properties - Project components
Figure 4. Server properties - Project components


The main panel displays a list of all existing project components. Select FirstSpirit Connect for FirstSpirit Commerce OS Project Configuration and open the corresponding configuration dialog via Configure.

The dialog is divided into the tabs General, Preview, Publication, and YouTube:

General

Within the tab General, the Storefront Base URL and the Glue-API Base URL have to be specified. They have to be assigned to the FirstSpirit server to connect to Spryker and retrieve data.

Project component - General
Figure 5. Project component - General


Preview

Within the Preview tab, the login path is required first. The corresponding field contains the default value /firstspirit_login_check, which can be adjusted if necessary.

Furthermore, the login data of a technical user must be entered in this tab. This must correspond to the Customer defined during the steps to be performed on the Spryker side. In Spryker, it is used to query the storefront, which is included in the ContentCreator using the Omnichannel Manager.

Project component - Preview
Figure 6. Project component - Preview


Publication

The Publication tab contains a list of all groups and full deployment schedules available in the project. It allows the selected deployment schedule to be provided in the Actions menu in the ContentCreators for the groups selected in the tab. The Actions menu contains the Publication menu item for executing the schedule. For groups that are not allowed to execute the schedule, the entry is visible but disabled.

Within the supplied reference project, the ChiefEditors can be enabled to execute the full deployment in this way, for example.

Furthermore, the release and the delete workflow use the selected schedule if the publication of the entire project should be triggered additionally to the release or deletion of a page.

Server and project administrators are allowed to execute the full deployment by default, regardless of the configuration within the tab.

Project component - Publication
Figure 7. Project component - Publication


YouTube

The reference project provided contains a Shoppable video paragraph. It allows to display and reference products at defined times in a YouTube video. The usage of the paragraph requires a Google API Key, which has to be entered here.

In addition, one or more Channel Ids can be specified, separated by commas. As soon as the field contains an Id, the video selection will show a dropdown. This allows to reference a YouTube video from a specific channel.

Projekt-Komponente - YouTube
Figure 8. Projekt-Komponente - YouTube


3.2. Adding the web component

To prepare the ContentCreator, a web component is needed, which is already added to the reference project. By default it is installed globally in the ServerManager in the area Server PropertiesWeb applications. In this case, all installation or configuration steps required for the web component have already been performed by the e-Spirit AG.

Alternatively, you may install the web component in the Project properties. Only in this case it still needs to be installed on an active web server. Therefore, open the ServerManager and select Project propertiesWeb components.

Within the main panel there are several tabs, each with a list of existing web components. This list contains the FirstSpirit Connect for Spryker Commerce OS Web App for the Preview and ContentCreator. The ContentCreator tab also contains the FirstSpirit ThirdPartyPreview WebApp and optionally the BasicWorkflows_ContentCreator_Library (see figure Web components in the project properties). The web component of the BasicWorkflows is only required when using the workflows.

In both tabs, select a web server via the selection box and start the installation with the Install button. After the successful installation, a dialog opens, in which the activation of the web server is to be confirmed.

For detailed information about adding web components, see the FirstSpirit Documentation for Administrators.