FirstSpirit Connect for Spryker Commerce OS

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

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

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

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

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

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.

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. Additionally, FirstSpirit-side socket timeout must be adjusted accordingly when communicating with the glue API (see chapter Configuration of the project component).

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:

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 FirstSpirit Connect module nor by the integration. However, they are listed below and a possible solution is outlined.

Preview page not found in ContentCreator

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

Missing RAM on Composer calls

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

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.

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

The session constant for the same site cookies needs to be set after the $config[KernelConstants::CORE_NAMESPACES]:

In addition, the domain needs to be added to the whitelist configuration:

Enable SSL in the yaml file deploy.dev.yml:

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

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:

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

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

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

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:

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

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.

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

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

They are available in Spryker under the following paths:

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

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

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

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

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

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.

The config_default-[environment]_[storename].php files can be adjusted in order to support a different configuration for different stores:

The configuration FirstSpiritDataImportConstants::FIRSTSPIRIT_DATA_IMPORT_URL_TEMPLATE determines how URLs of content pages from FirstSpirit are generated in Spryker. The default value is //, with locale being the language of the content and url being the URL defined by the editor in FirstSpirit. Additionally the variable store can be used, which resolves to the abbreviation of the used store. The changes to the URL structure have to be mirrored within the output channel of the template for content pages.

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:

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

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

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

Unlike the content created with FirstSpirit, the released media is not transferred to the CaaS, but to the CDN provided by the Crownpeak Technology GmbH. Therefore the schedule contains the script action Execute Publish Media to CDN.

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

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.

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.

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.

Deleting or deactivating categories or products in Spryker that are referenced in the FirstSpirit project leads to errors and warnings during the import. However, by default these are only recorded in the Spryker log. To provide all information about a release in one place, the errors and warnings must also be recorded in the FirstSpirit log. Therefore, the schedule contains the script action Trigger Fetch Spryker Logs. It determines all errors and warnings for missing categories and products from the Spryker log and transfers them as warnings to the FirstSpirit log. Operational managers are thus given the opportunity to react quickly to the outdated references in the FirstSpirit project.

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.

In most cases, the deployment of the content created or edited in FirstSpirit is performed via the ContentCreator. However, the ContentCreator does not inform the editor whether a publication was successful or failed. Therefore, the schedule contains the script action Send Result Mail. In case of an error, this action sends an e-mail with all relevant information to the recipient defined in the e-mail distribution list field in the schedule’s properties. Additionally the e-mail contains the possibility to forward these information to the Technical Support of the Crownpeak Technology GmbH.

To transfer the media to the CDN provided by the Crownpeak Technology GmbH, they must first be generated. Therefore the schedule contains the generation action Media Generation. It represents a partial generation, which refers to the root node of the Media Store.

To avoid inconsistencies in the live state, the options Clear generation directory beforehand and Generate release version must be activated in the Properties of the action. Furthermore, it is necessary that the URL Factory selected at this point for PathGeneration and the URL-Factory for media use configured in the project component of the CaaS are identical.

Once the media have been generated, they are transferred to the CDN. Therefore, the schedule contains the action Publish to CDN. In the Cloud environment, this action is added by the Cloud department of the Crownpeak Technology GmbH and is thus already preconfigured. No further configuration is required.

The reference project provides the possibility to extend an existing navigation or to create a brand new navigation. As with content changes, navigation changes must be released in order to publish them to the live state. The reference project therefore contains the workflow Release Navigation, which requires the release right for its execution. The workflow merely releases a global page for the navigation and is therefore only activated in the Global Settings. It does not provide conflict handling, nor does it follow the principle of dual control.

The reference project contains the report Lost and Found, which shows an overview of all orphaned product and category pages. These are pages that contain references to deleted or inactive products or categories in Spryker.

Each entry of this report has a delete button, which enables the removal of the corresponding page. The reference project therefore contains the workflow Direct delete, which is triggered by this button. With the exception of the dual control principle, its functionality corresponds to that of the delete BasicWorkflow described in the following chapter. In addition to the deletion of the page, the workflow releases the parent structure and finally performs a full deployment.

Content is released, deleted, and published by editors within the supplied reference project FirstSpirit Connect Reference Project via the BasicWorkflows. These were adapted project-specifically and extended by the possibility to execute a full generation. Just like the direct release or delete option, this option is only available to roles that have the release or delete right. In the reference project, this is the group ChiefEditors.

In addition, both workflows send an e-mail to the user who has performed (and not just requested) the release or deletion. In case of success, this e-mail only informs that the workflow has been successfully executed. In case of an error, it indicates that the recipient specified in the deployment schedule has received all necessary information and should be contacted.

The following subchapter explains the adjustments made.

Installation of the BasicWorkflows module

Before using the workflows, the BasicWorkflows module must first be installed on the FirstSpirit server and the web component activated. The necessary steps are the same as the installation of the other modules and activation of the corresponding web components. By default, these steps are already performed.

The use of BasicWorkflows in ContentCreator also requires the selection of the provided BasicWorkflows Status Provider in the Project properties  ContentCreator area within the ServerManager. This setting has as well already been made in the reference project FirstSpirit Connect Reference Project.

Templates

The BasicWorkflows need different templates. These usually have to be imported into the FirstSpirit project via the context menu. However, they are already included in the reference project and an import of the templates is therefore not necessary.

Permission assignment

In the final step, the workflows must be allowed in each store to run on FirstSpirit elements. To do this, you can open the permission assignment on the root nodes of the stores via the context menu entry Extras  Change Permissions. This step has already been performed in the reference project and is therefore omitted.

The rights set on the stores' root nodes to execute the workflows refer to the Everyone group. If this is not desired, the rights must be adjusted manually.

By default, the BasicWorkflows workflows has two ways to release or to delete an item:

In both cases, the direct option is only available to roles that have the release or delete right. In the reference project, this is the group ChiefEditors. Otherwise, a release or deletion can only be requested and assigned to the next person. This person either rejects the request by manually triggering a conflict, or executes the release or deletion of the element by continuing the workflow.

Both workflows provided in the reference project were adapted project-specific and extended by the possibility, to execute a full generation in addition to the release or deletion of a page. Therefore, an additional button has been added to the start dialog and the check dialog.

In the release workflow this is the button Page Publication. It corresponds to the transition trigger_release_and_deploy, which, like direct release, can only be executed with the release right.
The delete workflow has been extended by the button Delete with publication, which represents the transition trigger_delete_and_deploy and requires both release and delete rights.

Both buttons execute the set_value_for_deployment script, which sets the deploymentTriggered variable. This variable is evaluated in the last step of the respective workflow in the script trigger_full_deployment and defines whether the workflow executes a full generation in addition to the release or deletion.

In order to execute the publication, the Executable triggered by the trigger_full_deployment script must know the name of the corresponding full deployment schedule. Therefore the Executable accesses the combo box Schedule Entry for publication, which is included in the Publication tab of the project component, and queries the schedule selected in it. Within the reference project, the full generation Spryker Deployment is defined here.

After execution, both workflows also send an e-mail to the user who has performed (and not just requested) the release or deletion. This e-mail either just informs about the successful execution of the workflow or points out that an error occurred during the publication. In this case, the e-mail also indicates that the recipient specified in the Deployment schedule has received all needed information and should be contacted. This is necessary because only project administrators can resolve errors in the deployment schedule.

Both in the case of success and in the case of error, the executable called in the last step of the respective workflow accesses the technical page template html_mail_template to send the corresponding e-mail. This template includes the texts of all e-mails sent by the workflows or deployment schedules.

Editorial content in the FirstSpirit project is always edited on the basis of a page reference. It and the page on which it is based must first be created in the FirstSpirit project. Within the reference project FirstSpirit Connect Reference Project, the creation of the page reference and its page runs automatically in the background and invisible to the editor. The infer_page_storage_information script uses the page ID defined in the IndexController to determine the corresponding FirstSpirit page template.

The page template homepage contained in the reference project is an example of a static page. The following code fragment shows the output channel of this page template:

The page template maps the Twig template home.twig and contains the content areas fs_slt_2, and fs_slt_3. The content areas enable the addition of editorial content, for which various section templates are available in the reference project. Their content is added to the json object created in the template.

In addition to the editorial content, the previewId, the identifier and the pagetype are passed to the JSON object: The previewId serves to identify the page reference and allows its decoration in the ContentCreator as well as its mapping to the Spryker Twig template. The page reference for the preview is identified by the JavaScript of the Omnichannel Manager. The generation of the page in Spryker is done using the identifier. It ensures the unique identification in Spryker. It must also be known whether the underlying page is static or dynamic. This information is indicated by the pagetype.

The generated JSON object is part of the CaaS item to be generated, which is persisted on the Spryker side by the importer.

The page template homepage contained in the reference project is an example of a static page. It contains the content areas fs_slt_2, and fs_slt_3. The content areas allow the addition of editorial content. Different section templates are available for this, all based on the same principle. One of them is the shoppable_video section template, which is described here as an example.

Within the output channel of the Shoppable Video section, various general information is first defined and stored in the block array: The previewId serves the identification of the section and enables it to be edited in the ContentCreator. The fields active and store_names indicate that the CMS block represented by the section is active on the Spryker side and visible in the store selected in the project settings.

The output of the section on Spryker side is handled by the Twig template fs_molecule_block. This corresponds to a generic template that controls the output of all molecules. In order to ensure the output of the section both in the preview and in the live state, the name and path of this Twig template must be stored within the CaaS item. Both details are therefore included in the general information of the section.

The block_name_render render template then determines the block name. This is composed of the name of the parent content area and the ID of the section.

The block_key_render render template behaves in the same way as the block_name_render render template. In contrast to this, however, it does not determine the block name, but the unique key of the corresponding block.

Using the render template additional_block_attributes_render, additional attributes are added to the block. These attributes are the slot key and the position of the block within the slot, as well as the page type and a unique ID.

The importer requires the placeholders field to be in the generated CaaS item. Therefore, it has to be created here, even though it does not have any data.

The array data contains the editorial contents maintained in the form of the section. These correspond to the video ID of the selected YouTube video and a list of video items based on the shoppable_video_item section template described below. They are displayed at defined times of the video. To display the video, the player needs the previewId specified here. On Spryker side, the section is represented by the molecule fs-shoppable-video, whose name is also contained in the data array.

The importer expects the information in the context of the current language. For this reason, the corresponding language abbreviation to which the array data is assigned is determined.

In the preview, the contents of the section are output directly. Otherwise, the last step adds the section to the blocks array defined in the page template, which contains all sections of a page and integrates them into the CaaS item to be generated.

As mentioned before, the various video items are based on the shoppable_video_item section template. Within the output channel of this template, the editorial content for a single video item is determined and stored in the item array. The editorial content corresponds to the time at which the video item is displayed, an image, a text and a reference to the detail page of a product to be selected. The last step adds the single video item to the items array defined in the shoppable_video section template, which contains all video items and integrates them into the CaaS item to be generated.

The edit dialog in the ContentCreator has the Open Video button for entering the display time, the image, the text and the reference of a video item. This button opens another dialog in which the selected video is visible and playable. With the help of a timeline, the video items can be intuitively created, edited or deleted within this dialog.

In FirstSpirit, the creation and editing of editorial content takes place in ContentCreator. The storefront is embedded in it using the Omnichannel Manager. This in turn accesses the Preview CaaS and determines the current FirstSpirit contents from there. These contents are transferred to the Online CaaS via a FirstSpirit deployment. The latter makes them available to the importer, who transfers them to Spryker and persists them there.

The Twig template home.twig represents a static page on the Spryker side and can be found under the path src/Pyz/Yves/HomePage/Theme/default/views/home. To make this page editable in ContentCreator, it is necessary to replace the CMS slots contained in it.

The inclusion of a slot is done via the Spryker standard command cms_slot, which in turn calls the FirstSpiritPreviewSlotBlockWidgetCmsSlotContentPlugin. This is part of the delivery and requires an extension of the ShopCmsSlotDependencyProvider. Unlike the CmsSlotBlockWidget included in Spryker, it only takes into account the data stored in CaaS.

The Twig template home.twig is represented by the page template homepage contained in the reference project. It is an example for a static page and has the content areas fs_slt_2 and fs_slt_3. The following code example shows the integration of the slots of the same name within the Twig template to make the static page editable in ContentCreator.

The content areas fs_slt_2 and fs_slt_3 contained in the page template homepage allow the addition of editorial content. For this purpose, various section templates are available within the reference project, for which a corresponding block Twig template must exist on the Spryker side. One of these templates is the section template shoppable_video, which is represented by the molecule fs-shoppable-video on the Spryker side. This molecule is part of the Spryker module firstspirit-reference-components included in the delivery and is stored in the directory FirstSpiritReferenceComponents in Spryker.

The following code extract shows the content of the molecule fs-shoppable-video in a highly abbreviated form:

Within the template, the name and tag of the molecule are defined first. The fsBlockData object is then created. It provides access to the structured data defined in the output channel of the FirstSpirit section template. In the preview case, this data is obtained directly from the Preview CaaS. In contrast, the data for the live state comes from Spryker. Therefore, they are imported during a FirstSpirit generation from the Online CaaS and persisted in Spryker. The fsBlockData object and the JSON object created in FirstSpirit thus have the same structure in both cases.

The block body describes the output of the editorial content. These correspond to the time at which the video item is displayed, an image, a text and a reference to the detail page of a product to be selected.

The following figure shows the representation of the CMS block.

Just like static pages, the extension of a category page in the FirstSpirit project is based on a page reference. It and its associated page are also automatically created in the background and invisible to the editor.

The reference project contains the page template categorypage, which is an example of a category page and maps the Twig template catalog-with-cms-slot.twig. The following code fragment shows the output channel of this page template:

The output channel of the category page is almost identical to that of the homepage, which corresponds to a static page. It differs only in the page type, the revision id and in the number of content areas. The page type is used to determine the block name and must have the value category at this point. The block name is determined depending on the page type using the render template block_name_render, which is referenced in the output channel of the respective section. The content areas of the page template correspond to the CMS block positions defined on the Spryker side. They must therefore be named identically.

In addition to the already described Shoppable Video section and the Text-Image section, the section template carousel_section is available for adding editorial content to category pages. The carousel section in turn embeds one or more banners.

The banner allows the selection of an image that can be cut to size as well as the definition of a link, a title and a subtitle. For both the heading and the subtitle, a text color can be selected. Unlike the other sections, which can be used only on subcategory pages, the banner can be embedded on all category pages.

The banner corresponds to the Spryker molecule fs-banner.twig, whose output is also controlled by the generic Twig template fs_molecule_block.twig. This corresponds to a generic template that regulates the output of all molecules.

The output channel of the banner is almost identical to that of the Shoppable Video section and only differs in the evaluation of the available input components. For this reason, no additional extensions are required that go beyond the requirements already described for the Shoppable Video section.

The FirstSpirit page template categorypage contained in the reference project is an example of a category page. It has the content areas banner, top and bottom and maps the Twig template catalog-with-cms-slot.twig. This is stored in Spryker under the path src/Pyz/Yves/CatalogPage/Theme/default/views/catalog-with-cms-slot and extends the parent template page-layout-catalog.twig, which defines the base layout of all category pages.

The following code example shows the Twig template catalog-with-cms-slot.twig including the adjustments necessary for editing in FirstSpirit. Since only for the positions top and bottom content areas exist in the FirstSpirit page template, the integration of the CMS blocks takes place exclusively in these two cases via the Twig function fsSpyCmsBlock.

Each CMS block corresponds to a FirstSpirit section placed at a specific position on the category page. The use of positions in category pages is enabled Spryker sided by the CMS Block Category Connector feature, which is already configured within the demo shop. The feature provides by default the positions top, middle and bottom. In FirstSpirit, the positions are represented by the content areas of the corresponding page template. For this reason, the names of the content areas and the names of the positions defined for category pages must be identical.

For the integration of the banner the feature must be additionally extended by the position banner. For this the file cms_block_category_position.csv within the directory data/import has to be adapted accordingly.

To make the positions of the blocks for category pages known, the YAML-files within data/import/local/ need to be changed:

The transfer of the new position is then done via the following command, which has to be executed in the Spryker project directory.

Furthermore, the CMS block banner has to be added to the superior Twig template page-layout-catalog.twig, which is stored in the directory src/Pyz/Yves/CatalogPage/Theme/default/templates/page-layout-catalog. Therefore, the existing block title section within the template must be replaced by the following code.

In Spryker, the banner corresponds to the molecule fs-banner. The following code fragment shows the content of the molecule in a highly abbreviated form:

Within the template, the name and the tag of the molecule are defined first and then the fsBlockData object is created. It provides access to the structured data defined in the output channel of the FirstSpirit section template. In the preview case, this data is obtained directly from the Preview CaaS. In contrast, the data for the live state comes from Spryker. For this they are imported during the FirstSpirit generation from the Online CaaS and persisted in Spryker. The fsBlockData object and the JSON object created in FirstSpirit thus have the same structure.

The block body describes the output of the editorial content. These correspond to a cropable image and a link as well as a title and a subtitle, for each of which a text color is defined.

The following figure shows the representation of a carousel with an embedded banner in the ContentCreator.

The output of all molecules is controlled by the generic Twig template fs_molecule_block.twig. The following code fragment shows the content of this template:

As in the Twig template of the molecule, the fsBlockData object is first created in the generic template. The block content then includes the molecule specified in the FirstSpirit section template for the parameter moleculename. In Spryker, the molecule is stored in the directory FirstSpiritReferenceComponents. In this way, the Twig template generically controls the output of all molecules and creates the mapping between the FirstSpirit section template and the respective Spryker block Twig template.

The attributes attribute provides additional configuration attributes that can be defined in the output channel of a section template. They are provided in this way directly in the tag of the corresponding molecule, so that they can be easily accessed via TypeScript. If no configuration attributes are defined within the output channel of a section, the attributes attribute remains empty.

Editing a product page is equivalent to extending a category page and is, in the FirstSpirit project, also based on a page reference. This and its associated page are automatically created in the background and invisible to the editor.

The page template productpage provided with the reference project represents a product page. It maps the Twig template pdp.twig and comes with the output channel displayed in the following code snippet.

The output channel of the product page and the category page are almost identical. They only differ in the specification of the Page UID, the Product SKU and in the number of content areas. The Product SKU is a unique product ID which, together with the Page UID, is used to uniquely identify the product page in Spryker. By using the script set_product_sku, the Product SKU is automatically saved in the form of the page when a product page is created in the FirstSpirit project.

The Twig template product-cms-block.twig represents a product section on the Spryker side and extends the parent template pdp.twig, in which the basic layout of all product pages is defined. 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/Yves/CmsBlockWidget/Theme/default/components/molecules/product-cms-block` in Spryker.

The template pdp.twig requires the following adaptation to enable the integration of product sections.

The following code example shows the content of the Twig template product-cms-block.twig. It first contains the name of the molecule and specifies that the specification of a Product SKU is required. This is passed to the Twig template via the parent Twig template pdp.twig. The block body is used to output the contents that are maintained for the corresponding product page.

Just like static pages and category pages, the maintenance of dynamic content pages in the FirstSpirit project is based on a page reference. However, in contrast to the other pages that already exist in the project, dynamic content pages are created using the familiar editing process. For this reason, they are initially empty.

The creation of the page reference in the ContentCreator triggers an event of the Omnichannel Manager, which triggers the creation of the corresponding CMS page in Spryker. This is necessary for displaying the CMS page in the preview.

The reference project contains the page template contentpage. It is an example for dynamic content pages and maps the Twig template fs-content-page.twig, which has to be created on the Spryker side.

Within the output channel of the page template, various general information is first defined and stored in the JSON object of the CaaS item to be generated: The previewId serves to identify the page reference and allows its decoration in the ContentCreator as well as its mapping to the Spryker Twig template. The automatically determined name and path of this template are specified using the fields template_name and template_path. The page reference is identified using the JavaScript of the Omnichannel Manager.

In addition, the pagetype parameter is used to define the page type. In the case of dynamic content pages, the field must have the value cmspage.

The is_active and store_names fields indicate that the Twig template represented by the page is active on the Spryker side and visible in the store selected in the Project settings. The is_searchable field can also be used to configure whether the page can be searched by its name in Spryker. In contrast to the previewId, which only serves for the preview, the unique identifier also allows the referencing of the CaaS item on Spryker side.

In addition to the general information, the localizedAttributes array is used to pass specific information to the JSON object, which Spryker requires for each content page. They are used to define various metadata, a page name, and the URL at which the page will be accessible in Spryker. While the various metadata can optionally be entered by the editor in the form of the page, the URL is a language-dependent mandatory field. It must have the structure /language abbreviation/subpath, with the language abbreviation automatically prefixed to the URL during generation. The importer expects this information in the context of the current language. For this reason, the corresponding language abbreviation, which is passed to each attribute, is determined.

The page template for dynamic content pages contains the two content areas content_top and content_body. They enable the creation of editorial content, for which different section templates are available in the reference project. Their contents are added one after the other to the JSON object json created in the template.

Unlike static pages and category pages, dynamic content pages have so-called placeholders. These correspond to the content areas of the FirstSpirit page template and contain only references to the CMS blocks assigned to them. After the editorial content has been entered, these references are created for each content area.

In Spryker, the Twig template fs-content-page.twig represents a dynamic content page. Unlike static pages and category pages, dynamic content pages have placeholders. To make the placeholders editable in ContentCreator, it is necessary to use the Twig function fsSpyCms to include them.

Each placeholder represents a content area of the corresponding FirstSpirit page template. For this reason, the name of the placeholder and the name of the content area must be identical. Each of the content areas can contain any number of sections, for which a Twig template must also exist in Spryker.

The FirstSpirit page template contentpage contained in the reference project is an example for dynamic content pages. It has the content areas content_top and content_body and maps the Twig template fs-content-page.twig.

Within the Twig template, specific metadata and the page title are first defined. Then the output of the two placeholders content_top and content_body is handled within the blocks title and content. They reference the CMS blocks assigned to them, which in turn control the output of the editorial content.

The following code example shows the content of the template.

Both the magazine articles and the overview page are based on dynamic content pages. Since they differ in their structure, the magazine articles need their own page template in contrast to the overview page. In the reference project this corresponds to the page template magazine_detail_page and is a copy of a contentpage. However, in comparison to the contentpage, the magazine_detail_page has only one content area, which only allows the integration of the table template of the magazine articles.

The following code fragment shows the output channel of the page template magazine_detail_page:

The output channel of the magazine articles is almost identical to the output channel of dynamic content pages. It differs only in the definitions of the identifier, some attributes and the number of content areas.

The identifier allows the referencing of the CaaS item on Spryker side and must therefore be unique. However, if it were specified within the output channel, all magazine articles would have the same identifier. Due to this it is stored in the form of the corresponding data set.

In contrast to dynamic content pages, the URL is not specified in the page form, but, like the identifier, within the data set. For this reason, it is determined at this point from the input component of the data set. For the page name, the title defined for the magazine article is used. This ensures that each magazine article has a unique page name.

The enclosing If query prevents generation errors in case of an empty data source.

In contrast to dynamic content pages, the editorial content and the block references for the magazine articles are not determined within the page template, but in the output channel of the associated table template. This represents the only permissible content for the container content area.

The overview page corresponds to a dynamic content page. It includes the data required for it using a section template and also allows the addition of further sections. For this reason, it does not need its own page template.

In contrast to the other pages, the magazine articles represent individual data sets, which are integrated into a content page via content projection. Their maintenance and processing is therefore based on a table template that provides the corresponding form and forms the basis for the corresponding data source.

The table template magazine_articles contained in the reference project consists of two thematic content blocks:
The first block maps the Twig template fs-magazine-intro.twig in Spryker and consists of superordinate intro data, such as a title and various teaser information. For their determination, the render template magazine_intro_block_render_template is referenced within the output channel of the table template, the result of which is stored in the array contentTopBlocks. The output channel of this render template is almost identical to the output channel of the Shoppable Video section and differs only in the evaluation of the available input components.
The second block corresponds to the various sections of the magazine page, which respectively represent the Twig templates belonging to them in Spryker. The sections are combined in a FS_CATALOG, which is stored in the output channel of the table template in the contentBodyBlocks array.

Both arrays are successively added to the JSON object json created in the page template.

Since the magazine articles are based on dynamic content pages, they also have so-called placeholders. The output channels of the magazine articles and the content pages are therefore almost identical from this point on. They differ only in the output of the placeholder for the body area and in the specification of the previewId. In contrast to the content pages, the body area must also exist in the preview for the magazine articles in order to avoid the prohibited addition of further sections. The previewId specified in this step overwrites the ID of the parent page, which references all magazine articles. This is necessary because the previewId of the page is identical for all magazine articles, while the article IDs are unique.

In addition to the magazine articles, there is an overview page on which the articles are listed in the form of teasers sorted by date in ascending or descending order. In contrast to magazine articles, the editorial content is not rendered via a content projection, but via two ContentSelects. The reference project therefore contains the section template magazine_overview, which can only be used in dynamic content pages.

The output channel of the section template contains the ContentSelects in the first place. These query all data sets of the data source magazine and stores them in different order in the variables fr_st_teasers_descending or fr_st_teasers_ascending.

The next step is to define various information, which is also contained in all other sections of the reference project. At this point, the output channel is therefore identical to that of the Shoppable Video section.