ContentConnect

For Spryker Commerce OS

e-Spirit AG

2020-08-11
Table of Contents

1. Introduction

FirstSpirit is used to create versatile and project-specific content. Thanks to the ContentConnect 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 201907.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 ContentConnect For Spryker Commerce OS module is the reference project ContentConnect 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

ContentConnect 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:

    • ContentConnect
    • 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. If the FirstSpirit server is shut down due to maintenance work, for example, this does not affect Spryker.

1.3. Concept

The ContentConnect 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 ContentConnect Reference Project included in the delivery, the CMS placeholders 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 Placeholder.

1.3.2. Preview

The integration realized with the ContentConnect 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 placeholders 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 ContentConnect module, the following technical requirements must be met:

  • the modules ContentConnect, Content as a Service and Omnichannel Manager in their current versions
  • FirstSpirit (Legacy or Isolated Mode) in version 2019-05 or higher
  • Java 8 or 11
  • Spryker Commerce OS

When using the supplied reference project ContentConnect 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 ContentConnect 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 ContentConnect module nor by the integration. However, they are listed below and a possible solution is outlined.

Vagrant does not find VirtualBox

If it is not possible for Vagrant to find VirtualBox, the vagrant up command must be extended as follows:

Extension of the command vagrant up. 

vagrant up --provider=virtualbox

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 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 FirstSpirit, 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',
   'FirstSpirit'
];

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 firstspirit/firstspirit-caas
composer require firstspirit/firstspirit-preview
composer require firstspirit/firstspirit-data-state-writer
composer require firstspirit/firstspirit-data-cleanup
composer require firstspirit/firstspirit-data-import
composer require firstspirit/firstspirit-data-inconsistency-check
composer require firstspirit/firstspirit-data-rest-api
composer require firstspirit/firstspirit-cms-data-connector
composer require firstspirit/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 ContentConnect 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 firstspirit/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/firstspirit'),
   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/firstspirit/**/*"
],

To use the Twig template fs-carousel, which is contained in the module, a swipe effect must be enabled. The activation is done with the following command:

Activating the Swipe effect. 

npm install swiper

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 and category pages and the creation of dynamic content pages or a magazine. The page templates homepage, categorypage, contentpage, and magazine_detail_page contained in the reference project represent the Twig templates home.twig, catalog-with-cms-block.twig and fs-content-page.twig.

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 remaining Twig templates are part of the zip file included in the delivery and have to be stored under the following paths:

  • Category pages: src/Pyz/Yves/CmsBlockWidget/Theme/default/views/catalog-with-cms-block
  • Dynamic Content Pages: src/Pyz/Shared/Cms/Theme/default/templates/fs-content-page

2.1.3. 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_TECHNICAL_PAGE_COLLECTION] = '<CAAS COLLECTION>';
$config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_CAAS_NAVIGATION_DOCUMENT] = '<NAVIGATION DOCUMENT>';
$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 and category pages enables access to the editorial content stored in the Preview CaaS and its display in the ContentCreator.

The configuration of the CaaS collection for technical pages as well as the document for navigations are necessary for the maintenance and extension of the navigations contained in the shop with FirstSpirit. Since both parameters have a default value (technical or navigations), their configuration is optional and only necessary if there are differences.

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, whose value is limited by the CaaS to a maximum of '1000' documents, is optional and has the value '100' by default.

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 requires 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 FirstSpirit\Shared\FirstSpiritPreview\FirstSpiritPreviewConstants;
use FirstSpirit\Shared\FirstSpiritDataImport\FirstSpiritDataImportConstants;
use FirstSpirit\Shared\FirstSpiritCaaS\FirstSpiritCaaSConstants;

2.1.4. 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 the preview-specific JavaScript files ocm-content-editing.bundle.js and fs-preview-user-authentification.js as well as the CSS files fs-preview-ocm.css and fs-preview-user-authentication.css. The files are part of the zip file b2c-demo-shop-extensions-<VERSION>.zip included in the delivery and must be copied into the directory js or css below public/Yves/assets/STORE/default.

Both the JavaScript and the CSS files must then 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 fsIncludeOcmFiles and by extending the template data. The Twig function fsIncludeOcmFiles expects an identifier for the integration of the JavaScript or CSS files.

Adaptation of the Twig template. 

{% block headStyles %}
   <link rel="stylesheet" href="{{publicPath('css/yves_default.app.css')}}" />
   {{ fsIncludeOcmFiles(identifier='css') }}
{% endblock %}

<body [..] {{ fsIncludeDataAttributes() }}>

   [..]

   {% block footerScripts %}
      <script src="{{publicPath('js/yves_default.es6-polyfill.js')}}"></script>
      <script src="{{publicPath('js/yves_default.vendor.js')}}"></script>
      <script src="{{publicPath('js/yves_default.app.js')}}"></script>
      {{ fsIncludeOcmFiles(identifier='js') }}
   {% endblock %}

</body>

2.2. Plugins

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

  • HeadersSecurityExtensionPlugin
  • FsTwigExtensionPlugin
  • FirstSpiritDataImportsResourceRoutePlugin
  • FirstSpiritDataCleanupsResourceRoutePlugin
  • FirstSpiritCmsPagesResourceRoutePlugin
  • UserAndCustomerOauthScopeProviderPlugin
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. Therfore, 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 FirstSpirit\Yves\FirstSpiritPreview\Plugin\HeadersSecurityExtensionPlugin;
use FirstSpirit\Yves\FirstSpiritPreview\Plugin\FsTwigExtensionPlugin;

[...]

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

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 FirstSpirit\Glue\FirstSpiritDataRestApi\Plugin\FirstSpiritDataImportsResourceRoutePlugin;
use FirstSpirit\Glue\FirstSpiritDataRestApi\Plugin\FirstSpiritDataCleanupsResourceRoutePlugin;
use FirstSpirit\Glue\FirstSpiritDataRestApi\Plugin\FirstSpiritCmsPagesResourceRoutePlugin;

[...]

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

UserAndCustomerOauthScopeProviderPlugin

During FirstSpirit generation, on Spryker side, an authentication is performed with the customer, which must be specified in the project component during the configuration in FirstSpirit. The UserAndCustomerOauthScopeProviderPlugin checks whether this customer is assigned to a Zed user. If this is the case, the plugin adds the zed-user permission required for the import to the authentication token returned by Spryker.

The plugin requires a registration within the OauthDependencyProvider in the directory src/Pyz/Zed/Oauth. Therefore, the CustomerOauthScopeProviderPlugin has to be replaced within the method getScopeProviderPlugins as follows:

Registration of the UserAndCustomerOauthScopeProviderPlugin. 

use FirstSpirit\Zed\FirstSpiritDataImport\Communication\Plugin\Oauth\UserAndCustomerOauthScopeProviderPlugin;

[...]

protected function getScopeProviderPlugins(): array
{
   return [
      new UserAndCustomerOauthScopeProviderPlugin()
   ];
}

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.

  • FirstSpiritCategoryLinkWidget
  • FirstSpiritProductLinkWidget
  • FirstSpiritContentLinkWidget
  • FirstSpiritExternalLinkWidget
  • FirstSpiritProductFlyoutWidget
  • ExtendedNavigationWidget

The first two widgets 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.

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.

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.

The ExtendedNavigationWidget creates the possibility to maintain the navigations contained in the shop in FirstSpirit and to add further menu items. It extends the existing NavigationWidget in Spryker and provides various attributes that are required for the navigation to be displayed in the preview.

The widgets 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 FirstSpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritCategoryLinkWidget;
use FirstSpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritProductLinkWidget;
use FirstSpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritContentLinkWidget;
use FirstSpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritExternalLinkWidget;
use FirstSpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritProductFlyoutWidget;
use Pyz\Yves\NavigationWidget\Widget\ExtendedNavigationWidget;

[...]

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 addition to the mentioned controllers, the delivery contains the CmsBlockRenderController, which allows the update of a single CMS block in the preview. It does not exist initially in Spryker and therefore requires a registration in the YvesBootstrap file in the directory Pyz/Yves/ShopApplication. Within the file, the method getControllerProviderStack has to be extended as follows.

Extension of the method getControllerProviderStack. 

use FirstSpirit\Yves\FirstSpiritPreview\Plugin\Provider\FirstSpiritPreviewControllerProvider;

[...]
protected function getControllerProviderStack($isSsl)
{
   return [
      [...]
      new FirstSpiritPreviewControllerProvider($isSsl)
   ];
}

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 ContentConnect 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 in both the desktop and the mobile version. Its usage requires the referencing of the ExtendedNavigationWidget, the creation of a placeholder, and the addition of a preview ID.

The ExtendedNavigationWidget extends the existing NavigationWidget and provides various attributes for the preview of the navigation. Therefore it must be referenced instead of the NavigationWidget. For the desktop version this requires the adjustment of the header.twig file in the directory src/Pyz/Yves/ShopUi/Theme/default/components/organisms/header:

Adjustment of the header.twig file. 

[..]
   {% widget 'ExtendedNavigationWidget' args ['MAIN_NAVIGATION_DESKTOP', 'navigation-header'] %}
   {% endwidget %}
[..]

The referencing of the ExtendedNavigationWidget for the mobile main navigation is done in the side-drawer.twig file in the directory src/Pyz/Yves/ShopUi/Theme/default/components/organisms/side-drawer:

Adjustment of the side-drawer.twig file. 

[..]
   {% widget 'ExtendedNavigationWidget' args ['MAIN_NAVIGATION', 'navigation-header-mobile'] %}
   {% endwidget %}
[..]

In the preview, the main navigation requires another menu item, which serves as a placeholder. For the desktop version, this must be added to the navigation-header.twig file in the directory src/Pyz/Yves/ShopUi/Theme/default/components/molecules/navigation-header:

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

The addition of the placeholder in the mobile main navigation is done by changing the navigation-header-mobile.twig file in the directory src/Pyz/Yves/NavigationWidget/Theme/default/components/molecules/navigation-header-mobile:

Adjustment of the navigation-header-mobile.twig file. 

[...]
{% block body %}
   [...]
   {% include molecule('toggler-accordion') with {
      attributes: {
         trigger: '.js-navigation-multilevel-node__trigger',
         'class-to-toggle': 'navigation-multilevel-node__menu--hidden',
         activeClass: 'navigation-multilevel-node__icon--active'
      }
   } only %}
   {% if isFsPreview() %}
      <li class="fs-navigation-extension"></li>
   {% endif %}
{% endblock %}
[...]

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: Since both versions of the main navigation access this file, only one adjustment is necessary in this step:

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

If a page contains illegal code Spryker shows a so-called fail whale. This is a default error page provided by Spryker. Since this page does not include any navigation options, it puts the user in a state from which he can no longer access another shop page.

Therefore, the delivery contains an error page that matches the design of the other shop pages and includes both a header and a footer. To use it, the content of the folder ErrorPage must be copied into the existing directory src/Pyz/Yves/ErrorPage. The folder is a part of the supplied zip file b2c-demo-shop-extensions-<VERSION>.zip.

Furthermore the following line has to be added to the page error.html in the directory src/public/Yves/errorpage:

Enhancement of the error.html. 

<meta http-equiv="Refresh" content="0; url=/error/500" />

2.7. 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.8. Technical user

The integration realized with the ContentConnect 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 ContentConnect 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.9. 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 FirstSpirit\Zed\FirstSpiritDataImport\Communication\Console\FsDataImportConsole;

[...]

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

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

2.10. Frontend entry point

The FirstSpirit ContentCreator only generates and updates complete pages by default. In order to enable the updating of single sections within the preview, an additional EventListener is required on the Spryker side. This must be added to the frontend entry point. Therefore, the app.ts file in the directory src/Pyz/Yves/ShopUi/Theme/default has to be extended as follows:

Extension of the file app.ts. 

import { bootstrap, mount } from 'ShopUi/app';
bootstrap();
document.addEventListener('NewComponentAttached', () => mount());

If the app.ts file does not exist under the specified path, it must be created with the described content.

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

Extension of the EventDependencyProvider. 

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

[...]

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

      [...]
      $eventSubscriberCollection->add(new FirstSpiritCmsDataStorageEventSubscriber());
      [...]

      return $eventSubscriberCollection;
   }
}

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

Extension of the RabbitMqConfig file. 

use FirstSpirit\Shared\FirstSpiritCmsDataStorage\FirstSpiritCmsDataStorageConstants;

[...]

class RabbitMqConfig extends SprykerRabbitMqConfig
{
   protected function getQueueOptions()
   {
      $queueOptionCollection = new ArrayObject();

      [...]

      $queueOptionCollection->append($this->createQueueOption(
         FirstSpiritCmsDataStorageConstants::FS_CMS_BLOCK_DATA_SYNC_STORAGE_QUEUE,
         FirstSpiritCmsDataStorageConstants::FS_CMS_BLOCK_DATA_SYNC_STORAGE_ERROR_QUEUE,
         FirstSpiritCmsDataStorageConstants::FS_CMS_PAGE_DATA_SYNC_STORAGE_QUEUE,
         FirstSpiritCmsDataStorageConstants::FS_CMS_PAGE_DATA_SYNC_STORAGE_ERROR_QUEUE));

      [...]

      return $queueOptionCollection;
   }
}

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

Extension of the QueueDependencyProvider. 

use FirstSpirit\Shared\FirstSpiritCmsDataStorage\FirstSpiritCmsDataStorageConstants;

[...]

protected function getProcessorMessagePlugins(Container $container)
{
   return [
      [...]
      FirstSpiritCmsDataStorageConstants::FS_CMS_BLOCK_DATA_SYNC_STORAGE_QUEUE =>
         new SynchronizationStorageQueueMessageProcessorPlugin(),
      FirstSpiritCmsDataStorageConstants::FS_CMS_PAGE_DATA_SYNC_STORAGE_QUEUE =>
         new SynchronizationStorageQueueMessageProcessorPlugin(),
      [...]
   ];
}

3. FirstSpirit - Installation and Configuration

Various components must be installed and configured in order to use the functions of the ContentConnect 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 ContentConnect module. This is done via the project component, which is already added to the supplied reference project.

To use the ContentConnect module, the Content as a Service and Omnichannel Manager modules must also be configured. The necessary steps are described in the Content as a Service Documentation or in the Documentation for the Omnichannel Manager.

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 ContentConnect 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 /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. However, this must still 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 component. This list contains the ContentConnect For Spryker Commerce OS Web App for the Preview and ContentCreator. The ContentCreator tab also contains the FirstSpirit ThirdPartyPreview WebApp (see figure Web components in the Project properties).

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.

To use the web component FirstSpirit ThirdPartyPreview WebApp, a configuration described in the Documentation for the Omnichannel Manager is necessary.

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

Web components in the Project properties
Figure 9. Web components in the Project properties


3.3. Definition of the external preview URL

By using the Omnichannel Manager, the ContentCreator displays external content from Spryker to which the Omnichannel Manager needs access. The preview URL of the Spryker storefront must therefore be specified in the ContentCreator properties. Since the specification is always project-specific, there is no default configuration for it within the reference project.

Open the Project propertiesContentCreator area within the ServerManager and enter the URL of the storefront with the following syntax in the External preview URL field:

https://[STOREFRONT_HOST_DOMAIN]/en/?firstSpiritPreview=[PREVIEW_INIT_TOKEN]

The token to be specified for the firstSpiritPreview query parameter must match the authentication token defined during the configuration on Spryker side. It is stored in the file config_default-[environment].php in the directory config/Shared.

External Preview URL
Figure 10. External Preview URL


3.4. Conversion rule

The data to be transferred to CaaS is defined in the template set still to be created. The use of certain special characters could lead to invalid JSON objects. A conversion rule must therefore be created in order to prevent potential errors.

It is advisable to create a new conversion rule instead of editing an existing rule. To do this, create a text file in your file system and add the following content to this file:

Conversion rule. 

0x22="\""
[convert]
0x3c="&lt;"
0x3e="&gt;"
0x22="&#34;"
0x26="&amp;"
0x27="&#39;"

Then open ServerManager and select Server propertiesConversion rules. A list of the existing conversion rules is displayed in the main panel. After clicking Add, select the text file created earlier from your file system and click Open to confirm your selection. The new rule is then added to the list in the main panel and is to be assigned to the template set to be created.

More information is available in the FirstSpirit Documentation for Administrators.

3.5. Template set

In addition to the existing template sets of a project, another XML channel is required. This must be created manually for empty projects, but is already contained within the supplied reference project ContentConnect Reference Project.

The template set was created in the ServerManager under Project propertiesTemplate sets and has the following configuration:

Template set
Figure 11. Template set


In the selection box of the same name, the conversion rule created previously must be selected.

The template set is activated and therefore available in the project. It is used to define the contents to be transmitted, which are summarized in messages during generation and transmitted to the CaaS.

3.6. Resolutions

The reference project ContentConnect Reference Project has different sections, which can be used to include images on the various pages. The editor should be able to cut the images to a certain detail. This functionality is activated by specifying a resolution.

For the reference project the resolutions CONTENT_IMAGE, BANNER_IMAGE and MAGAZINE_ARTICLE_BANNER are required. They are already created within the ServerManagers in the Project propertiesResolutions area and specified at the corresponding places.

Resolutions
Figure 12. Resolutions


3.7. Generation schedule - full generation

By default, releasing content does not update the Online CaaS and does not transfer data to Spryker. Instead, it only includes the FirstSpirit release process, which can be mapped using the BasicWorkflows release workflow, for example. An update of the Online CaaS as well as a data transfer to Spryker takes place only in the context of a deployment.

The deployment of released editorial content is executed via a CaaS schedule. Therefore the reference project has the schedule Spryker Deployment, which is created within the ServerManager in the Project propertiesSchedule management area. It can be started using the Publication action available in ContentCreator and contains the following actions:

Actions of the full generation
Figure 13. Actions of the full generation


The schedule executes a full generation and transfers the data to the Online CaaS, which provides it to Spryker for import. The actions Initialize CaaS Generation, CaaS Generate, CaaS Cleanup and Finalize CaaS Generation are used to fill the Online CaaS. They are described in the Content as a Service-Dokumentation.

The actions Execute Publish Media to CDN, Setup CaaS Blocks Aggregations, Trigger Spryker Import, Trigger Fetch Spryker Logs, Trigger Spryker Cleanup, and Send Result Mail extend the schedule and are described in the following chapters.

In case of an error, the action Send Result Mail sends an e-mail with all relevant information to a recipient to be defined. The recipient’s e-mail address must be specified in the field e-mail distribution list in the properties of the schedule.

In addition, the ChiefEditors group within the reference project must be enabled to execute a full generation. To do so, the group must be allowed to execute the Interactive execution in the properties of the schedule. This setting has already been made in the schedule supplied.

Properties of the schedule
Figure 14. Properties of the schedule


3.7.1. Execute Publish Media to CDN

Unlike the content created with FirstSpirit, the released media is not transferred to the CaaS, but to the CDN provided by the e-Spirit AG. Therefore the schedule contains the script action Execute Publish Media to CDN.

Execute Publish Media to CDN. 

import de.espirit.firstspirit.access.AdminService;

String SCHEDULER_NAME = "Media Deployment";

connection = context.getConnection();
adminService = connection.getService(AdminService.class);

scheduleStorage = adminService.getScheduleStorage();
scheduleEntry = scheduleStorage.getScheduleEntry(context.getProject(), SCHEDULER_NAME);

if(scheduleEntry != null) {
   control = scheduleEntry.execute();
   control.awaitTermination();
   isSuccessful =
      control.state.state.equals(de.espirit.firstspirit.access.schedule.RunState.SUCCESS);
   if(!isSuccessful){
      context.logWarning(SCHEDULER_NAME + " Completed with errors!");
   }
   context.logInfo("Schedule Entry executed...");
} else {
   context.logError("Could not find schedule entry with name" + SCHEDULER_NAME);
}

The script triggers the media generation schedule, which is also included in the supplied reference project. The script contains the variable SCHEDULER_NAME, which has the name of the schedule as its value. If the name changes, it must also be adjusted accordingly here.

3.7.2. Setup CaaS Blocks Aggregations

By default, CaaS stores and delivers the content transferred from FirstSpirit page-based. However, the processing and persistence of editorial content in Spryker is done on the basis of CMS blocks, each corresponding to a FirstSpirit section. In order to resolve this discrepancy, the data stored in the Online CaaS must be prepared accordingly, before importing. For this reason, an aggregation must only be added to all collections of the Online CaaS. This adjustment is not necessary for the Preview CaaS, since the information in the preview is obtained directly from it and no processing takes place in Spryker.

The schedule contains the script action Setup CaaS Blocks Aggregations to create the aggregations.

Setup CaaS Blocks Aggregations. 

#!executable-class
com.espirit.ecom.contentconnect.spryker.module.caas.BlocksAggregationSetupExecutable

The script executes a PUT request for the configured collections of the Online CaaS. This generates the aggregations that are used to make all CMS blocks contained in the extended collections available for Spryker to import. For this, the script requires the list of the relevant collections, which can be passed to it using the optional parameter caas_collections.

By default, the parameter has the value contentpages;categorypages;productpages;technical and therefore does not need to be configured in the reference project. To overwrite the default value, the parameter caas_collections needs to be added in the script’s properties dialog. Its value must correspond to a list of all collections, separated by semicolons, for which an aggregation is to be created.