1. Introduction

FirstSpirit is used for creating versatile and project-specific content. Thanks to the ContentConnect module, it is now possible to transfer this content to the Salesforce Commerce Cloud e-commerce shop system and use it there.

In the remainder of this document, the abbreviated form “Commerce Cloud” will be used instead of “Salesforce Commerce Cloud”. This abbreviated form refers to Salesforce Commerce Cloud in all cases.

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

Components on the FirstSpirit side

These components are used for creating and maintaining editorial data, which is transferred to Commerce Cloud in the form of XML files and media.

Components on the Commerce Cloud side

These components are used for processing editorial content created in FirstSpirit. Commerce Cloud integrates this data into the shop and transfers it to the live state.

A part of the delivery of the ContentConnect module is a StarterPackage, including a reference project and various cartridge components, which in large part are set up on the Storefront Reference Architecture. 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. Description is given from the view of an editor as well as a FirstSpirit developer.

1.1. Range of functions

ContentConnect allows editors to:

  • Create native Commerce Cloud content using FirstSpirit

  • Access product information via the Open Commerce API (OC API)

  • Display shop elements and editorial content in the FirstSpirit preview simultaneously

  • Transfer content to the Commerce Cloud storage location via WebDAV

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

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 Commerce Cloud as part of a deployment so that it can be imported. Commerce Cloud then transfers the information to the live state.

As far as Commerce Cloud is concerned, this means there is no difference when it comes to delivering editorial content to the live state. Even if the FirstSpirit server is shut down because of maintenance work, for example, this has no effect on Commerce Cloud.

1.2. Architecture

FirstSpirit and Commerce Cloud are linked by an architecture made up of a range of components (see figure Architecture). These components are:

  • The modules installed on the FirstSpirit server:

    • ContentConnect module

    • WebDAV module

    • JSTL module

  • Commerce Cloud instances (Staging & Production)

architecture
Figure 1. Architecture

The individual components always interact in accordance with the following schema:

  1. The editorial content is created and edited in FirstSpirit. The content replaces placeholders in the HTML framework; however, the framework - like the products displayed on the live page - comes from Commerce Cloud. It is transferred via https to FirstSpirit, where it is required in order to display the preview in full. For product and category pages, this also requires communication with controllers that are part of the delivered cartridge. Products are transferred to FirstSpirit via the OC API interface of the Commerce Cloud Staging instance. This interface is also used to start various actions in the Commerce Cloud.

  2. All content changes carried out in FirstSpirit are made available to the Commerce Cloud Staging instance via WebDAV as part of a deployment. They are stored in various WebDAV directories in the form of media and XML files. From this point, they are then imported into the Commerce Cloud Staging instance library via jobs, which are initiated by a deployment action.

  3. This library is replicated in the live Commerce Cloud instance together with the product catalog. As far as Commerce Cloud is concerned, this means there is no difference when it comes to delivering editorial content to the live state.

Commerce Cloud thus represents the main component in this architecture. It delivers the content that has been created and/or maintained in FirstSpirit to the customer and provides all shop functions. There is only one loose link between the two systems; they primarily work in parallel with one another. If the FirstSpirit server is shut down because of maintenance work, for example, this has no effect on Commerce Cloud.

1.3. Concept

The ContentConnect module enables editorial content to be maintained in FirstSpirit and this to be transferred into Commerce Cloud via deployment. For this, the processing of content in both systems must be coordinated and be mutually compatible. The sub-chapters below describe the underlying concept used to achieve this compatibility.

1.3.1. Pages

Similar to FirstSpirit, the pages in Commerce Cloud are based on a structure of various components. To enable editorial content to be exchanged between both systems, these components must be coordinated.

Within the reference project ContentConnect Reference Project included in the delivery, the slots are represented by the content areas of a page template. Sections can be added to them; each one corresponds to an asset and, depending on the use cases, also has a slot configuration (see figure Page Rendering). With the aid of these configurations, it is possible to define which target group can see the corresponding content, or for how long this remains visible, for example. Each slot configuration refers to exactly one asset.

With FirstSpirit assets can thus be generated that are displayed on a page via slots.

salesforce
Figure 2. Page Rendering

1.3.2. Preview

The integration effected by the ContentConnect module only allows FirstSpirit to generate and maintain editorial content and to publish it in the form of assets. Commerce Cloud, however, continues to determine the framework of a page, whose slots integrate the generated assets.

To present the preview of a page, FirstSpirit therefore determines its current view in Commerce Cloud Storefront and downloads the HTML. The slots it contains are uniquely labeled with HTML comments. FirstSpirit substitutes these areas with the appropriate editorial content and displays the result in the preview.

1.3.3. Velocity

Salesforce provides the Content Integration API (CI API) as an alternative to the slot-based approach described previously. This API enables Velocity fragments to be evaluated on the Salesforce side, and therefore provides an easy way of implementing business logic on a page. In addition, it affords editors more control over the page layout than they have in the slot-based approach. The Velocity fragments, including the business logic, are maintained within FirstSpirit.

1.3.4. Languages

Editorial content is maintained in different languages on both the Salesforce and the FirstSpirit side. For integration, an assignment between the languages of both systems is therefore required. For this, a convention has been adopted for the languages used in the reference project, which relates to their abbreviation defined in FirstSpirit. This is oriented towards the existing languages in Salesforce and ensures every abbreviation is designated in accordance with the formula LANGUAGE CODE_COUNTRY CODE (see figure Languages). The language code corresponds to ISO 639 and the country code to ISO 3166.

Furthermore, in the project it is ensured that the FirstSpirit master language is assigned to the default language in Salesforce.

languages
Figure 3. Languages

This information is presented in more detail in the Generation and Homepage chapters.

1.3.5. Generation & deployment

It is Commerce Cloud that transfers the content created in FirstSpirit to the live state. The content must be made available to Commerce Cloud in the form of two XML files, which have been created during generation. While one of these files contains all the slot configurations created in the FirstSpirit project, the second contains all the assets.

The WebDAV deployment transfers both XML files together with the generated media to Commerce Cloud and stores them in the Commerce Cloud storage location. From this point, they are then imported via a job schedule, which is initiated by means of the FirstSpirit schedule.

1.3.6. Delete

The content of a FirstSpirit project can be changed or deleted at any time as part of the usual editorial process. These changes have to be applied to Salesforce. In the same way that new content is transferred, it is also deleted by means of deployment.

A current time stamp is added to all assets and slot configurations at the start of each full generation. Therefore, its time stamp diverges from the time stamps of the content, which is still present in Salesforce, but which has already been deleted in the FirstSpirit project. The last action of the generation schedule identifies the assets and slot configurations with an outdated time stamp and triggers their deletion.

1.4. Technical requirements

The ContentConnect module has the following technical requirements:

  • FirstSpirit version: FirstSpirit (isolated or legacy mode) since 2020-01

  • Commerce Cloud e-commerce shop system

  • Storefront Reference Architecture version 6.2.0

  • Crownpeak LINK Cartridges int_espirit, int_espirit_sfra resp. int_espirit_sg version 22.1.0

  • Open Commerce API version 22.10 or higher

  • Latest JSTL version (provided with the JSTL module)

  • Java 11 or higher

1.5. Important information

This section contains information that should be noted when using the ContentConnect module.

1.5.1. Content asset ID

Content assets that are created in FirstSpirit get a unique ID from FirstSpirit. If a content asset with the exact same ID is created in Commerce Cloud, this is overwritten by FirstSpirit when it is deployed.

2. Components

ContentConnect consists of various components. The functionality of these components is described in the following sub-chapters.

2.1. ContentConnect module

The ContentConnect module is the main component for connecting FirstSpirit and Commerce Cloud. It is extremely important for bidirectional data exchange between the FirstSpirit server and Commerce Cloud.

The module provides a report in both SiteArchitect and ContentCreator, showing the product information obtained from Commerce Cloud. The module determines which data is required and transfers it to the report when an editor initiates a query prompting it to do so. The data that is returned can then be used again for creating and maintaining editorial content.

If a generation is performed once the content has been created, the module combines the content in the form of two XML files. The WebDAV module then transfers the files to the Commerce Cloud storage location. Commerce Cloud reads out the data from this location and transfers it to the live state.

The ContentConnect module provides an API for the implementation of product-specific functions. More information is available in the accompanying Javadoc documentation.

2.2. WebDAV module

The editorial content is created and edited in FirstSpirit. In this case, however, it is Commerce Cloud that transfers it to the live state. This means that the content has to be made available to Commerce Cloud. For this purpose, the ContentConnect module creates one XML file for the library and one for the slot configuration as part of a deployment. These files must be transferred to Commerce Cloud along with the referenced media.

This is the task of the WebDAV module, which acts as a link between FirstSpirit and Commerce Cloud and stores the data in the Commerce Cloud storage location. Commerce Cloud reads out the data from this location.

2.3. JSTL module

Within the reference project, JSTL is required to preview certain pages. The JSTL module enables this. However, the module only needs to be installed on the FirstSpirit Server if JSTL has not yet been integrated on the server in any other way.

2.4. Commerce Cloud Cartridges

The delivery includes the three cartridges int_espirit, int_espirit_sfra, and int_espirit_sg. They work with all locales and are not subject to any particular restrictions in this respect.

int_espirit

The int_espirit cartridge contains scripts, which are used in the other two cartridges. The functions provided are used, for example, to map Commerce Cloud render templates on FirstSpirit page templates and thereby to make it possible to create category and product pages (see Product Page Template Mapping, Category Page Template Mappings, and Category and product pages).

int_espirit_sfra

The int_espirit_sfra cartridge overwrites a few templates from the Storefront Reference Architecture in order to enable a preview on the FirstSpirit side. The cartridge also contains the following controllers:

  • Common: The Common controller provides the standard components of a Salesforce shop as individual widgets.

  • Content: The Content controller receives the Velocity fragments maintained in FirstSpirit and returns the HTML rendered on this basis.

  • CategorySearchResult: The CategorySearchResult controller determines the products of a sub-category and provides these as a separate widget.

  • Product: The Product controller provides the widgets of a product detail page and controls how the product detail page is displayed when the website is live.

  • RenderTemplate: The RenderTemplate controller determines the Commerce Cloud render template for a specified product or a specified category. It uses the options of the Storefront Reference Architecture and draws on the functions of the int_espirit cartridge.

  • Search: The Search controller enables FirstSpirit category detail pages to be displayed in the live state.

int_espirit_sg

For shops that are not based on the Storefront Reference Architecture, the int_espirit_sg cartridge contains a corresponding implementation of the RenderTemplate controller.

3. Commerce Cloud - Installation and configuration

Various components must be installed and configured in order to use the functions of the ContentConnect module. The following sub-chapters explain the necessary steps for installing and configuring components in Commerce Cloud. The corresponding import file is located in the data folder.

3.1. Setting up the cartridges

The delivery includes three cartridges, which must be transferred to Commerce Cloud initially. Different methods for this are described in the Commerce Cloud documentation under Salesforce B2C Commerce 22.10 ➔ Developing Your Site>Development Components>Cartridges.

Next, the int_espirit cartridge must be added to all sites that are to receive FirstSpirit content. You can find relevant instructions in the Commerce Cloud documentation under Salesforce B2C Commerce 22.10 ➔ Developing Your Site>Development Components ➔ Register a Cartridge. Sites that are set up on the Storefront Reference Architecture and are maintained in FirstSpirit also require int_espirit_sfra in their cartridge path. However, if a site is based on SiteGenesis, its cartridge path must include int_espirit_sg.

The three cartridges work with all locales and are not subject to any particular restrictions in this respect.

3.2. Import of the zip file importExamples

For the setup of the job schedules and the content cleanup as well as for the slot configurations various files are required, which are stored in the file importExamples.zip. The zip file is included in the metadata directory within the delivery and must be added to the Commerce Cloud. To do so, it must be imported via the Administration  Site Development  Site Import & Export page. The files contained in it require different configuration steps, which are explained in detail in the corresponding subchapters.

3.3. Setting up the job schedules

To import the content and slot configurations generated by FirstSpirit into Commerce Cloud, a job schedule must be created in Commerce Cloud for each site. Therefore, the metadata directory of the delivery contains the zip file importExamples.zip, which requires an import into the Commerce Cloud as described previously.

The jobs imported with the zip file have the job IDs FirstSpirit-Import-RefArch and FirstSpirit-Import-RefArchGlobal by default. The ID ensures the uniqueness of the jobs for the different sites and can be adjusted as required on the Administration  Operations  Jobs page. It is recommended to include the ID of the respective site in the corresponding job ID to ensure uniqueness.

The job schedules configured in the file consist of three job steps. These are of the types Import Content, Import Content Slots, and Rebuild Search Index. All three job steps initially have the scope RefArch or RefArchGlobal, which must be changed to the appropriate site. In addition, these define different parameters whose default values can be kept mostly. Only the parameters WorkingFolder and FileNamePattern need to be adapted to the specific project. The editing dialog opens by clicking on the job step’s name.

WorkingFolder

The parameter WorkingFolder specifies - relative to the IMPEX directory - the path to the directory containing the XML files generated by FirstSpirit. Its value must be identical for both job steps.

FileNamePattern

The parameter defines the name of the XML files generated by FirstSpirit. In the case of the ImportContent job step, it must have the fs_import_library.xml value and for the ImportContentSlots job step, it must have the fs_import_slot_configuration.xml value.

General information about creating job schedules can be found in the Commerce Cloud documentation in chapter dministering Your Organization ➔ Jobs ➔ Creating Jobs.

The three job steps and their parameters are described in the Commerce Cloud documentation in the chapters ImportContent, ImportContentSlots, and SearchReindex.

3.4. Setting up content cleanup

In order to delete assets and slot configurations managed and deleted by FirstSpirit from Commerce Cloud too, the following steps must be taken:

  1. Import the user-defined system object attributes

  2. Optional: Create additional custom attributes for assets

  3. Generate search refinements for assets

  4. Adjust the OC API settings

  5. Set up the deployment schedule

Importing the user-defined system object attributes
For the persistence of time stamps assigned during generation, content cleanup uses the user-defined fsGenerationTime attribute as part of assets and slot configurations. This must initially be added to the system objects (content and slot configurations). To create the user-defined system object attributes, the zip file importExamples.zip must be available in the Commerce Cloud. It is stored within the metadata directory, which is included in the delivery. Its provision is done via the previously described import process.

Create additional custom attributes for assets
The number of content assets to be deleted can be additionally restricted on the basis of any other custom attributes. If this is desired, appropriate attributes must be created for content assets. A description can be found in the Commerce Cloud documentation under Salesforce B2C Commerce 22.10 ➔ Administering Your Organisation>Business Objects ➔ Creating Custom Attributes for Business Objects.

Generating search refinements for assets
For the newly created fsGenerationTime attribute and the additionally created custom attributes, a Commerce Cloud Search Refinement is to be generated. The Commerce Cloud documentation describes this under Merchandising Your Site ➔ Content Assets ➔ Working with Content Assets ➔ Creating Content Search Refinements.

After importing the user-defined system object attributes and creating the search refinement, it is necessary to rebuild the site’s search indexes.

3.5. OC API Settings

The OC API is used for aspects including reports and deployment. Therefore, the corresponding permissions must be set in Salesforce for the Client ID that is used.

The rights adjustments described below can also be found in the separate files Shop OCAPI-Settings and Data OCAPI-Settings.

The Client ID that is used requires permission to execute GET queries via the ShopAPI for the resources indicated below. These must be implemented in the global or site-specific context according to the use case.

  • /products/*/variations

  • /products/*

  • /product_search/variations

In addition when using content cleanup:

  • /content_search

Permissions are additionally required to execute GET, POST, and DELETE queries via the DataAPI for the resources indicated below. They are to be exclusively defined in the global context.

  • /catalogs (GET only)

  • /catalogs/*/categories (GET only)

  • /jobs/*/executions (GET & POST)

  • /jobs/*/executions/* (GET only)

In addition when using content cleanup:

  • /sites/*/slot_configuration_search (POST only)

  • /libraries/*/content/* (DELETE only)

  • /sites/*/slots/*/slot_configurations/* (DELETE only)

Furthermore, the usage of the Sorting Rules requires the following definition:

  • /sites/*/sorting_rule_search (nur POST)

If, as an option, workflows are to be used for deleting library folders and folder assignments, permissions are then required to execute DELETE queries via the DataAPI for the following resources:

  • /libraries/*/folders/*

  • /libraries/*/folder_assignments/*/*

3.6. Slot configurations

The templates from the int_espirit_sfra cartridge are used to add new slots to the site. Therefor, the delivery provides the zip file importExamples.zip with slot configurations for these slots. It is stored within the metadata directory, which is included in the delivery. The provision of the zip file slotConfigurations.xml in the Commerce Cloud is done via the previously described import process.

4. FirstSpirit - Installation and configuration

Various components must be installed and configured in order to use the functions of the ContentConnect module. The following sub-chapters explain the necessary steps for installing and configuring components in FirstSpirit.

4.1. Installing the modules

The ContentConnect delivery contains three modules that must be added to the FirstSpirit server. To install the modules, open the ServerManager and select Server properties  Modules.

modules
Figure 4. Module management in the server properties

The main panel contains a list of all the modules installed on the FirstSpirit server. Click Install, then select the contentconnect-fsm-<version number>.fsm file provided first, followed by the WebDavDeployment-<version number>.fsm and jstl.fsm files. Each time you make a selection, click Open to confirm it. Once installation has been successfully completed, the folders ContentConnect, WebDavDeployment and JSTL are added to the list. Each of these must be given All permissions.

The JSTL module only needs to be installed on the FirstSpirit Server if JSTL has not yet been integrated on the server in any other way.

After any module installation or update, the FirstSpirit server needs to be restarted.

4.2. Using WebDAV with https

To use the WebDAV server with https instead of http, it is not necessary to perform any additional configuration work. However, a local certificate authority managed by the company is normally used for https. The certificate in question, including the entire chain up to the certificate on the WebDAV server, must be made available to the FirstSpirit server’s JVM.

The JVM expects public certificates of this kind to be in the form of a PKCS12 file or a JKS file.

Using the command below, import the public root or intermediate certificates into a JKS file and select Yes in answer to the question whether the certificate is to be trusted. You must repeat this process for each certificate.

keytool -import -file cert1.crt -keystore truststore.jks –storepass changeit

Copy the Trust Store that is generated into the firstspirit5  conf directory of your FirstSpirit server and add the following lines to the file firstspirit5  conf  fs-wrapper.conf.

wrapper.java.additional.100=-Djavax.net.ssl.trustStore=conf/truststore.jks
wrapper.java.additional.101=-Djavax.net.ssl.trustStorePassword=changeit
wrapper.java.additional.102=-Djavax.net.ssl.trustStoreType=JKS

The parameters must be activated by restarting the FirstSpirit Server.

If the WebDAV server is expecting mutual SSL authentication, you must use the following calls to create and sign a client certificate as a first step.

openssl genrsa -out private.key 2048
openssl req -new -key private.key -out request.csr

The file request.csr is sent to the certificate authority, which responds with the file cert.crt. The private key, the public certificate, and the certificate from the certificate authority must then be collected in a Key Store to be read by the JVM.

cd firstspirit5/conf
openssl pkcs12 -export -in public.crt -inkey private.key \
-out clientcert.p12 -CAfile authority.crt

If the certificate chain consists of one or more intermediate certificates, you can import them via keytool.

keytool -import -file intermediate1.crt -trustcacerts \
-keystore clientcert.p12 -storepass changeit

The Key Store can be transferred to the JVM of the FirstSpirit Server by adding the following lines to firstspirit5  conf  fs-wrapper.conf.

wrapper.java.additional.103=-Djavax.net.ssl.keyStore=conf/clientcert.p12
wrapper.java.additional.104=-Djavax.net.ssl.keyStorePassword=changeit
wrapper.java.additional.105=-Djavax.net.ssl.keyStoreType=PKCS12

4.3. Project import

A part of the StarterPackage included in the delivery is the reference project ContentConnect Reference Project, which must be installed on the FirstSpirit server. To do this, open the import dialog in the ServerManager via the menu item Project  Import and click the Lokal button to select the ContentConnectReferenceProject.tar.gz file from your local data system. Then assign a project name and description and confirm the import with Yes. After successful installation, the project is added to the list in the main panel (see figure Imported project in the ServerManager).

importedproject
Figure 5. Imported project in the ServerManager

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

4.4. Configuring the project component

A project-specific configuration is required in order to use the ContentConnect module. It is set up using the project component, which is already added to the reference project supplied.

To configure the project component, open the ServerManager and select Project properties  Project components. A list of all existing project components is displayed in the main panel. Select the entry ContentConnect Project Configuration and click Configure to open the associated dialog (see figure Configuration dialog for the project component).

The subsequent configuration is used by the module services. The service and all running clients must be restarted each time the configuration is changed. Otherwise, the change in question will not be applied either to the services or to the clients.
config
Figure 6. Configuration dialog for the project component
Base URL

Start by entering the Base URL, which is derived from the URL of the Commerce Cloud instance and the ID of the site being used:

https://<SUBDOMAIN INSTANCE>.demandware.net/s/<SITE ID>

Based on this structure, a unique connection between the FirstSpirit project and the Commerce Cloud site is always guaranteed.

The Base URL field is a mandatory field.

To avoid problems concerning the certificate, it must be ensured that the subdomain does not contain any periods in its name.
Storefront Hostname

This configuration field is optional and should only be filled in if the hostname of the Storefront Base URL in the Project settings differs from the hostname of the Base URL configured in this dialog. In this case, the hostname including the protocol of the Storefront Base URL should be entered here.

Example:

https://<DIFFERENT SUBDOMAIN INSTANCE>.demandware.net/

Client ID

The Client ID is also a mandatory field. This is required in order to be able to use the Open Commerce Shop API.

The Client ID and the Base URL are essential for the connection between Commerce Cloud and FirstSpirit. If one of the two pieces of information is incorrect or is not available, then the relevant report for the product search is hidden in both FirstSpirit Clients.
Password

The components of the ContentConnect API require password-based authentication against Commerce Cloud. For this reason, a password that is defined when the API client is registered with Commerce Cloud is required in addition to the client ID.

Refinements

Refinements that improve product searches are defined in this configuration field. Refinements are entered as key value pairs separated using commas.

Up to the first nine key value pairs entered are used (Commerce Cloud will not accept more than nine refinements).

The format of the values of the key value pairs matches the format Commerce Cloud expects for refinement values. Both multiple values and sets of values can be entered for a refinement:

  • cgid=new-arrivals|electronics

  • price=(0..100)

Since a refinement is also used for category searches, two special cases need to be considered:

In the first case,

  • the product search is filtered by a category and

  • the configuration contains nine refinement definitions,

  • none of which is the cgid category refinement.

In this case, there are a total of ten refinement definitions, which is not permitted. Therefore, one of the refinements from the configuration is ignored so that the product search can be filtered by a category.

In the second case,

  • the product search is also filtered by a category and

  • the configuration contains the cgid category refinement.

In this case, there is a duplicate definition for the cgid category refinement: one from the module configuration and one from the product search; the latter is used. The value from the configuration is then used as the default value. It can be overwritten by the editor.
Locale

The Locale identifies the language and region of the current project. A maximum of one ID for an active locale that is permitted for storefront requests in the site configured at the top of the dialog may be entered. If the field is left blank, the locale parameter will not be used in storefront requests.

Auth User

If access restriction is activated in Commerce Cloud, the storefront user must be specified in this field.

Auth Password

The password belonging to the storefront user is specified in this field.

Product Page Template Mapping

One of the functions supported by the product report is the user-friendly creation of product pages, which use the page template Product Detail Page in the reference project. To enable this, this configuration field allows Salesforce render templates to be mapped to FirstSpirit page templates. The following rules apply here:

  • The field contains either no content at all or one or more mappings.

  • If the field remains empty, the use of product pages in the project is disabled.

  • Mappings are specified using a list separated by commas: <mapping>,<mapping>

  • Each mapping is arranged as follows: <isml_template>:<fs_template>

  • To configure a page template for all ISML templates that do not have an explicit mapping, the following form must be used: default:<fs_template>

Default Folder (Product Pages)

To create a new product page, it is essential to know where the page is to be integrated into the structure. The reference name of the Product Pages structure folder has already been entered here. All new product pages within the reference project are created in this folder. If the field is left empty, the editor must select a menu level.

Editable Folder (Product Pages)

This checkbox makes it possible to specify whether an editor can change the selection made in the Default Folder (Product Pages) field. The function is activated initially. If it is then deactivated, the corresponding input component is hidden in the dialog for creating a category or product page. In this case, it is not possible for the editor to select or change the menu item for a newly created category or product page.

The field Default Folder (Product Pages) and the checkbox Editable Folder (Product Pages) are ignored if the field Product Page Template Mapping is empty. If, instead, a mapping is defined, it is mandatory that the reference name of a structure folder is specified or that the checkbox is activated. Otherwise, it will not be possible to create new product pages due to the lack of assignment to a menu level, and errors will occur.
Category Page Template Mappings

The mapping of page templates can be configured using this configuration field for the creation of category pages via the category report. The following rules apply here:

  • The field contains either no content at all or one or more mappings.

  • If the field remains empty, the use of category pages in the project is disabled.

  • Mappings are specified using a list separated by commas: <mapping>,<mapping>

  • Each mapping is arranged as follows: <isml_template>:<fs_template>[:fallback_category]

  • The third part of the mapping is optional and is used to specify a fallback category for category pages that are based on the specified ISML template

  • To configure a page template and an optional fallback category for all ISML templates that do not have an explicit mapping, the following form must be used: default:<fs_template>[:fallback_category]

Categories can be marked as offline within Commerce Cloud. These offline categories are not delivered via the storefront, whereby no preview can be generated for them. To make it possible to also maintain category pages for offline categories via the FirstSpirit report, fallback categories must be specified for the associated ISML templates. Within the preview for an offline category page, this is then replaced by the configured fallback category.

We recommend using separate FirstSpirit templates for product pages and category pages.
Default Folder (Category Pages)

In the same way as with product pages, for each new category page it is essential to know where the page is to be integrated into the structure. The reference name of the Category Pages structure folder has already been entered here. All new category pages within the reference project are created in this folder. If the field is left empty, the editor must select a menu level.

Editable Folder (Category Pages)

In the same way as with the Editable Folder (Product Pages) checkbox, here it is possible to specify whether editors can change the selection made in the Default Folder (Category Pages) field. The function is activated initially. If it is then deactivated, the selection option is hidden in the dialog for creating a category page. In this case, it is not possible for the editor to select or change the menu item for a new page.

The field Default Folder (Category Pages) and the checkbox Editable Folder (Category Pages) are ignored if the field Category Page Template Mapping is empty. If, instead, a mapping is defined, it is mandatory that the reference name of a structure folder is specified or that the checkbox is activated. Otherwise, it will not be possible to create new category pages due to the lack of assignment to a menu level, and errors will occur.
Template Instantiation Script Uid

Select a script to be executed before and after category or product pages are created in this configuration field (the selection of a script is optional). The create_sfcc_item_wizard script specified is used to execute project-specific actions, which are required to generate the preview. In the reference project, it marks the created category or product page as translated for all languages.

Please note that only the code from the HTML channel of the script is executed.
View Type Priority

Images of products from Commerce Cloud are always provided in a range of sizes, but an image will not necessarily have been stored for every size. For this reason, the View Type Priority has been provided so that you can define which image sizes you wish to incorporate, separating the information you enter with commas.

In the case shown in the figure Configuration dialog for the project component, the medium image associated with each product is identified and is used if it exists. If there is no medium image, the large image is called up, followed by the small one if necessary.

As this is not a mandatory input field, it may therefore remain empty if you do not wish to define an order of priority. If this is the case, search results from a product query will be shown without an image.
Image Service Base URL

Commerce Cloud provides what is known as an Dynamic Imaging Service. If you wish to use it, you must specify the URL of the Image Service in the form http[s]://<image server host name> at this point. Product images are then called up via the Image Service.

Specifying the Image Service Base URL is optional. However, if the field is filled with a URL, then this entry must not contain any errors; otherwise, the relevant report for the product search is hidden in both FirstSpirit Clients. This still applies even if the Client ID and the Base URL are correct (see above).

Filtering by category differs depending on the report used. In the report for the product search, filtering is possible across all categories. In the report for the category search, however, filtering is only possible via the top-level categories.
Show Category Report

This checkbox can be used to control the display of the category report. The checkbox is deactivated by default (i.e., only the report for product searches is active).

category report
Figure 7. Category report
Test Configuration

Click the Test Configuration button to check the entries that have been entered. For this, the Client ID, the Base URL and - if available - the Image Service Base URL as well as the configurations for the product and category pages are taken into account.

4.5. Adding web components

Two web components are required for the Preview and for ContentCreator and have already been added to the reference project supplied. Nevertheless, they still need to be installed on an active web server. To do this, open the ServerManager and select Project properties  Web components.

Inside the main panel, various tab pages are visible. Each tab page contains a list of the existing web components. The list contains the following entries both for the Preview as well the ContentCreator (see figure Web components in the project properties):

  • ContentConnect Web Component

  • FS_JSTL_WebApp

Select a Web server on both tab pages via the selection box and start the installation by clicking the Install button. After successful installation, a dialog opens, in which the activation of the Web server must be confirmed.

More detailed information on how to add web components is available in the FirstSpirit Documentation for Administrators.

webcomponents
Figure 8. Web components in the project properties

4.6. Configuration of the web component

Part of the web component of the ContentConnect module are the Preview Proxy and the Preview Filter. Both components can be configured via the web.xml and are described in more detail in the following two chapters.

4.6.1. Preview Proxy

If problems with cross-origin requests occur during the preview due to the same-origin policy of modern web servers, then these can be remedied by using the Preview Proxy included in the ContentConnect module.

To do this, the calls to the resources concerned must be routed via the Preview Proxy. The Preview chapter explains how this is done in the project.

The Preview Proxy is configurable via the web.xml with the following parameter:

Parameter Default value Description

connection.keepalive

60

Duration of maintaining a connection within the Preview Proxy in seconds. Too high values may cause problems when loading resources.

Example

An example snippet of the web.xml, in which the Preview Proxy’s parameter is configured and the preconfigured URL path has been adjusted, might look as follows:

Example web.xml 
<servlet>
    <servlet-name>ContentConnectPreviewProxy</servlet-name>
    <servlet-class>com.espirit.moddev.demandware.preview.proxy.ProxyServlet</servlet-class>
    <load-on-startup>0</load-on-startup>
    <init-param>
      <param-name>connection.keepalive</param-name>
      <param-value>120</param-value>
   </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>ContentConnectPreviewProxy</servlet-name>
    <url-pattern>/assets/*</url-pattern>
</servlet-mapping>

4.6.2. Preview Filter

The ContentConnect Preview Filter determines the necessary information for displaying a page in the FirstSpirit preview. In the slot-based approach, it identifies the correct storefront URL for this purpose, downloads the HTML on the basis of this URL, and substitutes the slots it contains with the corresponding editorial content. If the CI API is being used, however, it has the Velocity fragments maintained in FirstSpirit evaluated on the Salesforce side, and displays the result at the corresponding point on the page in the FirstSpirit preview.

To carry out these steps, the filter requires some information that can be configured via various parameters in the web.xml of the added web components (for the Preview as well as ContentCreator). This information relates to various aspects, which can be divided into four groups.

The web.xml of the added web component added in the tab preview requires the adjustment of the parameter dispatcher. By default, the web.xml contains the value FORWARD for this parameter. However, in the case of the preview in the SiteArchitect, it requires the value REQUEST and must be replaced accordingly.

Adjustment in the web.xml for the preview in the SiteArchitect 
<filter-mapping>
   <filter-name>ContentConnectPreviewFilter</filter-name>
   <url-pattern>/*</url-pattern>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>

Beyond that, a configuration of the individual parameters is only necessary if their default values do not match the project-specific conditions.

Storefront URL parameters

As described previously, the Preview Filter determines the necessary information on the Salesforce side - both in the slot-based approach and when using the CI API. It then displays this information in the FirstSpirit preview. To do this, a project-specific storefront URL is required. As this is maintained in the project settings, the Preview Filter requires the associated input component to be specified for its query.

Parameter Default value Description

storefront.url.baseUrlFormField

ps_storefrontUrlBaseUrl

The input component for specifying the storefront’s base URL, which is extended with the page type and the ID of the element to be displayed (e.g., product, category, or asset ID). The component is maintained in the project settings.

The syntax for the storefront base URL can be found in the Salesforce B2C Commerce 22.10 ➔ Merchandising Your Site ➔ Search Engine Optimization ➔ URL Syntax ➔ Salesforce B2C Commerce URL Syntax Without SEO chapter of the Salesforce Commerce Cloud documentation.

As a value of the input component ps_storefrontUrlBaseUrl, only up to the locale, not the entire URL must be entered within the project settings.

E.g.: https://www.mystore.com/on/demandware.store/​Sites-YourShopHere-Site/

Changes to the project settings do not take effect straight away, as they are saved in the session of the user. They require the client to be restarted.

Storefront Crop Marks parameters

The placeholders included in the editorial content consist of a start as well as an end comment and have the format <!-- CMS-<IDENTIFIER>-START -→ or <!-- CMS-<IDENTIFIER>-END -→ by default. However, the use of individual affixes can be activated via a toggle in the project settings, which must be added if necessary. In this case, the default values are overwritten and specific prefixes and suffixes are used instead. In order to grant the Preview Filter access to this information, it requires the associated input components to be specified.

Parameter Default value Description

storefront.cropMarks. customAffixes.enabledFormField

ps_storefrontCropMarksCustomAffixesEnabled

The toggle in the project settings for (de)activating the use of individual affixes.

storefront.cropMarks. opening.prefixFormField

ps_storefrontCropMarksOpeningPrefix

The input component in the project settings for specifying a prefix for the start comment.

storefront.cropMarks. opening.suffixFormField

ps_storefrontCropMarksOpeningSuffix

The input component in the project settings for specifying a suffix for the start comment.

storefront.cropMarks. closing.prefixFormField

ps_storefrontCropMarksClosingPrefix

The input component in the project settings for specifying a prefix for the end comment.

storefront.cropMarks. closing.suffixFormField

ps_storefrontCropMarksClosingSuffix

The input component in the project settings for specifying a suffix for the end comment.

Storefront protection parameters

It is possible to protect the connection to Commerce Cloud via an authentication. This can be (de)activated in Salesforce and must be applied to FirstSpirit via the corresponding toggle in the project settings. If it is activated, the required access data must also be specified. The Preview Filter must be able to access this information and therefore requires the associated input components to be specified.

Parameter Default value Description

storefront.protection.enabledFormField

ps_storefrontProtectionEnabled

The input component in the project settings for (de)activating the authentication for the storefront URL.

storefront.protection.userFormField

ps_storefrontProtectionUser

The input component in the project settings for registering the storefront user.

storefront.protection.passwordFormField

ps_storefrontProtectionPassword

The input component in the project settings for the password of the storefront user.

Storefront downloader parameters

In addition to the other parameters, which are primarily used to determine the correct storefront URL, in the slot-based approach it must be possible to control the behavior of the Preview Filter while the HTML of the corresponding page is downloading. For this, it has different parameters, which can be maintained in the project settings. The Preview Filter must be able to access this information and therefore requires the associated input components to be specified.

The storefront downloader parameters are used to initialize the filter in the slot-based approach. As a result, they have a fixed fallback value for cases with a missing or empty input component.
Parameter Default value Description

storefront.downloader.maxConnections

ps_storefrontDownloaderMaxConnections

The input component in the project settings for specifying the maximum permissible number of parallel connections to Storefront.
The fallback value is 100.

storefront.downloader.socketTimeout

ps_storefrontDownloaderSocketTimeout

The input component in the project settings for specifying the time span (in milliseconds) in which a response from Storefront is expected.
The fallback value is 10000.

storefront.downloader.retryCount

ps_storefrontDownloaderRetryCount

The input component in the project settings for specifying the maximum number of connection attempts.
The fallback value is 3.

The use of the following two parameters is only recommended in exceptional cases, as they bypass the certificate check for https requests. This may be necessary if certificate errors prevent the preview from being displayed and the problem can not be resolved on the server side.
Parameter Default value Description

storefront.downloader.certificatesCheck

true

Setting this parameter to false disables certificate checks for https requests. As a result, all https requests for viewing the preview will be blocked initially. To allow requests against individual pages, the host name of the corresponding pages must be entered in the sslWhitelist.

storefront.downloader.sslWhitelist

empty

If the certificate check is deactivated, the host names to be excluded from the blocking are maintained via the sslWhitelist. Several host names have to be entered as a comma-separated list.

Storefront Cache Parameter

The HTML of slot-based pages downloaded by the Preview Filter is stored in a cache so that it does not have to be retrieved from the Commerce Cloud every time it is called. Such a cache exists across sessions for each project on the FirstSpirit server. This cache has some parameters that can be maintained in the project settings. The Preview Filter must be able to access this information and therefore needs to specify the associated input components.

Like the downloader parameters, the cache parameters are used to initialize the filter in the slot-based approach. For this reason they have a fixed fallback value in case of a missing or empty input component.
Parameter Default value Description

storefront.cache.maxEntries

ps_storefrontDownloaderMaxCacheEntries

The input component in the project settings for specifying the maximum number of elements in the cache.
The fallback value is 500.

storefront.cache.refreshAfterWrite

ps_storefrontCacheRefreshAfterWrite

The input component in the project settings for specifying the time span (in hours) until an element in the cache is marked as obsolete.
The fallback value is 1.
If an entry is marked as obsolete, it will be retrieved asynchronously from the Commerce Cloud at the next request. Until this process is completed, the cache returns the obsolete entry, so there is no delay.

storefront.cache.expireAfterWrite

ps_storefrontCacheExpireAfterWrite

The input component in the project settings for specifying the time span (in hours) until an item in the cache is marked as removable.
The fallback value is 24.
If an entry is marked as removable, it can be displaced from the cache by new elements. If an item is requested again after being displaced, it must be retrieved from the Commerce Cloud again.

storefront.cache.excludePatterns

ps_storefrontCacheExcludePatterns

The input component in the project settings for specifying storefront URLs that should not be kept in the cache. The URLs are specified in the form of a list of regular expressions.
The fallback value is an empty list.
Each element of the list component must have a text field named st_storefrontCacheExcludePattern containing the regular expression.

Example

An example snippet of the web.xml, in which two parameters of the Preview Filter are configured, might look like as follows:

Example web.xml 
<filter>
   <filter-name>ContentConnectPreviewFilter</filter-name>
   <filter-class>com.espirit.moddev.demandware.preview.PreviewFilter</filter-class>
   <init-param>
      <param-name>storefront.downloader.socketTimeout</param-name>
      <param-value>ps_myCustomStorefrontDownloaderSocketTimeout</param-value>
   </init-param>
   <init-param>
      <param-name>storefront.downloader.retryCount</param-name>
      <param-value>ps_myCustomStorefrontDownloaderRetryCount</param-value>
   </init-param>
</filter>

4.7. Resolutions

The reference project ContentConnect Reference Project has different sections, with which images can be integrated on the various pages. It should be possible for the editor to crop the images to a certain image section. This function is activated by specifying a resolution.

Specifying the resolution 
$CMS_REF(st_picture, resolution:"RESOLUTION")$

For the reference project, the following resolutions are required: BANNER, SLIDE, GRID_ELEMENT_HIGH, GRID_ELEMENT_WIDE, GRID_ELEMENT_SQUARE, IMAGE_MAP, ARTICLE_TEASER_IMAGE and TECHNOLOGY_IMAGE. They are already applied within the ServerManager in the Project properties  Resolutions area and specified in the corresponding areas in the sections.

resolutions
Figure 9. Resolutions

4.8. Deployment schedule

To transfer the content created in FirstSpirit to the Commerce Cloud storage location, the reference project supplied has a schedule, which contains the actions specified below (see figure Generation schedule actions). A description of the individual actions is provided in the subsequent sub-chapters.

More information on creating a schedule is available in the FirstSpirit Documentation for Administrators.

actions
Figure 10. Generation schedule actions

4.8.1. Initialize SFCC deployment

The first step is to initialize the deployment. This involves setting up content cleanup. While this is under way, a time stamp prior to the generation is created. This time stamp is used by the cleanup action in the last step of the schedule to delete outdated assets and slot configurations. It is for this reason that the schedule contains the action Salesforce Commerce Cloud Initializer:

sfcc initializer
Figure 11. Schedule action

To use content cleanup, the initialization must be the first action of the schedule. Otherwise this can lead to inconsistencies in the data inventory.

4.8.2. Content preparation - Full generation

To deploy the content that is relevant to Commerce Cloud, it must be determined from the project first. This requires a full generation to be carried out, generating all the referenced media in the correct resolution. The full generation also generates the XML collectors initialized in the project settings and fills them on the basis of the xmlCollector calls in the templates.

The schedule therefore has the generation action Content Preparation in whose Properties the following options are activated (see figure Content preparation action):

  • Perform FullGeneration

  • Clear generation directory beforehand

  • Generate Media in the generation directory

The defined Prefix for absolute paths /firstspirit is required for the WebDAV deployment action.

It is only possible to use the WebDAV module in conjunction with the default URL creator. To generate the path, the entry Default URLs is therefore selected, which is absolutely essential at this point.

The template sets for all the languages present in the project are also selected on the Extended tab page. In addition, the variable dwre_xmlGeneration is added, which contains the value false. This is set to the value true in the subsequent XML Import File actions and ensures that the XML files for the slot configurations and assets are only created once the generation is complete. The XML template in the project controls the process of generating the XML file.

content preparation
Figure 12. Content preparation action

4.8.3. XML import file - Partial generations

Commerce Cloud expects all data that is transferred to it to be in the form of XML files. For this reason, the information determined during the full generation must be read out of the XML collectors that are generated. In this case, the information must instead be written to an XML file that has to be created each time.

For each XML collector initialized in the project settings, the schedule provides another generation action. In contrast to the Content Preparation action, these are, however, partial generations. In their Properties, the option Execute partial generation for following start nodes is therefore activated. As a starting point, one of the page references based on the XML template is used (see figure Partial generation).

The variable dwre_xmlGeneration, which contains the value true, is also added to the Extended tab page for each of these actions. Together with the start node selected in each case, this ensures that the selected page reference is not generated until this point in time. This means that all the information required for creating the XML file will be available when this happens and it will not be possible for any gaps to appear. The XML template in the project controls the process of generating the XML file.

content libary
Figure 13. Partial generation

4.8.4. WebDAV deployment

Next, the XML files generated by means of the partial generations must be transferred to Commerce Cloud. They are published via a script action, for which the following parameters are defined in their Properties:

wdparameter
Figure 14. Properties
url

The URL specifies the host and the path on the WebDAV server. It always has the following structure:

https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Impex/…​/<PREFIX>/<SITE ID>

The path points to the location where the XML file in question is expected to be during the import. It must refer to an existing directory.
Additionally, the prefix must be the same as the Prefix for absolute paths used in the full generation.
user

A technical user who is authorized to use the WebDAV interface is required in order to transfer the data. This user must have write permissions and must be specified by name here.

Further information about these rights can be found under Administering Your Organization ➔ Permissions, Users, and Roles ➔ Roles and Permissions ➔ Create a Role in the Salesforce documentation.

password

A password is also required for the user specified in the previous step.

The technical user is subject to the password conditions defined by Commerce Cloud, which require the password to be changed at least every quarter. The parameter value must be changed each time this is carried out.
mediaurl

The media folder generated during the generation process, and its content, must be transferred to a separate directory so that Commerce Cloud can perform the import. This directory is defined using the parameter mediaurl. The mediaurl always has the following structure:

https://<SUBDOMAIN INSTANCE>.demandware.net/on/demandware.servlet/webdav/Sites/Libraries/<SITE ID|LIBRARY ID>/default/<PREFIX>

The mediaurl must refer to an existing directory.
Furthermore, as with the url, the prefix must be the same as the Prefix for absolute paths used in the full generation.

If a private library is being used, it is necessary to specify the site ID instead of the library ID in the path.
srcprefixdir

If only one particular directory is transferred to Commerce Cloud, it can be specified in relation to the root node of the generation directory using the optional parameter srcprefixdir. If the parameter is not defined, or no value is saved for it, the entire generation directory will be transferred.

purge

This parameter is optional and may only have the value true or false. If true is set, all the files and directories under the specified URL will be deleted before the transfer starts. If the parameter is set to false or no value at all, all the existing files and directories under the specified URL will be retained. New data will either be added or, in the case of existing data, overwritten.

javax_net_ssl_keyStore (optional)

This parameter can be used to specify a dedicated Java certificate file for WebDAV deployment.

javax_net_ssl_keyStorePassword (optional)

The password of the Java certificate file.

javax_net_ssl_keyStoreType (optional)

The type of the Java certificate file, e.g. jks.

The WebDAV deployment must not be executed in the event of an error.

4.8.5. Trigger SFCC import job schedule

Following the publication of the created XML files via WebDAV deployment, the created job schedule is executed. In Salesforce, the job schedule triggers the import of the generated content and slot configurations into Commerce Cloud. The ContentConnect module provides the Salesforce Commerce Cloud Importer schedule action for this purpose:

sfcc task
Figure 15. Schedule action

The action loads a configuration dialog, in which two parameters must be defined in addition to a freely assignable name.

import schedule task
Figure 16. Schedule action parameters
Import Job ID

This field contains the ID of the created job schedule.

Timeout

The value in this field displays the time span in seconds, in which the status of the job schedule will be queried every second. If the job schedule has not completed in the specified time span, this schedule action is indicated as having an error. The default value is 10 seconds.

As the Salesforce Commerce Cloud Importer requires a successful WebDAV deployment, this too must not be executed in the event of an error.

4.8.6. Salesforce Commerce Cloud Cleanup

Once the created job schedule has been executed, content cleanup is executed. All outdated assets and slot configurations are queried by the OC API and then deleted. The ContentConnect module provides the Salesforce Commerce Cloud Cleanup schedule action for this purpose:

sfcc cleanup
Figure 17. Schedule action

In addition to a freely assignable name for this schedule action, the associated configuration dialog contains the following parameters:

cleanup schedule task
Figure 18. Schedule action parameters
Use different site

Content cleanup uses a Commerce Cloud site to find the content assets and slot configurations to be deleted. The checkbox Use different site allows the use of content cleanup for a site other than the configured site.

Site Id

If the Use different site checkbox is active, the Commerce Cloud site to be used for content cleanup must be specified in this field.

Content asset cleanup  Enabled

This checkbox allows to enable/disable the content cleanup of assets.

Library Id

The ID of the Content Library from that Content Assets are deleted must be entered in this field. In the case of a private library, the library ID corresponds to the site ID.

Additional refinement(s)

In this field, attribute names and values can be specified for further filtering of the content assets to be deleted. The specification must have the following form:

ATTRIBUTE_NAME=ATTRIBUTE_VALUE [; ATTRIBUTE_NAME=ATTRIBUTE_VALUE] ...

The attribute values can contain the following parameters:

Parameter Replacement by

${projectId}

The ID of the generated FirstSpirit project

${projectName}

The name of the generated FirstSpirit project

The specified attributes must exist as custom attributes in the Commerce Cloud and have been filled with values via the FirstSpirit generation before the filtering described here can be used.
Slot configuration cleanup  Enabled

This checkbox allows the de-/activation of the content cleanup from Slot configurations.

Filter query

This field is used to filter the slot configurations to be deleted. A filter is specified as a query document in JSON format. Within the query, the parameters of the field Additional refinement(s) can be used, as the following example of a TextQuery illustrates:

"text_query": {
    "fields": ["c_fsProjectId"],
    "search_phrase": "${projectId}"
}

If the Filter query field remains empty, the ContentConnect module uses a MatchAllQuery, whereby the slot configurations to be deleted are not further filtered.

To avoid inconsistencies in the database or data loss, the action Salesforce Commerce Cloud Cleanup must be the last action of the schedule. For the same reason, content cleanup requires that this action only performs full generations. Furthermore, replication within the Commerce Cloud is not recommended during the execution of the cleanup.

Since the Salesforce Commerce Cloud Cleanup requires a successful execution of the job schedules and thus the import of the content, it must not be executed in the event of an error.

4.9. Workflows

Content is released, deleted, and published by editors within the supplied reference project ContentConnect Reference Project via workflows. For this reason, it contains a publish workflow, as well as the BasicWorkflows, which can be used as an alternative to project-specific workflows.

Installing the BasicWorkflows module

Before using the workflows, you must install the BasicWorkflows module on the FirstSpirit server and activate the web component. The necessary steps are the same as for installing the other modules and activating the associated web components. However, the web component for the BasicWorkflows is only needed on the ContentCreator tab page.

In addition, to use BasicWorkflows in the ContentCreator, the provided BasicWorkflows Status Provider must be selected in the Project properties  ContentCreator area within the ServerManager. In the reference project ContentConnect Reference Project, this setting has already been applied (see figure Element Status Provider).

statusprovider
Figure 19. Element Status Provider

In addition, in the Project properties  Options area, the Workflow for deleting elements is preselected. As a result, any action to delete elements within the project (Del button, delete icon) is executed via this workflow. The native (independent of a workflow) deletion of elements is therefore not available - not even for the administrator.

Templates

The BasicWorkflows and the workflow supplied with the StarterPackage require different templates. Usually, these need to be imported for the BasicWorkflows via the context menu in the FirstSpirit project used. However, they are already available in the reference project and importing the templates is therefore not necessary.

The publish workflow initiates the deployment schedule and requires its name for this. If this deviates from the Generate and deploy to SFCC expression, the value of the scheduleName variables must be adjusted accordingly within the script SFCC Release Deployment.

Permission assignment

In the final step, the workflows must be authorized in the individual stores so that they can be executed on FirstSpirit elements. To do this, select Extras  Change permissions from the context menu of the stores' root nodes to call up the permission assignment. This step has also already been carried out in the reference project and is therefore omitted.

The permissions for executing workflows set on the stores' root nodes relate to the Everyone group. This can only be changed by modifying the permissions manually.

You can find more detailed information in the BasicWorkflows Documentation.

4.10. Project settings

There is some essential project-specific information that needs to be entered for the connection between FirstSpirit and Commerce Cloud (see figure Project settings). It is entered using the project settings form and must be specified within the reference project.

Changes to the project settings do not take effect straight away, as they are saved in the session of the user. They require the client to be restarted.
p settings
Figure 20. Project settings
Storefront Base URL

The field is used to specify the storefront’s base URL, which is extended with the page type and the ID of the element to be displayed (e.g., product, category, or asset ID). It has the following format:

https://<SUBDOMAIN INSTANCE>/on/demandware.store/Sites-<SIDE ID>-Site

More information on the storefront base URL is available in the Commerce Cloud Documentation in the chapter Merchandising Your Site ➔ Search Engine Optimization ➔ URL Syntax ➔ Salesforce B2C Commerce URL Syntax Without SEO.

As a value of the storefront base URL, only up to the locale, not the entire URL must be entered in accordance with its specified format.

Example:
https://www.mystore.com/on/demandware.store/​Sites-YourShopHere-Site/
SFCC Content Asset ID Prefix

To uniquely identify the content assets generated by FirstSpirit, a prefix for the content asset ID is to be defined at this point.

Preview Protection (BasicAuth)

Within Commerce Cloud, it is possible to protect access to the storefront by activating the Online (protected) site status. If this restriction is applied, the storefront user must be specified in FirstSpirit. Activating the toggle displays the User and Password fields.

User

If access restriction is activated in Commerce Cloud, the storefront user must be specified in this field.

Password

The password belonging to the storefront user is specified in this field.

StarterPackage Version

This field is solely utilized to display the version of the used reference project.

Enable Custom Affixes

The toggle makes it possible to use individual affixes for the HTML comments included in the templates, which are used to indicate the content to be substituted for the preview. These have the format <!-- CMS-<IDENTIFIER>-START -→ or <!-- CMS-<IDENTIFIER>-END -→ by default. When the toggle is activated, all four affixes are overwritten and the default values are therefore no longer taken into account. The specific values can then be specified using the following fields. If one of the form fields is missing even though the toggle is activated, an empty string is used for the corresponding affix.

For the individual affixes, the format <!-- [OPENING_PREFIX]<IDENTIFIER>[OPENING_SUFFIX] -→ or <!-- [CLOSING_PREFIX]<IDENTIFIER>[CLOSING_SUFFIX] -→ applies.

Spaces that are entered in the configuration fields in front of or behind an individual affix are ignored.

If the toggle is activated without at least one affix defined, this can lead to unexpected behavior.

Within the reference project, all HTML comments have the standard format. For this reason, the template for the project settings does not include the toggle or the form fields for the use of individual affixes.
Opening Prefix/Opening Suffix

Together with the identifier, the opening prefix and the opening suffix form the start HTML comment and mark the beginning of the content to be substituted.

Closing Prefix/Closing Suffix

Together with the identifier, the closing prefix and the closing suffix form the end HTML comment and mark the end of the content to be substituted.

Storefront-URL Controller Form Field

To determine the storefront URL, the ContentConnect Preview Filter must know which controller (e.g., Home, Page or Search) it needs to address. This information generally depends on the page to be displayed, which is why the Preview Filter reads it out from an input component on the preview page form. The Preview Filter uses the pt_storefrontUrlController field by default. This behavior can be configured in the project settings using the ps_storefrontUrlControllerFormField field, in which the name of the form field to be read out is entered if required.

Within the reference project, all page templates have the pt_storefrontUrlController input component as standard. For this reason, the field for configuring its name is not included in the template for project settings.
Storefront-URL Context ID Form Field

In addition to the controller, the ContentConnect Preview Filter may in some cases require an ID (such as a product, category, or content asset ID); it also determines this on the basis of the page form. There is the option of configuring the corresponding form field in the project settings using the ps_storefrontUrlContextIdFormField field. The Preview Filter reads out the pt_storefrontUrlContextId component by default.

Within the reference project, all page templates have the pt_storefrontUrlContextId input component as standard. For this reason, the field for configuring its name is not included in the template for project settings.

Additionally, the template is used to initialize two XML collectors and a Product Manager, which are used in the other page and section templates of the project. These page and section templates define which data is to be transferred to Commerce Cloud. During the generation process, the data is collected on the basis of these definitions and the XML collectors are filled.

If there are project-specific requirements for the XML collectors, then these can be adapted using the methods from the XmlCollectorFactoryExecutable class. The information required for this is contained in the Javadoc for the class.

Information on calling up the Product Manager is contained in the Javadoc for the ManagerFactoryExecutable class.

5. Use cases

The ContentConnect module provides various options for accessing Commerce Cloud content and for using this in FirstSpirit. These functions are equivalent in both clients and are described in the following using the reference project ContentConnect Reference Project supplied in the form of use cases. The description of each use case is aimed at editors as well as FirstSpirit developers.

5.1. Preview

To display the preview of a page, the ContentConnect Preview Filter determines the necessary information on the Salesforce side. In the slot-based approach, it identifies the correct storefront URL for this purpose, downloads the HTML on the basis of this URL, and substitutes the slots it contains with the corresponding editorial content. The slots are uniquely labeled with HTML comments and are represented in FirstSpirit by the content areas of a page template. If the Content Integration API is being used, however, the Preview Filter has the Velocity fragments maintained in FirstSpirit evaluated on the Salesforce side, and displays the result at the corresponding point on the page.

Editor view
The editorial content is created and maintained in FirstSpirit. Editors have the standard tools available to them and do not require any additional knowledge. From the view of an editor, the content of both systems is automatically merged and displayed in the preview or in the ContentCreator.

Developer view
The pages within the reference project that is supplied are based on the slot-based approach as standard. However, as is the case in the example of the category detail page, it is also possible to use the CI API. The two approaches are fundamentally different from one another, and whichever one is being used is automatically taken into account by the ContentConnect Preview Filter when a preview is being generated.

Slot-based approach
Within the reference project supplied, the slots from Salesforce are represented by the content areas of the page templates. Sections can be added to them; each one corresponds to an asset and, depending on the use case, also has a slot configuration. To display a page in the preview, the slots contained in the downloaded HTML are substituted by the editorial content.

For the substitution, all content relevant for the preview must be labeled with unique HTML comments. From a technical point of view, these can occur in every template but are only included in page templates in the reference project. Each consists of a start as well as an end comment and has the format <!-- CMS-<IDENTIFIER>-START -→ or <!-- CMS-<IDENTIFIER>-END -→ by default.

The use of individual affixes can be activated for HTML comments via a toggle in the project settings, which must be added if necessary. In this case, the default values are overwritten and specific prefixes and suffixes are used instead.

These exact same HTML comments must also be inserted into the storefront page by the Salesforce developer, and the slots to be substituted must be indicated. It is important to make sure that the identifier in the FirstSpirit template and in the storefront page match. Otherwise, there is an error in the presentation of the preview.

Using the Content Integration API
The Content Integration API enables Velocity fragments to be evaluated on the Salesforce side. These fragments are maintained in the FirstSpirit templates and substituted when a page is displayed in the preview. For this purpose, the Preview Filter receives the results of the evaluation conducted on the Salesforce side and inserts them at the corresponding points on the page. The Velocity fragments must also be labeled with unique HTML comments to enable the Preview Filter to carry out this step. The comments consist of a start comment and an end comment, and must always use the following format: <!-- CMS-VELOCITY-<IDENTIFIER>-START -→ or <!-- CMS-VELOCITY-<IDENTIFIER>-END -→.

Substitutions with regular expressions
Should further substitutions be additionally required, specific regular expressions can be defined. These have their own syntax and always take the following form:

Syntax 
<!-- CMS-REGEX-PATTERN-START -->
   regex-match="<REGEX>"
   regex-value="<REPLACEMENT>"
<!-- CMS-REGEX-PATTERN-END -->

While the expression regex-match saves the regular expression, it is the expression regex-value that specifies the content, which will substitute all regex matches in the document. Both expressions are to be summarized as an instruction by the HTML comments <!-- CMS-REGEX-PATTERN-START -→ and <!-- CMS-REGEX-PATTERN-END -→.

With respect to the reference project, for example in the Preview Generation format template, this enables additional CSS to be integrated into each page template or any link on the Homepage to be substituted:

Format template 
$-- Set Bootstrap CSS--$
<!-- CMS-REGEX-PATTERN-START -->
   regex-match="<\/head>"
   regex-value="$CMS_IF(#global.is("PREVIEW"))$$CMS_RENDER(template: "preview_css_additions")$$CMS_END_IF$</head>"
<!-- CMS-REGEX-PATTERN-END -->

$-- Change Homepage Reference --$
<!-- CMS-REGEX-PATTERN-START -->
   regex-match="href=("|').*.home[?]"
   regex-value="href="$CMS_REF(pageref:"homepage")$""
<!-- CMS-REGEX-PATTERN-END -->

If a convert2 is used within the regular expressions applied, it is important to make sure that all special characters are correctly resolved. It may be necessary to adjust the conversion rule, in particular in conjunction with the dollar sign (ServerManager  Server properties  Conversion rules).

Please note that the replacement of the URL depends on the new storefront URL. The settings can be found under the menu item Merchant Tools  Site Preferences  Storefront URL.

ContentConnect Preview Language

The following pattern is needed to configure the display language in the ContentCreator:

Pattern 
$-- Set Preview Language --$
<!-- CMS-PARAM-PREVIEWLANG-START -->
        $CMS_VALUE(set_previewLang)$
<!-- CMS-PARAM-PREVIEWLANG-END -->

The format of the language abbreviation that is provided within the pattern is explained by the paragraph Determining the locale. If the Preview Filter cannot find this pattern it will use default as a value for the preview language.

ContentConnect preview proxy

If problems with cross-origin requests occur during the preview due to the same-origin policy of modern web servers, then these can be remedied by using the preview proxy included in the ContentConnect module.

In the supplied reference project, this is the case when loading the Font Awesome font via an integrated CSS file, for example. If the preview proxy is not used, a cross-origin request will be executed when the font is loaded, which will be blocked by the same-origin policy.

To manage the loading of the resources in question via the preview proxy and therefore avoid cross-origin requests, the Preview Generation format template includes the following regular expression. As a result, the configuration of the supplied web server does not need to be adapted.

If the preconfigured /proxy URL path is not to be used for the preview proxy, it must be adjusted in both the format template and in the web.xml. A more detailed description of the configuration options via the web.xml is given in the chapter Configuration of the web component.
Proxy integration 
$-- Redirect to proxy --$
<!-- CMS-REGEX-PATTERN-START -->
   regex-match="[^"'(]*?\/on\/demandware\.static\/"
   $CMS_IF(#global.is("WEBEDIT"))$
      regex-value="/fs5webedit_$CMS_VALUE(#global.project.id)$/proxy/on/demandware.static/"
   $CMS_ELSE$
      regex-value="/fs5preview_$CMS_VALUE(#global.project.id)$/proxy/on/demandware.static/"
   $CMS_END_IF$
<!-- CMS-REGEX-PATTERN-END -->

Troubleshooting

ContentConnect supports developers when analyzing problems and errors in the preview, such as erroneous substitutions or poor response times while generating a preview.

Developers can add special parameters to the URL of a preview page in order to influence how the Preview Filter works and receive useful information as a result. The available URL extensions are /debugTimings=true and /debugCCFilter=true.

/debugTimings=true instructs the Preview Filter to write the execution times of its processing steps as a comment at the end of the HTML document. For this purpose, the Preview Filter measures the duration of the following actions:

  • Search for content to be substituted

  • Substitution of slots with the current editorial content

  • Execution of particular substitutions via specific regular expressions

  • Complete processing of the page

If this parameter is specified, the Preview Filter generates the following output for the homepage of the reference project:

Output of the Preview Filter for the homepage with /debugTimings=true 
<!--
*** TIMING STATS ***

LANGUAGE-DROPDOWN = 0ms
&lt;script [^&lt;]*?/dwux-init.js.*?&lt;/script&gt; = 0ms
[^&quot;'(]*/s/SiteGenesisGlobal_MF_SP/[^&quot;')]* = 53ms
Scanning for content replacement blocks = 1ms
CUSTOM-NAVIGATION-LEFT = 0ms
[^&quot;'(]*?/on/demandware.static/ = 113ms
(&lt;!-- dw.+?--&gt;) = 1ms
&lt;iframe.*?id=&quot;DW-SFToolkit&quot;&gt;.*?&lt;/iframe&gt; = 1ms
LANGUAGE-DROPDOWN-MOBILE = 0ms
&lt;a.*?sid=&quot;([^&quot;]*?)&quot; = 1ms
&lt;/head&gt; = 0ms
WILL-IGNORE-FOR-PREVIEW = 0ms
HOME-CATEGORIES = 0ms
href=(&quot;|').*.home[?] = 1ms
&lt;!-- Demandware Analytics(([sS]*)&lt;/script&gt;) = 1ms
&lt;!-- Demandware Active Data (([sS]*)&lt;/script&gt;) = 0ms
HOME-MAIN = 0ms
HOME-CC-OVERRIDE = 0ms

Total time = 172ms

-->

In addition, the Preview Filter logs some information in the FirstSpirit Server log if the /debugTimings=true parameter is specified.

/debugCCFilter=true means that the Preview Filter does not download the storefront, perform substitutions or present the result in the preview. The page actually generated by FirstSpirit is shown in the preview instead. The HTML therefore contains the substitution comments and specifications in addition to the editorial content. If this parameter is specified, the Preview Filter therefore generates the following output (in a shortened form) for the homepage of the reference project:

Output of the Preview Filter for the homepage with /debugCCFilter=true 
<!-- CMS-HOME-MAIN-START -->
    [...]
<!-- CMS-HOME-MAIN-END -->

<!-- CMS-HOME-CATEGORIES-START -->
    [...]
<!-- CMS-HOME-CATEGORIES-END -->

[...]

<!-- CMS-REGEX-PATTERN-START -->
    regex-match="href=("|').*.home[?]"
    regex-value="href="/fs5webedit_90169/s=qgkM/preview/90169/site/EN_GB/current/90172/90361""
<!-- CMS-REGEX-PATTERN-END -->

[...]

Using these functions requires a preview page to be called up. The address of the preview page must have one of the parameters presented here added to it. There are various ways of doing this:

  1. Via the iFrame address in the ContentCreator

  2. Via the address of a page in the external preview

  3. Via generated links in the FirstSpirit preview, as shown here using the example of links on the homepage:

<!-- CMS-REGEX-PATTERN-START -->
    regex-match="href=("|').*.home[?]"
    regex-value="href="$CMS_REF(pageref:"homepage")$/debugCCFilter=true""
<!-- CMS-REGEX-PATTERN-END -->

Due to their functions, the /debugTimings=true and /debugCCFilter=true parameters cannot be used in combination with one another.

5.2. Generation

In order to deploy editorial content, FirstSpirit generates two XML files, which contain content assets and slot configurations, and are transferred to the Commerce Cloud. The corresponding generation and deployment schedule has already been described. This description also explains that templates in their presentation channels populate XML collectors with content (content assets) and slot configurations. These collectors are initialized in the project settings. All content and configurations to be deployed must be written to the XML collectors. Otherwise, they will not be transferred.

One asset and one slot configuration are typically generated for each section, allowing for personalization at the section level. Content pages are the only exception. In this case, a total of precisely one content asset and one slot configuration are created.

This chapter explains how the content and configurations of the project are collected and the XML files generated.

5.2.1. Content Assets

Populating the XML collector for content assets involves the following steps:

Generating a content asset ID using a project-wide convention

In the reference project, the ID of a content asset is comprised of a project-wide prefix, the ID of the generated page reference, and the section ID. These components are separated from one another by means of a hyphen and any underscores are substituted with hyphens.

In case of a content page the content asset ID simply consists of the prefix and the ID of the generated page reference.

 
$CMS_SET(set_xml_id, ps_dwAssetIdPrefix + "-" + #global.node.uid + "-" + #global.section.id)$
$CMS_SET(set_xml_id, set_xml_id.replaceAll("_","-"))$

Creating a new content asset in the XML collector

Once the ID has been determined, a new content asset is created in the XML collector using the useOrCreateContentNode method. This asset must be populated with the content of all generated languages during the full generation. For this reason, useOrCreateContentNode only generates a new asset if no asset with the specified ID already exists. All subsequent method calls on the XML collector then operate on this asset.

$CMS_SET(void, ps_xmlCollector.useOrCreateContentNode(set_xml_id))$

When a new content asset is created, the fsGenerationTime custom attribute is automatically added along with the current time stamp of the generation. This is necessary to ensure that the content cleanup only deletes obsolete content assets from the Commerce Cloud after deployment.

The value of this attribute must not be changed manually following this.

Determining the locale

Some of the following actions require a locale to be specified for the Commerce Cloud. For this purpose, the language_mapping format template maps a FirstSpirit language onto a locale of this kind, and is therefore included in each page. In the template, two variables are generated in the context of the page: set_previewLang and set_xml_lang. The first of these is used for generating the preview and has the format <language_COUNTRY>. An example of a potential value is fr_FR. The Homepage chapter also describes this aspect of the template in greater detail.

The set_xml_lang variable is used during the process of populating the content assets. Its value for the master language is x-default. In all other cases, it assumes the value of set_previewLang, but substitutes the underscore with a hyphen.

Since both variables are set in the context of the generated page, they are available in all sections of the page and can therefore be used both for generating the preview and for populating the XML collectors.

Setting the display-name property

For each language, the display name of the generated page reference corresponds to the display name of the associated content asset, which is set during generation by means of the addContentAttribute method. The set_xml_lang variable described above is required for this.

$CMS_SET(void, ps_xmlCollector.addContentAttribute({
    "name":"display-name",
    "value":#global.node.getDisplayName(#global.language).toString(),
    "attributes":{
        "xml:lang":set_xml_lang
    }
}))$

Setting the searchable-flag property to true

The content asset needs to be included in the search index of the Commerce Cloud, which is why the searchable-flag attribute is set to true.

$CMS_SET(void, ps_xmlCollector.addContentAttribute({
    "name":"searchable-flag",
    "value":"true"
}))$

Setting the online-flag property to true

The asset also needs to be available in the shop, which is why the online-flag attribute is also set to true.

$CMS_SET(void, ps_xmlCollector.addContentAttribute({
    "name":"online-flag",
    "value":"true"
}))$

Setting the body property

The editorial content from FirstSpirit is saved in the body custom attribute. The set_xml_body variable is first created in the reference project, and the rendered content is then stored in this variable. The variable is then transferred to the XML collector. The collector automatically embeds the content in a CDATA section, which means that no special preparation is required. Since the content is language-dependent, the locale in set_xml_lang is used in this step too.

$CMS_SET(void, ps_xmlCollector.addCustomAttribute({
    "id":"body",
    "cdata":set_xml_body.toString(),
    "attributes":{
        "xml:lang":set_xml_lang
    }
}))$

Folder

The Commerce Cloud makes it possible to specify a library folder in which it is to store a content asset. For this purpose, the XML collector provides the addFolderAttribute method, which receives the ID of this kind of folder. In the reference project, the folder containing all the content assets for a page is stored in the form for the page itself. Each page template transfers the value of the corresponding form field to the set_parent_id variable. The sections then use this variable to generate their assets.

$CMS_SET(void, ps_xmlCollector.addFolderAttribute({
    "id":set_parent_id
}))$

Folders that are referenced in this way must be identified to the Commerce Cloud by means of corresponding nodes in the generated XML file. This allows the Commerce Cloud to create any missing folders. The XML template takes responsibility for this task, and generates a defined set of folders.

Unless any additional measures are taken, only the IDs of these folders can be reliably used in the reference project when generating content assets. This is because FirstSpirit is only able to guarantee that precisely these folders exist. In the reference project, the corresponding form elements are therefore hidden in the page templates and assigned fallback values.

5.2.2. Slot configurations

The XML collector for slot configurations is populated in the Slot Configuration link template. Therefore, both pages as well as sections output the corresponding form elements directly via $CMS_VALUE$ calls:

$CMS_IF(!st_slotConfig.isEmpty)$
    $CMS_FOR(_slotConfig,st_slotConfig)$
        $CMS_VALUE(_slotConfig)$
    $CMS_END_FOR$
$CMS_END_IF$

The XML for slot configurations is manually assembled in the Slot Configuration template and written to the appropriate collector using the addXml method:

$CMS_SET(void, ps_xmlCollectorContentSlot.addXml(null, set_slotConfig.toString(), null))$

As with the process of creating the content asset, the fsGenerationTime custom attribute is automatically added to a slot configuration along with the current time stamp of the generation. This is necessary to ensure that the content cleanup only deletes obsolete slot configurations from the Commerce Cloud after the deployment.

The value of this attribute must not be changed manually following this.

5.2.3. Generating the XML files

Both generated XML files are based on the XML page template, which reads out the collected content and slot configurations from the XML collectors. For this purpose, the deployment schedule performs three generations:

  1. A full generation for populating the XML collectors,

  2. a partial generation for writing the content assets to an XML file, and

  3. a partial generation for writing the slot configurations to an XML file.

The full generation must be completed before FirstSpirit can generate the XML files, which is why this step cancels the generation of the XML template. This is done using the dwre_xmlGeneration schedule variable, which has the value false in the full generation and the value true in both partial generations.

Since both files are based on the same template, a feature is necessary in order to determine which XML collector is read out. This feature is the ps_importType form field, which can assume the content_library and content_slot values.

In the case of content_library, a defined set of library folders is first written to the XML collector for content assets. The getXml method is then executed on this collector and the result - an XML document - is output via a $CMS_VALUE$ call. If ps_importType has the value content_slot, getXml is called up on the collector for slot configurations instead and the result is also output.

The ContentConnect Technical Pages content folder contains two pages that are based on the XML template: Shop Assets, for which ps_importType has the value content_library, and Shop Slot Configurations, for which this form field is set to content_slot. These pages form the basis of the Shop Assets and Shop Slot Configurations page references in the ContentConnect Export Files structure folder; a partial generation is executed for each of these page references.

The storefront’s main navigation function can be used in FirstSpirit to navigate both the shop and the content maintained on the FirstSpirit side. Custom entries can also be added.

The main menu is primarily used to navigate between the various category pages within the preview (see figure Navigation). The main menu is part of the HTML downloaded during the preview from the Commerce Cloud Storefront and is therefore predefined by Commerce Cloud.

Editor view
The main menu allows the editor to switch between category pages. If an equivalent exists within FirstSpirit for a category page that has been called up, then the content of this page is shown. The editor is then able to edit the content originating from FirstSpirit. If no equivalent to the category page that has been called up exists within FirstSpirit, the original content obtained from Commerce Cloud is issued instead.

Developer view
To display a category page that exists in FirstSpirit to the editor, the links on the category pages are redirected to a dispatcher page via a specific regular expression initially in the reference project.

Redirecting the navigation links 
$-- Change Category Reference --$
<!-- CMS-REGEX-PATTERN-START -->
   regex-match="<a.*?\sdata-cgid="([^"]*?)""
   regex-value="<a href="$CMS_REF(pageref:"preview_dispatcher")$/forceRefresh=1?type=category&id=$1" id="$1""
<!-- CMS-REGEX-PATTERN-END -->

This regular expression, along with other specific regular expressions, forms part of the Preview Generation format template.

The Preview Dispatcher referenced in this expression is a technical page based on the page template with the same name. The Preview Dispatcher iterates over the content of the structure folder category_pages by using the FirstSpirit navigation function.

This structure folder corresponds to the folder that you configured as the target folder for creating new category pages when configuring the project component.

For each page found, the Preview Dispatcher memorizes the associated category, together with a corresponding reference to the page. As a result, for each call it can then decide whether a page exists in FirstSpirit for the requested category and forward accordingly.

If it was not possible to identify any pages created in FirstSpirit for a requested category, you are forwarded to a generic category preview page.

5.3.2. Expanding the navigation function

Editors can expand the main navigation function. New menu items are placed in front of those that already exist.

Editor view
To add a navigation item, simply place a content page below the Left Navigation menu item. Once the page has been released and transferred to the Commerce Cloud, the new navigation item will appear in the storefront. As shown in the Example of expanding the main navigation function figure, it is also possible to create nested menu structures.

custom navigation
Figure 22. Example of expanding the main navigation function

Menu structures may be nested up to a maximum of 4 levels deep.

Developer view
The new menu-custom-left global slot has been introduced on the Salesforce side using the menu.isml template supplied, and is surrounded by the following comments: <!-- CMS-CUSTOM-NAVIGATION-LEFT-START -→ and <!-- CMS-CUSTOM-NAVIGATION-LEFT-END -→. This slot can be populated by FirstSpirit in the same way as any other slot and substituted in the preview. A content asset for this slot contains the HTML for all elements that are to be used for expanding the navigation function.

This markup is created in FirstSpirit in the custom_navigation format template. This template contains a navigation function that searches all page references in the Left Navigation folder. It then generates the required HTML for all the pages found - both for the preview and for the live state. This is necessary so that the pages can be integrated into the main navigation function. For the preview, the result is also enclosed within the following HTML comments: <!-- CMS-CUSTOM-NAVIGATION-LEFT-START -→ and <!-- CMS-CUSTOM-NAVIGATION-LEFT-END -→. The template outputs the HTML for the navigation function in both cases.

To enable this navigation function to be used in the preview, each page template must integrate the custom_navigation format template by calling up the CMS_RENDER function.

The Left Navigation page template, plus a page and a page reference based on this template, are provided for the purpose of generating a content asset. The page reference is stored in the Left Navigation structure folder. As described above, the page template integrates the custom_navigation format template and saves the generated content in a content asset via the XML collector.

Unlike the other page templates, Left Navigation does not provide any sections. A slot configuration that will be output in the event of a generation must therefore be maintained in its form. For this purpose, the page template sets two variables prior to output. The first of these is a contentSlotId, since there is no content area from that a slot ID could be derived. The value of these variable is menu-custom-left, since the new slot referred to above is to be populated. The second variable is contentSlotTemplate, which is set to the value of the pt_sfccTemplate form field. The fallback value of this field is slots/content/contentAssetBody.isml. Without this variable, the template for slot configurations would attempt to derive the ISML template from the current section.

The Left Navigation page reference as well as the corresponding page must be manually released once.

5.4. Homepage

The homepage corresponds to the start page of the reference project supplied and is therefore displayed when the ContentCreator is first opened. Since its structure differs from that of the other content pages, it has its own template. This is referenced in the project just once.

Editor view
The homepage offers the editor three options for entering content:

  1. The header of the page displays a banner in which either a static image or a slider can be integrated.

  2. In the main area of the page:

    • Up to five products can be displayed in the form of a grid container, which provides seven different options for arranging the products.

    • Any number of products can be linked in the form of hot spots on a static image.

The sections required for entering content are covered in more detail in the corresponding sub-chapters.

Developer view
The homepage template primarily defines how the page is displayed in the FirstSpirit preview, whereas assets are predominantly generated in the integrated sections. However, certain requirements for generation are managed in the form as well as in the HTML channel. The developer view must therefore take both aspects into account.

Preview
Commerce Cloud supports a range of page types. In order to display editorial content in the FirstSpirit preview or in ContentCreator, FirstSpirit must generate the correct storefront URL to query the corresponding page in Commerce Cloud.

The page type to be used for the FirstSpirit preview is defined in the Preview Page Type form field. As Home is the only parameter provided for the homepage, it is selected as a default value and the input component is hidden.

To determine the desired storefront URL, it must also be ensured that the language codes used in FirstSpirit and in Commerce Cloud match. This task is performed by the language_mapping format template, which is integrated in the HTML channel. If the language codes do not match, FirstSpirit is unable to determine the corresponding page for the preview.

The sections maintained for the homepage are output within unique HTML comments. These always consist of a start and an end expression and denote the individual content areas. Based on the comments, FirstSpirit substitutes the slots in the preview with editorial content.

<!-- CMS-HOME-MAIN-START -->
   $CMS_RENDER(template:"mpp_body_wrapper",body:"home_main_m")$
   $CMS_RENDER(template:"empty_content_slot",label:"Home Main",body:"home_main")$
<!-- CMS-HOME-MAIN-END -->

<!-- CMS-HOME-CATEGORIES-START -->
   $CMS_RENDER(template:"mpp_body_wrapper",body:"home_categories_m")$
   $CMS_RENDER(template:"empty_content_slot",label:"Home Categories",body:"home_categories")$
<!-- CMS-HOME-CATEGORIES-END -->

<!-- CMS-HOME-CC-OVERRIDE-START -->
   $CMS_RENDER(template: "cc_createsectionwe_api")$
<!-- CMS-HOME-CC-OVERRIDE-END -->

If a content area has no sections, FirstSpirit displays a gray-shaded area in the preview instead (see figure Empty Slot). This shows the name of the content area and has a button that allows new sections to be generated in ContentCreator. The display of the gray area controls the empty_content_slot format template, while the function of the button is implemented in the cc_createsectionwe_api format template. It contains JavaScript, which may be integrated in the page only once.

empty slot hp
Figure 23. Empty Slot

Should further substitutions be required in addition to the exchange of slots, specific regular expressions can be defined. These have their own syntax and are summarized in the Preview Generation format template. It controls the generation of the preview and is referenced in all page templates of the reference project.

Generation
The assets created during the generation are filed in a folder structure in Salesforce. A corresponding folder is therefore defined for each page template in the reference project. The homepage form has the hidden SFCC Parent Folder field, whose value is assigned to the set_parent_id variable. It is evaluated in the integrated sections.

$CMS_SET(set_parent_id,pt_sfcc_parentFolder)$

A further requirement for generating assets is that the corresponding page must be marked as translated in FirstSpirit. If this is not the case, the generation is canceled.

$CMS_IF(!#global.preview && !#global.page.isTranslated)$
   $CMS_SET(#global.stopGenerate, true)$
$CMS_END_IF$

5.5. Content pages

The content pages correspond to the standard pages of the project and are referenced multiple times. Unlike the homepage and the category and product pages, they play a special role as they generate just one asset for the entire page. All editorial content from the content page and the sections added to it are summarized in this asset.

Editor view
The content pages offer the editor three options for entering content:

  • The header of the page displays a banner in which either a static image or a slider can be integrated.

  • The main area of the page enables the display of:

    • hot spots

    • a single blog article or an overview of all blog articles

    • a video

    • a text with a heading

The sections required for entering content are covered in more detail in the corresponding sub-chapters. As the text section is self-explanatory, this is not described specifically.

Developer view
Unlike for the remaining pages, the editorial content of the content page and its sections are summarized in a single asset. This asset is created in the HTML channel of the page template, which differentiates between the display of the page in the FirstSpirit preview and in the live state. The developer view must therefore take both aspects into account.

Preview

As the creation of the asset only affects generation, both developer views of the content page and the homepage are nearly identical with regard to the FirstSpirit preview.

The only discrepancy between both templates is in the configuration of the page type that is used, which is also defined in the hidden Preview Page Type form field for the content pages. In contrast to the homepage, it can assume different values in theory. For the reference project supplied, however, the Page parameter is required and is selected as the default value.

Furthermore, the content page has the hidden SFCC Context ID form field, in which a default content asset ID is saved. As a page still does not have an asset ID before generation, it is required to create the preview.

Generation

For generation, it is important to ensure firstly that the corresponding page is marked as translated in FirstSpirit. Only when this is the case is generation carried out and the asset for the content page is created.

$CMS_IF(!#global.preview && !#global.page.isTranslated)$
   $CMS_SET(#global.stopGenerate, true)$
$CMS_END_IF$

For this, the value of the hidden SFCC Parent Folder field is assigned to the set_parent_id variable initially. This value specifies where the created asset is filed in the Salesforce folder structure.

$CMS_SET(set_parent_id,pt_sfcc_parentFolder)$

The variables are evaluated while the XML collector is populated, which is carried out subsequently. In the process, a new content node is created, to which the editorial content of the page, among other things, is added.

5.6. Login page

Just like the homepage, the login page has a special role to play. This means that it differs from the other content pages. It is used to log into the shop and is only referenced once in the project.

Editor view
The login page offers the editor various options for entering content:

Developer view
As both the form and the content of the HTML channel for the login page and the homepage broadly match, both developer views are also nearly identical. Therefore, only the differences between the two templates will be described here.

The page type to be used for the FirstSpirit preview is also defined for the login pages in the hidden Preview Page Type form field. Just as for category and product detail pages, the Custom value is required in this context. It is used for the implementation of page types that are not covered by default by the Preview Filter as well as for the manual specification of the controller to be used. The controller must be specified using the hidden pt_storefrontUrlCustomController field. For login pages, its default value is Login-Show, which is added to the Storefront URL.

For generation, as is the case with the homepage, it is important to ensure that the login page is marked as translated in FirstSpirit. Only then the generation is carried out and the associated assets will be created.

5.7. Category and product pages

The ContentConnect module provides an individual report for products and categories in both SiteArchitect and ContentCreator. These reports are used to display the category and product information originating from Commerce Cloud, which can be used to create and maintain editorial content (see figure Reports).

To display the category report, the Show Category Report checkbox must be activated in the project component.
reports
Figure 24. Reports

The corresponding report can be used to create both category pages as well as product pages. To use this feature, you must define the templates on which these pages will be based, and where they are to be integrated into the structure, in the project component.

The SFCC Context ID field must be included in the page template that is selected in each case so that the ID of the referenced object can be saved. The field can be hidden. If this field ought to have a differing identifier for project-specific reasons, then this must be specified within the project settings.

<CMS_INPUT_TEXT name="pt_storefrontUrlContextId" hidden="yes" useLanguages="no">
  <LANGINFOS>
    <LANGINFO lang="*" label="SFCC Context ID"/>
  </LANGINFOS>
</CMS_INPUT_TEXT>

With regard to its category or product page, an object in the report can adopt one of three states:

  1. A category or product page does not exist and therefore can be created.

  2. A category or product page exists, which can be called up.

  3. A category or product page exists but either its page reference or the page cannot be found.

The three cases are displayed in different ways and described below.

Since the objects in the report are not permanently updated, the display might not reflect the current status.

Creating a category or product page
Objects for that a category or product page does not yet exist are identified in the report by a gray icon (see figure Creating a category or product page). If a page template has been defined in the project component, the Create Page button is displayed when such an object is hovered over.

report create normal
Figure 25. Creating a category or product page

A button is also displayed in the FirstSpirit preview on category landing pages, category detail pages, and product detail pages that can be accessed via the navigation. This button functions in the same way as the button in the report. It is only visible if a corresponding category landing page, category detail page, or product detail page does not exist in the FirstSpirit project.

landingpagebutton
Figure 26. Creating a category landing page, category detail page, or product detail page

Click on the button in the report or the button on a main category page to open a dialog that is split into two sections and in which a page can be created for the corresponding object.

The top section of the dialog is the structure selection area; it is completed automatically and as such is always the same. Within the structure, the editor has the option to select the menu level at which to generate the new page. The corresponding input component may already have been preassigned. In this case, a structure folder will already have been defined in the configuration dialog of the project component. However, the editor is free to change this selection.

In some cases, the structure selection area may be hidden in the dialog. In this case, a structure folder will also have been predefined in the project component. At the same time, however, a setting will have been made to prevent the editor from changing this preassignment.

Unlike the structure selection area, the form area underneath is always project-specific. It shows the form for the page template specified in the project component. The rules defined in the template also apply here.

Within the reference project, the form fields of the category or product pages are automatically populated or have corresponding default values. In addition, a structure folder is predefined in the project component, which cannot be changed by the editor. Both for the structure selection area and the form area, there is therefore no need for the editor to input anything. The dialog is not shown for this reason.

An example dialog is shown in the figure below:

report dialog newpage
Figure 27. Dialog for creating a category or product page

Click on Create to generate the page reference for the category or product page at the selected menu level. The corresponding page is created in a specific folder in the Page Store. Within this folder, a distinction between category and product pages is made once again on the basis of subfolders. The names of the page references and pages generated are based on the product ID (product name) or category ID (category name) schema.

If a script has also been specified in the project component, it is usually executed before and after the category or product page is created. The create_sfcc_item_wizard script included in the reference project supplied does, however, have a corresponding query, which is used to initiate the script, but only once the page has been created. It marks each created category or product page as translated for all languages and saves its storefront ID in the form.

Please note that only the code from the HTML channel of the script is executed.

The following parameters are transferred to this script:

Data type Object name Description

BaseContext

context

The context in which the script is executed.

boolean

beforeInstantiation

true if the script is executed before the page is created; otherwise false.

KeyProvider

keyProvider

The object for that a category or product page is being created. This is either a product or a category.

The Javadoc documentation supplied describes the KeyProvider, Product, and Category interfaces.

Once the process to generate the category or product page and the execution of the script have been completed, the new page is called up automatically.

Calling up an existing category or product page
Objects for that a category or product page already exists are identified in the report by a green icon (see figure Product with product page). When you hover over them, the report jump icon button is displayed. Click this button to call up the corresponding category or product page.

report jump to
Figure 28. Product with product page

Broken reference to a category or product page
If there are objects with a category or product page but the page reference or underlying page cannot be found, the objects are identified in the report by a red icon (see figure Broken object). When you hover over them, the Broken Reference button is displayed. Click on this button to open a dialog containing more information.

report ref broken
Figure 29. Broken object

Hidden categories
When the category report is called up, both visible as well as hidden categories are displayed by default. By removing the Include hidden categories check mark, the results list can be limited to include only visible categories:

category report hidden excluded
Figure 30. Hiding hidden categories

The identification of existing, broken, and unavailable references to category pages described in this chapter applies also to hidden categories.

5.7.1. Category landing pages

Category landing pages are used to display the products originating from Commerce Cloud. They provide an overview of all the products belonging to a selected main category. The products are arranged and the product information is displayed automatically; this cannot be influenced by the FirstSpirit editor.

Editor view
The category landing page offers the editor different options for entering content:

  • The header of the page displays a banner into which a static image can be integrated.

  • The main area has two content areas, in which:

may be used.

Developer view
As both the form and the content of the HTML channel for the category landing page and the homepage broadly match, both developer views are also nearly identical. This is therefore where only the discrepancy between both templates is described:

The page type to be used for the FirstSpirit preview is also defined for the category landing pages in the hidden Preview Page Type form field. In contrast to the homepage, it can assume different values in theory. For the reference project supplied, however, only the Search parameter is required and is selected as the default value.

Furthermore, the form has the SFCC Context ID field. The SFCC Context ID corresponds to the category ID from the storefront. If the field is empty, a category landing page maintained in the FirstSpirit project does not exist and the preview shows the corresponding Storefront page. A button to create a category landing page is added to the Storefront page via the Create Page template. This button functions in the same way as the button in the report. When generating a category landing page, the category ID is automatically saved to the associated form field.

The Preview Generation format template needs the category ID to generate the preview for all pages. For each page, it expects to receive the category ID in the form of the SFCC Context ID variable. This ID must therefore be included in every page template, with the exception of the homepage. If the associated form field is empty or the corresponding page in FirstSpirit is not marked as translated, generation is canceled.

$CMS_IF(!#global.preview && !#global.page.isTranslated || pt_storefrontUrlContextId.isEmpty)$
   $CMS_SET(#global.stopGenerate, true)$
$CMS_END_IF$

As described above, the form for the category landing pages does not contain any elements to be completed by the editor. No dialog is therefore shown when a page of this nature is created. If a form only contains elements for that the attribute hidden has the value yes, the ContentConnect module decides for itself that the form does not need to be shown. In the reference project, the form for the category landing pages does, however, contain an FS_BUTTON, which is only hidden dynamically in ContentCreator by means of a rule. In both clients, this button should not result in the dialog being shown when a category landing page is created. For this reason, the following elements were added to the form:

Form 
<CMS_INPUT_TOGGLE name="pt_hideNewPageDialogCC" hFill="yes" hidden="yes" singleLine="no">
  <LANGINFOS>
    <LANGINFO
      lang="*"
      label="Hide New Page Dialog in ContentCreator"
      description="Hide the dialog in the ContentCreator when creating a new landing page."
    />
  </LANGINFOS>
</CMS_INPUT_TOGGLE>

<CMS_INPUT_TOGGLE name="pt_hideNewPageDialogSA" hFill="yes" hidden="yes" singleLine="no">
  <LANGINFOS>
    <LANGINFO
      lang="*"
      label="Hide New Page Dialog in SiteArchitect"
      description="Hide the dialog in the SiteArchitect when creating a new landing page."
    />
  </LANGINFOS>
</CMS_INPUT_TOGGLE>

These explicitly instruct the ContentConnect module not to show the dialog in ContentCreator or in SiteArchitect. Their fallback values are therefore true.

5.7.2. Category detail pages

As with the category landing pages, the category detail pages are used to display the products originating from Commerce Cloud. However, unlike the category landing pages, they provide an overview of all products belonging to a subcategory. The products are arranged and the product information displayed automatically and cannot be influenced by the FirstSpirit editor.

Editor view
The category detail page only allows an editor to integrate a static image into the header of the page. Furthermore, the editor is unable to maintain content.

Developer view
Unlike the other pages, which follow the slot-based approach, both product and category detail pages use the Content Integration API (CI API). This API enables Velocity fragments that are maintained in the FirstSpirit template to be evaluated on the Salesforce side.

If the CI API is being used, the hidden Use velocity rendering toggle is activated in the form of the page template within the reference project, and the Custom parameter is defined in the Preview Page Type form field. The Content-Render value is also entered in the Velocity rendering controller appendix form field. This value defines the call of the Content controller that is supplied in the int_espirit_sfra cartridge and carries out Velocity rendering on the Salesforce side. The value must be adapted accordingly if an external controller is being used.

The chapter about the login page describes in more detail how an individual page type can be defined.

Another difference compared to the other pages is that the category detail pages only generate a single asset, just like the content pages. This asset is created in the HTML channel of the page template, which differentiates between the display of the page in the FirstSpirit preview and in the live state. The developer view must therefore take both the preview as well as the generation and the live state into account.

Preview

The Velocity fragments can be used to insert Salesforce widgets provided by the Common controller in a page. The $include.widget() function, which is defined in the Content controller, deals with the integration process. The required widget must be transferred to this function as a parameter.

The code example below shows the integration of the Salesforce Page Header in the category detail page:

Page Header integration 
<!-- CMS-VELOCITY-PAGE_HEADER-START -->
   $include.widget('Common-PageHeader')
<!-- CMS-VELOCITY-PAGE_HEADER-END -->

In addition to the general widgets, the CategorySearchResult controller integrates specific data into the category detail page: In the case of the preview, for example, it uses the category ID of the selected subcategory to determine the corresponding products, and then displays these in the preview. This data is already provided in the live state and is available to use via the $categorySearchResult variable.

Integrating subcategory products 
<!-- CMS-VELOCITY-SEARCH_RESULT-START -->
   $CMS_IF(#global.preview)$
      $include.widget('CategorySearchResult-Show', 'cgid', '$CMS_VALUE(pt_storefrontUrlContextId)$')
   $CMS_ELSE$
      $categorySearchResult
   $CMS_END_IF$
   [...]
<!-- CMS-VELOCITY-SEARCH_RESULT-END -->

Generation

For generation purposes, it is important to ensure firstly that the corresponding page is marked as translated in FirstSpirit and that the SFCC Context ID field is populated. The SFCC Context ID corresponds to the category ID from the storefront. When a category detail page is being generated via the report, the ID is automatically saved to the associated form field. The generation is only carried out and the asset for the category detail page is only created once the form field is populated and the corresponding page is marked as translated in FirstSpirit.

$CMS_IF(!#global.preview && !#global.page.isTranslated || pt_storefrontUrlContextId.isEmpty)$
   $CMS_SET(#global.stopGenerate, true)$
$CMS_END_IF$

The editorial content is then saved in the set_pageContent variable, and the set_parent_id variable is assigned the value of the hidden SFCC Parent Folder field. This value specifies where the created asset is filed in the Salesforce folder structure.

$CMS_SET(set_parent_id,pt_dwre_parentFolder)$

Both variables are evaluated while the XML collector is populated, a process that is carried out subsequently. In the process, a new content node is created, to which the editorial content of the page, among other things, is added.

Live state

A category detail page already exists for subcategories on the Salesforce side as standard. This page is used for the live state. The display is controlled by the Search controller, which has been expanded to take account of assets generated on the FirstSpirit side. Using this expansion and a category ID assigned to it, the controller first checks whether a category detail page that has been generated with FirstSpirit is present. If one is present, it is rendered in the live state with the Velocity engine. Otherwise, the Salesforce standard page is displayed.

5.7.3. Product detail pages

Like category detail pages, product pages are used to display products originating from Commerce Cloud. However, unlike category detail pages, they do not display an overview of multiple products. Instead, they provide a detail view of a single product. The product information originates from Commerce Cloud and cannot be edited by the FirstSpirit editor. However, the editor can choose to show and hide this information.

Editor view
Product detail pages offer the editor various options for entering content:

  • The page form contains various input components

    • to define a promotional text. This text can contain a maximum of 1,024 characters.

    • to show/hide product information.

  • The header of the page displays a banner into which a static image can be integrated.

  • The main area of the page enables the display of:

The sections required for entering content are covered in more detail in the corresponding sub-chapters. As the text section is self-explanatory, this is not described specifically.

Developer view
Just like category detail pages, product detail pages use the Content Integration API (CI API). This API enables Velocity fragments to be evaluated on the Salesforce side. Moreover, product detail pages only generate a single asset. This asset is generated in the HTML channel of the page template.

As both the form and the content of the HTML channel for product and category detail pages broadly match, both developer views are also identical in terms of form and content. Therefore, only the differences between the two templates will be described here.

The Salesforce widgets of a product detail page are made available via the Product controller and integrated into the page using Velocity fragments. Here too, the $include.widget() function of the Content controller is used for integration purposes (the function transfers the required widget as a parameter).

The hidden input components necessary to use the CI API include, for example, the Velocity rendering controller appendix field. Since product detail pages, like the login page, use an individual controller to generate the preview, this must be specified here. Therefore, the field contains the Content-Render value, to which a reference to the SFCC Context ID field is added. This corresponds to the ID of the product to be displayed and is required by the controller. The Preview Filter reads out this value and adds it in the corresponding location.

Default value for the Velocity rendering controller appendix form field 
Content-Render?pid={pt_storefrontUrlContextId}

As well as the hidden input components, the form also contains a text field for the entry of a promotional text and various CMS_INPUT_TOGGLEs. The toggles offer the editor the option to show or hide the widgets on the product detail page individually:

Integration with CMS_INPUT_TOGGLE 
$CMS_IF(!pt_hideProductInfo)$
   <!-- CMS-VELOCITY-PRODUCT_INFO-START -->
   $include.widget('Product-WrapProductTemplate','pid',$product.id,
                   'productTemplate','product/components/productInfo')
   <!-- CMS-VELOCITY-PRODUCT_INFO-END -->
$CMS_END_IF$

For generation purposes, it is important to ensure that product detail pages are also marked as translated and that the SFCC Context ID field is populated. In this case, the SFCC Context ID corresponds to the product ID from Storefront. If no product detail page maintained in the FirstSpirit project exists, the preview shows the corresponding Storefront page. The Storefront page display is based on the Product Detail Page Preview page template. A button to create a product detail page is added to the Storefront page via the Create Page template. This button functions in the same way as the button in the report. When creating a product detail page, the Product Detail Page page template is then used and the product ID is automatically saved to the associated form field. If the page is marked as translated and the SFCC Context ID field is populated, generation is carried out and the asset for the product detail page is created.

As well as providing the widgets, the Product controller also controls how the product detail page is displayed when the website is live. It uses the product ID to check whether a product detail page that has been generated with FirstSpirit exists. If it does, it is rendered in the live state with the Velocity engine. If it does not, a product detail page that already exists by default on the Salesforce side is displayed.

The header of a page allows a banner to be displayed in which either a static image or a slider can be integrated. Both variants each correspond to a section, which is available for the homepage and for normal content pages, as well as in articles and for category and product pages.

These are described in detail in the following sub-chapters.

slider
Figure 31. Slider

5.8.1. Slider

The slider corresponds to an image list. All entries in this list correspond to a slider item and are displayed one after another in the header of a page.

Editor view
With the slider, the editor is able to create a list of images, which can each be assigned a title as well as a link to a category or product page. The images can be selected from the media store or uploaded with the help of the input component.

A link to a category or product page is specified by entering link text and the associated product or category ID. Both fields are automatically populated when a product or category is transferred from one of the two reports. As the link refers to the entire banner, its link text is only used as a tooltip and is not displayed as a clickable link.

The selected images are displayed as a slider in the header of the corresponding page and can be cropped individually using the corresponding FirstSpirit functionality.

Developer view
The slider is based on the Bootstrap carousel and integrates the list of images selected by the editor. The images are selected via an FS_CATALOG input component, whose individual entries use the template for the slider item. The input component has the upload=yes parameter, which allows the editor to upload new images.

To crop the images, the SLIDE resolution is required, which is already applied in the project properties of the reference project and must be specified in the HTML channel:

Specifying the resolution 
$CMS_RENDER(template:"media_link",mediaref: st_picture,res:"SLIDE")$

The entire slider is assigned to the set_sectionContent variable, which is required during generation of the homepage or a category or product page to populate the corresponding XML file. For a content page, however, the variable is only output.

As the slider uses no content from Commerce Cloud, it does not have to be labeled with HTML tags, and is shown in the preview without substitution.

The banner image corresponds to a static image that is displayed in the header of a page.

Editor view
The static banner image is selected either via the media store or by uploading a new image. With the help of the standard FirstSpirit functionality, it can be cropped to the required image section.

In addition, the section offers editors the following further configuration options:

  • Maintaining a one-line title

  • Specifying a link to a category or product page

  • Defining the size and banner display

Once a title has been entered, it will have a blue background and can be positioned left, right, or center on the banner image. In doing so, it should be specified whether the blue-shaded background is displayed on the left or right, only as a narrow strip, or over the entire height of the banner. In the central position, it generally spans the entire height. The input component for positioning only becomes visible when the title is entered and is otherwise hidden.

A link to a category or product page is specified by entering link text and the associated product or category ID. Both fields are automatically populated when a product or category is transferred from one of the two reports. As the link refers to the entire banner image, its link text is only used as a tooltip and is not displayed as a clickable link.

To define the size of the banner, the options Small and Big are available for editors.
The Small option minimizes the height of the banner and displays it only as a narrow strip. This could lead to a selected image being cropped at the bottom.
The Big option displays the banner without any height restrictions and also allows the editor to define a design.

The options None, Top, and Bottom are available for the design. The None option results in no changes being made to the banner, while for the other two options, a white overlay is added to the upper left or lower right corner.

bannerimage
Figure 32. Banner image with 'Top' design

Developer view
The HTML channel references the selected image and displays it together with the configured title and link, while taking into account the image section and layout defined by the editor. To crop the image, the BANNER resolution is required, which is already applied in the project properties of the reference project and must be specified in the HTML:

Specifying the resolution 
$CMS_RENDER(template:"media_link",mediaref:st_picture,res:"BANNER")$

The st_picture input component has the upload=yes parameter, which allows the editor to upload new images, as well as to select an existing image from the media store.

The entire content is assigned to the set_sectionContent variable, which is required during generation of the homepage or a category or product page to populate the corresponding XML file. For a content page, however, the variable is only output.

As the image is referenced from the media store of the FirstSpirit project and is therefore not affected by substitution of Salesforce content, it does not have to be labeled with HTML tags.

5.9. Grid Container

In contrast to simple content pages, the homepage and category landing pages are able to display a group of three to five images via the grid container, each corresponding to a grid container element.

grid
Figure 33. Grid container

Editor view
With the grid container, the editor is able to create a list of images, which can each be assigned a title as well as a link to a product, category, or content page. Depending on the configuration, three to five images are displayed from this list and can be individually cropped to the required image section. The images can originate from the media store or can be uploaded with the help of the input component.

The images are arranged according to a certain layout that is predetermined by the editor. The following seven options are available here.

If the list created by the editor contains more entries than is envisaged by the layout, then only the first entries are taken into account. Surplus elements are ignored by the layout. The editor receives a notification about this in the form.

If the list created by the editor contains fewer entries than is envisaged by the layout, or if the editor does not select an image for an element, placeholders are displayed instead. In both cases, the page cannot be released until the layout is completed.
grid opt
Figure 34. Grid container - Layout options

Developer view
Within the HTML channel and based on the image section and layout chosen by the editor, the selected images are referenced and their configured titles and links displayed. Only the number of images corresponding to the layout are taken into account, and all other entries ignored.

To crop the images, the GRID_ELEMENT_SQUARE, GRID_ELEMENT_HIGH, and GRID_ELEMENT_WIDE resolutions are required. They are already applied in the project properties of the reference project and must be specified in the HTML:

Specifying the resolution 
$CMS_REF(st_picture, resolution:"GRID_ELEMENT_SQUARE")$
$CMS_REF(st_picture, resolution:"GRID_ELEMENT_HIGH")$
$CMS_REF(st_picture, resolution:"GRID_ELEMENT_WIDE")$

The st_picture input component has the upload=yes parameter, which allows the editor to upload new images, as well as to select an existing image from the media store.

The content is assigned to the set_sectionContent variable, which is required during generation of the homepage or a category landing page to populate the corresponding XML file.

As the images are referenced from the FirstSpirit media store and there is no substitution of Salesforce content, they do not have to be labeled with HTML tags and are displayed in the preview in the usual way.

5.10. Hot spots

In addition to the grid container, products can be displayed in the form of hot spots. Each hot spot corresponds to a product link, which is defined on a single static image parallel to the other hot spots. When you click, a flyout opens for each hot spot, which includes the name, an image, and a description of the corresponding product.

The static image is selected and the hot spots are defined with the help of the Shop the look section template, which can only be added to the homepage and content pages.

hotspot
Figure 35. Hot spots

Editor view
In addition to the static image, the editor can specify a title made up of maximum 20 characters, which can be positioned on the left, on the right or in the center on the image. The image can either be selected from the media store or uploaded via drag-and-drop on the Upload a picture button in the form. It can be cropped with the help of the familiar FirstSpirit functionality.

If the section is used within a blog article, the image to be selected cannot be cropped. This functionality is only available if the section is directly integrated into a page.

The editor can create any number of hot spots on the image by selecting an image section and defining a product link for this. The link expects a link text and a product ID. Both fields are automatically populated when a product is transferred from the product report. After the form has been saved, the created hot spots are displayed in the relevant location on the image and the link text corresponds to the displayed product name.

Developer view
The HTML channel initially references the selected image and displays it together with the title. The hot spots are then determined and positioned using the image sections specified by the editor. For each hot spot, the associated flyout is also created, which appears when the hot spot is clicked and automatically displays the corresponding product information.

The entire content is assigned to the set_sectionContent variable, which is required during generation of the homepage to populate the corresponding XML file. For a content page, however, the variable is only output.

As the image is referenced from the media store of the FirstSpirit project and is therefore not affected by substitution of Salesforce content, the content does not have to be labeled with HTML tags.

As the image map in FirstSpirit does not provide the option to upload and crop an image by default, the two scripts cc_crop and cc_upload have been added to the reference project. They make both functionalities available to the editor.

5.11. Blog

In contrast to the homepage and category and product pages, content pages have the option to display blog articles. Every blog article corresponds to a dataset of the Article data source and must first be generated by the editor.

With the aid of two table templates, they can be presented either in the form of an overview of all available blog articles or as a detail view of one single article. Both options are described in the sub-chapters below.

5.11.1. Article overview

The article overview presents all blog articles included in the project sorted by their creation date. In each case, the display is limited to the heading of an article plus the teaser and teaser image.

article overview
Figure 36. Article overview

The teaser image must be created with the resolution of ARTICLE_TEASER_IMAGE.

Editor view
As the overview is generated automatically, the editor can only define the number of blog articles to be displayed as well as their distribution across one or more pages. It is configured using the familiar FirstSpirit functionality on the Data tab of the relevant page reference.

Apart from this, the editor has no access to the function other than to integrate the table template.

Developer view
The HTML channel of the table template determines the datasets of the Article data source and in each case outputs the heading, the teaser, and the teaser image of all blog articles one after the other. The individual articles are separated by a horizontal line and their headings match the link to the relevant detail page.

To link the detail page, its reference name must be known to the overview page. In the reference project, the reference name of the relevant page reference (magazine_article) was therefore permanently included to the template for the overview page. In individual scenarios, this is therefore to be adapted accordingly.

In addition, a navigation function is inserted in the first position before the list of blog articles. This enables users to browse through the blog articles if they are distributed across several pages. If all blog articles are presented on a single page, the navigation function is hidden.

5.11.2. Articles

Every blog article corresponds to a dataset of the Article data source and makes various input options available to the editor.

Editor view
To create a blog article, the editor must first enter a heading and teaser text as well as select a teaser image. A creation date and an author must also be specified. The editor also has the option of specifying a banner or slider for the article. These paragraphs are created as described in chapter Banner.

To record the editorial content, the following sections are also available to the editor. The Article Tiles section can only be used within blog articles. It is not included in the section selection for the page templates.

  • Shop the look
    The section enables products to be presented as what are known as hot spots. It corresponds to the section of the same name, which can be added to the homepage and content pages and which has already been described in the previous chapter.

    If the section is used within a blog article, the image to be selected cannot be cropped. This functionality is only available if the section is directly integrated into a page.

  • Article Tiles
    This section can be used to present three blog articles side by side in a column view. In each case, the view comprises the heading, the teaser image, and the teaser text plus the author and the creation date of the article. Clicking the heading calls up the detail page of the corresponding blog article.

    A heading can be specified for the section and displayed left-aligned, right-aligned, or centered above the blog articles.

    article tiles
    Figure 37. Article Tiles

    To link the detail page, the reference name of the relevant page reference (magazine_article) was permanently included to the template for the section. In individual scenarios, this must be adapted accordingly.

  • Product Tiles
    This section is available for blog articles and product detail pages. It is described in the chapter of the same name. In the same way as Article Tiles, this section presents three products side by side in a column view.

    product tiles
    Figure 38. Product Tiles

  • Text Picture
    The section provides five ways of adding text and/or images. It corresponds to the section of the same name, which can be added to login pages and blog articles and is described in the corresponding chapter.

Developer view
The HTML channel first outputs the heading of the blog article along with the name of the author and the creation date. It then determines the sections generated by the editor and displays these one after the other.

As there is no substitution of Salesforce content, the blog content does not have to be labeled with HTML tags.

5.12. Text Picture

As its name suggests, this section is used to add text and/or images. It is only permitted in blog articles and login pages.

Editor view
This section provides editors with five different options for entering content. These options are selected from within a form:

Option 1 - only text

With the first option, only text can be added.

Option 2 - 1 picture

The second option enables a single image to be added.

Option 3 - 2 pictures side by side

In addition to the second option, the editor can use the third option to add two images, which are displayed side by side.

Option 4 - picture left, text right

This option enables the image and text to be displayed simultaneously. The image is displayed on the left of the text.

Option 5 - text left, picture right

The fourth and fifth option are equivalent to one another. In this case, however, the image is displayed on the right of the text.

Developer view
The content selected by the editor is displayed and positioned accordingly within the HTML channel based on the option selected by the editor. As the content does not come from Commerce Cloud, it does not have to be labeled with HTML tags. It is shown in the preview without substitution.

5.13. Product Tiles

Like article tiles, which can only be used in blog articles, this section presents three products side by side in a column view. It is only permitted in a blog article or on a product detail page and shows the name, image, and a description for each product. Clicking the product name opens the corresponding product detail page.

product tiles
Figure 39. Product Tiles

Editor view
In addition to the three products to be selected, the editor can specify an optional title made up of a maximum of 50 characters to be positioned on the left, on the right, or in the center above the product tiles. The products can be referenced in the form using drag-and-drop (the product name is added as link text). Unlike the product information, the product name can be edited.

If the selection created by the editor contains fewer than three products, the page cannot be released. It is not possible to select more than three products.

Developer view
The products selected by the editor are referenced and the title is positioned within the HTML channel. For each product, its name, a product image, and a description are determined and displayed. As the information is taken from Salesforce without substitutions, HTML tags are not required.

5.14. Video

A page in the reference project can also contain videos alongside purely textual information. Each video corresponds to a section, which provides different configuration options. The associated section template can only be added to content pages and category landing pages, not the homepage.

Editor view
To reference videos, editors can make use of the YouTube and Vimeo platforms. Both providers use a unique ID, which in each case forms part of the video URL:

  • Youtube: https://www.youtube.com/watch?v=<VIDEO ID>

  • Vimeo: https://vimeo.com/<VIDEO ID>

The corresponding video for the page can be added using this ID. The video is displayed in the standard format of 16:9. For YouTube videos, however, the options 21:9, 4:3, or 1:1 are also available. Furthermore, the editor can define whether playback is started automatically and whether the video may be displayed in full screen mode.

Developer view
Within the HTML channel, the selected video is first referenced in direct relation to the defined video platform. For this, the display format as well as the different URL parameters are set and, in a final step, the correct video URL generated in accordance with the editor’s configured settings in the form.

This content is assigned to the set_sectionContent variable, which is required during generation of a category landing page to populate the corresponding XML file. For a content page, however, the variable is only output.

As the embedded video does not come from Commerce Cloud, it does not have to be labeled with HTML tags. It is shown in the preview without substitution.

5.15. Social Media

Editors can use content from Facebook, Twitter, and Instagram in the reference project and embed it in a content page. There is also the option to place buttons on a page so that visitors can use them to share the website link via various platforms.

5.15.1. Embedding content

Content from social networking sites can be embedded in a website.

Editor view
The Social Media Embedding section template is used for embedding content from social networking sites. It requires one of the available platforms - Facebook, Twitter, or Instagram - to be selected within the section form.

If Facebook is being used as a platform, the type of post to be embedded must also be defined. Posts, comments, and videos are available for selection. In all cases, the URL of the post must then be entered in the corresponding form field. There may also be additional options available for changing the way in which a post is displayed, depending on the type of post.

Twitter also provides a whole host of different options for editors: It is possible to choose the List, Profile, or Collection Timelines option in the form in order to embed it in the page. To do this, the editor must enter the name of the Twitter account associated with the timeline in the Screen Name form field. List and Collection Timelines also require the timeline to be identified in the ID field.

Embedding an Instagram post simply requires the URL of the post to be entered in the form.

A slot configuration must also be specified for all page templates, with the exception of the content page.

Developer view
The section template uses various mechanisms to embed the post in the page, depending on the selected platform. The resulting HTML markup saves them in the set_sectionContent variable, which simply outputs them if a FirstSpirit preview is generated. When a content page is being generated, the value of the variable must also be output so that the value can be included in the content asset of the content page. A new asset is created on other pages instead, and the value of set_sectionContent is stored in this asset.

5.15.2. Sharing the page

It is possible to give visitors to the website the option of sharing the page via various social networking sites. A button for each supported platform can be placed on the page.

Editor view
The Social Media Share section template is provided for using this function. In this template, editors first select one or more social networking sites, for which they would like to add buttons in their page. The size and position of the buttons only need to be defined once for all the selected platforms. The supported platforms are Facebook and Twitter.

In the case of Facebook, there is the option to add individual text to the button; this text is maintained in the section form. In the case of Twitter, editors have the option of storing the tweet text and hashtags.

A slot configuration must also be specified for all page templates, with the exception of the content page.

Developer view
Depending on the selected networks, this template also generates different HTML content for the implementation of buttons. Unlike content pages, which simply output the markup, the other pages save the markup in a content asset. In the case of a preview, the markup is simply displayed.

5.16. Changing the language

The reference project supplied uses English as the master language. It also has Italian, French, Japanese, and Chinese as project languages. To switch the view of a page to one of these languages, the project provides the option of changing languages in the preview. This is displayed either as a dropdown menu or within a menu as a list item, depending on the screen size used.

langs
Figure 40. Changing the language

Editor view
Within the preview of the reference project, the change of language is displayed on the homepage, on content pages, and on category and product pages. This enables the editor to maintain editorial content on each page for all the languages contained within the project.

As the selection of existing languages is determined automatically based on the project languages and the display also cannot be influenced, the editor has no access to the function other than to simply use it.

Developer view
The change of language option is generated through the Language Dropdown format template and made available for use in the preview with the Preview Generation format template. This is displayed either as a dropdown menu or within a menu as a list item, depending on the screen size used (see figure Changing the language).

Both variants reference the Language Dropdown format template, which controls the display of variants via the showInMenu parameter to be transferred. As the change of language replaces all of the corresponding Salesforce content, both variants must be labeled with unique HTML comments.

Changing the language in the Preview Generation format template 
$-- Preview Language Switch --$
<!-- CMS-LANGUAGE-DROPDOWN-START -->
   $CMS_RENDER(template:"sfcc_language_dropdown", mobile:false)$
<!-- CMS-LANGUAGE-DROPDOWN-END -->

<!-- CMS-LANGUAGE-DROPDOWN-MOBILE-START -->
   $CMS_RENDER(template:"sfcc_language_dropdown", mobile:true)$
<!-- CMS-LANGUAGE-DROPDOWN-MOBILE-END -->

The Language Dropdown format template first determines the language currently displayed in the preview and shows this along with the corresponding icon as the first entry in the dropdown or language menu. The list of all languages contained within the project is then queried and made available as further selection options with the exception of the previously defined language.

The editorial content maintained on the FirstSpirit side contains links that can be used to link content. In addition, links can be used to provide documents for download or for contact details.

These are based on different link templates, which are described in detail in the following sub-chapters.

All link templates - with the exception of the article link - have the hidden Add link tags toggle component. It ensures that the corresponding link has <a> tags when the associated link template is used within a CMS_INPUT_DOM. If it is used in the context of a CMS_INPUT_LINK, the link does not get any <a> tags. The toggle is activated via a rule.

Add link tags 
$CMS_IF(lt_linkTags)$
   <a href="$CMS_VALUE(lt_url)$"
    $CMS_IF(!lt_linktext.isEmpty)$ title="$CMS_VALUE(lt_linktext)$"$CMS_END_IF$
    target="_blank">
      $CMS_VALUE(lt_linktext, default: "Link")$
   </a>
$CMS_ELSE$
   href="$CMS_VALUE(lt_url)$"
   $CMS_IF(!lt_linktext.isEmpty)$ title="$CMS_VALUE(lt_linktext)$"$CMS_END_IF$
   target="_blank"
$CMS_END_IF$

The category link and product link make it possible to link to category and product pages. They are almost equivalent to one another and are therefore described jointly in this chapter.

Editor view
A link to a category or product page is specified by entering link text and the associated product or category ID. Both fields are automatically populated when a product or category is transferred from one of the two reports. While the ID cannot be changed, the link text can be changed at will by the editor. If the editor deletes the link text or if the form field remains empty for other reasons, the term Product or Category is used instead.

In addition, category links allow the selection of a Sorting Rule. Sorting Rules are used to sort the products displayed on a category page according to predefined criteria. If the editor does not make a selection, the sorting of the products on the displayed category page is based on the Sorting Rule Best Matches by default.

Developer view
Within the HTML channel of both templates, a differentiation is made between the preview and the generated state for the generation of links. In the case of the generated state, an instruction is created, which triggers the determination of the correct URL on the Salesforce side. For a preview, the dispatcher included in the Site Store performs this task. To start with, it checks whether a FirstSpirit page reference exists for the transferred product or category ID. If no such page reference exists, it determines the associated page from the storefront instead and displays this in the preview. Furthermore, the URL of a category link is extended by a corresponding URL parameter if a Sorting Rule is selected for it. If the editor has not made a selection, a category page displays the Best Matches by default.

At the current time, the dispatcher is not yet able to correctly assign references to variations of products to a FirstSpirit page reference. Therefore, the corresponding page from Storefront is always displayed whenever references to variations of products appear.

The use of Sorting Rules is only possible in the live state. There is no sorting of any kind within the preview. It always displays only the Best Matches - regardless of a selected Sorting Rule.

5.17.2. FS content link

The FS content link is used to link page references within FirstSpirit.

Editor view
To create a content link, the editor selects a page reference from the Site Store and specifies any link text. Unlike the link text, selecting the page reference is a mandatory field. If the field for the link text remains empty, the term Link is used instead.

If a link to a page that exists exclusively in the storefront is required, the external link must be used instead of the content link.

Developer view
As an FS content link is an internal link within the project, the page reference selected by the editor for the preview can be directly referenced. Contrary to this, for the generated state, an instruction is created, which triggers the determination of the correct URL on the Salesforce side. For this, the asset ID, which is calculated beforehand within the link template, is transferred as a URL parameter.

5.17.3. Article link

The article link enables individual blog articles within a continuous text to be linked. For this reason, it can only be used within the text or Text Picture section.

Editor view
The article link is equivalent to the FS content link. The difference is the link target, which, in the case of the article link, corresponds to a blog article. It therefore expects a dataset from the Article data source to be referenced in addition to the link text. While the selection of the blog article is a mandatory field, the link text is optional. If the field remains empty, the heading of the blog article is used initially. If this has also not been specified, the term Article Link is used instead.

Developer view
As with the content link, the article link is an internal link within the project. For this reason, the selected blog article can be referenced directly in the preview based on its FS ID. For the generated state, an instruction is created instead, which triggers the determination of the correct URL on the Salesforce side. The asset ID is also transferred to it as a URL parameter.

To link the blog article, the reference name of the relevant page reference (magazine_article) was permanently added to the link template. In individual scenarios, this must be adapted accordingly.

The external link is used to link external websites.

Editor view
The external link functions similarly to the content link. Unlike this, however, it links to external content and therefore expects a URL in addition to the link text, rather than a page reference. While the URL is a mandatory field, the link text is optional. If the field for it remains empty, the term Link is used instead.

By entering the corresponding storefront URL, the external link can also be used for links to content in Commerce Cloud.

Developer view
Within the HTML channel, only the external link defined by the editor is created. As with the content link, it is not necessary to use the dispatcher.

The download link is used to provide documents on the website. They can be downloaded by website visitors and provide them with additional information.

Editor view
To provide a document on the website for downloading, the editor must select this from the media store and enter any link text. While selecting a document is mandatory, the field for the link text can remain empty. In this case, the term Download is used.

Developer view
Using the information entered by the editor, the download link is created in the HTML channel. For the generated state, the $staticlink parameter is added to it, which triggers the determination of the correct URL on the Salesforce side. In addition, the presentation channel does not contain any additional content.

More information about linking static content in Salesforce can be found under Merchandising Your Site ➔ Content Assets ➔ Content Assets for Developers ➔ Using Content Link Functions ➔ Linking to Another Site URL.

The e-mail link gives the option of getting in touch via e-mail.

Editor view
The form for the e-mail link consists of just two text fields. In these, the editor enters any link text as well as an e-mail address, the validity of which is checked using a regular expression in the Rules tab. Unlike the e-mail address, specifying link text is optional. If the field for it remains empty, the term E-Mail is used instead.

Developer view
The information entered by the editor is used to create and output a mailto link in the HTML channel. In addition, the presentation channel does not contain any additional content.

5.18. Slot configurations

Within the supplied reference project ContentConnect Reference Project, assets are represented by sections. Depending on the use case, they each have a slot configuration, which makes it possible to deliver editorial content in a way that is specific to the target group and tailored to the customer.

Editor view
The option to configure a slot is provided to an editor in the reference project in the form of an input component. It is included in the sections available to the editor and may include an unlimited number of slot configurations. A slot configuration is also defined as a default value for the input component in all available sections.

The preconfigured slot configuration is activated and selected as the default configuration for the associated slot. To change this, these properties must be modified manually.

Unlike the homepage, the login page, and the category pages, the content page, the category detail page, and the product detail pages only creates a single asset and summarizes all sections added to the page in this. For this reason, it is not possible to define a slot configuration for each section in these cases. The corresponding input component is therefore hidden for all sections of a content page, a category detail page, or a product detail page.

The slot configuration can be (de)activated by the editor and selected as the default configuration for the associated slot. In addition, it makes it possible to define the schedule parameters known from Salesforce. By adding several sections of the same type (e.g. several sliders) but that have different slot configurations, it is possible to implement different types of content.

One of the schedule parameters to be defined is the Schedule Type, for which the Default value, among others, can be selected. In this case, a Rank must also be entered, as otherwise errors will occur on the Salesforce side. Without this information, it is not possible to release the associated page.

Developer view
An individual slot configuration is represented by the SFCC Slot Configuration link template, which is used within the following sections of the Slot Configuration input component:

  • Banner Image

  • Slider

  • Grid container

  • Shop the look

  • Text

  • Video

  • Product Tiles

  • Social Media Share

  • Social Media Embedding

Within the HTML channel of the link template, the XML expected by Commerce Cloud is created in line with the configuration defined by the editor and written in the collector provided. The XML is transferred to Commerce Cloud using a deployment.

5.18.1. Variants

Slot configurations enable the realisation of different content variants and thus the delivery of target group-specific and customer-specific editorial content. In order to generate these content variants:

  1. either multiple slot configurations for a section

  2. or several sections of the same type (e.g. several sliders) with different slot configurations in a content area

must be created.

Since in the second case all variants would be displayed in the preview by default, the reference project has a variant selection for the homepage, the login page and for category landing pages (see figure Variant selection). As soon as a content area contains more than one section, the variant selection is visible and only the section selected in it is displayed in the preview.

If a section has multiple slot configurations, the variant selection only considers the first one.
variants
Figure 41. Variant selection

Each entry of the variant selection shows the title of the corresponding slot configuration and the parameters defined for it, whereby the default option is visualized in the form of a house icon and the rank as a double arrow. If the title of a slot configuration is missing, the variant selection represents the section type instead. In addition, deactivated slot configurations receive a gray background and a corresponding label.

In addition to the single entries, the variant selection has the Create a new variant button, which is used to create new sections in the corresponding content area. It has the same function as the Easy Edit button on existing sections.

The variant selection is integrated via so-called wrappers, which are integrated into the page or section templates in the form of the MPP Body Wrapper and MPP Section Wrapper format templates. Calling the MPP Section Wrapper replaces the output of the variable set_sectionContent in sections, to which all editorial contents of a section are assigned in the reference project. Equivalent to this, the MPP Body Wrapper in page templates replaces the output of the respective content area, which must be passed to the wrapper instead.

MPP Body Wrapper call for the main area of the homepage 
<!-- CMS-HOME-MAIN-START -->
   $CMS_RENDER(template:"mpp_body_wrapper",body:"home_main_m")$
   $CMS_RENDER(template:"empty_content_slot",label:"Home Main",body:"home_main_m")$
<!-- CMS-HOME-MAIN-END -->

5.19. Release, deleting, and deployment

Content is released, deleted, and deployed within the supplied reference project ContentConnect Reference Project via workflows. For this reason, it contains a publish workflow, as well as the BasicWorkflows.

Editor view
The BasicWorkflows provide an editor with the option to release modified content and to remove FirstSpirit elements both from the Current State and the Release State. Both workflows are based on the four-eyes principle and are always executed in the context of a page. If a conflict arises while a workflow is running, the workflow can be continued once the conflict has been rectified.

The publish workflow is available to editors to synchronize changes made in the FirstSpirit project on the Salesforce side. It initiates the deployment schedule and is therefore executed without any context. For this reason, it is started in ContentCreator via the Actions menu and in SiteArchitect via the Task list. The deployment schedule transfers all released content to Commerce Cloud and triggers the deletion of assets and slot configurations, which have been removed in FirstSpirit, on the Salesforce side.

publish wf
Figure 42. Publish workflow in ContentCreator

Developer view
The release workflow and the delete workflow correspond to those of the BasicWorkflows module and have not been changed. The release workflow is oriented towards the administrative direct release and provides its functionality for the editor. The delete workflow makes it possible to remove elements from the Current State and the Release State.

To transfer the changes made in the FirstSpirit project, the publish workflow has also been added to the reference project. Using the SFCC Release Deployment script, this determines the deployment schedule and executes it. Unlike the other two workflows, it does not refer explicitly to one single page. For this reason, the option Workflow executable without context is activated in its Properties.

wf options
Figure 43. Publish workflow options

To also remove the assets and slot configurations deleted in the FirstSpirit project on the Salesforce side, the publish workflow must be executed.

ContentConnect is a product of Crownpeak Technology GmbH, Dortmund, Germany.
Only a license agreed upon with Crownpeak Technology GmbH is valid with respect to the user for using the module.

Details regarding any third-party software products in use but not created by Crownpeak Technology GmbH, as well as the third-party licenses and, if applicable, update information can be found in the file THIRD-PARTY.txt included with the module.

7. Help

The Technical Support of the Crownpeak Technology GmbH provides expert technical support covering any topic related to the FirstSpirit™ product. You can get and find more help concerning relevant topics in our community.

8. Disclaimer

This document is provided for information purposes only. Crownpeak Technology GmbH may change the contents hereof without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. Crownpeak Technology GmbH specifically disclaims any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. The technologies, functionality, services, and processes described herein are subject to change without notice.