ContentConnect

For Spryker Commerce OS

e-Spirit AG

2020-03-12
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. 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 etcphp7.2cli 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 configShared:

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-cleanup
composer require firstspirit/firstspirit-data-import
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-directoryfrontend 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/**/*"
],

In the same file the compilerOptions have to be extended if the supplied Shoppable Video is used in the project. This adjustment is necessary because the TypeScript of the Twig template fs-shoppable-video accesses the Youtube API.

Enhancement of the compilerOptions. 

[...]

"compilerOptions": {
   "baseUrl": ".",
   [...],
   "paths": {
      [...]
   },
   "types": ["youtube"]
},

In addition, the fs-shoppable-video Twig template expects a Youtube iframe, which must be installed manually. The installation of the iframe as well as the adoption of the changes to the compilerOptions is done with the following commands:

Shoppable Video - Commands. 

npm install youtube-iframe
npm install @types/youtube

To use the Twig template fs-carousel, which is also 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 files-<VERSION>.zip included in the delivery and must be stored under the path srcPyzSharedCmsBlockThemedefaulttemplate 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 sections 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 srcPyzYvesHomePageThemedefaultviewshome, 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: srcPyzYvesCmsBlockWidgetThemedefaultviewscatalog-with-cms-block
  • Dynamic Content Pages: srcPyzSharedCmsThemedefaulttemplatesfs-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 configShared 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_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 two 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 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 fs-preview-ocm-impl.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 files-<VERSION>.zip included in the delivery and must be copied into the directory js or css below publicYvesassetsSTOREdefault.

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

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

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 srcPyzGlueGlueApplication 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 srcPyzZedOauth. 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 allow 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
  • FirstSpiritMagazineLinkWidget
  • FirstSpiritExternalLinkWidget
  • FirstSpiritProductFlyoutWidget

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, the FirstSpiritMagazineLinkWidget, 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 and the FirstSpiritMagazineLinkWidget are 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 widgets are registered using the following code, which must be added to the ShopApplicationDependencyProvider in srcPyzYvesShopApplication.

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\FirstSpiritMagazineLinkWidget;
use FirstSpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritExternalLinkWidget;
use FirstSpirit\Yves\FirstSpiritPreview\Widget\FirstSpiritProductFlyoutWidget;

[...]

protected function getGlobalWidgets(): array
{
   return [
      [...]
      FirstSpiritCategoryLinkWidget::class,
      FirstSpiritProductLinkWidget::class,
      FirstSpiritContentLinkWidget::class,
      FirstSpiritMagazineLinkWidget::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 files-<VERSION>.zip included in the delivery. They must be copied into the directory Controller to be created below srcPyzYvesHomePage|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 PyzYvesShopApplication. Within the file, the method getControllerProviderStack has to be extended as follows.

Extension of the method getControllerProviderStack. 

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

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

2.5. 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 srcPyzYvesErrorPage. The folder is a part of the supplied zip file files-<VERSION>.zip.

Furthermore the following line has to be added to the page error.html in the directory srcpublicYveserrorpage:

Enhancement of the error.html. 

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

2.6. Query Container

The previously installed 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 files-<VERSION>.zip included in the delivery and must be copied into the directory srcPyzZedCmsBlockStoragePersistence to be created.

2.7. 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.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 srcPyzZedConsole directory:

Extension of the getConsoleCommands. 

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

[...]

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

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

2.9. 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 srcPyzYvesShopUiThemedefault 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.10. 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, two 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 PyzZedEvent.

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

      [...]

      return $queueOptionCollection;
   }
}

The registration of the event subscriber necessary for the queues requires an adjustment of the QueueDependencyProvider in the directory PyzZedQueue:

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(),
      [...]
   ];
}

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. Installation of the modules

In order to provide the functions of the ContentConnect module, the modules Content as a Service and Omnichannel Manager are additionally required, which must also be installed on the FirstSpirit server.

The delivery contains only the ContentConnect module. The Content as a Service and Omnichannel Manager modules are available from Technical Support.

To install the modules, open ServerManager and select Server propertiesModules.

Server properties - Module installation
Figure 4. Server properties - Module installation


The main panel displays a list of all modules installed on the FirstSpirit server. After clicking Install, select the contentconnect-spryker-module-<Versionnumber>.fsm, caas-<Versionnumber>.fsm and fs-tpp-api-<Versionnumber>.fsm one after the other and confirm your selection with Open. After the successful installation, the folders ContentConnect, Content as a Service and FirstSpirit ThirdPartyPreview were added to the list, each of which must have All rights.

The Content as a Service module contains a service that is used to specify a default configuration. The necessary steps are described in the Content as a Service Documentation.

After each installation or update of a module, the FirstSpirit server must be restarted.

3.2. Project import

A part of the delivery is the reference project ContentConnect Reference Project, which has to be installed on the FirstSpirit server. Open the import dialog in ServerManager via ProjectImport and select the file referenceproject.tar.gz from your local file system via the Local button. Then enter a project name and a description and confirm the import with Yes. After the successful installation, the project was added to the list in the main panel.

Imported project in ServerManager
Figure 5. Imported project in ServerManager


In addition to the standard groups Everyone and Administrators, there are three further user groups in the reference project: Editors, ChiefEditors and ProjectAdmins. The groups have different rights, which are selected according to their tasks and defined for the different stores. Users outside these groups are not allowed to use the reference project by default.

3.3. 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 6. 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 and Publication:

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 7. 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 8. Project component - Preview


Publication

The Publication tab contains a list of all groups and deployment jobs available in the project. It allows the selected deployment job to be provided in the Actions menu of the ContentCreators for the groups selected in the tab. The Actions menu contains the Publication menu item for executing the job. For groups that are not allowed to execute the job, 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.

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

Project component - Publication
Figure 9. Project component - Publication


3.4. 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 10. Web components in the Project properties


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

External Preview URL
Figure 11. External Preview URL


3.6. 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.7. 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 12. 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.8. 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 13. Resolutions


3.9. 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 14. 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 Setup CaaS Blocks Aggregations, Trigger Spryker Import und Trigger Spryker Cleanup extend the schedule and are described in the following chapters.

Within the reference project, the ChiefEditors group must be enabled to execute both full and partial generation. To do so, the group must be allowed to execute the Interactive execution in the properties of both schedules. This setting has already been made in the schedules supplied.

Interactive execution
Figure 15. Interactive execution


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

Configuration parameter
Figure 16. Configuration parameter


3.9.2. Trigger Spryker Import

In FirstSpirit, the creation and editing of editorial content takes place in the ContentCreator. After release, they are transferred by deployment to the Online CaaS and imported from there by Spryker to be integrated into the shop. In order to keep the contents always up-to-date in Spryker, the import process must be triggered by the deployment. Therefore, the schedule contains the script action Trigger Spryker Import. The script activates a import job on Spryker side, which in turn triggers the import and persistence of the contents stored in the Online CaaS.

Trigger Spryker Import. 

#!executable-class
com.espirit.ecom.contentconnect.spryker.module.trigger.triggerimport.TriggerImportExecutable

When using the Spryker B2C Demo Shop, the import may fail when accessing the access-tokens endpoint with a Response Code 500. In this case, the key files dev_only_private.key and dev_only_public.key within the directory datashopdevelopmentcurrentconfigZed must receive the authorization 600 or 660 respectively.

3.9.3. Trigger Spryker Cleanup

The creation and editing of editorial content takes place in FirstSpirit before it is transferred to the Online CaaS via deployment and imported from there by Spryker. In order to keep the data in both systems up-to-date, deleted content from the FirstSpirit project must also be removed on the Spryker side. Therefore, the schedule contains the script action Trigger Spryker Cleanup. The script triggers a comparison between the contents stored in the Online CaaS and persisted in the Spryker data system. In this way, the obsolete data can be determined on the Spryker side and then removed.

Trigger Spryker Cleanup. 

#!executable-class
com.espirit.ecom.contentconnect.spryker.module.trigger.triggercleanup.TriggerCleanupExecutable

3.10. Generation schedule - partial generation

In addition to the generation of the entire project there may be the requirement to publish only individual pages. This requires a partial generation.

Therefore the reference project has the order Spryker Partial Deployment, which is created within the ServerManager in the Project propertiesSchedule management area. It is referenced by the release workflow described in the following and has the same actions as the <full generation with exception of the CaaS Cleanup action. In conjunction with a partial deployment, the CaaS Cleanup action results in data loss in CaaS and may therefore only be used in the full generation schedule.

Furthermore, the radio button Perform partial generation for the following starting points must be activated in the properties of the action CaaS Generate. This setting has already been made in the schedule supplied with the reference project.

Actions of the partial generation
Figure 17. Actions of the partial generation


Within the reference project, the ChiefEditors group must be enabled to execute both full and partial generation. To do so, the group must be allowed to execute the Interactive execution in the properties of both schedules. This setting has already been made in the schedules supplied.

Interactive execution
Figure 18. Interactive execution


3.11. Generation schedule - preview generation

Under certain circumstances it might happen that the datasets in the FirstSpirit project, the CaaS and in Spryker differ. In this case the contents from the Online CaaS and in Spryker can be updated by a full generation. In contrast, updating the Preview CaaS would require all pages within the FirstSpirit project to be saved again separately.

For this reason, the reference project has the schedule Spryker Preview Deployment, which is created within the ServerManager in the Project propertiesSchedule management area and can only be executed by project administrators. The schedule has the same actions as the <full generation with exception of the Setup CaaS Blocks Aggregations action. Since the information in the preview is obtained directly from the Preview CaaS and no processing takes place in Spryker, it is not necessary to create aggregations for the preview generation.

After a project import a content exchange is mandatory.

Actions of the preview generation
Figure 19. Actions of the preview generation


Within the actions Initialize CaaS Generation, CaaS Generate, Trigger Spryker Import, and Trigger Spryker Cleanup different settings are necessary.

Initialize CaaS Generation

Among other things, the action Initialize CaaS Generation requires the definition of a API Key and a CaaS URL. In the case of the preview generation, the Preview CaaS data must be specified for both parameters.

The API Key requires both read and write permissions.

A description of the action and the parameters needed for it is contained in the Content as a Service Documentation.

CaaS Generate

During preview generation, this action may only deal with the current state of the content. For this reason, the checkbox 'Generate release status' in the Properties of the action must be deactivated.

A description of the action is contained in the Content as a Service Documentation.