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:
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 assumed that the reader is confident in the use of FirstSpirit and Spryker as well as CaaS and Omnichannel Manager. |
ContentConnect enables editors to do the following:
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.
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:
The individual components always interact according to the following schema:
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.
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.
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.
With FirstSpirit, CMS blocks can be generated that are displayed in a page via CMS Placeholder.
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.
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.
To use the ContentConnect module, the following technical requirements must be met:
When using the supplied reference project ContentConnect Reference Project, the current version of the BasicWorkflows module is also required.
This chapter contains information that should be observed when using the ContentConnect module.
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.
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.
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 [...]
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.
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.
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
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/**/*" ],
The generic Twig template fs_molecule_block.twig
controls the output of the supplied molecules.
It is a part of the zip file b2c-demo-shop-extensions-<VERSION>.zip
included in the delivery and must be stored under the path src/Pyz/Shared/CmsBlock/Theme/default/template
in Spryker.
The integration of the Twig templates in Spryker takes place via the following command, which finally is to be executed in the Spryker project directory.
Integration of the Twig templates.
npm run yves
The FirstSpirit templates allow the extension of existing static pages, product, and category pages and the creation of dynamic content pages or a magazine.
Therefore, the reference project contains the page templates homepage
, productpage
, categorypage
, contentpage
, and magazine_detail_page
.
In addition, the following Twig templates are required in Spryker:
The Twig template home.twig
, which can be found under the path src/Pyz/Yves/HomePage/Theme/default/views/home
, needs some changes.
These are explained in the description of the static pages.
The remaining Twig templates are part of the zip file included in the delivery and have to be stored under the following paths:
src/Pyz/Yves/CmsBlockWidget/Theme/default/views/catalog-with-cms-block
src/Pyz/Yves/CmsBlockWidget/Theme/default/components/molecules/product-cms-block
src/Pyz/Shared/Cms/Theme/default/templates/fs-content-page
In FirstSpirit, the creation and editing of editorial content takes place in ContentCreator. The storefront is embedded in it using the Omnichannel Manager.
To enable the display of the shop contents from Spryker in ContentCreator, an extension of the environment-specific configuration is necessary.
To do this, a token must be defined in the file config_default-[environment].php
in the directory config/Shared
as well as the host and port of the FirstSpirit start page.
Furthermore, the operation of CaaS requires the specification of some parameters.
These parameters are necessary both for production operation and for the use of the CaaS in the preview.
Extension of the configuration.
// ----------- FirstSpirit Preview Configurations $config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_AUTHENTICATION_INIT_TOKEN] = '<ADD TOKEN>'; $config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_WEB_HOST] = '<ADD FS PREVIEW HOST>'; $config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_CAAS_CONTENT_PAGE_COLLECTION] = '<CAAS COLLECTION>'; $config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_CAAS_CATEGORY_PAGE_COLLECTION] = '<CAAS COLLECTION>'; $config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_CAAS_PRODUCT_PAGE_COLLECTION] = '<CAAS COLLECTION>'; $config[FirstSpiritPreviewConstants::FIRSTSPIRIT_PREVIEW_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>';
The token is used for authentication and must be specified in the ContentCreator settings as a query parameter of the external preview URL during the configuration in FirstSpirit. It can be defined arbitrarily.
Specifying the fully qualified host of the FirstSpirit home page (e.g. http://localhost:8000
) is a requirement of the HeadersSecurityExtensionPlugins to be installed.
It uses the information to enable previewing in ContentCreator.
The mentions of the CaaS collections for content, category and product pages enable access to the editorial content stored in the Preview CaaS and its display in the ContentCreator.
The 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.
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.
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;
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 some preview-specific JavaScript and CSS files, which are included in the FirstSpiritPreview module.
Both the JavaScript and the CSS files must be added to the Twig template, which is responsible for the basic layout of all shop pages.
By default this is the page-blank.twig
template, which is stored under the path src/Pyz/Yves/ShopUi/Theme/default/templates/page-blank
.
In the same template, the data attributes must also be determined by the Twig function fsIncludeDataAttributes
.
The Twig template is adapted by calling the Twig functions fsIncludeDataAttributes
and 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>
In addition to the installation of the Spryker modules, the following plugins must be included:
HeadersSecurityExtensionPlugin
FsTwigExtensionPlugin
FirstSpiritDataImportsResourceRoutePlugin
FirstSpiritDataCleanupsResourceRoutePlugin
FirstSpiritCmsPagesResourceRoutePlugin
UserAndCustomerOauthScopeProviderPlugin
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() ]; }
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
.
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() [...] ]; }
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() ]; }
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 ]; }
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:
The overwriting is done by creating the corresponding classes, which are all part of the zip file b2c-demo-shop-extensions-<VERSION>.zip
included in the delivery.
They must be copied into the directory Controller
to be created below src/Pyz/Yves/HomePage|CatalogPage|CmsPage
.
If the classes already exist under the path specified for them, the controllers are already overwritten project-specifically. In this case, it need to be ensured that the view parameters are extended accordingly. |
In contrast to the other pages, the product pages require the adaptation of the ProductController which already exists in Spryker.
It is contained in the directory src/Pyz/Yves/ProductDetailPage/Controller/ProductController
and must be extended by the definition of the page type and the Product SKU.
The following code snippet shows the changes to be made:
Extension of the ProductController.
<?php namespace Pyz\Yves\ProductDetailPage\Controller; [...] use FirstSpirit\Shared\FirstSpiritPreview\FirstSpiritPreviewConstants; class ProductController extends SprykerShopProductController { protected function executeDetailAction(array $productData, Request $request): array { [...] $viewData['cart'] = $quoteTransfer; $viewData[FirstSpiritPreviewConstants::VIEW_DATA_PAGE_TYPE_KEY] = FirstSpiritPreviewConstants::PRODUCT_PAGE_TYPE; $viewData[FirstSpiritPreviewConstants::VIEW_DATA_PAGE_ID_KEY] = $productData['sku']; return $viewData; } }
In addition to the controllers mentioned above, the delivery includes further RenderControllers which enable individual CMS elements to be updated in the preview.
They are addressed by the FirstSpiritPreviewControllerProvider
which initially does not exist in Spryker and therefore requires registration in the YvesBootstrap
file in the Pyz/Yves/ShopApplication
directory.
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) ]; }
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" />
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.
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 →
via the button .
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. |
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) ];
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 |
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(), [...] ]; }
Various components must be installed and configured in order to use the functions of the ContentConnect module. The following subchapters explain the steps required.
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 module must also be configured. The necessary steps are described in the Content as a Service Documentation. For the media usage, the generation of media into the CaaS has been defined in the CaaS project component. This configuration is explicitly not to be used in productive operation. For productive operation, the media usage must be converted to the use of a CDN. |
To configure the project component, open the ServerManager
and select →
.
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 .
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.
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.
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. |
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.
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 →
.
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
and optionally the BasicWorkflows_ContentCreator_Library
(see figure Web components in the Project properties).
The web component of the BasicWorkflows is only required when using the workflows.
In both tabs, select a web server via the selection box and start the installation with the
button. After the successful installation, a dialog opens, in which the activation of the web server is to be confirmed.For detailed information about adding web component, see the FirstSpirit Documentation for Administrators.
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 →
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
.
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="<" 0x3e=">" 0x22=""" 0x26="&" 0x27="'"
Then open ServerManager
and select →
.
A list of the existing conversion rules is displayed in the main panel.
After clicking , select the text file created earlier from your file system and click 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.
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 →
and has the following configuration:
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.
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 →
area and specified at the corresponding places.
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 →
area.
It can be started using the Publication
action available in ContentCreator and contains the following actions: